ai-project-manage-cli 1.0.4 → 1.0.6

package/templates/skills/mr-review-brief/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: mr-review-brief
+description: 在功能分支上相对 main/master 生成 MR 评审说明：功能变更、复杂项实现思路、对照仓库约定的规范符合性、建议验证步骤。供人类审核 AI 或大批量 diff，避免看不懂直接打回。用户主动触发；提及 MR 评审说明、评审摘要、变更说明、代码评审说明、release-checklist（历史名称）时使用。
+---
+
+# MR 评审说明（供人类审核）
+
+**目的**：把相对基准分支的改动整理成评审者可读的说明，**不是**上线清单。重点三件事：
+
+1. **功能面**：改了什么、用户侧前后差异、该验什么。  
+2. **实现思路（复杂项）**：AI/作者为何这样拆问题、数据流或调用链、与现有模块如何衔接，避免评审者对着大段 diff 无从读起。  
+3. **规范符合性**：对照本仓库已有约定（`AGENTS.md`、`.cursor/rules` 等）做**诚实对照**，便于确认 AI 是否按项目规矩办事。
+
+## 触发前提
+
+- **仅在新分支执行**：当前分支必须不是 `main` 或 `master`
+- **用户主动触发**：如「生成 MR 评审说明」「评审摘要」「给 MR 写说明」等
+
+若当前在 main/master，提示：请先切换到功能分支再生成。
+
+## 核心原则
+
+- **按功能写正文**，不把「文件 M/A/D 列表」当正文主体；需要指到代码时，用少量**关键路径**（文件或模块名）辅助复杂项说明即可。  
+- **实现思路**用自然语言与少量结构化小标题，**禁止**大段粘贴源码。  
+- **规范符合性**：只能写**有据可查**的结论；不确定一律标为 **待评审核对** 并写明要查什么，**禁止**无依据写「已全部遵守规范」。  
+- 功能描述要**具体**：「之前 → 现在」，禁止空泛「调整了 XX 模块」。
+
+## 执行流程
+
+1. **获取变更**（只读 git）：
+
+```bash
+git branch --show-current
+git log main..HEAD --oneline   # 或 master..HEAD
+git diff main..HEAD --name-status
+git diff main..HEAD            # 必要时查看具体 diff
+```
+
+2. **按功能归纳**：业务功能维度、影响页面/流程；识别**复杂项**（填法见模板文件末尾注释中的 `{RATIONALE_COMPLEX}`）。
+
+3. **规范对照**（按变更范围选读，不必全文背诵）：
+
+   - 仓库根：`AGENTS.md`（Rush、子项目命令、Prisma 等）
+   - 若涉及前端：`apps/fe/AGENTS.md`
+   - 若涉及后端：`servers/be/AGENTS.md`
+   - 与改动相关的 `.cursor/rules`（如 Rush 命令规范）
+
+   将**与本次 diff 可能相关的条目**逐条对照，写入 `{CONVENTION_COMPLIANCE}`。
+
+4. **填充模板**：`mr-review-template.md`，替换全部占位符。
+
+5. **交付**：
+
+   - **必须在对话中输出完整 Markdown**，便于粘贴到 MR 描述或首条评论；**勿包含**模板末尾的 `<!-- 填法... -->` 注释块。
+   - **落盘**（可选）：仅当用户明确要求且提供保存位置时写入，默认**不落盘**。
+
+## 模板占位符
+
+模板路径：`mr-review-template.md`。
+
+| 占位符 | 含义 |
+|--------|------|
+| `{BRANCH_NAME}` | 当前分支名 |
+| `{DATE}` | 生成日期 |
+| `{BASE_BRANCH}` | main 或 master |
+| `{SCOPE}` | 前端 / 后端 / 全栈 / 公共 等 |
+| `{FUNCTION_CHANGES}` | 功能变更正文 |
+| `{RATIONALE_COMPLEX}` | 复杂项实现思路 |
+| `{CONVENTION_COMPLIANCE}` | 规范符合性 |
+| `{VERIFY_SUGGESTIONS}` | 建议验证步骤 |
+
+**各占位符的正文结构、字段与示例**：见模板**文件末尾** `<!-- ... -->` 填法注释。生成粘贴到 MR 的 Markdown 时**不要输出该 HTML 注释块**。
+
+**仅在 SKILL 强调（注释里不重复展开）**：规范结论须与「核心原则」一致——有据才写「已遵守」，否则标「待评审核对」并写清查什么。
+
+## 实现注意
+
+- 只读命令：`git branch`、`git diff`、`git log`、`git show-ref`  
+- 基准分支：优先 `main`，否则 `master`

