codex-proxy-rs/CONTRIBUTING.md

贡献与审查

贡献应解决明确的问题，并保持或改善项目的可维护性。提交者、自动检查和审查者使用同一套标准，让重复问题在提交和初审阶段得到处理。

本文定义协作流程与审查标准；模块职责以 系统架构 为准，视觉规则以 管理端主题 为准。没有明确约定时遵循相邻实现；具体页面的布局决定不自动成为全项目限制。

提交 Issue

问题反馈使用仓库的 Issue 表单，填写问题类型、描述、版本与环境、复现步骤和预期结果。接口问题补充平台与认证类型、模型、客户端，以及脱敏后的请求、响应和请求 ID；页面问题附相关截图或录屏。

日志和配置只提供定位所需片段，不上传真实凭据或完整请求转储。功能建议与协作规则调整可直接提交 Issue，说明场景、原因和建议方案。

问题与方案依据

开发、创建 PR 和审查都先核实待解决的问题、触发条件与预期行为，再确定或评估实现。区分问题发生版本、目标分支现状和本次变更后的行为，不把需求描述、PR 描述或第三方项目的做法直接当成事实。目标分支已修复的问题，应说明当前仍需补齐的差异，不能据此否定旧版本中的问题。

涉及上游协议、客户端行为或兼容性时，以对应版本的官方源码为首要资料。优先读取用户提供或本机已有的官方源码，核对仓库来源、版本或提交；本地资料不足时查官方仓库的对应版本源码，再结合官方测试、文档、发布说明和运行证据。第三方资料只作线索或补充。引用具体文件、符号或行号，对外引用优先使用固定提交的源码链接；源码不可得或版本不匹配时说明证据缺口，不把最新实现当成当前部署行为。无上游依赖的内部变更，以本项目代码、合同和运行证据为依据。

官方已有同一场景的处理方式时，优先沿用其协议语义、职责归属和解决路径，检查是否只需复用已有能力或正确传递官方合同。新增覆盖配置、补偿逻辑或采用第三方兼容方案，应说明官方路径为何不足；偏离官方方案需有本项目的实际约束和验证依据，不机械照搬源码，也不默认接受已有提案。

反馈 Issue 时区分观察到的症状、根因假设和方案建议，关联已有 Issue、PR 及包含修复的发布版本。能说明问题的反馈可以先提交，不要求报告者先找到官方源码或证明根因；引用官方行为或提出实现方案时，按上述原则注明依据与缺口。

PR 流程

1. 准备变更。 按上述依据核实问题与方案，找到所属模块、相关调用链和最接近的现有实现，在功能分支完成修改与自查。涉及架构、公开合同或较大交互变化时，先说明方案与取舍。
2. 发起 PR。 目标分支使用 main。说明问题成立的依据、触发场景、改动后的行为和实际验证结果；涉及官方行为时注明源码位置、版本和方案关系。界面改动提供截图、录屏或可复现的预览方式。一个 PR 围绕一个明确目标，必要重构说明关联原因。
3. 自动检查与初审。 CI 执行适用的格式、静态分析、测试和构建检查；启用 AI 审查后，由它按本规范辅助检查语义、复用和一致性。提交者先处理明确问题，维护者重点审阅方案、风险与用户体验。
4. 修改与合并。 更新代码后重新执行受影响的检查，确认审查意见已处理，验证证据对应当前变更。维护者审阅批准后再合并；需要升级说明的变更同步相关文档。

AI 开发和审查入口是根目录的 AGENTS.md。在仓库上下文中要求“审查 PR #编号”时，应按下列标准执行，无需再次列举要求。

项目技能

仓库技能位于 .agents/skills/，随代码共享。技能提供执行流程，协作与审查标准仍以本文和 AGENTS.md 为准。

技能	用途	调用示例
dev-guide	项目开发与文档导航	$dev-guide 修复当前问题
github-pr	创建或审查 PR	$github-pr 创建当前分支的 PR / $github-pr 审查 PR #编号
github-issue	整理或提交 Issue	$github-issue 提交当前问题
release	准备发布说明或正式发版	$release 整理本次发布说明 / $release 发布 vX.Y.Z

审查请求默认在当前会话报告；明确要求创建 PR、提交 Issue 或正式发版时才执行对应远程操作。技能安装不等于启用 GitHub 自动审查。

