ai-project-manage-cli 8.1.6 → 8.1.7

package/README.md

@@ -39,6 +39,8 @@ apm connect
 apm connect --server https://your-server.com
 ```
 
+启动前会检测 npm registry 上当前大版本的最新包；若落后则先 `npm install -g` 更新，再以新版本重新连接。跨大版本请手动执行 `apm update --major`。
+
 同一时刻仅允许一个 connect。
 
 `apm connect` 处理完 WebIDE 消息后，会将 `.apm/project/<项目ID>/` 下的项目文档变更推回平台。

package/dist/index.js

@@ -324,6 +324,14 @@ var requestConfig = {
       method: "PUT",
       path: "/cli/webide/plan"
     }),
+    webideUpsertChecklist: defineEndpoint({
+      method: "PUT",
+      path: "/cli/webide/checklist"
+    }),
+    webideGetChecklist: defineEndpoint({
+      method: "GET",
+      path: "/cli/webide/checklist"
+    }),
     webideReplaceTestCases: defineEndpoint({
       method: "PUT",
       path: "/cli/webide/test-cases"
@@ -512,6 +520,8 @@ async function runLogin(opts) {
 
 // src/commands/update.ts
 import { spawnSync } from "child_process";
+import { existsSync as existsSync2 } from "fs";
+import { join as join4 } from "path";
 
 // src/version.ts
 import { readFileSync as readFileSync2 } from "fs";
@@ -530,6 +540,7 @@ function readCliVersion() {
 }
 
 // src/commands/update.ts
+var APM_SKIP_SELF_UPDATE_ENV = "APM_SKIP_SELF_UPDATE";
 var useNpmShell = process.platform === "win32";
 function runNpm(args, options = {}) {
   return spawnSync(useNpmShell ? "npm.cmd" : "npm", args, {
@@ -622,10 +633,17 @@ function npmAvailable() {
   return !r.error && r.status === 0;
 }
 async function runUpdate(options = {}) {
+  if (process.env[APM_SKIP_SELF_UPDATE_ENV] === "1") {
+    return { didUpdate: false };
+  }
   const current = readCliVersion();
   const currentMajor = parseMajorVersion(current);
   const globalLatest = await fetchLatestPublishedVersion();
   const latestInMajor = options.allowMajorUpgrade ? null : await fetchLatestPublishedVersionInMajor(currentMajor);
+  if (options.quietIfCurrent && !options.allowMajorUpgrade && !latestInMajor && !globalLatest) {
+    console.warn(`[apm] \u65E0\u6CD5\u68C0\u6D4B\u6700\u65B0\u7248\u672C\uFF0C\u7EE7\u7EED\u4F7F\u7528\u5F53\u524D ${current}`);
+    return { didUpdate: false };
+  }
   const resolved = resolveUpdateTarget({
     current,
     allowMajorUpgrade: options.allowMajorUpgrade,
@@ -633,8 +651,10 @@ async function runUpdate(options = {}) {
     globalLatest
   });
   if (resolved.action === "skip") {
-    console.log(`[apm] \u5DF2\u662F\u6700\u65B0\u7248\u672C ${current}`);
-    return;
+    if (!options.quietIfCurrent) {
+      console.log(`[apm] \u5DF2\u662F\u6700\u65B0\u7248\u672C ${current}`);
+    }
+    return { didUpdate: false };
   }
   if (resolved.majorUpgradeAvailable) {
     console.log(
@@ -671,14 +691,57 @@ async function runUpdate(options = {}) {
   } else {
     console.log(`[apm] \u5DF2\u662F\u6700\u65B0\u7248\u672C ${current}`);
   }
+  return { didUpdate: expectedBump };
+}
+function resolveApmEntryPath(entryArg = process.argv[1]) {
+  const npmResult = runNpm(["root", "-g"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  if (npmResult.status === 0) {
+    const globalRoot = npmResult.stdout?.toString().trim();
+    if (globalRoot) {
+      const candidate = join4(globalRoot, CLI_PACKAGE_NAME, "dist", "index.js");
+      if (existsSync2(candidate)) {
+        return candidate;
+      }
+    }
+  }
+  const fromArgv = entryArg?.trim();
+  if (fromArgv && existsSync2(fromArgv)) {
+    return fromArgv;
+  }
+  if (fromArgv) {
+    return fromArgv;
+  }
+  console.error("[apm] \u65E0\u6CD5\u89E3\u6790 apm \u5165\u53E3\u8DEF\u5F84");
+  process.exit(1);
+}
+function reexecConnectAfterUpdate(options) {
+  console.log("[apm] \u66F4\u65B0\u5B8C\u6210\uFF0C\u6B63\u5728\u4EE5\u65B0\u7248\u672C\u91CD\u65B0\u8FDE\u63A5\u2026");
+  const apmScript = resolveApmEntryPath();
+  const args = [apmScript, "connect"];
+  const server = options.server?.trim();
+  if (server) {
+    args.push("--server", server);
+  }
+  const result = spawnSync(process.execPath, args, {
+    stdio: "inherit",
+    env: { ...process.env, [APM_SKIP_SELF_UPDATE_ENV]: "1" }
+  });
+  if (result.error) {
+    console.error("[apm] \u91CD\u542F connect \u5931\u8D25:", result.error.message);
+    process.exit(1);
+  }
+  process.exit(result.status ?? 0);
 }
 
 // src/commands/update-skills.ts
-import { existsSync as existsSync2, statSync as statSync2 } from "fs";
+import { existsSync as existsSync3, statSync as statSync2 } from "fs";
 async function syncWorkspaceSkills(workdir) {
   const apmDir = workspaceApmDir(workdir);
   const fsApmDir = toFsPath(apmDir);
-  if (!existsSync2(fsApmDir)) {
+  if (!existsSync3(fsApmDir)) {
     throw new Error("[apm] \u672A\u627E\u5230 .apm \u76EE\u5F55\uFF0C\u8BF7\u5148\u6267\u884C apm init");
   }
   const apmStat = statSync2(fsApmDir);
@@ -690,7 +753,7 @@ async function syncWorkspaceSkills(workdir) {
 }
 async function runUpdateSkills() {
   const apmDir = workspaceApmDir();
-  if (!existsSync2(apmDir)) {
+  if (!existsSync3(apmDir)) {
     console.error("[apm] \u672A\u627E\u5230 .apm \u76EE\u5F55\uFF0C\u8BF7\u5148\u6267\u884C apm init");
     process.exit(1);
   }
@@ -703,14 +766,14 @@ async function runUpdateSkills() {
 
 // src/utils/project-documents.ts
 import {
-  existsSync as existsSync3,
+  existsSync as existsSync4,
   readdirSync as readdirSync2,
   readFileSync as readFileSync3,
   rmSync,
   writeFileSync as writeFileSync2
 } from "fs";
 import { createHash } from "crypto";
-import { dirname as dirname3, join as join4, relative, sep } from "path";
+import { dirname as dirname3, join as join5, relative, sep } from "path";
 
 // src/utils/git.ts
 import { execFile as execFile2 } from "child_process";
@@ -784,11 +847,11 @@ function normalizeProjectIdForPath(projectId) {
 }
 function projectDocumentsDir(apmRoot, projectId) {
   const id = normalizeProjectIdForPath(projectId);
-  return join4(apmRoot ?? workspaceApmDir(), "project", id);
+  return join5(apmRoot ?? workspaceApmDir(), "project", id);
 }
 function projectDocumentLocalPath(apmRoot, projectId, documentPath) {
   const normalized = normalizeLocalDocumentPath(documentPath);
-  return join4(
+  return join5(
     projectDocumentsDir(apmRoot, projectId),
     ...normalized.split("/")
   );
@@ -808,11 +871,11 @@ function hashLocalFileContent(content) {
   return createHash("sha256").update(content, "utf8").digest("hex");
 }
 function readLocalManifest(apmRoot, projectId) {
-  const manifestPath = join4(
+  const manifestPath = join5(
     projectDocumentsDir(apmRoot, projectId),
     MANIFEST_FILE
   );
-  if (!existsSync3(manifestPath)) {
+  if (!existsSync4(manifestPath)) {
     return null;
   }
   try {
@@ -825,13 +888,13 @@ function readLocalManifest(apmRoot, projectId) {
 }
 function listLocalDocumentPaths(apmRoot, projectId) {
   const root = projectDocumentsDir(apmRoot, projectId);
-  if (!existsSync3(root)) {
+  if (!existsSync4(root)) {
     return [];
   }
   const paths = [];
   const walk = (dir) => {
     for (const entry of readdirSync2(dir, { withFileTypes: true })) {
-      const abs = join4(dir, entry.name);
+      const abs = join5(dir, entry.name);
       if (entry.isDirectory()) {
         walk(abs);
         continue;
@@ -960,13 +1023,13 @@ ${diagnostic ?? ""}`);
     const absPath = toFsPath(
       projectDocumentLocalPath(targetApmDir, projectId, path)
     );