package/templates/skills/mr-review-brief/mr-review-template.md

@@ -0,0 +1,47 @@
+# MR 评审说明 - {BRANCH_NAME}
+
+**生成时间**：{DATE}  
+**对比基准**：{BASE_BRANCH}  
+**变更范围**：{SCOPE}
+
+---
+
+## 功能变更
+
+{FUNCTION_CHANGES}
+
+---
+
+## 实现思路（复杂项）
+
+{RATIONALE_COMPLEX}
+
+---
+
+## 项目规范符合性
+
+{CONVENTION_COMPLIANCE}
+
+---
+
+## 建议验证
+
+{VERIFY_SUGGESTIONS}
+
+<!--
+填法（勿粘贴到 MR 正文）：输出时去掉本注释块。
+
+{FUNCTION_CHANGES} — 每个功能一段：
+### N. {功能/页面名称}
+- 之前：{行为}
+- 现在：{行为}
+- 影响范围：{入口、流程、页面（产品语言）}
+
+{RATIONALE_COMPLEX} — 仅复杂项展开（多文件联动、新抽象、非直观重构、关键算法或状态机）；简单增删改写「本次以局部增删为主，无单独展开的实现思路。」
+每复杂项可用二级标题，含：要解决的问题（1～2 句）；实现要点（拆分、数据流/调用链、与现有代码接点）；若有明显取舍可一句说明。
+
+{CONVENTION_COMPLIANCE} — 列表或表格，每条：规范来源；状态：已遵守 | 不适用 | 待评审核对；说明一句。
+已遵守须能指向本次改动中的体现；待评审核对须写清评审要查什么；未触及的规范勿强行已遵守。
+
+{VERIFY_SUGGESTIONS} — 与功能对应或可合并为场景流；步骤可执行，写清预期结果。
+-->