规则文件保护

PR 不接受根目录或子目录中 AGENTS.md 的新增、修改、删除或重命名。调整这些文件时先提交 Issue 说明原因和建议，由维护者处理；规则保护工作流 会提示并关闭包含此类变更的 PR。撤销相关变更后可以重新打开 PR，继续正常检查。

源码变更遵守现有架构边界与迁移冻结规则，由对应 CI 检查执行；不额外设立整块业务目录的 PR 禁改清单。构建、测试和安全扫描复用现有工作流。

审查标准

按改动涉及的范围选择检查深度，无需为每个 PR 填写所有维度的报告。

结论先回答原问题是否成立（成立、部分成立、不成立或证据不足），说明触发条件和依据；再判断解决方向是否合理，交代适用的官方方案、本次实现与它的关系及必要调整，最后报告实现问题与验证缺口。原问题是否成立与 PR 实现是否正确分别判断。源码推断、实际复现和检查结果分别说明，CI 通过不能代替问题与方案的论证。

维度	检查重点
设计与架构	职责归属、依赖方向、公开接口是否合理；是否融入已有体系，有无绕过边界的旁路
正确性与兼容性	正常、异常和边界输入；并发、取消、重试与副作用；是否改变既有 API、协议或数据合同
安全与数据	权限、输入校验、敏感信息、状态隔离和持久化一致性；日志与诊断是否符合脱敏边界
简洁性与复用	重复业务规则、冗余状态、无效代码和过早抽象；能否用更直接的实现解决当前问题
性能与资源	实际数据规模下的查询、请求、内存与连接成本；资源释放、背压和异常时的生命周期
可读性与风格	命名是否准确，控制流是否易懂，格式是否一致；注释解释约束与原因而非复述代码
测试与验证	是否覆盖真实触发条件和结果，能否发现回归；证据是否对应本次变更，有无跳过或缺失项
界面与交互	共用组件和主题、信息层级、状态反馈、响应式、键盘操作及可访问性；是否有实际页面证据
文档与升级	行为、配置、API 和部署说明是否同步；数据迁移和兼容影响是否交代清楚

审查意见区分三类：

• 必须修复： 有具体触发条件的缺陷、违反现有合同或明确项目规范的问题。说明位置、依据、影响和最小修复方向。
• 建议： 不影响合同或规范的替代实现、命名偏好和局部优化。个人偏好不能单独阻止合并，也不应强求与本次目标无关的重构。
• 验证缺口： 尚未检查的行为、状态或运行环境。说明缺少什么证据，由维护者评估是否需要补齐，不能把未验证当作已通过或已发现缺陷。

复杂度不按行数判断，复用不只看语法相似。建议合并重复逻辑时应指出共享的业务含义；建议保留特殊分支时应能说明它服务的场景。例外应有依据，不能仅为绕过检查而放宽规则。

项目约定

• AI 进行 Rust 开发时，加载并使用 $rust-best-practices 技能。模块、可见性、依赖方向和测试目录按架构文档执行，使用现有 Rustfmt 与 Clippy 配置。
• Vue 使用 TypeScript、<script setup> 和现有 ESLint 配置；API 请求通过已有模块及 request 封装，沿用逐行请求配置格式。
• 业务数据的解析、校验和展示优先复用已有逻辑。新增抽象放在拥有该职责的模块，避免重复事实源或无实际需求的通用层。
• 新增代码注释使用中文。提交信息使用英文 Conventional Commits，参考近期历史，按完整功能归并；确由 Codex 参与的提交保留 Co-authored-by: Codex <noreply@openai.com>。
• 发布说明写入 release/notes.md，标题首行为目标版本的 # vX.Y.Z，章节标题和正文使用中文；命令、配置键、协议名等保留原文。只说明本次版本的实际变化，按影响交代升级事项。
• PR 聚焦目标；无关格式化、重构和依赖升级单独处理。

文档职责与更新条件

常规文档说明当前有效的用法、接口合同、模块职责和维护约束，不承担变更历史。 只有改动使对应说明失真、缺少必要信息，或改变读者需要执行的操作与判断时，才更新文档。 内部修复、重构和界面微调不默认附带文档改动；审查时不能仅因 PR 没改文档就判定存在缺口。

