ai-project-manage-cli 1.0.3 → 1.0.5

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」结构：业务合理性 + **问题**，不出现可行性/风险点）
+
+字段顺序与并存：`需求描述` 始终第一；`业务合理性` 仅在不合理时出现在 `需求描述` 之后。其后仍遵循「有问题则只写问题，无问题则写可行性（可加风险点）」。