package/templates/skills/openspec-apply-change/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: openspec-apply-change
+description: 根据 OpenSpec 变更实施任务。在用户希望开始实现、继续实现或逐项完成任务时使用。
+license: MIT
+compatibility: 需要 openspec CLI。
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.2.0"
+---
+
+根据 OpenSpec 变更实施任务。
+
+**输入**：可选指定变更名称。若未指定，先尝试从对话上下文推断；若仍无法唯一确定，按步骤 1 的固定规则选定变更。**不要**向用户发起反问式确认或交互式选题。
+
+**步骤**
+
+1. **选择变更**
+
+   若已提供名称则直接使用。否则：
+   - 若用户在对话中提到了变更，从上下文推断
+   - 若仅存在一个活跃变更，自动选中
+   - 若仍有歧义：运行 `openspec list --json`，**按 CLI 返回列表中的第一个候选**作为本次变更（若你的环境有更稳定的排序字段，以「列表顺序优先」为准）；在回复中列出当时可见的候选名，并声明「使用变更：<name>」以及如何覆盖（例如 `/opsx:apply <其他>`）。**不要**调用 AskUserQuestion，**不要**停下来让用户当场选择。
+
+   始终声明：「使用变更：<name>」以及如何覆盖（例如 `/opsx:apply <其他>`）。
+
+2. **查看状态以理解 schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   解析 JSON 以了解：
+   - `schemaName`：当前工作流（例如 `"spec-driven"`）
+   - 任务清单在哪个工件中（spec-driven 通常为 `tasks`，其他 schema 以 status 为准）
+
+3. **获取 apply 说明**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   返回内容包括：
+   - 上下文文件路径（因 schema 而异，可能是 proposal/specs/design/tasks 或 spec/tests/implementation/docs）
+   - 进度（总数、已完成、剩余）
+   - 带状态的任务列表
+   - 基于当前状态的动态说明
+
+   **处理状态：**
+   - 若 `state: "blocked"`（缺少工件）：展示提示，建议使用 openspec-continue-change
+   - 若 `state: "all_done"`：祝贺完成，建议归档
+   - 其他情况：进入实现
+
+4. **阅读上下文文件**
+
+   阅读 apply 说明输出中 `contextFiles` 列出的文件。
+   文件取决于所用 schema：
+   - **spec-driven**：proposal、specs、design、tasks
+   - 其他 schema：以 CLI 输出的 contextFiles 为准
+
+5. **展示当前进度**
+
+   展示：
+   - 所用 schema
+   - 进度：「N/M 个任务已完成」
+   - 剩余任务概览
+   - CLI 返回的动态说明
+
+6. **实现任务（循环直至完成或阻塞）**
+
+   对每个待办任务：
+   - 说明正在处理哪一项
+   - 完成所需代码改动
+   - 保持改动最小、聚焦
+   - 在标记完成前收集依据：
+     - `Requirement IDs`：本实现满足哪些需求
+     - `Planned Files` 与实际改动文件：若有合理偏差需注明
+     - `Validation Case IDs`：为验证行为执行了哪些用例
+     - `Validation Result`：通过/失败及简要断言摘要
+   - 仅在依据已记录且验证通过后，在任务文件中将 `- [ ]` 改为 `- [x]`
+   - **Git**：本待办对应的实现与任务勾选等改动，**单独提交一个 commit**（一项待办 = 一个 commit；不要把多项待办混在同一 commit）。提交信息建议包含变更名与任务标识或简述。
+   - 继续下一项
+
+   **暂停条件：**
+   - 任务不清晰 → 依据上下文与已有工件做合理推断并继续；必要时在说明中写明假设，**不反问用户**
+   - 实现暴露设计问题 → 建议更新工件（陈述式说明，不提问）
+   - 遇到错误或阻塞 → 报告原因与可选后续，**不反问用户**
+   - 用户中断
+
+7. **完成或暂停时展示状态**
+
+   展示：
+   - 本会话完成的任务
+   - 总体进度：「N/M 个任务已完成」
+   - 若全部完成：建议归档
+   - 若暂停：说明原因并列出可选后续（陈述式，**不反问用户**）
+
+**实现过程中的输出**
+
+```
+## 正在实施：<change-name>（schema: <schema-name>）
+
+处理任务 3/7：<task description>
+[...实现过程...]
+✓ 任务完成 · commit <short-sha> <subject>
+
+处理任务 4/7：<task description>
+[...实现过程...]
+✓ 任务完成 · commit <short-sha> <subject>
+```
+
+**完成时的输出**
+
+```
+## 实现完成
+
+**变更：** <change-name>
+**Schema：** <schema-name>
+**进度：** 7/7 个任务已完成 ✓
+
+### 本会话已完成
+- [x] Task 1
+- [x] Task 2
+...
+
+（每项待办均已对应独立 commit。）
+
+全部任务完成！可以归档此变更。
+```
+
+**暂停时的输出（遇到问题）**
+
+```
+## 实现已暂停
+
+**变更：** <change-name>
+**Schema：** <schema-name>
+**进度：** 4/7 个任务已完成
+
+### 遇到的问题
+<问题描述>
+
+**可选后续：**
+1. <选项 1>
+2. <选项 2>
+3. <选项 3>
+
+（陈述即可；不要求用户当场作答。）
+```
+
+**约束**
+- 持续执行任务直至完成或阻塞
+- 开始前务必阅读上下文文件（来自 apply 说明输出）
+- 若任务有歧义，先依据上下文与 spec 做合理推断并实现；**不**为澄清而反问用户
+- 若实现暴露问题，暂停并建议更新工件
+- 代码改动保持最小、与每项任务范围一致
+- 未完成需求映射与验证依据前，**不要**将任务勾为完成
+- 若验证失败或缺少依据，保持任务未勾选并明确报告缺口
+- 若任务元数据缺失（Requirement IDs / Planned Files / Validation Case IDs / Done Criteria），在可能的情况下于实现前补全
+- 每完成一项任务并记录依据后，立即更新对应勾选框，并**随即**为该待办单独 `git commit`（一项待办一个 commit）
+- 遇错误或硬阻塞时暂停并说明原因；需求不清时在任务说明中记录假设与风险，**不反问用户**
+- 使用 CLI 输出的 contextFiles，不要假定具体文件名
+
+**与流动工作流的衔接**
+
+本技能支持「对变更执行操作」模型：
+
+- **可随时调用**：不必等所有工件就绪（若已有任务）、可在部分实现之后、可与其他操作穿插
+- **允许更新工件**：若实现暴露设计问题，建议更新工件——不锁阶段，可灵活推进

