@xgent-ai/skills 0.1.0 → 0.4.0

package/skills/review-code/references/git-scopes.md

@@ -0,0 +1,38 @@
+# 输入范围与 Git 取证
+
+开始时读取 `git rev-parse --show-toplevel`、`git status --short` 和 HEAD；如无 HEAD，单独处理首次提交前的工作树。命令从仓库根执行。下面尖括号是占位符，不可照抄；验证 ref 并解析成 SHA 后再使用。用户路径放在 `--` 后，正确引用空格和特殊字符；脚本收集文件名用 `-z`，不按空格拆分。
+
+## 四类输入
+
+| 输入 | 基线 → 目标 | 取证方式与边界 |
+| --- | --- | --- |
+| uncommitted，或未提交的指定文件 | HEAD → 当前工作树，另核对 index | `git diff --no-ext-diff --no-textconv HEAD --` 看 tracked 净差异；`git diff --cached` 和 `git diff` 区分 staged/unstaged；`git ls-files --others --exclude-standard -z` 枚举并读取 untracked |
+| 单 commit C | C 的第一父提交 → C | 先 `git rev-list --parents -n 1 <C>`；普通提交用 `git diff <C^1> <C> --`。根提交用 `git show --root --format= --no-ext-diff --no-textconv <C> --`；merge commit 默认第一父提交并注明，用户指定其他父提交时从其要求 |
+| commit 范围 A..B | A 的树 → B 的树 | `git diff <A> <B> --` 审查累计净效果，不叠加逐 commit 的中间问题；不混入当前工作树。A 是基线，不包含 A 自身引入的改动 |
+| 相对基准分支 BASE | merge-base(HEAD, BASE) → 当前工作树 | 固定 BASE 和 HEAD 的 SHA，用 `git merge-base --all <HEAD> <BASE>` 确认唯一共同祖先，再 `git diff <merge-base> --`。沿用原生 review 的 tracked 工作树语义，包含 staged/unstaged；不得误写成只审 committed |
+
+所有实际 diff/show 命令均加 `--no-ext-diff --no-textconv`，避免仓库自定义 diff 驱动执行。先用 `--name-status -M` 盘点增删改与重命名，再读取 patch 和必要全文。
+
+### 未提交与分支模式
+
+- staged 和 unstaged 可能相互抵消，即 `git diff HEAD` 为空而 index 非空。仍检查两层；仅存在于 index 的缺陷标注为“只提交 staged 内容时触发”，不能说当前工作树也有该缺陷。若用户只要求 staged，则基线为 HEAD、目标为 index，用 `git show :<path>` 读取完整目标文件。
+- 未初始化 HEAD 时，以空树为基线，读取 staged 新文件、工作树及 untracked；不要因 `git diff HEAD` 失败判定无变更。可用 `git diff --cached` 配合文件清单和全文。
+- 分支模式默认审查 tracked 工作树差异。先声明这一范围；untracked 不在该 diff 中，但应枚举，新增调用依赖它们时作为上下文读取。用户要求把新文件也纳入审查时，明确增加 untracked 范围并记录清单；未纳入的必要新文件形成覆盖限制，不能宣称完整实现已审。
+- 用户明确要求“只审已提交分支变更”时，用 `git diff <merge-base> <HEAD> --`。本地 dirty 内容仅记录，不作为目标代码。用户要求分支 tip 之间直接比较时用两端树差异，明确它不同于共同祖先比较。
+- untracked 按新增文件完整审查；忽略文件不自动纳入，除非用户明确点名。二进制、生成文件或子模块无法深入检查时，记录实际检查的指针/来源与缺口，不静默视为无风险。
+
+### 范围、父提交和 ref 异常
+
+- `A...B` 明确解释为 `merge-base(A, B) → B`，不等同 `A..B`。用户说“从 A 到 B，包含 A”时，以 `A^1 → B` 为范围；A 为根提交则以空树为基线。自然语言未说明是否包含起点且无法推断时询问。
+- 单 commit 为 merge 时，第一父提交差异是默认审查对象；不要依赖可能隐藏普通变更的 combined diff。冲突解决逻辑按需与其他父提交对照，记录实际审查父提交。
+- ref 验证可用 `git rev-parse --verify --end-of-options '<ref>^{commit}'`。不存在、浅克隆历史不足、无共同祖先或存在多个 merge-base 时，不擅自退回 HEAD~1 或任选基线；说明缺口并澄清/按已有授权补齐历史。
+- unmerged index 要明确记录；可以审查确定部分，但 unresolved conflict 不等于完整可运行快照，不给出无保留正确结论。
+- 用户限定文件时只对限定文件的变更出 findings，读取相关文件证明影响；另发现范围外线索可列覆盖建议，不静默扩大任务。
+
+## 固定版本与行号
+
+- 记录原始输入和解析后的完整 SHA、实际比较方式、dirty 状态、纳入文件清单；工作树/index/untracked 使用内容 hash 或等价可复查快照，不能只靠 `git status` 判断内容未变。包括影响结论的上下游文件与附带计划。
+- 历史版本的代码、调用方、测试与契约从目标树读取，如 `git show <target>:<path>`、`git grep <pattern> <target> --`；基线证据从 base 读取。执行环境的当前指令仍须遵守，涉及历史仓库约定时标明所用版本。
+- 不为读历史代码而 checkout、reset 或 stash 用户工作树。需要运行目标版本时用隔离临时检出或快照；确保命令在该版本执行，并记录快照路径和 SHA。
+- 默认使用目标侧的短行范围；删除行/删除文件可用基线侧，必须标记 old/base 及 SHA。重命名附旧路径；index 定位明确标 staged。引用历史版本时附 `SHA:path:line`，不要把当前文件链接冒充历史行内容。
+- 结束前比较固定基线与相关内容指纹。外部修改需重审受影响部分；写报告、临时验证产物不得污染本轮输入，也不能因此把用户的新改动一起排除。

package/skills/review-code/references/report-contract.md

