ai-project-manage-cli 4.0.7 → 4.0.9

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
@@ -1006,6 +1003,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 +1107,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 +1119,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 +1218,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 +1231,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 +1441,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 +1461,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 +1766,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 +2131,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 +2150,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) => {

package/package.json

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

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

@@ -1,43 +1,75 @@
+# 评审输出模板
+
+顶格写评审人，随后按 PRD 章节逐条输出。全文使用**产品经理可读**的表述；锚定 PRD 时**只写行号**，不复述需求。
+
+```markdown
+### 评审人
+
+{模型名}（{前端 / 后端 / 全栈}）
+
 ### 需求点 1
 
-- **需求描述：**: （一句话概括要做什么，产品视角）
-  - （关键点 1）
-  - （关键点 2）
+- **锚定：** `prd.md` L44–L55
+
+- **待澄清：**
+  - {文档未写清、影响本端理解边界的点；无则整段省略}
+  - {示例（前端）：「类型」隐藏后，统计分析页的「分类」筛选是否一并去掉，导出是否统一走临床模板}
+  - {示例（后端）：新建单据「默认临床」对应字典编码/文案未写明，历史非临床记录在列表是否仍展示原类型}
 
 ### 需求点 2
 
-- **需求描述：**: （一句话概括要做什么，产品视角）
+- **锚定：** `prd.md` L59–L67
 
-- **问题：**
-  - （问题 1：必须澄清“页面/表/口径/范围/汇总规则”等）
-  - （问题 2）
-  - （问题 3）
+{PRD 已写清且改造面不大 → 仅锚定，不写其他字段}
 
 ### 需求点 3
 
-- **需求描述：**: （一句话概括要做什么，产品视角）
-
-- **可行性：**
-  - 成本：低/中/高
-  - （在不引入猜测的前提下，说明成本对应的业务/口径/环节调整）
+- **锚定：** `prd.md` L69–L81
 
-### 需求点 4
+- **待澄清：**
+  - {仅列本端视角的缺口}
 
-- **需求描述：**: （一句话概括要做什么，产品视角）
-- **可行性：**
-  - 成本：中/高
-  - （在不引入猜测的前提下，说明成本对应的业务/口径/环节调整）
-- **风险点：**
-  - （风险 1：可能影响的不止是展示文案，例如统计口径/汇总逻辑/跨模块联动等）
-  - （风险 2）
+### 需求点 4（业务合理性：仅不合理时出现）
 
-### 需求点 5（业务合理性：仅不合理时出现）
+- **锚定：** `prd.md` L83–L106
 
-- **需求描述：**: （一句话概括要做什么，产品视角）
 - **业务合理性：**
-  - （为何不合理/与用户目标或现有业务冲突/用户方案非当下较优；可写更可取的替代思路或需产品先拍板的点）
-- **可行性：**
-  - 成本：低/中/高
-  - （仍可在指出业务问题的同时评估落地成本；若信息仍不足以落地，则改用「需求点 2」结构：业务合理性 + **问题**，不出现可行性/风险点）
 
-字段顺序与并存：`需求描述` 始终第一；`业务合理性` 仅在不合理时出现在 `需求描述` 之后。其后仍遵循「有问题则只写问题，无问题则写可行性（可加风险点）」。
+  - {为何与业务目标冲突或方案非较优；可给替代思路}
+
+- **待澄清：**
+  - {若仍有文档缺口}
+
+### 需求点 5
+
+- **锚定：** `prd.md` L108–L132
+
+- **实现难度高：**
+  - {用产品语言说明：改造涉及哪些页面/流程/规则，为何面大；示例：加/减分明细需按审批层级分块改造，涉及弹窗表单、子表编辑与汇总多处联动，业务规则变化面大}
+
+---
+
+## 联调依赖项
+
+{**仅当前端评审**且存在联调前置信息时出现；**可选**，无则省略整节}
+
+> 不用产品回复，仅记录，待技术评审阶段处理。
+
+{简短条目，记录后续需与后端对齐的接口/字段/能力诉求}
+
+- 一票否决：需明确存储位置（主表字段或独立子表）及回显字段，以便行风办页勾选与查看页展示。
+- 加/减分明细分级：需明确各级分值对应落库字段，以便分块编辑与汇总。
+```
+
+## 字段规则
+
+
+| 字段        | 规则                                                             |
+| --------- | -------------------------------------------------------------- |
+| **锚定**    | 每条必有；写 `prd.md` L{起}–L{止}，与 Read 工具读到的行号一致；**不**概括、**不**复述该段需求 |
+| **待澄清**   | 按需；无缺口则**不写**（不要写「无」）                                          |
+| **实现难度高** | 按需；**仅**改造面大或业务逻辑影响大时写；一般难度**不写**                              |
+| **业务合理性** | 按需；仅方案明显不合理时出现                                                 |
+| **联调依赖项** | 全文最多一节；**不算待澄清**；不用产品回复，仅记录，待技术评审阶段处理                          |
+
+