ai-project-manage-cli 1.0.28 → 2.0.1

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

@@ -1,6 +1,6 @@
 ---
 name: requirement-review
-description: 结合本仓库上下文对需求做结构化评审，按 output-template.md 形成完整 Markdown 评审正文，并通过 CLI 写入评论正文（短正文可直接 --content；过长时用临时文件 --content-file，成功后删除）。输入为需求正文及 `commentId`（首轮与正文一起给出）。仅在用户明确声明使用本技能时应用。
+description: 结合本仓库上下文对需求做结构化评审，按 output-template.md 形成完整 Markdown 评审正文；**始终**将正文落盘到 `.apm/workitems/<name>/comment-<commentId>.md` 并通过 CLI `--content-file` 写入评论（**不删除**该文件）。输入为需求正文、`commentId`、workitem 目录名 `<name>`（首轮一并给出或可从 `.apm/workitems/` 唯一定位）。仅在用户明确声明使用本技能时应用。
 ---
 
 # 需求评审（仓库内）
@@ -10,18 +10,19 @@ description: 结合本仓库上下文对需求做结构化评审，按 output-te
 - **必须**：用户**明确声明**使用本技能（例如在对话中 @ 本 SKILL）
 - 未作上述声明时，**不**因「帮我看看需求」「评审一下」等表述自动套用本技能的工作方式与输出模板
 
-满足触发后，用户须在**首轮对话**中一并给出：**需求正文**、`commentId`（评论 id）。不要求路径或附件。
+满足触发后，用户须在**首轮对话**中一并给出：**需求正文**、`commentId`（评论 id）、**workitem 目录名 `<name>`**（与 `.apm/workitems/<name>/prd.md` 等同级产物所在目录一致，通常为 kebab-case）。若未给出 `<name>` 但仓库内**仅有一个**合理关联的 workitem 目录，可据 `.apm/workitems/` 推断；否则须先索要。不要求其他附件。
 
 ## 输入
 
 - **需求正文**：用户粘贴的待评审内容
 - **`commentId`**：评论记录 id（整数，与正文一起在对话中给出）
+- **`<name>`**：`.apm/workitems/<name>/` 下的目录名，用于落盘评论存档（见下文）；与首轮一并给出或由仓库唯一定位
 
-若首轮未给出 `commentId`，须先向用户索要后再执行第 6 步。
+若首轮未给出 `commentId` 或无法确定 `<name>`，须先向用户索要（或澄清）后再执行第 6 步。
 
 ## 输出
 
-- **评审正文**：须先按模板在**逻辑上**成文（完整 Markdown 字符串），不得仅给零散要点。可在回复中展示、可选保存为 `.md`，**均非必须**；第 6 步将该字符串写入评论：**短正文**可直接 `--content` 或 heredoc；**过长**（易触 shell 参数长度/转义问题）时写入**临时文件**并用 `--content-file`，成功后**删除该临时文件**（不落盘到仓库）。
+- **评审正文**：须先按模板在**逻辑上**成文（完整 Markdown 字符串），不得仅给零散要点。可在回复中展示。**落盘（强制）**：将第 4 步全文以 UTF-8 写入 **`.apm/workitems/<name>/comment-<commentId>.md`**（文件名中的 id 与输入 `commentId` 一致，例如 `comment-42.md`）；**始终保留该文件**，不因 CLI 成功而删除，也不使用临时目录替代。第 6 步**统一**用该路径作为 `--content-file` 更新评论（避免 shell 参数长度与转义问题）。
 - 将需求拆成若干条「需求点」（若本就一条则一条），对每条按 [output-template.md](output-template.md) 的**字段规则与并存关系**输出结论。
 - 语言面向产品/研发可读：少堆砌实现细节，**不**用具体文件路径、函数名当「证据」；仓库仅用于理解**能力边界、术语与业务上下文**。
 
@@ -42,29 +43,19 @@ description: 结合本仓库上下文对需求做结构化评审，按 output-te
 1. **锁定正文**：以用户提供的全部需求正文为准；若明显缺段或指代不清，在「问题」中列出待澄清点。
 2. **按需读仓库**：快速扫 `AGENTS.md`、`apps/fe/AGENTS.md`、`servers/be/AGENTS.md` 及 `.apm/product-capability-inventory` 中与需求相关的条目；不展开无关模块代码。
 3. **拆条**：多条诉求时拆成 `### 需求点 1..N`，每条独立走完「业务合理性（可选）→ 问题 或 可行性（+风险）」逻辑。
-4. **成文**：按 `output-template.md` 拼出完整 Markdown 字符串（顶格可加 `### 评审人` + 当前模型名）；该字符串即评审正文，可与是否保存文件、是否在聊天中展示解耦。
+4. **成文**：按 `output-template.md` 拼出完整 Markdown 字符串（顶格可加 `### 评审人` + 当前模型名）；**随即**将全文写入 **`.apm/workitems/<name>/comment-<commentId>.md`**（目录不存在则创建；同一 id 重跑则**覆盖**该文件，仍不删除）。
 5. **自检**：每条是否都有「需求描述」；「问题」与「可行性/风险」是否互斥符合 `output-template.md`；是否误引代码路径作论据。
-6. **提交评审记录**：调用 **CLI 命令**，将第 4 步的**完整评审正文**（与若已保存的 `.md` 内容一致）写入指定评论正文。
+6. **提交评审记录**：调用 **CLI 命令**，读取第 4 步已落盘的 **`.apm/workitems/<name>/comment-<commentId>.md`**，将内容与评论正文同步。
 
-   - **CLI 命令**：使用 `apm comment update` 将评审正文写入指定评论
-   - **短正文**（不易超长）：`apm comment update --id <commentId> --content "<评审正文全文>"`，或多行用 heredoc 避免转义：
+   - **CLI 命令**：`apm comment update --id <commentId> --content-file .apm/workitems/<name>/comment-<commentId>.md`
+   - **禁止**：成功后 `rm` 该文件或使用仅存在于系统临时目录、意图事后删除的副本；评论存档以 workitem 目录下该文件为准。
 
    ```bash
-   apm comment update --id 1 --content "$(cat <<'EOF'
-这里是评审正文（第 4 步成文结果）
-EOF
-)"
+   apm comment update --id 42 --content-file .apm/workitems/my-feature/comment-42.md
    ```
 
-   - **过长正文**：勿强行塞进一条 shell 参数；将第 4 步全文写入**临时文件**（如 `mktemp` 或系统临时目录下的唯一文件名，UTF-8），再：
-
-   ```bash
-   apm comment update --id <commentId> --content-file /path/to/tmp-review.md
-   rm -f /path/to/tmp-review.md
-   ```
-
-   `comment update` **成功后**再执行 `rm`；失败时保留文件便于排查。实际调用时把 `commentId` 换成首轮对话给出的值。失败时把命令的报错信息贴出；成功时可简要确认评论正文已更新。
+   实际调用时替换为你的 `<commentId>`、`<name>`。失败时把命令报错贴出；成功时可简要确认评论已更新且 **`comment-<commentId>.md` 仍保留在仓库中**。
 
 ## 附加资源
 
-- 输出结构与字段规则：[output-template.md](output-template.md)（本技能独立维护，可与飞书 `example.md` 分叉迭代）
+- 输出结构与字段规则：[output-template.md](output-template.md)