codex-proxy-rs/CONTRIBUTING.md

贡献与审查

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

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

交流与反馈

讨论区 用于使用问答、想法讨论、实验反馈和经验分享。 提问时按需补充版本、部署方式、已尝试的方法及脱敏信息；问题解决后，请在「使用问答」中标记有帮助的答案

明确的 Bug、具体功能需求或协作规则建议使用 Issue，无需先开讨论。 讨论形成可执行事项后，可以新建 Issue 并互相附链接；已有 Issue 的后续信息继续补充在原帖，避免重复记录。 围绕问题友善交流，欢迎不同使用场景和方案观点

提交 Issue

按场景选择 接口问题反馈、常规问题反馈 或 功能建议 表单，按对应提示提供信息。故障反馈填写实际运行版本和中转链路；接口问题区分客户端显示与网关实际响应，页面问题附相关截图或录屏

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

问题与方案依据

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

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

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

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

PR 流程

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

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

项目技能

仓库技能位于 .agents/skills/，随代码共享。技能提供执行流程，协作与审查标准仍以本文和 AGENTS.md 为准。 AI 开发、排查、代码审查和文档修改必须执行 cpr-dev-guide；准备、创建、更新及审查 PR 必须执行 cpr-github-pr，不以用户是否显式点名技能为条件。PR 内修复仍须经过开发流程，不能用填写 PR 正文代替实现自审与验证

技能	用途	调用示例
cpr-dev-guide	项目开发与文档导航	$cpr-dev-guide 修复当前问题
cpr-plugin-dev	网关插件开发、打包与验证	$cpr-plugin-dev 开发一个添加响应头的插件
cpr-github-pr	准备、创建、更新或审查 PR	$cpr-github-pr 创建当前分支的 PR / $cpr-github-pr 审查 PR #编号
cpr-github-issue	整理或提交 Issue	$cpr-github-issue 提交当前问题
cpr-release	准备发布说明或正式发版	$cpr-release 整理本次发布说明 / $cpr-release 发布 vX.Y.Z

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

AI 使用披露

PR 正文说明提交者是否使用 AI。使用 AI 参与方案、代码、文档、测试或自审时，写明工具名称和实际模型型号；使用多个模型时分别列出，可简述各自参与范围。 Codex、ChatGPT、Claude Code 等工具或产品名称不能代替模型型号，优先填写工具显示或调用配置中的具体模型标识。 无法获知型号时如实标记「型号未提供，待补充」，不能猜测或伪造，也不能把待补信息称为已完成披露；补齐前保留 Draft。 更新 PR 时同步新增的模型信息；这一披露不替代提交者自审、验证责任或已有提交署名约定

规则文件保护

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 聚焦目标；无关格式化、重构和依赖升级单独处理

文档职责与更新条件

文档只描述当前有效状态，不记录变更历史，在所属章节就地修订，不追加“本次新增”“此前行为”或修复经过

只有用法、合同、职责、约束或读者需要执行的操作发生变化时才更新，内部重构和界面微调不默认附带文档改动

内容归属

文档	回答的问题	详略边界
README	项目能做什么，如何开始	简短介绍、最短可用路径和文档导航
部署与运维	如何安装、接入、排障和恢复	前置条件、配置、操作步骤、结果判断与风险
开发与源码联调	如何准备环境、运行源码和联调独立仓库	可执行命令、目录关系和依赖维护
API 参考	调用者如何正确请求和解释结果	鉴权、字段、默认值、错误、限制与幂等语义，不展开内部实现或界面布局
系统架构	业务事实归谁，调用如何协作	模块边界、状态所有权、生命周期和不变量，不重复字段清单
管理端主题	界面如何保持一致，主题如何扩展	文案与视觉约束、Token 合同、实现入口和验收范围
插件使用	如何安装、授权、配置和使用插件	管理员操作与影响，不展开 SDK 调用或宿主事务实现
插件 SDK / CLI	如何编写和打包插件	作者合同、权限边界、示例与打包验证
数据库迁移	如何维护 schema 和准备测试库	冻结规则、升级约束和测试环境，不罗列迁移历史
本文	如何协作、审查和交付	流程、判断标准与验证要求，任务入口由 开发技能 串联

• 同一事实只在所属文档完整说明，其他位置按读者任务保留必要摘要和链接
• 改动原因、前后对比、排查经过和验证结果放在 PR、Issue 或任务报告；release/notes.md 是发版时使用的发布说明，不作为常规文档的历史章节，也不随普通开发任务自动追加
• 仍影响升级、恢复或兼容使用的内容，写成明确的适用条件与操作，保留必要限制，不叙述演变过程

层次与行文

• 按读者任务组织章节，先给入口和操作，再解释限制；长篇参考文档提供导航，独立主题使用小标题
• 快速开始只保留走通流程的必要步骤；API、配置、恢复和权限等容易误用的内容写清输入、默认值、边界与失败处理
• 短说明直接成段，并列信息用列表，可比较的字段或职责用表格，避免一段堆叠多个主题
• 标题、表格单元格、短列表项和独立短段通常不加句号；长段优先拆分，确需区分完整句意时保留句号，不机械替换成逗号或分号
• 命令、URL、版本号、字段名和原始输出保持准确，不为统一标点改写代码示例

审查时逐段核对：是否属于当前状态、是否回答读者问题、是否放在正确文档、是否重复、脱离变更背景能否独立理解

没有文档改动本身不构成验证缺口，判断依据是当前说明是否仍然准确、完整

界面验证

AI 进行前端开发时，加载并使用 $frontend-design 技能。设计方案以本项目的用户任务、管理端主题 和已有页面为依据，优先延续原页面的布局、信息层级与交互；设计技能不构成重做页面的理由

开发前查找原页面、同类页面及 modules/ui/src/components 中的基础组件，明确参考实现和可复用部分，再确定最小改动。只有原设计不能满足本次操作或存在具体问题时才调整结构，并在 PR 中说明原因；不顺带换风格、重排无关区域或增加重复的模式入口。需要扩展时在对应职责层修改；局部样式的适用范围遵循主题文档，不一律禁止，也不靠页面覆盖掩盖共用组件的问题

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

提交者在浏览器中验证受影响路径，页面变更的 PR 必须提供实际运行截图，包括布局、文案、样式和交互状态的变化：

• 修改现有页面提供变更前后截图，尽量保持相同数据、主题和窗口尺寸；新增页面提供完成态截图。截图保留必要上下文，让审查者能判断布局和信息密度，不只截取孤立控件
• 按影响范围补充浅色/深色、窄窗口及空/加载/错误等受影响状态；共用主题或基础组件变更按主题文档扩大验证范围。弹出层中的内容需展示展开状态，不能只截关闭后的页面
• 在 PR 正文嵌入或链接审查者可访问的图片，注明页面入口、状态和对应提交。录屏、预览地址和复现步骤用于补充，不能替代截图；本机绝对路径不算可供远端审阅的附件
• 视觉或交互继续修改后更新受影响截图，使证据对应待审实现。截图与模拟数据不得包含真实凭据，不用设计稿、生成图片或旧版截图冒充运行结果
• 环境不足时说明缺少的截图和交互验证，不宣称验收通过；页面 PR 在截图补齐前保留 Draft，不标为可审阅或建议合并

截图用于视觉审阅，保存、切换、错误恢复和键盘操作等行为仍需实际验证并记录覆盖范围，不能仅凭静态图片推断交互正确

涉及浏览器能力或访问环境差异时，按项目支持的部署方式核对相关 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 服务或更改分支设置