ai-project-manage-cli 4.0.8 → 4.0.10

package/README.md

@@ -4,7 +4,11 @@
 
 ## 安装
 
-`npm install ai-project-manage-cli@latest`
+`npm install -g ai-project-manage-cli@latest`
+
+## 更新到最新版
+
+`apm update`（等价于 `npm install -g ai-project-manage-cli@latest`）
 
 ## 登录
 
@@ -16,4 +20,4 @@
 
 ## 连接服务器
 
-`apm connect`
+`apm connect`

package/dist/index.js

@@ -1,9 +1,6 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync10 } from "fs";
-import { dirname as dirname2, join as join10 } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
 import { Command } from "commander";
 
 // src/config.ts
@@ -103,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"
@@ -240,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));
 }
@@ -1006,6 +1112,84 @@ async function runRefine(requirementId) {
   console.log(JSON.stringify(data, null, 2));
 }
 
+// src/commands/update.ts
+import { spawnSync } from "child_process";
+
+// src/version.ts
+import { readFileSync as readFileSync6 } from "fs";
+import { dirname as dirname2, join as join9 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+var CLI_PACKAGE_NAME = "ai-project-manage-cli";
+function readCliVersion() {
+  try {
+    const dir = dirname2(fileURLToPath2(import.meta.url));
+    const pkgPath = join9(dir, "..", "package.json");
+    const pkg = JSON.parse(readFileSync6(pkgPath, "utf8"));
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+// src/commands/update.ts
+function registryBaseUrl() {
+  const fromEnv = process.env.npm_config_registry?.trim() || process.env.NPM_CONFIG_REGISTRY?.trim();
+  return (fromEnv || "https://registry.npmjs.org").replace(/\/+$/, "");
+}
+async function fetchLatestPublishedVersion() {
+  const url = `${registryBaseUrl()}/${CLI_PACKAGE_NAME}/latest`;
+  try {
+    const res = await fetch(url);
+    if (!res.ok) return null;
+    const data = await res.json();
+    return data.version?.trim() || null;
+  } catch {
+    return null;
+  }
+}
+function npmAvailable() {
+  const r = spawnSync("npm", ["--version"], { encoding: "utf8" });
+  return !r.error && r.status === 0;
+}
+async function runUpdate() {
+  const current = readCliVersion();
+  const latest = await fetchLatestPublishedVersion();
+  if (latest && current === latest) {
+    console.log(`[apm] \u5DF2\u662F\u6700\u65B0\u7248\u672C ${current}`);
+    return;
+  }
+  if (!npmAvailable()) {
+    console.error(
+      `[apm] \u672A\u627E\u5230 npm\u3002\u8BF7\u5B89\u88C5 Node.js \u540E\u6267\u884C\uFF1Anpm install -g ${CLI_PACKAGE_NAME}@latest`
+    );
+    process.exit(1);
+  }
+  const targetLabel = latest ?? "latest";
+  console.error(
+    `[apm] \u5F53\u524D\u7248\u672C ${current}\uFF0C\u6B63\u5728\u5B89\u88C5 ${CLI_PACKAGE_NAME}@${targetLabel} \u2026`
+  );
+  const install = spawnSync(
+    "npm",
+    ["install", "-g", `${CLI_PACKAGE_NAME}@latest`],
+    { stdio: "inherit", shell: process.platform === "win32" }
+  );
+  if (install.error) {
+    console.error("[apm] \u66F4\u65B0\u5931\u8D25:", install.error.message);
+    process.exit(1);
+  }
+  if (install.status !== 0) {
+    process.exit(install.status ?? 1);
+  }
+  const after = readCliVersion();
+  if (latest && after === latest) {
+    console.log(`[apm] \u5DF2\u66F4\u65B0\u5230 ${after}`);
+  } else {
+    console.log(
+      `[apm] \u66F4\u65B0\u5B8C\u6210\u3002\u82E5\u7248\u672C\u53F7\u672A\u53D8\u5316\uFF0C\u8BF7\u5728\u65B0\u7EC8\u7AEF\u6267\u884C apm -V \u786E\u8BA4\uFF08\u5168\u5C40\u5B89\u88C5\u8DEF\u5F84\u53EF\u80FD\u672A\u5237\u65B0\uFF09`
+    );
+  }
+}
+
 // src/commands/update-dev-status.ts
 async function runUpdateDevStatus(requirementId, status) {
   const cfg = await ensureLoggedConfig();
@@ -1032,7 +1216,7 @@ async function runUpdateStatus(requirementId, status) {
 import path5 from "node:path";
 
 // src/commands/deploy/internal/apm-config.ts
-import { existsSync as existsSync4, readFileSync as readFileSync6 } from "node:fs";
+import { existsSync as existsSync4, readFileSync as readFileSync7 } from "node:fs";
 import { resolve as resolve4 } from "node:path";
 function loadApmConfig(options) {
   const p = resolve4(
@@ -1044,7 +1228,7 @@ function loadApmConfig(options) {
     process.exit(1);
   }
   try {
-    const raw = readFileSync6(p, "utf8");
+    const raw = readFileSync7(p, "utf8");
     return JSON.parse(raw);
   } catch (e) {
     console.error(`\u65E0\u6CD5\u89E3\u6790 apm.config.json\uFF1A${p}`, e);
@@ -1143,7 +1327,7 @@ import path4 from "node:path";
 import Docker from "dockerode";
 
 // src/commands/deploy/internal/backend-deploy/dockerode-client/connection-options.ts
-import { existsSync as existsSync5, readFileSync as readFileSync7 } from "node:fs";
+import { existsSync as existsSync5, readFileSync as readFileSync8 } from "node:fs";
 import path from "node:path";
 function asOptionalTlsBuffer(value) {
   if (typeof value !== "string") {
@@ -1156,7 +1340,7 @@ function asOptionalTlsBuffer(value) {
     return void 0;
   }
   if (existsSync5(normalized)) {
-    return readFileSync7(normalized);
+    return readFileSync8(normalized);
   }
   const looksLikePath = /[\\/]/.test(normalized) || normalized.endsWith(".pem");
   if (looksLikePath) {
@@ -1366,7 +1550,7 @@ var DockerodeClient = class {
 var createDockerodeClient = (config) => new DockerodeClient(config);
 
 // src/commands/deploy/internal/backend-deploy/dockerode-client/env.ts
-import { existsSync as existsSync6, readFileSync as readFileSync8, statSync as statSync3 } from "node:fs";
+import { existsSync as existsSync6, readFileSync as readFileSync9, statSync as statSync3 } from "node:fs";
 import path2 from "node:path";
 function stripSurroundingQuotes(value) {
   const t = value.trim();
@@ -1386,7 +1570,7 @@ function loadEnvFromFile(envFilePath) {
   if (!existsSync6(targetPath) || !statSync3(targetPath).isFile()) {
     return {};
   }
-  const raw = readFileSync8(targetPath, "utf-8");
+  const raw = readFileSync9(targetPath, "utf-8");
   const result = {};
   for (const line of raw.split(/\r?\n/)) {
     const normalized = line.trim();
@@ -1691,16 +1875,16 @@ import { copyFile, readdir as readdir2, stat } from "node:fs/promises";
 import path7 from "node:path";
 
 // src/commands/deploy/internal/load-apm-dotenv.ts
-import { existsSync as existsSync8, readFileSync as readFileSync9 } from "node:fs";
-import { join as join9 } from "node:path";
+import { existsSync as existsSync8, readFileSync as readFileSync10 } from "node:fs";
+import { join as join10 } from "node:path";
 function loadApmDotEnvIfPresent() {
-  const p = join9(WORKSPACE_APM_DIR, ".env");
+  const p = join10(WORKSPACE_APM_DIR, ".env");
   if (!existsSync8(p)) {
     return;
   }
   let text;
   try {
-    text = readFileSync9(p, "utf8");
+    text = readFileSync10(p, "utf8");
   } catch {
     return;
   }
@@ -2056,16 +2240,6 @@ function registerDeployCommands(program) {
 }
 
 // src/index.ts
-function readCliVersion() {
-  try {
-    const dir = dirname2(fileURLToPath2(import.meta.url));
-    const pkgPath = join10(dir, "..", "package.json");
-    const pkg = JSON.parse(readFileSync10(pkgPath, "utf8"));
-    return pkg.version ?? "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
-}
 function buildProgram() {
   const program = new Command();
   program.name("apm").description(
@@ -2085,6 +2259,11 @@ function buildProgram() {
   program.command("init").description("\u5728\u5F53\u524D\u5DE5\u4F5C\u76EE\u5F55\u521D\u59CB\u5316 .apm \u6A21\u677F\uFF08\u82E5 .apm \u5DF2\u5B58\u5728\u4E14\u975E\u7A7A\u5219\u62A5\u9519\uFF09").option("--name <name>", "\u5DE5\u4F5C\u76EE\u5F55\u540D\u79F0").action(async (opts) => {
     await runInit(opts.name);
   });
+  program.command("update").description(
+    `\u901A\u8FC7 npm \u5168\u5C40\u5B89\u88C5 ${CLI_PACKAGE_NAME}@latest\uFF0C\u5C06 apm \u66F4\u65B0\u5230 registry \u6700\u65B0\u7248`
+  ).action(async () => {
+    await runUpdate();
+  });
   program.command("pull").description(
     "GET /api/cli/requirements/pull\uFF0C\u540C\u6B65\u6570\u636E\u4E0E\u9644\u4EF6\u5230 .apm/workitems/<\u9700\u6C42ID>"
   ).argument("<requirementId>", "\u9700\u6C42 ID").action(async (requirementId) => {
@@ -2103,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.8",
+  "version": "4.0.10",
   "description": "命令行工具：后续用于调用平台后端 API 完成运维与自动化操作",
   "type": "module",
   "private": false,

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

@@ -1,75 +1,68 @@
 ---
 name: apm-refine
-description: 根据需求 ID 读取工作项 prd.md 与 reviews.xml，按「修订稿」标准结构（修订说明、背景与目标、范围、需求点、非功能、待确认/问题与局限等）润色并回写，再执行 apm refine 同步平台；当用户在对话中 @ 本技能或提出需求润色时使用。
+description: 根据需求 ID 读取 prd.md 与 reviews.xml，润色为简短、可验收的业务需求文档并回写，再执行 apm refine 同步平台；当用户 @ 本技能或提出需求润色时使用。
 ---
 
 # APM 需求润色
 
 用户仅提供 **需求 ID**（workitem id）。**缺 ID 时索要，不猜测。**
 
-## 合并原则
-
-1. **正文依据 = 需求原文 + 补充信息**：只把用户在补充信息中**明确**要体现的内容（补充、修改、删除、拍板口径）合并进修订稿；用户没说到的，**保持原文或不写**，**不自作主张**补需求、不替用户「落实」评审建议。
-2. **未回应的评审**：不列入「待确认」、不改成待办、不推断「仍有问题」；视为用户未要求在本次修订中处理（可能无此问题、暂不改、或评审误解）。
-3. **评审的定位**：仅辅助理解补充信息在回应什么；补充信息与评审不一致时，**以补充信息为准**。
-4. **消除重复**：同一议题在原文与补充信息中多处出现时，合并为**一处**表述。
-5. **可追溯（轻量）**：可选「修订说明」概括相对原文的变化，且**只写补充信息实际带来的变化**，不罗列未采纳的评审。
-6. **与仓库一致**：对照 `AGENTS.md`、`.apm/product-capability-inventory` 等，避免修订稿与用户已确认表述冲突；**禁止**用代码路径当需求论据。
-7. **图片引用保持原样**：若原文含图片（如 `<img ...>`），在修订稿中直接保留对应 `img` 标签原文；不要改写成“图片见原始文档”等占位说明。
-
-## 强制执行顺序（四步）
-
-### 步骤 1：读取 `prd.md` 与 `reviews.xml`
+## 产出品质
 
-1. 使用 **Read** 读取 **`.apm/workitems/<需求ID>/prd.md`**。
-2. 当PRD涉及到图片链接时，自动下载对应的图片，存放在 `.apm/workitems/<需求ID>/images/<对应图片名称>.png`，并理解图片内容
-3. 使用 **Read** 读取 **`.apm/workitems/<需求ID>/reviews.xml`**。
+润色后的 `prd.md` 应做到：
 
-**失败与缺省：**
+- **可验收**：产品、测试、开发不读代码也能写用例；每条规则能对应一个测试点
+- **简短**：合并后删繁就简，两三分钟可通读
+- **业务化**：写界面、按钮、选项、场景与系统表现；材料中的技术名译为用户能懂的说法（原文要求保留的名称除外）
+- **分场景**：新增 / 编辑 / 审核等分开写；**暂存**与**提交**的行为、校验时机分别写清
+- **边界清楚**：范围写明包含与不包含；需求点内用 **「不考虑」** 标明明确排除项
+- **术语统一**：同一字段、按钮全文同一叫法；改名时写明界面、提示、校验文案一并调整
+- **结构平**：每个需求点一层 bullet（2 ～ 5 条），关键用语 **加粗**
 
-- 若 **`prd.md` 无法读取**（不存在、无权限等）：**终止**后续步骤，在最终对用户的说明中记录失败原因。
-- 若 **`reviews.xml` 无法读取**（不存在等）：**不终止**；视为**无评审意见**，仅基于当前 `prd.md` 做标准化与润色，不杜撰评审内容。
+正文骨架、需求点写法、示例与落盘自检见 **[apm-refine-template.md](./apm-refine-template.md)**。
 
-### 步骤 2：润色为「标准需求文档」
-
-在**不向用户追问补充信息**的前提下完成（**禁止**为润色向用户发起对话式提问；材料中已写的 `reply` 与评审意见视为**补充信息**可吸收。有歧义、缺信息、与 reviews 冲突等，**对材料未载明之事项**一律记入 **「问题与局限」** 或按条件写入 **「待确认」**，见 **[apm-refine-template.md](./apm-refine-template.md)** 与小节 3）。
+## 合并原则
 
-1. **综合 `reviews.xml`（若可读）**  
-   解析其中各条 `review` 的 `content`（对 prd 的改进点/问题）与 `reply`（已给出的处理意见）。将**可落实的**回复与结论吸收进正文；**未覆盖或仍模糊**的，写入 **「问题与局限」**；若原文或 `reply` 中**已标明**未决、「待定」等，则同时或单独写入 **「待确认」**。**不**停步询问用户。
+1. **正文 = 需求原文 + 已拍板补充**：合并 `prd.md` 与 `reviews.xml` 里 `reply` 的明确口径；未说到的保持原文或不写，不自行扩需求。
+2. **评审辅助理解 `reply`**；与补充冲突时以补充为准；未回应的评审本次不处理。
+3. **同一议题只写一处**；合并后篇幅短于或接近原文。
+4. **图片**：原文图片语法原样保留；理解图片后把规则写入对应需求点的文字描述。
 
-2. **落盘结构：标准「修订稿」模板（写入 `prd.md` 须遵循）**  
-   使用 **Read** 读取与 `SKILL.md` 同目录的 **[apm-refine-template.md](./apm-refine-template.md)**，按其中**修订稿骨架**与章节说明组织正文（默认全文润色形态）。执行本技能时**须**读取该文件，不以记忆代替。
+## 执行步骤
 
-   **改动与边界（仍须满足）**
+### 步骤 1：读取材料
 
-   - **修订说明**中的「本次合并的要点」须**分点**写清本次相对原文的变更与**范围边界**（影响面、不做的事）。若改动项多于 3 条，可在「修订说明」后续追加小节 **「相对原文的变更」** 继续分点罗列。
-   - 全文润色时**不要机械留空标题**：无内容的章节可删除（如无非功能则不写该章），但**背景与目标 / 范围 / 需求说明**一般应完整可读。
+1. **Read** `.apm/workitems/<需求ID>/prd.md`
+2. **Read** `.apm/workitems/<需求ID>/reviews.xml`（不存在则视为无评审）
+3. **理解 PRD 中的图片**（有则执行）：
+   - 图片为标准 Markdown：`![描述](展示URL "相对路径")` — 圆括号内为展示 URL，**引号内**为相对路径（如 `attachments/图1.png`）
+   - **优先读本地附件**：`.apm/workitems/<需求ID>/<相对路径>`；存在则用该文件理解图片内容
+   - **本地不存在时**：再用圆括号内的展示 URL 下载图片后理解
+   - 将理解到的界面/字段/交互规则写入对应需求点；回写时保留原 `![…](… "…")` 语法不变
 
-   **局部替换（不必强行铺满模板）**  
-   若本轮实质上只需替换若干段落：可在 `prd.md` 中保留未改章节，仅重写涉及段落为**修改后的完整段落**，并在 **修订说明**（或 **相对原文的变更摘要**）中用简短 bullet 说明相对原文改了什么。**对用户对话仍以步骤 5 表格为唯一输出**，不把局部稿粘贴到对话里。
+`prd.md` 不可读 → 终止，步骤 5 注明原因。
 
-3. **「问题与局限」与「待确认」**  
-   触发条件见 **[apm-refine-template.md](./apm-refine-template.md)** 文末两节；凡触发「问题与局限」的情形须按该节撰写，**禁止**因上述情况向用户发起追问。
+### 步骤 2：润色
 
-### 步骤 3：回写 `prd.md`
+**不向用户追问。** `reply` 视为补充信息。
 
-使用 **Write** 将**完整**润色后的正文写回 **第一步同一路径**：**`.apm/workitems/<需求ID>/prd.md`**（覆盖原文件）。
+1. 将 `reply` 中已拍板内容并入正文对应需求点。
+2. **Read** **[apm-refine-template.md](./apm-refine-template.md)**，按骨架、写法表与示例组织全文。
+3. 写完后按模板 **「落盘前自检」** 核对，不满足则再改一版。
+4. **待确认**：仅当补充信息原文含「待定」「再议」等时追加该章，每条一行归纳用户原意。
+5. **局部替换**：只改涉及段落时，保留其余章节，重写为完整段落。
 
-### 步骤 4：执行 `apm refine <需求ID>`
+### 步骤 3：回写
 
-在**仓库/工作区根目录**执行：
+**Write** 覆盖 `.apm/workitems/<需求ID>/prd.md`。
 
-```bash
-apm refine <需求ID>
-```
+### 步骤 4：同步
 
-命令结束后将本步执行结果记入「步骤 5」表格对应行的**状态**（见下）。
+仓库根目录执行：`apm refine <需求ID>`
 
 ### 步骤 5：回复用户
 
-对用户可见回复 **仅限一张 Markdown 表格**，**仅填写步骤 1 ～ 4 每步的执行状态**。**不得**在表格外输出任何其他内容（不粘贴 prd 正文、不另写摘要或提示）。
-
-建议表头（每行「状态」仅填 **成功** / **失败** / **跳过**；失败时可加简短原因，如 `失败：文件不存在`）：
+**仅**输出一张状态表，表格外无其他文字：
 
 | 步骤                              | 状态 |
 | --------------------------------- | ---- |
@@ -78,4 +71,4 @@ apm refine <需求ID>
 | 3. 回写 `prd.md`                  |      |
 | 4. 执行 `apm refine <需求ID>`     |      |
 
----
+状态：**成功** / **失败** / **跳过**（失败可加简短原因）。

package/template/skills/apm-refine/apm-refine-template.md

@@ -1,39 +1,73 @@
-# [需求标题]（修订稿）
+# 需求文档模板
 
-**修订说明**（可选）
+执行润色时 **Read 本文件**，按下列骨架与写法组织 `prd.md`。
 
-- 基于评审日期 / 评审记录：简要一句
-- 本次合并的要点：1～3 条 bullet
+## 正文骨架
 
----
+```markdown
+# [需求标题]
 
 ## 背景与目标
 
-（合并原文与用户补充信息中明确补充/修正的表述）
+（1 ～ 3 句：业务背景、要解决的问题、预期效果）
 
 ## 范围
 
-- **包含**：
-- **不包含**：（若**补充信息**或原文中明确收窄/排除）
+- **包含**：…
+- **不包含**：…
 
 ## 需求说明
 
-### 需求点 1：[名称]
+### 需求点 1：[简短名称]
 
-（将原文与补充信息合并后的**可执行描述**写清：角色、场景、规则、口径、边界）
+- …
+- …
 
 ### 需求点 2：…
+```
 
-## 非功能与约束（若有）
+按需追加（材料中确有相关内容时）：
 
-（性能、权限、兼容、埋点等——仅当原文或补充信息涉及）
+- **非功能与约束** — 性能、权限、兼容、埋点等
+- **待确认** — 补充信息里用户原文写明的待定项，每条 `[ ]` 一行
 
-## 待确认
+## 需求点怎么写
 
-仅当**用户自己在补充信息里**留下未拍板事项、或写明「待定」「再议」等时列出（可选章节，可整节省略）：
+每条 bullet 写清一个可验收点，优先覆盖：
 
-- [ ] （用户未决口径摘要）— 用户原话或简要归纳
+| 类型      | 写法要点                                               |
+| --------- | ------------------------------------------------------ |
+| 展示/选项 | 展示或隐藏；保留/去掉哪些选项；新建默认值              |
+| 文案      | 原名称 → 新名称；界面、提示、校验文案一并统一          |
+| 按钮      | 场景 + 按钮名 + 行为（对照哪个既有按钮、是否仅改文案） |
+| 校验      | 场景 + 字段展示条件 + 必填时机（暂存 / 提交分别怎样）  |
+| 边界      | **不考虑** …（历史数据、迁移、导出等明确排除项）       |
 
----
+材料中的技术名可译为业务表述，例如：`audit1` → 一级审批；保存不推进流程 → **暂存**；办理并推进流程 → **提交**。
 
-若用户只需要「替换某几段」而非全文，可仅在回复中给出**修改后的完整段落** + 简短「相对原文的变更摘要」，不必机械填满所有章节。
+## 示例
+
+```markdown
+### 需求点 2：新增/编辑弹窗底部操作
+
+- 在**新增、编辑**场景下，弹窗底部新增 **「暂存」** 按钮。
+- **「暂存」**：沿用原 **「确定」** 按钮的业务逻辑（含校验与保存/流程行为），**仅将按钮展示文案改为「暂存」**。
+
+### 需求点 3：「科室医德考评小组人员名单」字段
+
+- 原字段展示名 **「科室医德考评人员名单」** 统一改为 **「科室医德考评小组人员名单」**；凡界面、提示、校验文案等涉及该名称处**一并修改**。
+- 当流程处于 **一级审批** 且该字段**展示**时，须校验为**必填**（在展示场景下触发，而非所有保存入口一律校验）。
+```
+
+## 落盘前自检
+
+- [ ] 含 **背景与目标、范围、需求说明** 三章，叙述完整
+- [ ] 2 分钟内可通读；每个需求点 2 ～ 5 条 bullet，一层列表
+- [ ] 场景、按钮行为、校验时机表述清楚，前后一致
+- [ ] 「范围」与需求点中的 **「不考虑」** 口径一致
+- [ ] 全文使用业务语言，术语统一
+- [ ] 仅材料明确涉及时才有「非功能」「待确认」
+
+## 局部替换
+
+只改部分段落时：保留未改章节，替换涉及段落为完整段落；结构仍符合上文骨架。

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

@@ -1,57 +1,101 @@
 ---
 name: apm-review
-description: 结合本仓库上下文对需求做结构化评审，只有当用户主动提及该技能时才可被使用，该技能调用依赖需求ID。
+description: 结合本仓库上下文对需求做结构化评审，只有当用户主动提及该技能时才可被使用，该技能调用依赖需求 ID。
 ---
 
 # 需求评审
 
 用户仅提供 **需求 ID**（workitem id）。缺 ID 时索要，不猜测。
 
+## 评审目标
+
+帮助产品经理**梳理需求边界、发现文档中未写清的口径**，并在实现难度较高时给出提示。**不是**为了凑问题而提问——PRD 已足够清晰且无高难度改造时，可只输出少量锚定条目，不必强行列出待澄清项。
+
+## 评审立场
+
+每轮评审从 **前端 / 后端 / 全栈** 中择定一种立场，按该视角输出 **YAML 行级评审**，并执行一次 `apm comment --format=structured`。
+
+### 如何确定立场
+
+1. **用户明示**：用户说明「前端 / 后端 / 全栈 / 仅 UI / 仅接口」等，以用户为准。
+2. **用户未说明**：阅读仓库中与该需求相关的现有代码，推断评审者更贴近哪一端；仍无法判断时，**默认前端**，并在 `reviewer.stance` 使用 `frontend`。
+3. **全栈**：在同一轮评审中同时覆盖 UI 与流程/数据关注点；同一业务点若需澄清，合并为**一条** `clarify`（不要拆成两句重复问题）。
+
+### 各端关注点（互斥优先，减少并行评审重复）
+
+| 维度           | 前端                                                                       | 后端                                                                      |
+| -------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| **核心关注**   | 页面、弹窗、Tab、按钮、文案、显隐、交互顺序、校验在界面上的反馈            | 流程节点、业务规则、数据落库、字段口径、汇总/计算逻辑、权限与校验时机     |
+| **典型待澄清** | 哪些页面要改、按钮在什么场景出现、暂存/提交时界面如何提示、只读/可编辑范围 | 默认值与枚举、必填校验在暂存/提交下是否不同、主子表关系、汇总取哪一级数据 |
+| **尽量不提**   | 表结构、API 契约、payload 字段名（留给技术评审）                           | 组件名、具体控件选型、Tab 顺序（除非 PRD 已涉及且影响校验规则）           |
+
+**去重规则**（按立场选用）：
+
+- **前端立场**：只写界面与交互侧待澄清，不写落库/API 契约类问题（联调诉求用 `kind: coordination`）。
+- **后端立场**：只写流程、规则与数据侧待澄清，不写控件选型、Tab 布局等纯 UI 问题。
+- **全栈立场**：同一业务点合并为一条 `clarify`，**不要**拆成两句意思重复的问题。
+
+## 表述规范（产品经理可读）
+
+1. **产品语言优先**：用「医德考评弹窗」「行风办审批页」等说法；**禁止**用文件路径、组件名、函数名作为论据主体（行号锚定除外）。
+2. **后端可略宽**：必要时可写**表名 / 主表字段名**帮助产品理解数据口径，但仍避免贴大段代码或接口路径。
+3. **锚定 PRD**：每条 `items[]` 必须写 **`anchor: { start, end }`**，与 Read 读到的 `prd.md` 行号一致；**不**在 `body` 里复述该段需求原文。
+4. **问题 = 文档缺口**：只写 PRD **未写清**且**影响本端理解边界**的点。已写清楚的规则不要重复质疑。
+
+## 不在「待澄清」里写的内容
+
+以下不得使用 `kind: clarify`，若需记录则用 **`kind: coordination`**（且必须有行号锚定）：
+
+- 接口字段名、请求体结构、子表编码
+- 前后端谁传哪个参数、现有 edit 接口是否够用
+- 与现网代码实现对齐的改造方案
+
+`coordination` **不用产品回复**，仅作记录，待技术评审阶段处理。若同一行区间既要澄清又要联调，**拆成两条** `items`。
+
 ## 评审原则
 
-1. **产品视角优先**：用户侧影响、业务闭环、风险与待确认点；避免晦涩技术术语堆砌。
-2. **与仓库对齐（能力边界）**：阅读 `AGENTS.md`、子项目说明、`.apm/product-capability-inventory` 等与需求相关的部分，判断需求是否与既有能力/术语冲突、是否超出现有边界。**禁止**用「某文件某行」证明 PRD 对错；**禁止**根据代码**猜测** PRD 未写清的口径——口径不清应归入「问题」待产品澄清。
-3. **业务合理性（按需）**：结合仓库可读的业务/产品上下文，判断需求是否想清楚、方案是否当下较优、是否与业务目标或流程冲突。**仅当**不合理、需再商榷或非当下较优时，才写 `- **业务合理性：**:`；合理则**不写**该字段。
-4. **信息完备与落地（互斥规则）**：
-   - 仅当 PRD/需求信息**不足以**形成开发可执行描述（关键落点、口径、范围、汇总规则等无法确定）时，写 `- **问题：**`，此时**不写**可行性与风险点。
-   - 若已足以判断「可以实现」（非关键细节不阻塞落地），写 `- **可行性：**`（成本低/中/高 + 精简说明）；影响面大时再追加 `- **风险点：**`。
-5. **澄清优先但不泛问**：不阻塞落地则不提问；不问可推断的琐碎问题。
-6. **隐性知识沉淀可执行**：对用户单独输出的每条沉淀建议应能回答「在仓库里补什么、能消除哪类隐性歧义」；若本次未发现值得沉淀的差异点，仍须给出一句结论（例如「未发现与通用假设显著偏离、需单独成文的隐性规则」）。
+1. **产品视角优先**：用户侧影响、业务闭环、边界与风险。
+2. **与仓库对齐（能力边界）**：阅读 `AGENTS.md`、`.apm/product-capability-inventory` 及与需求相关的代码，判断改造面。**禁止**用代码证明 PRD 对错；口径不清归入 `clarify`。
+3. **`kind: business`**：仅当方案与业务目标明显冲突或明显非较优解时使用。
+4. **`kind: difficulty`**：仅当改造面大或业务逻辑影响大时使用。
+5. **澄清优先但不泛问**：不阻塞理解则不提问。
 
 ## 执行步骤
 
 ### 步骤 1：读取 `prd.md`
 
 1. 使用 **Read** 读取 `.apm/workitems/<需求ID>/prd.md`。
-2. 当 PRD 涉及到图片链接时，自动下载对应的图片，存放在 `.apm/workitems/<需求ID>/images/<对应图片名称>.png`，并理解图片内容
-3. 若 Read **失败**（文件不存在或无法读取）：本步骤记为失败，**终止**，不执行步骤 2、3。
+2. 当 PRD 涉及到图片链接时，自动下载对应的图片，存放在 `.apm/workitems/<需求ID>/images/<对应图片名称>.png`，并理解图片内容。
+3. 若 Read **失败**：本步骤记为失败，**终止**，不执行后续步骤。
 
 ### 步骤 2：读代码
 
-阅读仓库源码以及 `.apm/product-capability-inventory` 中与需求相关的条目；不展开无关模块代码。
-
-### 步骤 3：评审
-
-1. **拆条**：多条诉求时拆成 `### 需求点 1..N`，每条独立走完「业务合理性（可选）→ 问题 或 可行性（+风险）」逻辑。
-
-2. **成文（仅评审模板）**：按 `output-template.md` 拼出写入 comment 的 Markdown（顶格可加 `### 评审人` + 当前模型名）；**不含**「隐性知识沉淀」段落；
-
-3. 使用 **Write** 将正文写入**临时文件**，路径建议使用**绝对路径**，例如 `/tmp/apm-review-<需求ID>.md`。**Markdown 评审正文**：**只写确实存在的问题**；用「需求背景 / 需求范围 / 交互与功能要求第 X 节 / 非目标」等文档自有结构**点名条款**（半句锚定即可），不先单独铺一节「对用户意图的理解」，**不写与 `prd-review` 类似的整条「需求描述」复述**。撰写前须完成代码检索并锁定本轮**评审立场**（见 reference 中「评审立场」），正文内容与措辞须与该立场一致，**不得超越可见范围下断定**。
+阅读仓库源码以及 `.apm/product-capability-inventory` 中与需求相关的条目，用于**理解现网能力与边界、判断改造面**。
 
-4. **自检**：每条是否都有「需求描述」；「问题」与「可行性/风险」是否互斥符合 `output-template.md`；是否误引代码路径作论据；comment 全文是否**未混入**隐性知识段落。
+### 步骤 3：评审与提交
 
-5. **提交评审记录**：在项目根目录下执行：`apm comment <需求ID> --file=<临时文件绝对路径> --model=<评论使用的模型名称>`。
+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. **自检**：
+   - 每条均有 `anchor`，且无全篇评审；
+   - `stance` 与立场一致；
+   - `clarify` 均为产品可回答的业务问题；
+   - `coordination` 无 `reply` 字段；
+   - 无重复语义的条目。
+6. 在项目根目录执行：
 
-6. 命令结束后 **删除临时文件**（**Delete** 工具或 `rm`），无论命令成功或失败都尽量清理（失败时保留文件仅供用户排错——技能默认仍删除，若需保留应在表格备注中说明）。
+   `apm comment <需求ID> --file=<临时文件绝对路径> --format=structured --model=<模型名>`
 
-### 步骤 3：回复用户
+7. 命令结束后 **删除临时文件**（失败时若需排错可保留，默认仍删除）。
 
-对用户可见回复 **仅限一张 Markdown 表格**，汇总三步的**结果**（成功/失败、摘要信息）。**不得**在表格外输出任何其他内容（不在对话中粘贴完整评审正文；正文已通过 `apm comment` 提交）。
+### 步骤 4：回复用户
 
-建议表头：
+对用户可见回复 **仅限一张 Markdown 表格**，汇总各步**结果**。**不得**在表格外输出其他内容。
 
-| 步骤              | 结果        | 说明                                                                                                                          |
-| ----------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| 1. 读取 prd.md    | 成功 / 失败 | 例如实际读取路径；失败时写错误原因                                                                                            |
-| 2. 评审与 comment | 成功 / 失败 | 临时文件路径（已删可写「已清理」）；`apm comment` 退出情况或 API 返回摘要；**建议**注明本轮评审立场（仅前台 / 仅后台 / 全栈） |
-| 3. 清理临时文件   | 成功 / 失败 | —                                                                                                                             |
+| 步骤              | 结果        | 说明                                                                            |
+| ----------------- | ----------- | ------------------------------------------------------------------------------- |
+| 1. 读取 prd.md    | 成功 / 失败 | 实际路径；失败时写原因                                                          |
+| 2. 评审与 comment | 成功 / 失败 | 临时文件；`apm comment` 情况；**注明 stance**（frontend / backend / fullstack） |
+| 3. 清理临时文件   | 成功 / 失败 | —                                                                               |

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

@@ -1,43 +1,64 @@
-### 需求点 1
+# 评审输出模板（YAML · structured）
 
-- **需求描述：**: （一句话概括要做什么，产品视角）
-  - （关键点 1）
-  - （关键点 2）
+使用 **YAML** 文件提交行级评审；每条必须锚定 `prd.md` 行号。全文使用**产品经理可读**的表述；**不**在 `body` 里复述需求原文。
 
-### 需求点 2
+## 文件示例
 
-- **需求描述：**: （一句话概括要做什么，产品视角）
+```yaml
+reviewer:
+  model: Auto
+  stance: frontend # frontend | backend | fullstack
 
-- **问题：**
-  - （问题 1：必须澄清“页面/表/口径/范围/汇总规则”等）
-  - （问题 2）
-  - （问题 3）
+items:
+  - anchor: { start: 44, end: 55 }
+    kind: clarify
+    body: |
+      - 「类型」隐藏后，统计分析页的「分类」筛选是否一并去掉，导出是否统一走临床模板
 
-### 需求点 3
+  - 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: |
+      - 用产品语言说明改造面：涉及哪些页面/流程/规则，为何面大
 
-### 需求点 4
+  - anchor: { start: 44, end: 55 }
+    kind: coordination
+    body: |
+      - 需与后端对齐的接口/字段诉求（不用产品回复）
+```
 
-- **需求描述：**: （一句话概括要做什么，产品视角）
-- **可行性：**
-  - 成本：中/高
-  - （在不引入猜测的前提下，说明成本对应的业务/口径/环节调整）
-- **风险点：**
-  - （风险 1：可能影响的不止是展示文案，例如统计口径/汇总逻辑/跨模块联动等）
-  - （风险 2）
+## kind 与技能表述
 
-### 需求点 5（业务合理性：仅不合理时出现）
+| `kind`（YAML 小写） | 含义       | 说明                         |
+| ------------------- | ---------- | ---------------------------- |
+| `clarify`           | 待澄清     | 文档未写清、影响本端理解边界 |
+| `difficulty`        | 实现难度高 | 仅改造面大或业务逻辑影响大时 |
+| `business`          | 业务合理性 | 仅方案明显不合理时           |
+| `coordination`      | 联调依赖   | **禁止** `reply`；待技术评审 |
 
-- **需求描述：**: （一句话概括要做什么，产品视角）
-- **业务合理性：**
-  - （为何不合理/与用户目标或现有业务冲突/用户方案非当下较优；可写更可取的替代思路或需产品先拍板的点）
-- **可行性：**
-  - 成本：低/中/高
-  - （仍可在指出业务问题的同时评估落地成本；若信息仍不足以落地，则改用「需求点 2」结构：业务合理性 + **问题**，不出现可行性/风险点）
+## 字段规则
 
-字段顺序与并存：`需求描述` 始终第一；`业务合理性` 仅在不合理时出现在 `需求描述` 之后。其后仍遵循「有问题则只写问题，无问题则写可行性（可加风险点）」。
+| 字段              | 规则                                                             |
+| ----------------- | ---------------------------------------------------------------- |
+| `reviewer.stance` | 必填：`frontend` / `backend` / `fullstack`                       |
+| `reviewer.model`  | 建议填写；可被 CLI `--model` 覆盖                                |
+| `anchor`          | 必填 `{ start, end }`，1-based 闭区间，与 Read `prd.md` 行号一致 |
+| `body`            | 必填；产品语言；**禁止**全篇评审（必须有行号）                   |
+| 同区间多类型      | 拆成多条 `items`（例如同时 `clarify` 与 `coordination` 各一条）  |
+
+## 提交命令
+
+```bash
+apm comment <需求ID> --file=/tmp/apm-review-<需求ID>.yaml --format=structured --model=<模型名>
+```
+
+`.yaml` / `.yml` 扩展名在未指定 `--format` 时默认按 structured 解析。