ai-project-manage-cli 6.0.54 → 6.0.56

package/dist/index.js

@@ -999,6 +999,19 @@ function reasonForCleanup(sessionId, sessionStatusById) {
   }
   return "\u4FDD\u7559";
 }
+async function isBranchMergedIntoDefault(cwd, branch, defaultBranch) {
+  const ref = await localBranchExists2(cwd, branch) ? branch : `origin/${branch}`;
+  try {
+    await execGit3(
+      cwd,
+      ["merge-base", "--is-ancestor", ref, `origin/${defaultBranch}`],
+      true
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
 async function runCleanBranches(options = {}) {
   const cwd = options.cwd ?? process.cwd();
   const dryRun = options.dryRun ?? false;
@@ -1035,11 +1048,20 @@ async function runCleanBranches(options = {}) {
   }
   let currentBranch = await getCurrentBranch2(cwd);
   let defaultBranch = null;
+  if (dryRun) {
+    defaultBranch = await resolveDefaultBranch(cwd);
+  }
   for (const item of toDelete) {
     const { branch, sessionId, reason } = item;
     const label = `${branch} (${sessionId}: ${reason})`;
     if (dryRun) {
-      console.log(`[apm] [dry-run] \u5C06\u5220\u9664 ${label}`);
+      const merged = await isBranchMergedIntoDefault(
+        cwd,
+        branch,
+        defaultBranch
+      );
+      const mergeTag = merged ? "\u5DF2\u5408\u5E76" : "\u672A\u5408\u5E76";
+      console.log(`[apm] [dry-run] \u5C06\u5220\u9664 ${label} [${mergeTag}]`);
       continue;
     }
     if (currentBranch === branch) {
@@ -1482,7 +1504,7 @@ async function runUpdate() {
   const latest = await fetchLatestPublishedVersion();
   if (latest && current === latest) {
     console.log(`[apm] \u5DF2\u662F\u6700\u65B0\u7248\u672C ${current}`);
-    return;
+    return { didUpdate: false };
   }
   if (!npmAvailable()) {
     console.error(
@@ -1512,22 +1534,22 @@ async function runUpdate() {
       `[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`
     );
   }
+  return { didUpdate: true };
 }
 
 // src/commands/update-skills.ts
 import { existsSync as existsSync6, mkdirSync as mkdirSync4, statSync as statSync3 } from "fs";
 import { join as join10 } from "path";
-async function runUpdateSkills() {
-  const apmDir = workspaceApmDir();
-  if (!existsSync6(apmDir)) {
-    console.error("[apm] \u672A\u627E\u5230 .apm \u76EE\u5F55\uFF0C\u8BF7\u5148\u6267\u884C apm init");
-    process.exit(1);
+async function syncWorkspaceSkills(cfg, workdir) {
+  const apmDir = workspaceApmDir(workdir);
+  const fsApmDir = toFsPath(apmDir);
+  if (!existsSync6(fsApmDir)) {
+    throw new Error("[apm] \u672A\u627E\u5230 .apm \u76EE\u5F55\uFF0C\u8BF7\u5148\u6267\u884C apm init");
   }
-  const apmStat = statSync3(apmDir);
+  const apmStat = statSync3(fsApmDir);
   if (!apmStat.isDirectory()) {
     throw new Error(`[apm] \u8DEF\u5F84\u5DF2\u5B58\u5728\u4F46\u4E0D\u662F\u76EE\u5F55: ${apmDir}`);
   }
-  const cfg = await ensureLoggedConfig();
   const api = createApmApiClient(cfg);
   const { list } = await api.cli.listSkills({});
   if (syncAgentsGuide(apmDir)) {
@@ -1539,7 +1561,7 @@ async function runUpdateSkills() {
     console.log(`[apm] \u5DF2\u540C\u6B65\u57FA\u7840\u89C4\u5219: rules/${name}`);
   }
   const skillsDir = join10(apmDir, "skills");
-  mkdirSync4(skillsDir, { recursive: true });
+  mkdirSync4(toFsPath(skillsDir), { recursive: true });
   const baseNames = syncBaseSkills(skillsDir);
   for (const name of baseNames) {
     console.log(`[apm] \u5DF2\u540C\u6B65\u57FA\u7840\u6280\u80FD: skills/${name}/`);
@@ -1563,6 +1585,19 @@ async function runUpdateSkills() {
     `[apm] \u540C\u6B65\u5B8C\u6210\uFF1A${ruleNames.length} \u4E2A\u57FA\u7840\u89C4\u5219\uFF0C${baseNames.length} \u4E2A\u57FA\u7840\u6280\u80FD\uFF0C${written.length} \u4E2A\u8865\u5145\u6280\u80FD`
   );
 }
+async function runUpdateSkills() {
+  const apmDir = workspaceApmDir();
+  if (!existsSync6(apmDir)) {
+    console.error("[apm] \u672A\u627E\u5230 .apm \u76EE\u5F55\uFF0C\u8BF7\u5148\u6267\u884C apm init");
+    process.exit(1);
+  }
+  const apmStat = statSync3(apmDir);
+  if (!apmStat.isDirectory()) {
+    throw new Error(`[apm] \u8DEF\u5F84\u5DF2\u5B58\u5728\u4F46\u4E0D\u662F\u76EE\u5F55: ${apmDir}`);
+  }
+  const cfg = await ensureLoggedConfig();
+  await syncWorkspaceSkills(cfg, resolveWorkdirPath());
+}
 
 // src/commands/sync-deploy-config.ts
 import { existsSync as existsSync7, statSync as statSync4 } from "fs";
@@ -1741,6 +1776,7 @@ async function runUpdateMessageStatus(options) {
 }
 
 // src/commands/connect.ts
+import { spawnSync as spawnSync2 } from "child_process";
 import WebSocket from "ws";
 
 // src/ws/protocol.ts
@@ -2395,6 +2431,56 @@ async function runCursorAgent(cfg, ctx, options) {
   }
 }
 
+// src/commands/connect/cli-version-sync.ts
+import { existsSync as existsSync11, readFileSync as readFileSync9, writeFileSync as writeFileSync10 } from "fs";
+import { join as join12 } from "path";
+var CLI_VERSION_FILE = ".cli-version.json";
+function manifestPath(apmDir) {
+  return join12(apmDir, CLI_VERSION_FILE);
+}
+function loadManifest3(apmDir) {
+  const path10 = toFsPath(manifestPath(apmDir));
+  if (!existsSync11(path10)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(
+      readFileSync9(path10, "utf8")
+    );
+    if (parsed?.version === 1 && typeof parsed.cliVersion === "string" && parsed.cliVersion.trim()) {
+      return parsed;
+    }
+  } catch {
+  }
+  return null;
+}
+function saveManifest3(apmDir, cliVersion) {
+  const manifest = { version: 1, cliVersion };
+  writeFileSync10(
+    toFsPath(manifestPath(apmDir)),
+    `${JSON.stringify(manifest, null, 2)}
+`,
+    "utf8"
+  );
+}
+var syncedInSession = /* @__PURE__ */ new Map();
+function shouldSyncSkillsForCliVersion(workdir, currentVersion) {
+  const cached = syncedInSession.get(workdir);
+  if (cached === currentVersion) {
+    return false;
+  }
+  const stored = loadManifest3(workspaceApmDir(workdir));
+  if (stored?.cliVersion === currentVersion) {
+    syncedInSession.set(workdir, currentVersion);
+    return false;
+  }
+  return true;
+}
+function markSkillsSyncedForCliVersion(workdir, cliVersion) {
+  saveManifest3(workspaceApmDir(workdir), cliVersion);
+  syncedInSession.set(workdir, cliVersion);
+}
+
 // src/commands/connect/pre-step-cache.ts
 var PULL_TTL_MS = 3e4;
 function sessionWorkdirKey(sessionId, workdir) {
@@ -2513,6 +2599,19 @@ async function handleInboundMessage(cfg, msg, signal, ctx) {
     } else {
       console.log(`[apm] step=commit-pull skipped sessionId=${msg.sessionId}`);
     }
+    const cliVersion = readCliVersion();
+    if (shouldSyncSkillsForCliVersion(workdir, cliVersion)) {
+      if (signal.aborted) return;
+      console.log(
+        `[apm] CLI \u7248\u672C ${cliVersion} \u4E0E\u5DE5\u4F5C\u533A\u8BB0\u5F55\u4E0D\u4E00\u81F4\uFF0C\u6267\u884C update-skills`
+      );
+      await runStep("update-skills", async () => {
+        await syncWorkspaceSkills(cfg, workdir);
+        markSkillsSyncedForCliVersion(workdir, cliVersion);
+      });
+    } else {
+      console.log(`[apm] step=update-skills skipped workdir=${workdir}`);
+    }
     if (signal.aborted) return;
     await runStep(
       "cursor-agent",
@@ -2584,7 +2683,24 @@ function startHeartbeat(ws, clientMachineId) {
   const timer = setInterval(send, HEARTBEAT_MS);
   return () => clearInterval(timer);
 }
+function reexecConnect(options) {
+  const args = [process.argv[1], "connect"];
+  const server = options.server?.trim();
+  if (server) {
+    args.push("--server", server);
+  }
+  const result = spawnSync2(process.execPath, args, { stdio: "inherit" });
+  if (result.error) {
+    console.error("[apm] \u91CD\u542F connect \u5931\u8D25:", result.error.message);
+    process.exit(1);
+  }
+  process.exit(result.status ?? 0);
+}
 async function runConnect(options) {
+  const { didUpdate } = await runUpdate();
+  if (didUpdate) {
+    reexecConnect(options);
+  }
   const cfg = await ensureLoggedConfig();
   if (options.server?.trim()) {
     cfg.baseUrl = options.server.trim().replace(/\/+$/, "");
@@ -2736,19 +2852,19 @@ async function runCreatePr(options) {
 import path5 from "node:path";
 
 // src/commands/deploy/internal/apm-config.ts
-import { existsSync as existsSync11, readFileSync as readFileSync9 } from "node:fs";
+import { existsSync as existsSync12, readFileSync as readFileSync10 } from "node:fs";
 import { resolve as resolve4 } from "node:path";
 function loadApmConfig(options) {
   const p = resolve4(
     process.cwd(),
     options?.configPath ?? resolve4(workspaceApmDir(), "apm.config.json")
   );
-  if (!existsSync11(p)) {
+  if (!existsSync12(p)) {
     console.error(`\u672A\u627E\u5230\u914D\u7F6E\u6587\u4EF6\uFF1A${p}`);
     process.exit(1);
   }
   try {
-    const raw = readFileSync9(p, "utf8");
+    const raw = readFileSync10(p, "utf8");
     return JSON.parse(raw);
   } catch (e) {
     console.error(`\u65E0\u6CD5\u89E3\u6790 apm.config.json\uFF1A${p}`, e);
@@ -2870,7 +2986,7 @@ import path4 from "node:path";
 import Docker from "dockerode";
 
 // src/commands/deploy/internal/backend-deploy/dockerode-client/connection-options.ts
-import { existsSync as existsSync12, readFileSync as readFileSync10 } from "node:fs";
+import { existsSync as existsSync13, readFileSync as readFileSync11 } from "node:fs";
 import path from "node:path";
 function asOptionalTlsBuffer(value) {
   if (typeof value !== "string") {
@@ -2882,8 +2998,8 @@ function asOptionalTlsBuffer(value) {
   if (normalized === "") {
     return void 0;
   }
-  if (existsSync12(normalized)) {
-    return readFileSync10(normalized);
+  if (existsSync13(normalized)) {
+    return readFileSync11(normalized);
   }
   const looksLikePath = /[\\/]/.test(normalized) || normalized.endsWith(".pem");
   if (looksLikePath) {
@@ -3093,7 +3209,7 @@ var DockerodeClient = class {
 var createDockerodeClient = (config) => new DockerodeClient(config);
 
 // src/commands/deploy/internal/backend-deploy/dockerode-client/env.ts
-import { existsSync as existsSync13, readFileSync as readFileSync11, statSync as statSync5 } from "node:fs";
+import { existsSync as existsSync14, readFileSync as readFileSync12, statSync as statSync5 } from "node:fs";
 import path2 from "node:path";
 function stripSurroundingQuotes(value) {
   const t = value.trim();
@@ -3110,10 +3226,10 @@ function loadEnvFromFile(envFilePath) {
     return {};
   }
   const targetPath = path2.resolve(envFilePath);
-  if (!existsSync13(targetPath) || !statSync5(targetPath).isFile()) {
+  if (!existsSync14(targetPath) || !statSync5(targetPath).isFile()) {
     return {};
   }
-  const raw = readFileSync11(targetPath, "utf-8");
+  const raw = readFileSync12(targetPath, "utf-8");
   const result = {};
   for (const line of raw.split(/\r?\n/)) {
     const normalized = line.trim();
@@ -3284,12 +3400,12 @@ function dockerPushImage(params, cwd) {
 }
 
 // src/commands/deploy/internal/backend-deploy/resolve-dockerfile.ts
-import { existsSync as existsSync14 } from "node:fs";
+import { existsSync as existsSync15 } from "node:fs";
 import path3 from "node:path";
 function resolveDockerBuildPaths(cwd) {
   const dockerfilePath = path3.join(cwd, "Dockerfile");
   Logger.info(`\u67E5\u627EDockerfile\u6587\u4EF6\uFF0C\u8DEF\u5F84: ${dockerfilePath}`);
-  if (!existsSync14(dockerfilePath)) {
+  if (!existsSync15(dockerfilePath)) {
     throw new Error(`Dockerfile \u4E0D\u5B58\u5728\uFF1A${dockerfilePath}`);
   }
   Logger.info("\u2713 Dockerfile \u5B58\u5728");
@@ -3939,7 +4055,7 @@ function buildProgram() {
     await runUpdateMessageStatus(opts);
   });
   program.command("connect").description(
-    "\u8FDE\u63A5\u5E73\u53F0 WebSocket\uFF08/ws/agent\uFF09\uFF0C\u7EF4\u6301\u5FC3\u8DF3\u5E76\u5904\u7406\u4E0B\u884C message\uFF08TYPING \u2192 Cursor \u2192 SUCCESS/FAILED\uFF09"
+    "\u8FDE\u63A5\u5E73\u53F0 WebSocket\uFF08/ws/agent\uFF09\uFF0C\u7EF4\u6301\u5FC3\u8DF3\u5E76\u5904\u7406\u4E0B\u884C message\uFF08TYPING \u2192 Cursor \u2192 SUCCESS/FAILED\uFF09\uFF1B\u542F\u52A8\u524D\u81EA\u52A8 apm update \u5230\u6700\u65B0\u7248"
   ).option("--server <url>", "API \u6839\u5730\u5740\uFF0C\u8986\u76D6 config \u4E2D\u7684 baseUrl").action(async (opts) => {
     await runConnect(opts);
   });

package/package.json

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

package/template/rules/write_doc.md

@@ -21,7 +21,10 @@
 固定文件名: `SQL.md`
 保存位置: `.apm/sessions/<会话 ID>/docs/SQL.md`
 适用场景: 后端开发涉及 SQL 改动（DDL/DML、表结构、Mapper/XML 中 SQL 等）时必须产出或追加更新，详见 `.apm/skills/apm-dev/SKILL.md` 中「后端 SQL 变更文档」章节。
-格式要求: 待执行的 SQL 语句须放在 ` ```sql ` 代码块中，按执行顺序逐条列出。
+格式要求:
+
+- 须标注**目标数据库**（库名/实例名、类型如 MySQL；同一变更涉及多库时分别标注）
+- 待执行的 SQL 语句须放在 ` ```sql ` 代码块中，按执行顺序逐条列出
 
 ## 文档同步
 

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

@@ -5,7 +5,7 @@
 ### 步骤 1: 获取实现计划与协作内容
 
 1. 用 **Read** 工具阅读本端计划：前端读 `.apm/sessions/<会话ID>/docs/FRONTEND-PLAN.md`，后端读 `docs/BACKEND-PLAN.md`；计划不存在则退出流程并回复说明（兼容旧流程：若存在 `PRD.md` + `FRONTEND.md` / `BACKEND.md` + `API.md`，按旧文档执行）。
-2. 前端涉及接口对接时，以后端计划中的「API 契约」章节为准，**不等后端部署完成**；契约没写清的字段 `@后端` 确认，禁止自行猜测。
+2. 前端涉及接口对接时，以 `docs/API.md` 为唯一契约来源，**不等后端部署完成**；`API.md` 不存在或字段没写清时 `@后端` 补充，禁止自行猜测或在计划中重复编写接口定义。
 3. **假设门禁（开发前必须检查）**：查看计划「依据与假设」章节——
    - 「假设」仍有未确认项：**Read** `.apm/sessions/<会话ID>/messages.xml`，查找项目经理是否已回复确认；
    - 项目经理已回复：先按 `.apm/skills/apm-write-plan/SKILL.md` 步骤 5 把确认结果**回填进计划文档并同步**（确认的假设移入「依据」，否定的修订实现步骤与白名单），然后再开发；
@@ -50,6 +50,7 @@
 
 若本次改动涉及 SQL（DDL/DML、表结构、索引、数据修复、Mapper/XML 中新增或修改 SQL 语句等），开发阶段必须 **Write** `.apm/sessions/<会话ID>/docs/SQL.md`，内容包括：
 
+- **目标数据库**（库名/实例名、类型如 MySQL；同一变更涉及多库时分别标注）
 - 变更摘要（改了什么表/数据、为什么）
 - 完整 SQL 语句（按执行顺序排列；**每条须放在 ` ```sql ` 代码块中**，便于复制执行）
 - 执行环境说明（测试/生产是否一致、是否需人工执行）
@@ -58,6 +59,10 @@
 示例：
 
 ````markdown
+## 目标数据库
+
+`oxc_platform`（MySQL 8.x）
+
 ## 变更摘要
 
 为 inspection_class 表新增 is_project_add 字段。
@@ -84,6 +89,6 @@ ALTER TABLE inspection_class ADD COLUMN is_project_add VARCHAR(1) DEFAULT '0';
 2. **发布测试环境**：**Read** `.apm/skills/apm-deploy/SKILL.md` 并按其流程部署；**后端**涉及 SQL 变更时，须在回复中引用 `docs/SQL.md`，并写明待执行的 SQL 文件名或执行顺序。
 3. **白名单对账**：在回复中逐文件列出本次改动与计划白名单的对应关系。
 
-**注意：不做联调。** 前后端各自按 API 契约交付，接口对不上属于契约或实现问题，由 diff 评审与人工验收暴露后打回修复；禁止自行发起「联调」「接口实测」类的开放式动作。
+**注意：不做联调。** 前后端各自按 `API.md` 交付，接口对不上属于契约或实现问题，由 diff 评审与人工验收暴露后打回修复；禁止自行发起「联调」「接口实测」类的开放式动作。
 
 完成后用 `append_message` 回复：改动概述 + 白名单对账 + 构建结果 + 测试环境地址，并 `@` 评审角色进行 diff 评审。

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

@@ -18,12 +18,12 @@
 
 ### 步骤 2：四项检查
 
-| 检查项         | 判定                                                                                                                      |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| **白名单对账** | diff 中出现白名单之外的文件，且计划未更新说明 → **不通过**                                                                |
-| **需求相关性** | 存在与本需求无关的改动（顺手重构、改格式、动了无关逻辑）→ **不通过**                                                      |
-| **计划落实**   | 计划「实现步骤」中的关键点在 diff 中找不到对应实现 → **不通过**                                                           |
-| **SQL 文档**   | **仅后端**：diff 涉及 SQL 改动（DDL/DML、表结构、Mapper/XML 中 SQL 等），但 `docs/SQL.md` 缺失或与改动不一致 → **不通过** |
+| 检查项         | 判定                                                                                                                                          |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| **白名单对账** | diff 中出现白名单之外的文件，且计划未更新说明 → **不通过**                                                                                    |
+| **需求相关性** | 存在与本需求无关的改动（顺手重构、改格式、动了无关逻辑）→ **不通过**                                                                          |
+| **计划落实**   | 计划「实现步骤」中的关键点在 diff 中找不到对应实现 → **不通过**                                                                               |
+| **SQL 文档**   | **仅后端**：diff 涉及 SQL 改动（DDL/DML、表结构、Mapper/XML 中 SQL 等），但 `docs/SQL.md` 缺失、未标注目标数据库、或与改动不一致 → **不通过** |
 
 注意事项：
 

package/template/skills/apm-write-plan/SKILL.md

@@ -6,10 +6,12 @@
 
 本技能合并了原 `apm-write-prd`、`apm-review`、`apm-write-frontend-plan`、`apm-write-backend-api` 四个技能的职能：评审（判断是否参与、发现口径缺口）和方案（怎么改、改哪些文件）一步完成。
 
-| 角色 | 产出文档                                | 路径                    |
-| ---- | --------------------------------------- | ----------------------- |
-| 后端 | `BACKEND-PLAN.md`（含「API 契约」章节） | `docs/BACKEND-PLAN.md`  |
-| 前端 | `FRONTEND-PLAN.md`                      | `docs/FRONTEND-PLAN.md` |
+| 角色 | 产出文档                                                      | 路径                                  |
+| ---- | ------------------------------------------------------------- | ------------------------------------- |
+| 后端 | `BACKEND-PLAN.md`（实现计划）+ `API.md`（联调契约，单独产出） | `docs/BACKEND-PLAN.md`、`docs/API.md` |
+| 前端 | `FRONTEND-PLAN.md`                                            | `docs/FRONTEND-PLAN.md`               |
+
+**两份后端文档禁止合并**：`BACKEND-PLAN.md` 不写完整参数表 / JSON 示例；`API.md` 不写 Service / SQL 等实现细节。
 
 ---
 
@@ -28,14 +30,17 @@
 2. **再调研代码**：只看与需求直接相关的页面 / 接口 / 表。**调研预算：最多读 15 个代码文件**，禁止全库考古、禁止顺藤摸瓜阅读无关模块。
 3. **口径不清不要自己拍板**：调研中发现需求没写清的业务口径（例如字段含义、互斥规则、历史数据兼容），一律记入计划的「依据与假设」章节，禁止编造业务规则。
 
+**前端额外要求**：若本次涉及接口对接，**Read** `docs/API.md`；不存在则先 `@后端` 产出 `API.md`，**禁止在计划中自行编写或抄写接口定义**。
+
 ### 步骤 3：按模板写计划
 
-**Read** `.apm/skills/apm-write-plan/plan-template.md`，按模板 **Write** 对应的计划文档。三个章节为硬性要求，缺一不可：
+**Read** `.apm/skills/apm-write-plan/plan-template.md`，按模板 **Write** 对应的计划文档。硬性要求，缺一不可：
 
 1. **依据与假设**：每条关键口径标注来源（需求原文第几条 / 现有代码行为 / 已有文档）；标不出来源的就是「假设」，单独列出。
 2. **改动文件白名单**：本次允许改动的文件完整列表。后续开发与 diff 评审都以此为准，**开发时改了白名单之外的文件会被打回**。
-3. **后端专属——API 契约**：给前端看的接口定义（Path、参数、响应示例、错误码）。前端开发以契约为准，不等后端部署完成。
+3. **后端专属——同步产出 API.md**（涉及接口变更时）：**Read** `.apm/skills/apm-write-plan/api-template.md`，按模板 **Write** `docs/API.md`。这是前端联调的唯一契约来源，前端直接阅读本文档，禁止各写一份。
 4. **后端专属——SQL 变更声明**（仅当涉及表结构/数据变更时）：在「实现步骤」中注明开发须产出 `docs/SQL.md`；计划本身不写大段 SQL，完整语句由后端开发阶段写入该文档。
+5. **前端专属——接口对接要点**：只写「何时调、关键点」，引用 `API.md` 章节，**禁止复制参数表 / JSON 示例**。
 
 ### 步骤 4：回复
 
@@ -43,7 +48,8 @@
 
 - **「假设」章节非空**：把假设逐条列进回复内容，`@项目经理` 请其确认；明确说「以上假设确认前不开始开发」。
 - **无假设**：回复计划已就绪，可进入测试要点编写。
-- 前端计划依赖的接口后端契约还没出：在计划「期望接口」小节写出前端期望的接口形态，回复时 `@后端` 对齐，不要空等。
+- **后端**：涉及接口变更时，回复中 `@前端` 阅读 `API.md` 并编写 `FRONTEND-PLAN.md`。
+- **前端**：`API.md` 尚未就绪时，回复 `@后端` 先产出 `API.md`，**禁止自行编写接口契约**。
 
 ### 步骤 5：假设回填（项目经理确认后必须执行）
 
@@ -54,10 +60,11 @@
    - 被确认的假设 → **移入「依据」表格**，来源写「项目经理确认（第 N 轮）」；
    - 被否定或修正的假设 → 按项目经理给出的口径**修订「实现步骤」与「改动文件白名单」**；
    - 项目经理没有回应的假设 → 保留在「假设」中，再次 `@项目经理` 追问。
-3. 重新执行 `apm sync-document` 同步计划。
-4. 回复消息：逐条说明每个假设的处理结果（确认采纳 / 按口径修订了什么），全部解决则声明「假设已清零，可进入测试要点编写」。
+3. **后端**：假设修订涉及接口口径时，同步更新 `docs/API.md`。
+4. 重新执行 `apm sync-document` 同步计划与 API 文档。
+5. 回复消息：逐条说明每个假设的处理结果（确认采纳 / 按口径修订了什么），全部解决则声明「假设已清零，可进入测试要点编写」。
 
-**禁止**跳过回填直接开发：澄清结论必须落进计划文档，后续开发与 diff 评审都只认计划文档，不认聊天记录。
+**禁止**跳过回填直接开发：澄清结论必须落进计划文档（接口口径落进 `API.md`），后续开发与 diff 评审都只认文档，不认聊天记录。
 
 ---
 
@@ -65,8 +72,8 @@
 
 - 篇幅 **40 ～ 100 行**，宁可少写；不要伪代码、不要大段 SQL（完整语句写入 `docs/SQL.md`，由后端开发阶段产出）。
 - 用产品语言描述行为，文件路径只出现在「改动文件白名单」。
-- 前后端可同轮并行编写计划，不互相阻塞。
+- 前后端可同轮并行编写计划；前端接口部分依赖 `API.md`，后端须先或同步产出。
 
 ## 何时使用
 
-协作流程阶段 1（实现计划）；或用户要求写 `BACKEND-PLAN.md` / `FRONTEND-PLAN.md`。
+协作流程阶段 1（实现计划）；或用户要求写 `BACKEND-PLAN.md` / `FRONTEND-PLAN.md` / `API.md`。

package/template/skills/apm-write-plan/api-template.md

@@ -0,0 +1,35 @@
+# API.md 模板
+
+给前端联调用。实现步骤见 `BACKEND-PLAN.md`；本文只写契约，篇幅尽量克制。
+
+```markdown
+# <功能名称> — 接口
+
+## 背景
+
+<1 ～ 2 句：本次新增/变更/复用哪些接口>
+
+## <接口名称>（新增）
+
+- **GET** `/实际/path`
+- **用途**：…
+- **参数**：`pageNo`、`pageSize`（可选，默认 …）；`xxx`（何时传、何时不传）
+- **成功**：`result` 结构简述 + 简短 JSON 示例
+- **失败**：格式非法 → `message` 示例；无数据 → 空列表算成功
+
+## <接口名称>（现网，不变）
+
+- **GET** `/实际/path/{id}`
+- **用途**：…
+- **前端关注字段**：`fieldA` → 模板 xxx
+
+## 联调说明
+
+1. 首屏：只传 …
+2. 筛选：…
+3. 选中后：必须先调详情，禁止 …
+```
+
+## 不要写
+
+SQL、Java 类路径、Service 实现、后端验收清单。

package/template/skills/apm-write-plan/plan-template.md

@@ -1,10 +1,12 @@
 # 计划文档模板
 
-> 后端写 `docs/BACKEND-PLAN.md`，前端写 `docs/FRONTEND-PLAN.md`。
-> 「API 契约」章节仅后端需要；「期望接口」小节仅前端在后端契约未就绪时需要。
+> 后端写 `docs/BACKEND-PLAN.md` + `docs/API.md`（两份文档禁止合并）。
+> 前端写 `docs/FRONTEND-PLAN.md`；接口细节只读 `docs/API.md`，禁止在计划中重复抄写。
+
+## 后端计划（BACKEND-PLAN.md）
 
 ```markdown
-# <需求名> · <前端|后端>实现计划
+# <需求名> · 后端实现计划
 
 ## 1. 需求理解
 
@@ -33,35 +35,61 @@
 2. 第二步做什么
 3. ...（通常 3 ～ 6 步，不写代码细节）
 
-> **后端**：若涉及表结构或数据变更，在步骤中注明「开发须产出 `docs/SQL.md`」，SQL 语句不写在本计划内。
+> 若涉及表结构或数据变更，在步骤中注明「开发须产出 `docs/SQL.md`」，SQL 语句不写在本计划内。
+> 若涉及接口变更，在步骤中注明「须同步产出 `docs/API.md`」，接口参数表不写在本计划内。
 
 ## 4. 改动文件白名单
 
 > 开发只允许改这些文件；diff 评审会逐一对账，越界会被打回。
 > 开发中确需新增，先更新本清单并在群里说明原因。
 
-- `src/views/inspection/InspectionProjectForm.vue` — 新增「是否加分」单选与互斥逻辑
-- `src/api/inspection.ts` — 新增字段透传
+- `src/.../InspectionProjectController.java` — 新增保存入参校验
+- `src/.../InspectionProjectService.java` — 互斥逻辑
 - ...
+```
+
+## 前端计划（FRONTEND-PLAN.md）
+
+> 写计划前必须先 **Read** `docs/API.md`；不存在则退出并 `@后端`，禁止自行编造接口或写「期望接口」。
+
+```markdown
+# <需求名> · 前端实现计划
 
-## 5. API 契约（仅后端；前端开发以此为准）
+## 1. 需求理解
 
-### 5.1 <接口名>
+用 3 ～ 5 行复述本端要做什么（产品语言），不复制需求原文。
 
-- Path：`POST /inspection/project/save`
-- 新增入参：
+## 2. 依据与假设
 
-| 字段         | 类型   | 必填 | 说明                             |
-| ------------ | ------ | ---- | -------------------------------- |
-| isProjectAdd | string | 否   | "1"=加分项；与 isProjectDed 互斥 |
+### 依据（口径 + 来源）
 
-- 响应示例：
+| #   | 口径                           | 来源            |
+| --- | ------------------------------ | --------------- |
+| 1   | 「是否加分」与「是否扣分」互斥 | 需求原文第 1 条 |
+| 2   | 加分项不汇总进分类分值         | 需求原文第 2 条 |
 
-  { "success": true, "result": { "id": "xxx" } }
+### 假设（待项目经理确认，确认前不开发）
 
-- 错误码：互斥冲突返回 `success=false, message="加分与扣分不可同时勾选"`
+- [ ] A1：xxx（为什么需要确认）
+
+> 无假设时写「无，口径均有依据」。
+
+## 3. 实现步骤
+
+1. 第一步做什么（对应哪条口径）
+2. 第二步做什么
+3. 对接 `API.md` 中的某某接口（只写调用时机，不复制参数表）
+4. ...
+
+## 4. 改动文件白名单
+
+- `src/views/inspection/InspectionProjectForm.vue` — 新增「是否加分」单选与互斥逻辑
+- `src/api/inspection.ts` — 新增字段透传
+- ...
 
-## 6. 期望接口（仅前端，后端契约未就绪时填写）
+## 5. 接口对接要点（引用 API.md，禁止复制）
 
-- 期望 `查询分类详情` 返回 `classScore` 字段，由后端确认。
+- 列表：<何时请求、首屏传什么>（见 `API.md` § xxx）
+- 详情：<选中后怎么走>（见 `API.md` § xxx）
+- 注意：<禁止用列表数据代替详情等>
 ```