ai-project-manage-cli 4.0.9 → 4.0.10

package/dist/index.js

@@ -100,6 +100,10 @@ var requestConfig = {
       method: "POST",
       path: "/cli/requirements/comment"
     }),
+    commentStructured: defineEndpoint({
+      method: "POST",
+      path: "/cli/requirements/comment-structured"
+    }),
     refine: defineEndpoint({
       method: "POST",
       path: "/cli/requirements/refine"
@@ -237,15 +241,120 @@ function resolveCwdPath(file) {
   return resolve(process.cwd(), file);
 }
 
+// src/structured-review-yaml.ts
+import { parse } from "yaml";
+var KIND_MAP = {
+  clarify: "CLARIFY",
+  difficulty: "DIFFICULTY",
+  business: "BUSINESS",
+  coordination: "COORDINATION",
+  CLARIFY: "CLARIFY",
+  DIFFICULTY: "DIFFICULTY",
+  BUSINESS: "BUSINESS",
+  COORDINATION: "COORDINATION"
+};
+var STANCE_VALUES = /* @__PURE__ */ new Set(["frontend", "backend", "fullstack"]);
+function asRecord(value) {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value;
+  }
+  throw new Error("YAML \u7ED3\u6784\u65E0\u6548\uFF1A\u9700\u8981\u5BF9\u8C61\u6839\u8282\u70B9");
+}
+function parseAnchor(anchor, index) {
+  const rec = asRecord(anchor);
+  const start = Number(rec.start ?? rec.startLine);
+  const end = Number(rec.end ?? rec.endLine);
+  if (!Number.isInteger(start) || !Number.isInteger(end) || start < 1 || end < start) {
+    throw new Error(`items[${index}].anchor \u884C\u53F7\u65E0\u6548\uFF08\u9700 1 \u2264 start \u2264 end\uFF09`);
+  }
+  return { start, end };
+}
+function parseKind(raw, index) {
+  const key = String(raw ?? "").trim();
+  const kind = KIND_MAP[key] ?? KIND_MAP[key.toLowerCase()];
+  if (!kind) {
+    throw new Error(
+      `items[${index}].kind \u65E0\u6548\uFF0C\u5E94\u4E3A clarify | difficulty | business | coordination`
+    );
+  }
+  return kind;
+}
+function parseStructuredReviewYaml(raw, cliModel) {
+  let doc;
+  try {
+    doc = parse(raw);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new Error(`YAML \u89E3\u6790\u5931\u8D25\uFF1A${msg}`);
+  }
+  const root = asRecord(doc);
+  const reviewer = asRecord(root.reviewer ?? {});
+  const stance = String(reviewer.stance ?? root.stance ?? "").trim();
+  if (!STANCE_VALUES.has(stance)) {
+    throw new Error("reviewer.stance \u5FC5\u987B\u4E3A frontend\u3001backend \u6216 fullstack");
+  }
+  const modelFromYaml = reviewer.model != null ? String(reviewer.model).trim() : "";
+  const model = cliModel?.trim() || modelFromYaml || null;
+  const itemsRaw = root.items;
+  if (!Array.isArray(itemsRaw) || itemsRaw.length === 0) {
+    throw new Error("items \u4E0D\u80FD\u4E3A\u7A7A");
+  }
+  const items = itemsRaw.map((entry, index) => {
+    const item = asRecord(entry);
+    const anchor = parseAnchor(item.anchor ?? item, index);
+    const kind = parseKind(item.kind, index);
+    const body = typeof item.body === "string" ? item.body.trim() : String(item.body ?? "").trim();
+    if (!body) {
+      throw new Error(`items[${index}].body \u4E0D\u80FD\u4E3A\u7A7A`);
+    }
+    if (kind === "COORDINATION" && item.reply != null && String(item.reply).trim()) {
+      throw new Error(`items[${index}] \u8054\u8C03\u4F9D\u8D56\uFF08coordination\uFF09\u4E0D\u5141\u8BB8 reply`);
+    }
+    return {
+      startLine: anchor.start,
+      endLine: anchor.end,
+      kind,
+      body
+    };
+  });
+  return { stance, model, items };
+}
+function inferCommentFormat(filePath, explicit) {
+  if (explicit === "structured" || explicit === "legacy") {
+    return explicit;
+  }
+  const lower = filePath.toLowerCase();
+  if (lower.endsWith(".yaml") || lower.endsWith(".yml")) {
+    return "structured";
+  }
+  return "legacy";
+}
+
 // src/commands/comment.ts
-async function runComment(requirementId, file, model) {
+async function runComment(requirementId, file, options) {
   const cfg = await ensureLoggedConfig();
-  const content = readFileSync2(resolveCwdPath(file), "utf8");
+  const resolvedPath = resolveCwdPath(file);
+  const raw = readFileSync2(resolvedPath, "utf8");
+  const format = inferCommentFormat(resolvedPath, options?.format);
   const api = createApmApiClient(cfg);
+  if (format === "structured") {
+    const parsed = parseStructuredReviewYaml(raw, options?.model);
+    const data2 = await api.cliRequirements.commentStructured({
+      requirementId,
+      stance: parsed.stance,
+      model: parsed.model,
+      items: parsed.items
+    });
+    console.log(JSON.stringify(data2, null, 2));
+    return;
+  }
+  if (!raw.trim()) {
+    throw new Error("\u8BC4\u8BBA\u6B63\u6587\u4E0D\u80FD\u4E3A\u7A7A");
+  }
   const data = await api.cliRequirements.comment({
     requirementId,
-    content,
-    model
+    content: raw,
+    model: options?.model
   });
   console.log(JSON.stringify(data, null, 2));
 }
@@ -2173,9 +2282,20 @@ function buildProgram() {
   ).action(async (requirementId, opts) => {
     await runBranch(requirementId, { message: opts.message });
   });
-  program.command("comment").description("POST /api/cli/requirements/comment\uFF08\u6B63\u6587\u6765\u81EA\u6587\u4EF6\uFF09").argument("<requirementId>", "\u9700\u6C42 ID").requiredOption("--file <path>", "\u8BC4\u8BBA\u6B63\u6587\u6587\u4EF6\u8DEF\u5F84").option("--model <model>", "\u8BC4\u8BBA\u6A21\u578B").action(
+  program.command("comment").description(
+    "\u63D0\u4EA4\u9700\u6C42\u8BC4\u5BA1\uFF1Alegacy \u4E3A\u6574\u7BC7 Markdown\uFF08POST \u2026/comment\uFF09\uFF1Bstructured \u4E3A\u884C\u7EA7 YAML\uFF08POST \u2026/comment-structured\uFF09"
+  ).argument("<requirementId>", "\u9700\u6C42 ID").requiredOption(
+    "--file <path>",
+    "\u8BC4\u8BBA\u6587\u4EF6\u8DEF\u5F84\uFF08.yaml/.yml \u9ED8\u8BA4 structured\uFF09"
+  ).option(
+    "--format <format>",
+    "structured | legacy\uFF08\u9ED8\u8BA4 legacy\uFF1B.yaml/.yml \u672A\u6307\u5B9A\u65F6\u89C6\u4E3A structured\uFF09"
+  ).option("--model <model>", "\u8BC4\u8BBA\u6A21\u578B\uFF08\u8986\u76D6 YAML reviewer.model\uFF09").action(
     async (requirementId, options) => {
-      await runComment(requirementId, options.file, options.model);
+      await runComment(requirementId, options.file, {
+        model: options.model,
+        format: options.format
+      });
     }
   );
   program.command("refine").description("POST /api/cli/requirements/refine\uFF08\u6B63\u6587\u6765\u81EA\u6587\u4EF6\uFF09").argument("<requirementId>", "\u9700\u6C42 ID").action(async (requirementId) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-project-manage-cli",
-  "version": "4.0.9",
+  "version": "4.0.10",
   "description": "命令行工具：后续用于调用平台后端 API 完成运维与自动化操作",
   "type": "module",
   "private": false,

package/template/skills/apm-review/SKILL.md

@@ -9,17 +9,17 @@ description: 结合本仓库上下文对需求做结构化评审，只有当用
 
 ## 评审目标
 
-帮助产品经理**梳理需求边界、发现文档中未写清的口径**，并在实现难度较高时给出提示。**不是**为了凑问题而提问——PRD 已足够清晰且无高难度改造时，仅写锚定即可，不必强行列出待澄清项。
+帮助产品经理**梳理需求边界、发现文档中未写清的口径**，并在实现难度较高时给出提示。**不是**为了凑问题而提问——PRD 已足够清晰且无高难度改造时，可只输出少量锚定条目，不必强行列出待澄清项。
 
 ## 评审立场
 
-每轮评审从 **前端 / 后端 / 全栈** 中择定一种立场，按该视角撰写一篇评审正文，并执行一次 `apm comment`。
+每轮评审从 **前端 / 后端 / 全栈** 中择定一种立场，按该视角输出 **YAML 行级评审**，并执行一次 `apm comment --format=structured`。
 
 ### 如何确定立场
 
 1. **用户明示**：用户说明「前端 / 后端 / 全栈 / 仅 UI / 仅接口」等，以用户为准。
-2. **用户未说明**：阅读仓库中与该需求相关的现有代码，推断评审者更贴近哪一端；仍无法判断时，**默认前端**，并在 `### 评审人` 中注明「未指定立场，按代码推断为 xxx」。
-3. **全栈**：在同一篇评审中同时覆盖 UI 与流程/数据关注点；同一业务点合并为一条待澄清项（见下文去重规则）。
+2. **用户未说明**：阅读仓库中与该需求相关的现有代码，推断评审者更贴近哪一端；仍无法判断时，**默认前端**，并在 `reviewer.stance` 使用 `frontend`。
+3. **全栈**：在同一轮评审中同时覆盖 UI 与流程/数据关注点；同一业务点若需澄清，合并为**一条** `clarify`（不要拆成两句重复问题）。
 
 ### 各端关注点（互斥优先，减少并行评审重复）
 
@@ -31,37 +31,34 @@ description: 结合本仓库上下文对需求做结构化评审，只有当用
 
 **去重规则**（按立场选用）：
 
-- **前端立场**：只写界面与交互侧待澄清，不写落库/API 契约类问题。
+- **前端立场**：只写界面与交互侧待澄清，不写落库/API 契约类问题（联调诉求用 `kind: coordination`）。
 - **后端立场**：只写流程、规则与数据侧待澄清，不写控件选型、Tab 布局等纯 UI 问题。
-- **全栈立场**：同一业务点若 UI 与规则都涉及，合并为**一条**待澄清（优先产品能直接回答的业务表述），**不要**拆成两句意思重复的问题。
+- **全栈立场**：同一业务点合并为一条 `clarify`，**不要**拆成两句意思重复的问题。
 
 ## 表述规范（产品经理可读）
 
-1. **产品语言优先**：用「医德考评弹窗」「行风办审批页」「列表页分类筛选」等说法；**禁止**用文件路径、组件名、函数名作为论据或问题主体（`prd.md` 行号锚定除外）。
+1. **产品语言优先**：用「医德考评弹窗」「行风办审批页」等说法；**禁止**用文件路径、组件名、函数名作为论据主体（行号锚定除外）。
 2. **后端可略宽**：必要时可写**表名 / 主表字段名**帮助产品理解数据口径，但仍避免贴大段代码或接口路径。
-3. **锚定 PRD**：每条评审用 **`prd.md` 行号**指回原文（如 `prd.md` L44–L55），**不**另写半句概括或复述需求内容。
-4. **问题 = 文档缺口**：只写 PRD **未写清**且**影响本端理解边界**的点（例如：只说了改字段名，没说哪些页面/弹窗要改；只说了新增 Tab，没说各审批节点能否编辑）。已写清楚的规则不要重复质疑。
+3. **锚定 PRD**：每条 `items[]` 必须写 **`anchor: { start, end }`**，与 Read 读到的 `prd.md` 行号一致；**不**在 `body` 里复述该段需求原文。
+4. **问题 = 文档缺口**：只写 PRD **未写清**且**影响本端理解边界**的点。已写清楚的规则不要重复质疑。
 
-## 不在本轮的问题项
+## 不在「待澄清」里写的内容
 
-以下属于**技术评审 / 联调**阶段，**不得**写入「待澄清」：
+以下不得使用 `kind: clarify`，若需记录则用 **`kind: coordination`**（且必须有行号锚定）：
 
 - 接口字段名、请求体结构、子表编码
 - 前后端谁传哪个参数、现有 edit 接口是否够用
 - 与现网代码实现对齐的改造方案
 
-若**前端**评审时确知实现依赖某些后端信息，可在全文末尾单独增加 **`## 联调依赖项`**（见 `output-template.md`），**简短**记录接口/字段等诉求；**不用产品回复，仅作记录，待技术评审阶段处理**。
+`coordination` **不用产品回复**，仅作记录，待技术评审阶段处理。若同一行区间既要澄清又要联调，**拆成两条** `items`。
 
 ## 评审原则
 
-1. **产品视角优先**：用户侧影响、业务闭环、边界与风险；避免术语堆砌。
-2. **与仓库对齐（能力边界）**：阅读 `AGENTS.md`、`.apm/product-capability-inventory` 及与需求相关的代码，判断需求是否超出现有能力。**禁止**用代码证明 PRD 对错；**禁止**根据代码**猜测** PRD 未写清的口径——口径不清归入「待澄清」。
-3. **业务合理性（按需）**：仅当方案与业务目标明显冲突或明显非较优解时，写 `- **业务合理性：**`；合理则不写。
-4. **待澄清与实现难度（按需）**：
-   - 存在**阻碍本端理解或验收**的文档缺口 → 写 `- **待澄清：**`。
-   - 实现难度**高**时额外写 `- **实现难度高：**`（用产品语言简述原因）；一般难度**不写**该字段。
-   - **高难度**指：对现有代码改造面大（涉及文件/模块较多），或业务逻辑变化影响较大。
-5. **澄清优先但不泛问**：不阻塞理解则不提问；不问可从 PRD 或常识推断的琐碎点。
+1. **产品视角优先**：用户侧影响、业务闭环、边界与风险。
+2. **与仓库对齐（能力边界）**：阅读 `AGENTS.md`、`.apm/product-capability-inventory` 及与需求相关的代码，判断改造面。**禁止**用代码证明 PRD 对错；口径不清归入 `clarify`。
+3. **`kind: business`**：仅当方案与业务目标明显冲突或明显非较优解时使用。
+4. **`kind: difficulty`**：仅当改造面大或业务逻辑影响大时使用。
+5. **澄清优先但不泛问**：不阻塞理解则不提问。
 
 ## 执行步骤
 
@@ -69,35 +66,36 @@ description: 结合本仓库上下文对需求做结构化评审，只有当用
 
 1. 使用 **Read** 读取 `.apm/workitems/<需求ID>/prd.md`。
 2. 当 PRD 涉及到图片链接时，自动下载对应的图片，存放在 `.apm/workitems/<需求ID>/images/<对应图片名称>.png`，并理解图片内容。
-3. 若 Read **失败**（文件不存在或无法读取）：本步骤记为失败，**终止**，不执行后续步骤。
+3. 若 Read **失败**：本步骤记为失败，**终止**，不执行后续步骤。
 
 ### 步骤 2：读代码
 
-阅读仓库源码以及 `.apm/product-capability-inventory` 中与需求相关的条目，用于**理解现网能力与边界、判断改造面**，不展开无关模块。**读代码是为了校准评审立场和实现难度，不是为了把代码细节写进评审正文。**
+阅读仓库源码以及 `.apm/product-capability-inventory` 中与需求相关的条目，用于**理解现网能力与边界、判断改造面**。
 
 ### 步骤 3：评审与提交
 
-1. **锁定立场**（见上文「评审立场」），在正文顶格写 `### 评审人` + 模型名 + 立场（如「Auto（前端）」）。
-2. **拆条**：按 PRD 章节拆条（标题序号与 PRD 一致即可）；每条写 **`prd.md` 行号锚定**，按需追加待澄清、实现难度高、业务合理性等字段，**不**复述该段需求原文。
-3. **成文**：按 **[output-template.md](./output-template.md)** 拼 Markdown；**不含**「隐性知识沉淀」段落。
-4. 使用 **Write** 写入临时文件（建议绝对路径 `/tmp/apm-review-<需求ID>.md`）。
+1. **锁定立场**，填入 YAML `reviewer.stance`（`frontend` / `backend` / `fullstack`）。
+2. **拆条**：每条对应 `prd.md` 连续行号；按需设置 `kind`（`clarify` / `difficulty` / `business` / `coordination`）与 `body`。
+3. **成文**：按 **[output-template.md](./output-template.md)** 写 YAML。
+4. 使用 **Write** 写入临时文件（建议 `/tmp/apm-review-<需求ID>.yaml`）。
 5. **自检**：
-   - 全文是否始终符合已锁定的评审立场；
-   - 待澄清项是否均为产品能回答的业务/交互/规则问题，而非接口契约；
-   - 是否误用代码路径、组件名作主要表述；
-   - 一般难度需求是否误写了「实现难度高」；
-   - 是否存在语义重复的待澄清项（应合并或删去一条）。
-6. 在项目根目录执行一次：`apm comment <需求ID> --file=<临时文件绝对路径> --model=<评论使用的模型名称>`。
+   - 每条均有 `anchor`，且无全篇评审；
+   - `stance` 与立场一致；
+   - `clarify` 均为产品可回答的业务问题；
+   - `coordination` 无 `reply` 字段；
+   - 无重复语义的条目。
+6. 在项目根目录执行：
+
+   `apm comment <需求ID> --file=<临时文件绝对路径> --format=structured --model=<模型名>`
+
 7. 命令结束后 **删除临时文件**（失败时若需排错可保留，默认仍删除）。
 
 ### 步骤 4：回复用户
 
-对用户可见回复 **仅限一张 Markdown 表格**，汇总各步**结果**（成功/失败、摘要）。**不得**在表格外输出任何其他内容（完整评审正文已通过 `apm comment` 提交）。
-
-建议表头：
+对用户可见回复 **仅限一张 Markdown 表格**，汇总各步**结果**。**不得**在表格外输出其他内容。
 
-| 步骤              | 结果        | 说明                                                                                           |
-| ----------------- | ----------- | ---------------------------------------------------------------------------------------------- |
-| 1. 读取 prd.md    | 成功 / 失败 | 实际路径；失败时写原因                                                                         |
-| 2. 评审与 comment | 成功 / 失败 | 临时文件（已删可写「已清理」）；`apm comment` 情况；**注明本轮评审立场**（前端 / 后端 / 全栈） |
-| 3. 清理临时文件   | 成功 / 失败 | —                                                                                              |
+| 步骤              | 结果        | 说明                                                                            |
+| ----------------- | ----------- | ------------------------------------------------------------------------------- |
+| 1. 读取 prd.md    | 成功 / 失败 | 实际路径；失败时写原因                                                          |
+| 2. 评审与 comment | 成功 / 失败 | 临时文件；`apm comment` 情况；**注明 stance**（frontend / backend / fullstack） |
+| 3. 清理临时文件   | 成功 / 失败 | —                                                                               |

package/template/skills/apm-review/output-template.md

@@ -1,75 +1,64 @@
-# 评审输出模板
-
-顶格写评审人，随后按 PRD 章节逐条输出。全文使用**产品经理可读**的表述；锚定 PRD 时**只写行号**，不复述需求。
-
-```markdown
-### 评审人
-
-{模型名}（{前端 / 后端 / 全栈}）
-
-### 需求点 1
-
-- **锚定：** `prd.md` L44–L55
-
-- **待澄清：**
-  - {文档未写清、影响本端理解边界的点；无则整段省略}
-  - {示例（前端）：「类型」隐藏后，统计分析页的「分类」筛选是否一并去掉，导出是否统一走临床模板}
-  - {示例（后端）：新建单据「默认临床」对应字典编码/文案未写明，历史非临床记录在列表是否仍展示原类型}
-
-### 需求点 2
-
-- **锚定：** `prd.md` L59–L67
-
-{PRD 已写清且改造面不大 → 仅锚定，不写其他字段}
-
-### 需求点 3
-
-- **锚定：** `prd.md` L69–L81
-
-- **待澄清：**
-  - {仅列本端视角的缺口}
-
-### 需求点 4（业务合理性：仅不合理时出现）
-
-- **锚定：** `prd.md` L83–L106
-
-- **业务合理性：**
-
-  - {为何与业务目标冲突或方案非较优；可给替代思路}
-
-- **待澄清：**
-  - {若仍有文档缺口}
-
-### 需求点 5
-
-- **锚定：** `prd.md` L108–L132
-
-- **实现难度高：**
-  - {用产品语言说明：改造涉及哪些页面/流程/规则，为何面大；示例：加/减分明细需按审批层级分块改造，涉及弹窗表单、子表编辑与汇总多处联动，业务规则变化面大}
-
----
-
-## 联调依赖项
-
-{**仅当前端评审**且存在联调前置信息时出现；**可选**，无则省略整节}
-
-> 不用产品回复，仅记录，待技术评审阶段处理。
+# 评审输出模板（YAML · structured）
+
+使用 **YAML** 文件提交行级评审；每条必须锚定 `prd.md` 行号。全文使用**产品经理可读**的表述；**不**在 `body` 里复述需求原文。
+
+## 文件示例
+
+```yaml
+reviewer:
+  model: Auto
+  stance: frontend # frontend | backend | fullstack
+
+items:
+  - anchor: { start: 44, end: 55 }
+    kind: clarify
+    body: |
+      - 「类型」隐藏后，统计分析页的「分类」筛选是否一并去掉，导出是否统一走临床模板
+
+  - anchor: { start: 59, end: 67 }
+    kind: clarify
+    body: |
+      - （PRD 已写清且无缺口时可省略该条，不要写「仅锚定」空条目）
+
+  - anchor: { start: 83, end: 106 }
+    kind: business
+    body: |
+      - 方案与业务目标冲突的原因；可给替代思路
+
+  - anchor: { start: 108, end: 132 }
+    kind: difficulty
+    body: |
+      - 用产品语言说明改造面：涉及哪些页面/流程/规则，为何面大
+
+  - anchor: { start: 44, end: 55 }
+    kind: coordination
+    body: |
+      - 需与后端对齐的接口/字段诉求（不用产品回复）
+```
 
-{简短条目，记录后续需与后端对齐的接口/字段/能力诉求}
+## kind 与技能表述
 
-- 一票否决：需明确存储位置（主表字段或独立子表）及回显字段，以便行风办页勾选与查看页展示。
-- 加/减分明细分级：需明确各级分值对应落库字段，以便分块编辑与汇总。
-```
+| `kind`（YAML 小写） | 含义       | 说明                         |
+| ------------------- | ---------- | ---------------------------- |
+| `clarify`           | 待澄清     | 文档未写清、影响本端理解边界 |
+| `difficulty`        | 实现难度高 | 仅改造面大或业务逻辑影响大时 |
+| `business`          | 业务合理性 | 仅方案明显不合理时           |
+| `coordination`      | 联调依赖   | **禁止** `reply`；待技术评审 |
 
 ## 字段规则
 
+| 字段              | 规则                                                             |
+| ----------------- | ---------------------------------------------------------------- |
+| `reviewer.stance` | 必填：`frontend` / `backend` / `fullstack`                       |
+| `reviewer.model`  | 建议填写；可被 CLI `--model` 覆盖                                |
+| `anchor`          | 必填 `{ start, end }`，1-based 闭区间，与 Read `prd.md` 行号一致 |
+| `body`            | 必填；产品语言；**禁止**全篇评审（必须有行号）                   |
+| 同区间多类型      | 拆成多条 `items`（例如同时 `clarify` 与 `coordination` 各一条）  |
 
-| 字段        | 规则                                                             |
-| --------- | -------------------------------------------------------------- |
-| **锚定**    | 每条必有；写 `prd.md` L{起}–L{止}，与 Read 工具读到的行号一致；**不**概括、**不**复述该段需求 |
-| **待澄清**   | 按需；无缺口则**不写**（不要写「无」）                                          |
-| **实现难度高** | 按需；**仅**改造面大或业务逻辑影响大时写；一般难度**不写**                              |
-| **业务合理性** | 按需；仅方案明显不合理时出现                                                 |
-| **联调依赖项** | 全文最多一节；**不算待澄清**；不用产品回复，仅记录，待技术评审阶段处理                          |
+## 提交命令
 
+```bash
+apm comment <需求ID> --file=/tmp/apm-review-<需求ID>.yaml --format=structured --model=<模型名>
+```
 
+`.yaml` / `.yml` 扩展名在未指定 `--format` 时默认按 structured 解析。