From a1fc368474258d079bd66d25608880ebc374178b Mon Sep 17 00:00:00 2001 From: Zyy Date: Mon, 28 Sep 2026 15:54:49 +0800 Subject: [PATCH] docs: streamline documentation and skill workflows Keep documentation focused on current behavior and clear ownership. Load skill references by task and clarify official source priority and reply tone. Co-authored-by: Codex --- .agents/skills/cpr-dev-guide/SKILL.md | 82 +-- .../cpr-dev-guide/references/documentation.md | 38 ++ .../references/plugin-boundaries.md | 11 + .agents/skills/cpr-github-issue/SKILL.md | 87 +-- .agents/skills/cpr-github-pr/SKILL.md | 144 ++--- .../skills/cpr-github-pr/references/create.md | 35 + .../skills/cpr-github-pr/references/review.md | 33 + .agents/skills/cpr-plugin-dev/SKILL.md | 105 +-- .../cpr-plugin-dev/references/development.md | 11 +- .../cpr-plugin-dev/references/frontend.md | 11 + .../references/implementation.md | 24 + .agents/skills/cpr-release/SKILL.md | 128 +--- .../cpr-release/references/experimental.md | 14 +- .../cpr-release/references/operations.md | 49 ++ .../cpr-release/references/preparation.md | 36 ++ AGENTS.md | 21 +- CONTRIBUTING.md | 152 +++-- README.md | 31 +- backend/apps/plugin-cli/README.md | 15 +- backend/crates/gateway-plugin/sdk/README.md | 24 +- .../gateway-plugin/sdk/docs/capabilities.md | 117 ++-- .../gateway-plugin/sdk/docs/manifest.md | 29 +- backend/migrations/README.md | 20 +- deploy/README.md | 292 +++++---- docs/api.md | 602 +++++++++--------- docs/architecture.md | 378 +++++------ docs/development.md | 87 ++- docs/plugins.md | 73 ++- docs/theme.md | 176 ++--- 29 files changed, 1498 insertions(+), 1327 deletions(-) create mode 100644 .agents/skills/cpr-dev-guide/references/documentation.md create mode 100644 .agents/skills/cpr-dev-guide/references/plugin-boundaries.md create mode 100644 .agents/skills/cpr-github-pr/references/create.md create mode 100644 .agents/skills/cpr-github-pr/references/review.md create mode 100644 .agents/skills/cpr-plugin-dev/references/frontend.md create mode 100644 .agents/skills/cpr-plugin-dev/references/implementation.md create mode 100644 .agents/skills/cpr-release/references/operations.md create mode 100644 .agents/skills/cpr-release/references/preparation.md diff --git a/.agents/skills/cpr-dev-guide/SKILL.md b/.agents/skills/cpr-dev-guide/SKILL.md index 09cd431a4..e69ed6c3d 100644 --- a/.agents/skills/cpr-dev-guide/SKILL.md +++ b/.agents/skills/cpr-dev-guide/SKILL.md @@ -1,69 +1,49 @@ --- name: cpr-dev-guide -description: Codex Proxy RS 仓库开发与问题审查入口。用户要求“开发／实现这个功能”“直接改”“修复一下”“看下报错”“审查这个问题／代码”“自审当前改动”“调整页面”“更新文档”，或继续修改本仓库的 Rust、Vue、协议、存储、部署和 CI 时主动使用，无需点名技能。负责定位、方案、自审与验证；提交或审查 PR 另配合 cpr-github-pr。Use for implementation, debugging, code review and documentation in this repository, not generic advice for unrelated projects. +description: Codex Proxy RS 仓库的开发、修复、排障、代码审查和文档修改入口；PR、Issue、插件创作与发版按任务另用对应技能 --- # 开发指南 -先读根目录的 [AGENTS.md](../../../AGENTS.md) 和 [CONTRIBUTING.md](../../../CONTRIBUTING.md)。 -本技能只组织工作入口，架构、协议和视觉规则从下列权威文档读取，不维护第二份副本。 +## 加载边界 -普通问题审查、代码审查与排查由本技能进入贡献文档的审查标准；有 PR 链接、编号或提交 PR 的意图时再加载 `cpr-github-pr`。 -审查请求先报告结论，不因加载开发技能而擅自修复；用户已要求修改时完成实现、自审和验证。 +- 遵守已提供的 [AGENTS.md](../../../AGENTS.md)，上下文已有的规则不重复读取 +- 下表是条件导航，不是必读清单，只加载当前任务命中的技能与章节，进入新阶段再补读 +- 文档链接带 `#章节` 不代表读取工具会自动截取内容，先用 `rg -n '^#{1,4} ' 文件` 找边界，再按范围读取；常规定位不整份加载 CONTRIBUTING、架构、API、主题或全部 references，确需全文审查时再展开 +- 每次补读先明确要解决的未知项，已有资料足够就继续工作；文档提及 Rust、Vue、插件或发布，不等于要加载对应开发流程 ## 按任务读取 -| 任务 | 技能与文档入口 | +| 当前任务 | 必读的相关部分 | | --- | --- | -| 用户能力、快速开始 | [README](../../../README.md) | -| 模块职责、调用链、状态归属 | [系统架构](../../../docs/architecture.md) | -| Rust 开发 | 加载并使用 `$rust-best-practices`，结合 [系统架构](../../../docs/architecture.md) 与 [项目约定](../../../CONTRIBUTING.md#项目约定) | -| HTTP 路由、请求与响应、导入导出 | [API 文档](../../../docs/api.md) | -| 插件 SDK、Runtime 或宿主能力扩展 | 先执行下方「插件架构边界」，结合 [系统架构](../../../docs/architecture.md) 定位原生能力归属 | -| 开发独立网关插件 | 先执行下方「插件架构边界」，再使用 [cpr-plugin-dev](../cpr-plugin-dev/SKILL.md)：公开 SDK、能力选择、示例、打包与验证 | -| 前端开发、管理端组件、主题 Token、视觉验证 | 按下方「前端任务」加载设计约束，结合 [管理端主题](../../../docs/theme.md) 与 [界面验证](../../../CONTRIBUTING.md#界面验证) | -| 常规文档更新 | [文档职责与更新条件](../../../CONTRIBUTING.md#文档职责与更新条件)：维护当前说明，在原章节就地修订，不记录变更历史 | -| 部署、客户端配置、备份与恢复 | [部署说明](../../../deploy/README.md) | -| 数据迁移、冻结清单与本地测试库 | [迁移说明](../../../backend/migrations/README.md) | -| 验证命令与提交规范 | [贡献与审查](../../../CONTRIBUTING.md) | -| 创建或审查 PR | [cpr-github-pr](../cpr-github-pr/SKILL.md) | -| 整理或提交 Issue | [cpr-github-issue](../cpr-github-issue/SKILL.md) | -| 发布说明、版本规划与发版 | [cpr-release](../cpr-release/SKILL.md) | +| 开发、排障、代码审查 | [问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)，需要定位代码时按 AGENTS 的 CodeGraph 约定执行 | +| 模块或调用链变更 | [Workspace 边界](../../../docs/architecture.md#3-workspace-边界)及所属模块章节，不通读整份架构 | +| Rust 开发或审查 | `$rust-best-practices`、所属模块、[后端自审](../../../docs/architecture.md#后端自审)，验证时读[命令](../../../docs/architecture.md#验证命令) | +| 页面开发 | `$frontend-design`、[文案与信息层级](../../../docs/theme.md#界面文案与信息层级)、[界面验证](../../../CONTRIBUTING.md#界面验证)；修改已有页面前留存截图，主题算法仅在涉及时读取 | +| 接口、部署或迁移 | 分别定位 [API](../../../docs/api.md)、[部署](../../../deploy/README.md)、[迁移](../../../backend/migrations/README.md)的对应章节 | +| SDK、Runtime、宿主扩展或独立插件 | [插件职责边界](references/plugin-boundaries.md)；只有创作、排查独立网关插件时使用 [cpr-plugin-dev](../cpr-plugin-dev/SKILL.md) | +| 修改或审查文档 | [文档检查](references/documentation.md)及目标章节，不默认读取代码开发、页面验收或发布流程 | +| 普通代码审查 | [审查标准](../../../CONTRIBUTING.md#审查标准)；审查默认只读 | +| PR / Issue / 发版 | 按当前意图选 [PR](../cpr-github-pr/SKILL.md)、[Issue](../cpr-github-issue/SKILL.md)或[发版](../cpr-release/SKILL.md)，普通提交不创建 PR | -## 前端任务 +## 参考仓库的优先级 -- 加载并使用 `$frontend-design`，先读 [界面文案与信息层级](../../../docs/theme.md#界面文案与信息层级)，将本项目的管理工具风格、现有字体与主题 Token 作为设计约束 -- 开发前对照原页面及该章节的同类参考，确认可复用布局、组件与操作位置；修改已有页面前先留存截图，不为局部需求重做页面 -- 页面保留操作所需的简短信息，重复文案删除，详细帮助按主题约定收进 Popover；关键限制和错误仍就近提示 -- 交付前按该章节复核文案、层级与密度，按 [界面验证](../../../CONTRIBUTING.md#界面验证) 实际操作并保存前后截图；页面 PR 的截图必须可供审查者访问，预览步骤与构建不能替代 +- 涉及 Codex 行为、协议或兼容性时，以官方 [openai/codex](https://github.com/openai/codex) 对应版本的源码与调用链为第一手资料，先查官方实现 +- 优先使用用户提供或本机已有的官方仓库，核对来源、版本或提交；资料不足时再查官方对应版本的源码、测试与文档 +- 三方仓库只能提供排查线索或实现参考，不能代替官方行为依据；与官方不一致时回到官方源码核实，不直接照搬三方结论 +- 结论注明适用版本或提交，区分官方事实、三方参考与本项目推断；官方证据不足时保留不确定性 -## 后端任务 +## 执行与收尾 -加载并使用 `$rust-best-practices`，先按架构文档定位事实归属与既有调用链，实现后逐项执行 [后端自审](../../../docs/architecture.md#后端自审) 中与本次改动相关的检查。 -交付说明实际复用位置、重要边界的处理与验证缺口，不用“符合最佳实践”或“CI 已通过”代替自审结论。 +1. 确认工作区、任务范围与已有改动，先定位事实归属、同类实现和调用链，再修改；编码前只读[项目约定](../../../CONTRIBUTING.md#项目约定)的对应条目 +2. 自审完整差异，处理本次引入的职责越界、重复规则、冗余状态与无依据分支；仅审查时报告，不自行修复 +3. 按变更范围读取[验证](../../../CONTRIBUTING.md#验证)，区分通过、失败、跳过与未执行；提交时补读[提交约定](../../../CONTRIBUTING.md#项目约定) +4. 交付说明实际结果与验证缺口；页面证据和后端生命周期检查按上表执行，不把构建通过当作行为验收 -## 插件架构边界 +## 文档硬约束 -**底线：宿主可以暴露底层能力，但不能替插件完成业务。** 开发或审查插件 SDK、Runtime、宿主接口及独立网关插件时，必须先明确宿主与插件各自的职责；具体架构依据见 [系统架构](../../../docs/architecture.md)。 +**常规文档只描述当前状态，不写变更历史**，这项检查适用于每次开发收尾，不限于专门的文档任务 -- 宿主提供独立、可组合的受控原生能力，负责授权、资源隔离、事务和审计，复用已有服务与状态归属。 - 插件自身的触发条件、跨资源业务关联、策略和流程编排由插件实现；不能将某个 Issue 的使用场景直接做成宿主的组合流程，或为其增加专属业务状态与补偿逻辑。 -- 开发独立网关插件时，在插件内通过公开 SDK 组合用户要求的业务。发现能力缺口时，先界定可独立使用的基础接口，不能把整个插件业务搬进宿主。 -- 基础接口必须说明输入输出、权限、事务、失败及重复调用语义；这些合同不应夹带对插件业务工作流或私有数据模型的要求。 -- 自审完整调用链、协议、测试与文档，检查是否混入插件业务判断、自动串联或专属状态；仅更换通用名称不算消除业务耦合。 - -## 执行顺序 - -1. 从仓库根目录确认工作区、当前任务范围和相关运行实例；保留已有改动。 -2. 按 `AGENTS.md` 的 CodeGraph 约定定位入口、调用链和职责归属，再阅读相关实现。 -3. 按 [问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据) 核实触发条件、问题发生版本与目标分支现状， - 优先依据适用的官方源码确定或评估方案。结合上表读取所需文档，先找可复用的同类实现，再按授权修改或审查所属模块。 -4. 文档和运行结果不一致时，追查当前源码、配置与版本，区分实现缺陷和文档过期； - 按 [文档职责与更新条件](../../../CONTRIBUTING.md#文档职责与更新条件) 判断是否修订，不为每次改动追加文档或发布说明。 -5. 复核相对目标基线的完整差异及上下游：开发时清理本次引入的职责越界、重复逻辑、冗余状态和无依据的分支；仅审查时报告问题与依据。页面与后端分别按上述任务入口执行，插件相关变更还须逐项核对「插件架构边界」，不等待 PR 审查代做开发自审。 -6. 交付前按文档职责逐段复核最终文档 diff：新增内容是否回答当前读者的使用或维护问题，是否属于该文档， - 是否与其他位置重复，脱离本次变更背景能否独立理解。仅解释实现经过、前后对比或验证结果的内容移到 - 任务报告或 PR；仍影响升级、恢复的说明保留适用条件与操作。没有文档差异时，只核对行为变化是否使现有说明失真。 -7. 按 `CONTRIBUTING.md` 验证并报告结果。后端 Cargo 命令从 `backend/` 执行，或显式指定该目录的 manifest。用户要求提交或更新 PR 时，进入 `cpr-github-pr` 流程整理最终证据与正文。 - -发布任务按 `cpr-release` 技能读取当前版本、发布入口和工作流，发布说明语言遵循 `CONTRIBUTING.md`。 +- 动笔前确定读者、所属章节与必须说明的当前事实，没有必要就不改文档 +- 有文档差异时执行[文档检查](references/documentation.md)，逐段决定保留、改写、删除或移入任务报告，未完成内容审查不能称文档已检查 +- 没有文档差异时只确认现有说明是否失真；普通开发不自动修改 `release/notes.md` diff --git a/.agents/skills/cpr-dev-guide/references/documentation.md b/.agents/skills/cpr-dev-guide/references/documentation.md new file mode 100644 index 000000000..1cc46e262 --- /dev/null +++ b/.agents/skills/cpr-dev-guide/references/documentation.md @@ -0,0 +1,38 @@ +# 文档检查 + +仅在准备修改文档或最终差异含文档时读取，职责与行文依据是 [文档职责与更新条件](../../../../CONTRIBUTING.md#文档职责与更新条件)，只读该节 + +## 写之前 + +先明确这段内容服务谁、解决哪个当前使用或维护问题、属于哪个现有章节，再决定详略 + +接口保留调用合同，架构保留职责与不变量，部署保留操作与排障；同一事实只在所属位置完整说明，其他位置链接 + +常规文档在原章节修订，不追加本次变更小节，不为了“同步文档”补写修复总结 + +内部重构、实现经过、前后对比、验证结果应留在 PR、Issue 或任务报告 + +## 逐段验收 + +检查工作区和暂存区中本任务的最终文档差异，按内容用途处理，不只搜索关键词： + +| 段落回答的问题 | 处理 | +| --- | --- | +| 现在如何使用、配置或理解结果 | 保留当前事实与必要边界，放回所属章节 | +| 谁负责状态、事务、资源和失败处理 | 放入所属架构章节，避免在 API 或部署文档复述实现 | +| 这次做了什么、以前怎样、为什么这样修、跑过哪些测试 | 移入 PR、Issue 或任务报告，不以换成现在时的方式留在常规文档 | +| 特定配置或数据状态下如何升级、恢复 | 写明适用条件、操作及限制，删除演变过程 | +| 别处已完整说明的事实 | 合并或改为必要摘要与链接 | + +脱离提交日期、Issue 和本次任务背景后，读者仍应能独立理解正文 + +业务中的请求历史、审计记录、旧数据兼容与回滚操作是当前功能，不能因含“历史”“旧”等词而删除 + +## 交付检查 + +- 检查新段落的必要性、归属、重复与当前状态表达，发现变更叙述先改完再交付 +- 标题、短列表、表格和独立短段通常不加句号，长段按主题拆分，命令与字段保持准确 +- 检查相对链接、章节锚点、表格与命令示例，`git diff --check` 或构建通过不能代替内容审查 +- 报告实际覆盖和缺口即可，不把检查记录写进常规文档 + +只有明确的发布说明任务才进入 `cpr-release`，`release/notes.md` 用于该次发行，不向 README、API、架构或部署文档复制版本变化列表 diff --git a/.agents/skills/cpr-dev-guide/references/plugin-boundaries.md b/.agents/skills/cpr-dev-guide/references/plugin-boundaries.md new file mode 100644 index 000000000..97b1ac7a5 --- /dev/null +++ b/.agents/skills/cpr-dev-guide/references/plugin-boundaries.md @@ -0,0 +1,11 @@ +# 插件职责边界 + +仅在开发或审查 SDK、Runtime、宿主扩展接口及独立网关插件时读取 +先看[插件扩展](../../../../docs/architecture.md#31-插件扩展)中的职责与执行边界，不通读整份架构 + +**宿主可以暴露底层能力，不能替插件完成业务** + +- 宿主提供可独立组合的受控原生能力，负责授权、资源隔离、事务与审计，复用已有服务与状态归属 +- 插件自身的触发条件、跨资源关联、策略和流程编排由插件实现，不能把某个使用场景做成宿主专属流程、状态或补偿逻辑 +- 发现能力缺口时，界定可独立使用的基础接口，说明输入输出、权限、事务、失败及重复调用语义，不夹带插件私有数据模型或工作流 +- 自审调用链、合同、测试与文档中的业务判断、自动串联和专属状态，仅换成通用名称不算解除耦合 diff --git a/.agents/skills/cpr-github-issue/SKILL.md b/.agents/skills/cpr-github-issue/SKILL.md index 2dedd6ab1..513a9e8be 100644 --- a/.agents/skills/cpr-github-issue/SKILL.md +++ b/.agents/skills/cpr-github-issue/SKILL.md @@ -1,61 +1,62 @@ --- name: cpr-github-issue -description: 整理、创建和补充 GitHub Issue。用户说“提／开／提交一个 Issue”“报个 bug 到仓库”“反馈给上游”“把问题或功能建议整理成 Issue”“补充这个 Issue”时主动使用；已有 Issue 反馈上下文中的“提交吧”“补上复现”也适用。处理缺陷、功能与协作规则反馈，区分草拟和发布。Use for drafting, filing and updating issues; standalone “审查问题／看下报错／修一下” belongs to cpr-dev-guide, not automatic Issue submission. +description: 草拟、创建、补充或回复 GitHub Issue，包括缺陷、功能和协作规则反馈；单独排障或修复不自动发布 Issue --- -# 整理与提交 Issue +# Issue 协作 -本仓库流程见 [贡献与审查](../../../CONTRIBUTING.md)，按场景选择当前的 -[接口问题反馈](../../../.github/ISSUE_TEMPLATE/api-bug-report.yml)、[常规问题反馈](../../../.github/ISSUE_TEMPLATE/general-bug-report.yml) -或 [功能建议](../../../.github/ISSUE_TEMPLATE/feature-request.yml) 表单。从表单读取字段与必填项，不在技能中复制一份字段清单。 -用户指定其他仓库时，使用该仓库当前的贡献规则与 Issue 模板，不能把这里的表单套过去。 +## 目标与范围 -## 确定目标和动作 +从用户 URL、remote 和上下文确认接收仓库，fork 场景区分自己的仓库与上游 -- 根据用户 URL、仓库上下文和 remote 确认接收 Issue 的仓库。fork 场景核对用户要反馈给自己的 fork 还是上游。 -- “写一份、整理内容、草拟 Issue”只准备正文；明确要求“提交、创建 Issue”才发布。 - 已经授权提交且信息足够时直接完成，不重复索要确认；仅自动选中技能不能授权发布。 -- “有个 bug”“这个报错怎么修”本身是排障语境，不能推断要发 Issue；结合已有反馈任务识别省略的目标和动作。 -- “补充这个 Issue”先读取原帖与已有讨论，按授权更新正文或追加证据，不重复新建；需要排查或修改本仓库时先执行 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)。 -- 缺少无法推断的目标或关键复现事实时，只问必要信息，并先整理其余已有证据。 -- 使用可用的 GitHub 连接器或 `gh`。不要为提交 Issue 安装新工具、修改仓库配置或启用额外服务。 +草拟只准备正文，明确创建或提交才发布；已有授权直接执行，自动命中技能本身不授权远程写入 -## 证据与去重 +补充已有 Issue 先读原帖和讨论，按授权更新或追加，不重复新建；无法推断的目标或关键事实才向用户补齐 -1. 读取目标仓库实际 Issue 模板和配置，区分缺陷、功能建议与协作规则提案。 - 本仓库功能建议有独立表单，协作规则提案允许普通 Issue；其他仓库按其配置选择入口。 -2. 先搜索 open 和 closed Issues，结合关键词、错误信息与触发条件检查重复，而不只比较标题。 - 同时核对相关 PR 与发布记录，关联已有修复及其发布版本；仅主分支已修复时明确尚未发布。 - 同一问题已有记录且没有新增证据时返回已有链接；用户仍明确要求新建时按其要求处理。 - 不因发现重复而擅自评论、重开或关闭已有 Issue。 -3. 从用户描述、当前版本与已有诊断中整理事实：区分实际结果、预期结果、稳定复现条件和未经证实的推测。 - 不把本地开发版本当作发生问题的部署版本；无法复现时如实说明已知条件。 - 引用官方行为或提出实现方案时，按 [问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据) 注明来源、版本与缺口； - 不把找到官方源码或证明根因作为提交症状反馈的前提。 -4. 只收集定位所需信息。正文、日志片段和附件去除密钥、Cookie、令牌、代理认证、私人请求内容等敏感信息； - 不直接附完整配置或请求转储。记录与复现相关的代理、TUN、证书条件，不擅自修改这些环境来收集材料。 +## 按需取材 -## 编写正文 +- 新建 Issue 时，本仓库只读[提交 Issue](../../../CONTRIBUTING.md#提交-issue)及本次匹配的一张表单：[接口问题](../../../.github/ISSUE_TEMPLATE/api-bug-report.yml)、[常规问题](../../../.github/ISSUE_TEMPLATE/general-bug-report.yml)或[功能建议](../../../.github/ISSUE_TEMPLATE/feature-request.yml)；协作规则提案可用普通 Issue +- 回复时读取原帖、相关讨论与支撑答复的证据，按下方回复口吻组织内容，不套用新建 Issue 的表单 +- 其他仓库读取它自己的相关规则与实际模板，长文档先定位标题再截取，不预读全部模板或 CONTRIBUTING +- 搜索同场景 open/closed Issues、相关 PR 和发布记录，区分主分支修复与已发布修复，不凭标题判断重复；没有新证据时返回已有链接，用户仍要求新建则按其要求处理 +- 仅当需要额外排查或修改时使用 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)，提交症状反馈不以找到根因为前提 +- 引用上游行为或提出方案时读取[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)，涉及 Codex 时按[参考仓库优先级](../cpr-dev-guide/SKILL.md#参考仓库的优先级)先查官方 Codex 源码，三方仓库仅作参考；注明适用版本、来源与缺口 -- 标题写具体症状或所需行为，不预先断言尚未证明的根因。语言与目标仓库及用户要求一致。 -- YAML Issue Form 按字段顺序使用 `attributes.label` 作为 Markdown 小标题，填写相应答案。 - `gh issue create --body-file` 直接提交正文，不会替你完成网页表单校验；手动核对必填字段、选项和必选确认项。 - 不把原始 YAML、占位文字或尚未确认的勾选项当成答案提交。 -- 无法获知的信息明确写未提供或不适用，并说明理由；如果该事实关系到能否理解或复现问题，发布前补齐。 - 功能或规则提案说明当前场景、缺少的能力、建议结果和必要取舍，不强行填写缺陷复现步骤。 -- 附件只使用用户授权发布且实际可访问的地址；本机 `/tmp/...` 路径不能作为 GitHub 附件。 - 没有可用附件时保留操作描述并说明缺口，不声称截图已上传。 -- 使用模板规定或用户要求的 labels、assignees；先确认它们在目标仓库存在，不自行猜测。 +## 正文与证据 -## 提交与收尾 +标题说明症状或期望行为，区分发生问题的部署版本、实测结果、预期结果与根因假设 -把核对后的 UTF-8 正文写入临时文件，或直接传给连接器的结构化字段。CLI 变量先从已确认的目标与正文赋值： +功能和规则提案说明场景、缺少的能力及建议结果，无需硬套缺陷复现步骤 + +YAML 表单按 `attributes.label` 和字段顺序组织正文，手工核对必填项、选项与确认项，CLI 不会代做表单校验 + +未知信息如实标明，影响理解或复现的关键事实先补齐，不提交原始 YAML、占位答案或未确认的勾选项 + +日志和附件仅含定位所需的脱敏片段，不公开凭据、完整配置或请求转储，不擅自修改代理、TUN、证书环境取证 + +附件须获授权且可访问，本机路径不算附件；labels 和 assignees 仅按模板或用户要求设置，并确认实际存在 + +Issue 可记录复现、排查和变更经过，不因此向常规文档追加历史；确需改文档时执行[文档检查](../cpr-dev-guide/references/documentation.md) + +## 回复口吻 + +草拟和发布 Issue 回复时遵守以下约定： + +- 用第一人称“我”表达，称呼对方为“佬友”，称呼自然出现即可，不逐句重复，也不用“我们”“本助手”代称自己 +- 语气客气、委婉，直接回应对方的具体问题；补充信息或提出不同意见时说明缘由，避免命令式、责备式表达 +- 使用自然短句，简单回复用短段，只有并列信息较多时才分点；少用句号，避免客服套话、机械模板和空泛保证 +- 只把实际完成的排查、复现和验证写成“我已……”；未确认的事实如实说明，委婉表达也要说清结论、限制和下一步 + +## 发布与收尾 + +使用可用连接器或 `gh`，不为提交反馈安装工具、修改仓库配置或启用服务 + +多行正文通过结构化字段或 UTF-8 文件传递，以下变量须先从已确认的目标与正文赋值： ```bash gh issue create --repo "$issue_repo" --title "$issue_title" --body-file "$issue_body_file" ``` -发布前快速复核目标、必填内容、脱敏及重复记录；更新已有 Issue 时保留与本次无关的内容，核对目标编号和当前正文。 -网络超时或返回不明确时先查询远端是否已经创建或更新，避免重复提交。 -发布后读取目标 Issue 确认仓库、标题和正文，返回链接及必要的信息缺口。 -只准备草稿或发布失败时提供可直接使用的标题与正文，明确尚未提交。 +发布前核对目标、必填内容、脱敏与重复记录，更新时保留无关原文；不擅自评论、重开或关闭重复 Issue + +超时或结果不明确时先查询远端再重试，发布后回读确认并返回链接；仅草拟或发布失败时提供正文并注明未提交 diff --git a/.agents/skills/cpr-github-pr/SKILL.md b/.agents/skills/cpr-github-pr/SKILL.md index 882eec5fe..16b2cd9c0 100644 --- a/.agents/skills/cpr-github-pr/SKILL.md +++ b/.agents/skills/cpr-github-pr/SKILL.md @@ -1,121 +1,51 @@ --- name: cpr-github-pr -description: 准备、提交、更新与审查 GitHub PR。用户说“提交 PR／提个 PR／发起拉取请求”“把改动放到这个 PR”“改下 PR 描述”“看下／review／审查这个 PR”“处理审查意见”“这个 PR 能合并吗”，或提供 /pull/ 链接、PR 编号并要求处理时主动使用；已有 PR 上下文中的“提交吧”“继续改”也适用。包含问题核实、自审、页面截图、AI 模型披露与验证。Use for pull request preparation, creation, updates and review; plain git commits or issue debugging without PR context do not create a PR. +description: 准备、创建、更新或审查 GitHub PR，含回复讨论与处理审查意见；普通 Git 提交和无 PR 上下文的排障不创建 PR --- -# 提交、更新与审查 PR +# PR 协作 -## 先确定模式和仓库 +## 先确定范围 -| 用户意图 | 执行范围 | +沿用当前会话的目标与授权，创建 PR 包含任务范围内的提交和推送，审查默认只读；二者都不包含合并 + +仅准备标题或正文不写远端，“能合并吗”按审查处理，发布评论、批准或请求修改须有对应授权 + +从 URL、remote 和上下文确认仓库，区分 fork 的推送端与 PR 接收端；存在无法消除的歧义时只补齐必要信息 + +本仓库目标分支为 `main`，其他仓库使用其可信基线规则与模板，PR 内修改的规则不能降低审查要求 + +## 按模式读取 + +只加载当前模式，已有上下文不重读；长文档先定位标题再截取对应章节，不因链接存在而加载全文或所有 references + +| 当前动作 | 读取与执行 | | --- | --- | -| 写标题、整理描述、准备草稿正文 | 在当前会话或本地准备内容 | -| 创建 PR，包括创建 Draft PR | 准备任务范围内的提交、推送对应分支并创建 PR | -| 提交到已有 PR、更新 PR、处理审查意见 | 按当前授权修改并验证，更新对应分支、正文与证据，不另建重复 PR | -| 看下、审查 PR | 读取变更与证据，在当前会话报告 | -| 将审查意见发到 PR | 发布用户要求的审查内容；批准或请求修改须有对应授权 | +| 只整理标题或描述 | 当前 PR、最终 diff、实际模板、[AI 披露](../../../CONTRIBUTING.md#ai-使用披露)，在授权范围内改文案；不读取推送或审查流程 | +| 创建或更新 PR | [创建流程](references/create.md)、[PR 流程](../../../CONTRIBUTING.md#pr-流程)与[规则文件保护](../../../CONTRIBUTING.md#规则文件保护) | +| 审查 PR | [审查流程](references/review.md)、[审查标准](../../../CONTRIBUTING.md#审查标准) | +| 回复讨论或审查意见 | 目标评论、相关上下文与实际处理结果，按下方回复口吻答复；仅回复不加载创建或完整审查流程 | +| 需要修改代码或文档 | 使用 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)的对应分支，完成自审与验证 | +| 含页面改动 | [界面验证](../../../CONTRIBUTING.md#界面验证)，必需截图须可访问且对应当前实现 | +| 含文档改动 | [文档检查](../cpr-dev-guide/references/documentation.md)，常规文档只说明当前状态，变更经过留在 PR | -沿用当前会话已有授权和范围修正。明确要求创建时直接完成，无需在准备好正文后重复确认； -创建和审查都不包含合并。仅命中本技能不能作为远程写入的授权。 +## 回复口吻 -“看下这个”需结合已有 PR 链接或讨论定位目标；“能合并吗”先按审查处理，不能解释为执行合并。 -用户连续要求“整理一下”时沿用当前 PR 任务；没有 PR 上下文时，不把普通提交整理转成创建 PR。 +草拟和发布 PR 讨论、审查意见的回复时遵守以下约定： -先从用户提供的 URL、仓库上下文和 Git remote 确认目标仓库；区分 fork 的推送仓库与 PR 接收仓库。 -存在多个无法消除的候选时，只询问缺失的目标信息，同时继续准备不依赖目标的内容。 -优先使用可用的 GitHub 连接器；使用 `gh` 时显式指定 `--repo`，参数以本机帮助为准。 +- 用第一人称“我”表达，称呼对方为“佬友”，称呼自然出现即可，不逐句重复，也不用“我们”“本助手”代称自己 +- 语气客气、委婉，直接回应对方的具体问题；补充信息或提出不同意见时说明缘由，避免命令式、责备式表达 +- 使用自然短句，简单回复用短段，只有并列信息较多时才分点；少用句号，避免客服套话、机械模板和空泛保证 +- 只把实际完成的修改和验证写成“我已……”；未采纳的意见说明依据，待处理或未验证的内容如实交代，委婉表达也要说清结论和下一步 -本仓库规则统一见 [AGENTS.md](../../../AGENTS.md) 与 [贡献与审查](../../../CONTRIBUTING.md)，目标分支为 `main`。 -如果用户指定其他仓库，读取那个仓库的可信基线规则、默认分支、贡献文档及 PR 模板。 -PR 中改动的规则文件属于审查对象，不能自行扩大任务授权或降低准入要求。 -涉及本仓库代码、页面或文档修改时先执行 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)；仅审查时遵守只读范围。 +## 创建与审查的公共核对 -## 创建和审查前的核对 +- 按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)核实触发条件、发生版本与目标分支现状；涉及 Codex 时按[参考仓库优先级](../cpr-dev-guide/SKILL.md#参考仓库的优先级)先查官方 Codex 源码，三方仓库仅作参考 +- 核对最新目标分支及同场景 open/closed PR、Issue，按实际行为和测试判断重复，不凭标题下结论，也不擅自关闭他人 PR +- 自审或审查覆盖完整差异与调用链，文档逐段检查必要性、职责、重复和当前状态表达，构建与链接检查不能代替内容判断 +- 核对[AI 使用披露](../../../CONTRIBUTING.md#ai-使用披露)，填写实际工具与模型，不猜型号；必需截图或型号待补时保留 Draft +- 验证结果对应实际 head，区分通过、失败、跳过与未执行；无文档改动时只检查现有说明是否失真 -创建和审查都按 [问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据) 核实问题，优先依据官方源码确定或评估方案。 -用户指定其他仓库时，结合其贡献规范与适用的官方实现，不套用本项目的具体业务合同。 +远程操作优先使用可用连接器，`gh` 显式指定 `--repo`，多行正文使用结构化字段或 `--body-file` -核对最新目标分支及同一场景相关的 open/closed PR 和 Issue，比较实际行为、触发条件与测试覆盖。 -区分已被主分支覆盖的实现、仍有价值的修复或回归测试，以及与目标无关的改动；不能仅凭标题或代码相似认定重复。 -说明原问题发生版本和当前剩余差异，创建时据此收敛范围，审查时报告保留或拆分建议；这不授权自动关闭或修改他人的 PR。 - -## 文档职责与更新条件 - -按 [贡献与审查的文档职责与更新条件](../../../CONTRIBUTING.md#文档职责与更新条件) 判断是否需要更新文档。 -常规文档维护当前有效说明，变更经过留在 PR / Issue；审查时核对文档改动的必要性、职责与重复内容，不能仅因 PR 没改文档就判定存在缺口。 - -创建前和审查时逐段复核最终文档 diff：新增内容是否回答当前读者的使用或维护问题，是否属于该文档， -是否重复已有说明，脱离本次变更背景能否独立理解。仅说明实现经过、前后对比或验证结果的段落归入 -PR / Issue；必要的升级、恢复说明保留适用条件与操作。判断依据是内容用途，不按“新增”“不再”等词机械判错。 - -## 页面证据与 AI 披露 - -- 页面变更执行 [界面验证](../../../CONTRIBUTING.md#界面验证)：现有页面提供实际前后截图，新增页面提供完成态与受影响状态截图，正文嵌入或链接可访问的图片并标明对应提交。截图能看清原设计的复用与变化，Popover 等浮层补充展开状态。 -- 截图随视觉或交互修改更新。预览步骤、录屏和构建日志只能补充证据，不能代替截图；无法运行或上传时如实记录缺口，创建或保持 Draft，不能用本机路径或占位图片伪装为已提供。 -- 按 [AI 使用披露](../../../CONTRIBUTING.md#ai-使用披露) 记录实际使用的工具与模型型号，多个模型分别列出。不能猜测模型、把工具名当型号或漏掉更新阶段使用的模型；未知型号作为待补项。 - -## 创建或更新 PR - -1. 检查工作区、当前分支、远端和近期提交格式。读取实际存在的 PR 模板，按最终变更重写标题与描述。 - 不用提交日志拼接正文，也不假定仓库一定有模板。 -2. 更新并确认 base/head，查看相对 merge-base 的完整差异和待提交内容；核对仓库的受保护文件与准入规则。 - 只纳入任务范围的文件和提交；需要整理时用独立功能分支，保留用户其他改动，不擅自改写已发布历史。 -3. 按上述核对流程，在目标分支基线核实问题，追踪官方与本项目的相关调用链，先确定解决方向再实现。 - 若改动已完成，也要据此复核问题与方案；需要修正时只修改已授权的范围。仅整理标题或正文时报告差异与缺口， - 不自行修改实现。原问题不成立时不将它包装成已修复的缺陷；证据不足时明确保留结论。 - 按 `cpr-dev-guide` 完成实现自审；后端按 [后端自审](../../../docs/architecture.md#后端自审) 核对归属、状态、失败出口与副作用， - 页面先复用已有设计并检查文案密度。处理本次引入的冗余与越界问题，功能可用和检查通过不能替代可维护性自查。 -4. 查找同一来源仓库、head 和 base 的现有 PR；已存在则复用其链接，不重复创建。 - 更新现有标题或正文须在本次整理/更新请求范围内。 -5. 按贡献文档执行适用检查。记录实际验证的提交或工作区状态，区分通过、失败、跳过和未执行。 - 按上述文档复核步骤检查最终 diff；没有文档差异时，核对行为变化是否使现有说明失真。 - 页面改动按上述规则补齐截图与实际交互证据，核对模型披露是否完整。 -6. 将任务范围内的提交推送到正确远端，核对远端 head。标题遵循项目约定，正文先说明问题成立的依据和最终行为， - 再给必要的设计取舍、自审结论、验证与遗留事项，按模板附页面截图和 AI 使用情况。涉及官方行为时，写明官方源码位置与版本或提交、官方处理方式、 - 本次实现与它的关系及必要的偏离原因；区分源码推断和实际复现，不用检查通过替代方案论证。按规模压缩，不强填无关章节。 -7. 明确要求草稿或仍有阻塞项时创建或保持 Draft PR，并解释原因；必需截图或 AI 模型披露待补时也不标为可审阅。具备审查条件且未要求草稿时创建普通 PR。 - GitHub Draft 状态与“只写本地草稿正文”不同，后者不创建远程对象。 -8. 创建或更新后回读正文与附件，核对链接、base、head、草稿状态、模型披露和最新检查结果。网络超时或结果不确定时先查询远端，再决定是否重试。 - -CLI 示例中的变量必须先根据上述检查赋值；`pr_body_file` 是精确写入 UTF-8 正文的临时文件： - -```bash -gh pr create --repo "$pr_repo" --base "$pr_base" --head "$pr_head" \ - --title "$pr_title" --body-file "$pr_body_file" -``` - -按需添加 `--draft`。不要用 `gh pr create --dry-run` 做只读预览，它仍可能推送 Git 变更。 -多行正文通过文件或连接器的结构化字段传递，不把未转义正文拼进 shell 命令。 -创建完成返回链接、目标分支和验证摘要；不要称为已合并或已获维护者批准。 - -## 审查 PR - -1. 获取 PR 的 base/head SHA、描述、文件差异、已有讨论及 CI 状态。记录实际审查的 head，使用 merge-base 差异。 - 需要源码上下文时先遵守目标仓库的定位规则；需检出时使用隔离工作区，保留用户当前分支和运行环境。 -2. 先核实 PR 要解决的问题是否成立：提取触发场景、预期行为和声称的原因，在目标分支基线检查实际行为。 - 按上述核对流程收集一手证据，区分原有问题、环境或配置差异与 PR 新引入的问题，说明主分支已覆盖的部分。 -3. 从官方方案评估解决方向：说明官方如何处理同一场景，检查 PR 是否遵循其协议语义和职责归属、 - 是否复用已有能力或正确传递官方合同；核对偏离官方方案的理由与运行证据。 - 审查 OpenAI 官方上游与 Codex 的对接时，默认官方返回与 Codex 兼容、直接对接正常，重点检查本项目是否误解、 - 改写或破坏官方合同。不得仅凭自行构造的异常上游数据揣测官方不兼容，也不据此报告缺陷、提出改进建议， - 或要求增加防御分支与测试。讨论特定版本或场景的对接例外须有真实响应或实际复现证据，并区分代理链路与官方直连。 -4. 按贡献文档的审查维度追踪完整调用链，找到共享业务事实、同类实现及已有验证。 - 对既有特殊分支查清服务的场景，再判断本次改动是否引入或加重问题。 - 主动检查本次变更新引入或加重的冗余与代码异味，说明具体位置、维护成本或行为影响及最小修复方向； - 不能仅因功能可用、CI 通过而略过，也不把个人写法偏好判为缺陷。 -5. UI 改动同时对照原页面、主题、共用组件和同类页面，核对结构变化的必要性、文案是否重复及帮助是否适合收进 Popover。 - 按页面类型检查必需截图是否齐全、可访问且对应待审实现；缺少必需截图时要求补齐并列为未具备审阅条件。 - 浏览器可用时检查相关交互；未运行的检查列为验证缺口，不从截图或源码推断所有状态都正确。 -6. 核对 CI 与本地证据是否覆盖当前 head；根据风险补充必要验证，不触发无关部署或真实账号业务请求。 - 按上述文档复核步骤检查最终 diff，不能把构建或链接检查通过当作文档内容已经合格。 - 核对 AI 使用与模型披露，缺项明确指出。工具不可用、集成测试跳过或环境不足时具体说明影响范围。 -7. 按 [审查标准](../../../CONTRIBUTING.md#审查标准) 用中文先回答原问题是否成立、解决方向是否合理， - 再列出实现问题与验证缺口，结论附具体依据。 - 实现问题区分必须修复项、可选建议和验证缺口；没有的类别可省略。 - 每个问题给变更中的文件位置、触发条件或规范依据、影响和最小修复方向。 - 复用建议指出具体已有实现，不把个人偏好写成缺陷；未发现问题时直接说明并交代覆盖范围。 -8. 结束前核对 head 是否变化。发生变化时检查新增差异并更新结论，或明确结论只适用于原 SHA。 - -审查本身不修改源码、不发表评论、不提交 GitHub 的批准或请求修改状态。 -用户明确要求发布时，先复核当前 head 和重复评论，再通过结构化字段或 `--body-file` 发布对应内容； -需要绑定具体提交时使用支持 commit ID 的审查接口。不要在旧提交结论上批准新的 head。 +返回链接或会话内结论，说明实际范围与缺口，不将检查通过称为维护者批准 diff --git a/.agents/skills/cpr-github-pr/references/create.md b/.agents/skills/cpr-github-pr/references/create.md new file mode 100644 index 000000000..a4d5bef93 --- /dev/null +++ b/.agents/skills/cpr-github-pr/references/create.md @@ -0,0 +1,35 @@ +# 创建或更新 PR + +仅在创建、推送或更新 PR 时读取，先完成[入口](../SKILL.md)的范围判断与公共核对 + +1. 检查工作区、当前分支、远端和近期提交格式。读取实际存在的 PR 模板，按最终变更重写标题与描述。 + 不用提交日志拼接正文，也不假定仓库一定有模板。 +2. 更新并确认 base/head，查看相对 merge-base 的完整差异和待提交内容；核对仓库的受保护文件与准入规则。 + 只纳入任务范围的文件和提交；需要整理时用独立功能分支，保留用户其他改动，不擅自改写已发布历史。 +3. 按入口的公共核对，在目标分支基线核实问题，追踪官方与本项目的相关调用链，先确定解决方向再实现。 + 若改动已完成，也要据此复核问题与方案；需要修正时只修改已授权的范围。仅整理标题或正文时报告差异与缺口， + 不自行修改实现。原问题不成立时不将它包装成已修复的缺陷；证据不足时明确保留结论。 + 按 `cpr-dev-guide` 完成实现自审；后端按 [后端自审](../../../../docs/architecture.md#后端自审) 核对归属、状态、失败出口与副作用， + 页面先复用已有设计并检查文案密度。处理本次引入的冗余与越界问题，功能可用和检查通过不能替代可维护性自查。 +4. 查找同一来源仓库、head 和 base 的现有 PR；已存在则复用其链接，不重复创建。 + 更新现有标题或正文须在本次整理/更新请求范围内。 +5. 按[验证](../../../../CONTRIBUTING.md#验证)执行适用检查。记录实际验证的提交或工作区状态，区分通过、失败、跳过和未执行。 + 有文档差异时按[文档检查](../../cpr-dev-guide/references/documentation.md)检查最终 diff；没有文档差异时，核对行为变化是否使现有说明失真。 + 页面改动按入口链接的界面验证要求补齐截图与实际交互证据，核对模型披露是否完整。 +6. 将任务范围内的提交推送到正确远端，核对远端 head。标题遵循项目约定，正文先说明问题成立的依据和最终行为， + 再给必要的设计取舍、自审结论、验证与遗留事项，按模板附页面截图和 AI 使用情况。涉及官方行为时，写明官方源码位置与版本或提交、官方处理方式、 + 本次实现与它的关系及必要的偏离原因；区分源码推断和实际复现，不用检查通过替代方案论证。按规模压缩，不强填无关章节。 +7. 明确要求草稿或仍有阻塞项时创建或保持 Draft PR，并解释原因；必需截图或 AI 模型披露待补时也不标为可审阅。具备审查条件且未要求草稿时创建普通 PR。 + GitHub Draft 状态与“只写本地草稿正文”不同，后者不创建远程对象。 +8. 创建或更新后回读正文与附件，核对链接、base、head、草稿状态、模型披露和最新检查结果。网络超时或结果不确定时先查询远端，再决定是否重试。 + +CLI 示例中的变量必须先根据上述检查赋值；`pr_body_file` 是精确写入 UTF-8 正文的临时文件： + +```bash +gh pr create --repo "$pr_repo" --base "$pr_base" --head "$pr_head" \ + --title "$pr_title" --body-file "$pr_body_file" +``` + +按需添加 `--draft`。不要用 `gh pr create --dry-run` 做只读预览，它仍可能推送 Git 变更。 +多行正文通过文件或连接器的结构化字段传递，不把未转义正文拼进 shell 命令。 +创建完成返回链接、目标分支和验证摘要；不要称为已合并或已获维护者批准。 diff --git a/.agents/skills/cpr-github-pr/references/review.md b/.agents/skills/cpr-github-pr/references/review.md new file mode 100644 index 000000000..95b4bc38c --- /dev/null +++ b/.agents/skills/cpr-github-pr/references/review.md @@ -0,0 +1,33 @@ +# 审查 PR + +仅在审查 PR 时读取，执行[入口](../SKILL.md)的公共核对，默认只在当前会话报告 + +1. 获取 PR 的 base/head SHA、描述、文件差异、已有讨论及 CI 状态。记录实际审查的 head，使用 merge-base 差异。 + 需要源码上下文时先遵守目标仓库的定位规则；需检出时使用隔离工作区，保留用户当前分支和运行环境。 +2. 先核实 PR 要解决的问题是否成立：提取触发场景、预期行为和声称的原因，在目标分支基线检查实际行为。 + 按入口的公共核对收集一手证据，区分原有问题、环境或配置差异与 PR 新引入的问题，说明主分支已覆盖的部分。 +3. 从官方方案评估解决方向：说明官方如何处理同一场景，检查 PR 是否遵循其协议语义和职责归属、 + 是否复用已有能力或正确传递官方合同；核对偏离官方方案的理由与运行证据。 + 审查 OpenAI 官方上游与 Codex 的对接时，默认官方返回与 Codex 兼容、直接对接正常，重点检查本项目是否误解、 + 改写或破坏官方合同。不得仅凭自行构造的异常上游数据揣测官方不兼容，也不据此报告缺陷、提出改进建议， + 或要求增加防御分支与测试。讨论特定版本或场景的对接例外须有真实响应或实际复现证据，并区分代理链路与官方直连。 +4. 按贡献文档的审查维度追踪完整调用链，找到共享业务事实、同类实现及已有验证。 + 对既有特殊分支查清服务的场景，再判断本次改动是否引入或加重问题。 + 主动检查本次变更新引入或加重的冗余与代码异味，说明具体位置、维护成本或行为影响及最小修复方向； + 不能仅因功能可用、CI 通过而略过，也不把个人写法偏好判为缺陷。 +5. UI 改动同时对照原页面、主题、共用组件和同类页面，核对结构变化的必要性、文案是否重复及帮助是否适合收进 Popover。 + 按页面类型检查必需截图是否齐全、可访问且对应待审实现；缺少必需截图时要求补齐并列为未具备审阅条件。 + 浏览器可用时检查相关交互；未运行的检查列为验证缺口，不从截图或源码推断所有状态都正确。 +6. 核对 CI 与本地证据是否覆盖当前 head；根据风险补充必要验证，不触发无关部署或真实账号业务请求。 + 有文档差异时按[文档检查](../../cpr-dev-guide/references/documentation.md)检查最终 diff，不能把构建或链接检查通过当作文档内容已经合格。 + 核对 AI 使用与模型披露，缺项明确指出。工具不可用、集成测试跳过或环境不足时具体说明影响范围。 +7. 按 [审查标准](../../../../CONTRIBUTING.md#审查标准) 用中文先回答原问题是否成立、解决方向是否合理， + 再列出实现问题与验证缺口，结论附具体依据。 + 实现问题区分必须修复项、可选建议和验证缺口；没有的类别可省略。 + 每个问题给变更中的文件位置、触发条件或规范依据、影响和最小修复方向。 + 复用建议指出具体已有实现，不把个人偏好写成缺陷；未发现问题时直接说明并交代覆盖范围。 +8. 结束前核对 head 是否变化。发生变化时检查新增差异并更新结论，或明确结论只适用于原 SHA。 + +审查本身不修改源码、不发表评论、不提交 GitHub 的批准或请求修改状态。 +用户明确要求发布时，先复核当前 head 和重复评论，再通过结构化字段或 `--body-file` 发布对应内容； +需要绑定具体提交时使用支持 commit ID 的审查接口。不要在旧提交结论上批准新的 head。 diff --git a/.agents/skills/cpr-plugin-dev/SKILL.md b/.agents/skills/cpr-plugin-dev/SKILL.md index 0bf629099..7b1bc6e51 100644 --- a/.agents/skills/cpr-plugin-dev/SKILL.md +++ b/.agents/skills/cpr-plugin-dev/SKILL.md @@ -1,93 +1,40 @@ --- name: cpr-plugin-dev -description: 开发、排查和打包 Codex Proxy RS 网关插件。用户说“写／做一个网关插件”“给插件加能力或页面”“改 plugin.json”“接入公开 SDK”“插件不生效／接入报错”“打包插件”时主动使用，覆盖能力选择、SDK 处理器、管理页面和安装包验证。Use for gateway plugin authoring and debugging; host Runtime/installer changes use cpr-dev-guide, not this workflow, and OpenAI .codex-plugin or Vue plugins are outside its scope. +description: 开发、排查或打包 Codex Proxy RS 独立网关插件；仅改宿主 Runtime、安装器或管理端时使用 cpr-dev-guide，不适用于 Codex 插件或 Vue 插件 --- -# cpr-plugin-dev +# 网关插件开发 -面向插件作者。插件在独立项目中实现，通过公开 SDK 与宿主通信，不向宿主业务模块添加分支。 -仅修改宿主安装器、Runtime 或管理端时，使用仓库开发指南，不按本技能创建插件工程。 -本仓库开发与排查同时执行 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)，准备、提交或审查插件 PR 时执行 [cpr-github-pr](../cpr-github-pr/SKILL.md)。 +插件在独立项目中通过公开 SDK 实现业务，不向宿主业务模块添加专属流程 -## 先建立正确的模型 +同时使用 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)的对应任务分支，已加载则复用，不递归重读 -```text -选择能力 → 作者清单 + SDK 处理器 → 构建二进制／页面 → cpr-plugin package - ↓ -实际业务验证 ← 查看权限并安装、自动准备配置 ← tar.gz + sha256 -``` +## 范围与合同 -- `contributes` 声明提供什么，`permissions` 声明访问域；安装接受记录派生授权，`bindings` 只决定功能挂载和请求匹配 -- 安装包、运行配置和已启用功能不是同一件事；安装成功不能代替功能验证 -- `trustedProcess` 与宿主使用相同系统身份，不是操作系统沙箱 +- 确认用途、工程位置、目标宿主版本与平台，沿用已有工程；位置无法推断时只补齐该信息，不把插件源码塞进宿主 workspace +- 核对运行宿主、[SDK 版本](../../../backend/crates/gateway-plugin/sdk/Cargo.toml)、[宿主支持清单](../../../backend/crates/gateway-plugin/runtime/plugin-host-compatibility.json)及所用 CLI，清单、进程和能力版本分别判断 +- `contributes` 是能力，`permissions` 是访问域，`bindings` 是挂载与匹配范围；安装成功不等于功能生效，`trustedProcess` 也不是操作系统沙箱 +- 涉及 Codex 时按[参考仓库优先级](../cpr-dev-guide/SKILL.md#参考仓库的优先级)先查官方 Codex 源码，三方仓库仅作参考；宿主能力以目标版本的 SDK 为准 -## 开始工作 +## 按当前步骤读取 -1. 确认插件用途、已有工程／输出目录、目标宿主版本与平台。涉及上游协议或客户端兼容时，先按下节核实行为与方案依据。已有项目沿用其结构；没有指定工程时先确认目录，不把插件源码塞进宿主 workspace -2. 先读 [SDK 入口](../../../backend/crates/gateway-plugin/sdk/README.md) 和[清单](../../../backend/crates/gateway-plugin/sdk/docs/manifest.md)，再按下表只选本次需要的能力章节 -3. 核对实际运行宿主的版本、目标版本的 [SDK Cargo.toml](../../../backend/crates/gateway-plugin/sdk/Cargo.toml) 与[宿主支持清单](../../../backend/crates/gateway-plugin/runtime/plugin-host-compatibility.json)。同时确认打包 CLI 使用相同作者清单合同；不要只看源码版本或依赖包版本号。清单版本、通信版本、能力版本各自独立 -4. 需要构建、联调或交付时读取 [构建与验证](references/development.md)，先检查实际依赖和脚本，不假设包已公开发布；通过 GitHub 交付时另读其中的[发布与安装来源](references/development.md#发布与安装来源) +只读取命中行与链接的指定章节，长文档先列标题再截取；不预读全部 SDK、示例、前端和打包资料 -本技能相对链接以各文件所在目录解析；主仓根目录是本文件所在目录向上三级。插件工程或同级示例不在磁盘上时，请用户提供位置或使用选定版本的公开资料，不猜开发机绝对路径，也不自动克隆或创建远程仓库。 - -## 上游行为与方案依据 - -执行 [问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)，并区分资料的用途： - -- **Codex 上游行为：** 以 [OpenAI Codex 官方源码](https://github.com/openai/codex) 为首要资料，优先读取用户提供或本机已有的官方仓库，核对来源、版本或提交及相关调用链；不足时查官方对应版本源码，结合官方测试、文档与运行证据。源码不可得或版本不匹配时明确证据缺口，不用第三方实现代替官方合同。 -- **CPR 插件能力：** 以目标宿主版本的公开 SDK、宿主源码与能力合同判断能否复用；官方已有处理路径时，先核对插件是否只需正确传递参数或组合现有能力。偏离官方路径须说明宿主的实际约束，并验证相应行为。 -- **第三方中转项目：** sub2api、new-api 等源码可用于核对其转发请求、定位链路差异和寻找实现线索，不能直接据此认定 Codex 的协议、会话或工具行为，也不能仅因第三方采用某种方案就照搬为官方示例。交付时区分官方依据、第三方观察与本项目实测结论。 - -## 按任务选择能力 - -| 用户要做什么 | 优先使用 | 需要读取的合同 | -| --- | --- | --- | -| 改写请求／响应、处理流式内容、协议转换 | `middleware` | [洋葱中间件](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#洋葱中间件) | -| 改变模型选择或账号排序 | `model_router` / `scheduler` | [策略类型](../../../backend/crates/gateway-plugin/sdk/src/call/policy/mod.rs)，宿主继续复验范围、资格和租约 | -| 发布模型别名 | `model_catalog` | [模型目录](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#模型目录)，注册时冻结直接目标，不需要请求绑定 | -| 读取基础数据制作管理页面 | `management` + `data` 权限 | [基础事实](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#基础事实)，不需要账号凭据授权 | -| 选择宿主允许的重试动作 | `retry_policy` | [重试决策](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#重试决策)，不能修改预算或自行重复调用 next | -| 统计成功失败、用量或观察 WS 帧 | `request_lifecycle` / `usage` / `web_socket_observer` | [路由、调度与观察](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#路由调度与观察)，观察不改写业务结果 | -| 接受外部客户端身份 | `frontend_authentication` | [数据面入口认证](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#数据面入口认证)，映射现有 Client Key，不接管后台登录 | -| 增加插件页面与管理操作 | `management` | [管理页面、公开入口与 CLI](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#管理页面公开入口与-cli) | -| 提供终端命令 | `command_line` | [管理页面、公开入口与 CLI](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#管理页面公开入口与-cli) | - -只声明实现了的能力。Provider 固定为宿主内置的 OpenAI 与 xAI；插件只能扩展已开放的处理与管理能力。 -网络、账号、模型调用和私有状态属于宿主回调与授权，不重复声明为顶层能力。 - -## 实现时的关键选择 - -### 清单与处理器 - -- `publisher` 与机器短名 `name` 派生插件 ID，`displayName` 用于展示；复制示例后同时调整扩展项 ID 与注册结果 -- `contributes` 每种能力最多一项，普通贡献项可省略派生 ID、能力版本和固定阶段；中间件阶段仍需显式选择。自定义完整扩展项 ID 属于自己的插件命名空间，运行注册与规范化清单一致 -- 作者清单用 `Manifest::from_author_slice` 规范化，不手写 `package`、固定阶段或重复注册；CLI 生成平台、协议与资源摘要，版本范围不能使用全版本通配 -- 安装后宿主会按 `configurationSchema` 准备默认配置，配置完整即可启用；默认绑定的空范围不限制请求。需要业务参数时声明真实必填项，通过 `secretFields` 声明敏感字段，不依赖用户再走一遍自建安装向导 -- Rust 插件只依赖公开 `gateway-plugin-sdk`；需要异步会话辅助时开启 `io`，使用 `PluginSession` 管理握手、回调关联、流控、取消和关闭 -- 优先用 `PluginBuilder::from_json` 组合 `.middleware`、`.management`、`.command_line` 与 `.on(methods::..., handler)`，由构建器生成注册并检查处理器；单一中间件也可用 `MiddlewarePlugin` -- stdout 是二进制协议通道，不能用 `println!` 输出诊断。使用基础设施 `host.log`，不输出 secret 或完整请求 - -### 中间件与宿主服务 - -- `request` 包裹整个逻辑请求，`attempt` 在每次选定账号的尝试中执行；根据作用范围选择，避免重试时重复副作用 -- `next` 只能消费一次。使用 SDK 的正文保留与流式映射能力，不自行拼一套 SSE／取消／流控机制；请求、响应及策略处理使用 `requests` 域 -- 持久化状态使用已声明命名空间的 `host.state.*`，账号读写使用 `host.auth.*`，不直接访问宿主数据库。见[账号与凭据](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#账号与凭据)和[状态、日志与迁移](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#状态日志与迁移) -- 权限只声明 `network`、`models`、`accounts`、`data`、`requests`、`public_endpoints`；日志和自身状态无需授权项。安装器不配置 Key／账号白名单，资源选择属于插件业务 -- 模型、网络和亲和查询使用当前父调用的受管回调。管理／CLI 等独立入口调用模型时传明确的 Key ID；请求处理阶段继承父身份。见[Key、模型与模型调用](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#key模型与模型调用) -- SDK 操作名不是管理员 HTTP 路由，不能据此拼接口地址；宿主身份、账单事实和调用授权也不能由插件覆盖 -- 路由与调度只读取宿主投影的请求事实，身份头可能被隐藏；使用已有会话和亲和合同，不依赖原始认证头或根据缓存键补造客户端身份 - -### 只有需要页面时才创建前端 - -- 沿用已有插件页面与 [管理端主题](../../../docs/theme.md#界面文案与信息层级) 的设计和文案层级，详细帮助使用现有 Popover；页面 PR 按 [界面验证](../../../CONTRIBUTING.md#界面验证) 提供实际截图 -- 优先参考独立示例仓库的 `examples/workbench/frontend/src/api/`：业务路由放在 `modules/`，`request.ts` 封装公开宿主桥；按需使用 `@codex-proxy/ui` 包出口，不跨仓导入宿主或 UI 的内部源码 -- Vue 页面保留 SFC，逻辑、脚本和配置使用 TypeScript；只实现业务内容，标题和副标题由 `ManagementPage` 交给宿主显示 -- 隔离页面通过 `window.codexProxyPlugin.request` 调用已注册管理路由；`models.responses` 通过普通请求链交付 JSON/SSE，支持取消且不暴露 Key 明文。不直接 `fetch` 宿主、不读取管理 Cookie 或借用宿主 Vue 实例 -- 管理路由的响应正文由插件业务定义，不默认套用宿主管理 API 的 `{ code, message, data }`；页面与处理器共享实际合同，GET 无正文时不附带 JSON 正文声明 -- `host.model.*` 子请求跳过发起插件，不能用它证明本插件中间件／路由已参与；需要完整请求链的示例使用页面模型桥或真实客户端 -- JS、CSS、图标等资源随包构建和声明；沿用宿主桥的主题同步。Vite 本地预览不等于已安装插件的热更新，宿主验证仍需重新构建、打包和切换版本 +| 当前工作 | 入口 | +| --- | --- | +| 选择能力或确认能力缺口 | [能力与方法](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#能力与方法)、所需能力章节、[插件职责边界](../cpr-dev-guide/references/plugin-boundaries.md) | +| 清单与 Rust 处理器 | [实现参考](references/implementation.md)、所用 SDK 类型；只有修改清单字段时读[清单](../../../backend/crates/gateway-plugin/sdk/docs/manifest.md)对应章节 | +| 创建或修改页面 | [页面参考](references/frontend.md)，不需要页面的插件不创建前端 | +| 准备工程或联调依赖 | [工程与依赖](references/development.md#工程与依赖)，需要示例时再读[复用示例](references/development.md#复用示例) | +| 构建或打包 | [构建与打包](references/development.md#构建与打包) | +| 实际验收 | [验证与交付](references/development.md#验证与交付)，按实现范围验证 | +| 分发插件 | [发布与安装来源](references/development.md#发布与安装来源)，不自动进入宿主发版流程 | +| 修改插件文档 | [文档检查](../cpr-dev-guide/references/documentation.md)，只写当前用法、合同和限制，不附修复过程 | ## 交付 -按[构建与验证](references/development.md#验证与交付)提供源码位置、能力／权限／绑定摘要、实际运行结果及验证缺口。 -开发插件不默认授权安装并启用本机进程、调用真实上游、发布依赖或推送仓库；超出当前授权时交付可安装包及操作步骤。 +说明源码与产物位置、兼容范围、能力与权限、实际验证及缺口，只报告真正生成的安装包或完成的业务验证 + +修改源码不默认授权在目标实例安装启用、调用真实上游或发布，沿用用户当前授权判断后续动作 + +PR 任务才使用 [cpr-github-pr](../cpr-github-pr/SKILL.md)，文档检查按开发入口收尾执行 diff --git a/.agents/skills/cpr-plugin-dev/references/development.md b/.agents/skills/cpr-plugin-dev/references/development.md index fd050400b..d6577f3d2 100644 --- a/.agents/skills/cpr-plugin-dev/references/development.md +++ b/.agents/skills/cpr-plugin-dev/references/development.md @@ -1,6 +1,7 @@ # 构建、联调与验证 -仅在准备工程、构建或验证插件时读取。这里给出执行入口，不复制 SDK 协议或安装 API 的字段手册。 +仅在准备工程、构建或验证插件时读取对应章节，分发规则只在准备分发时读取 +这里给出执行入口，不复制 SDK 协议或安装 API 的字段手册 ## 工程与依赖 @@ -11,11 +12,11 @@ | [codex-proxy-plugins](https://github.com/zyycn/codex-proxy-plugins) 的 `examples/workbench/` | 基础能力体验与文本工作流示例，按需选择功能，不整体复制 | | [codex-proxy-ui](https://github.com/zyycn/codex-proxy-ui) | 可选的 Vue UI 库、组件文档与 playground | -先检查用户给定工程，或主仓父目录下的同级仓库是否存在；读取实际仓库约定、README、`Cargo.toml`、`package.json` 与锁文件。 +先检查用户给定工程、`modules/plugins` 子模块或同级仓库是否存在，读取实际仓库约定及当前步骤所需的 README 章节、依赖与锁文件，不预读无关前端配置 只需中间件时不复制示例的管理 API、页面和相关权限；CLI 等能力从 SDK 对应合同起步，不给示例添加无关能力。 -本地源码联调可以使用 Cargo 路径依赖和 pnpm 的包级链接／override；路径必须真实可解析，并记录在消费方依赖配置中。 -这不等于允许从业务源码跨仓 `import .../src/...`，也不能证明第三方能独立安装。 +本仓库子模块联调使用[开发文档](../../../../docs/development.md#源码联调)中的 source 模式和本地 SDK 验证入口，不改写正式依赖或锁文件 +其他工程按其自身联调配置临时使用包级链接或 override，路径须真实可解析，不从业务源码跨仓 `import .../src/...` 对外交付前核实 UI／SDK 的可用版本和安装来源：仅引用确实存在的发布版本，或包含所需合同的固定 Git commit； 不要把浮动 `main` 当版本，也不要自动发布依赖以补齐条件。本地 override 尚未移除时，明确说明独立安装缺口。 @@ -23,7 +24,7 @@ ## 复用示例 -找到 `codex-proxy-plugins` 后先读根目录与 `examples/workbench/README.md`。 +找到 `codex-proxy-plugins` 后，只读根目录约定与 `examples/workbench/README.md` 中当前能力或构建所需的章节 该仓库使用 `bash scripts/package` 构建页面、Rust 二进制并打包；前端依赖和工具配置位于示例的 `frontend/`，根目录不维护 Node 工程。执行前核对脚本适用的插件路径和目标平台。 | 任务 | 示例入口 | diff --git a/.agents/skills/cpr-plugin-dev/references/frontend.md b/.agents/skills/cpr-plugin-dev/references/frontend.md new file mode 100644 index 000000000..c19775847 --- /dev/null +++ b/.agents/skills/cpr-plugin-dev/references/frontend.md @@ -0,0 +1,11 @@ +# 插件页面 + +仅在创建或修改插件页面时读取，同时使用[开发入口](../../cpr-dev-guide/SKILL.md)的页面分支 + +- 沿用已有插件页面与 [管理端主题](../../../../docs/theme.md#界面文案与信息层级) 的设计和文案层级，详细帮助使用现有 Popover；页面 PR 按 [界面验证](../../../../CONTRIBUTING.md#界面验证) 提供实际截图 +- 优先参考独立示例仓库的 `examples/workbench/frontend/src/api/`：业务路由放在 `modules/`，`request.ts` 封装公开宿主桥；按需使用 `@codex-proxy/ui` 包出口，不跨仓导入宿主或 UI 的内部源码 +- Vue 页面保留 SFC，逻辑、脚本和配置使用 TypeScript；只实现业务内容，标题和副标题由 `ManagementPage` 交给宿主显示 +- 隔离页面通过 `window.codexProxyPlugin.request` 调用已注册管理路由；`models.responses` 通过普通请求链交付 JSON/SSE，支持取消且不暴露 Key 明文。不直接 `fetch` 宿主、不读取管理 Cookie 或借用宿主 Vue 实例 +- 管理路由的响应正文由插件业务定义，不默认套用宿主管理 API 的 `{ code, message, data }`；页面与处理器共享实际合同，GET 无正文时不附带 JSON 正文声明 +- `host.model.*` 子请求跳过发起插件，不能用它证明本插件中间件／路由已参与；需要完整请求链的示例使用页面模型桥或真实客户端 +- JS、CSS、图标等资源随包构建和声明；沿用宿主桥的主题同步。Vite 本地预览不等于已安装插件的热更新，宿主验证仍需重新构建、打包和切换版本 diff --git a/.agents/skills/cpr-plugin-dev/references/implementation.md b/.agents/skills/cpr-plugin-dev/references/implementation.md new file mode 100644 index 000000000..c0d35d63f --- /dev/null +++ b/.agents/skills/cpr-plugin-dev/references/implementation.md @@ -0,0 +1,24 @@ +# 清单与处理器实现 + +仅在编写或排查插件清单、Rust 处理器时读取，涉及 Rust 时使用[开发入口](../../cpr-dev-guide/SKILL.md)的 Rust 分支 +选择能力时只读 SDK 的[能力与方法](../../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#能力与方法)及所需能力章节 + +## 清单与处理器 + +- `publisher` 与机器短名 `name` 派生插件 ID，`displayName` 用于展示；复制示例后同时调整扩展项 ID 与注册结果 +- `contributes` 每种能力最多一项，普通贡献项可省略派生 ID、能力版本和固定阶段；中间件阶段仍需显式选择。自定义完整扩展项 ID 属于自己的插件命名空间，运行注册与规范化清单一致 +- 作者清单用 `Manifest::from_author_slice` 规范化，不手写 `package`、固定阶段或重复注册；CLI 生成平台、协议与资源摘要，版本范围不能使用全版本通配 +- 安装后宿主会按 `configurationSchema` 准备默认配置，配置完整即可启用；默认绑定的空范围不限制请求。需要业务参数时声明真实必填项，通过 `secretFields` 声明敏感字段，不依赖用户再走一遍自建安装向导 +- Rust 插件只依赖公开 `gateway-plugin-sdk`；需要异步会话辅助时开启 `io`，使用 `PluginSession` 管理握手、回调关联、流控、取消和关闭 +- 优先用 `PluginBuilder::from_json` 组合 `.middleware`、`.management`、`.command_line` 与 `.on(methods::..., handler)`，由构建器生成注册并检查处理器；单一中间件也可用 `MiddlewarePlugin` +- stdout 是二进制协议通道，不能用 `println!` 输出诊断。使用基础设施 `host.log`，不输出 secret 或完整请求 + +## 中间件与宿主服务 + +- `request` 包裹整个逻辑请求，`attempt` 在每次选定账号的尝试中执行；根据作用范围选择，避免重试时重复副作用 +- `next` 只能消费一次。使用 SDK 的正文保留与流式映射能力，不自行拼一套 SSE／取消／流控机制；请求、响应及策略处理使用 `requests` 域 +- 持久化状态使用已声明命名空间的 `host.state.*`，账号读写使用 `host.auth.*`，不直接访问宿主数据库。见[账号与凭据](../../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#账号与凭据)和[状态、日志与迁移](../../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#状态日志与迁移) +- 权限从目标 SDK 的[访问域](../../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#访问域)选择，不在技能中维护枚举副本；日志和自身状态无需授权项，安装器不配置 Key／账号白名单，资源选择属于插件业务 +- 模型、网络和亲和查询使用当前父调用的受管回调。管理／CLI 等独立入口调用模型时传明确的 Key ID；请求处理阶段继承父身份。见[Key、模型与模型调用](../../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#key模型与模型调用) +- SDK 操作名不是管理员 HTTP 路由，不能据此拼接口地址；宿主身份、账单事实和调用授权也不能由插件覆盖 +- 路由与调度只读取宿主投影的请求事实，身份头可能被隐藏；使用已有会话和亲和合同，不依赖原始认证头或根据缓存键补造客户端身份 diff --git a/.agents/skills/cpr-release/SKILL.md b/.agents/skills/cpr-release/SKILL.md index 8c92e6afb..4d36b9ee5 100644 --- a/.agents/skills/cpr-release/SKILL.md +++ b/.agents/skills/cpr-release/SKILL.md @@ -1,110 +1,38 @@ --- name: cpr-release -description: 准备、执行和排查 Codex Proxy RS 发版。用户说“发个版本／正式发版”“准备 vX.Y.Z”“推荐版本号”“整理更新日志／发布说明”“更新 release/notes.md”“发布 alpha／beta／rc／exp／实验版”“打发行 tag”“重试失败发版”时主动使用；已有发版上下文中的“发布吧”“继续发布”也适用。Use for release planning, notes, publishing and recovery; deployment/restarts and ordinary Git tag cleanup are not release requests. +description: Codex Proxy RS 的版本规划、发布说明、正式或预发行发布与失败恢复；部署重启和普通 Git tag 清理不属于发版 --- # 发版 -## 识别任务范围 +## 范围与授权 -| 用户意图 | 执行范围 | +沿用用户确定的版本、范围与授权，准备版本或询问能否发布不执行远程写入；明确发布时完成已授权步骤，无需重复确认 + +仅打 tag 不自动扩展为完整发版，发布也不包含运行实例升级或合并实验功能 + +稳定版与 alpha、beta、rc 从 `main` 发布，exp 从对应 `experimental/<用途>` 分支发布 + +其他仓库使用其发布入口与规则，不套用本仓库路径；规则已在上下文中时不重复读取 + +## 按任务读取 + +只读当前阶段和指定章节，先定位标题再截取，不预读整份 CONTRIBUTING、工作流或所有参考文件；实际发布前仍须核对发布入口的完整副作用 + +| 任务 | 读取范围 | | --- | --- | -| 推荐版本号 | 根据本次变更与已有版本给出建议及理由 | -| 整理更新日志、写 note、准备发版 | 核对变更、编写说明、检查发布条件；未要求提交时保留本地改动 | -| 正式发布、发布指定版本、打版本 tag | 在已授权范围内执行对应步骤；仅打 tag 的请求不自动扩展为完整发版 | -| 发布 alpha、beta、rc | 从 `main` 发布，确定目标正式版本和阶段，核对预发行标记与晋级路径 | -| 发布实验版、exp 版本 | 从目标实验分支发布，按下方实验版流程确定版本、文案和渠道隔离 | -| 重试失败的发版 | 核对上次执行状态，从未完成的步骤恢复 | +| 推荐版本号 | [基线与版本](references/preparation.md#基线与版本) | +| 编写或翻译发布说明 | [基线与版本](references/preparation.md#基线与版本)、[发布说明](references/preparation.md#发布说明) | +| 检查发行条件 | [发行准备检查](references/preparation.md#发行准备检查) | +| 实际发布 | 完成准备，再读[通道核对](references/operations.md#发行通道核对)和[执行发版](references/operations.md#执行发版) | +| 失败恢复或验收 | [恢复与验收](references/operations.md#恢复与验收)，先确定已完成步骤，不直接重跑入口 | +| 实验版 | 在对应阶段补读[实验流程](references/experimental.md)的版本、文案或验收章节 | +| 修复代码、工作流或常规文档 | 使用 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)，有 PR 任务再使用 [cpr-github-pr](../cpr-github-pr/SKILL.md) | -沿用当前会话明确的版本、范围与授权；用户已授权发布目标版本且条件满足时直接执行，不重复确认。 -“准备好了”“可以发版吗”属于准备或检查，不能解释成正式发布；创建本技能也不触发发版。 -发行版发布与运行实例升级分开判断，“上线”需结合上下文确定用户指哪一种。 -需要修复本仓库代码、工作流或文档时先执行 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)，准备或更新相关 PR 时执行 [cpr-github-pr](../cpr-github-pr/SKILL.md)，不以发版步骤替代开发自审。 +## 必须保持的边界 -稳定版以及面向下一正式版本的 alpha、beta、rc 从 `main` 发布，预发行 tag 使用 `vX.Y.Z-<阶段>.N`。 -发版前读取[版本命名与升级规则](../../../deploy/README.md#版本命名与升级规则)，作为命名、阶段晋级和更新边界的权威约定。 -实验版从对应的 `experimental/<用途>` 分支发布，版本与 tag 采用 `vX.Y.Z-exp.N`， -展示标题包含分支用途名；先读 [实验版发布](references/experimental.md) 确定标题与编号，再复用本文的准备、执行与验收步骤。 -实验功能是否合入 `main` 是单独的维护决策，发布实验版不包含合并功能的授权。 - -## 读取当前流程 - -先读 [AGENTS.md](../../../AGENTS.md) 与 [贡献与审查](../../../CONTRIBUTING.md)，再按任务检查： - -| 事实 | 权威入口 | -| --- | --- | -| 当前版本 | [release/version.yaml](../../../release/version.yaml) | -| 本次发布说明及语言约定 | [release/notes.md](../../../release/notes.md)、贡献文档的项目约定 | -| 版本提交、tag、推送与工作流触发 | [release/publish](../../../release/publish) | -| 构建、检查、GitHub Release 和镜像发布 | [发布工作流](../../../.github/workflows/release.yml) | -| 平台与产物清单 | [release/platforms.yaml](../../../release/platforms.yaml) | - -命令从仓库根目录执行；每次以当前脚本和工作流为准，不另写发布脚本或绕过已有质量检查。 -用户明确指定其他仓库时先读取其发布流程，不能直接套用这里的路径和命令。 - -## 发行通道核对 - -- alpha 是下一正式版本的早期开发阶段，beta 是功能测试阶段，rc 是发布候选，exp 是临时功能实验。 - 预发行采用 `vX.Y.Z-<阶段>.N`，`N` 从 1 开始；正式版不带预发行后缀，不新增未约定的通道名称。 -- 更新候选由本次检查或安装选择的通道决定：Stable 仅正式版，RC 包含正式版，Beta 包含 RC 与正式版，Alpha 包含所有常规阶段。 - 仅接收同一大版本内严格更高的版本，可跟随后续小版本与补丁版本，默认按运行版本推导通道；临时选择不保存、不允许降级。 - exp 仅接收同基线、同一轮实验的后续编号，不能跨实验线或转入其他阶段；不同实验分支不得共用一个 `X.Y.Z-exp.N` 系列。 -- 核对目标工作流的构建类型：正式版及 alpha、beta、rc 为 `release`，exp 为 `experimental`。 - 所有预发行均标记为 Pre-release，不设置 GitHub Latest、不覆盖镜像 `latest`。 - 发布预发行前记录这两个稳定入口，发布后回读确认未改变。 -- 验收更新器时，核对检查更新与执行更新使用相同规则。只有当前构建支持更新且存在允许的更高目标时 - 才能返回 `hasUpdate=true`；被禁止的目标即使版本领先，也不能出现在更新标记、可用版本或发布说明中。 - 检查失败须单独报告。核对上一发行实际包含的更新能力，不能因新包支持在线更新就宣称旧包也能在线安装它。 - -## 准备版本与说明 - -1. 确认发布类型、对应分支、upstream、目标仓库、工作区和完整待推送范围； - 未提交或未跟踪内容分别核对，不因脚本只检查已跟踪文件就认定所有内容都已纳入发布。 -2. 读取版本文件、已有 tag 和实际发行记录，确认上一发布基线与本次目标提交。 - 根据基线到目标的提交和最终差异归纳变更，剔除回退、重复和未进入发布范围的内容。 - 不能只用当前版本文件或最近几条提交判断“本次更新”。 -3. 使用用户指定或当前会话已确定的目标版本；需要建议时按兼容性、能力新增和修复范围说明理由。 - 目标 tag 必须未被占用；遇到已有同名版本先判断是重试还是新发版，不自动递增版本掩盖冲突。 -4. 按贡献文档维护 `release/notes.md`。正文写中文，保留版本号和必要技术标识； - 按用户可感知的最终行为归并，不逐条翻译 commit，也不把排查过程或未验证承诺写入说明。 - 可按新增功能、问题修复、体验优化、升级说明组织，省略没有内容的章节。 -5. 替换为本次版本说明，首行与目标 tag 一致且正文非空。升级事项应能追溯到实际迁移、配置或兼容变化； - 敏感信息脱敏，未合入功能不宣称已发布。已有准确说明仅需翻译时保持其事实和范围。 -6. 按贡献规范检查变更与现有 CI 证据，明确通过、失败、跳过和未执行。 - 涉及数据库迁移时，对照同一大版本的上一正式 Release 及本轮预发行/实验线的已发布版本检查迁移是否保持不变，并验证升级路径； - 跨大版本按项目部署约定判断，不默认支持在线升级。区分未发布迁移的整理、已执行这些迁移的源码部署实例， - 以及 CI 实际采用的冻结基线。未发版不代表迁移从未被执行，CI 冻结检查失败也不等于正式版数据库升级失败； - 按各自证据报告兼容性与检查结果，不因未发版而自动放宽现有冻结规则。 - 只修改说明时无需重建前后端；实际发版仍要跟踪发布工作流针对目标提交的检查与产物。 - -## 执行发版 - -调用入口前重新核对当前脚本的副作用、目标版本和待推送提交，保留无关工作区内容，不自动清理或暂存用户文件。 -先编辑 `release/notes.md`，保留为未提交改动（已暂存或未暂存均可）；其他已跟踪文件的改动应先单独提交。 -脚本会更新 `release/version.yaml`，将它与最终工作区中的发布说明一起提交为 `chore(release): vX.Y.Z`。 -不要提前单独提交说明或把版本文件改成目标版本；脚本要求说明相对 HEAD 有改动，并自行更新版本号。 -本任务需要的提交按贡献文档保留英文 Conventional Commits 与相应署名。 - -在准备完成且用户已授权发布后，将 `release_version` 设为已确定的版本，执行： - -```bash -release/publish "$release_version" -``` - -该命令会创建包含版本号和发布说明的单次提交与 annotated tag，原子推送分支和 tag，再从长期分支手动触发 `release.yml`。 -它没有只读预演模式；不能为了检查或演练而执行。发布工作流读取 tag 中的说明，修改 tag 之后的本地文件不会改变该次构建。 - -只调整已发布页面的标题或正文时，编辑对应 GitHub Release 的 `name` 或 `body` 并回读核对； -保持已有 tag、源码提交、附件和预发行状态，不重新执行发布入口。 - -## 恢复与验收 - -- 脚本中断或网络超时时，先核对本地提交与 tag、远端分支与 tag、对应工作流 run 及 Release，确定已完成到哪一步。 - 若本地已创建版本提交或 tag，不直接重跑入口，也不通过删 tag、回退版本或强推来消除报错。 -- 提交和 tag 已推送但工作流未触发时，核对目标后使用脚本提示的 dispatch 命令补触发； - 工作流已存在则跟踪或恢复对应 run，避免重复发布。发现 tag 指向不同提交时报告冲突，不移动已发布 tag。 -- 跟踪与本次 tag 对应的 run ID，核对工作流解析的目标提交。触发工作流成功只表示已开始，不能当作发布完成。 -- 发布完成后核对 GitHub Release 的版本、正式版/预发行状态和中文变更正文；对照平台清单与工作流确认归档、校验和及镜像产物。 - 工作流附加的安装说明和自动提交列表按其当前配置处理，不用它们替代手写的中文变更说明。 -- 返回版本、tag 对应提交、Release/工作流链接及实际结果。失败、仍在构建或缺失产物时明确说明，不能称为发布成功； - Release 和镜像已生成也不表示用户的运行实例已经升级。 +- `release/publish` 会提交、打 tag、推送并触发工作流，没有只读预演模式，不能用于探测或演练 +- 同名版本、超时或中断先查本地与远端状态，不删已发布 tag、不移动 tag、不强推掩盖冲突 +- 预发行不得覆盖 GitHub Latest 或镜像 `latest`，完成后回读核对 +- `release/notes.md` 只承载当前发行的说明，常规文档只写当前状态，不追加版本历史；其变更执行[文档检查](../cpr-dev-guide/references/documentation.md) +- 交付版本、提交、Release／工作流链接与实际结果，未完成构建或缺失产物时不称发布成功 diff --git a/.agents/skills/cpr-release/references/experimental.md b/.agents/skills/cpr-release/references/experimental.md index 8c335a33a..ff67e4c71 100644 --- a/.agents/skills/cpr-release/references/experimental.md +++ b/.agents/skills/cpr-release/references/experimental.md @@ -1,7 +1,7 @@ # 实验版发布 -适用于独立于主版本维护、供用户主动选择体验的实验功能。发布入口仍是仓库的 `release/publish`， -构建复用目标实验分支的 `.github/workflows/release.yml` 与 `release/platforms.yaml`。 +按当前任务只读版本、发布能力、文案或验收章节，不因准备实验说明而读取执行流程 +适用于独立于主版本维护、供用户主动选择体验的实验功能，入口使用仓库的 `release/publish`，构建复用目标实验分支的工作流与平台清单 ## 分支与版本 @@ -14,10 +14,10 @@ 不为统一名称移动 tag 或替换原有产物。 - GitHub Release 展示标题采用 `vX.Y.Z-<用途>.M`，`<用途>` 取实验分支名去掉 `experimental/` 前缀后的部分。 发布前通过 `gh api` 核对相同正式版基线与用途的已有 Release 标题和旧命名 tag，新发行取已有最大编号加 1，首次从 1 开始。 - 展示编号 `M` 独立于实际 tag 的 `exp.N`，旧命名发行也计入，不能因改用 `exp.N` 而重置；同一发行重试沿用已确定编号。 + 展示编号 `M` 独立于实际 tag 的 `exp.N`，所有同基线、同用途的已有发行均计入，不随 tag 命名格式重置；同一发行重试沿用已确定编号。 例如已有 `v3.10.0-codex-anti-degradation.1`，下一次 tag 即使是 `v3.10.0-exp.1`，标题也应为 `v3.10.0-codex-anti-degradation.2`。 - tag 和产物继续使用 `exp.N`：镜像版本去掉 tag 开头的 `v`，安装包沿用项目的版本、系统和架构命名。 - 发布说明首行仍匹配实际 tag；关联 Issue 和试验目的写在正文中。新标题规则不自动改名已有 Release。 + 发布说明首行匹配实际 tag，关联 Issue 和试验目的写在正文中，已有 Release 不因新发行而改名 ## 先核对发布能力 @@ -54,12 +54,12 @@ ## 执行与验收 -按主技能准备说明和其他变更后，在实验分支执行 `release/publish `。 +按[版本与说明准备](preparation.md)的对应章节准备后，再按[执行发版](operations.md#执行发版)在实验分支调用入口 入口创建版本提交和 tag，并从该分支 dispatch 发布工作流；不要从 `main` 发布实验代码。 -按主技能的「发行通道核对」确认稳定入口未改变，并检查实验线隔离与上一版本的更新能力。 +按[发行通道核对](operations.md#发行通道核对)确认稳定入口未改变，并检查实验线隔离与上一版本的更新能力。 检查展示标题的分支用途与历史续号、它所对应的实际 tag，以及目标 tag 的源码提交、完整产物、校验和、多架构平台和 Pre-release 标记。 同基线的 `X.Y.Z-exp.N` 按 SemVer 排序低于正式 `X.Y.Z`；渠道隔离仍以更新器过滤和发布标签规则为准。 -失败时按主技能从未完成步骤恢复，不通过换版本号或移动 tag 掩盖失败。 +失败时按[恢复与验收](operations.md#恢复与验收)从未完成步骤恢复，不通过换版本号或移动 tag 掩盖失败。 仅维护已有页面文案时不重新构建；报告实际完成状态、发布链接及验证缺口。 diff --git a/.agents/skills/cpr-release/references/operations.md b/.agents/skills/cpr-release/references/operations.md new file mode 100644 index 000000000..f3afc7dd2 --- /dev/null +++ b/.agents/skills/cpr-release/references/operations.md @@ -0,0 +1,49 @@ +# 执行、恢复与验收 + +只在实际发布、恢复失败步骤或验收发行时读取对应章节，先核对[入口](../SKILL.md)中的范围与授权 + +## 发行通道核对 + +- alpha 是下一正式版本的早期开发阶段，beta 是功能测试阶段，rc 是发布候选，exp 是临时功能实验。 + 预发行采用 `vX.Y.Z-<阶段>.N`，`N` 从 1 开始；正式版不带预发行后缀，不新增未约定的通道名称。 +- 更新候选由本次检查或安装选择的通道决定：Stable 仅正式版，RC 包含正式版，Beta 包含 RC 与正式版，Alpha 包含所有常规阶段。 + 仅接收同一大版本内严格更高的版本，可跟随后续小版本与补丁版本，默认按运行版本推导通道；临时选择不保存、不允许降级。 + exp 仅接收同基线、同一轮实验的后续编号，不能跨实验线或转入其他阶段；不同实验分支不得共用一个 `X.Y.Z-exp.N` 系列。 +- 核对目标工作流的构建类型：正式版及 alpha、beta、rc 为 `release`，exp 为 `experimental`。 + 所有预发行均标记为 Pre-release，不设置 GitHub Latest、不覆盖镜像 `latest`。 + 发布预发行前记录这两个稳定入口，发布后回读确认未改变。 +- 验收更新器时，核对检查更新与执行更新使用相同规则。只有当前构建支持更新且存在允许的更高目标时 + 才能返回 `hasUpdate=true`；被禁止的目标即使版本领先，也不能出现在更新标记、可用版本或发布说明中。 + 检查失败须单独报告。核对上一发行实际包含的更新能力，不能因新包支持在线更新就宣称旧包也能在线安装它。 + +## 执行发版 + +调用入口前重新核对当前脚本的副作用、目标版本和待推送提交，保留无关工作区内容，不自动清理或暂存用户文件。 +先编辑 `release/notes.md`，保留为未提交改动（已暂存或未暂存均可）；其他已跟踪文件的改动应先单独提交。 +脚本会更新 `release/version.yaml`，将它与最终工作区中的发布说明一起提交为 `chore(release): vX.Y.Z`。 +不要提前单独提交说明或把版本文件改成目标版本；脚本要求说明相对 HEAD 有改动，并自行更新版本号。 +本任务需要的提交按[项目约定](../../../../CONTRIBUTING.md#项目约定)保留英文 Conventional Commits 与相应署名。 + +在准备完成且用户已授权发布后，将 `release_version` 设为已确定的版本，执行： + +```bash +release/publish "$release_version" +``` + +该命令会创建包含版本号和发布说明的单次提交与 annotated tag，原子推送分支和 tag，再从长期分支手动触发 `release.yml`。 +它没有只读预演模式；不能为了检查或演练而执行。发布工作流读取 tag 中的说明，修改 tag 之后的本地文件不会改变该次构建。 + +只调整已发布页面的标题或正文时，编辑对应 GitHub Release 的 `name` 或 `body` 并回读核对； +保持已有 tag、源码提交、附件和预发行状态，不重新执行发布入口。 + +## 恢复与验收 + +- 脚本中断或网络超时时，先核对本地提交与 tag、远端分支与 tag、对应工作流 run 及 Release，确定已完成到哪一步。 + 若本地已创建版本提交或 tag，不直接重跑入口，也不通过删 tag、回退版本或强推来消除报错。 +- 提交和 tag 已推送但工作流未触发时，核对目标后使用脚本提示的 dispatch 命令补触发； + 工作流已存在则跟踪或恢复对应 run，避免重复发布。发现 tag 指向不同提交时报告冲突，不移动已发布 tag。 +- 跟踪与本次 tag 对应的 run ID，核对工作流解析的目标提交。触发工作流成功只表示已开始，不能当作发布完成。 +- 发布完成后核对 GitHub Release 的版本、正式版/预发行状态和中文变更正文；对照平台清单与工作流确认归档、校验和及镜像产物。 + 工作流附加的安装说明和自动提交列表按其当前配置处理，不用它们替代手写的中文变更说明。 +- 返回版本、tag 对应提交、Release/工作流链接及实际结果。失败、仍在构建或缺失产物时明确说明，不能称为发布成功； + Release 和镜像已生成也不表示用户的运行实例已经升级。 diff --git a/.agents/skills/cpr-release/references/preparation.md b/.agents/skills/cpr-release/references/preparation.md new file mode 100644 index 000000000..b1add4142 --- /dev/null +++ b/.agents/skills/cpr-release/references/preparation.md @@ -0,0 +1,36 @@ +# 版本与说明准备 + +只在规划版本、编写发布说明或准备发行时读取对应部分，不因准备文案加载执行流程 + +## 基线与版本 + +1. 确认类型、分支、upstream、目标仓库、工作区与完整待发布范围，保留无关改动；未跟踪文件也需核对 +2. 读取 [version.yaml](../../../../release/version.yaml)、相关 tag 和实际 Release，确定上一发布基线与本次目标提交，再核对二者间的最终 diff，不只看最近几条提交 +3. 使用用户确定的目标版本，建议版本时说明兼容性、能力或修复依据；同名 tag 先区分重试与新发行，不递增版本掩盖冲突 +4. 命名与晋级按[版本命名与升级规则](../../../../deploy/README.md#版本命名与升级规则)，实验版另读[实验流程](experimental.md#分支与版本) + +## 发布说明 + +读取当前 [notes.md](../../../../release/notes.md)与[项目约定](../../../../CONTRIBUTING.md#项目约定)中的发布说明条目 + +- 只在发布说明任务中修改 `release/notes.md`，替换为本次版本内容，首行为目标 tag，正文使用中文 +- 按用户可感知的最终变化归并，省略空章节，不逐条翻译提交，不写排查过程或未经验证的承诺 +- 剔除回退、重复及未进入发行范围的内容，升级事项须能追溯到实际迁移、配置或兼容变化 +- 只翻译已有准确说明时保持事实与范围，不混入其他变更 +- 常规文档仍只描述当前状态；必要修订执行[文档检查](../../cpr-dev-guide/references/documentation.md)，不复制发布说明中的版本变化列表 + +实际发布由 `release/publish` 提交说明与版本文件，准备说明时不要提前单独提交或把版本文件改成目标版本 +用户只要求准备时保留本地改动，纯说明修改无需重建前后端 + +## 发行准备检查 + +进入实际发行准备后，读取目标分支的 [release/publish](../../../../release/publish)、[工作流](../../../../.github/workflows/release.yml)与[平台清单](../../../../release/platforms.yaml)，按当前入口执行，不另写脚本或绕过检查 + +按[验证要求](../../../../CONTRIBUTING.md#验证)核对目标提交的证据，区分通过、失败、跳过与未执行 +数据库变更同时读取[迁移冻结规则](../../../../backend/migrations/README.md#冻结规则)： + +- 对照同一大版本的上一正式版和本轮预发行／实验线的已发布版本，验证迁移未改写及升级路径 +- 区分未发布迁移、已执行迁移的源码部署实例与 CI 冻结基线，未发版不代表未执行，也不授权放宽冻结规则 +- 兼容性与 CI 检查分别报告，跨大版本不默认支持在线升级 + +正式执行时再读取[通道核对](operations.md#发行通道核对)与[执行发版](operations.md#执行发版)，触发工作流不等于发布成功 diff --git a/AGENTS.md b/AGENTS.md index bcda97aa1..503c5e952 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,15 +5,21 @@ | 任务意图与常见说法 | 必用技能 | | --- | --- | | 开发、实现、修复、排查报错、审查问题或代码、修改文档 | [cpr-dev-guide](.agents/skills/cpr-dev-guide/SKILL.md) | -| 提交／提个 PR、准备或更新 PR、提交到已有 PR、看下 PR、处理 PR 审查意见 | [cpr-github-pr](.agents/skills/cpr-github-pr/SKILL.md)；需要修改时同时执行 cpr-dev-guide | -| 提 Issue、反馈到仓库、把问题或建议整理成 Issue | [cpr-github-issue](.agents/skills/cpr-github-issue/SKILL.md) | +| 提交／提个 PR、准备或更新 PR、看下 PR、回复 PR 讨论、处理 PR 审查意见 | [cpr-github-pr](.agents/skills/cpr-github-pr/SKILL.md)；需要修改时同时执行 cpr-dev-guide | +| 提 Issue、反馈到仓库、把问题或建议整理成 Issue、补充或回复 Issue | [cpr-github-issue](.agents/skills/cpr-github-issue/SKILL.md) | | 写网关插件、修改插件能力、排查插件接入、打包插件 | [cpr-plugin-dev](.agents/skills/cpr-plugin-dev/SKILL.md)，同时执行 cpr-dev-guide | | 发版、准备版本、发布 beta／实验版、整理发布说明、打发行 tag | [cpr-release](.agents/skills/cpr-release/SKILL.md) | -结合上下文识别“提交吧”“看看这个问题”等省略说法：普通 Git 提交不自动变成 PR，代码排查不自动变成 Issue；审查与发版准备不代表获准远程写入。 -任务进入新阶段时补载对应技能，不能只读取文件而跳过其中的问题核实、自审、验证与交付步骤。协作流程和审查标准见 [CONTRIBUTING.md](CONTRIBUTING.md)。 +结合上下文识别“提交吧”“看看这个问题”等省略说法：普通 Git 提交不自动变成 PR，代码排查不自动变成 Issue；审查与发版准备不代表获准远程写入 + +只加载当前任务命中的技能、模式和文档章节，复用已有上下文，进入新阶段再补读；链接是按需入口，不是全文或全部参考文件的必读清单 + +执行所选流程中的问题核实、自审、验证与交付要求，协作流程和审查标准见 [CONTRIBUTING.md](CONTRIBUTING.md) + +Issue 和 PR 回复分别按对应技能的[Issue 回复口吻](.agents/skills/cpr-github-issue/SKILL.md#回复口吻)与[PR 回复口吻](.agents/skills/cpr-github-pr/SKILL.md#回复口吻)执行 + 模块职责以 [系统架构](docs/architecture.md) 为准，界面约定以 [管理端主题](docs/theme.md) 为准； -没有明确约定时保持与相邻实现一致，不把单次页面反馈扩展成全仓规则。 +没有明确约定时保持与相邻实现一致，不把单次页面反馈扩展成全仓规则 ## CodeGraph @@ -28,11 +34,12 @@ If there is no `.codegraph/` directory, skip CodeGraph entirely — indexing is ## 工作方式 -- 开发和审查按 [问题与方案依据](CONTRIBUTING.md#问题与方案依据) 先核实问题，以官方源码为首要参考确定或评估方案。 +- 开发和审查按 [问题与方案依据](CONTRIBUTING.md#问题与方案依据) 先核实问题；涉及 Codex 行为、协议或兼容性时，按[参考仓库优先级](.agents/skills/cpr-dev-guide/SKILL.md#参考仓库的优先级)以官方 Codex 仓库对应版本源码为第一手资料，三方仓库仅作参考 - 先定位变更所属模块、同类实现和上下游调用关系，再选择最小合理改动。复用已有能力，也避免为尚不存在的需求增加抽象。 - 提交前自审最终差异，先处理本次引入的职责混淆、重复规则、冗余状态和无依据的兼容分支；后端按 [后端自审](docs/architecture.md#后端自审) 追踪状态与资源生命周期，不能把自审留给 CI 或 PR 审查者。 - 页面变更先复用已有页面设计与组件，不因个人偏好重排页面或另建交互。文案取舍遵循 [界面文案与信息层级](docs/theme.md#界面文案与信息层级)，页面 PR 必须提供 [实际截图](CONTRIBUTING.md#界面验证)。 - 代码注释使用中文，解释原因与边界；提交信息使用英文，沿用历史中的 Conventional Commits 格式。 +- 常规文档只描述当前状态，不记录变更历史；按[文档职责与更新条件](CONTRIBUTING.md#文档职责与更新条件)在所属章节就地修订，分清层次与详略，短段和列表少用句号，交付前逐段检查必要性、归属、重复与当前状态表达 - 按变更范围执行验证，记录命令、结果和缺口。跳过的测试不算通过；界面与集成行为需要对应运行证据，构建通过不能替代实际验收。 - 审查请求默认只读。修复、提交、推送和合并按用户当前授权执行；“本地验证通过”不等于用户已经审阅批准。 - 不读取或输出无关凭据，不把真实密钥、代理认证、账号令牌或请求转储放入提交、截图及审查报告。 @@ -43,7 +50,7 @@ If there is no `.codegraph/` directory, skip CodeGraph entirely — indexing is ### 审查范围 - 确认目标分支与当前变更范围，结合调用方、被调用方及已有测试审查；结论对应实际审查的提交或工作区状态。 -- 按 CONTRIBUTING.md 的维度检查设计、正确性、安全、复杂度、性能、可读性、验证、界面和文档，深度与变更风险相称。 +- 按[审查标准](CONTRIBUTING.md#审查标准)检查设计、正确性、安全、复杂度、性能、可读性、验证、界面和文档，深度与变更风险相称 - 重点核对现有架构和数据合同：共享业务事实是否重复解释，异步与并发操作是否破坏状态，权限和敏感数据是否越界，协议适配是否影响兼容性。 - 修改既有特殊分支时先查场景和历史；放宽检查、修改测试或新增例外需要业务依据，不能仅以让检查通过为理由。 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bb20ce0ad..c7636631f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,47 +1,47 @@ # 贡献与审查 -贡献应解决明确的问题，并保持或改善项目的可维护性。提交者、自动检查和审查者使用同一套标准，让重复问题在提交和初审阶段得到处理。 +贡献应解决明确的问题，并保持或改善项目的可维护性。提交者、自动检查和审查者使用同一套标准，让重复问题在提交和初审阶段得到处理 -本文定义协作流程与审查标准；模块职责以 [系统架构](docs/architecture.md) 为准，视觉规则以 [管理端主题](docs/theme.md) 为准。没有明确约定时遵循相邻实现；具体页面的布局决定不自动成为全项目限制。 +本文定义协作流程与审查标准；模块职责以 [系统架构](docs/architecture.md) 为准，视觉规则以 [管理端主题](docs/theme.md) 为准。没有明确约定时遵循相邻实现；具体页面的布局决定不自动成为全项目限制 ## 交流与反馈 [讨论区](https://github.com/zyycn/codex-proxy-rs/discussions) 用于使用问答、想法讨论、实验反馈和经验分享。 -提问时按需补充版本、部署方式、已尝试的方法及脱敏信息；问题解决后，请在「使用问答」中标记有帮助的答案。 +提问时按需补充版本、部署方式、已尝试的方法及脱敏信息；问题解决后，请在「使用问答」中标记有帮助的答案 明确的 Bug、具体功能需求或协作规则建议使用 Issue，无需先开讨论。 讨论形成可执行事项后，可以新建 Issue 并互相附链接；已有 Issue 的后续信息继续补充在原帖，避免重复记录。 -围绕问题友善交流，欢迎不同使用场景和方案观点。 +围绕问题友善交流，欢迎不同使用场景和方案观点 ### 提交 Issue -按场景选择 [接口问题反馈](.github/ISSUE_TEMPLATE/api-bug-report.yml)、[常规问题反馈](.github/ISSUE_TEMPLATE/general-bug-report.yml) 或 [功能建议](.github/ISSUE_TEMPLATE/feature-request.yml) 表单，按对应提示提供信息。故障反馈填写实际运行版本和中转链路；接口问题区分客户端显示与网关实际响应，页面问题附相关截图或录屏。 +按场景选择 [接口问题反馈](.github/ISSUE_TEMPLATE/api-bug-report.yml)、[常规问题反馈](.github/ISSUE_TEMPLATE/general-bug-report.yml) 或 [功能建议](.github/ISSUE_TEMPLATE/feature-request.yml) 表单，按对应提示提供信息。故障反馈填写实际运行版本和中转链路；接口问题区分客户端显示与网关实际响应，页面问题附相关截图或录屏 -日志和配置只提供定位所需片段，不上传真实凭据或完整请求转储。功能建议说明使用场景、当前不便和期望行为；协作规则调整可直接提交普通 Issue，说明原因和建议方案。 +日志和配置只提供定位所需片段，不上传真实凭据或完整请求转储。功能建议说明使用场景、当前不便和期望行为；协作规则调整可直接提交普通 Issue，说明原因和建议方案 ## 问题与方案依据 -开发、创建 PR 和审查都先核实待解决的问题、触发条件与预期行为，再确定或评估实现。区分问题发生版本、目标分支现状和本次变更后的行为，不把需求描述、PR 描述或第三方项目的做法直接当成事实。目标分支已修复的问题，应说明当前仍需补齐的差异，不能据此否定旧版本中的问题。 +开发、创建 PR 和审查都先核实待解决的问题、触发条件与预期行为，再确定或评估实现。区分问题发生版本、目标分支现状和本次变更后的行为，不把需求描述、PR 描述或第三方项目的做法直接当成事实。目标分支已修复的问题，应说明当前仍需补齐的差异，不能据此否定旧版本中的问题 -涉及上游协议、客户端行为或兼容性时，以对应版本的官方源码为首要资料。优先读取用户提供或本机已有的官方源码，核对仓库来源、版本或提交；本地资料不足时查官方仓库的对应版本源码，再结合官方测试、文档、发布说明和运行证据。第三方资料只作线索或补充。引用具体文件、符号或行号，对外引用优先使用固定提交的源码链接；源码不可得或版本不匹配时说明证据缺口，不把最新实现当成当前部署行为。无上游依赖的内部变更，以本项目代码、合同和运行证据为依据。 +涉及上游协议、客户端行为或兼容性时，以对应版本的官方源码为首要资料。优先读取用户提供或本机已有的官方源码，核对仓库来源、版本或提交；本地资料不足时查官方仓库的对应版本源码，再结合官方测试、文档、发布说明和运行证据。第三方资料只作线索或补充。引用具体文件、符号或行号，对外引用优先使用固定提交的源码链接；源码不可得或版本不匹配时说明证据缺口，不把最新实现当成当前部署行为。无上游依赖的内部变更，以本项目代码、合同和运行证据为依据 -官方已有同一场景的处理方式时，优先沿用其协议语义、职责归属和解决路径，检查是否只需复用已有能力或正确传递官方合同。新增覆盖配置、补偿逻辑或采用第三方兼容方案，应说明官方路径为何不足；偏离官方方案需有本项目的实际约束和验证依据，不机械照搬源码，也不默认接受已有提案。 +官方已有同一场景的处理方式时，优先沿用其协议语义、职责归属和解决路径，检查是否只需复用已有能力或正确传递官方合同。新增覆盖配置、补偿逻辑或采用第三方兼容方案，应说明官方路径为何不足；偏离官方方案需有本项目的实际约束和验证依据，不机械照搬源码，也不默认接受已有提案 -反馈 Issue 时区分观察到的症状、根因假设和方案建议，关联已有 Issue、PR 及包含修复的发布版本。能说明问题的反馈可以先提交，不要求报告者先找到官方源码或证明根因；引用官方行为或提出实现方案时，按上述原则注明依据与缺口。 +反馈 Issue 时区分观察到的症状、根因假设和方案建议，关联已有 Issue、PR 及包含修复的发布版本。能说明问题的反馈可以先提交，不要求报告者先找到官方源码或证明根因；引用官方行为或提出实现方案时，按上述原则注明依据与缺口 ## PR 流程 -1. **准备变更。** 按上述依据核实问题与方案，找到所属模块、相关调用链和最接近的现有实现，在功能分支完成修改。提交前自审完整差异，清理本次引入的重复逻辑、冗余状态与职责越界；后端按 [后端自审](docs/architecture.md#后端自审) 执行。涉及架构、公开合同或较大交互变化时，先说明方案与取舍。 -2. **发起 PR。** 目标分支使用 `main`，按 [PR 模板](.github/pull_request_template.md) 说明问题依据、触发场景、最终行为、自审和实际验证结果；涉及官方行为时注明源码位置、版本和方案关系。页面变更必须按 [界面验证](#界面验证) 附实际截图，使用 AI 时按 [AI 使用披露](#ai-使用披露) 写明模型。一个 PR 围绕一个明确目标，必要重构说明关联原因。 -3. **自动检查与初审。** CI 执行适用的格式、静态分析、测试和构建检查；启用 AI 审查后，由它按本规范辅助检查语义、复用和一致性。提交者先处理明确问题，维护者重点审阅方案、风险与用户体验。 -4. **修改与合并。** 更新代码后重新执行受影响的检查，确认审查意见已处理，验证证据对应当前变更。维护者审阅批准后再合并；需要升级说明的变更同步相关文档。 +1. **准备变更**：按上述依据核实问题与方案，找到所属模块、相关调用链和最接近的现有实现，在功能分支完成修改。提交前自审完整差异，清理本次引入的重复逻辑、冗余状态与职责越界；后端按 [后端自审](docs/architecture.md#后端自审) 执行。涉及架构、公开合同或较大交互变化时，先说明方案与取舍 +2. **发起 PR**：目标分支使用 `main`，按 [PR 模板](.github/pull_request_template.md) 说明问题依据、触发场景、最终行为、自审和实际验证结果；涉及官方行为时注明源码位置、版本和方案关系。页面变更必须按 [界面验证](#界面验证) 附实际截图，使用 AI 时按 [AI 使用披露](#ai-使用披露) 写明模型。一个 PR 围绕一个明确目标，必要重构说明关联原因 +3. **自动检查与初审**：CI 执行适用的格式、静态分析、测试和构建检查；启用 AI 审查后，由它按本规范辅助检查语义、复用和一致性。提交者先处理明确问题，维护者重点审阅方案、风险与用户体验 +4. **修改与合并**：更新代码后重新执行受影响的检查，确认审查意见已处理，验证证据对应当前变更。维护者审阅批准后再合并；需要升级说明的变更同步相关文档 -AI 开发和审查入口是根目录的 [AGENTS.md](AGENTS.md)。在仓库上下文中要求“审查 PR #编号”时，应按下列标准执行，无需再次列举要求。 +AI 开发和审查入口是根目录的 [AGENTS.md](AGENTS.md)。在仓库上下文中要求“审查 PR #编号”时，应按下列标准执行，无需再次列举要求 ### 项目技能 仓库技能位于 `.agents/skills/`，随代码共享。技能提供执行流程，协作与审查标准仍以本文和 `AGENTS.md` 为准。 -AI 开发、排查、代码审查和文档修改必须执行 `cpr-dev-guide`；准备、创建、更新及审查 PR 必须执行 `cpr-github-pr`，不以用户是否显式点名技能为条件。PR 内修复仍须经过开发流程，不能用填写 PR 正文代替实现自审与验证。 +AI 开发、排查、代码审查和文档修改必须执行 `cpr-dev-guide`；准备、创建、更新及审查 PR 必须执行 `cpr-github-pr`，不以用户是否显式点名技能为条件。PR 内修复仍须经过开发流程，不能用填写 PR 正文代替实现自审与验证 | 技能 | 用途 | 调用示例 | | --- | --- | --- | @@ -51,26 +51,26 @@ AI 开发、排查、代码审查和文档修改必须执行 `cpr-dev-guide`； | [cpr-github-issue](.agents/skills/cpr-github-issue/SKILL.md) | 整理或提交 Issue | `$cpr-github-issue 提交当前问题` | | [cpr-release](.agents/skills/cpr-release/SKILL.md) | 准备发布说明或正式发版 | `$cpr-release 整理本次发布说明` / `$cpr-release 发布 vX.Y.Z` | -审查请求默认在当前会话报告；明确要求创建 PR、提交 Issue 或正式发版时才执行对应远程操作。技能安装不等于启用 GitHub 自动审查。 +审查请求默认在当前会话报告；明确要求创建 PR、提交 Issue 或正式发版时才执行对应远程操作。技能安装不等于启用 GitHub 自动审查 ### AI 使用披露 PR 正文说明提交者是否使用 AI。使用 AI 参与方案、代码、文档、测试或自审时，写明工具名称和实际模型型号；使用多个模型时分别列出，可简述各自参与范围。 `Codex`、`ChatGPT`、`Claude Code` 等工具或产品名称不能代替模型型号，优先填写工具显示或调用配置中的具体模型标识。 无法获知型号时如实标记「型号未提供，待补充」，不能猜测或伪造，也不能把待补信息称为已完成披露；补齐前保留 Draft。 -更新 PR 时同步新增的模型信息；这一披露不替代提交者自审、验证责任或已有提交署名约定。 +更新 PR 时同步新增的模型信息；这一披露不替代提交者自审、验证责任或已有提交署名约定 ### 规则文件保护 -PR 不接受根目录或子目录中 `AGENTS.md` 的新增、修改、删除或重命名。调整这些文件时先提交 Issue 说明原因和建议，由维护者处理；[规则保护工作流](.github/workflows/agents-md-guard.yml) 会提示并关闭包含此类变更的 PR。撤销相关变更后可以重新打开 PR，继续正常检查。 +PR 不接受根目录或子目录中 `AGENTS.md` 的新增、修改、删除或重命名。调整这些文件时先提交 Issue 说明原因和建议，由维护者处理；[规则保护工作流](.github/workflows/agents-md-guard.yml) 会提示并关闭包含此类变更的 PR。撤销相关变更后可以重新打开 PR，继续正常检查 -源码变更遵守现有架构边界与迁移冻结规则，由对应 CI 检查执行；不额外设立整块业务目录的 PR 禁改清单。构建、测试和安全扫描复用现有工作流。 +源码变更遵守现有架构边界与迁移冻结规则，由对应 CI 检查执行；不额外设立整块业务目录的 PR 禁改清单。构建、测试和安全扫描复用现有工作流 ## 审查标准 -按改动涉及的范围选择检查深度，无需为每个 PR 填写所有维度的报告。 +按改动涉及的范围选择检查深度，无需为每个 PR 填写所有维度的报告 -结论先回答原问题是否成立（成立、部分成立、不成立或证据不足），说明触发条件和依据；再判断解决方向是否合理，交代适用的官方方案、本次实现与它的关系及必要调整，最后报告实现问题与验证缺口。原问题是否成立与 PR 实现是否正确分别判断。源码推断、实际复现和检查结果分别说明，CI 通过不能代替问题与方案的论证。 +结论先回答原问题是否成立（成立、部分成立、不成立或证据不足），说明触发条件和依据；再判断解决方向是否合理，交代适用的官方方案、本次实现与它的关系及必要调整，最后报告实现问题与验证缺口。原问题是否成立与 PR 实现是否正确分别判断。源码推断、实际复现和检查结果分别说明，CI 通过不能代替问题与方案的论证 | 维度 | 检查重点 | | --- | --- | @@ -86,59 +86,81 @@ PR 不接受根目录或子目录中 `AGENTS.md` 的新增、修改、删除或 审查意见区分三类： -- **必须修复：** 有具体触发条件的缺陷、违反现有合同或明确项目规范的问题。说明位置、依据、影响和最小修复方向。 -- **建议：** 不影响合同或规范的替代实现、命名偏好和局部优化。个人偏好不能单独阻止合并，也不应强求与本次目标无关的重构。 -- **验证缺口：** 尚未检查的行为、状态或运行环境。说明缺少什么证据，由维护者评估是否需要补齐，不能把未验证当作已通过或已发现缺陷。 +- **必须修复：** 有具体触发条件的缺陷、违反现有合同或明确项目规范的问题。说明位置、依据、影响和最小修复方向 +- **建议：** 不影响合同或规范的替代实现、命名偏好和局部优化。个人偏好不能单独阻止合并，也不应强求与本次目标无关的重构 +- **验证缺口：** 尚未检查的行为、状态或运行环境。说明缺少什么证据，由维护者评估是否需要补齐，不能把未验证当作已通过或已发现缺陷 -复杂度不按行数判断，复用不只看语法相似。建议合并重复逻辑时应指出共享的业务含义；建议保留特殊分支时应能说明它服务的场景。例外应有依据，不能仅为绕过检查而放宽规则。 +复杂度不按行数判断，复用不只看语法相似。建议合并重复逻辑时应指出共享的业务含义；建议保留特殊分支时应能说明它服务的场景。例外应有依据，不能仅为绕过检查而放宽规则 ## 项目约定 -- AI 进行 Rust 开发时，加载并使用 `$rust-best-practices` 技能。模块、可见性、依赖方向和测试目录按架构文档执行，使用现有 Rustfmt 与 Clippy 配置。 -- Vue 使用 TypeScript、`