ai-project-manage-cli 6.0.39 → 6.0.41

package/dist/index.js

@@ -1417,7 +1417,7 @@ ${stack}`
 // src/commands/connect/cursor-agent.ts
 import { Agent, CursorAgentError } from "@cursor/sdk";
 import { setMaxListeners as setMaxListeners2 } from "node:events";
-import { resolve as resolve3 } from "path";
+import { resolve as resolve4 } from "path";
 
 // src/session-utils.ts
 var EventSession = class {
@@ -1577,6 +1577,58 @@ ${JSON.stringify(event, null, 2)}
 \`\`\``;
 }
 
+// src/commands/connect/agent-session-registry.ts
+import { existsSync as existsSync8, mkdirSync as mkdirSync5, readFileSync as readFileSync7, writeFileSync as writeFileSync7 } from "node:fs";
+import { dirname as dirname4, resolve as resolve3 } from "node:path";
+function registryPath(workdir, sessionId) {
+  return resolve3(workdir, ".apm", "sessions", sessionId, "cursor-agents.json");
+}
+function readRegistry(path10) {
+  if (!existsSync8(path10)) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(readFileSync7(path10, "utf8"));
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      const result = {};
+      for (const [key, value] of Object.entries(
+        parsed
+      )) {
+        if (typeof value === "string" && value.trim()) {
+          result[key] = value.trim();
+        }
+      }
+      return result;
+    }
+  } catch {
+  }
+  return {};
+}
+function writeRegistry(path10, registry) {
+  mkdirSync5(dirname4(path10), { recursive: true });
+  writeFileSync7(path10, `${JSON.stringify(registry, null, 2)}
+`, "utf8");
+}
+function loadSessionAgentId(workdir, sessionId, user) {
+  const registry = readRegistry(registryPath(workdir, sessionId));
+  return registry[user];
+}
+function saveSessionAgentId(workdir, sessionId, user, agentId) {
+  const path10 = registryPath(workdir, sessionId);
+  const registry = readRegistry(path10);
+  registry[user] = agentId;
+  writeRegistry(path10, registry);
+}
+function clearSessionAgentId(workdir, sessionId, user) {
+  const path10 = registryPath(workdir, sessionId);
+  const registry = readRegistry(path10);
+  if (!(user in registry)) {
+    return;
+  }
+  delete registry[user];
+  writeRegistry(path10, registry);
+}
+
 // src/commands/connect/cursor-message-log.ts
 var CURSOR_MESSAGE_LOG_SYNC_INTERVAL_MS = 2e3;
 function createThrottledCursorMessageLogSync(cfg, ctx, onError) {
@@ -1672,6 +1724,37 @@ function formatCursorRunFailure(runId, options) {
   }
   return `Cursor run \u5931\u8D25: ${runId} \u2014 ${details.join("\uFF1B")}`;
 }
