diff --git a/.agents/skills/cpr-dev-guide/SKILL.md b/.agents/skills/cpr-dev-guide/SKILL.md new file mode 100644 index 000000000..18a2ba2e7 --- /dev/null +++ b/.agents/skills/cpr-dev-guide/SKILL.md @@ -0,0 +1,58 @@ +--- +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. +--- + +# 开发指南 + +先读根目录的 [AGENTS.md](../../../AGENTS.md) 和 [CONTRIBUTING.md](../../../CONTRIBUTING.md)。 +本技能只组织工作入口，架构、协议和视觉规则从下列权威文档读取，不维护第二份副本。 + +普通问题审查、代码审查与排查由本技能进入贡献文档的审查标准；有 PR 链接、编号或提交 PR 的意图时再加载 `cpr-github-pr`。 +审查请求先报告结论，不因加载开发技能而擅自修复；用户已要求修改时完成实现、自审和验证。 + +## 按任务读取 + +| 任务 | 技能与文档入口 | +| --- | --- | +| 用户能力、快速开始 | [README](../../../README.md) | +| 模块职责、调用链、状态归属 | [系统架构](../../../docs/architecture.md) | +| Rust 开发 | 加载并使用 `$rust-best-practices`，结合 [系统架构](../../../docs/architecture.md) 与 [项目约定](../../../CONTRIBUTING.md#项目约定) | +| HTTP 路由、请求与响应、导入导出 | [API 文档](../../../docs/api.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) | + +## 前端任务 + +- 加载并使用 `$frontend-design`，先读 [界面文案与信息层级](../../../docs/theme.md#界面文案与信息层级)，将本项目的管理工具风格、现有字体与主题 Token 作为设计约束 +- 开发前对照原页面及该章节的同类参考，确认可复用布局、组件与操作位置；修改已有页面前先留存截图，不为局部需求重做页面 +- 页面保留操作所需的简短信息，重复文案删除，详细帮助按主题约定收进 Popover；关键限制和错误仍就近提示 +- 交付前按该章节复核文案、层级与密度，按 [界面验证](../../../CONTRIBUTING.md#界面验证) 实际操作并保存前后截图；页面 PR 的截图必须可供审查者访问，预览步骤与构建不能替代 + +## 后端任务 + +加载并使用 `$rust-best-practices`，先按架构文档定位事实归属与既有调用链，实现后逐项执行 [后端自审](../../../docs/architecture.md#后端自审) 中与本次改动相关的检查。 +交付说明实际复用位置、重要边界的处理与验证缺口，不用“符合最佳实践”或“CI 已通过”代替自审结论。 + +## 执行顺序 + +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`。 diff --git a/.agents/skills/cpr-dev-guide/agents/openai.yaml b/.agents/skills/cpr-dev-guide/agents/openai.yaml new file mode 100644 index 000000000..3956f26dd --- /dev/null +++ b/.agents/skills/cpr-dev-guide/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "cpr-dev-guide" + short_description: "仓库开发、修复、排查、代码审查与文档修改的流程入口" + default_prompt: "使用 $cpr-dev-guide 按当前任务定位问题与现有实现，完成已授权的开发或审查，并自审、验证和报告结果。" +policy: + allow_implicit_invocation: true diff --git a/.agents/skills/github-issue/SKILL.md b/.agents/skills/cpr-github-issue/SKILL.md similarity index 80% rename from .agents/skills/github-issue/SKILL.md rename to .agents/skills/cpr-github-issue/SKILL.md index c6ecc2de5..2dedd6ab1 100644 --- a/.agents/skills/github-issue/SKILL.md +++ b/.agents/skills/cpr-github-issue/SKILL.md @@ -1,6 +1,6 @@ --- -name: github-issue -description: 整理与提交 GitHub Issue（问题反馈 / 功能建议）。用于“提个 Issue”“把这个问题反馈到仓库”“帮我报个 bug”“整理成 Issue”，以及通过 Issue 提议功能或协作规则的场景；区分草拟正文和实际提交。Use for drafting or filing bug reports and feature requests; not for debugging-only, editing Issue Forms/templates, or skill-authoring requests. +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. --- # 整理与提交 Issue @@ -16,6 +16,7 @@ description: 整理与提交 GitHub Issue（问题反馈 / 功能建议）。用 - “写一份、整理内容、草拟 Issue”只准备正文；明确要求“提交、创建 Issue”才发布。 已经授权提交且信息足够时直接完成，不重复索要确认；仅自动选中技能不能授权发布。 - “有个 bug”“这个报错怎么修”本身是排障语境，不能推断要发 Issue；结合已有反馈任务识别省略的目标和动作。 +- “补充这个 Issue”先读取原帖与已有讨论，按授权更新正文或追加证据，不重复新建；需要排查或修改本仓库时先执行 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)。 - 缺少无法推断的目标或关键复现事实时，只问必要信息，并先整理其余已有证据。 - 使用可用的 GitHub 连接器或 `gh`。不要为提交 Issue 安装新工具、修改仓库配置或启用额外服务。 @@ -54,6 +55,7 @@ description: 整理与提交 GitHub Issue（问题反馈 / 功能建议）。用 gh issue create --repo "$issue_repo" --title "$issue_title" --body-file "$issue_body_file" ``` -发布前快速复核目标、必填内容、脱敏及重复记录。网络超时或返回不明确时先查询远端是否已经创建，避免重复提交。 -发布后读取新 Issue 确认仓库、标题和正文，返回链接及必要的信息缺口。 +发布前快速复核目标、必填内容、脱敏及重复记录；更新已有 Issue 时保留与本次无关的内容，核对目标编号和当前正文。 +网络超时或返回不明确时先查询远端是否已经创建或更新，避免重复提交。 +发布后读取目标 Issue 确认仓库、标题和正文，返回链接及必要的信息缺口。 只准备草稿或发布失败时提供可直接使用的标题与正文，明确尚未提交。 diff --git a/.agents/skills/cpr-github-issue/agents/openai.yaml b/.agents/skills/cpr-github-issue/agents/openai.yaml new file mode 100644 index 000000000..6ba52f009 --- /dev/null +++ b/.agents/skills/cpr-github-issue/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "cpr-github-issue" + short_description: "整理、提交或补充 Issue，核对复现、重复反馈与发布范围" + default_prompt: "使用 $cpr-github-issue 按当前请求整理、提交或补充 Issue，核对目标、复现证据、重复记录和脱敏，不将草拟自动变成发布。" +policy: + allow_implicit_invocation: true diff --git a/.agents/skills/github-pr/SKILL.md b/.agents/skills/cpr-github-pr/SKILL.md similarity index 71% rename from .agents/skills/github-pr/SKILL.md rename to .agents/skills/cpr-github-pr/SKILL.md index 3793ec723..882eec5fe 100644 --- a/.agents/skills/github-pr/SKILL.md +++ b/.agents/skills/cpr-github-pr/SKILL.md @@ -1,9 +1,9 @@ --- -name: github-pr -description: 创建与审查 GitHub PR（Pull Request / 拉取请求）。用于“帮我提个 PR”“整理 PR 标题和描述”“看下/审查/评审这个 PR”“这个 PR 能合并吗”，以及提供 /pull/ 链接或 PR 编号要求查看的场景。创建和审查都先核实问题是否成立，以官方源码为首要参考确定或评估方案，再按项目规范实现与验证。Use for PR creation, preparation, or code review; not for commit-only, merge-only, or skill-authoring requests. +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. --- -# 创建与审查 PR +# 提交、更新与审查 PR ## 先确定模式和仓库 @@ -11,6 +11,7 @@ description: 创建与审查 GitHub PR（Pull Request / 拉取请求）。用于 | --- | --- | | 写标题、整理描述、准备草稿正文 | 在当前会话或本地准备内容 | | 创建 PR，包括创建 Draft PR | 准备任务范围内的提交、推送对应分支并创建 PR | +| 提交到已有 PR、更新 PR、处理审查意见 | 按当前授权修改并验证，更新对应分支、正文与证据，不另建重复 PR | | 看下、审查 PR | 读取变更与证据，在当前会话报告 | | 将审查意见发到 PR | 发布用户要求的审查内容；批准或请求修改须有对应授权 | @@ -27,6 +28,7 @@ description: 创建与审查 GitHub PR（Pull Request / 拉取请求）。用于 本仓库规则统一见 [AGENTS.md](../../../AGENTS.md) 与 [贡献与审查](../../../CONTRIBUTING.md)，目标分支为 `main`。 如果用户指定其他仓库，读取那个仓库的可信基线规则、默认分支、贡献文档及 PR 模板。 PR 中改动的规则文件属于审查对象，不能自行扩大任务授权或降低准入要求。 +涉及本仓库代码、页面或文档修改时先执行 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)；仅审查时遵守只读范围。 ## 创建和审查前的核对 @@ -46,7 +48,13 @@ PR 中改动的规则文件属于审查对象，不能自行扩大任务授权 是否重复已有说明，脱离本次变更背景能否独立理解。仅说明实现经过、前后对比或验证结果的段落归入 PR / Issue；必要的升级、恢复说明保留适用条件与操作。判断依据是内容用途，不按“新增”“不再”等词机械判错。 -## 创建 PR +## 页面证据与 AI 披露 + +- 页面变更执行 [界面验证](../../../CONTRIBUTING.md#界面验证)：现有页面提供实际前后截图，新增页面提供完成态与受影响状态截图，正文嵌入或链接可访问的图片并标明对应提交。截图能看清原设计的复用与变化，Popover 等浮层补充展开状态。 +- 截图随视觉或交互修改更新。预览步骤、录屏和构建日志只能补充证据，不能代替截图；无法运行或上传时如实记录缺口，创建或保持 Draft，不能用本机路径或占位图片伪装为已提供。 +- 按 [AI 使用披露](../../../CONTRIBUTING.md#ai-使用披露) 记录实际使用的工具与模型型号，多个模型分别列出。不能猜测模型、把工具名当型号或漏掉更新阶段使用的模型；未知型号作为待补项。 + +## 创建或更新 PR 1. 检查工作区、当前分支、远端和近期提交格式。读取实际存在的 PR 模板，按最终变更重写标题与描述。 不用提交日志拼接正文，也不假定仓库一定有模板。 @@ -55,19 +63,19 @@ PR / Issue；必要的升级、恢复说明保留适用条件与操作。判断 3. 按上述核对流程，在目标分支基线核实问题，追踪官方与本项目的相关调用链，先确定解决方向再实现。 若改动已完成，也要据此复核问题与方案；需要修正时只修改已授权的范围。仅整理标题或正文时报告差异与缺口， 不自行修改实现。原问题不成立时不将它包装成已修复的缺陷；证据不足时明确保留结论。 - 实现应职责清晰、表达直接、复用合理；提交前主动清理本次变更引入的重复逻辑、冗余状态、死代码、 - 多余抽象及无依据的兼容分支。功能可用和检查通过不能替代可维护性自查。 + 按 `cpr-dev-guide` 完成实现自审；后端按 [后端自审](../../../docs/architecture.md#后端自审) 核对归属、状态、失败出口与副作用， + 页面先复用已有设计并检查文案密度。处理本次引入的冗余与越界问题，功能可用和检查通过不能替代可维护性自查。 4. 查找同一来源仓库、head 和 base 的现有 PR；已存在则复用其链接，不重复创建。 更新现有标题或正文须在本次整理/更新请求范围内。 5. 按贡献文档执行适用检查。记录实际验证的提交或工作区状态，区分通过、失败、跳过和未执行。 按上述文档复核步骤检查最终 diff；没有文档差异时，核对行为变化是否使现有说明失真。 - 前端改动提供实际界面证据或预览步骤；缺少证据时写明，不用构建成功替代视觉验收。 + 页面改动按上述规则补齐截图与实际交互证据，核对模型披露是否完整。 6. 将任务范围内的提交推送到正确远端，核对远端 head。标题遵循项目约定，正文先说明问题成立的依据和最终行为， - 再给必要的设计取舍、验证与遗留事项。涉及官方行为时，写明官方源码位置与版本或提交、官方处理方式、 + 再给必要的设计取舍、自审结论、验证与遗留事项，按模板附页面截图和 AI 使用情况。涉及官方行为时，写明官方源码位置与版本或提交、官方处理方式、 本次实现与它的关系及必要的偏离原因；区分源码推断和实际复现，不用检查通过替代方案论证。按规模压缩，不强填无关章节。 -7. 明确要求草稿或仍有阻塞项时创建 Draft PR，并解释原因；具备审查条件且未要求草稿时创建普通 PR。 +7. 明确要求草稿或仍有阻塞项时创建或保持 Draft PR，并解释原因；必需截图或 AI 模型披露待补时也不标为可审阅。具备审查条件且未要求草稿时创建普通 PR。 GitHub Draft 状态与“只写本地草稿正文”不同，后者不创建远程对象。 -8. 创建后核对链接、base、head、草稿状态和最新检查结果。网络超时或结果不确定时先查询远端，再决定是否重试。 +8. 创建或更新后回读正文与附件，核对链接、base、head、草稿状态、模型披露和最新检查结果。网络超时或结果不确定时先查询远端，再决定是否重试。 CLI 示例中的变量必须先根据上述检查赋值；`pr_body_file` 是精确写入 UTF-8 正文的临时文件： @@ -95,11 +103,12 @@ gh pr create --repo "$pr_repo" --base "$pr_base" --head "$pr_head" \ 对既有特殊分支查清服务的场景，再判断本次改动是否引入或加重问题。 主动检查本次变更新引入或加重的冗余与代码异味，说明具体位置、维护成本或行为影响及最小修复方向； 不能仅因功能可用、CI 通过而略过，也不把个人写法偏好判为缺陷。 -5. UI 改动同时对照主题、共用组件、数据展示逻辑和同类页面。浏览器可用时检查相关交互及状态； - 未运行的页面检查列为验证缺口，不从截图或源码推断所有状态都正确。 +5. UI 改动同时对照原页面、主题、共用组件和同类页面，核对结构变化的必要性、文案是否重复及帮助是否适合收进 Popover。 + 按页面类型检查必需截图是否齐全、可访问且对应待审实现；缺少必需截图时要求补齐并列为未具备审阅条件。 + 浏览器可用时检查相关交互；未运行的检查列为验证缺口，不从截图或源码推断所有状态都正确。 6. 核对 CI 与本地证据是否覆盖当前 head；根据风险补充必要验证，不触发无关部署或真实账号业务请求。 按上述文档复核步骤检查最终 diff，不能把构建或链接检查通过当作文档内容已经合格。 - 工具不可用、集成测试跳过或环境不足时具体说明影响范围。 + 核对 AI 使用与模型披露，缺项明确指出。工具不可用、集成测试跳过或环境不足时具体说明影响范围。 7. 按 [审查标准](../../../CONTRIBUTING.md#审查标准) 用中文先回答原问题是否成立、解决方向是否合理， 再列出实现问题与验证缺口，结论附具体依据。 实现问题区分必须修复项、可选建议和验证缺口；没有的类别可省略。 diff --git a/.agents/skills/cpr-github-pr/agents/openai.yaml b/.agents/skills/cpr-github-pr/agents/openai.yaml new file mode 100644 index 000000000..82717a94c --- /dev/null +++ b/.agents/skills/cpr-github-pr/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "cpr-github-pr" + short_description: "提交、更新与审查 PR，核对问题、自审、页面截图和 AI 模型披露" + default_prompt: "使用 $cpr-github-pr 按当前请求准备、提交、更新或审查 PR，核实问题与方案，检查自审、验证、页面截图和 AI 模型披露。" +policy: + allow_implicit_invocation: true diff --git a/.agents/skills/plugin-dev/SKILL.md b/.agents/skills/cpr-plugin-dev/SKILL.md similarity index 90% rename from .agents/skills/plugin-dev/SKILL.md rename to .agents/skills/cpr-plugin-dev/SKILL.md index 609c6cbdc..b68c9da43 100644 --- a/.agents/skills/plugin-dev/SKILL.md +++ b/.agents/skills/cpr-plugin-dev/SKILL.md @@ -1,12 +1,13 @@ --- -name: plugin-dev -description: 开发 Codex Proxy RS 网关插件，包括选择扩展能力、编写 plugin.json、实现公开 SDK 处理器、管理页面、打包与本地验证。用于新建插件、修改插件或排查插件接入；不用于 OpenAI Codex 的 .codex-plugin 插件、Vue 插件或仅修改宿主插件管理功能。 +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. --- -# plugin-dev +# cpr-plugin-dev 面向插件作者。插件在独立项目中实现，通过公开 SDK 与宿主通信，不向宿主业务模块添加分支。 仅修改宿主安装器、Runtime 或管理端时，使用仓库开发指南，不按本技能创建插件工程。 +本仓库开发与排查同时执行 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)，准备、提交或审查插件 PR 时执行 [cpr-github-pr](../cpr-github-pr/SKILL.md)。 ## 先建立正确的模型 @@ -70,6 +71,7 @@ description: 开发 Codex Proxy RS 网关插件，包括选择扩展能力、编 ### 只有需要页面时才创建前端 +- 沿用已有插件页面与 [管理端主题](../../../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 实例 diff --git a/.agents/skills/cpr-plugin-dev/agents/openai.yaml b/.agents/skills/cpr-plugin-dev/agents/openai.yaml new file mode 100644 index 000000000..dd18846db --- /dev/null +++ b/.agents/skills/cpr-plugin-dev/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "cpr-plugin-dev" + short_description: "网关插件开发、接入排障、SDK 实现、页面与打包验证" + default_prompt: "使用 $cpr-plugin-dev 按当前请求开发、排查或打包 Codex Proxy RS 网关插件，复用公开 SDK 与已有页面并验证实际行为。" +policy: + allow_implicit_invocation: true diff --git a/.agents/skills/plugin-dev/references/development.md b/.agents/skills/cpr-plugin-dev/references/development.md similarity index 100% rename from .agents/skills/plugin-dev/references/development.md rename to .agents/skills/cpr-plugin-dev/references/development.md diff --git a/.agents/skills/release/SKILL.md b/.agents/skills/cpr-release/SKILL.md similarity index 92% rename from .agents/skills/release/SKILL.md rename to .agents/skills/cpr-release/SKILL.md index 0c43172b8..2917d6562 100644 --- a/.agents/skills/release/SKILL.md +++ b/.agents/skills/cpr-release/SKILL.md @@ -1,6 +1,6 @@ --- -name: release -description: 准备或执行当前仓库的正式版、alpha/beta/rc 预发行版和 exp 实验版发版，维护中文发布说明。用于“发版”“发布 beta/rc/实验版”“准备 vX.Y.Z”“推荐版本号”“整理发布说明”“更新 release/notes.md”“打版本 tag”等发行任务。Use for version planning, release notes, and publishing stable, prerelease, or experimental releases; not for deploying/restarting an instance or authoring a release skill. +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. --- # 发版 @@ -19,6 +19,7 @@ description: 准备或执行当前仓库的正式版、alpha/beta/rc 预发行 沿用当前会话明确的版本、范围与授权；用户已授权发布目标版本且条件满足时直接执行，不重复确认。 “准备好了”“可以发版吗”属于准备或检查，不能解释成正式发布；创建本技能也不触发发版。 发行版发布与运行实例升级分开判断，“上线”需结合上下文确定用户指哪一种。 +需要修复本仓库代码、工作流或文档时先执行 [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#版本命名与升级规则)，作为命名、阶段晋级和更新边界的权威约定。 diff --git a/.agents/skills/cpr-release/agents/openai.yaml b/.agents/skills/cpr-release/agents/openai.yaml new file mode 100644 index 000000000..e746168a0 --- /dev/null +++ b/.agents/skills/cpr-release/agents/openai.yaml @@ -0,0 +1,6 @@ +interface: + display_name: "cpr-release" + short_description: "版本规划、中文发布说明、正式与预发行发布及失败恢复" + default_prompt: "使用 $cpr-release 按当前请求准备版本与中文说明、执行已授权的发版或恢复失败步骤，核对渠道与实际结果。" +policy: + allow_implicit_invocation: true diff --git a/.agents/skills/release/references/experimental.md b/.agents/skills/cpr-release/references/experimental.md similarity index 100% rename from .agents/skills/release/references/experimental.md rename to .agents/skills/cpr-release/references/experimental.md diff --git a/.agents/skills/dev-guide/SKILL.md b/.agents/skills/dev-guide/SKILL.md deleted file mode 100644 index a547cde26..000000000 --- a/.agents/skills/dev-guide/SKILL.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -name: dev-guide -description: 当前仓库开发指南。修改或排查本仓库的 Rust 网关、Vue 管理端、账号与出站代理、接口协议、部署、CI、发布或文档时使用，定位权威规范和验证入口。Use for development in the repository containing this skill; not for generic Rust/Vue questions in unrelated repositories. ---- - -# 开发指南 - -先读根目录的 [AGENTS.md](../../../AGENTS.md) 和 [CONTRIBUTING.md](../../../CONTRIBUTING.md)。 -本技能只组织工作入口，架构、协议和视觉规则从下列权威文档读取，不维护第二份副本。 - -## 按任务读取 - -| 任务 | 技能与文档入口 | -| --- | --- | -| 用户能力、快速开始 | [README](../../../README.md) | -| 模块职责、调用链、状态归属 | [系统架构](../../../docs/architecture.md) | -| Rust 开发 | 加载并使用 `$rust-best-practices`，结合 [系统架构](../../../docs/architecture.md) 与 [项目约定](../../../CONTRIBUTING.md#项目约定) | -| HTTP 路由、请求与响应、导入导出 | [API 文档](../../../docs/api.md) | -| 开发独立网关插件 | [plugin-dev](../plugin-dev/SKILL.md)：公开 SDK、能力选择、示例、打包与验证 | -| 前端开发、管理端组件、主题 Token、视觉验证 | 按下方「前端任务」加载设计约束，结合 [管理端主题](../../../docs/theme.md) 与 [界面验证](../../../CONTRIBUTING.md#界面验证) | -| 常规文档更新 | [文档职责与更新条件](../../../CONTRIBUTING.md#文档职责与更新条件)：维护当前说明，在原章节就地修订，不记录变更历史 | -| 部署、客户端配置、备份与恢复 | [部署说明](../../../deploy/README.md) | -| 数据迁移、冻结清单与本地测试库 | [迁移说明](../../../backend/migrations/README.md) | -| 验证命令与提交规范 | [贡献与审查](../../../CONTRIBUTING.md) | -| 创建或审查 PR | [github-pr](../github-pr/SKILL.md) | -| 整理或提交 Issue | [github-issue](../github-issue/SKILL.md) | -| 发布说明、版本规划与发版 | [release](../release/SKILL.md) | - -## 前端任务 - -- 加载并使用 `$frontend-design`，先读 [界面文案与信息层级](../../../docs/theme.md#界面文案与信息层级)，将本项目的管理工具风格、现有字体与主题 Token 作为设计约束 -- 开发前按该章节的参考入口和相邻页面核对布局、文案密度与操作位置，再选择共用组件 -- 交付前按该章节检查界面文案中的句号、分号，以及过大的标题、重复说明和说明块占用的空间，结合 [界面验证](../../../CONTRIBUTING.md#界面验证) 核对实际页面 - -## 执行顺序 - -1. 从仓库根目录确认工作区、当前任务范围和相关运行实例；保留已有改动。 -2. 按 `AGENTS.md` 的 CodeGraph 约定定位入口、调用链和职责归属，再阅读相关实现。 -3. 按 [问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据) 核实触发条件、问题发生版本与目标分支现状， - 优先依据适用的官方源码确定方案。结合上表读取所需文档，先找可复用的同类实现，再修改所属模块。 -4. 文档和运行结果不一致时，追查当前源码、配置与版本，区分实现缺陷和文档过期； - 按 [文档职责与更新条件](../../../CONTRIBUTING.md#文档职责与更新条件) 判断是否修订，不为每次改动追加文档或发布说明。 -5. 交付前按文档职责逐段复核最终文档 diff：新增内容是否回答当前读者的使用或维护问题，是否属于该文档， - 是否与其他位置重复，脱离本次变更背景能否独立理解。仅解释实现经过、前后对比或验证结果的内容移到 - 任务报告或 PR；仍影响升级、恢复的说明保留适用条件与操作。没有文档差异时，只核对行为变化是否使现有说明失真。 -6. 按 `CONTRIBUTING.md` 验证并报告结果。后端 Cargo 命令从 `backend/` 执行，或显式指定该目录的 manifest。 - -发布任务按 `release` 技能读取当前版本、发布入口和工作流，发布说明语言遵循 `CONTRIBUTING.md`。 diff --git a/.agents/skills/dev-guide/agents/openai.yaml b/.agents/skills/dev-guide/agents/openai.yaml deleted file mode 100644 index 7671f3acc..000000000 --- a/.agents/skills/dev-guide/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "dev-guide" - short_description: "从仓库规范与架构文档定位实现、验证和交付的正确入口" - default_prompt: "使用 $dev-guide 按当前仓库规范与架构完成开发、验证或发布。" diff --git a/.agents/skills/github-issue/agents/openai.yaml b/.agents/skills/github-issue/agents/openai.yaml deleted file mode 100644 index 8cb53bdfc..000000000 --- a/.agents/skills/github-issue/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "github-issue" - short_description: "按仓库表单整理复现证据、检查重复反馈并提交脱敏 Issue" - default_prompt: "使用 $github-issue 将当前问题整理为符合仓库表单的 Issue 并提交。" diff --git a/.agents/skills/github-pr/agents/openai.yaml b/.agents/skills/github-pr/agents/openai.yaml deleted file mode 100644 index 0082dac91..000000000 --- a/.agents/skills/github-pr/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "github-pr" - short_description: "创建与审查拉取请求，先核实问题，以官方源码为首要依据确定或评估实现方案" - default_prompt: "使用 $github-pr 按当前请求创建或审查 PR，先核实问题是否成立，以官方源码为首要参考确定或评估解决方案，说明源码依据及必要的偏离原因，并按仓库规范实现与验证或报告审查结论。" diff --git a/.agents/skills/plugin-dev/agents/openai.yaml b/.agents/skills/plugin-dev/agents/openai.yaml deleted file mode 100644 index 95bd68775..000000000 --- a/.agents/skills/plugin-dev/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "plugin-dev" - short_description: "从能力选择到 SDK 实现、管理页面、打包与验证的插件开发指南" - default_prompt: "使用 $plugin-dev 为 Codex Proxy RS 开发插件，先确认需要的能力，再按公开 SDK 实现、打包并验证。" diff --git a/.agents/skills/release/agents/openai.yaml b/.agents/skills/release/agents/openai.yaml deleted file mode 100644 index b9d4f030d..000000000 --- a/.agents/skills/release/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "release" - short_description: "按仓库流程准备稳定版或实验版的中文说明，完成发行与渠道验证" - default_prompt: "使用 $release 按指定的稳定版或实验版渠道准备中文发布说明，并核对发版条件。" diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 000000000..112fe2909 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,20 @@ +## 问题与改动 + + + +## 自审与验证 + + + +## 页面截图 + + + +## AI 使用 + + diff --git a/AGENTS.md b/AGENTS.md index 945da188f..bcda97aa1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,17 @@ # 项目协作约定 -开发和审查先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，使用其中的协作流程和审查标准。 +按用户意图和当前会话主动加载并执行仓库技能，不要求用户写出 `$技能名`： + +| 任务意图与常见说法 | 必用技能 | +| --- | --- | +| 开发、实现、修复、排查报错、审查问题或代码、修改文档 | [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) | +| 写网关插件、修改插件能力、排查插件接入、打包插件 | [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)。 模块职责以 [系统架构](docs/architecture.md) 为准，界面约定以 [管理端主题](docs/theme.md) 为准； 没有明确约定时保持与相邻实现一致，不把单次页面反馈扩展成全仓规则。 @@ -19,10 +30,13 @@ If there is no `.codegraph/` directory, skip CodeGraph entirely — indexing is - 开发和审查按 [问题与方案依据](CONTRIBUTING.md#问题与方案依据) 先核实问题，以官方源码为首要参考确定或评估方案。 - 先定位变更所属模块、同类实现和上下游调用关系，再选择最小合理改动。复用已有能力，也避免为尚不存在的需求增加抽象。 +- 提交前自审最终差异，先处理本次引入的职责混淆、重复规则、冗余状态和无依据的兼容分支；后端按 [后端自审](docs/architecture.md#后端自审) 追踪状态与资源生命周期，不能把自审留给 CI 或 PR 审查者。 +- 页面变更先复用已有页面设计与组件，不因个人偏好重排页面或另建交互。文案取舍遵循 [界面文案与信息层级](docs/theme.md#界面文案与信息层级)，页面 PR 必须提供 [实际截图](CONTRIBUTING.md#界面验证)。 - 代码注释使用中文，解释原因与边界；提交信息使用英文，沿用历史中的 Conventional Commits 格式。 - 按变更范围执行验证，记录命令、结果和缺口。跳过的测试不算通过；界面与集成行为需要对应运行证据，构建通过不能替代实际验收。 - 审查请求默认只读。修复、提交、推送和合并按用户当前授权执行；“本地验证通过”不等于用户已经审阅批准。 - 不读取或输出无关凭据，不把真实密钥、代理认证、账号令牌或请求转储放入提交、截图及审查报告。 +- 使用 AI 的 PR 按 [AI 使用披露](CONTRIBUTING.md#ai-使用披露) 写明实际模型型号，不以工具名称代替模型。 ## Code Review Rules @@ -36,8 +50,8 @@ If there is no `.codegraph/` directory, skip CodeGraph entirely — indexing is ### 代码与界面一致性 - 对重复逻辑、冗余状态和多余抽象给出具体位置及影响；建议复用时指出已有实现，不能仅凭行数或语法相似判定质量。 -- UI 变更对照项目基础组件、主题和同类页面，检查交互、状态、响应式与可访问性。局部问题是否应在共用组件修复，按职责判断，不一律禁止局部样式。 -- 核对截图、预览和实际交互证据；未检查的状态明确列为验证缺口，不推断视觉验收已经通过。 +- UI 变更对照原页面、项目基础组件、主题和同类页面，检查布局变化是否服务本次需求、是否堆叠重复文案，以及交互、状态、响应式与可访问性。局部问题是否应在共用组件修复，按职责判断，不一律禁止局部样式。 +- 核对页面 PR 按 [界面验证](CONTRIBUTING.md#界面验证) 提供的截图与实际交互证据；缺少必需截图时明确要求补齐，未检查的状态列为验证缺口，不推断视觉验收已经通过。 ### 审查输出 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 64f4a9feb..3af7ae4e3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,8 +31,8 @@ ## PR 流程 -1. **准备变更。** 按上述依据核实问题与方案，找到所属模块、相关调用链和最接近的现有实现，在功能分支完成修改与自查。涉及架构、公开合同或较大交互变化时，先说明方案与取舍。 -2. **发起 PR。** 目标分支使用 `main`。说明问题成立的依据、触发场景、改动后的行为和实际验证结果；涉及官方行为时注明源码位置、版本和方案关系。界面改动提供截图、录屏或可复现的预览方式。一个 PR 围绕一个明确目标，必要重构说明关联原因。 +1. **准备变更。** 按上述依据核实问题与方案，找到所属模块、相关调用链和最接近的现有实现，在功能分支完成修改。提交前自审完整差异，清理本次引入的重复逻辑、冗余状态与职责越界；后端按 [后端自审](docs/architecture.md#后端自审) 执行。涉及架构、公开合同或较大交互变化时，先说明方案与取舍。 +2. **发起 PR。** 目标分支使用 `main`，按 [PR 模板](.github/pull_request_template.md) 说明问题依据、触发场景、最终行为、自审和实际验证结果；涉及官方行为时注明源码位置、版本和方案关系。页面变更必须按 [界面验证](#界面验证) 附实际截图，使用 AI 时按 [AI 使用披露](#ai-使用披露) 写明模型。一个 PR 围绕一个明确目标，必要重构说明关联原因。 3. **自动检查与初审。** CI 执行适用的格式、静态分析、测试和构建检查；启用 AI 审查后，由它按本规范辅助检查语义、复用和一致性。提交者先处理明确问题，维护者重点审阅方案、风险与用户体验。 4. **修改与合并。** 更新代码后重新执行受影响的检查，确认审查意见已处理，验证证据对应当前变更。维护者审阅批准后再合并；需要升级说明的变更同步相关文档。 @@ -41,17 +41,25 @@ AI 开发和审查入口是根目录的 [AGENTS.md](AGENTS.md)。在仓库上下 ### 项目技能 仓库技能位于 `.agents/skills/`，随代码共享。技能提供执行流程，协作与审查标准仍以本文和 `AGENTS.md` 为准。 +AI 开发、排查、代码审查和文档修改必须执行 `cpr-dev-guide`；准备、创建、更新及审查 PR 必须执行 `cpr-github-pr`，不以用户是否显式点名技能为条件。PR 内修复仍须经过开发流程，不能用填写 PR 正文代替实现自审与验证。 | 技能 | 用途 | 调用示例 | | --- | --- | --- | -| [dev-guide](.agents/skills/dev-guide/SKILL.md) | 项目开发与文档导航 | `$dev-guide 修复当前问题` | -| [plugin-dev](.agents/skills/plugin-dev/SKILL.md) | 网关插件开发、打包与验证 | `$plugin-dev 开发一个添加响应头的插件` | -| [github-pr](.agents/skills/github-pr/SKILL.md) | 创建或审查 PR | `$github-pr 创建当前分支的 PR` / `$github-pr 审查 PR #编号` | -| [github-issue](.agents/skills/github-issue/SKILL.md) | 整理或提交 Issue | `$github-issue 提交当前问题` | -| [release](.agents/skills/release/SKILL.md) | 准备发布说明或正式发版 | `$release 整理本次发布说明` / `$release 发布 vX.Y.Z` | +| [cpr-dev-guide](.agents/skills/cpr-dev-guide/SKILL.md) | 项目开发与文档导航 | `$cpr-dev-guide 修复当前问题` | +| [cpr-plugin-dev](.agents/skills/cpr-plugin-dev/SKILL.md) | 网关插件开发、打包与验证 | `$cpr-plugin-dev 开发一个添加响应头的插件` | +| [cpr-github-pr](.agents/skills/cpr-github-pr/SKILL.md) | 准备、创建、更新或审查 PR | `$cpr-github-pr 创建当前分支的 PR` / `$cpr-github-pr 审查 PR #编号` | +| [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 自动审查。 +### AI 使用披露 + +PR 正文说明提交者是否使用 AI。使用 AI 参与方案、代码、文档、测试或自审时，写明工具名称和实际模型型号；使用多个模型时分别列出，可简述各自参与范围。 +`Codex`、`ChatGPT`、`Claude Code` 等工具或产品名称不能代替模型型号，优先填写工具显示或调用配置中的具体模型标识。 +无法获知型号时如实标记「型号未提供，待补充」，不能猜测或伪造，也不能把待补信息称为已完成披露；补齐前保留 Draft。 +更新 PR 时同步新增的模型信息；这一披露不替代提交者自审、验证责任或已有提交署名约定。 + ### 规则文件保护 PR 不接受根目录或子目录中 `AGENTS.md` 的新增、修改、删除或重命名。调整这些文件时先提交 Issue 说明原因和建议，由维护者处理；[规则保护工作流](.github/workflows/agents-md-guard.yml) 会提示并关闭包含此类变更的 PR。撤销相关变更后可以重新打开 PR，继续正常检查。 @@ -99,7 +107,7 @@ PR 不接受根目录或子目录中 `AGENTS.md` 的新增、修改、删除或 只有改动使对应说明失真、缺少必要信息，或改变读者需要执行的操作与判断时，才更新文档。 内部修复、重构和界面微调不默认附带文档改动；审查时不能仅因 PR 没改文档就判定存在缺口。 -- 按 [开发指南的文档入口](.agents/skills/dev-guide/SKILL.md#按任务读取) 找到内容所属文档，在原有章节就地修订， +- 按 [开发指南的文档入口](.agents/skills/cpr-dev-guide/SKILL.md#按任务读取) 找到内容所属文档，在原有章节就地修订， 不按每次变更追加说明。同一事实只保留一处完整说明，其他文档按读者任务提供必要摘要和链接。 - API 文档保留调用所需的字段、状态、语义和限制；架构文档保留职责与不变量；部署文档保留配置、操作和排障。 不把界面布局、内部锁或索引实现写进接口说明，也不把前端库的实现选择写进部署说明。 @@ -110,13 +118,21 @@ PR 不接受根目录或子目录中 `AGENTS.md` 的新增、修改、删除或 ## 界面验证 -AI 进行前端开发时，加载并使用 `$frontend-design` 技能。设计方案以本项目的用户任务、[管理端主题](docs/theme.md) 和已有组件为依据，在任务范围内改进布局、视觉与交互。 +AI 进行前端开发时，加载并使用 `$frontend-design` 技能。设计方案以本项目的用户任务、[管理端主题](docs/theme.md) 和已有页面为依据，优先延续原页面的布局、信息层级与交互；设计技能不构成重做页面的理由。 -开发前查找同类页面及`modules/ui/src/components` 中的基础组件，优先使用已有主题 Token、交互和数据展示逻辑。需要扩展时在对应职责层修改；局部样式的适用范围遵循主题文档，不一律禁止，也不靠页面覆盖掩盖共用组件的问题。 +开发前查找原页面、同类页面及 `modules/ui/src/components` 中的基础组件，明确参考实现和可复用部分，再确定最小改动。只有原设计不能满足本次操作或存在具体问题时才调整结构，并在 PR 中说明原因；不顺带换风格、重排无关区域或增加重复的模式入口。需要扩展时在对应职责层修改；局部样式的适用范围遵循主题文档，不一律禁止，也不靠页面覆盖掩盖共用组件的问题。 列表列宽、序号、按钮、分页和弹窗尺寸由实际任务与数据规模决定，以同类页面为参照。新增或调整交互时说明用户需要完成什么操作，不把某个页面的取舍推广成全局禁令。 -提交者在浏览器中验证受影响路径，提供前后截图、录屏或预览步骤，并标明实际覆盖的状态。按变更选择浅色/深色、窄窗口、空/加载/错误状态、大量数据及键盘操作；共用主题或基础组件变更按主题文档扩大验证范围。模拟数据与预览材料不包含真实凭据。 +提交者在浏览器中验证受影响路径，页面变更的 PR 必须提供实际运行截图，包括布局、文案、样式和交互状态的变化： + +- 修改现有页面提供变更前后截图，尽量保持相同数据、主题和窗口尺寸；新增页面提供完成态截图。截图保留必要上下文，让审查者能判断布局和信息密度，不只截取孤立控件。 +- 按影响范围补充浅色/深色、窄窗口及空/加载/错误等受影响状态；共用主题或基础组件变更按主题文档扩大验证范围。弹出层中的内容需展示展开状态，不能只截关闭后的页面。 +- 在 PR 正文嵌入或链接审查者可访问的图片，注明页面入口、状态和对应提交。录屏、预览地址和复现步骤用于补充，不能替代截图；本机绝对路径不算可供远端审阅的附件。 +- 视觉或交互继续修改后更新受影响截图，使证据对应待审实现。截图与模拟数据不得包含真实凭据，不用设计稿、生成图片或旧版截图冒充运行结果。 +- 环境不足时说明缺少的截图和交互验证，不宣称验收通过；页面 PR 在截图补齐前保留 Draft，不标为可审阅或建议合并。 + +截图用于视觉审阅，保存、切换、错误恢复和键盘操作等行为仍需实际验证并记录覆盖范围，不能仅凭静态图片推断交互正确。 涉及浏览器能力或访问环境差异时，按项目支持的部署方式核对相关 HTTP/HTTPS、localhost/实际部署地址与浏览器版本，记录实际覆盖的条件；本地预览正常不能替代部署环境中的交互验收。 diff --git a/backend/crates/gateway-plugin/sdk/README.md b/backend/crates/gateway-plugin/sdk/README.md index 25780fe6a..ae49044c2 100644 --- a/backend/crates/gateway-plugin/sdk/README.md +++ b/backend/crates/gateway-plugin/sdk/README.md @@ -15,7 +15,7 @@ SDK 仍处于实验阶段；能力是否可用取决于宿主支持、清单声 打包 → [安装、配置与启用](../../../../docs/plugins.md)。完整可运行示例位于独立仓库 `codex-proxy-plugins` 的 `examples/workbench`。 -使用 AI 协作开发时，可调用仓库技能 [`$plugin-dev`](../../../../.agents/skills/plugin-dev/SKILL.md)，按任务定位合同、示例和验证入口。 +使用 AI 协作开发时，可调用仓库技能 [`$cpr-plugin-dev`](../../../../.agents/skills/cpr-plugin-dev/SKILL.md)，按任务定位合同、示例和验证入口。 ## 模块与依赖 diff --git a/docs/architecture.md b/docs/architecture.md index a3baaee25..0a4984340 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -721,6 +721,20 @@ PostgreSQL 备份恢复属于人工维护操作。当前没有部署级维护模 变更应落在拥有该事实的边界：协议适配进 API，执行策略进 Core，Provider 差异进对应 Provider，持久化 实现进 Store，生命周期进 Host，管理规则进 Admin。不要用兼容 shim、第二套状态机或跨层旁路绕开 owner。 +### 后端自审 + +提交前沿受影响的完整调用链复核最终差异，不能只读新增函数或等待 CI、PR 审查者发现问题。按改动涉及的职责检查： + +- **职责归属**：说明业务决定由哪个模块负责、哪些层只传递合同或投影结果，对照 [Workspace 边界](#3-workspace-边界) 与现有同类路径，避免调用方重新解释被调用方已拥有的规则。 +- **事实与状态**：同一解析、校验、错误分类和业务规则复用所属模块的实现；检查新增字段、缓存、标志或状态机能否由已有状态推导，避免多个可写来源。必要缓存明确更新、失效与并发约束。 +- **失败与资源**：从成功、错误、取消和超时出口核对事务、锁、连接、任务与租约的释放；涉及异步清理时确认返回后的下一次操作不会被尚未完成的清理误挡。 +- **并发与副作用**：按实际改动核对 revision、幂等、重试、部分成功与过期结果，明确谁提交状态、谁发布变化、谁负责重试，不在不同层重复补偿或放宽既有隔离合同。 +- **必要性与验证**：删除本次引入的重复分支、无用转换、死代码和无明确职责的转发包装；保留特殊分支需说明真实场景。测试覆盖可观察结果与失败条件，不靠增加防御代码或改弱断言让检查通过。 + +在 PR 中简述与本次变更相关的归属、复用判断和验证结果，标明仍未覆盖的边界；无需复制整张检查清单，也不借自审扩大为无关重构。 + +### 验证命令 + 后端验证从 `backend/Cargo.toml` 执行，仓库根目录没有 Cargo manifest： ```bash diff --git a/docs/theme.md b/docs/theme.md index 0febe0ab8..a2473dba2 100644 --- a/docs/theme.md +++ b/docs/theme.md @@ -40,11 +40,16 @@ 管理端以查看状态和完成操作为主，延续紧凑的信息布局、清楚的主次关系，以及表面色差、间距和轻阴影构成的层级 +- **先沿用已有设计**：先看原页面和最接近的同类实现，复用布局、控件、操作位置与状态展示，新增能力优先融入原有操作路径 + 只有现有设计无法承载本次任务时才改变结构，并说明具体问题，不以个人审美或设计技能中的通用建议为由重做页面 - **文案不使用句号和分号**：自行编写的标题、标签、按钮、表单帮助、空状态、提示和错误文案不使用 `。`、句末 `.`、`；` 或 `;`，优先写成短语或简短分句 需要表达多个要点时，按内容关系拆成字段、短行或列表，不把长段落机械替换成逗号串 这项约定针对界面文案，URL、版本号、小数、代码、原始日志和用户输入保留原样 -- **说明只补必要信息**：标题和操作已能表达的内容不再用副标题重复，帮助文字贴近对应控件，扩展说明按需放入帮助入口或折叠区域 - 影响操作选择的限制、错误原因和不可逆后果仍在操作处清楚展示，简化时保留含义 +- **说明只补必要信息**：标题、字段值和操作已能表达的内容不再重复，不同时用帮助文字、状态行和说明卡解释同一事实 + 页面保留当前决策必需的短提示，详细规则、背景原因、示例和低频帮助优先收进已有 Popover 或就近的帮助入口，不把实现细节写成用户教程 + 重要说明可以在 Popover 中展开，但影响当前选择的关键限制、错误原因和不可逆后果需在操作处保留简明提示，不能全部藏起来 +- **按内容选择提示方式**：Tooltip 用于短名称或单句补充，Popover 用于需要阅读、多段说明或含链接的内容，复用项目现有组件 + 帮助入口需可识别、可通过键盘和触屏打开，图标提供可访问名称，不依赖悬停才能读到必要内容 - **避免大字报**：不堆叠超大标题、口号、整屏介绍、重复副标题或大段说明卡片，页面尽快进入数据、筛选和操作 页面标题与关键指标沿用已有组件的强调方式，辅助说明使用正文或次级文字层级，不通过放大字号、加粗整段或增加大块留白来突出普通说明 - **按任务组织空间**：优先使用紧凑的工具栏、表格、表单和必要的指标卡，卡片承担独立的信息或操作职责，不为每段说明单独套卡 @@ -414,6 +419,7 @@ utility / arbitrary variant；Vue Transition、跨浏览器 Range、动态富文 ## 验证 基础检查与受影响页面的验收按 [贡献与审查](../CONTRIBUTING.md#界面验证) 执行。 +对照前后截图复核是否改变了无关区域、增加重复说明或不必要的空白，帮助内容收进浮层后检查入口可发现性与展开状态。 修改主题派生、主题编辑器或共用组件的视觉行为时，按影响范围补充以下检查： - 四个预置、自定义 HEX、浅色、深色和跟随系统模式。