package/templates/skills/openspec-propose/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: openspec-propose
+description: 以明确的需求文档为输入，一步生成 OpenSpec 变更工件（proposal/design/tasks/specs）。在用户只需要规格与实现规划、不需要手工测试用例时使用。
+license: MIT
+compatibility: 需要 openspec CLI。
+metadata:
+  author: openspec
+  version: "1.1"
+  generatedBy: "1.2.0"
+---
+
+提出新变更——在**需求文档**基础上创建变更并生成 OpenSpec 工件。
+
+范围边界：
+- 本技能仅用于规格/规划类工件（`proposal.md`、`design.md`、`tasks.md`、specs）。
+
+将创建包含以下内容的变更：
+- proposal.md（做什么、为什么）
+- design.md（怎么做）
+- tasks.md（实现步骤）
+
+---
+
+**输入（必须满足）**
+
+1. **明确的需求文档**——二选一或同时提供：
+   - 文档**正文**（粘贴到对话中），或
+   - 仓库内**文件路径**（由你读取该文件）。
+2. **变更名**（kebab-case）——可选；若未给出，由你从需求文档中归纳 kebab-case 名称，**不要**为命名向用户追问。
+
+**不满足时不继续**：仅有模糊想法、没有可引用的需求正文/文件时，说明本技能需要「可对照的需求文档」，请用户先整理需求或指明文档路径后再触发。
+
+---
+
+**执行流程**
+
+### 1. 锚定需求与变更名
+
+- 若给的是路径：用 Read 读取全文，确认可读、无截断。
+- 通读需求文档，标记：目标用户/场景、功能范围、非目标、约束、验收口径。文档未写明的部分：**不要**向用户追问；在 `proposal.md` / `design.md` 中写明合理**假设**，或列为**已知缺口/风险/待后续补充**，并在任务中体现需实现侧拍板的内容。
+- 确定或推导变更目录名 `<name>`（kebab-case）。若与已有 `openspec/changes/<name>/` 冲突：在 `proposal.md` 中说明与既有变更的关系；若需新建目录则自动采用不冲突名称（例如在原名后加 `-2`、`-extend` 等），**不要**为此反问用户。
+
+### 2. 创建变更脚手架
+
+```bash
+openspec new change "<name>"
+```
+
+会在 `openspec/changes/<name>/` 下生成带 `.openspec.yaml` 的变更脚手架。
+
+### 3. 获取工件构建顺序
+
+```bash
+openspec status --change "<name>" --json
+```
+
+解析 JSON：
+
+- `applyRequires`：实现前需完成的工件 ID 列表（例如 `["tasks"]`）
+- `artifacts`：所有工件及其状态与依赖
+
+### 4. 按依赖顺序生成工件（需求文档为唯一事实来源）
+
+使用 **TodoWrite** 跟踪各工件进度。按依赖顺序遍历（先处理无待处理依赖的工件）。
+
+对每一个依赖已满足的 `ready` 工件：
+
+a. 获取该工件的生成说明：
+
+```bash
+openspec instructions <artifact-id> --change "<name>" --json
+```
+
+说明 JSON 含：`context`、`rules`、`template`、`instruction`、`outputPath`、`dependencies`（**不要**把 `context`/`rules` 写入输出文件）。
+
+b. 读取已完成的依赖文件；**撰写正文时严格以需求文档为准**，将需求中的条目映射到 `template` 各节，避免臆造未在需求中出现的范围。
+
+c. 按 `template` 结构写入 `outputPath`。创建 `tasks` 时，每项任务须含可追溯元数据：
+
+- `Requirement IDs`：对应规格中的需求 ID
+- `Planned Files`：预期改动的文件路径
+- `Validation Case IDs`：验证用例 ID（若有）
+- `Done Criteria`：可观察的完成标准
+
+d. 简短提示：「已创建 <artifact-id>」
+
+e. 每完成一个工件后重新执行：
+
+```bash
+openspec status --change "<name>" --json
+```
+
+直到 `applyRequires` 中所有工件在 `artifacts` 里均为 `status: "done"`。
+
+### 5. 展示最终状态
+
+```bash
+openspec status --change "<name>"
+```
+
+---
+
+**输出**
+
+完成所有工件后汇总：
+
+- 变更名称与路径
+- 已创建工件列表及简要说明
+- 说明需求文档如何反映在各工件中（一两句即可）
+- 就绪说明：「所有工件已创建！可以开始实现。」
+- 提示：「执行 `/opsx:apply` 或让我来实现，即可开始处理任务。」
+
+---
+
+**工件编写指引**
+
+- 各工件类型遵循 `openspec instructions` 返回的 `instruction` 与 `template`。
+- **需求文档**是范围与验收的权威来源；`context`/`rules` 是给你的约束，**不得**写入输出文件。
+- 创建新工件前先读依赖工件，保持与已写规格一致。
+- 实现细节优先落在 `tasks.md`：spec 写行为与需求，task 写可追溯的实现与验证映射。
+
+**护栏**
+
+- 按模式中 `apply.requires` 创建**全部**必需工件。
+- 每写入一个工件后确认文件存在，再进入下一个。
+- 对任务项保留 Requirement IDs、Planned Files、Validation Case IDs、Done Criteria，便于后续审计。
+- 需求与现有变更冲突或同名目录已存在时：按上文规则在文档中说明关系或自动换名，**不要**反问用户。