@@ -0,0 +1,56 @@
+# 问题与报告合同
+
+## 落盘与交付
+
+- 默认保存完整 Markdown 报告；只有用户明确要求仅聊天/不写文件时跳过，不询问是否保存。
+- 路径优先级：用户指定路径 → 附带的本地计划同目录 `<计划名去扩展名>.code-review.md` → 仓库既有报告目录 → 当前工作区 `docs/reviews/<主题>.code-review.md`。无本地计划时，主题可用 `uncommitted`、`commit-<短SHA>`、`range-<短A>-<短B>` 或 `against-<基准分支短名>`；将分支中的 `/` 等路径字符转换为 `-`，不把 ref 直接作为目录。
+- 写前检查文件已存在与否。仅在用户明确授权更新/覆盖该报告时覆盖；否则另存 `<主题>.code-review.<YYYY-MM-DD>.md`、`<主题>.code-review.<YYYY-MM-DD>-2.md` 等未占用名称。指定路径冲突也遵守此规则，最终说明实际路径。不得把报告写到代码或原计划文件，即使名字碰巧一致。
+- 由当前主 agent 单独写入完整报告，回读实际文件核对内容与定位。空 findings、`inconclusive` 和部分覆盖不免除落盘。不要只写摘要或拼接未经裁定的 reviewer 回报。
+- 最终聊天给实际文件链接、总体结论和重要问题/限制摘要。写入失败时明确“报告未落盘”、原因和目标路径，聊天提供完整报告以保留结果，落盘仍标未完成；不链接不存在的文件。
+
+## 问题格式
+
+每条一个独立根因，优先级置于简短行动标题前（标题不超过 80 字符）；问题正文用一段说明触发条件、实际行为、影响和关键依据。不要在正文堆阅读日志。
+
+```markdown
+### F-01 · [P1] <简短、可执行的修复标题>
+
+- 定位：<目标路径:短行范围，target/index/base 侧及版本；须与 diff 重叠>
+- 问题：<在具体输入或状态下，改动如何导致故障，影响哪个调用方/契约，为什么是本次引入。单段。>
+- 证据：<上下游代码、需求/计划/仓库规则的精确定位，或复现命令与实际结果>
+- 修复与验证：<最小修复方向；验证该行为的断言/回归场景，不自动实施>
+- 置信度：<高/中及依据；可用 0–1 数值，但不把主观分值伪装成统计测量>
+```
+
+主定位取最小有意义的 diff 行范围，通常 1–5 行，避免超过 10 行。删除缺陷定位到基线侧删除行并标 SHA；缺失行为定位到应负责它的改动入口/调用点，不凭空造一个不存在文件的行号。完整需求遗漏确实没有 diff 锚点时，放计划符合性缺口，说明影响，可影响结论，但不伪装成行内 finding。
+
+本地当前文件用可点击路径；历史版本另标 `SHA:path:line`，需要可点击证据时链接实际存在的版本快照文件。支持证据可在 diff 外。基于仓库规则的结论须引用实际读过且适用的规则最小行范围；不能只写“违反最佳实践”。
+
+不强制给代码片段。确有助益时最多三行；`suggestion` 块仅含可直接替换的最小代码，保留原缩进，不在块内解释。自然语言足以说明修复时不生成 patch。
+
+## 严重度与置信度
+
+| 等级 | 含义 |
+| --- | --- |
+| P0 | 必须立即停止其他工作处理的普遍性严重故障，阻断发布/运行/主要使用，无须额外输入假设；极少使用 |
+| P1 | 紧急，应在下一修复周期处理的高影响缺陷；写明受影响条件与范围 |
+| P2 | 应修复的一般缺陷，有明确局部功能、兼容性、性能或维护后果 |
+| P3 | 有证据、值得修复但优先级低的小问题；纯风格和个人偏好不报 |
+
+严重度描述后果，置信度描述证据。只有猜测的风险属于待核实项，不以 P3 收纳。不要把所有安全字样都升为 P0，也不把未运行测试自动降格成已证实失败。
+
+## 完整报告顺序
+
+1. **确认问题**：按 P0 → P3 排序，F-01 等稳定编号。没有时写“未发现可确认的问题”，不凑数；复审沿用编号并区分已解决、仍存在、新增。
+2. **待核实/待决策项**：缺少什么证据、影响哪个结论、如何补证；无法访问的文件/环境、需求歧义、尚未运行的关键验证放这里。
+3. **覆盖与验证**：一句话意图；仓库根与日期；原输入、解析 SHA、比较方式、工作树/index 指纹或快照、文件限制、纳入/排除项；已审行为链与未覆盖部分；实际命令、目标版本、结果、失败原因。区分静态、测试、浏览器与外部资料证据；注明实际 reviewer 分工（若有）。
+4. **计划符合性（有计划才写）**：计划路径和版本、本次任务/里程碑；仅列相关需求的映射和缺口，包含未核实及后续范围。不要复制整份计划或更新其进度。
+5. **总体结论与修复顺序**：结论、1–3 句理由与覆盖限制；优先解除契约/数据/安全根因，再修局部行为，最后验证相关回归。明确解除阻塞的可观察条件，不把评审结论当作 merge/deploy 授权。
+
+### 正确性结论
+
+- `patch is incorrect`：有已证实影响正确性或形成实质阻塞的缺陷/本期需求缺口，引用对应编号或计划缺口。其余覆盖不足仍须说明。
+- `patch is correct`：在明确审查范围内未发现上述缺陷，证据足以支撑判断；非阻塞的小问题不自动否定正确性。表述为评审判断，不保证不存在未知 bug。
+- `inconclusive`：尚无足够证据裁定，或没有实际可审变更，例如基线不明确、关键调用方无法读取、冲突未解或关键验收无法核实。说明缺口，不把它写成代码已证实有错。
+
+空 findings 不自动等于正确；未运行全量测试也不自动等于不可裁定，依据关键行为的实际证据判断。报告落盘成功与代码是否正确是两个不同结论。

package/skills/review-code/references/review-lenses.md