+async function obtainAgent(ctx) {
+  const agentOptions = {
+    apiKey: ctx.apiKey,
+    model: { id: ctx.model || "default" },
+    local: {
+      cwd: ctx.cwd,
+      settingSources: []
+    }
+  };
+  const savedAgentId = ctx.user ? loadSessionAgentId(ctx.workdir, ctx.sessionId, ctx.user) : void 0;
+  if (savedAgentId) {
+    try {
+      const agent2 = await Agent.resume(savedAgentId, agentOptions);
+      console.log(
+        `[apm] \u590D\u7528\u4F1A\u8BDD Agent user=${ctx.user} agentId=${savedAgentId}`
+      );
+      return { agent: agent2, resumed: true };
+    } catch (err) {
+      console.warn(
+        `[apm] \u590D\u7528 Agent \u5931\u8D25\uFF08agentId=${savedAgentId}\uFF09\uFF0C\u56DE\u9000\u4E3A\u65B0\u5EFA:`,
+        err instanceof Error ? err.message : err
+      );
+      clearSessionAgentId(ctx.workdir, ctx.sessionId, ctx.user);
+    }
+  }
+  const agent = await Agent.create(agentOptions);
+  if (ctx.user) {
+    saveSessionAgentId(ctx.workdir, ctx.sessionId, ctx.user, agent.agentId);
+  }
+  return { agent, resumed: false };
+}
 async function runCursorAgent(cfg, ctx, options) {
   const signal = options?.signal;
   logAbortSignalStats(signal, "runCursorAgent:start");
@@ -1682,18 +1765,18 @@ async function runCursorAgent(cfg, ctx, options) {
   if (!apiKey) {
     throw new Error("\u7F3A\u5C11 apiKey\uFF0C\u65E0\u6CD5\u8C03\u7528 Cursor SDK");
   }
-  const cwd = resolve3(ctx.workdir);
+  const cwd = resolve4(ctx.workdir);
   const prompt = ctx.prompt;
   console.log(
     `[apm] Cursor Agent \u5F00\u59CB messageId=${ctx.messageId} sessionId=${ctx.sessionId} cwd=${cwd}`
   );
-  const agent = await Agent.create({
+  const { agent, resumed } = await obtainAgent({
     apiKey,
-    model: { id: ctx.model || "default" },
-    local: {
-      cwd,
-      settingSources: []
-    }
+    model: ctx.model,
+    cwd,
+    workdir: ctx.workdir,
+    sessionId: ctx.sessionId,
+    user: ctx.user
   });
   const eventSession = new EventSession(prompt);
   const remoteLogCtx = logCtx(ctx, agent.agentId);
@@ -1745,6 +1828,9 @@ async function runCursorAgent(cfg, ctx, options) {
         resultText: result.result
       });
       console.error(`[apm] ${failureMessage}`);
+      if (resumed) {
+        clearSessionAgentId(ctx.workdir, ctx.sessionId, ctx.user);
+      }
       throw new Error(failureMessage);
     }
     if (result.status === "cancelled") {
@@ -1753,6 +1839,9 @@ async function runCursorAgent(cfg, ctx, options) {
     console.log(`[apm] Cursor Agent \u5B8C\u6210 messageId=${ctx.messageId}`);
   } catch (err) {
     if (err instanceof CursorAgentError) {
+      if (resumed) {
+        clearSessionAgentId(ctx.workdir, ctx.sessionId, ctx.user);
+      }
       throw new Error(
         `Cursor \u542F\u52A8\u5931\u8D25: ${err.message}${err.isRetryable ? "\uFF08\u53EF\u91CD\u8BD5\uFF09" : ""}`
       );
@@ -1797,10 +1886,10 @@ function createRunSlotPool(maxConcurrent = DEFAULT_MAX_CONCURRENT) {
       active += 1;
       return Promise.resolve();
     }
-    return new Promise((resolve5) => {
+    return new Promise((resolve6) => {
       waiters.push(() => {
         active += 1;
-        resolve5();
+        resolve6();
       });
     });
   };
@@ -1893,7 +1982,8 @@ async function handleInboundMessage(cfg, msg, signal, ctx) {
           prompt: msg.content,
           model: msg.model,
           apiKey: msg.apiKey,
-          workdir: msg.workdir
+          workdir: msg.workdir,
+          user: msg.user
         },
         { signal }
       )
@@ -1967,7 +2057,7 @@ async function runConnect(options) {
   }
   const url = buildAgentWsUrl(cfg.baseUrl, resolveApiKey(cfg));
   console.log(`[apm] \u8FDE\u63A5 ${cfg.baseUrl} \u2026`);
-  await new Promise((resolve5, reject) => {
+  await new Promise((resolve6, reject) => {
     const ws = new WebSocket(url);
     let stopHeartbeat;
     let shuttingDown = false;
@@ -1996,7 +2086,7 @@ async function runConnect(options) {
         ]);
       } catch {
       }
-      resolve5();
+      resolve6();
       process.exit(code);
     };
     ws.on("open", () => {
@@ -2083,19 +2173,19 @@ async function runConnect(options) {
 import path5 from "node:path";
 
 // src/commands/deploy/internal/apm-config.ts
-import { existsSync as existsSync8, readFileSync as readFileSync7 } from "node:fs";
-import { resolve as resolve4 } from "node:path";
+import { existsSync as existsSync9, readFileSync as readFileSync8 } from "node:fs";
+import { resolve as resolve5 } from "node:path";
 function loadApmConfig(options) {
-  const p = resolve4(
+  const p = resolve5(
     process.cwd(),
-    options?.configPath ?? resolve4(workspaceApmDir(), "apm.config.json")
+    options?.configPath ?? resolve5(workspaceApmDir(), "apm.config.json")
   );
-  if (!existsSync8(p)) {
+  if (!existsSync9(p)) {
     console.error(`\u672A\u627E\u5230\u914D\u7F6E\u6587\u4EF6\uFF1A${p}`);
     process.exit(1);
   }
   try {
-    const raw = readFileSync7(p, "utf8");
+    const raw = readFileSync8(p, "utf8");
     return JSON.parse(raw);
   } catch (e) {
     console.error(`\u65E0\u6CD5\u89E3\u6790 apm.config.json\uFF1A${p}`, e);
@@ -2217,7 +2307,7 @@ import path4 from "node:path";
 import Docker from "dockerode";
 
 // src/commands/deploy/internal/backend-deploy/dockerode-client/connection-options.ts
-import { existsSync as existsSync9, readFileSync as readFileSync8 } from "node:fs";
+import { existsSync as existsSync10, readFileSync as readFileSync9 } from "node:fs";
 import path from "node:path";
 function asOptionalTlsBuffer(value) {
   if (typeof value !== "string") {
@@ -2229,8 +2319,8 @@ function asOptionalTlsBuffer(value) {
   if (normalized === "") {
     return void 0;
   }
-  if (existsSync9(normalized)) {
-    return readFileSync8(normalized);
+  if (existsSync10(normalized)) {
+    return readFileSync9(normalized);
   }
   const looksLikePath = /[\\/]/.test(normalized) || normalized.endsWith(".pem");
   if (looksLikePath) {
@@ -2355,17 +2445,17 @@ var DockerodeClient = class {
     await this.client.getImage(image).remove({ force: true });
   }
   async pullImage(image, auth) {
-    const stream = await new Promise((resolve5, reject) => {
+    const stream = await new Promise((resolve6, reject) => {
       const pullOptions = auth ? { authconfig: auth } : void 0;
       this.client.pull(image, pullOptions, (err, output) => {
         if (err || !output) {
           reject(err ?? new Error("docker pull \u8FD4\u56DE\u7A7A\u8F93\u51FA"));
           return;
         }
-        resolve5(output);
+        resolve6(output);
       });
     });
-    await new Promise((resolve5, reject) => {
+    await new Promise((resolve6, reject) => {
       this.client.modem.followProgress(
         stream,
         (err) => {
@@ -2373,7 +2463,7 @@ var DockerodeClient = class {
             reject(err);
             return;
           }
-          resolve5();
+          resolve6();
         },
         () => void 0
       );
@@ -2440,7 +2530,7 @@ var DockerodeClient = class {
 var createDockerodeClient = (config) => new DockerodeClient(config);
 
 // src/commands/deploy/internal/backend-deploy/dockerode-client/env.ts
-import { existsSync as existsSync10, readFileSync as readFileSync9, statSync as statSync4 } from "node:fs";
+import { existsSync as existsSync11, readFileSync as readFileSync10, statSync as statSync4 } from "node:fs";
 import path2 from "node:path";
 function stripSurroundingQuotes(value) {
   const t = value.trim();
@@ -2457,10 +2547,10 @@ function loadEnvFromFile(envFilePath) {
     return {};
   }
   const targetPath = path2.resolve(envFilePath);
-  if (!existsSync10(targetPath) || !statSync4(targetPath).isFile()) {
+  if (!existsSync11(targetPath) || !statSync4(targetPath).isFile()) {
     return {};
   }
-  const raw = readFileSync9(targetPath, "utf-8");
+  const raw = readFileSync10(targetPath, "utf-8");
   const result = {};
   for (const line of raw.split(/\r?\n/)) {
     const normalized = line.trim();
@@ -2631,12 +2721,12 @@ function dockerPushImage(params, cwd) {
 }
 
 // src/commands/deploy/internal/backend-deploy/resolve-dockerfile.ts
-import { existsSync as existsSync11 } from "node:fs";
+import { existsSync as existsSync12 } 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 (!existsSync11(dockerfilePath)) {
+  if (!existsSync12(dockerfilePath)) {
     throw new Error(`Dockerfile \u4E0D\u5B58\u5728\uFF1A${dockerfilePath}`);
   }
   Logger.info("\u2713 Dockerfile \u5B58\u5728");
@@ -2864,14 +2954,14 @@ var MinioClient = class {
   async deleteObjectsByPrefix(bucket, prefix) {
     const objectsStream = this.inner.listObjectsV2(bucket, prefix, true);
     const keys = [];
-    await new Promise((resolve5, reject) => {
+    await new Promise((resolve6, reject) => {
       objectsStream.on("data", (obj) => {
         if (obj.name) {
           keys.push(obj.name);
         }
       });
       objectsStream.on("error", reject);
-      objectsStream.on("end", resolve5);
+      objectsStream.on("end", resolve6);
     });
     const chunkSize = 500;
     for (let i = 0; i < keys.length; i += chunkSize) {
@@ -3109,7 +3199,7 @@ async function ensureRemoteDir(sftp, dir) {
   }
 }
 function execCommand(client, command) {
-  return new Promise((resolve5, reject) => {
+  return new Promise((resolve6, reject) => {
     client.exec(command, (err, stream) => {
       if (err) return reject(err);
       let stdout = "";
@@ -3119,7 +3209,7 @@ function execCommand(client, command) {
           reject(new Error(`\u8FDC\u7A0B\u547D\u4EE4\u5931\u8D25 (${code}): ${stderr || stdout}`));
           return;
         }
-        resolve5(stdout);
+        resolve6(stdout);
       }).on("data", (data) => {
         stdout += data.toString();
       });

package/package.json

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

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

@@ -1,9 +1,12 @@
+# apm-dev：按计划开发并发布测试环境
+
 ## 工作流程
 
-### 步骤 1: 获取当前版本 PRD 的内容以及协作内容
+### 步骤 1: 获取实现计划与协作内容
 
-1. 用 **Read** 工具阅读 `.apm/sessions/<会话ID>/docs/PRD.md`，如果不存在则开发失败，退出流程。
-2. 按需阅读 `.apm/sessions/<会话ID>/docs` 下其他文档：前端对照 `FRONTEND.md` + `API.md`，后端对照 `BACKEND.md` + `API.md`
+1. 用 **Read** 工具阅读本端计划：前端读 `.apm/sessions/<会话ID>/docs/FRONTEND-PLAN.md`，后端读 `docs/BACKEND-PLAN.md`；计划不存在则退出流程并回复说明（兼容旧流程：若存在 `PRD.md` + `FRONTEND.md` / `BACKEND.md` + `API.md`，按旧文档执行）。
+2. 前端涉及接口对接时，以后端计划中的「API 契约」章节为准，**不等后端部署完成**；契约没写清的字段 `@后端` 确认，禁止自行猜测。
+3. 计划「假设」章节存在未确认项时，先 `@项目经理` 确认，确认前不开始开发。
 
 ### 步骤 2: 明确开发模式
 
@@ -11,33 +14,46 @@
 
 - 影响范围局部：少量文件或单一层次（例如仅前端组件、或仅一个后端模块小改）。
 - 无新表结构/大规模迁移/权限模型变更。
-- PRD 验收点清晰且数量少（经验上 **≤3** 条独立验收维度）。
+- 计划实现步骤清晰且数量少（经验上 **≤3** 条独立步骤）。
 - 不需要跨多服务的架构裁定即可开工。
 
 **Spec 开发**：（命中任一条即可）：
 
 - 前后端联动、多包改造或新公共抽象。
 - 新数据模型、迁移、或安全/审计/权限相关。
-- PRD 范围大、条款多，或存在明显「待确认/多方案」需先规划。
+- 计划范围大、条款多，或存在明显「待确认/多方案」需先规划。
 - 评估认为不先产出 **proposal / design / specs / tasks** 不宜直接编码。
 
 ### 步骤 3: 如果前一步判定为 **Quick 开发** 才（在子 Agent 中）执行本步骤，否则执行下一步：
 
-- 父 Agent 已通过 **Read** 掌握 `PRD.md`；若启动新子 Agent，在委派提示中写明会话 ID、消息 ID、工作项路径、以及「实现须严格对照 PRD，改动范围最小化；完成后若有代码改动须单独 `git commit`」。
+- 父 Agent 已通过 **Read** 掌握本端计划；若启动新子 Agent，在委派提示中写明会话 ID、消息 ID、工作项路径、以及「实现须严格对照计划，**只允许改动计划『改动文件白名单』中列出的文件**；完成后若有代码改动须单独 `git commit`」。
 - 使用 **Task** 工具，`subagent_type: generalPurpose`，**readonly: false**，委派子 Agent：
-  - 按需 **Read** `.apm/sessions/<会话ID>/docs/PRD.md`
-  - 按 PRD 直接改代码；遵守本仓库构建与依赖约定（AGENTS.md）。
-  - **Git**：实现与自洽验收通过后，若有代码改动，**立即 `git add` + `git commit` 一次**（Quick 通常为单次交付，**一次实现 = 一个 commit**；勿拆成无意义碎 commit）。提交信息建议包含 `seesionId`（可从 `session.yaml` 或 PRD 获取）与 PRD 摘要或验收点简述。
-  - 完成后在返回中说明：改了哪些路径、如何对照验收、是否通过本地可执行的检查（若子 Agent 跑了 `rushx build` / 测试等则写明结果）；若有 commit，写明 **short-sha** 与 **subject**，无代码改动则注明跳过 commit。
+  - 按需 **Read** 本端计划文档。
+  - 按计划直接改代码；遵守本仓库构建与依赖约定（AGENTS.md）。
+  - **白名单约束**：只改计划白名单内的文件。开发中确需新增文件或改动白名单外文件，先更新计划文档的白名单（写明原因）并同步，再动手；**禁止悄悄越界**。
+  - **Git**：实现与自洽验收通过后，若有代码改动，**立即 `git add` + `git commit` 一次**（Quick 通常为单次交付，**一次实现 = 一个 commit**；勿拆成无意义碎 commit）。提交信息建议包含 `sessionId`（可从 `session.yaml` 获取）与需求摘要。
+  - 完成后在返回中说明：改了哪些路径、与白名单的对账结果（逐文件列出）、是否通过本地可执行的检查（若子 Agent 跑了构建/测试则写明结果）；若有 commit，写明 **short-sha** 与 **subject**，无代码改动则注明跳过 commit。
 
 ### 步骤 4: 如果前一步判定为 **Spec 开发** 才（在子 Agent 中）执行本步骤，否则执行下一步：
 
 1. 父 Agent **Read** `.apm/skills/apm-propose/SKILL.md` 和 `.apm/skills/apm-apply-change/SKILL.md`
 2. **子 Agent A（规划）**：Task `generalPurpose`，提示其自行 **Read** `.apm/skills/apm-propose/SKILL.md` 并完整遵循：在 `plans/` 下生成 **proposal、design、specs、tasks** 等工件。
-3. **子 Agent B（实现）**：待 A 成功落盘后，再 Task `generalPurpose`，提示其自行 **Read** `.apm/skills/apm-apply-change/SKILL.md` 并完整遵循：按 **`plans/tasks.md`** 驱动实现与勾选；遵守该技能中的停止条件与 commit 约定。
+3. **子 Agent B（实现）**：待 A 成功落盘后，再 Task `generalPurpose`，提示其自行 **Read** `.apm/skills/apm-apply-change/SKILL.md` 并完整遵循：按 **`plans/tasks.md`** 驱动实现与勾选；遵守该技能中的停止条件与 commit 约定；同样遵守计划「改动文件白名单」。
 4. 若 **apm-propose** 未产出可用 **`plans/tasks.md`**，不得强行进入 **apm-apply-change**；表格中标记阻塞原因。
 
 ### 步骤 5: 提交并 push 代码，保证工作区干净
 
 - Quick / Spec 子 Agent 完成且本地已有 commit 时，父 Agent **立即 `git push`**（当前分支首次 push 用 `git push -u origin HEAD`）。
 - 无本地 commit、无远程或未配置 upstream 时说明原因，勿强行 push。
+
+### 步骤 6: 构建验证与发布测试环境（完成定义）
+
+开发完成的定义是以下三项**全部满足**，缺一不可：
+
+1. **构建通过**：执行本仓库的构建/检查命令（见 AGENTS.md 或部署文档），失败必须修复后重试。
+2. **发布测试环境**：**Read** `.apm/skills/apm-deploy/SKILL.md` 并按其流程部署；部署涉及 SQL 变更时，在回复中明确写出待执行的 SQL 文件名。
+3. **白名单对账**：在回复中逐文件列出本次改动与计划白名单的对应关系。
+
+**注意：不做联调。** 前后端各自按 API 契约交付，接口对不上属于契约或实现问题，由 diff 评审与人工验收暴露后打回修复；禁止自行发起「联调」「接口实测」类的开放式动作。
+
+完成后 `apm append-message` 回复：改动概述 + 白名单对账 + 构建结果 + 测试环境地址，并 `@` 评审角色进行 diff 评审。

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

@@ -0,0 +1,50 @@
+# apm-diff-review：开发完成后的代码改动评审
+
+## 适用范围
+
+开发完成、发布测试环境之后，由评审角色（可以是另一端工程师或专职评审智能体）检查 git 改动是否「只做了该做的事」。这是防止 AI 乱改代码的机器门禁：**通过才交人验收，不通过打回开发**。
+
+评审对象是 **diff**，不是整个代码库；禁止借评审之机重构或顺手改代码。**本技能全程只读，不允许写任何代码。**
+
+---
+
+## 工作流程
+
+### 步骤 1：定位本次任务的改动
+
+1. **Read** `.apm/sessions/<会话ID>/docs/` 下的 `BACKEND-PLAN.md` / `FRONTEND-PLAN.md`，拿到「改动文件白名单」。
+2. 在工作目录执行 `git log --oneline -20`，找到本任务相关的 commit（提交信息中含会话 ID 或需求关键词）。
+3. `git diff <基线>..HEAD --stat` 与 `git diff <基线>..HEAD` 查看完整改动。
+
+### 步骤 2：三项检查
+
+| 检查项 | 判定 |
+|--------|------|
+| **白名单对账** | diff 中出现白名单之外的文件，且计划未更新说明 → **不通过** |
+| **需求相关性** | 存在与本需求无关的改动（顺手重构、改格式、动了无关逻辑）→ **不通过** |
+| **计划落实** | 计划「实现步骤」中的关键点在 diff 中找不到对应实现 → **不通过** |
+
+注意事项：
+
+- 锚定计划和需求原文做判断，不要凭个人偏好挑剔代码风格。
+- 改动是否「无关」拿不准时，倾向放过，但在回复中提示验收人留意。
+
+### 步骤 3：输出结论
+
+**通过**：`apm append-message` 回复评审结论，并 `@项目经理` 交人验收，回复中必须包含：
+
+1. 「diff 评审通过」+ 一句话改动概述；
+2. 测试环境地址（从开发的回复或工作日志中获取）；
+3. 提示按 `CHECKLIST.md` 逐条验收。
+
+**不通过**：`apm append-message` 输出问题清单（每条注明文件 + 问题 + 依据哪条计划/需求），`@` 对应工程师打回修改。**禁止自己动手改。**
+
+---
+
+## 迭代上限
+
+同一任务的 diff 评审**最多打回 3 次**。第 3 次仍不通过时，不再打回，改为 `@项目经理` 说明僵持原因，由人决策（人工修复 / 调整计划 / 放弃本次改动）。
+
+## 何时使用
+
+协作流程阶段 4（diff 评审）；或用户要求评审代码改动。

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

@@ -0,0 +1,42 @@
+# apm-write-checklist：编写人工回归要点清单
+
+## 适用范围
+
+测试智能体在前后端计划（`BACKEND-PLAN.md` / `FRONTEND-PLAN.md`）就绪后，编写 `docs/CHECKLIST.md`。
+
+这份清单是**给人做回归验收用的**，不是自动化测试用例：把需求的关键点过一遍即可，一条一行，人拿着它在测试环境点一遍就能判断需求做没做对。
+
+---
+
+## 工作流程
+
+### 步骤 1：读需求与计划
+
+1. **Read** `.apm/sessions/<会话ID>/TASK.md` —— **以需求原文为准出题**，不要只从计划推导（计划理解错了，照着计划出的题也会跟着错）。
+2. **Read** `docs/BACKEND-PLAN.md`、`docs/FRONTEND-PLAN.md`（存在哪份读哪份）。
+
+### 步骤 2：交叉校验（这一步是打回机制）
+
+逐条对照需求原文与计划：
+
+- **计划与需求矛盾、或需求关键点在计划中没有覆盖**：不要写清单，先 `apm append-message` 指出问题并 `@` 对应工程师打回，等计划修订后再写。
+- **计划中的「假设」尚未被项目经理确认**：在回复中提醒，但可以先写清单（清单按需求原文出）。
+- 计划覆盖完整：进入步骤 3。
+
+### 步骤 3：按模板写清单
+
+**Read** `.apm/skills/apm-write-checklist/checklist-template.md`，按模板 **Write** `docs/CHECKLIST.md`。
+
+要求：
+
+- **5～15 条**，关键点级别，不写入参出参细节、不写接口路径。
+- 每条 = 在哪个页面、做什么操作、预期看到什么。
+- 必须覆盖：需求的每个功能点至少 1 条、关键互斥/边界规则至少 1 条、对既有功能的回归至少 1 条（确认没改坏原有逻辑）。
+
+### 步骤 4：同步并回复
+
+执行 `apm sync-document <会话ID> --file=CHECKLIST.md`，回复消息说明清单已就绪，可进入开发。
+
+## 何时使用
+
+协作流程阶段 2（测试要点）；或用户要求写 `CHECKLIST.md`。

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

@@ -0,0 +1,34 @@
+# 回归要点清单模板
+
+```markdown
+# <需求名> · 人工回归要点
+
+> 验收人按编号逐条验证；某条不通过时，直接在群里回复「第 N 条不通过，实际现象：xxx」即可。
+
+## 新功能验证
+
+| # | 页面 / 位置 | 操作 | 预期 |
+|---|-------------|------|------|
+| 1 | 检查项目维护 → 编辑 | 勾选「是否加分」 | 「是否扣分」自动取消，两者不可同时勾选 |
+| 2 | 检查项目维护 → 保存 | 同时勾选加分与扣分后保存 | 保存被拦截并提示互斥 |
+| 3 | 检查模板维护 → 新增 | 选择检查分类 | 「检查分类分值」自动带入，加分项不计入汇总 |
+
+## 边界与兼容
+
+| # | 页面 / 位置 | 操作 | 预期 |
+|---|-------------|------|------|
+| 4 | 检查录入 | 对加分项录入加分并保存 | 总分正确增加且不设上限，重新打开回显一致 |
+| 5 | 检查录入 | 打开改造前创建的历史单据 | 正常显示，原扣分逻辑不变 |
+
+## 既有功能回归
+
+| # | 页面 / 位置 | 操作 | 预期 |
+|---|-------------|------|------|
+| 6 | 检查录入 | 普通扣分项的录入与保存 | 与改造前行为完全一致 |
+```
+
+写作要求：
+
+- 表格三列固定：位置、操作、预期；每条一行，禁止嵌套步骤。
+- 「预期」写人肉眼可判断的现象，不写「接口返回 200」这类机器口径。
+- 总数控制在 5～15 条，超出说明粒度太细，合并。

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

@@ -0,0 +1,57 @@
+# apm-write-plan：直接基于需求写实现计划
+
+## 适用范围
+
+前端 / 后端工程师在任务启动后**直接读原始需求写实现计划**，不经过 PRD。
+
+本技能合并了原 `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` |
+
+---
+
+## 工作流程
+
+### 步骤 1：判断本端是否需要参与
+
+**Read** `.apm/sessions/<会话ID>/TASK.md`（必要时结合群消息中项目经理的补充说明）。
+
+- **不涉及本端改动**：立即 `apm append-message` 回复「本需求与前端/后端无关，理由：xxx」（一句话说明理由），**流程到此结束，禁止写任何文档、禁止改任何代码**。
+- **涉及本端改动**：进入步骤 2。
+
+### 步骤 2：有限调研（必须遵守预算）
+
+1. **优先读现成结论**：先读 `docs/` 下已有的模块档案、历史工作日志、其他成员已同步的文档，能复用就不要重新调研。
+2. **再调研代码**：只看与需求直接相关的页面 / 接口 / 表。**调研预算：最多读 15 个代码文件**，禁止全库考古、禁止顺藤摸瓜阅读无关模块。
+3. **口径不清不要自己拍板**：调研中发现需求没写清的业务口径（例如字段含义、互斥规则、历史数据兼容），一律记入计划的「依据与假设」章节，禁止编造业务规则。
+
+### 步骤 3：按模板写计划
+
+**Read** `.apm/skills/apm-write-plan/plan-template.md`，按模板 **Write** 对应的计划文档。三个章节为硬性要求，缺一不可：
+
+1. **依据与假设**：每条关键口径标注来源（需求原文第几条 / 现有代码行为 / 已有文档）；标不出来源的就是「假设」，单独列出。
+2. **改动文件白名单**：本次允许改动的文件完整列表。后续开发与 diff 评审都以此为准，**开发时改了白名单之外的文件会被打回**。
+3. **后端专属——API 契约**：给前端看的接口定义（Path、参数、响应示例、错误码）。前端开发以契约为准，不等后端部署完成。
+
+### 步骤 4：同步文档并回复
+
+1. 执行 `apm sync-document <会话ID> --file=<文档名>`。
+2. 回复消息（遵守 `reply.md`）：
+   - **「假设」章节非空**：把假设逐条列进回复内容，`@项目经理` 请其确认；明确说「以上假设确认前不开始开发」。
+   - **无假设**：回复计划已就绪，可进入测试要点编写。
+   - 前端计划依赖的接口后端契约还没出：在计划「期望接口」小节写出前端期望的接口形态，回复时 `@后端` 对齐，不要空等。
+
+---
+
+## 写作要求
+
+- 篇幅 **40～100 行**，宁可少写；不要伪代码、不要大段 SQL。
+- 用产品语言描述行为，文件路径只出现在「改动文件白名单」。
+- 前后端可同轮并行编写计划，不互相阻塞。
+
+## 何时使用
+
+协作流程阶段 1（实现计划）；或用户要求写 `BACKEND-PLAN.md` / `FRONTEND-PLAN.md`。

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

@@ -0,0 +1,65 @@
+# 计划文档模板
+
+> 后端写 `docs/BACKEND-PLAN.md`，前端写 `docs/FRONTEND-PLAN.md`。
+> 「API 契约」章节仅后端需要；「期望接口」小节仅前端在后端契约未就绪时需要。
+
+```markdown
+# <需求名> · <前端|后端>实现计划
+
+## 1. 需求理解
+
+用 3～5 行复述本端要做什么（产品语言），不复制需求原文。
+
+## 2. 依据与假设
+
+### 依据（口径 + 来源）
+
+| # | 口径 | 来源 |
+|---|------|------|
+| 1 | 「是否加分」与「是否扣分」互斥 | 需求原文第 1 条 |
+| 2 | 加分项不汇总进分类分值 | 需求原文第 2 条 |
+| 3 | 分值字段现状为 varchar | 代码现状：inspection_class 表 |
+
+### 假设（待项目经理确认，确认前不开发）
+
+- [ ] A1：xxx（为什么需要确认）
+- [ ] A2：xxx
+
+> 无假设时写「无，口径均有依据」。
+
+## 3. 实现步骤
+
+1. 第一步做什么（对应哪条口径）
+2. 第二步做什么
+3. ...（通常 3～6 步，不写代码细节）
+
+## 4. 改动文件白名单
+
+> 开发只允许改这些文件；diff 评审会逐一对账，越界会被打回。
+> 开发中确需新增，先更新本清单并在群里说明原因。
+
+- `src/views/inspection/InspectionProjectForm.vue` — 新增「是否加分」单选与互斥逻辑
+- `src/api/inspection.ts` — 新增字段透传
+- ...
+
+## 5. API 契约（仅后端；前端开发以此为准）
+
+### 5.1 <接口名>
+
+- Path：`POST /inspection/project/save`
+- 新增入参：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| isProjectAdd | string | 否 | "1"=加分项；与 isProjectDed 互斥 |
+
+- 响应示例：
+
+    { "success": true, "result": { "id": "xxx" } }
+
+- 错误码：互斥冲突返回 `success=false, message="加分与扣分不可同时勾选"`
+
+## 6. 期望接口（仅前端，后端契约未就绪时填写）
+
+- 期望 `查询分类详情` 返回 `classScore` 字段，由后端确认。
+```