package/templates/skills/requirement-doc-refine/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: requirement-doc-refine
+description: 依据用户提供的补充信息（如对评审的回复、澄清与拍板口径）完善需求文档，合并定稿后经 CLI（apm comment process）存档。须同时提供需求原文、评审内容作对照与 requirementId、versionSeq；以补充信息为准，未回应的评审点不自动当成待办。仅在用户明确声明使用本技能时应用（例如 @ 本 SKILL 或写明 requirement-doc-refine）；不因泛泛表述自动启用。
+---
+
+# 需求文档完善（基于补充信息）
+
+本技能用于在**需求原文**之上，结合用户给出的**补充信息**，把零散说明整理成**结构清晰、可执行**的一版需求正文，并通过 CLI 提交以写入需求内容版本。补充信息**常见**为针对评审的逐条回应，亦可包含用户明确提供的其他修订说明；**仅**将用户明确要写入的口径并入正文，不替用户发挥。
+
+## 触发条件
+
+- **必须**：用户**明确声明**使用本技能（例如在对话中 @ 本 `SKILL.md`、或写明使用 `requirement-doc-refine` /「用需求文档完善技能」等可核验的指代）。
+- 未作上述声明时，**不**因「帮我完善需求」「合并补充信息进 PRD」「根据评审改需求」「更新需求文档」等表述自动套用本技能的工作方式与模板。
+
+满足触发后，再按下节收集材料并执行；若缺「需求原文」「补充信息（用户回应）」「评审内容」或存档所需的 **`requirementId`**、**`versionSeq`**（修订所基于的版本序号），先索要再执行。
+
+## 输入（按需收集）
+
+声明使用本技能后，还须具备：
+
+- **必需**：**需求原文**、**评审内容**、**补充信息（用户回应）**（含对哪些点做了补充；可不要求逐条对齐评审编号）、**`requirementId`**（需求 id，整数）、**`versionSeq`**（该需求下作为修订基准的版本序号，与界面 `v1`、`v2` 一致，非数据库 id），与定稿正文一起在首轮给出，供第 5 步 `apm comment process` 使用。
+- **评审内容**：完整评审 Markdown（或与本次修订对应的摘录），用于把补充信息与评审条目对上号；**不得**据此单方面改需求。
+
+| 输入 | 说明 |
+|------|------|
+| **需求原文** | 待完善的 PRD/需求全文或关键段落 |
+| **评审内容** | 与本次修订对应的评审正文（或摘录）；用于对照，**不得**单独驱动改写 |
+| **补充信息（用户回应）** | 用户明确要写入需求或明确补充/修正的口径；**未提及的评审点一律不主动处理** |
+| **`requirementId`** | 需求 id，对应 CLI `--requirement-id` |
+| **`versionSeq`** | 修订所基于的版本序号（与界面 `v1`、`v2` 一致），对应 CLI `--version-seq` |
+
+可选：**修订范围**（全文重写 / 只改某几节）、**术语表**、**必须保留的编号**。
+
+## 合并原则
+
+1. **正文依据 = 需求原文 + 补充信息**：只把用户在补充信息中**明确**要体现的内容（补充、修改、删除、拍板口径）合并进修订稿；用户没说到的，**保持原文或不写**，**不自作主张**补需求、不替用户「落实」评审建议。
+2. **未回应的评审**：不列入「待确认」、不改成待办、不推断「仍有问题」；视为用户未要求在本次修订中处理（可能无此问题、暂不改、或评审误解）。
+3. **评审的定位**：仅辅助理解补充信息在回应什么；补充信息与评审不一致时，**以补充信息为准**。
+4. **消除重复**：同一议题在原文与补充信息中多处出现时，合并为**一处**表述。
+5. **可追溯（轻量）**：可选「修订说明」概括相对原文的变化，且**只写补充信息实际带来的变化**，不罗列未采纳的评审。
+6. **与仓库一致**：对照 `AGENTS.md`、`docs/product-capability-inventory` 等，避免修订稿与用户已确认表述冲突；**禁止**用代码路径当需求论据。
+
+## 输出
+
+- **默认**：输出 **Markdown** 形式的**更新后需求**（或用户指定章节），结构参考 [updated-requirement-template.md](updated-requirement-template.md)；**定稿全文**作为第 5 步传给 `apm comment process` 的正文（`--content` 或 `--content-file`）。
+- **用户只要补丁**：仍须合并为**完整一版**正文再存档（对话中可附「变更摘要」便于阅读）。
+- **语言**：与需求原文一致（中文为主时全文中文）。
+
+## 执行步骤
+
+1. 以**原文**为底稿，对照**评审内容**，逐条落实**补充信息**中明确要求写进需求的修改。
+2. 仅当某条补充信息明显对应某条评审时，再辅助定位修改位置；**跳过**用户完全未提的评审条目（仍须已提供评审全文/摘录以便对照，但不据此发挥）。
+3. **「待确认」**：仅当**用户自己在补充信息里**留下未决口径、或明确说「待定」「再议」时写入；**不因**评审提了而用户未提供对应补充就填「待确认」。
+4. 通读检查：无内部矛盾；正文无不来自补充信息的「新需求」。
+5. **存档需求版本（使用 CLI）**：将第 4 步定稿的**完整修订稿**通过 CLI 命令提交，由服务端处理该版本下「待处理」评论并创建新版本（同步需求正文）。
+
+   - **命令**：`apm comment process`
+   - **必填参数**：
+     - `--requirement-id <id>`：需求 id（即本技能输入的 `requirementId`）
+     - `--version-seq <n>`：该需求下的版本序号（与界面 `1`、`2` 一致，非数据库 id）
+     - `--content <text>` 或 `--content-file <path>`：修订后的需求正文全文（二选一）
+
+   **示例（推荐文件方式，避免多行转义）**：
+
+   ```bash
+   apm comment process \
+     --requirement-id 1 \
+     --version-seq 2 \
+     --content-file ./updated-requirement.md
+   ```
+
+   **示例（直接传文本）**：
+
+   ```bash
+   apm comment process \
+     --requirement-id 1 \
+     --version-seq 2 \
+     --content "这是要存档的一版需求正文内容……"
+   ```
+
+   实际调用时把 `requirementId`、`versionSeq` 换成首轮给出的值，把 `content`（或 `content-file` 指向的文件内容）换成第 4 步成文结果。命令失败时说明错误信息；成功时可简要确认已创建新版本并返回处理结果。若用户**另行**要求写入仓库内某路径，再按需保存文件。
+
+## 自检清单
+
+- [ ] 修订稿中的新增/变更均可追溯到补充信息（或用户要求保留的原文），无「替用户采纳评审」的发挥
+- [ ] 未把未回应的评审当成待解决问题写进文档
+- [ ] 未把评审人猜测当事实写进需求
+- [ ] 修订稿单读可理解，不依赖聊天记录才能懂
+- [ ] `apm comment process` 传入的正文与定稿修订稿一致，`--requirement-id`、`--version-seq` 与用户给定一致
+
+## 附加资源
+
+- 推荐输出结构：[updated-requirement-template.md](updated-requirement-template.md)

