starred/codex-proxy-rs
1
0
Fork 0
mirror of https://github.com/zyycn/codex-proxy-rs.git synced 2026-11-06 08:06:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(skills): streamline routing and clarify development boundaries

Browse Source 
Co-authored-by: Codex <noreply@openai.com>
This commit is contained in:
Zyy
2026-10-18 04:14:22 +08:00
co-authored by Codex
parent 733e9aa8a0
commit 72bdc234ca
14 changed files with 123 additions and 119 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/cpr-dev-guide/SKILL.md
+20 -37
View File
@@ -1,59 +1,42 @@
---
name: cpr-dev-guide
description: Codex Proxy RS 仓库的开发、修复、排障、代码审查和文档修改入口；PR、Issue、插件创作与发版按任务另用对应技能
description: Codex Proxy RS 前后端开发、排障、代码审查和文档修改入口；改页面、弹窗、样式、文案，修接口、调度、数据库、Rust、宿主 SDK 或 Runtime 时均使用；PR、Issue、独立网关插件与发版另配对应技能
---
# 开发指南
## 参考仓库的优先级
## 先匹配任务与文件
**Codex 兼容性优先保持官方行为，以透明转发和最小必要适配为默认方案；这是开发、排障与审查的前置约束，不只是引用资料的要求**
按用户要改的行为初判，定位后按实际修改或审查的文件复核，不要求用户说出“前端”“后端”或技能名。**命中多行就同时执行，先读取对应规范再修改或给出审查结论**；任务范围变化时补齐新命中项，已有上下文直接复用
- 以官方 [openai/codex](https://github.com/openai/codex) 对应版本的源码与调用链为第一手资料，先查用户提供或本机已有的官方仓库，核对来源、版本或提交；资料不足时再查官方对应版本的源码、测试与文档
- 先对照官方与 CPR 的实际请求、响应及状态生命周期，确认本项目是否改写、遗漏或破坏官方合同；真实上游报错不自动等于 CPR 缺陷，源码推断、代理链路复现与官方直连结果分别说明
- 官方路径已能满足场景时，优先复用已有能力或正确透传合同，不额外解释请求意图、扩展工具权限或改变续接语义；补偿后请求成功、测试通过或第三方采用同一做法，都不能单独证明代理应改变行为
- 偏离官方行为必须说明官方路径为何不足、本项目的实际约束、最小必要改动及行为代价，并提供对应验证；依据不足时保持现有合同并报告缺口，不先加兼容分支再以通过测试作为必要性依据；用户明确要求的行为变更限定在授权范围内
- 网关独有的调度、隔离和资源管理按本项目职责评估，不能机械照搬单客户端实现，也不能借此任意改变客户端可观察行为；新增默认限制或回收阈值须有实际容量依据，并验证对续接、重试与延迟的影响
- 三方仓库只作线索或实现参考，不能替代官方行为依据；结论注明适用版本或提交，区分官方事实、三方参考与本项目推断，不把自定义策略表述为官方要求
## 加载边界
- 遵守已提供的 [AGENTS.md](../../../AGENTS.md)，上下文已有的规则不重复读取
- 下表是条件导航，不是必读清单，只加载当前任务命中的技能与章节，进入新阶段再补读
- 文档链接带 `#章节` 不代表读取工具会自动截取内容，先用 `rg -n '^#{1,4} ' 文件` 找边界，再按范围读取；常规定位不整份加载 CONTRIBUTING、架构、API、主题或全部 references，确需全文审查时再展开
- 每次补读先明确要解决的未知项，已有资料足够就继续工作；文档提及 Rust、Vue、插件或发布，不等于要加载对应开发流程
## 按任务读取
| 当前任务 | 必读的相关部分 |
| 命中条件，操作或文件满足其一即可 | 必须执行 |
| --- | --- |
| 开发、排障、代码审查 | [问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)，需要定位代码时按 AGENTS 的 CodeGraph 约定执行 |
| 调整页面、弹窗、表单、按钮、文案、样式或交互；目标在 `frontend/`、`modules/ui/`、插件前端，或是 `.vue` 文件 | [前端流程](references/frontend.md)，覆盖组件复用、文案、Token、样式、视觉状态和运行证据；局部修改同样执行 |
| 修改服务端接口、路由、调度、账号与用量规则、持久化、后台任务或协议行为；目标是 `backend/` 中的实现、配置、迁移，或 Rust 源码 | [Workspace 边界](../../../docs/architecture.md#3-workspace-边界)、所属模块、[后端自审](../../../docs/architecture.md#后端自审)；涉及 Rust 时使用 `$rust-best-practices` 和下方后端注释要求，验证时读[命令](../../../docs/architecture.md#验证命令) |
| 修改页面接口调用，或开发、排查、审查面向管理端或模型客户端的 HTTP／WS API 合同 | [API](../../../docs/api.md)对应章节；优先复用已有接口，核对调用方 → 服务端解析 → 实际查询或执行，不能只凭前端类型认定参数生效；按实际改动叠加前后端规范 |
| 模块或调用链变更 | [Workspace 边界](../../../docs/architecture.md#3-workspace-边界)及所属模块章节，不通读整份架构 |
| Rust 开发或审查 | `$rust-best-practices`、所属模块、[后端自审](../../../docs/architecture.md#后端自审)，验证时读[命令](../../../docs/architecture.md#验证命令) |
| 页面开发 | `$frontend-design`、[前端职责](../../../docs/architecture.md#34-前端模块职责)、[文案与信息层级](../../../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) |
| 修改部署行为、`deploy/` 配置或数据库迁移 | 按范围读取[部署](../../../deploy/README.md)、[迁移](../../../backend/migrations/README.md)对应章节 |
| 开发、排查或审查宿主 SDK、Runtime、扩展接口或独立插件；目标在 `backend/crates/gateway-plugin/` | [插件职责边界](references/plugin-boundaries.md)及所用 [SDK](../../../backend/crates/gateway-plugin/sdk/README.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 |
纯文档任务按文档分支执行，不因文档所在目录或提及的路径、语言、功能加载开发流程。每次补读只解决当前未知项；文档链接带 `#章节` 不代表工具自动截取，先用 `rg -n '^#{1,4} ' 文件` 找边界，只读命中章节，不预读整份 CONTRIBUTING、架构、API、主题或全部 references，全文审查除外
## 参考仓库的优先级
开发、排障和代码审查先按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)核实问题与方案。涉及 Codex 行为时执行其中的官方行为优先约束：对应版本的官方源码优先，以透明转发和最小必要适配为默认方案，先判断偏离是否必要再评价实现
## 执行与收尾
1. 确认工作区、任务范围与已有改动，先定位事实归属、同类实现和调用链，再修改；编码前只读[项目约定](../../../CONTRIBUTING.md#项目约定)的对应条目
2. 自审完整差异，处理本次引入的职责越界、重复规则、冗余状态与无依据分支；仅审查时报告，不自行修复
3. 按变更范围读取[验证](../../../CONTRIBUTING.md#验证)，区分通过、失败、跳过与未执行；提交时补读[提交约定](../../../CONTRIBUTING.md#项目约定)
4. 交付说明实际结果与验证缺口；页面证据和后端生命周期检查按上表执行，不把构建通过当作行为验收
1. 遵守已提供的 [AGENTS.md](../../../AGENTS.md)，按其 CodeGraph 约定定位代码；确认工作区、任务范围与已有改动，找到事实归属、同类实现和调用链，补齐上表命中规范及[项目约定](../../../CONTRIBUTING.md#项目约定)对应条目后再修改
2. 自审完整差异，处理本次引入的职责越界、重复规则、冗余状态与无依据分支；删除或替换功能时一并清理失效的配置、类型、调用、测试与文档，已部署数据和公开合同仍遵守所属迁移及兼容规则；仅审查时报告，不自行修复
3. 常规文档只写当前状态；有文档差异时执行[文档检查](references/documentation.md)，没有时只确认现有说明是否失真，普通开发不自动修改 `release/notes.md`
4. 按变更范围执行[验证](../../../CONTRIBUTING.md#验证)及其停止条件，沿用本轮有效证据与用户已确定的验收分工，区分通过、失败、跳过与未执行；提交时补读[提交约定](../../../CONTRIBUTING.md#项目约定)
5. 交付实际结果与验证缺口；前端按[前端流程](references/frontend.md)核对最终差异和运行证据，后端按上表检查生命周期，不把构建通过当作行为验收
## 后端注释
- 每个 Rust 文件顶层使用简短的中文 `//!` 注释说明文件职责，覆盖生产源码、测试与构建脚本；测试文件说明测试范围或辅助用途，生成文件同步维护生成器
- 注释不使用中文或英文句号，多句说明按语义分行；保留 URL、版本号、标识符和代码示例中有语义的点号
- 文件说明聚焦当前功能与职责边界，局部注释解释原因和约束，避免复述代码或记录修改经过
## 文档硬约束
**常规文档只描述当前状态，不写变更历史**，这项检查适用于每次开发收尾，不限于专门的文档任务
- 动笔前确定读者、所属章节与必须说明的当前事实，没有必要就不改文档
- 有文档差异时执行[文档检查](references/documentation.md)，逐段决定保留、改写、删除或移入任务报告，未完成内容审查不能称文档已检查
- 没有文档差异时只确认现有说明是否失真；普通开发不自动修改 `release/notes.md`
.agents/skills/cpr-dev-guide/agents/openai.yaml
+2 -2
View File
@@ -1,6 +1,6 @@
interface:
display_name: "cpr-dev-guide"
short_description: "仓库开发、修复、排查、代码审查与文档修改的流程入口"
default_prompt: "使用 $cpr-dev-guide 按当前任务定位问题与现有实现，完成已授权的开发或审查，并自审、验证和报告结果。"
short_description: "前后端开发、排障与审查入口，按任务和文件匹配规范并验证"
default_prompt: "使用 $cpr-dev-guide 按请求和实际文件匹配前后端规范，读取命中项后完成已授权的开发或审查，并自审、验证和报告结果。"
policy:
allow_implicit_invocation: true
.agents/skills/cpr-dev-guide/references/documentation.md
+4 -11
View File
@@ -1,16 +1,10 @@
# 文档检查
仅在准备修改文档或最终差异含文档时读取，职责与行文依据是 [文档职责与更新条件](../../../../CONTRIBUTING.md#文档职责与更新条件)，只读该节
修改或审查文档时读取，职责与行文统一按 [文档职责与更新条件](../../../../CONTRIBUTING.md#文档职责与更新条件)，只读该节
## 写之前
先明确这段内容服务谁、解决哪个当前使用或维护问题、属于哪个现有章节，再决定详略
接口保留调用合同，架构保留职责与不变量，部署保留操作与排障；同一事实只在所属位置完整说明，其他位置链接
常规文档在原章节修订，不追加本次变更小节，不为了“同步文档”补写修复总结
内部重构、实现经过、前后对比、验证结果应留在 PR、Issue 或任务报告
先确定读者、必须说明的当前事实与所属章节，再决定是否需要修改及详略；文档职责与更新条件按上节核对
## 逐段验收
@@ -30,9 +24,8 @@
## 交付检查
- 检查新段落的必要性、归属、重复与当前状态表达，发现变更叙述先改完再交付
- 标题、短列表、表格和独立短段通常不加句号，长段按主题拆分，命令与字段保持准确
- 完成上述逐段验收及[行文检查](../../../../CONTRIBUTING.md#层次与行文)，发现问题先处理，未完成内容审查不能称文档已检查
- 检查相对链接、章节锚点、表格与命令示例，`git diff --check` 或构建通过不能代替内容审查
- 报告实际覆盖和缺口即可，不把检查记录写进常规文档
只有明确的发布说明任务才进入 `cpr-release`，`release/notes.md` 用于该次发行，不向 README、API、架构或部署文档复制版本变化列表
只有明确的发布说明任务才进入 `cpr-release`；发布说明与常规文档的边界按[内容归属](../../../../CONTRIBUTING.md#内容归属)执行
.agents/skills/cpr-dev-guide/references/frontend.md
+32
View File
@@ -0,0 +1,32 @@
# 前端开发与审查
适用于页面、组件、弹窗、表单及局部文案和样式修改，不以是否创建 PR 为触发条件；仅审查时核对和报告，不自行修改
## 开始前
读取[前端职责](../../../../docs/architecture.md#34-前端模块职责)、[文案与信息层级](../../../../docs/theme.md#界面文案与信息层级)和[界面验证](../../../../CONTRIBUTING.md#界面验证)，明确本次用户操作、原页面、最接近的同类实现及可复用基础组件；按本轮验收分工留存所需截图
用户要求看效果或自行验收时，按[源码联调](../../../../docs/development.md#源码联调)提供当前工作区的可访问预览与页面入口，确认热更新和依赖来源；需要模拟数据时用于实际页面并标明，不把静态稿、旧构建或仅有本机文件路径当作可用预览
按改动补读，不把“未修改主题算法”当作跳过页面样式规范的理由：
| 改动 | 规范入口 |
| --- | --- |
| Vue 逻辑、请求或状态 | [项目约定](../../../../CONTRIBUTING.md#项目约定)的前端条目及上述前端职责 |
| 颜色、间距、字体、边框、阴影、局部 CSS 或交互样式 | [通用颜色消费](../../../../docs/theme.md#通用颜色消费)、[样式与命名约定](../../../../docs/theme.md#样式与命名约定)，核对无边常态及 Hover、Focus 等视觉状态 |
| 主题算法、编辑器或共用组件视觉行为 | 所改主题章节及[扩大验证范围](../../../../docs/theme.md#验证) |
| 明确指定设计技能，或建立、重塑视觉方向 | 使用指定技能或 `$frontend-design`，设计取舍仍以项目主题、用户任务和已有页面为依据 |
普通维护和新增业务页面沿用现有设计；设计技能中的配色、字体、布局探索不覆盖项目规范，主题算法只在涉及时读取
## 交付前
对照最终差异和实际页面逐项核对，不以读取过规范代替检查：
- **复用与范围**：是否沿用参考页面和基础组件，已有组件能承载时不手写替代控件；共用缺陷按职责修复，修复后清理本次已失效的页面补丁，不顺带重排无关区域或新增重复入口
- **文案与层级**：标点是否合规，标题、状态和帮助是否重复，详细说明与当前决策必需提示的位置是否合适
- **样式与状态**：是否使用对应 Token 与 utility，局部样式是否符合适用边界，受影响的主题、窄屏及交互状态是否正确
- **查询与动作**：区分首次加载、刷新、分页、单行与批量操作，核对 loading、禁用状态的影响范围；沿用请求层错误处理，不在页面叠加同一错误的提示
- **运行证据**：按界面验证核对截图与实际交互，证据对应当前实现；页面 PR 的可访问图片和 Draft 条件按该节执行
交付简述所复用的页面或组件、实际验证范围及缺口；环境不足时如实说明，不能仅凭构建、源码或截图推断未验证的行为
.agents/skills/cpr-dev-guide/references/plugin-boundaries.md
+7 -3
View File
@@ -3,9 +3,13 @@
仅在开发或审查 SDK、Runtime、宿主扩展接口及独立网关插件时读取
先看[插件扩展](../../../../docs/architecture.md#31-插件扩展)中的职责与执行边界，不通读整份架构
**宿主可以暴露底层能力，不能替插件完成业务**
**宿主提供可组合能力，守住自身合同、资源与稳定性；插件业务正确性和兼容修复由插件负责**
- 宿主提供可独立组合的受控原生能力，负责授权、资源隔离、事务与审计，复用已有服务与状态归属
- 插件自身的触发条件、跨资源关联、策略和流程编排由插件实现，不能把某个使用场景做成宿主专属流程、状态或补偿逻辑
- 发现能力缺口时，界定可独立使用的基础接口，说明输入输出、权限、事务、失败及重复调用语义，不夹带插件私有数据模型或工作流
- 自审调用链、合同、测试与文档中的业务判断、自动串联和专属状态，仅换成通用名称不算解除耦合
- 插件行为不可预测，只保留宿主安全解码、权限、资源限制及一致性所需的检查，不为插件业务正确性增加语义校验、未知字段拒绝或重复检查；失败按已有调用、会话、实例边界及能力策略拒绝、隔离和回收，不把单次业务错误扩大为全局停用
- 不靠猜测插件意图、补造业务字段、修正业务结果、重放操作或增加插件专属兼容分支让错误插件继续工作；问题归插件时在插件侧修复，不把补偿搬进宿主 SDK 或 Runtime
- 通用协议与会话辅助、公开合同规定的默认值和失败恢复仍按既有合同执行，不能因拒绝业务兜底而删掉必要的宿主保护；故障隔离按[信任与资源边界](../../../../docs/architecture.md#信任与资源边界)评估，不假定完整信任的插件具有安全沙箱
- 开放已有能力时复用宿主服务与数据模型，不为插件的导入、修正、重算等编排新增表、字段、账本或任务系统；确有宿主能力缺口时，界定可独立使用的基础接口及输入输出、权限、事务、失败和重复调用语义，不夹带插件私有模型与工作流
- 新增防御、兼容、重试、缓存或状态前，说明要保护的宿主不变量、触发依据和最小处理范围；仅为迁就某个插件或猜测未来行为时不加入宿主
- 自审调用链、合同、测试与文档中的业务判断、自动串联和专属状态，仅换成通用名称不算解除耦合；验证失败与取消后的资源释放、状态一致性和其他调用受影响范围，不以插件恢复成功代替宿主边界验证
.agents/skills/cpr-github-issue/SKILL.md
+3 -8
View File
@@ -20,7 +20,7 @@ description: 草拟、创建、补充或回复 GitHub Issue，包括缺陷、功
- 其他仓库读取它自己的相关规则与实际模板，长文档先定位标题再截取，不预读全部模板或 CONTRIBUTING
- 搜索同场景 open/closed Issues、相关 PR 和发布记录，区分主分支修复与已发布修复，不凭标题判断重复；没有新证据时返回已有链接，用户仍要求新建则按其要求处理
- 仅当需要额外排查或修改时使用 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)，提交症状反馈不以找到根因为前提
- 引用上游行为或提出方案时读取[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)，涉及 Codex 时执行[官方行为优先约束](../cpr-dev-guide/SKILL.md#参考仓库的优先级)；注明适用版本、来源与缺口，不把上游报错直接定性为 CPR 缺陷，也不把第三方补偿方案当成预期行为；症状反馈仍不以证明根因为前提
- 引用上游行为或提出方案时执行[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)，注明适用版本、来源与缺口
## 正文与证据
@@ -36,16 +36,11 @@ YAML 表单按 `attributes.label` 和字段顺序组织正文，手工核对必
附件须获授权且可访问，本机路径不算附件；labels 和 assignees 仅按模板或用户要求设置，并确认实际存在
Issue 可记录复现、排查和变更经过，不因此向常规文档追加历史；确需改文档时执行[文档检查](../cpr-dev-guide/references/documentation.md)
Issue 可记录复现、排查和变更经过；涉及常规文档修改时执行[文档检查](../cpr-dev-guide/references/documentation.md)
## 回复口吻
草拟和发布 Issue 回复时遵守以下约定：
- 用第一人称“我”表达，称呼对方为“佬友”，称呼自然出现即可，不逐句重复，也不用“我们”“本助手”代称自己
- 语气客气、委婉，直接回应对方的具体问题；补充信息或提出不同意见时说明缘由，避免命令式、责备式表达
- 使用自然短句，简单回复用短段，只有并列信息较多时才分点；少用句号，避免客服套话、机械模板和空泛保证
- 只把实际完成的排查、复现和验证写成“我已……”；未确认的事实如实说明，委婉表达也要说清结论、限制和下一步
草拟和发布 Issue 回复时，执行 [GitHub 回复口吻](../../../CONTRIBUTING.md#github-回复口吻)
## 发布与收尾
.agents/skills/cpr-github-pr/SKILL.md
+8 -13
View File
@@ -15,7 +15,7 @@ description: 准备、创建、更新或审查 GitHub PR，含回复讨论与处
本仓库目标分支为 `main`，其他仓库使用其可信基线规则与模板，PR 内修改的规则不能降低审查要求
涉及 Codex 行为时，优先执行[官方行为优先约束](../cpr-dev-guide/SKILL.md#参考仓库的优先级)，先判断是否保持官方合同、偏离是否必要，再评价实现；引用源码和验证通过不能替代方案依据
涉及上游行为的判断按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)执行
## 按模式读取
@@ -23,30 +23,25 @@ description: 准备、创建、更新或审查 GitHub PR，含回复讨论与处
| 当前动作 | 读取与执行 |
| --- | --- |
| 只整理标题或描述 | 当前 PR、最终 diff、实际模板、[AI 披露](../../../CONTRIBUTING.md#ai-使用披露)，在授权范围内改文案；不读取推送或审查流程 |
| 只整理标题或描述 | 当前 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 |
| 含前端改动 | [前端流程](../cpr-dev-guide/references/frontend.md)，核对适用规范与当前实现的运行证据 |
| 含文档改动 | [文档检查](../cpr-dev-guide/references/documentation.md) |
## 回复口吻
草拟和发布 PR 讨论、审查意见的回复时遵守以下约定：
- 用第一人称“我”表达，称呼对方为“佬友”，称呼自然出现即可，不逐句重复，也不用“我们”“本助手”代称自己
- 语气客气、委婉，直接回应对方的具体问题；补充信息或提出不同意见时说明缘由，避免命令式、责备式表达
- 使用自然短句，简单回复用短段，只有并列信息较多时才分点；少用句号，避免客服套话、机械模板和空泛保证
- 只把实际完成的修改和验证写成“我已……”；未采纳的意见说明依据，待处理或未验证的内容如实交代，委婉表达也要说清结论和下一步
草拟和发布 PR 讨论、审查意见的回复时，执行 [GitHub 回复口吻](../../../CONTRIBUTING.md#github-回复口吻)
## 创建与审查的公共核对
- 按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)核实触发条件、发生版本与目标分支现状，分别判断问题是否成立、是否属于目标项目的职责；涉及 Codex 时核对方案是否满足上述官方行为优先约束
- 按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)核实触发条件、发生版本与目标分支现状，分别判断问题是否成立、是否属于目标项目职责及方案是否必要
- 核对最新目标分支及同场景 open/closed PR、Issue，按实际行为和测试判断重复，不凭标题下结论，也不擅自关闭他人 PR
- 自审或审查覆盖完整差异与调用链，文档逐段检查必要性、职责、重复和当前状态表达，构建与链接检查不能代替内容判断
- 自审或审查覆盖完整差异与调用链，前端与文档按模式表检查
- 核对[AI 使用披露](../../../CONTRIBUTING.md#ai-使用披露)，填写实际工具与模型，不猜型号；必需截图或型号待补时保留 Draft
- 验证结果对应实际 head，区分通过、失败、跳过与未执行；无文档改动时只检查现有说明是否失真
- 验证结果对应实际 head，区分通过、失败、跳过与未执行；无文档改动时只核对现有说明是否失真
远程操作优先使用可用连接器，`gh` 显式指定 `--repo`，多行正文使用结构化字段或 `--body-file`
.agents/skills/cpr-github-pr/references/create.md
+5 -11
View File
@@ -6,19 +6,13 @@
不用提交日志拼接正文，也不假定仓库一定有模板。
2. 更新并确认 base/head，查看相对 merge-base 的完整差异和待提交内容；核对仓库的受保护文件与准入规则。
只纳入任务范围的文件和提交；需要整理时用独立功能分支，保留用户其他改动，不擅自改写已发布历史。
3. 按入口的公共核对，在目标分支基线核实问题，追踪官方与本项目的相关调用链，先确定解决方向再实现。
若改动已完成，也要据此复核问题与方案；需要修正时只修改已授权的范围。仅整理标题或正文时报告差异与缺口，
不自行修改实现。原问题不成立时不将它包装成已修复的缺陷；证据不足时明确保留结论。
按 `cpr-dev-guide` 完成实现自审；后端按 [后端自审](../../../../docs/architecture.md#后端自审) 核对归属、状态、失败出口与副作用，
页面先复用已有设计并检查文案密度。处理本次引入的冗余与越界问题，功能可用和检查通过不能替代可维护性自查。
3. 已完成的改动也须按入口公共核对复核问题与方案。原问题不成立时不包装成已修复的缺陷，证据不足时保留结论。
实现与自审按 [cpr-dev-guide](../../cpr-dev-guide/SKILL.md)执行，包括适用的后端生命周期和前端检查；需要修正时只修改已授权范围。
4. 查找同一来源仓库、head 和 base 的现有 PR；已存在则复用其链接，不重复创建。
更新现有标题或正文须在本次整理/更新请求范围内。
5. 按[验证](../../../../CONTRIBUTING.md#验证)执行适用检查。记录实际验证的提交或工作区状态，区分通过、失败、跳过和未执行。
有文档差异时按[文档检查](../../cpr-dev-guide/references/documentation.md)检查最终 diff；没有文档差异时，核对行为变化是否使现有说明失真。
页面改动按入口链接的界面验证要求补齐截图与实际交互证据，核对模型披露是否完整。
5. 按[验证](../../../../CONTRIBUTING.md#验证)执行适用检查，记录对应提交或工作区状态；文档、页面证据与模型披露按入口核对。
6. 将任务范围内的提交推送到正确远端，核对远端 head。标题遵循项目约定，正文先说明问题成立的依据和最终行为，
再给必要的设计取舍、自审结论、验证与遗留事项，按模板附页面截图和 AI 使用情况。涉及官方行为时，写明官方源码位置与版本或提交、官方处理方式、
本次实现与它的关系及必要的偏离原因；区分源码推断和实际复现，不用检查通过替代方案论证。按规模压缩，不强填无关章节。
再给必要的设计取舍、自审结论、验证与遗留事项，按模板附页面截图和 AI 使用情况。涉及上游行为时，按[问题与方案依据](../../../../CONTRIBUTING.md#问题与方案依据)写明官方源码位置、版本、处理方式及本次方案关系。按规模压缩，不强填无关章节。
7. 明确要求草稿或仍有阻塞项时创建或保持 Draft PR，并解释原因；必需截图或 AI 模型披露待补时也不标为可审阅。具备审查条件且未要求草稿时创建普通 PR。
GitHub Draft 状态与“只写本地草稿正文”不同，后者不创建远程对象。
8. 创建或更新后回读正文与附件，核对链接、base、head、草稿状态、模型披露和最新检查结果。网络超时或结果不确定时先查询远端，再决定是否重试。
@@ -32,4 +26,4 @@ gh pr create --repo "$pr_repo" --base "$pr_base" --head "$pr_head" \
按需添加 `--draft`。不要用 `gh pr create --dry-run` 做只读预览，它仍可能推送 Git 变更。
多行正文通过文件或连接器的结构化字段传递，不把未转义正文拼进 shell 命令。
创建完成返回链接、目标分支和验证摘要；不要称为已合并或已获维护者批准。
创建完成返回链接、目标分支和验证摘要，不称为已合并。
.agents/skills/cpr-github-pr/references/review.md
+7 -19
View File
@@ -4,30 +4,18 @@
1. 获取 PR 的 base/head SHA、描述、文件差异、已有讨论及 CI 状态。记录实际审查的 head，使用 merge-base 差异。
需要源码上下文时先遵守目标仓库的定位规则；需检出时使用隔离工作区，保留用户当前分支和运行环境。
2. 先核实 PR 要解决的问题是否成立：提取触发场景、预期行为和声称的原因，在目标分支基线检查实际行为。
按入口的公共核对收集一手证据，区分原有问题、环境或配置差异与 PR 新引入的问题，说明主分支已覆盖的部分。
3. 从官方方案评估解决方向：说明官方如何处理同一场景，检查 PR 是否遵循其协议语义和职责归属、
是否复用已有能力或正确传递官方合同；按入口的官方行为优先约束核对偏离的必要性、最小范围、行为代价与运行证据。
审查 OpenAI 官方上游与 Codex 的对接时，默认官方返回与 Codex 兼容、直接对接正常，重点检查本项目是否误解、
改写或破坏官方合同。不得仅凭自行构造的异常上游数据揣测官方不兼容，也不据此报告缺陷、提出改进建议，
或要求增加防御分支与测试。讨论特定版本或场景的对接例外须有真实响应或实际复现证据，并区分代理链路与官方直连。
真实复现上游错误或补偿后成功，也不能单独证明 CPR 应改写请求；缺少必要性依据的行为偏离须在解决方向中明确指出，
不因测试通过而给出方案合理的结论。网关资源策略单独核对容量依据与客户端影响，不以官方客户端没有同类池策略就判错。
4. 按贡献文档的审查维度追踪完整调用链，找到共享业务事实、同类实现及已有验证。
2. 按入口公共核对在目标分支基线核实问题，区分原有问题、环境或配置差异与 PR 新引入的问题，说明主分支已覆盖的部分。
3. 按[问题与方案依据](../../../../CONTRIBUTING.md#问题与方案依据)评估解决方向，涉及上游时说明官方处理方式及本次方案关系；缺少必要性依据的偏离明确指出，不因测试通过就认定方案合理。
4. 按[审查标准](../../../../CONTRIBUTING.md#审查标准)追踪完整调用链，找到共享业务事实、同类实现及已有验证。
对既有特殊分支查清服务的场景，再判断本次改动是否引入或加重问题。
主动检查本次变更新引入或加重的冗余与代码异味，说明具体位置、维护成本或行为影响及最小修复方向；
不能仅因功能可用、CI 通过而略过，也不把个人写法偏好判为缺陷。
5. UI 改动同时对照原页面、主题、共用组件和同类页面，核对结构变化的必要性、文案是否重复及帮助是否适合收进 Popover。
按页面类型检查必需截图是否齐全、可访问且对应待审实现；缺少必需截图时要求补齐并列为未具备审阅条件。
浏览器可用时检查相关交互；未运行的检查列为验证缺口，不从截图或源码推断所有状态都正确。
5. 前端改动执行[前端流程](../../cpr-dev-guide/references/frontend.md)，浏览器可用时检查相关交互；缺少必需截图时要求补齐并列为未具备审阅条件。
6. 核对 CI 与本地证据是否覆盖当前 head；根据风险补充必要验证，不触发无关部署或真实账号业务请求。
有文档差异时按[文档检查](../../cpr-dev-guide/references/documentation.md)检查最终 diff，不能把构建或链接检查通过当作文档内容已经合格。
文档差异按[文档检查](../../cpr-dev-guide/references/documentation.md)核对最终 diff。
核对 AI 使用与模型披露，缺项明确指出。工具不可用、集成测试跳过或环境不足时具体说明影响范围。
7. 按 [审查标准](../../../../CONTRIBUTING.md#审查标准) 用中文先回答原问题是否成立、解决方向是否合理，
再列出实现问题与验证缺口，结论附具体依据。
实现问题区分必须修复项、可选建议和验证缺口；没有的类别可省略。
每个问题给变更中的文件位置、触发条件或规范依据、影响和最小修复方向。
复用建议指出具体已有实现，不把个人偏好写成缺陷；未发现问题时直接说明并交代覆盖范围。
7. 按审查标准用中文输出问题是否成立、方案是否合理及对应依据，再列实现问题与验证缺口；复用建议指出具体已有实现。
没有问题的类别可省略，未发现问题时直接说明并交代覆盖范围。
8. 结束前核对 head 是否变化。发生变化时检查新增差异并更新结论，或明确结论只适用于原 SHA。
审查本身不修改源码、不发表评论、不提交 GitHub 的批准或请求修改状态。
.agents/skills/cpr-plugin-dev/SKILL.md
+2 -2
View File
@@ -14,7 +14,7 @@ description: 开发、排查或打包 Codex Proxy RS 独立网关插件；仅改
- 确认用途、工程位置、目标宿主版本与平台，沿用已有工程；位置无法推断时只补齐该信息，不把插件源码塞进宿主 workspace
- 核对运行宿主、[SDK 版本](../../../backend/crates/gateway-plugin/sdk/Cargo.toml)、[宿主支持清单](../../../backend/crates/gateway-plugin/runtime/plugin-host-compatibility.json)及所用 CLI，清单、进程和能力版本分别判断
- `contributes` 声明处理器，`bindings` 选择挂载与匹配范围；安装成功不等于功能生效。当前清单拒绝 `permissions`，安装者完整信任插件，`trustedProcess` 不提供操作系统沙箱或访问域隔离，见[完整信任](../../../backend/crates/gateway-plugin/sdk/docs/manifest.md#完整信任)
- 涉及 Codex 兼容性适配时执行[官方行为优先约束](../cpr-dev-guide/SKILL.md#参考仓库的优先级)，不因实现位于插件中扩大请求改写或补偿范围；用户明确要求的业务改写限定在授权范围，宿主能力以目标版本的 SDK 为准
- Codex 兼容性适配按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)执行，不因位于插件中扩大改写或补偿范围；业务改写限于用户授权，宿主能力以目标 SDK 为准
## 按当前步骤读取
@@ -29,7 +29,7 @@ description: 开发、排查或打包 Codex Proxy RS 独立网关插件；仅改
| 构建或打包 | [构建与打包](references/development.md#构建与打包) |
| 实际验收 | [验证与交付](references/development.md#验证与交付)，按实现范围验证 |
| 分发插件 | [发布与安装来源](references/development.md#发布与安装来源)，不自动进入宿主发版流程 |
| 修改插件文档 | [文档检查](../cpr-dev-guide/references/documentation.md)，只写当前用法、合同和限制，不附修复过程 |
| 修改插件文档 | [文档检查](../cpr-dev-guide/references/documentation.md) |
## 交付
.agents/skills/cpr-plugin-dev/references/frontend.md
+1 -2
View File
@@ -1,8 +1,7 @@
# 插件页面
仅在创建或修改插件页面时读取，同时使用[开发入口](../../cpr-dev-guide/SKILL.md)的页面分支
仅在创建或修改插件页面时读取，先执行[前端流程](../../cpr-dev-guide/references/frontend.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 实例
.agents/skills/cpr-release/SKILL.md
+2 -2
View File
@@ -31,9 +31,9 @@ description: Codex Proxy RS 的版本规划、发布说明、正式或预发行
## 必须保持的边界
- 发行范围涉及 Codex 兼容性变化时，按[官方行为优先约束](../cpr-dev-guide/SKILL.md#参考仓库的优先级)核对已有方案依据和实际验证范围；缺少依据如实列为发行风险，不以 CI 通过代替，不把网关自定义策略写成官方要求
- Codex 兼容性变化按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)核对已有依据与验证范围，缺少依据列为发行风险，不以 CI 通过代替
- `release/publish` 会提交、打 tag、推送并触发工作流，没有只读预演模式，不能用于探测或演练
- 同名版本、超时或中断先查本地与远端状态，不删已发布 tag、不移动 tag、不强推掩盖冲突
- 预发行不得覆盖 GitHub Latest 或镜像 `latest`，完成后回读核对
- `release/notes.md` 只承载当前发行的说明，常规文档只写当前状态，不追加版本历史；其变更执行[文档检查](../cpr-dev-guide/references/documentation.md)
- `release/notes.md` 只承载当前发行的说明；常规文档修改另按开发入口执行[文档检查](../cpr-dev-guide/references/documentation.md)
- 交付版本、提交、Release／工作流链接与实际结果，未完成构建或缺失产物时不称发布成功
AGENTS.md
+4 -4
View File
@@ -4,7 +4,7 @@
| 任务意图与常见说法 | 必用技能 |
| --- | --- |
| 开发、实现、修复、排查报错、审查问题或代码、修改文档 | [cpr-dev-guide](.agents/skills/cpr-dev-guide/SKILL.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、补充或回复 Issue | [cpr-github-issue](.agents/skills/cpr-github-issue/SKILL.md) |
| 写网关插件、修改插件能力、排查插件接入、打包插件 | [cpr-plugin-dev](.agents/skills/cpr-plugin-dev/SKILL.md)，同时执行 cpr-dev-guide |
@@ -16,7 +16,7 @@
执行所选流程中的问题核实、自审、验证与交付要求，协作流程和审查标准见 [CONTRIBUTING.md](CONTRIBUTING.md)
Issue 和 PR 回复分别按对应技能的[Issue 回复口吻](.agents/skills/cpr-github-issue/SKILL.md#回复口吻)与[PR 回复口吻](.agents/skills/cpr-github-pr/SKILL.md#回复口吻)执行
Issue 和 PR 回复统一按 [GitHub 回复口吻](CONTRIBUTING.md#github-回复口吻)执行
模块职责以 [系统架构](docs/architecture.md) 为准，界面约定以 [管理端主题](docs/theme.md) 为准；
没有明确约定时保持与相邻实现一致，不把单次页面反馈扩展成全仓规则
@@ -34,10 +34,10 @@ If there is no `.codegraph/` directory, skip CodeGraph entirely — indexing is
## 工作方式
- 开发和审查按 [问题与方案依据](CONTRIBUTING.md#问题与方案依据) 先核实问题；涉及 Codex 行为、协议或兼容性时，按[参考仓库优先级](.agents/skills/cpr-dev-guide/SKILL.md#参考仓库的优先级)以官方 Codex 仓库对应版本源码为第一手资料，三方仓库仅作参考
- 开发和审查按 [问题与方案依据](CONTRIBUTING.md#问题与方案依据) 先核实问题及方案必要性；涉及 Codex 行为、协议或兼容性时，以官方对应版本源码为第一手资料，三方仓库仅作参考
- 先定位变更所属模块、同类实现和上下游调用关系，再选择最小合理改动。复用已有能力，也避免为尚不存在的需求增加抽象。
- 提交前自审最终差异，先处理本次引入的职责混淆、重复规则、冗余状态和无依据的兼容分支；后端按 [后端自审](docs/architecture.md#后端自审) 追踪状态与资源生命周期，不能把自审留给 CI 或 PR 审查者。
- 页面变更先复用已有页面设计与组件，不因个人偏好重排页面或另建交互。文案取舍遵循 [界面文案与信息层级](docs/theme.md#界面文案与信息层级)，页面 PR 必须提供 [实际截图](CONTRIBUTING.md#界面验证)。
- 前端开发与审查执行[前端流程](.agents/skills/cpr-dev-guide/references/frontend.md)，先复用已有页面设计与组件，不因个人偏好重排页面或另建交互；页面 PR 必须提供 [实际截图](CONTRIBUTING.md#界面验证)。
- 代码注释使用中文，解释原因与边界；提交信息使用英文，沿用历史中的 Conventional Commits 格式。
- 常规文档只描述当前状态，不记录变更历史；按[文档职责与更新条件](CONTRIBUTING.md#文档职责与更新条件)在所属章节就地修订，分清层次与详略，短段和列表少用句号，交付前逐段检查必要性、归属、重复与当前状态表达
- 按变更范围执行验证，记录命令、结果和缺口。跳过的测试不算通过；界面与集成行为需要对应运行证据，构建通过不能替代实际验收。
CONTRIBUTING.md
+26 -5
View File
@@ -19,15 +19,30 @@
日志和配置只提供定位所需片段，不上传真实凭据或完整请求转储。功能建议说明使用场景、当前不便和期望行为；协作规则调整可直接提交普通 Issue，说明原因和建议方案
### GitHub 回复口吻
AI 草拟或发布 Issue、PR 讨论及审查意见的回复时：
- 用第一人称“我”，自然称呼对方为“佬友”，不逐句重复，也不用“我们”“本助手”代称自己
- 客气、委婉地回应具体问题，补充信息或提出不同意见时说明缘由，避免命令式、责备式表达
- 使用自然短句，简单回复用短段，并列信息较多时再分点；少用句号，避免客服套话、机械模板和空泛保证
- 只把实际完成的排查、复现、修改和验证写成“我已……”；未采纳的意见说明依据，未确认、待处理或未验证的内容如实交代，说清结论、限制和下一步
## 问题与方案依据
开发、创建 PR 和审查都先核实待解决的问题、触发条件与预期行为，再确定或评估实现。区分问题发生版本、目标分支现状和本次变更后的行为，不把需求描述、PR 描述或第三方项目的做法直接当成事实。目标分支已修复的问题，应说明当前仍需补齐的差异，不能据此否定旧版本中的问题
涉及上游协议、客户端行为或兼容性时，以对应版本的官方源码为首要资料。优先读取用户提供或本机已有的官方源码，核对仓库来源、版本或提交；本地资料不足时查官方仓库的对应版本源码，再结合官方测试、文档、发布说明和运行证据。第三方资料只作线索或补充。引用具体文件、符号或行号，对外引用优先使用固定提交的源码链接；源码不可得或版本不匹配时说明证据缺口，不把最新实现当成当前部署行为。无上游依赖的内部变更，以本项目代码、合同和运行证据为依据
涉及上游协议、客户端行为或兼容性时，遵守以下依据与行为约束；无上游依赖的内部变更以本项目代码、合同和运行证据为依据
官方已有同一场景的处理方式时，优先沿用其协议语义、职责归属和解决路径，检查是否只需复用已有能力或正确传递官方合同。新增覆盖配置、补偿逻辑或采用第三方兼容方案，应说明官方路径为何不足；偏离官方方案需有本项目的实际约束和验证依据，不机械照搬源码，也不默认接受已有提案
- **资料来源**：以对应版本的官方源码与调用链为首要资料，Codex 对照 [openai/codex](https://github.com/openai/codex)。先查用户提供或本机已有的仓库，核对来源、版本或提交；不足时再查官方对应版本源码，结合测试、文档、发布说明和运行证据。三方资料只作线索或实现参考，不能替代官方依据
- **证据表达**：引用具体文件、符号或行号，对外优先使用固定提交的源码链接；注明适用版本，区分官方事实、三方参考与本项目推断。源码不可得或版本不匹配时报告缺口，不把最新实现当作部署行为，也不把自定义策略写成官方要求
- **默认方案**：Codex 兼容性优先保持官方行为，以透明转发和最小必要适配为默认方案。沿用官方协议语义、职责归属和解决路径，优先复用已有能力或正确传递合同，不额外解释请求意图、扩展工具权限或改变续接语义
- **问题核实**：对照官方与 CPR 的实际请求、响应及状态生命周期，检查本项目是否误解、改写、遗漏或破坏合同；分别说明源码推断、代理链路复现与官方直连结果。真实上游报错不自动等于 CPR 缺陷
- **审查官方对接**：审查 OpenAI 官方上游与 Codex 的对接时，默认二者兼容、直接对接正常。不得仅凭自行构造的异常上游数据揣测官方不兼容，据此报告缺陷、提出改进建议或要求防御分支与测试；特定版本或场景的例外须有真实响应或实际复现证据
- **偏离依据**：新增覆盖配置、补偿逻辑或三方兼容方案前，说明官方路径为何不足、本项目实际约束、最小改动、行为代价及验证。补偿后成功、测试通过或三方采用同一做法不能单独证明必要性；依据不足时保持现有合同并报告缺口，不先加分支再倒推理由。用户明确要求的行为变更限定在授权范围内
- **网关职责**：调度、隔离和资源管理按网关职责评估，不机械照搬单客户端实现，不因官方客户端没有同类池策略就判错，也不任意改变客户端可观察行为。新增默认限制或回收阈值须有容量依据，并验证续接、重试与延迟影响
反馈 Issue 时区分观察到的症状、根因假设和方案建议，关联已有 Issue、PR 及包含修复的发布版本。能说明问题的反馈可以先提交，不要求报告者先找到官方源码或证明根因；引用官方行为或提出实现方案时，按上述原则注明依据与缺口
反馈 Issue 时区分症状、根因假设和方案建议，关联已有 Issue、PR 及包含修复的发布版本。症状反馈不以找到官方源码或证明根因为前提；引用上游行为或提出方案时注明上述依据与缺口
## PR 流程
@@ -147,7 +162,7 @@ PR 不接受以下协作规则文件的新增、修改、删除或重命名：
## 界面验证
AI 进行前端开发时，加载并使用 `$frontend-design` 技能。设计方案以本项目的用户任务、[管理端主题](docs/theme.md) 和已有页面为依据，优先延续原页面的布局、信息层级与交互；设计技能不构成重做页面的理由
AI 进行前端开发或审查时，执行[前端流程](.agents/skills/cpr-dev-guide/references/frontend.md)，覆盖页面、组件、弹窗、表单及局部文案和样式。用户指定设计技能时使用该技能；未指定时，只有任务明确需要建立或重塑视觉方向才使用 `$frontend-design`。新增页面也优先沿用 [管理端主题](docs/theme.md) 和已有设计，设计技能不构成重做页面的理由
开发前查找原页面、同类页面及 `modules/ui/src/components` 中的基础组件，明确参考实现和可复用部分，再确定最小改动。只有原设计不能满足本次操作或存在具体问题时才调整结构，并在 PR 中说明原因；不顺带换风格、重排无关区域或增加重复的模式入口。需要扩展时在对应职责层修改；局部样式的适用范围遵循主题文档，不一律禁止，也不靠页面覆盖掩盖共用组件的问题
@@ -163,11 +178,17 @@ AI 进行前端开发时，加载并使用 `$frontend-design` 技能。设计方
截图用于视觉审阅，保存、切换、错误恢复和键盘操作等行为仍需实际验证并记录覆盖范围，不能仅凭静态图片推断交互正确
当前用户明确接管或确认本轮视觉验收时，沿用约定分工和结果；明确免除本次截图时，该项不再阻塞交付或要求 Draft。报告区分用户确认、AI 实测和未验证，其他验证仍执行；后续修改只复核受影响部分
涉及浏览器能力或访问环境差异时，按项目支持的部署方式核对相关 HTTP/HTTPS、localhost/实际部署地址与浏览器版本，记录实际覆盖的条件；本地预览正常不能替代部署环境中的交互验收
## 验证
选择与变更相关的检查，纯文档修改无需重建前后端。行为修复补充能覆盖触发条件和结果的测试，不增加仅复述实现的断言
按变更风险明确要验证的行为与通过条件，优先复用现有检查；缺少有效回归覆盖时补充行为测试，不为表名、字段清单或 SQL 文本形状单独保留测试，也不增加仅复述实现的断言。纯文档修改无需重建前后端
必要验证通过且没有新改动、失败或未解疑点后停止扩围与重复运行。真实账号验证满足约定场景后即收尾，不无目的重复请求；用户限定验证范围或次数时按其要求执行，未覆盖项如实列出
临时预览、模拟数据、诊断脚本与压测产物放在 `.runtime/` 或系统临时目录，使用后按需清理；只有持续维护的工具和回归测试进入源码目录，不把一次性验收产物混进 `src/`、`examples/` 或正式提交
| 范围 | 现有检查 | 仍需提供的证据 |
| --- | --- | --- |