@@ -0,0 +1,33 @@
+# 审查视角与取舍
+
+这些是调查线索，不是自动判错规则。每项仍须通过主流程的引入性、影响和证据门槛。
+
+| 视角 | 需要追踪的行为与证据 |
+| --- | --- |
+| 需求符合性 | 用户请求/计划中的本期验收 → 入口 → 实现 → 可观察结果；遗漏、误解和越界是否产生实际契约或范围后果。需求歧义列待决策，不用“常见做法”替作者决定 |
+| 正确性与兼容性 | 调用链和状态转换、边界与错误路径、重试/幂等/并发、事务与资源释放；API/类型/序列化/配置默认值变动对现有消费者的具体影响 |
+| 安全与数据 | 不可信输入是否可达危险操作、身份与对象级授权/租户隔离、敏感数据流、注入、路径与请求边界；数据迁移、约束、失败回滚和读写兼容性。报告敏感证据时隐藏实际密钥 |
+| 性能与资源 | 真实规模下的查询次数、无界读取/队列/循环、阻塞、缓存一致性、订阅或连接泄漏；复杂度与实测分开，不强制缓存/批处理，不虚构毫秒或容量 |
+| 测试与交付 | 测试断言是否能捕获改变的行为，mock 是否掩盖协议/权限/事务，回归用例能否在基线失败而目标通过；构建、入口接线、配置、依赖和部署产物是否一致 |
+
+## 可选开发计划
+
+只核对所审变更承担的任务与验收。最小映射为 `需求/章节 → 本次任务 → 实现证据 → 验证状态`，状态区分已核实、存在缺陷、未核实、后续范围。不要求计划必须采用某个模板或有正式 ID。
+
+计划符合性发现问题后仍继续安全与正确性审查，不用“先修计划偏差”跳过其他风险。用户明确改变需求时以当前用户要求为准，列出与旧计划的差异；不自动改计划，也不把服从新要求视为缺陷。没有被本次变更触及/承诺的旧功能缺失不属于新增问题。
+
+无测试本身不自动成为 finding。说明本次改变的哪个重要行为无法被现有测试保护，以及具体失败风险；若缺陷已在 findings 中，测试建议归入同条，避免重复计算。仅凭测试覆盖率数字不能宣布质量达标。
+
+有 UI 时按变更检查主要路径、加载/空/错误状态、键盘操作和可访问性。静态推演、实际浏览器走查、自动化结果分开记录；没有运行页面不声称视觉或交互验证通过。
+
+## 来源与有意取舍
+
+以下是本 skill 的设计来源，运行评审时无需加载来源文件：
+
+- **Codex CLI 0.159.3**（2026-10-02 本机 `codex --version`、`codex review --help` 及二进制内嵌 review prompt）：沿用新增且可行动的缺陷门槛、具体受影响代码证据、允许空 findings、P0–P3、短 diff 定位、适用仓库规则引用、单段说明和不自动修复。官方 [CLI 文档的 review 说明](https://learn.chatgpt.com/docs/codex/cli) 也列出未提交、commit、基准分支三类入口。
+- **`local/code-review`** 的 `SKILL.md`、`references/requesting-code-review.md`、`references/verification-before-completion.md`：吸收明确评审范围、证据先于结论、反馈先核实；不引入每个实现任务都必须再派 reviewer、固定包管理器或自动修复的流程。
+- **`local/code-reviewer/SKILL.md`**：吸收快速筛查逻辑、导入导出、安全和性能线索；不采用每次保存触发、固定函数行数阈值、模式匹配即报错或未经实测的速度承诺。
+- **`local/code-reviewer2/SKILL.md`** 与 `references/spec-compliance-review.md`、`references/review-checklist.md`、`references/report-template.md`：吸收先理解意图、需求映射、多维审查和可行动反馈；不强制赞美、建议代码或因需求未通过而停止其他审查。
+- **`skills/review-dev-plan/references/report-contract.md`**：沿用完整报告默认落盘、路径优先级、防覆盖、单写者、回读和失败披露。代码报告用 `.code-review.md` 区分计划报告的 `.review.md`；不继承计划的就绪状态或固定四 reviewer 编排。
+
+commit 范围、可选计划映射和 `inconclusive` 是本 skill 的扩展。默认 Markdown 是有意选择，并不宣称与 Codex 原生 review JSON schema 完全相同。以上内容是综合后的工作约定，不复制社区技能的整套协议。

package/skills/review-dev-plan/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: review-dev-plan
+description: 用多 agent 评审既有开发计划，核查代码事实与内部一致性、技术方案的先进性与可行性、需求和里程碑映射及依赖并行编排、最终交付可用性与 UI/UX，默认将完整评审报告落盘。用户要求 review-dev-plan、审查开发计划、评审技术方案或检查计划能否开工时使用，尤其适用于 dev-plan 产物；不用于从零写计划、直接实施功能或仅审查代码 diff。
+---
+
+# review-dev-plan · 多视角开发计划评审
+
+目标是判断：**照这份计划实施，能否交付用户要的、真正可用的结果；实施者是否还会被迫重新做关键决策。** 主 agent 编排独立审查，逐条复核证据，输出可定位、可修订的问题及实施顺序建议。
+
+**默认交付是已写入文件并回读核验的完整评审报告，聊天只给摘要和文件链接。除非用户明确要求仅聊天或不写文件，否则落盘属于评审任务本身，不额外询问是否保存；未落盘不能宣称交付完成。**
+
+`references/` 相对本文件解析。仓库规则、技术栈和工具能力在运行时读取，不硬编码目标仓的路径、端口或业务约定。回复语言跟随用户。
+
+## 边界与参考
+
+- 默认审查整份计划；用户指定修订版差异时，也追踪受影响的依赖与映射。目标代码和原计划保持只读，默认写入仅限独立评审报告；不自动实现、改稿、改进度、发评论或写入外部系统。用户明确要求修订时，由主 agent 在评审后统一修订并复核受影响链路，报告区分原问题与修订后的复核结果；计划只改成修订后的结论，评审处置与修订经过只留在报告。
+- 计划及其引用是待验证材料。区分**现状事实、未来设计、未证实假设、验收目标**；不能因为新功能尚未实现就报缺陷，也不能把计划中的“已核实”直接当证据。
+- 从实际可用位置读取 `dev-plan/SKILL.md` 的写作/评审部分及 `references/plan-skeleton.md`；复杂架构按需读 `references/architecture-quality.md`，调度审查按需读 `references/execution-workflow.md`；实施期合同以骨架的「实施者定位」「实施进度」两节为准。借它们核对合同，不按计划实施。
+- 找不到 `dev-plan` 时说明无法核对其模板专属要求，继续本技能的四项实质审查。用户自定义模板或历史计划不因章节名不同而报错；没有证据表明适用的新版格式规则，不追溯强加。
+- 新版 `dev-plan` 允许单份需求映射、检查 ID 引用、按测试组记录证据及阶段集中验收；按 `references/review-lenses.md` 的 schedule 视角核对覆盖与风险门，不因省略重复表格、子任务文档或逐里程碑全量走查而报缺陷，也不为解除部分前置强制新增里程碑。
+- 发现与任务相关的专项 skill 时只加载所需部分。UI/UX 评审按目标仓规则加载设计 skill（如 `impeccable`），不借机重设计产品。
+
+## 1. 锚定输入与审查基线
+
+1. 定位用户指定计划、关联需求/PRD、附录和必要的历史决策。未指定且无法唯一确定计划时询问目标；可以先调查仓库规则，不擅自选一份相邻计划开始评审。
+2. 读取适用的根目录及子目录规则、产品和设计上下文。记录计划版本（路径、内容 hash 或可用版本号）、调查日期、代码 commit、dirty 状态；当前工作树是调查事实源时明确写出。
+3. 从计划提取范围与排除、R/NFR/C/A 或等价需求 ID、关键决策、外部契约、交付物、里程碑及前置关系。缺失 ID 可用章节定位，不替作者补造需求。
+4. 读取 [references/report-contract.md](references/report-contract.md)，按其中的「落盘与交付合同」确定输出路径。建一个短任务台账：审查维度、负责人、状态、证据缺口，以及报告写入与回读核验。明确 UI 是否在范围内、是否已有可运行页面/原型、哪些结论必须访问外部服务或官方文档。
+
+## 2. 编排四个独立审查视角
+
+先读 [references/review-lenses.md](references/review-lenses.md) 的对应节，再分派下表。**有多 agent 工具时实际启动 subagents**，不是在同一段回答里扮演四个角色。主 agent 保留综合裁定职责。
+
+| 角色 | 主责 | 必须交回的专属结果 |
+| --- | --- | --- |
+| `facts` | 代码事实、陈述正确性、内部矛盾 | 主张与代码证据；互相冲突的两处位置 |
+| `architecture` | 技术路线、先进性、可行性 | 关键选择的适配/代价；需补证的技术前提 |
+| `schedule` | 需求、设计、任务、里程碑、验收映射 | 断链项；依赖图/边表；可并行波次与集成门 |
+| `delivery` | 最终交付可用性，含 UI/UX | 用户主路径闭环；运行与验收缺口；界面证据等级 |
+
+### 调度规则
+
+- 默认一视角一 reviewer；简单局部计划可用两位独立 reviewer 各覆盖两个视角，在同一回报内分开标明覆盖与结论，减少调度回合。不得合并后漏审某个维度。模型继承主 agent，不主动覆盖模型或推理档位。所有 reviewer 只读，报告由主 agent 单写，不让多个 agent 改同一文件。
+- 并发数受实际剩余槽位约束，主 agent 也占槽位。只有 4 个总槽位时，先并行 3 个视角，完成后复用空闲 agent 审第 4 个；更少槽位则分批，不能漏掉任何视角。主 agent 同期整理需求账本和全局矛盾。
+- 初轮独立调查，不把主 agent 的预设缺陷或其他 reviewer 的结论当任务答案。每人拿相同基线、用户约束和原始材料；独立返回后再交换相互影响的证据。
+- 共用浏览器会话、可变数据库或外部环境时由主 agent 指定一个操作者，其他 reviewer 读证据；只读代码可并行。评审不执行迁移、种子、部署或有副作用的验收命令。
+- 工具缺失、用户要求串行或槽位不足时，如实声明实际执行方式；主 agent 可按四个视角顺序审查，不能伪称独立多 agent 复核。单个 reviewer 失败时重派一次或主 agent 接管；无法核实的部分留在覆盖缺口中。
+
+### 每个 reviewer 的派发合同
+
+发送实际绝对路径和已确认上下文，不只说“审一下方案”。可沿用：
+
+```text
+你负责 {facts/architecture/schedule/delivery}，只读评审，不实现、不改稿、不继续派生 agent。
+用户目标及范围：{原始要求、排除、已有决定}
+计划与基线：{计划绝对路径、版本；仓库根、commit/dirty、日期}
+必读：{本 SKILL.md、report-contract.md、review-lenses.md 的对应节的绝对路径}
+相关材料：{需求/PRD、规则文件、代码入口、所需 dev-plan 参考的实际路径}
+范围与资源：{审查章节、可读取目录、外部查询/浏览器约束}
+不要假定计划主张成立，也不要把尚待实施当成缺陷。按需追到行为级代码证据。
+交回：范围与基线；候选问题（计划定位、触发、影响、证据、最小修订、验证、P级及置信度）；
+本视角专属结果；未核实项与所需证据。没有问题可返回空 findings。
+跨视角问题只标关联，不代替另一角色完成审查。无法继续则回报缺口。
+```
+
+## 3. 主 agent 交叉复核与裁定
+
+1. 收齐四个视角的结果；逐条阅读支持候选问题的计划段落和原始证据，确认适用范围、代码版本和触发条件。不能把多名 agent 的一致意见当事实。
+2. 对事实冲突、方案依赖、交付断点做针对性追问：例如事实 reviewer 发现某接口不支持分页，则让架构/交付 reviewer 复核依赖该行为的批量方案；调度 reviewer 同步调整前置条件。只复核受影响链路，证据仍缺则保留未决，不无限辩论。
+3. 按根因与修订动作去重，保留所有实质不同的问题；多处症状归并后仍附关键定位。不设问题数量指标，也不只报前三项。误报撤回，低证据主张移到待核实项，不凑 P3。
+4. 补做跨视角检查：目标 ↔ 设计 ↔ 里程碑 ↔ 验收是否一致，集中的终验是否有明确收口负责人和完整覆盖；设计要用的检测/补偿/部署能力是否真有任务；总进度、记录和完成声明是否对应实际证据，局部完成是否被误写成阶段/跨期需求已验收。
+5. 若 `dev-plan` 校验脚本可用且适用，用实际路径运行 `check_paths.sh <计划> <仓库根>` 与 `check_progress.sh <计划> <仓库根>`。路径缺失须人工区分新增、示例、错误复用。用户自定义模板或历史计划未采用该恢复快照/完成记录协议时，跳过 `check_progress.sh` 并说明原因，人工核对其等价进度、依赖与验收证据；不要把格式不兼容判成计划错误。脚本通过不证明行为真实或验收完成；脚本缺失/失败如实记录，不用“通过”替代人工检查。
+6. 结束前核对计划及相关代码有无并发修改。若基线变化，只重审受影响结论；无法收敛则标为待核实。收集或停止尚在运行的 reviewer，再交付。
+
+## 4. 输出评审结果
+
+使用 [references/report-contract.md](references/report-contract.md) 的报告结构和落盘合同：**先列问题，再给结论与修订顺序**。由主 agent 写入完整报告；空 findings 或建议状态为 `Blocked` 也要落盘，不能只保存摘要或子 agent 回报。
+
+报告至少包含：
+
+- 按严重度排序、编号的问题，每条定位到计划行或稳定章节，并附行为级代码/规则/外部证据。
+- 四个维度的审查覆盖及未核实项；UI 分清文档推演、原型走查和实际浏览器验证。
+- 需求到交付的映射缺口，以及建议的依赖顺序、可并行任务、共享资源负责人和最终集成验收。没有安全并行空间时给出具体原因。
+- 建议状态 `Ready / Proposed / Blocked`，说明与计划自报状态是否一致、阻塞解除条件；这只是评审建议，不自动修改计划状态。
+
+**没有确认问题时允许空 findings；有未核实的关键前提时不能据此判 Ready。计划评审通过也不表示功能已实现或上线可用。**
+
+交付前确认：报告已写入并回读、内容符合上述合同、文件链接指向实际产物。最终回复给出报告链接、建议状态及关键问题/待核实项摘要；用户明确要求仅聊天时，直接在聊天中交付完整报告。写入失败时按落盘合同说明未完成项，不把聊天摘要算作完成。

package/skills/review-dev-plan/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "开发计划评审"
+  short_description: "多 agent 核查代码事实、技术方案、依赖编排与交付可用性，默认落盘报告"
+  default_prompt: "使用 $review-dev-plan 评审指定开发计划，将有证据的问题、就绪结论和可并行的实施编排建议写入完整评审报告，默认落盘并回读核验，回复报告链接与摘要。"

package/skills/review-dev-plan/references/report-contract.md

@@ -0,0 +1,59 @@
+# 问题判定与报告合同
+
+## 落盘与交付合同
+
+- **默认保存完整 Markdown 报告**，只有用户明确要求仅聊天或不写文件时才跳过。聊天中的报告正文、拟写入内容或路径预告都不算已落盘。
+- 路径优先级：用户指定路径 → 本地计划同目录的 `<计划文件名去掉扩展名>.review.md`；例如 `docs/plan/cache.md` 对应 `docs/plan/cache.review.md`。输入只有聊天文本或远程文档、没有本地计划文件时，遵循仓库报告目录约定；无约定则写当前工作区的 `docs/reviews/<主题短名>.review.md`。按需创建目录，不因用户未指定路径而停下询问。
+- 写入前检查目标是否已存在。用户已明确要求更新或覆盖该报告时按授权执行；否则保留旧报告，在同目录依次尝试 `<主题>.review.<YYYY-MM-DD>.md`、`<主题>.review.<YYYY-MM-DD>-2.md` 等未占用名称。用户指定路径发生同名冲突时也另存，并在最终回复说明实际路径；不得覆盖原计划或代码。
+- 主 agent 单独写入下文「完整报告顺序」的全部内容，然后回读实际文件，核对问题、待核实项、覆盖与基线、实施编排和总体结论均已保留，检查引用定位与报告路径有效。空 findings、部分证据缺失或 `Blocked` 不免除保存义务，按实际覆盖情况写明限制。
+- 最终聊天回复只给实际报告链接、建议状态和关键问题/待核实项摘要，避免重复整份报告；明确仅聊天时才在聊天中交付完整报告。
+- 无可用文件写入工具或写入失败时，明确说明“报告未落盘”、原因与目标路径，在聊天中提供完整报告以保留结果，并将落盘标为未完成；不能声称已保存或给出不存在的产物链接。
+
+## 什么进入 findings
+
+确认的问题须同时具备：计划中的可定位主张或缺口、已核实的依据、具体触发/受影响场景、对本期目标的实际后果、可执行的最小修订。建议作者换个人偏好的技术、堆更多章节、覆盖无关老问题，都不算。
+
+“没有写 X”须先确认全文/引用中确实没有，并证明 X 是本期交付必要条件。证据不足的风险放待核实项，写所需证据及影响；关键待核实项仍可阻塞就绪判断，不能伪装成已证实缺陷。
+
+每条只解释一个独立根因。合并重复症状时保留涉及的需求、里程碑和规则来源。无实质影响的拼写、偏好、格式不报；违反适用合同而会造成实施偏差的格式问题说明其后果。
+
+## 严重度与置信度
+
+| 等级 | 在计划评审中的含义 |
+| --- | --- |
+| P0 | 已证实、无须额外假设就会造成重大安全/数据/运行灾难的计划指令，必须立即纠正；极少使用 |
+| P1 | 核心目标不可达，或范围、安全、数据、外部契约、关键 NFR 存在高影响错误；受影响任务开工前必须修订 |
+| P2 | 局部功能、验收或编排有可证实缺口；在对应里程碑前修正 |
+| P3 | 有明确收益和依据的小改进，不阻塞实施；纯偏好不进入 findings |
+
+置信度用高/中/低及依据。严重度表示后果，置信度表示证据强弱，不互相替代。仅猜测的问题不靠降为 P3 混入 findings。
+
+## 单条问题格式
+
+```markdown
+1. [P1] F-01 · <简短、可执行的标题>
+   - 定位：<计划路径:行号或稳定章节；冲突时给两处；关联 R/M ID>
+   - 问题：<在什么条件下，按计划会发生什么，为什么影响本期目标。简短一段。>
+   - 证据：<代码路径:精确行号/符号、适用规则定位、实测结果或官方文档 URL/版本/日期>
+   - 修订：<最小需要补充、改正的决策/契约/任务；避免整份重写>
+   - 复核：<改稿后检查的断言或实现后的验收；区分二者>
+   - 置信度：<高/中 + 原因>；阻塞：<受影响任务/里程碑或否>
+```
+
+本地文件优先使用可点击路径和短行定位；行号变动大时同时给稳定标题/符号。定位指向原计划有责任承载该要求的位置，不能指向 reviewer 自己新写的报告。代码行号不必位于 git diff 内，计划评审可能没有 diff。
+
+## 完整报告顺序
+
+1. **确认问题**：P0 → P3 排序，稳定编号 F-01 等；空结果写“未发现可确认的问题”，不凑数。复审沿用原编号，区分已解决、仍存在、新增。
+2. **待核实/待决策**：每项写缺什么证据、影响哪个决定/任务、谁可提供以及最晚确认点；责任人未知就写待指定，不虚构用户承诺。
+3. **覆盖摘要**：记录计划与代码基线、实际 agent 分工、四维覆盖/跳过理由、脚本及浏览器实际执行情况。只列结论相关来源，不倾倒阅读日志。无 UI 可写不适用；交付可用性不能随 UI 一起跳过。
+4. **映射与实施编排**：列断链 ID 或确认映射完整的核对范围；给依赖边、并行波次、共享文件/资源负责人角色和汇合验收。现有编排成立时简要确认并引用原计划，只展开有必要调整的部分，不重抄完整映射或为形式新增里程碑/过程文档。只报文件不冲突、不报依赖条件的“可并行”不合格。小计划可合成一张短表。
+5. **总体结论与修订顺序**：建议状态、理由、与原状态的差异，先纠正前提/契约，再修设计、映射与编排；写清解除阻塞的可观察条件。
+
+### 就绪判断（沿用 dev-plan 的含义）
+
+- `Blocked`：仍有会改变范围、安全、数据、外部契约或关键 NFR 的未决项，或核心交付无法成立；说明具体阻塞范围。无关且独立的前期工作可以单列，不把整个计划宣称 Ready。
+- `Proposed`：方案与实施前置完整，只等待非阻塞评审；不能用它收纳重大未知或实质开工阻塞。
+- `Ready`：所审范围的实施前置均已解决，关键证据无缺口，剩余非阻塞建议不影响承诺交付。说明评审覆盖限制，不把 Ready 当作实现完成或产品上线许可。
+
+严重度和状态不是机械一一对应：同一个 P2 在某计划中可能阻塞关键外部契约，另一个 P2 只是非关键局部改进。依据影响判断，不使用总分平均掉阻塞项。

package/skills/review-dev-plan/references/review-lenses.md

@@ -0,0 +1,82 @@
+# 四个审查视角
+
+各 reviewer 只需读自己的节；跨视角追问时再读关联节。检查深度与计划改动面相称，不为填清单创造需求或阻塞。
+
+## A. facts：代码事实、正确性与矛盾
+
+把关键陈述整理成“计划主张 → 类型 → 来源 → 核实结果”。优先核实会改变技术选择、依赖或交付结果的事实：
+
+- 声称存在或可复用的路径、符号、路由、表、包导出、命令、配置是否真实存在；新增项明确标注即可，不能要求它已存在。
+- 追到调用者与实现的行为：参数/返回、错误、分页、排序、事务、幂等、权限传播、缓存失效和删除语义。函数同名、类型匹配不等于行为满足。
+- 安装/初始化、存量升级、部署配置和生产执行链是否与开发态假设一致。计划声明“无需改动”的邻接面是否真的支持目标。
+- 数字与结论是否有用户要求、代码、配置、运行证据或明确决策来源；没有来源的性能承诺、规模、工期不能成为架构依据。
+- 对照全文的范围/非目标、契约字段、事实归属、鉴权、数据生命周期、失败语义、迁移回滚、验收断言和进度，找互斥陈述。矛盾同时定位两处，并说明在什么操作上无法同时成立。
+- 旧文档与当前代码不一致时标明时间和基线；规则约束与运行事实分开，不能因为文档旧就自行废除规则。已有缺陷只有被本计划依赖或放大、导致目标无法交付时才进入本次 findings，并说明关联。
+
+交回关键核实表：`主张/计划定位 | 事实/设计/假设/目标 | 证据定位 | 已核实足够/已核实缺口/未核实 | 影响`。无关事实不用穷举。
+
+## B. architecture：技术先进性与可行性
+
+“先进性”评价的是在真实约束下能否改善交付、性能、安全、可靠性或维护成本。**新技术不自动加分，旧技术也不自动合格**。
+
+1. 从本期 R/NFR/C 推导需要解决的问题。主要选择是否有可行备选、收益与代价；复杂或难回退选择是否记录选择理由与重审条件。简单可逆决策无需硬补 ADR。
+2. 同时比较沿用现有范式和有实际收益的现代方案：能力差距、生态支持、复杂度、可维护性、迁移成本、运行成本和团队可操作性。仅因版本旧而建议升级不算问题；已有方案无法满足受支持版本、必要能力或明确约束时应指出。
+3. 涉及版本能力、弃用、支持周期、安全公告或外部服务限制等时效性事实，先读目标项目依赖/锁文件，再查官方文档、发布说明或原始论文，标记版本、查询日期和 URL。不能联网则列具体待核实项，不用记忆冒充最新结论。
+4. 审查模块边界、事实所有权、接口深度和变化局部性；新基础设施或抽象是否解决真实复杂度，删除它后是否只减少转发层。避免为假想规模过度设计，也不机械维护已不适配的现状。
+5. 核对关键请求/任务的并发、原子性、幂等、重试、超时、租约、隔离、背压和失败恢复，按实际风险裁剪；热路径的查询/索引、缓存与新鲜性是否满足目标。
+6. 对持久化和外部契约检查新旧版本共存、迁移/回填、切换门、不可逆步骤、回滚及恢复。对外依赖核实真实能力、权限、配额和部署条件。
+7. 验证方案能否以目标仓的构建、测试和运行入口落地；风险是否有观测/验证手段。需要 spike 的未知项写“验证问题、成功判据、影响的决策、最晚完成点”，不在评审中自动实现 spike。
+
+交回少量关键决策的判断：`选择 | 驱动需求 | 证据与版本 | 收益/代价 | 可行性 | 必要修订或保留理由`。只是另一种同样可行的做法放非阻塞建议，不能当缺陷。
+
+## C. schedule：映射、依赖与实施编排
+
+双向追踪，不只看里程碑标题齐不齐：
+
+`需求 R/NFR/C/A → 设计/决策 → 交付物/任务 → 里程碑 → 可观察验收`
+
+- 每条本期需求有实现与验收；每项设计/交付物有负责的任务；每个验收有设计依据。映射在账本或专门表中完整保留一份即可，需求原文和断言可引用 PRD/检查 ID，须追到定义与覆盖范围，不要求多处重复展开。排除/延期有明确去向，不能用无关测试占位。
+- 里程碑退出条件能判定局部结果，阶段收口有跨模块集成与用户主路径验证。允许同能力、同环境且无独立风险门的验收合并，核对检查覆盖、执行时点、收口负责人和前置就绪；骨架阶段不要求尚未实现的端到端路径。安全、迁移、不可逆操作、发布及用户分期门不能被合并绕过，风险不能拖到终验才发现。局部完成不等于阶段/跨期需求已验收，fixture 或构建通过不能替代真实集成、权限、业务或界面验收。
+- 完成数、最近完成、下一步、记录链接及基线一致；初稿不预填完成，进行中不计完成。已完成有本里程碑退出检查证据；可按测试组覆盖多条条件，须逐条可追溯，共同环境/基线可只写一次，不默认要求子任务文档。复用证据须有原记录及依据：相关代码、配置、依赖、输入与环境未变，否则重跑受影响检查，阶段收口仍有必要集成回归。适用 dev-plan 协议时核对逐行退出条件及里程碑记录，不机械否定历史格式。
+- 提取有向依赖边 `前置任务 → 后置任务` 及其产物；检查循环、缺失节点、倒置、隐藏的跨系统前置和过粗的里程碑阻塞。编号不是依赖，文件分目录也不代表无依赖。
+- 区分开发、集成和终验前置，以及代码、契约、迁移、配置/权限与环境资源依赖。下游只需某个已通过必要检查的成果时，建议将依赖细化到该成果与解锁证据即可，不强制新增里程碑。稳定契约下可用 fixture 开发；无关走查或发布排练不默认阻塞开发，用户分期与风险门仍须遵守。
+
+无论有无 findings，都交回编排核对结论；现有编排成立时引用原计划的依赖与验收安排，有必要调整时再给建议（简单线性计划可用短表）：
+
+| 波次/任务 | 前置及解锁证据 | 可同时做的工作 | 写入边界/共享负责人 | 运行资源约束 | 汇合验收 |
+| --- | --- | --- | --- | --- | --- |
+
+只有输入稳定、前置满足、文件及运行资源无冲突时才建议并行；小任务委派成本可能高于收益，未使用 subagents 本身不构成编排缺陷。公共类型、路由注册、锁文件、迁移序号由单一负责人处理；同库迁移、端口、开发栈、浏览器会话需隔离或串行。主集成人负责整体验收与计划回写。
+
+没有工期估算时只说拓扑顺序和结构上的瓶颈链；不要声称计算出关键工期或编造“节省 X%”。不能安全并行时解释具体依赖即可。reviewer 这里只建议实施编排，不启动实施任务。
+
+## D. delivery：可用性与 UI/UX
+
+从目标使用者的完整任务反推交付，避免只检查文件是否齐全：
+
+`获得/安装 → 初始化/配置 → 登录与授权 → 找到入口 → 完成核心操作 → 确认结果 → 失败后恢复`
+
+非 UI 交付使用相应旅程：调用方接入 API、运维部署服务、开发者安装并调用 SDK。没有界面时 UI 标为“不适用”，仍须审交付可用性。
+
+- 交付物是否包含所需产物、入口、配置、迁移、权限/种子增量、示例或使用说明；安装后能否实际使用，已安装用户能否升级。
+- 主路径与失败/边界是否端到端闭环；长任务、部分成功、重复提交、权限不足、依赖不可用是否给出可理解状态和恢复办法。
+- 发布顺序、回退/补偿、观测和运维步骤是否能由目标操作者执行，验证所需账号、数据、环境和工具是否在计划中有获取办法。
+- 看似“最终验收”的内容是否只覆盖单模块或静态检查；成功结果是否能由使用者观察，而不是依赖实现者知道内部日志。
+
+涉及 UI 时读取适用的 PRODUCT/DESIGN 或等价上下文，按仓库规则使用设计 skill，核对：
+
+- 信息架构、导航和发现性是否贴近目标角色与任务；主操作和信息层级是否明确，是否把实现细节变成用户的额外工作。
+- loading、empty、error、partial、disabled、success 的语义和下一步；表单校验、操作反馈、可恢复性；破坏性操作采用与后果相称的确认或撤销。
+- 权限变化、长文本/大数据、响应式、键盘与焦点、读屏名称、对比度、主题、语言和减少动效等项目适用要求是否有方案与验收。
+- 复用组件/设计规范是否一致；不因个人审美偏好报缺陷。UX 问题说明“哪个角色做什么时，被什么阻碍，导致什么结果”。
+
+区分证据层级：
+
+| 现有材料 | 能得出的结论 | 报告措辞 |
+| --- | --- | --- |
+| 仅计划/流程描述 | 任务闭环与交互方案的合理性 | 文档推演；待实现后浏览器验收 |
+| 静态设计稿/截图 | 可见布局与信息层级 | 静态评审，不能证明交互行为 |
+| 可运行原型/页面 | 本次实际走过的主路径与边界 | 写环境、步骤、结果和证据 |
+| 环境或浏览器不可用 | 只能判断已有材料 | 未在浏览器验证；注明缺口 |
+
+已有可运行 UI 且授权与工具允许时，按项目浏览器工作流验证主路径及关键边界；有写入副作用的操作先确认授权范围，不能为评审改动真实业务数据。尚未实现的计划不因没有页面就自动 Blocked，关键在交互方案与未来验收是否足够明确。类型检查和单测不算 UI 验证。

package/skills/review-prd/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: review-prd
+description: 评审既有 PRD 或产品需求文档，核实代码现状与依赖，审查创新性、先进性、可用性、便捷体验、美观 UI、AI 赋能、SMAR、UAT 预期状态及分期终验，默认将完整评审报告落盘。用户要求 review-prd、review PRD、需求评审或检查需求是否合理且可验收时使用；不用于从零写 PRD、评审技术开发计划或仅审查代码 diff。
+---
+
+# review-prd · 基于代码事实的产品需求评审
+
+目标是判断：**在用户约束内，这份 PRD 是否充分设计了值得做、可用且体验好的产品，能否清楚交接「做什么」与「怎样算完成」，它对代码现状和前置能力的认识是否真实。** 评审既检查错误与缺口，也检查有价值的创新和 AI 机会是否被遗漏；不止审文档格式。
+
+**默认交付是已写入文件并回读核验的完整评审报告，聊天只给摘要和实际文件链接。除非用户明确要求仅聊天或不写文件，否则落盘属于评审任务本身，不额外询问是否保存；未落盘不能宣称交付完成。**
+
+`references/` 相对本文件解析。仓库规则、产品上下文、代码位置、工具和外部依赖在运行时读取，不硬编码目标仓的业务约定。回复语言跟随用户。
+
+## 边界与参考
+
+- 默认审查整份 PRD；指定差异或局部范围时，同时追踪受影响的场景、需求、验收和分期。原 PRD 与代码保持只读，默认写入仅限独立评审报告；不自动实现、改稿、写 SPMS 或发送评论。用户明确要求修订时，先形成可追踪的问题，再统一修订并复核；报告保留处置记录，PRD 正文只保留修订后的产品结论。
+- 区分**现状事实、目标能力、用户/平台约束、未证实假设、验收门槛与观察/PoC 基线**。新能力尚未实现不是 PRD 缺陷；代码当前行为也不是禁止产品演进的理由。报告指出增量与前置，不擅自把当前实现固化为需求。
+- PRD 回答 what / why / 怎样算完成。用户旅程、信息层级、视觉要求、AI 产品行为属于产品设计；内部架构、表结构、端点拆分、模型/算法选型与技术里程碑属于开发计划。UAT 定义角色、场景、预期状态与清晰判据；测试脚本、造数、故障注入、工具及 TC 创建属于测试计划。已给定技术约束、外部产品契约与作为产品能力的评测台可以保留，不能机械按技术词判越界。
+- 在可用时读取 `prd/references/product-quality.md` 校准产品质量规则；采用该模板的文档再按需读 `prd/references/prd-skeleton.md`。找不到 `prd` 时继续按本技能的实质标准评审，不要求安装依赖。用户自定义模板或历史 PRD 不因章节名、编号、缺少 TC 或未录入 SPMS 被判不合格。
+- UI 评审读取目标仓实际适用的产品/设计规范；只有能看到的材料才支持视觉结论。源码、静态稿、原型与浏览器实测分别标注，不把静态推演写成已验证体验。
+
+## 1. 锚定输入与审查基线
+
+1. 定位用户指定 PRD、原始诉求、已确认约束、关联 PRD 与必要决策。目标无法唯一确定时询问文件/范围，可以先调查仓库规则；不擅自选一份相邻文档评审。
+2. 读取适用的根目录及相关子目录规则、产品与设计上下文。记录 PRD 路径/版本或内容 hash、调查日期、代码仓路径、commit 与 dirty 状态；当前工作树参与调查时明确写出。无 Git 则用可用版本标识；读不到源代码则如实记录证据缺口，继续能做的文档审查。
+3. 提取目标、非目标、角色/权限、业务状态、关键旅程、FR/NFR、UAT/验收、依赖、产品决策、分期与终验关系。无需求 ID 时用稳定章节定位，不补造 SPMS key。只读工具可用时核对关联项目/需求与重复立项情况，不把录入状态当实现状态。
+4. 将会改变产品选择的现状主张和前置条件列入核实清单：声称已支持、未支持、可复用、无需改动、兼容、已验证及性能数字等。标清它们是事实还是未来目标。
+5. 读取 [references/report-contract.md](references/report-contract.md)，确定报告路径；记录四个审查维度及代码核实、报告写入、回读核验的状态。事实能查就先查，只向用户询问无法从证据推出的产品决定；缺少某项输入时继续不依赖它的审查。
+
+## 2. 编排四个审查视角
+
+先读 [references/review-lenses.md](references/review-lenses.md) 的对应节，再分派。各视角都以用户约束为边界，不为凑问题扩大产品范围。
+
+| 角色 | 主责 | 必须交回的专属结果 |
+| --- | --- | --- |
+| `facts` | 代码现状、依赖契约、主张真伪与内部冲突 | 现状核实矩阵：已有能力、真实增量、行为冲突、未核实项及证据 |
+| `product` | 创新、先进性、AI 价值与合理范围 | 关键产品选择的价值/取舍；有依据的遗漏机会、AI 闭环与前置 |
+| `experience` | 可用性、便捷旅程、美观 UI 与状态表达 | 各角色任务闭环；体验/视觉缺口；界面证据等级 |
+| `acceptance` | SMAR、UAT、需求追踪、分期与终验 | 目标/场景/需求/验收/UAT 的断链；独立用户价值、计划规模与终验一致性 |
+
+### 调度规则
+
+- 有多 agent 工具且当前授权允许时实际启动只读 subagents，主 agent 负责综合裁定和报告单写；不能在同一回答中扮演多个角色后宣称独立复核。简单局部文档可用两位 reviewer 各覆盖两个视角，回报分开说明覆盖与结论。模型继承主 agent，不主动覆盖模型或推理档位。
+- 并发数按实际剩余槽位安排，主 agent 也占槽位。只有 4 个总槽位时，先运行 3 个视角，结束后复用空闲 agent 完成第 4 个；更少则分批。工具/授权不允许、用户要求串行时，主 agent 按四个视角顺序审查，如实写执行方式，不能漏掉维度。
+- 初轮给 reviewer 相同基线、用户约束和原始材料，不把预设缺陷或别人的结论当答案。每个 reviewer 只读原 PRD 与代码，不能继续派生 agent，也不写最终报告。
+- 代码可并行只读；共用浏览器或外部环境由一个操作者采集证据。评审不自动跑迁移、种子、部署、收费模型评测或有副作用的业务操作。必要验证按现有授权执行，做不到则报告缺口。
+- 单个 reviewer 失败时重派一次或由主 agent 接管；不能核实的部分进入待核实项，不无限重试。
+
+### Reviewer 派发合同
+
+```text
+你负责 {facts/product/experience/acceptance}，只读评审，不实现、不改稿、不继续派生 agent。
+用户目标及范围：{原始要求、排除、已有产品决定}
+PRD 与基线：{PRD 绝对路径及版本；代码仓根、commit/dirty、日期}
+必读：{本 SKILL.md、report-contract.md、review-lenses.md 对应节的绝对路径}
+相关材料：{规则、产品/设计上下文、已知代码入口、关联 PRD/需求的实际位置}
+资源边界：{可读目录、可运行检查、外部查询与浏览器授权}
+核实产品主张依赖的实际行为；新功能未实现不算缺陷，现有代码也不是永久产品约束。
+交回：范围与基线；候选问题（PRD 定位、场景/触发、影响、证据、最小产品修订、
+复核判据、严重度与置信度）；本视角专属结果；待核实/待决定项及所需证据。
+没有问题可以返回空 findings。机会提案须说明用户价值与约束，不强制增加功能或实现方案。
+```
+
+## 3. 主 agent 交叉复核与裁定
+
+1. 逐条阅读支持候选问题的 PRD 段落与原始证据，核对角色、作用域、版本和触发条件。文件/函数存在不等于行为可用，多位 reviewer 一致也不等于事实。
+2. 现状核实至少追到 PRD 依赖的用户或外部系统可观察行为：入口/权限、关键业务逻辑、结果与状态反馈；按需求核对租户隔离、分页、重复/冲突、数据保护、失败恢复、AI 权限/预算及依赖。只读到部分链路就标部分核实，不声称端到端可用。
+3. 将证据影响传回相关视角：例如事实侧发现模型调用没有当前主体授权，产品侧复核 AI 前置，体验侧复核不可用状态，验收侧复核判据和分期。只复核受影响链路，不借机设计具体调用方案。
+4. 按根因与修订动作去重，保留所有实质不同的问题。已确认问题进入 findings，低证据主张进入待核实项；纯偏好不算缺陷，有价值但非必要的产品机会单列，不凑问题数或用总分抵消阻塞。
+5. 核对「目标 ↔ 场景 ↔ FR/NFR ↔ 验收 ↔ UAT 状态 ↔ 分期/终验」的一致性。每期要有独立用户价值；承接计划尽量 5–8 个 Milestone，连续性例外 9–10 个须有理由，最多 10 个。PRD 的规模建议不是技术任务表，不能要求其已经拆出 M1…Mn。
+6. 结束前核对 PRD 与相关代码是否并发变化；只重审受影响结论，无法收敛则标待核实。收集或停止仍在运行的 reviewer，再交付。
+
+## 4. 输出评审结果
+
+使用 [references/report-contract.md](references/report-contract.md) 的完整报告顺序和落盘合同，**先列问题，再给总体结论与修订顺序**。由主 agent 保存完整报告并回读；空 findings、代码无法访问或结论为「需补证」也要落盘。
+
+报告至少包含：
+
+- 按严重度排序且可定位的问题，附用户场景、实际后果、行为级证据、最小产品修订与复核条件。
+- 代码现状核实矩阵、关键依赖和待核实项；区分静态代码、现有测试、实际运行与浏览器证据，不把尚待开发的目标报成当前缺陷。
+- 四维覆盖及六个产品设计维度的实质结论、SMAR/UAT 与分期终验的断链；不因缺少固定章节或 TC 判错。
+- 建议结论 **通过 / 需修订 / 需补证**，写清阻塞范围与解除条件；有价值的非阻塞机会与修订优先顺序。
+
+**评审通过仅表示在已核实范围内可作为开发/测试计划的输入，不表示功能已实现、性能已实测、UI 已验证或可直接上线。** 最终聊天回复给实际报告链接、结论和关键问题/待核实项摘要。写入失败时说明「报告未落盘」并按合同保留完整内容，不能链接不存在的产物。

package/skills/review-prd/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "PRD 评审"
+  short_description: "核实代码现状，审查产品价值、AI、UI、UAT、SMAR 与分期，产出有证据的评审报告"
+  default_prompt: "使用 $review-prd 评审指定 PRD，核实代码现状及关键依赖，将有证据的问题、产品改进建议和结论写入完整评审报告，默认落盘并回读核验，回复报告链接与摘要。"

package/skills/review-prd/references/report-contract.md

@@ -0,0 +1,64 @@
+# 问题判定与 PRD 评审报告合同
+
+## 落盘与交付
+
+- **默认保存完整 Markdown 报告**；只有用户明确要求仅聊天或不写文件时跳过。聊天正文、拟写入内容和路径预告都不算已落盘，不把「是否保存」留作交付前的确认问题。
+- 路径优先级：用户指定 → 本地 PRD 同目录的 `<PRD 文件名去掉扩展名>.review.md`。输入只有聊天文本/远程文档时遵循仓库报告目录惯例，无惯例则写当前工作区的 `docs/reviews/<主题短名>.review.md`。按需建目录，不因未给路径停下。
+- 写入前检查同名。已授权更新/覆盖该报告则执行；否则保留旧报告，依次尝试同目录 `<主题>.review.<YYYY-MM-DD>.md`、`<主题>.review.<YYYY-MM-DD>-2.md` 等未占用名称。用户指定路径冲突也保留旧文件并说明实际路径，不覆盖原 PRD 或代码。
+- 主 agent 单写完整报告并回读实际文件，核对 findings、待核实项、代码矩阵、覆盖、映射/分期、结论和修订顺序齐全；检查引用定位与文件链接。空 findings、缺源码或「需补证」不免除落盘。
+- 最终聊天给实际报告链接、结论与关键摘要；仅聊天模式在聊天交付完整报告。写入工具不可用或失败时明确「报告未落盘」、原因与目标路径，在聊天保留完整结果，将保存标为未完成；不能链接不存在的文件。
+
+## 什么进入 findings
+
+确认的问题同时具备：PRD 可定位的主张/缺口、已核实依据、具体用户场景/触发、对已确认目标的实际后果、可执行的最小产品修订。每条一个独立根因，重复症状合并但保留关键定位。纯格式、偏好或无关旧代码问题不进入 findings。
+
+「没有写 X」先查正文、引用、附录及已确认约束，证明 X 是本产品目标的必要条件；章节标题不同不算缺失。新功能未实现不算 PRD 错误；可确认的前置误判、虚假现状或缺少产品增量才是问题。源码未定位、依赖未联调不是「能力不存在」的证据。
+
+证据不足的主张放待核实项，写需什么证据及对结论的影响；关键证据缺口仍可阻塞通过。高价值且在约束内的增强机会有依据则单列提案，不能把每个合理备选都报成缺陷，更不能借评审自行增加产品承诺。
+
+## 严重度与置信度
+
+| 等级 | PRD 评审中的含义 |
+| --- | --- |
+| P0 | 已确认的产品规则直接要求重大安全、数据或业务灾难，需立即纠正；极少使用 |
+| P1 | 核心任务、权限/数据边界、关键依赖或终验口径存在高影响错误/缺口，进入下游计划前须修订 |
+| P2 | 局部产品行为、体验、验收或分期存在可证实缺口，相关范围交接前修正 |
+| P3 | 有明确依据和收益的小改进，不阻塞交接；个人偏好不算问题 |
+
+严重度表示后果，置信度用高/中及依据表达证据强弱。仅猜测的风险不能靠降为 P3 混进 findings，不设问题数或评分指标。
+
+## 单条问题格式
+
+```markdown
+1. [P1] F-01 · <可行动的标题>
+   - 定位：<PRD 文件:行号/稳定章节；冲突时两处；需求/场景/验收 ID>
+   - 场景与问题：<什么角色在什么条件下要完成什么，按当前 PRD 会产生什么后果>
+   - 证据：<读过的代码文件:精确行号/符号、用户约束/规则定位、运行证据或官方文档 URL/版本/日期>
+   - 修订：<最小需要补定/改正的产品行为、状态、边界、前置或验收；不展开内部实现>
+   - 复核：<改稿后应一致的产品断言/依据；未来效果验证与本次文档复核分开>
+   - 置信度：<高/中 + 依据>；阻塞：<目标/需求/交接范围或否>
+```
+
+本地引用使用可点击文件链接与短行定位，必要时补稳定标题/符号；定位指向原 PRD 应承载要求的位置，不指向 reviewer 自己的新报告。只引用读过的原文，截断内容先补读；不能把外部例子数字当成本产品承诺。
+
+## 完整报告顺序
+
+1. **确认问题**：P0 → P3，F-01 等稳定编号；无确认问题如实写「未发现可确认的问题」。复审沿用编号，区分已解决、仍存在、新增。
+2. **待核实/待决策**：缺什么证据或产品决定、影响哪项需求、谁能提供及应在何交接节点前明确；负责人未知写待指定，不虚构日期或用户承诺。
+3. **代码现状核实矩阵**：`PRD 主张/定位 | 类型 | 实际行为与证据等级 | 已有满足/部分满足/真实增量/行为冲突/未核实 | 产品影响`。代码读不到仍列关键主张、调查限制和所需材料，不留空表假装核实完毕。
+4. **覆盖与基线**：PRD 版本/路径、代码仓/commit/dirty、日期、实际 reviewer 分工或串行方式、四维覆盖。六个产品维度分别给结论/不适用理由；记录实际代码、测试、设计稿及浏览器证据等级与缺口，只列结论相关来源，不倾倒读文件日志。
+5. **需求追踪与分期终验**：列目标/场景/需求/验收/UAT 断链或已核对范围；检查每期独立价值、5–8 个 Milestone 预算/最多 10 个的连续性例外、关键前置、跨期终验及相互冲突的口径。建议产品交付顺序，不生成技术任务、并行波次或测试脚本。
+6. **产品增强机会**：有依据的非必要提案，写价值、场景、约束/代价及采用后需调整的需求；无则写「无」，不为创新凑数。
+7. **总体结论与修订顺序**：建议结论、阻塞范围与解除条件。先修事实/约束，再定产品语义/体验/AI，随后同步验收、UAT 和分期终验。未解决的重大未知不能藏进「通过」。
+
+短 PRD 可以用紧凑段落/表格承载这些内容；完整报告不是固定字数，也不是 reviewer 原始回报的拼接。结构借鉴 `review-dev-plan`，判断对象是产品需求，不沿用其实施就绪状态或技术编排要求。
+
+## 结论口径
+
+- **通过**：所审范围产品目标、行为、状态、验收与分期清楚，关键现状和前置有证据，剩余建议不影响交接；说明覆盖限制。
+- **需修订**：有已确认且阻塞交接的产品问题，列具体范围和修订条件。无关独立能力可单列已满足条件，不能将整份含阻塞的 PRD 宣称通过。
+- **需补证**：暂无已确认的交接阻塞，但关键现状、依赖或产品决定仍不能成立/未确认，列所需证据与节点。已有阻塞缺陷同时存在时用「需修订」并继续列补证项。
+
+状态按影响与证据判断，不能靠总分平均。纯产品方向已经足够明确、技术实现选择留给开发计划时，不因尚无架构方案阻塞 PRD；核心依赖能力是否存在/授权/适配仍须核实。
+
+评审通过不表示功能已实现、线上部署、性能达标、UI 已通过浏览器验收，也不自动批准需求或变更 SPMS 状态。