ZyyandCodex
687ebd0331
Introduce SDK 0.4, manifest v3, protocol v4, the isolated plugin runtime, and cpr-plugin packaging CLI for independently maintained plugins. Support installation, permissions, one active configuration per plugin, version-specific settings, rollback, management pages, and CLI extensions. Isolate plugin failures so native gateway startup and requests remain available. Keep provider registration and UI choices fixed to built-in OpenAI and xAI. Support nine extension capabilities with permission-scoped model and account callbacks to the host. Unify plugin settings and version management, support plugin icons, and improve narrow layouts. Use the fixed GitHub UI dependency and pnpm 12 for standalone frontend and container builds. Reduce runtime test packaging cost and align preparation modules with the repository layout. Co-authored-by: Codex <noreply@openai.com>
17 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 技能。设计方案以本项目的用户任务、管理端主题 和已有组件为依据，在任务范围内改进布局、视觉与交互。
开发前查找同类页面及同级 codex-proxy-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
需要修改组件库时，按 UI 源码联调指南 建立临时本地链接；提交前恢复发布依赖并核对锁文件，不能将开发机目录写入发行依赖。独立插件的 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 服务或更改分支设置。