-    if (existsSync3(absPath)) {
+    if (existsSync4(absPath)) {
       rmSync(absPath, { force: true });
       deleted += 1;
     }
   }
   writeFileSync2(
-    toFsPath(join4(docsDir, MANIFEST_FILE)),
+    toFsPath(join5(docsDir, MANIFEST_FILE)),
     `${JSON.stringify(remoteManifest, null, 2)}
 `,
     "utf8"
@@ -1284,7 +1347,7 @@ function handleCancelAction(payload, ctx) {
 }
 
 // src/commands/connect/core/worker/worker.ts
-import { dirname as dirname4, join as join5 } from "path";
+import { dirname as dirname4, join as join6 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { Worker } from "node:worker_threads";
 
@@ -1310,7 +1373,7 @@ function resolveWebIdeWorkerHeapMb(env = process.env, totalMemoryBytes = totalme
 }
 
 // src/commands/connect/core/worker/worker.ts
-var workerFile = join5(
+var workerFile = join6(
   dirname4(fileURLToPath3(import.meta.url)),
   "worker-script.js"
 );
@@ -1663,14 +1726,14 @@ function dispatchConnectAction(payload, ctx) {
 
 // src/commands/connect-lock.ts
 import {
-  existsSync as existsSync4,
+  existsSync as existsSync5,
   mkdirSync as mkdirSync3,
   readFileSync as readFileSync4,
   unlinkSync,
   writeFileSync as writeFileSync3
 } from "fs";
-import { join as join6 } from "path";
-var CONNECT_LOCK_PATH = join6(APM_CONFIG_DIR, "connect.lock");
+import { join as join7 } from "path";
+var CONNECT_LOCK_PATH = join7(APM_CONFIG_DIR, "connect.lock");
 function isProcessAlive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
   try {
@@ -1681,7 +1744,7 @@ function isProcessAlive(pid) {
   }
 }
 function readConnectLock() {
-  if (!existsSync4(CONNECT_LOCK_PATH)) return null;
+  if (!existsSync5(CONNECT_LOCK_PATH)) return null;
   try {
     const raw = readFileSync4(CONNECT_LOCK_PATH, "utf8");
     const parsed = JSON.parse(raw);
@@ -1847,6 +1910,10 @@ function resolveConnectServerOption(options) {
   return void 0;
 }
 async function runConnect(options) {
+  const { didUpdate } = await runUpdate({ quietIfCurrent: true });
+  if (didUpdate) {
+    reexecConnectAfterUpdate(options);
+  }
   const cfg = await ensureLoggedConfig();
   const serverOverride = resolveConnectServerOption(options);
   if (serverOverride) {
@@ -1973,7 +2040,7 @@ function buildProgram() {
     await runSyncProjectDocuments(opts);
   });
   program.command("connect").description(
-    "\u8FDE\u63A5\u5E73\u53F0 WebSocket\uFF08/ws/agent\uFF09\uFF0C\u7EF4\u6301\u5FC3\u8DF3\u5E76\u5904\u7406\u4E0B\u884C webide-message"
+    "\u8FDE\u63A5\u524D\u68C0\u6D4B\u5E76\u66F4\u65B0\u5230\u5F53\u524D\u5927\u7248\u672C\u6700\u65B0 CLI\uFF0C\u518D\u8FDE\u63A5\u5E73\u53F0 WebSocket\uFF08/ws/agent\uFF09"
   ).option("--server <url>", "API \u6839\u5730\u5740\uFF0C\u8986\u76D6 config \u4E2D\u7684 baseUrl").action(async (opts) => {
     await runConnect({ server: opts.server });
   });

package/dist/worker-script.js

@@ -72,6 +72,14 @@ var requestConfig = {
       method: "PUT",
       path: "/cli/webide/plan"
     }),
+    webideUpsertChecklist: defineEndpoint({
+      method: "PUT",
+      path: "/cli/webide/checklist"
+    }),
+    webideGetChecklist: defineEndpoint({
+      method: "GET",
+      path: "/cli/webide/checklist"
+    }),
     webideReplaceTestCases: defineEndpoint({
       method: "PUT",
       path: "/cli/webide/test-cases"
@@ -1499,7 +1507,7 @@ function createMergeWebIdePullRequestsTool(options) {
   const { webideMergePullRequests } = options;
   return {
     MergeWebIdePullRequests: {
-      description: "Merge all open pull requests for this WebIDE task. Call once with confirmedConflictFree=true. No baseline sync or review is required before calling.",
+      description: "Merge all open pull requests for this WebIDE task. During accept, call UpsertWebIdeChecklist first with the full acceptance checklist, then call this once with confirmedConflictFree=true. No baseline sync is required before merging.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1586,6 +1594,63 @@ function createUpsertWebIdePlanTool(options) {
     }
   };
 }
+function createUpsertWebIdeChecklistTool(options) {
+  const { webideUpsertChecklist } = options;
+  return {
+    UpsertWebIdeChecklist: {
+      description: "Persist or replace the acceptance checklist markdown for this WebIDE task. Call with the full checklist (what changed, which repos/files, how to verify) before merging PRs. Use during accept so humans can review later.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          content: {
+            type: "string",
+            description: "Full acceptance checklist in Markdown (Chinese): summary of code changes, scope by repo, key files, verification notes"
+          }
+        },
+        required: ["content"]
+      },
+      execute: async (args) => {
+        const content = asString(args.content);
+        if (!content) {
+          throw new Error("UpsertWebIdeChecklist \u7F3A\u5C11 content");
+        }
+        await webideUpsertChecklist({ content });
+        return JSON.stringify({ ok: true, chars: content.length }, null, 2);
+      }
+    }
+  };
+}
+function createGetWebIdeChecklistTool(options) {
+  const { boundTaskId, webideGetChecklist } = options;
+  return {
+    GetWebIdeChecklist: {
+      description: "Fetch the acceptance checklist markdown for a WebIDE task by taskId. Returns content=null if none has been written yet. Use when you need to read or revise an existing checklist.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          taskId: {
+            type: "string",
+            description: "WebIDE task id whose checklist to load"
+          }
+        },
+        required: ["taskId"]
+      },
+      execute: async (args) => {
+        const taskId = asString(args.taskId);
+        if (!taskId) {
+          throw new Error("GetWebIdeChecklist \u7F3A\u5C11 taskId");
+        }
+        if (taskId !== boundTaskId) {
+          throw new Error(
+            `GetWebIdeChecklist \u7684 taskId \u987B\u4E3A\u5F53\u524D\u4EFB\u52A1 ${boundTaskId}`
+          );
+        }
+        const result = await webideGetChecklist({ taskId });
+        return JSON.stringify(result, null, 2);
+      }
+    }
+  };
+}
 
 // src/commands/connect/tools/webide-test-case-tools.ts
 function asString2(value) {
@@ -1618,7 +1683,7 @@ function createUpsertWebIdeTestCasesTool(options) {
   const { webideReplaceTestCases } = options;
   return {
     UpsertWebIdeTestCases: {
-      description: "Persist generated automated test cases for this WebIDE task (full replace) and mark the workflow TEST_READY. Call once with the complete case list after reviewing the task and code changes.",
+      description: "Persist generated automated test cases for this WebIDE task (full replace). Call once with the complete case list after reviewing the task and code changes. Does not change workflow phase.",
       inputSchema: {
         type: "object",
         properties: {
@@ -2364,6 +2429,23 @@ function createCursorCustomTools(cfg2, options) {
         })
       );
     }
+    if (wantsTool("UpsertWebIdeChecklist", options, enablePlan)) {
+      Object.assign(
+        tools,
+        createUpsertWebIdeChecklistTool({
+          webideUpsertChecklist: (args) => cli.webideUpsertChecklist({ taskId, ...args })
+        })
+      );
+    }
+    if (wantsTool("GetWebIdeChecklist", options, enablePlan)) {
+      Object.assign(
+        tools,
+        createGetWebIdeChecklistTool({
+          boundTaskId: taskId,
+          webideGetChecklist: (args) => cli.webideGetChecklist(args)
+        })
+      );
+    }
     if (wantsTool("UpsertWebIdeTestCases", options, enablePlan)) {
       Object.assign(
         tools,
@@ -4145,100 +4227,6 @@ async function cleanWebIdeWorkspaceCache(taskId, workdir, cfg2) {
   }
 }
 
-// src/commands/connect/webide-run-action.ts
-function startActionForInbound(action) {
-  switch (action) {
-    case "request-assessment":
-      return "start-assessment";
-    case "request-design":
-    case "request-revise-design":
-      return "start-design";
-    case "request-write-plan":
-    case "request-revise-plan":
-      return "start-write-plan";
-    case "request-develop":
-    case "skip-plan":
-      return "start-develop";
-    case "request-start-project":
-      return "start-project";
-    case "request-execute-sql":
-      return "start-execute-sql";
-    case "request-bugfix":
-      return "start-bugfix";
-    case "request-organize-code":
-    case "request-patch":
-      return "start-organize-code";
-    case "request-accept":
-      return "start-accept";
-    default:
-      return null;
-  }
-}
-function completeActionForInbound(action) {
-  switch (action) {
-    case "request-assessment":
-    case "confirm-assumptions":
-      return "complete-assessment";
-    case "request-design":
-    case "request-revise-design":
-      return "complete-design";
-    case "request-write-plan":
-    case "request-revise-plan":
-      return "complete-write-plan";
-    case "request-develop":
-    case "skip-plan":
-      return "complete-develop";
-    case "request-start-project":
-      return "complete-project";
-    case "request-execute-sql":
-      return "complete-execute-sql";
-    case "request-bugfix":
-      return "complete-bugfix";
-    case "request-organize-code":
-    case "request-patch":
-      return "complete-organize-code";
-    case "request-accept":
-      return "complete-accept";
-    default:
-      return null;
-  }
-}
-async function webIdeRunAction(cfg2, taskId, action, params) {
-  const api = createApmApiClient(cfg2);
-  await api.cli.webideRunAction({ taskId, action, params });
-  console.log(`[apm] webide runAction ok action=${action} taskId=${taskId}`);
-}
-async function webIdeSyncTransitionPrepEvents(cfg2, taskId, startAction, prepEvents) {
-  try {
-    const api = createApmApiClient(cfg2);
-    await api.cli.webideUpdateTransitionPrepEvents({
-      taskId,
-      startAction,
-      prepEvents
-    });
-  } catch (err) {
-    console.warn(
-      `[apm] sync transition prepEvents failed taskId=${taskId}:`,
-      err instanceof Error ? err.message : err
-    );
-  }
-}
-async function webIdeDiscardTransitionPrepDraft(cfg2, taskId, startAction) {
-  try {
-    const api = createApmApiClient(cfg2);
-    await api.cli.webideUpdateTransitionPrepEvents({
-      taskId,
-      startAction,
-      discardDraft: true
-    });
-  } catch (err) {
-    console.warn(
-      `[apm] discard transition prep draft failed taskId=${taskId}:`,
-      err instanceof Error ? err.message : err
-    );
-  }
-}
-
 // src/commands/connect/webide-ask-question.ts
 function asString5(value) {
   return typeof value === "string" ? value.trim() : "";
@@ -4298,9 +4286,8 @@ async function fetchAssumptionAnswersAndContinueAssessment(options) {
       resolution: row.resolution
     });
   }
-  await webIdeRunAction(cfg2, taskId, "continue-assessment");
   console.log(
-    `[apm] \u5047\u8BBE\u7ED3\u679C\u5DF2\u62C9\u53D6\u5E76\u7EE7\u7EED\u8BC4\u4F30 taskId=${taskId} count=${answers.length}`
+    `[apm] \u5047\u8BBE\u7ED3\u679C\u5DF2\u62C9\u53D6 taskId=${taskId} count=${answers.length}`
   );
   return JSON.stringify({ title, answers }, null, 2);
 }
@@ -4790,6 +4777,102 @@ function parseWebIdePromptPayload(content) {
   return null;
 }
 
+// src/commands/connect/webide-run-action.ts
+function startActionForInbound(action) {
+  switch (action) {
+    case "request-assessment":
+      return "start-assessment";
+    case "request-design":
+    case "request-revise-design":
+      return "start-design";
+    case "request-write-plan":
+    case "request-revise-plan":
+      return "start-write-plan";
+    case "request-develop":
+    case "skip-plan":
+      return "start-develop";
+    case "request-start-project":
+      return "start-project";
+    case "request-execute-sql":
+      return "start-execute-sql";
+    case "request-bugfix":
+      return "start-bugfix";
+    case "request-organize-code":
+    case "request-patch":
+      return "start-organize-code";
+    case "request-accept":
+      return "start-accept";
+    case "confirm-assumptions":
+      return "continue-assessment";
+    default:
+      return null;
+  }
+}
+function completeActionForInbound(action) {
+  switch (action) {
+    case "request-assessment":
+    case "confirm-assumptions":
+      return "complete-assessment";
+    case "request-design":
+    case "request-revise-design":
+      return "complete-design";
+    case "request-write-plan":
+    case "request-revise-plan":
+      return "complete-write-plan";
+    case "request-develop":
+    case "skip-plan":
+      return "complete-develop";
+    case "request-start-project":
+      return "complete-project";
+    case "request-execute-sql":
+      return "complete-execute-sql";
+    case "request-bugfix":
+      return "complete-bugfix";
+    case "request-organize-code":
+    case "request-patch":
+      return "complete-organize-code";
+    case "request-accept":
+      return "complete-accept";
+    default:
+      return null;
+  }
+}
+async function webIdeRunAction(cfg2, taskId, action, params) {
+  const api = createApmApiClient(cfg2);
+  await api.cli.webideRunAction({ taskId, action, params });
+  console.log(`[apm] webide runAction ok action=${action} taskId=${taskId}`);
+}
+async function webIdeSyncTransitionPrepEvents(cfg2, taskId, startAction, prepEvents) {
+  try {
+    const api = createApmApiClient(cfg2);
+    await api.cli.webideUpdateTransitionPrepEvents({
+      taskId,
+      startAction,
+      prepEvents
+    });
+  } catch (err) {
+    console.warn(
+      `[apm] sync transition prepEvents failed taskId=${taskId}:`,
+      err instanceof Error ? err.message : err
+    );
+  }
+}
+async function webIdeDiscardTransitionPrepDraft(cfg2, taskId, startAction) {
+  try {
+    const api = createApmApiClient(cfg2);
+    await api.cli.webideUpdateTransitionPrepEvents({
+      taskId,
+      startAction,
+      discardDraft: true
+    });
+  } catch (err) {
+    console.warn(
+      `[apm] discard transition prep draft failed taskId=${taskId}:`,
+      err instanceof Error ? err.message : err
+    );
+  }
+}
+
 // src/commands/connect/core/worker/handlers/webide-message.ts
 var WEBIDE_CODE_CHANGE_ACTIONS = /* @__PURE__ */ new Set([
   "skip-plan",

package/package.json

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

package/template/AGENTS.webide.md

@@ -17,7 +17,7 @@
 - `webide_sql_execute.md`：execute-sql 轮次连库执行 SQL 时 Read
 - `webide_terminal.md`：长驻进程禁止用 Shell；本地服务由顶栏「启动项目」触发，开发任务不要自行起服务
 - `webide_testcase.md`：生成测试用例并调用 `UpsertWebIdeTestCases`
-- `webide_merge.md`：验收通过后调用 `MergeWebIdePullRequests`
+- `webide_merge.md`：验收通过后先 `UpsertWebIdeChecklist` 写验收清单，再 `MergeWebIdePullRequests`
 
 ### 目录
 
@@ -25,4 +25,4 @@
 - 任务附件：`.apm/webide/<taskId>/attachments/`（prompt 出现「任务附件」时按路径查看）
 - 仓库清单：`.apm/workspace-repos.json`（先确认单仓 / 多仓；多仓必须写清改动范围并点名仓库）
 
-计划、用例、合并 PR 走 WebIDE 专用工具（`AskQuestion`、`RecommendPlan`、`UpsertWebIdePlan`、`UpsertWebIdeTestCases`、`MergeWebIdePullRequests` 等）。本地服务由用户在顶栏「启动项目」启动，开发任务不要自行起长驻进程。
+计划、用例、验收清单、合并 PR 走 WebIDE 专用工具（`AskQuestion`、`RecommendPlan`、`UpsertWebIdePlan`、`UpsertWebIdeChecklist`、`GetWebIdeChecklist`、`UpsertWebIdeTestCases`、`MergeWebIdePullRequests` 等）。本地服务由用户在顶栏「启动项目」启动，开发任务不要自行起长驻进程。

package/template/rules/webide_merge.md

@@ -1,16 +1,24 @@
 ## WebIDE 合并规范
 
-适用场景：WebIDE 验收通过（`accept`）后合并本任务 PR。
+适用场景：WebIDE 验收通过（`accept` / `request-accept`）后，先落库验收清单，再合并本任务 PR。
 
 ### 目标
 
-将本任务各仓库特性分支上的变更合并进基线分支（通常为 `main`）。
+1. 留下一份可事后查阅的「验收清单」（描述本任务实际改了什么）。
+2. 将各仓库特性分支上的变更合并进基线分支（通常为 `main`）。
 
 ### 步骤
 
-1. 调用一次 `MergeWebIdePullRequests`（`confirmedConflictFree=true`），由平台合并本任务全部 OPEN PR。
-2. 用 `AppendMessage` 汇总合并结果（PR 编号、仓库）。
+1. **先写验收清单**：调用一次 `UpsertWebIdeChecklist`，提交完整 Markdown 全文（不要只提交 diff）。若需对照已有清单，可先 `GetWebIdeChecklist`（传当前 `taskId`）。建议结构：
+   - 改动摘要
+   - 按仓库的改动范围
+   - 关键改动点（模块 / 文件 / 接口 / 页面）
+   - 如何验收 / 回归点
+   - 备注（已知限制、未做事项、SQL/配置；无则写「无」）
+2. 调用一次 `MergeWebIdePullRequests`（`confirmedConflictFree=true`），由平台合并本任务全部 OPEN PR。
+3. 用 `AppendMessage` 汇总：清单已落库 + 合并结果（PR 编号、仓库）。
 
 ### 禁止
 
+- **禁止**跳过 `UpsertWebIdeChecklist` 直接合并
 - 在合并之外自行执行同步基线、代码审核、部署等额外流程