16 KiB
贡献与审查
贡献应解决明确的问题，并保持或改善项目的可维护性。提交者、自动检查和审查者使用同一套标准，让重复问题在提交和初审阶段得到处理。
本文定义协作流程与审查标准；模块职责以 系统架构 为准，视觉规则以 管理端主题 为准。没有明确约定时遵循相邻实现；具体页面的布局决定不自动成为全项目限制。
交流与反馈
讨论区 用于使用问答、想法讨论、实验反馈和经验分享。 提问时按需补充版本、部署方式、已尝试的方法及脱敏信息；问题解决后，请在「使用问答」中标记有帮助的答案。
明确的 Bug、具体功能需求或协作规则建议使用 Issue，无需先开讨论。 讨论形成可执行事项后，可以新建 Issue 并互相附链接；已有 Issue 的后续信息继续补充在原帖，避免重复记录。 围绕问题友善交流，欢迎不同使用场景和方案观点。
提交 Issue
按场景选择 接口问题反馈、常规问题反馈 或 功能建议 表单，按对应提示提供信息。故障反馈填写实际运行版本和中转链路；接口问题区分客户端显示与网关实际响应，页面问题附相关截图或录屏。
日志和配置只提供定位所需片段，不上传真实凭据或完整请求转储。功能建议说明使用场景、当前不便和期望行为；协作规则调整可直接提交普通 Issue，说明原因和建议方案。
问题与方案依据
开发、创建 PR 和审查都先核实待解决的问题、触发条件与预期行为，再确定或评估实现。区分问题发生版本、目标分支现状和本次变更后的行为，不把需求描述、PR 描述或第三方项目的做法直接当成事实。目标分支已修复的问题，应说明当前仍需补齐的差异，不能据此否定旧版本中的问题。
涉及上游协议、客户端行为或兼容性时，以对应版本的官方源码为首要资料。优先读取用户提供或本机已有的官方源码，核对仓库来源、版本或提交；本地资料不足时查官方仓库的对应版本源码，再结合官方测试、文档、发布说明和运行证据。第三方资料只作线索或补充。引用具体文件、符号或行号，对外引用优先使用固定提交的源码链接；源码不可得或版本不匹配时说明证据缺口，不把最新实现当成当前部署行为。无上游依赖的内部变更，以本项目代码、合同和运行证据为依据。
官方已有同一场景的处理方式时，优先沿用其协议语义、职责归属和解决路径，检查是否只需复用已有能力或正确传递官方合同。新增覆盖配置、补偿逻辑或采用第三方兼容方案，应说明官方路径为何不足；偏离官方方案需有本项目的实际约束和验证依据，不机械照搬源码，也不默认接受已有提案。
反馈 Issue 时区分观察到的症状、根因假设和方案建议，关联已有 Issue、PR 及包含修复的发布版本。能说明问题的反馈可以先提交，不要求报告者先找到官方源码或证明根因；引用官方行为或提出实现方案时，按上述原则注明依据与缺口。
PR 流程
- 准备变更。 按上述依据核实问题与方案，找到所属模块、相关调用链和最接近的现有实现，在功能分支完成修改与自查。涉及架构、公开合同或较大交互变化时，先说明方案与取舍。
- 发起 PR。 目标分支使用
main。说明问题成立的依据、触发场景、改动后的行为和实际验证结果；涉及官方行为时注明源码位置、版本和方案关系。界面改动提供截图、录屏或可复现的预览方式。一个 PR 围绕一个明确目标，必要重构说明关联原因。 - 自动检查与初审。 CI 执行适用的格式、静态分析、测试和构建检查；启用 AI 审查后，由它按本规范辅助检查语义、复用和一致性。提交者先处理明确问题，维护者重点审阅方案、风险与用户体验。
- 修改与合并。 更新代码后重新执行受影响的检查，确认审查意见已处理，验证证据对应当前变更。维护者审阅批准后再合并；需要升级说明的变更同步相关文档。
AI 开发和审查入口是根目录的 AGENTS.md。在仓库上下文中要求“审查 PR #编号”时，应按下列标准执行，无需再次列举要求。
项目技能
仓库技能位于 .agents/skills/，随代码共享。技能提供执行流程，协作与审查标准仍以本文和 AGENTS.md 为准。
| 技能 | 用途 | 调用示例 |
|---|---|---|
| dev-guide | 项目开发与文档导航 | $dev-guide 修复当前问题 |
| plugin-dev | 网关插件开发、打包与验证 | $plugin-dev 开发一个添加响应头的插件 |
| 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 技能。设计方案以本项目的用户任务、管理端主题 和已有组件为依据，在任务范围内改进布局、视觉与交互。
开发前查找同类页面及modules/ui/src/components 中的基础组件，优先使用已有主题 Token、交互和数据展示逻辑。需要扩展时在对应职责层修改；局部样式的适用范围遵循主题文档，不一律禁止，也不靠页面覆盖掩盖共用组件的问题。
列表列宽、序号、按钮、分页和弹窗尺寸由实际任务与数据规模决定，以同类页面为参照。新增或调整交互时说明用户需要完成什么操作，不把某个页面的取舍推广成全局禁令。
提交者在浏览器中验证受影响路径，提供前后截图、录屏或预览步骤，并标明实际覆盖的状态。按变更选择浅色/深色、窄窗口、空/加载/错误状态、大量数据及键盘操作；共用主题或基础组件变更按主题文档扩大验证范围。模拟数据与预览材料不包含真实凭据。
涉及浏览器能力或访问环境差异时，按项目支持的部署方式核对相关 HTTP/HTTPS、localhost/实际部署地址与浏览器版本，记录实际覆盖的条件；本地预览正常不能替代部署环境中的交互验收。
验证
选择与变更相关的检查，纯文档修改无需重建前后端。行为修复补充能覆盖触发条件和结果的测试，不增加仅复述实现的断言。
| 范围 | 现有检查 | 仍需提供的证据 |
|---|---|---|
| Rust | Rustfmt、严格 Clippy、后端测试、架构边界检查 | 相关失败场景和集成行为 |
| 前端 | ESLint、类型检查与构建 | 页面一致性、交互和实际数据状态 |
| 数据库迁移 | 冻结清单校验与 PR 基线比对 | 升级行为及兼容说明 |
| 依赖安全 | Cargo Audit、pnpm Audit | 本次变更的权限、数据与信任边界 |
| 工作流与容器 | Actionlint、相关容器检查 | 改动涉及的运行行为 |
UI 与示例源码分别在独立的 codex-proxy-ui、codex-proxy-plugins 仓库维护。前端的依赖、锁文件和 ESLint 配置均在 frontend/ 管理，仓库根目录不维护 Node 包。UI 使用固定 GitHub 标签或提交依赖，锁文件记录实际提交、源码归档地址及完整性摘要，常规开发和 CI 不需要检出同级仓库。安装时 pnpm 按 UI 自身锁文件准备构建依赖，再执行 prepack 生成 JS、CSS 和类型声明。开发服务通过 UI 包的 development 入口使用 Vue SFC，生产构建使用 dist。
pnpm 版本由 frontend/package.json 的 packageManager 固定，CI 和 Docker 从该字段读取。frontend/pnpm-workspace.yaml 的 allowBuilds 按仓库放行自有 UI 包的构建脚本；升级依赖时核对源码并更新锁文件，无需逐次修改构建许可，不开放全部依赖脚本。
pnpm --dir frontend install --frozen-lockfile
需要联合修改组件库或插件时，使用 源码联调 中的子模块与开发入口；联调只临时替换解析路径，不改写正式依赖或锁文件。独立插件的 SDK 固定到包含所需合同的 Git 提交，不依赖浮动分支。
前端从仓库根目录执行：
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 服务或更改分支设置。