package/templates/skills/requirement-doc-refine/updated-requirement-template.md

@@ -0,0 +1,39 @@
+# [需求标题]（修订稿）
+
+**修订说明**（可选）
+
+- 基于评审日期 / 评审记录：简要一句
+- 本次合并的要点：1～3 条 bullet
+
+---
+
+## 背景与目标
+
+（合并原文与用户补充信息中明确补充/修正的表述）
+
+## 范围
+
+- **包含**：
+- **不包含**：（若**补充信息**或原文中明确收窄/排除）
+
+## 需求说明
+
+### 需求点 1：[名称]
+
+（将原文与补充信息合并后的**可执行描述**写清：角色、场景、规则、口径、边界）
+
+### 需求点 2：…
+
+## 非功能与约束（若有）
+
+（性能、权限、兼容、埋点等——仅当原文或补充信息涉及）
+
+## 待确认
+
+仅当**用户自己在补充信息里**留下未拍板事项、或写明「待定」「再议」等时列出（可选章节，可整节省略）：
+
+- [ ] （用户未决口径摘要）— 用户原话或简要归纳
+
+---
+
+若用户只需要「替换某几段」而非全文，可仅在回复中给出**修改后的完整段落** + 简短「相对原文的变更摘要」，不必机械填满所有章节。