• 按 开发指南的文档入口 找到内容所属文档，在原有章节就地修订， 不按每次变更追加说明。同一事实只保留一处完整说明，其他文档按读者任务提供必要摘要和链接。
• API 文档保留调用所需的字段、状态、语义和限制；架构文档保留职责与不变量；部署文档保留配置、操作和排障。 不把界面布局、内部锁或索引实现写进接口说明，也不把前端库的实现选择写进部署说明。
• 改动原因、前后对比、排查经过和本次验证结果放在 PR / Issue 或任务报告。版本变更与升级影响按维护者的发版安排维护 release/notes.md，不为普通开发任务或 PR 自动追加发布说明。
• 仍影响实际升级、恢复或兼容使用的限制与操作应保留，并注明适用条件；不能仅因涉及旧版就删除。 审查文档改动时核对必要性、所属职责与重复内容，区分当前使用说明和仅解释此次修复的内容。

界面验证

AI 进行前端开发时，加载并使用 $frontend-design 技能。设计方案以本项目的用户任务、管理端主题 和已有组件为依据，在任务范围内改进布局、视觉与交互。

开发前查找同类页面及 components/base 中的基础组件，优先使用已有主题 Token、交互和数据展示逻辑。需要扩展时在对应职责层修改；局部样式的适用范围遵循主题文档，不一律禁止，也不靠页面覆盖掩盖共用组件的问题。

列表列宽、序号、按钮、分页和弹窗尺寸由实际任务与数据规模决定，以同类页面为参照。新增或调整交互时说明用户需要完成什么操作，不把某个页面的取舍推广成全局禁令。

提交者在浏览器中验证受影响路径，提供前后截图、录屏或预览步骤，并标明实际覆盖的状态。按变更选择浅色/深色、窄窗口、空/加载/错误状态、大量数据及键盘操作；共用主题或基础组件变更按主题文档扩大验证范围。模拟数据与预览材料不包含真实凭据。

涉及浏览器能力或访问环境差异时，按项目支持的部署方式核对相关 HTTP/HTTPS、localhost/实际部署地址与浏览器版本，记录实际覆盖的条件；本地预览正常不能替代部署环境中的交互验收。

验证

选择与变更相关的检查，纯文档修改无需重建前后端。行为修复补充能覆盖触发条件和结果的测试，不增加仅复述实现的断言。

范围	现有检查	仍需提供的证据
Rust	Rustfmt、严格 Clippy、后端测试、架构边界检查	相关失败场景和集成行为
前端	ESLint、类型检查与构建	页面一致性、交互和实际数据状态
数据库迁移	冻结清单校验与 PR 基线比对	升级行为及兼容说明
依赖安全	Cargo Audit、pnpm Audit	本次变更的权限、数据与信任边界
工作流与容器	Actionlint、相关容器检查	改动涉及的运行行为

前端从仓库根目录执行：

pnpm --dir frontend format:check
pnpm --dir frontend build
git diff --check

build 已包含类型检查；不维护独立前端测试代码。后端的工具链、命令与线程栈设置统一见 修改与验收。

依赖 PostgreSQL / Redis 的测试使用 专用测试环境，未配置导致跳过时明确记录。CI 中已有对应服务和检查，见 质量工作流 与 安全扫描。

集成变更应验证实际业务路径及结果，不能只凭健康检查或探测成功认定全链路正常。协议和网络改动按需核对认证、证书、代理、流式交付及客户端结果；记录影响复现的环境条件。缺少运行条件时说明缺口，不用模拟结果代替真实集成结论。

自动检查与合并条件

CI 已按变更范围调用现有质量检查。新增自动规则优先使用现有工具，要求依据明确、结果稳定、误报可控；无法可靠判定的设计与视觉问题保留审查判断，避免把具体源码写法锁成测试。

AI 自动审查需要在所用工具中单独启用。其支持的检查范围和优先级过滤以工具说明为准；即使能读取 AGENTS.md，也不能保证所有可维护性和视觉问题都会被报告。配置参考 Codex GitHub 审查文档。

要由 GitHub 强制执行合并条件，维护者需配置对应分支的必需状态检查、审阅批准和讨论解决要求，并按需要设置新提交后的重新审阅。配置前核对实际检查名称与触发范围，见 GitHub 分支保护。规则文档本身不会启用 AI 服务或更改分支设置。