package/templates/skills/requirement-review/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: requirement-review
+description: 结合本仓库上下文对需求做结构化评审，按 output-template.md 形成完整 Markdown 评审正文，并通过 CLI 写入评论正文（可不落盘本地文件）。输入为需求正文及 `commentId`（首轮与正文一起给出）。仅在用户明确声明使用本技能时应用。
+---
+
+# 需求评审（仓库内）
+
+## 触发条件
+
+- **必须**：用户**明确声明**使用本技能（例如在对话中 @ 本 SKILL）
+- 未作上述声明时，**不**因「帮我看看需求」「评审一下」等表述自动套用本技能的工作方式与输出模板
+
+满足触发后，用户须在**首轮对话**中一并给出：**需求正文**、`commentId`（评论 id）。不要求路径或附件。
+
+## 输入
+
+- **需求正文**：用户粘贴的待评审内容
+- **`commentId`**：评论记录 id（整数，与正文一起在对话中给出）
+
+若首轮未给出 `commentId`，须先向用户索要后再执行第 6 步。
+
+## 输出
+
+- **评审正文**：须先按模板在**逻辑上**成文（完整 Markdown 字符串），不得仅给零散要点。可在回复中展示、可选保存为 `.md`，**均非必须**；第 6 步的 `content` 即该字符串，**无需**先写入仓库文件再请求接口。
+- 将需求拆成若干条「需求点」（若本就一条则一条），对每条按 [output-template.md](output-template.md) 的**字段规则与并存关系**输出结论。
+- 语言面向产品/研发可读：少堆砌实现细节，**不**用具体文件路径、函数名当「证据」；仓库仅用于理解**能力边界、术语与业务上下文**。
+
+结构要点（细节以 `output-template.md` 为准）：`### 需求点 n`、`- **需求描述：**:` 及可选的 `业务合理性` / `问题` / `可行性` / `风险点`；**严禁** H1/H2 与表格。
+
+## 评审原则
+
+1. **产品视角优先**：用户侧影响、业务闭环、风险与待确认点；避免晦涩技术术语堆砌。
+2. **与仓库对齐（能力边界）**：阅读 `AGENTS.md`、子项目说明、`docs/product-capability-inventory` 等与需求相关的部分，判断需求是否与既有能力/术语冲突、是否超出现有边界。**禁止**用「某文件某行」证明 PRD 对错；**禁止**根据代码**猜测** PRD 未写清的口径——口径不清应归入「问题」待产品澄清。
+3. **业务合理性（按需）**：结合仓库可读的业务/产品上下文，判断需求是否想清楚、方案是否当下较优、是否与业务目标或流程冲突。**仅当**不合理、需再商榷或非当下较优时，才写 `- **业务合理性：**:`；合理则**不写**该字段。
+4. **信息完备与落地（互斥规则）**：
+   - 仅当 PRD/需求信息**不足以**形成开发可执行描述（关键落点、口径、范围、汇总规则等无法确定）时，写 `- **问题：**`，此时**不写**可行性与风险点。
+   - 若已足以判断「可以实现」（非关键细节不阻塞落地），写 `- **可行性：**`（成本低/中/高 + 精简说明）；影响面大时再追加 `- **风险点：**`。
+5. **澄清优先但不泛问**：不阻塞落地则不提问；不问可推断的琐碎问题。
+
+## 执行步骤
+
+1. **锁定正文**：以用户提供的全部需求正文为准；若明显缺段或指代不清，在「问题」中列出待澄清点。
+2. **按需读仓库**：快速扫 `AGENTS.md`、`apps/fe/AGENTS.md`、`servers/be/AGENTS.md` 及 `docs/product-capability-inventory` 中与需求相关的条目；不展开无关模块代码。
+3. **拆条**：多条诉求时拆成 `### 需求点 1..N`，每条独立走完「业务合理性（可选）→ 问题 或 可行性（+风险）」逻辑。
+4. **成文**：按 `output-template.md` 拼出完整 Markdown 字符串（顶格可加 `### 评审人` + 当前模型名）；该字符串即评审正文，可与是否保存文件、是否在聊天中展示解耦。
+5. **自检**：每条是否都有「需求描述」；「问题」与「可行性/风险」是否互斥符合 `output-template.md`；是否误引代码路径作论据。
+6. **提交评审记录**：调用 **CLI 命令**，将第 4 步的**完整评审正文**（与若已保存的 `.md` 内容一致）写入指定评论正文。
+
+   - **CLI 命令**：使用 `apm comment update` 将评审正文写入指定评论
+   - **参数**：`apm comment update --id <commentId> --content "<评审正文全文>"`
+   - **多行正文建议**：用这里文档拼接，避免手动转义：
+
+   ```bash
+   apm comment update --id 1 --content "$(cat <<'EOF'
+这里是评审正文（第 4 步成文结果）
+EOF
+)"
+   ```
+
+   实际调用时把 `commentId` 换成首轮对话给出的 `commentId`，把 `--content` 换成第 4 步成文结果。失败时把命令的报错信息贴出；成功时可简要确认评论正文已更新。
+
+## 附加资源
+
+- 输出结构与字段规则：[output-template.md](output-template.md)（本技能独立维护，可与飞书 `example.md` 分叉迭代）

package/templates/skills/requirement-review/output-template.md

@@ -0,0 +1,49 @@
+> 本文件定义 `requirement-review` 技能的**评审输出** Markdown 结构与字段规则；迭代本技能时优先改此文件。
+
+### 评审人
+
+模型名称
+
+### 需求点 1
+
+- **需求描述：**: （一句话概括要做什么，产品视角）
+  - （关键点 1）
+  - （关键点 2）
+
+### 需求点 2
+
+- **需求描述：**: （一句话概括要做什么，产品视角）
+
+- **问题：**
+  - （问题 1：必须澄清“页面/表/口径/范围/汇总规则”等）
+  - （问题 2）
+  - （问题 3）
+
+### 需求点 3
+
+- **需求描述：**: （一句话概括要做什么，产品视角）
+
+- **可行性：**
+  - 成本：低/中/高
+  - （在不引入猜测的前提下，说明成本对应的业务/口径/环节调整）
+
+### 需求点 4
+
+- **需求描述：**: （一句话概括要做什么，产品视角）
+- **可行性：**
+  - 成本：中/高
+  - （在不引入猜测的前提下，说明成本对应的业务/口径/环节调整）
+- **风险点：**
+  - （风险 1：可能影响的不止是展示文案，例如统计口径/汇总逻辑/跨模块联动等）
+  - （风险 2）
+
+### 需求点 5（业务合理性：仅不合理时出现）
+
+- **需求描述：**: （一句话概括要做什么，产品视角）
+- **业务合理性：**
+  - （为何不合理/与用户目标或现有业务冲突/用户方案非当下较优；可写更可取的替代思路或需产品先拍板的点）
+- **可行性：**
+  - 成本：低/中/高
+  - （仍可在指出业务问题的同时评估落地成本；若信息仍不足以落地，则改用「需求点 2」结构：业务合理性 + **问题**，不出现可行性/风险点）
+
+字段顺序与并存：`需求描述` 始终第一；`业务合理性` 仅在不合理时出现在 `需求描述` 之后。其后仍遵循「有问题则只写问题，无问题则写可行性（可加风险点）」。