ai-project-manage-cli 6.0.93 → 6.0.95

package/README.md

@@ -55,7 +55,7 @@ apm daemon start
 apm daemon start -f
 ```
 
-PM2 已内置；同一时刻仅允许一个 connect。启动时会自动检测 CLI 更新并刷新守护配置。
+使用全局 PM2（未安装时会自动执行 `npm install -g pm2`）；同一时刻仅允许一个 connect。启动时会自动检测 CLI 更新并刷新守护配置。
 
 `apm pull` 会自动将平台登记的**仓库项目文档**同步到 `.apm/project/`（含 `manifest.json`）。Agent 修改 `.apm/project/` 下文件后，`apm connect` 处理完消息会自动推回平台。
 

package/dist/index.js

@@ -2029,9 +2029,169 @@ async function runSyncProjectDocuments(options) {
 }
 
 // src/commands/sync-document.ts
-import { existsSync as existsSync10 } from "fs";
+import { existsSync as existsSync10, readFileSync as readFileSync9 } from "fs";
 import { basename as basename3 } from "path";
 
+// src/assumptions/local-validate.ts
+var NO_ASSUMPTIONS_RE = /无[，,]?\s*口径均有依据/;
+var BLOCK_HEADER_RE = /^####\s+(A\d+)\s*$/im;
+var DEV_PATTERNS = [
+  { pattern: /status\s*=/i, message: "\u5305\u542B status= \u7B49\u6280\u672F\u679A\u4E3E" },
+  { pattern: /\.(java|vue|ts|tsx|jsx|sql)\b/i, message: "\u5305\u542B\u6587\u4EF6\u8DEF\u5F84" },
+  { pattern: /`[^`]+`/i, message: "\u5305\u542B\u4EE3\u7801\u53CD\u5F15\u53F7" },
+  { pattern: /\bSELECT\b|\bINSERT\b|\bALTER\b/i, message: "\u5305\u542B SQL \u5173\u952E\u5B57" },
+  { pattern: /\w+\.\w+/i, message: "\u5305\u542B\u7C7B\u540D\u6216\u8868\u5B57\u6BB5\u70B9\u53F7\u5199\u6CD5" },
+  { pattern: /\b[a-z]+_[a-z0-9_]+\b/i, message: "\u5305\u542B snake_case \u5B57\u6BB5\u540D" }
+];
+var BUSINESS_VERBS = /提交|展示|校验|驳回|审批|允许|禁止|筛选|列表|详情|暂存|删除|新增|修改|导出|导入/;
+function parseOptionsBlock(text) {
+  const options = [];
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    const match = trimmed.match(/^-\s*([a-zA-Z0-9_]+)[:：]\s*(.+)$/);
+    if (match) {
+      options.push({ id: match[1], label: match[2].trim() });
+    }
+  }
+  return options;
+}
+function parseField(block, label) {
+  const re = new RegExp(
+    `-\\s*\\*\\*${label}\\*\\*(?:\\\uFF08[^\uFF09]*\\\uFF09)?[:\uFF1A]\\s*(.*)$`,
+    "im"
+  );
+  const match = block.match(re);
+  const value = match?.[1]?.trim();
+  return value || void 0;
+}
+function parseStructuredBlock(code, block) {
+  const pmQuestion = parseField(block, "\u95EE") ?? parseField(block, "prompt");
+  if (!pmQuestion) return null;
+  const optionsSection = block.match(
+    /-\s*\*\*选项\*\*[:：]?\s*\n([\s\S]*?)(?=\n-\s*\*\*|$)/i
+  );
+  const options = optionsSection ? parseOptionsBlock(optionsSection[1]) : [];
+  return {
+    code,
+    questionId: code,
+    pmQuestion,
+    context: parseField(block, "\u573A\u666F"),
+    options,
+    technicalNote: parseField(block, "\u7814\u53D1\u5907\u6CE8"),
+    reason: parseField(block, "\u539F\u56E0")
+  };
+}
+function hasNoAssumptionsMarker(markdown) {
+  return NO_ASSUMPTIONS_RE.test(markdown.replace(/\r\n/g, "\n"));
+}
+function countAssumptionMarkers(markdown) {
+  const normalized = markdown.replace(/\r\n/g, "\n").trim();
+  if (NO_ASSUMPTIONS_RE.test(normalized)) return 0;
+  const codes = /* @__PURE__ */ new Set();
+  for (const line of normalized.split("\n")) {
+    const match = line.trim().match(/^####\s+(A\d+)\s*$/);
+    if (match) codes.add(match[1]);
+  }
+  return codes.size;
+}
+function parseAssumptionsDocument(markdown, _source) {
+  const normalized = markdown.replace(/\r\n/g, "\n").trim();
+  if (!normalized || NO_ASSUMPTIONS_RE.test(normalized)) {
+    return [];
+  }
+  const results = [];
+  const blocks = normalized.split(/(?=^####\s+A\d+\s*$)/im);
+  for (const block of blocks) {
+    const headerMatch = block.match(BLOCK_HEADER_RE);
+    if (!headerMatch) continue;
+    const parsed = parseStructuredBlock(headerMatch[1], block);
+    if (parsed) results.push(parsed);
+  }
+  return results;
+}
+function validateAssumptionForPm(assumption) {
+  const issues = [];
+  const questionForCheck = assumption.pmQuestion.replace(/`[^`]*`/g, "").trim();
+  if (!assumption.pmQuestion?.trim()) {
+    issues.push("\u7F3A\u5C11\u4E1A\u52A1\u95EE\u53E5");
+  } else if (questionForCheck.length < 6) {
+    issues.push("\u95EE\u53E5\u8FC7\u77ED");
+  } else if (!BUSINESS_VERBS.test(questionForCheck)) {
+    issues.push("\u95EE\u53E5\u7F3A\u5C11\u53EF\u7406\u89E3\u7684\u4E1A\u52A1\u52A8\u8BCD");
+  }
+  for (const { pattern, message } of DEV_PATTERNS) {
+    if (pattern.test(questionForCheck)) {
+      issues.push(message);
+    }
+  }
+  if (!assumption.context?.trim()) {
+    issues.push("\u7F3A\u5C11\u573A\u666F\u8BF4\u660E");
+  }
+  if (!assumption.options || assumption.options.length < 2) {
+    issues.push("\u9009\u9879\u5C11\u4E8E 2 \u9879");
+  }
+  return { ok: issues.length === 0, issues };
+}
+function printAssumptionValidationResult(result) {
+  for (const warning of result.warnings) {
+    console.warn(`[apm] \u5047\u8BBE\u6821\u9A8C\u544A\u8B66: ${warning}`);
+  }
+  for (const item of result.issues) {
+    console.error(
+      `[apm] \u5047\u8BBE ${item.code} \u672A\u901A\u8FC7 PM \u6821\u9A8C: ${item.issues.join("\uFF1B")}`
+    );
+  }
+}
+function resolveAssumptionSourceFromFileName(fileName) {
+  const key = fileName.replace(/\.md$/i, "").toUpperCase();
+  if (key === "FRONTEND-ASSUMPTIONS") {
+    return "FRONTEND_PLAN" /* FRONTEND_PLAN */;
+  }
+  if (key === "BACKEND-ASSUMPTIONS") {
+    return "BACKEND_PLAN" /* BACKEND_PLAN */;
+  }
+  return null;
+}
+function validateAssumptionsMarkdown(markdown, source) {
+  const markerCount = countAssumptionMarkers(markdown);
+  const explicitEmpty = hasNoAssumptionsMarker(markdown);
+  if (explicitEmpty && markerCount === 0) {
+    return {
+      ok: true,
+      markerCount: 0,
+      parsedCount: 0,
+      issues: [],
+      warnings: []
+    };
+  }
+  const parsed = parseAssumptionsDocument(markdown, source);
+  const issues = [];
+  const warnings = [];
+  for (const item of parsed) {
+    const result = validateAssumptionForPm(item);
+    if (!result.ok) {
+      issues.push({ code: item.code, issues: result.issues });
+    }
+  }
+  if (markerCount > 0 && parsed.length === 0) {
+    warnings.push(
+      `\u68C0\u6D4B\u5230 ${markerCount} \u6761\u5047\u8BBE\u6807\u8BB0\uFF0C\u4F46\u683C\u5F0F\u65E0\u6CD5\u89E3\u6790\u3002\u8BF7\u4F7F\u7528 #### A1 + \u95EE/\u573A\u666F/\u9009\u9879 \u7ED3\u6784\u3002`
+    );
+  } else if (markerCount > parsed.length) {
+    warnings.push(
+      `\u68C0\u6D4B\u5230 ${markerCount} \u6761\u5047\u8BBE\u6807\u8BB0\uFF0C\u4EC5\u89E3\u6790 ${parsed.length} \u6761\u3002`
+    );
+  }
+  const ok = issues.length === 0 && warnings.length === 0 && (markerCount === 0 || parsed.length > 0);
+  return {
+    ok,
+    markerCount,
+    parsedCount: parsed.length,
+    issues,
+    warnings
+  };
+}
+
 // src/commands/sync-session-documents.ts
 import { existsSync as existsSync9, readdirSync as readdirSync4, readFileSync as readFileSync8 } from "fs";
 import { join as join12 } from "path";
@@ -2116,6 +2276,19 @@ async function runSyncDocument(sessionId, options) {
     );
     process.exit(1);
   }
+  const fileName = basename3(absPath);
+  const assumptionSource = resolveAssumptionSourceFromFileName(fileName);
+  if (assumptionSource) {
+    const content = readFileSync9(absPath, "utf8");
+    const validation = validateAssumptionsMarkdown(content, assumptionSource);
+    if (!validation.ok) {
+      printAssumptionValidationResult(validation);
+      console.error(
+        "[apm] \u5047\u8BBE sync \u672A\u901A\u8FC7\uFF0C\u5DF2\u4E2D\u6B62\u4E0A\u4F20\u3002\u8BF7\u6309 apm-write-assumptions \u6280\u80FD\u4FEE\u6B63\u540E\u91CD\u8BD5"
+      );
+      process.exit(1);
+    }
+  }
   const cfg = await ensureLoggedConfig();
   const api = createApmApiClient(cfg);
   const docsDir = sessionDocsDir(trimmedSessionId);
@@ -2216,6 +2389,7 @@ async function runUpdateMessageStatus(options) {
 
 // src/commands/connect.ts
 import WebSocket from "ws";
+import { setTimeout as delay2 } from "node:timers/promises";
 
 // src/ws/protocol.ts
 function nonEmptyString(v) {
@@ -3004,7 +3178,7 @@ ${JSON.stringify(event, null, 2)}
 }
 
 // src/commands/connect/agent-session-registry.ts
-import { existsSync as existsSync11, mkdirSync as mkdirSync5, readFileSync as readFileSync9, writeFileSync as writeFileSync10 } from "node:fs";
+import { existsSync as existsSync11, mkdirSync as mkdirSync5, readFileSync as readFileSync10, writeFileSync as writeFileSync10 } 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");
@@ -3014,7 +3188,7 @@ function readRegistry(path13) {
     return {};
   }
   try {
-    const parsed = JSON.parse(readFileSync9(path13, "utf8"));
+    const parsed = JSON.parse(readFileSync10(path13, "utf8"));
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
       const result = {};
       for (const [key, value] of Object.entries(
@@ -3482,7 +3656,7 @@ async function ensureMessageHasReply(cfg, sessionId, messageId, fallback) {
 }
 
 // src/commands/connect/cli-version-sync.ts
-import { existsSync as existsSync12, readFileSync as readFileSync10, writeFileSync as writeFileSync11 } from "fs";
+import { existsSync as existsSync12, readFileSync as readFileSync11, writeFileSync as writeFileSync11 } from "fs";
 import { join as join13 } from "path";
 var CLI_VERSION_FILE = ".cli-version.json";
 function manifestPath(apmDir) {
@@ -3495,7 +3669,7 @@ function loadManifest3(apmDir) {
   }
   try {
     const parsed = JSON.parse(
-      readFileSync10(path13, "utf8")
+      readFileSync11(path13, "utf8")
     );
     if (parsed?.version === 1 && typeof parsed.cliVersion === "string" && parsed.cliVersion.trim()) {
       return parsed;
@@ -3584,7 +3758,7 @@ function createRunSlotPool(maxConcurrent = DEFAULT_MAX_CONCURRENT) {
 }
 
 // src/commands/connect-lock.ts
-import { existsSync as existsSync13, mkdirSync as mkdirSync6, readFileSync as readFileSync11, unlinkSync, writeFileSync as writeFileSync12 } from "fs";
+import { existsSync as existsSync13, mkdirSync as mkdirSync6, readFileSync as readFileSync12, unlinkSync, writeFileSync as writeFileSync12 } from "fs";
 import { join as join14 } from "path";
 var CONNECT_LOCK_PATH = join14(APM_CONFIG_DIR, "connect.lock");
 function isProcessAlive(pid) {
@@ -3599,7 +3773,7 @@ function isProcessAlive(pid) {
 function readConnectLock() {
   if (!existsSync13(CONNECT_LOCK_PATH)) return null;
   try {
-    const raw = readFileSync11(CONNECT_LOCK_PATH, "utf8");
+    const raw = readFileSync12(CONNECT_LOCK_PATH, "utf8");
     const parsed = JSON.parse(raw);
     if (typeof parsed.pid !== "number" || parsed.mode !== "foreground" && parsed.mode !== "pm2" || typeof parsed.startedAt !== "string") {
       return null;
@@ -3654,7 +3828,7 @@ function forceReleaseConnectLock() {
 
 // src/commands/daemon.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { createRequire } from "node:module";
+import { setTimeout as delay } from "node:timers/promises";
 import { existsSync as existsSync14, mkdirSync as mkdirSync7, writeFileSync as writeFileSync13 } from "fs";
 import { join as join15 } from "path";
 var PM2_APP_NAME = "apm-connect";
@@ -3682,10 +3856,12 @@ function buildConnectPm2Ecosystem(options) {
         args: options.connectArgs,
         autorestart: true,
         min_uptime: "10s",
-        max_restarts: 100,
+        max_restarts: 0,
         restart_delay: 3e3,
         exp_backoff_restart_delay: 1e3,
         max_memory_restart: "1G",
+        kill_timeout: 5e3,
+        shutdown_with_message: true,
         env
       }
     ]
@@ -3695,11 +3871,69 @@ function formatConnectPm2EcosystemFile(ecosystem) {
   return `module.exports = ${JSON.stringify(ecosystem, null, 2)};
 `;
 }
-function resolvePm2Bin() {
-  const require2 = createRequire(import.meta.url);
-  return require2.resolve("pm2/bin/pm2");
-}
 var useNpmShell2 = process.platform === "win32";
+function runNpm2(args, options = {}) {
+  return spawnSync2(useNpmShell2 ? "npm.cmd" : "npm", args, {
+    ...options,
+    shell: useNpmShell2
+  });
+}
+function findGlobalPm2() {
+  const whichResult = spawnSync2(useNpmShell2 ? "where" : "which", ["pm2"], {
+    encoding: "utf8",
+    shell: useNpmShell2,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  if (whichResult.status === 0) {
+    const lines = whichResult.stdout?.toString().trim().split(/\r?\n/) ?? [];
+    for (const line of lines) {
+      const candidate = line.trim();
+      if (candidate && existsSync14(candidate)) {
+        return candidate;
+      }
+    }
+  }
+  const binResult = runNpm2(["bin", "-g"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  if (binResult.status === 0) {
+    const globalBin = binResult.stdout?.toString().trim();
+    if (globalBin) {
+      const candidate = join15(globalBin, useNpmShell2 ? "pm2.cmd" : "pm2");
+      if (existsSync14(candidate)) {
+        return candidate;
+      }
+    }
+  }
+  return null;
+}
+function installGlobalPm2() {
+  console.log("[apm] \u672A\u68C0\u6D4B\u5230\u5168\u5C40 pm2\uFF0C\u6B63\u5728\u5B89\u88C5 npm install -g pm2 \u2026");
+  const result = runNpm2(["install", "-g", "pm2"], {
+    encoding: "utf8",
+    stdio: "inherit"
+  });
+  if (result.status !== 0) {
+    console.error("[apm] \u5B89\u88C5 pm2 \u5931\u8D25\uFF0C\u8BF7\u624B\u52A8\u6267\u884C: npm install -g pm2");
+    process.exit(result.status ?? 1);
+  }
+}
+function ensureGlobalPm2() {
+  const existing = findGlobalPm2();
+  if (existing) {
+    return existing;
+  }
+  installGlobalPm2();
+  const installed2 = findGlobalPm2();
+  if (!installed2) {
+    console.error(
+      "[apm] \u5B89\u88C5 pm2 \u540E\u4ECD\u65E0\u6CD5\u627E\u5230\u53EF\u6267\u884C\u6587\u4EF6\uFF0C\u8BF7\u624B\u52A8\u6267\u884C: npm install -g pm2"
+    );
+    process.exit(1);
+  }
+  return installed2;
+}
 function resolveApmEntryPath(entryArg = process.argv[1]) {
   const fromArgv = entryArg?.trim();
   if (fromArgv && existsSync14(fromArgv)) {
@@ -3729,20 +3963,13 @@ function isRunningUnderPm2() {
   return process.env.name === PM2_APP_NAME && process.env.pm_id !== void 0;
 }
 function runPm2(args, options) {
-  let pm2Bin;
-  try {
-    pm2Bin = resolvePm2Bin();
-  } catch {
-    console.error(
-      "[apm] \u672A\u627E\u5230\u5185\u7F6E pm2\uFF0C\u8BF7\u91CD\u65B0\u5B89\u88C5 apm CLI\uFF1Anpm install -g ai-project-manage-cli@latest"
-    );
-    process.exit(1);
-  }
+  const pm2Bin = ensureGlobalPm2();
   const spawnOptions = {
     encoding: "utf8",
-    stdio: options?.inherit ? "inherit" : ["ignore", "pipe", "pipe"]
+    stdio: options?.inherit ? "inherit" : ["ignore", "pipe", "pipe"],
+    shell: useNpmShell2
   };
-  const result = spawnSync2(process.execPath, [pm2Bin, ...args], spawnOptions);
+  const result = spawnSync2(pm2Bin, args, spawnOptions);
   if (result.error) {
     console.error("[apm] \u6267\u884C pm2 \u5931\u8D25:", result.error.message);
     process.exit(1);
@@ -3756,15 +3983,14 @@ function runPm2(args, options) {
   }
 }
 function runPm2Json(args) {
-  let pm2Bin;
-  try {
-    pm2Bin = resolvePm2Bin();
-  } catch {
+  const pm2Bin = findGlobalPm2();
+  if (!pm2Bin) {
     return "[]";
   }
-  const result = spawnSync2(process.execPath, [pm2Bin, ...args], {
+  const result = spawnSync2(pm2Bin, args, {
     encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"]
+    stdio: ["ignore", "pipe", "pipe"],
+    shell: useNpmShell2
   });
   if (result.status !== 0) return "[]";
   return result.stdout?.toString() ?? "[]";
@@ -3860,6 +4086,7 @@ async function prepareEcosystem(server) {
 }
 async function runDaemonStart(options) {
   assertConnectNotRunning();
+  ensureGlobalPm2();
   await runUpdate();
   const cfg = await prepareEcosystem(options.server);
   runPm2(["start", PM2_ECOSYSTEM_PATH, "--update-env"], { inherit: true });
@@ -3878,10 +4105,44 @@ async function runDaemonStart(options) {
   console.log("[apm] \u505C\u6B62: apm daemon stop");
 }
 async function runDaemonStop() {
+  pruneStaleConnectLock();
+  if (!isPm2ConnectOnline()) {
+    killConnectLockProcessIfAlive();
+    forceReleaseConnectLock();
+    console.log(`[apm] ${PM2_APP_NAME} \u672A\u5728\u8FD0\u884C`);
+    return;
+  }
   runPm2(["stop", PM2_APP_NAME], { inherit: true });
+  for (let i = 0; i < 10; i += 1) {
+    if (!isPm2ConnectOnline()) break;
+    await delay(500);
+  }
+  if (isPm2ConnectOnline()) {
+    console.log(`[apm] \u4F18\u96C5\u505C\u6B62\u8D85\u65F6\uFF0C\u5F3A\u5236\u79FB\u9664 ${PM2_APP_NAME}\u2026`);
+    runPm2(["delete", PM2_APP_NAME], { inherit: true });
+  }
+  killConnectLockProcessIfAlive();
   forceReleaseConnectLock();
   console.log(`[apm] ${PM2_APP_NAME} \u5DF2\u505C\u6B62`);
 }
+function killConnectLockProcessIfAlive() {
+  pruneStaleConnectLock();
+  const lock = readConnectLock();
+  if (!lock || !isProcessAlive(lock.pid)) return;
+  try {
+    process.kill(lock.pid, "SIGTERM");
+  } catch {
+    forceReleaseConnectLock();
+    return;
+  }
+  if (isProcessAlive(lock.pid)) {
+    try {
+      process.kill(lock.pid, "SIGKILL");
+    } catch {
+    }
+  }
+  forceReleaseConnectLock();
+}
 async function runDaemonRestart(options) {
   pruneStaleConnectLock();
   const lock = readConnectLock();
@@ -3916,6 +4177,8 @@ async function runDaemonLogs(options) {
 
 // src/commands/connect.ts
 var HEARTBEAT_MS = 3e4;
+var RECONNECT_MIN_MS = 1e3;
+var RECONNECT_MAX_MS = 6e4;
 async function updateMessageStatus(cfg, messageId, status) {
   const api = createApmApiClient(cfg);
   await api.cli.updateMessageStatus({ id: messageId, status });
@@ -4068,6 +4331,17 @@ async function handleInboundMessage(cfg, msg, signal, ctx) {
     }
   }
 }
+function interruptibleSleep(ms, signal) {
+  if (signal.aborted) return Promise.resolve();
+  return new Promise((resolve5) => {
+    const timer = setTimeout(resolve5, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve5();
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
 function startHeartbeat(ws, clientMachineId) {
   const send = () => {
     if (ws.readyState === WebSocket.OPEN) {
@@ -4083,182 +4357,274 @@ function startHeartbeat(ws, clientMachineId) {
   const timer = setInterval(send, HEARTBEAT_MS);
   return () => clearInterval(timer);
 }
-async function runConnect(options) {
-  const { didUpdate } = await runUpdate();
-  if (didUpdate) {
-    await handleConnectAfterUpdate(options);
-  }
-  const cfg = await ensureLoggedConfig();
-  if (options.server?.trim()) {
-    cfg.baseUrl = options.server.trim().replace(/\/+$/, "");
-  }
-  const clientMachineId = resolveClientMachineId(cfg);
-  if (!clientMachineId) {
-    console.error("[apm] config \u7F3A\u5C11 clientMachineId\uFF0C\u8BF7\u91CD\u65B0 apm login");
-    process.exit(1);
-  }
-  assertConnectNotRunning();
-  acquireConnectLock("foreground");
-  process.on("exit", releaseConnectLock);
-  const url = buildAgentWsUrl(cfg.baseUrl, resolveApiKey(cfg));
-  console.log(`[apm] \u8FDE\u63A5 ${cfg.baseUrl} \u2026`);
-  await new Promise((resolve5, reject) => {
-    const ws = new WebSocket(url);
-    let stopHeartbeat;
-    let shuttingDown = false;
-    const shutdownAbort = new AbortController();
-    const runSlots = createRunSlotPool();
-    const activeTasks = /* @__PURE__ */ new Set();
-    const activeRuns = /* @__PURE__ */ new Map();
-    const pendingCancels = /* @__PURE__ */ new Set();
-    const shutdown = async (code = 0) => {
-      if (shuttingDown) return;
-      shuttingDown = true;
-      logAbortSignalStats(
-        shutdownAbort.signal,
-        "connect:shutdown-before-abort"
-      );
-      shutdownAbort.abort();
-      logAbortSignalStats(shutdownAbort.signal, "connect:shutdown-after-abort");
-      stopHeartbeat?.();
-      if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
-        ws.terminate();
-      }
-      try {
-        await Promise.race([
-          Promise.all(activeTasks),
-          new Promise((r) => setTimeout(r, SHUTDOWN_DRAIN_MS))
-        ]);
-      } catch {
-      }
-      releaseConnectLock();
-      resolve5();
-      process.exit(code);
-    };
-    ws.on("open", () => {
-      console.log("[apm] WebSocket \u5DF2\u8FDE\u63A5");
-      stopHeartbeat = startHeartbeat(ws, clientMachineId);
-    });
-    ws.on("message", (data) => {
-      if (shuttingDown) return;
-      const text = Buffer.isBuffer(data) ? data.toString("utf8") : String(data);
-      const parsed = parseAgentWsMessage(text);
-      if (parsed === null) {
-        console.error("[apm] \u6536\u5230\u65E0\u6548 JSON");
-        return;
-      }
-      if (typeof parsed === "object" && parsed !== null && parsed.type === "heartbeat") {
-        return;
-      }
-      const validated = validateAgentWsMessage(parsed, "outbound");
-      if (!validated.ok) {
-        console.error(`[apm] \u6536\u5230\u65E0\u6548 WS \u5305: ${validated.reason}`);
-        return;
-      }
-      if (validated.data.type === "cancel") {
-        const { messageId } = validated.data;
-        pendingCancels.add(messageId);
-        activeRuns.get(messageId)?.abort();
-        return;
-      }
-      if (validated.data.type === "deploy") {
-        const msg2 = validated.data;
-        const perDeployController = new AbortController();
-        const signal2 = AbortSignal.any([
-          shutdownAbort.signal,
-          perDeployController.signal
-        ]);
-        const task2 = (async () => {
-          await runSlots.acquire();
-          try {
-            await handleInboundDeploy(cfg, msg2, signal2);
-          } finally {
-            runSlots.release();
-          }
-        })();
-        activeTasks.add(task2);
-        void task2.finally(() => {
-          activeTasks.delete(task2);
-        });
-        return;
-      }
-      if (validated.data.type !== "message") {
-        return;
-      }
-      const msg = validated.data;
-      const perMessageController = new AbortController();
-      activeRuns.set(msg.messageId, perMessageController);
-      if (pendingCancels.has(msg.messageId)) {
-        activeRuns.delete(msg.messageId);
-        pendingCancels.delete(msg.messageId);
-        return;
-      }
-      const signal = AbortSignal.any([
+function attachWsHandlers(ws, ctx, onOpen) {
+  const {
+    cfg,
+    clientMachineId,
+    shutdownAbort,
+    runSlots,
+    activeTasks,
+    activeRuns,
+    pendingCancels,
+    isShuttingDown
+  } = ctx;
+  ws.on("open", () => {
+    console.log("[apm] WebSocket \u5DF2\u8FDE\u63A5");
+    onOpen();
+  });
+  ws.on("message", (data) => {
+    if (isShuttingDown()) return;
+    const text = Buffer.isBuffer(data) ? data.toString("utf8") : String(data);
+    const parsed = parseAgentWsMessage(text);
+    if (parsed === null) {
+      console.error("[apm] \u6536\u5230\u65E0\u6548 JSON");
+      return;
+    }
+    if (typeof parsed === "object" && parsed !== null && parsed.type === "heartbeat") {
+      return;
+    }
+    const validated = validateAgentWsMessage(parsed, "outbound");
+    if (!validated.ok) {
+      console.error(`[apm] \u6536\u5230\u65E0\u6548 WS \u5305: ${validated.reason}`);
+      return;
+    }
+    if (validated.data.type === "cancel") {
+      const { messageId } = validated.data;
+      pendingCancels.add(messageId);
+      activeRuns.get(messageId)?.abort();
+      return;
+    }
+    if (validated.data.type === "deploy") {
+      const msg2 = validated.data;
+      const perDeployController = new AbortController();
+      const signal2 = AbortSignal.any([
         shutdownAbort.signal,
-        perMessageController.signal
+        perDeployController.signal
       ]);
-      const ctx = {
-        shutdownSignal: shutdownAbort.signal,
-        perMessageSignal: perMessageController.signal
-      };
-      const task = (async () => {
+      const task2 = (async () => {
         await runSlots.acquire();
         try {
-          if (signal.aborted || isUserCancelled(ctx)) return;
-          try {
-            await updateMessageStatus(cfg, msg.messageId, "TYPING");
-          } catch (typingErr) {
-            if (isUserCancelled(ctx)) return;
-            console.error(
-              "[apm] \u66F4\u65B0 TYPING \u72B6\u6001\u5931\u8D25:",
-              typingErr instanceof Error ? typingErr.message : typingErr
-            );
-            try {
-              await setMessageError(
-                cfg,
-                msg.messageId,
-                typingErr instanceof Error ? typingErr.message : String(typingErr)
-              );
-              await updateMessageStatus(cfg, msg.messageId, "FAILED");
-            } catch (statusErr) {
-              console.error(
-                "[apm] \u66F4\u65B0 FAILED \u72B6\u6001\u5931\u8D25:",
-                statusErr instanceof Error ? statusErr.message : statusErr
-              );
-            }
-            return;
-          }
-          await handleInboundMessage(cfg, msg, signal, ctx);
+          await handleInboundDeploy(cfg, msg2, signal2);
         } finally {
           runSlots.release();
-          activeRuns.delete(msg.messageId);
-          pendingCancels.delete(msg.messageId);
         }
       })();
-      activeTasks.add(task);
-      void task.finally(() => {
-        activeTasks.delete(task);
+      activeTasks.add(task2);
+      void task2.finally(() => {
+        activeTasks.delete(task2);
       });
+      return;
+    }
+    if (validated.data.type !== "message") {
+      return;
+    }
+    const msg = validated.data;
+    const perMessageController = new AbortController();
+    activeRuns.set(msg.messageId, perMessageController);
+    if (pendingCancels.has(msg.messageId)) {
+      activeRuns.delete(msg.messageId);
+      pendingCancels.delete(msg.messageId);
+      return;
+    }
+    const signal = AbortSignal.any([
+      shutdownAbort.signal,
+      perMessageController.signal
+    ]);
+    const messageCtx = {
+      shutdownSignal: shutdownAbort.signal,
+      perMessageSignal: perMessageController.signal
+    };
+    const task = (async () => {
+      await runSlots.acquire();
+      try {
+        if (signal.aborted || isUserCancelled(messageCtx)) return;
+        try {
+          await updateMessageStatus(cfg, msg.messageId, "TYPING");
+        } catch (typingErr) {
+          if (isUserCancelled(messageCtx)) return;
+          console.error(
+            "[apm] \u66F4\u65B0 TYPING \u72B6\u6001\u5931\u8D25:",
+            typingErr instanceof Error ? typingErr.message : typingErr
+          );
+          try {
+            await setMessageError(
+              cfg,
+              msg.messageId,
+              typingErr instanceof Error ? typingErr.message : String(typingErr)
+            );
+            await updateMessageStatus(cfg, msg.messageId, "FAILED");
+          } catch (statusErr) {
+            console.error(
+              "[apm] \u66F4\u65B0 FAILED \u72B6\u6001\u5931\u8D25:",
+              statusErr instanceof Error ? statusErr.message : statusErr
+            );
+          }
+          return;
+        }
+        await handleInboundMessage(cfg, msg, signal, messageCtx);
+      } finally {
+        runSlots.release();
+        activeRuns.delete(msg.messageId);
+        pendingCancels.delete(msg.messageId);
+      }
+    })();
+    activeTasks.add(task);
+    void task.finally(() => {
+      activeTasks.delete(task);
+    });
+  });
+}
+function connectOnce(url, ctx, connectionAbort, onConnected) {
+  return new Promise((resolve5, reject) => {
+    const ws = new WebSocket(url);
+    let stopHeartbeat;
+    let settled = false;
+    const finish = (fn) => {
+      if (settled) return;
+      settled = true;
+      connectionAbort.removeEventListener("abort", onConnectionAbort);
+      stopHeartbeat?.();
+      fn();
+    };
+    const onConnectionAbort = () => {
+      if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+        ws.terminate();
+      }
+    };
+    connectionAbort.addEventListener("abort", onConnectionAbort);
+    attachWsHandlers(ws, ctx, () => {
+      stopHeartbeat = startHeartbeat(ws, ctx.clientMachineId);
+      onConnected();
     });
     ws.on("close", (code, reason) => {
       console.log(
         `[apm] \u8FDE\u63A5\u5DF2\u65AD\u5F00 code=${code}${reason ? ` reason=${reason.toString()}` : ""}`
       );
-      void shutdown();
+      if (ctx.isShuttingDown()) {
+        finish(() => reject(new Error("shutdown")));
+        return;
+      }
+      finish(resolve5);
     });
     ws.on("error", (err) => {
       console.error("[apm] WebSocket \u9519\u8BEF:", err.message);
-      reject(err);
-    });
-    process.on("SIGINT", () => {
-      console.log("[apm] \u6B63\u5728\u5173\u95ED\u2026");
-      void shutdown();
-    });
-    process.on("SIGTERM", () => {
-      void shutdown();
+      if (ctx.isShuttingDown()) {
+        finish(() => reject(new Error("shutdown")));
+        return;
+      }
+      if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+        ws.terminate();
+      }
     });
   });
 }
+async function runConnect(options) {
+  const { didUpdate } = await runUpdate();
+  if (didUpdate) {
+    await handleConnectAfterUpdate(options);
+  }
+  const cfg = await ensureLoggedConfig();
+  if (options.server?.trim()) {
+    cfg.baseUrl = options.server.trim().replace(/\/+$/, "");
+  }
+  const clientMachineId = resolveClientMachineId(cfg);
+  if (!clientMachineId) {
+    console.error("[apm] config \u7F3A\u5C11 clientMachineId\uFF0C\u8BF7\u91CD\u65B0 apm login");
+    process.exit(1);
+  }
+  assertConnectNotRunning();
+  const lockMode = isRunningUnderPm2() ? "pm2" : "foreground";
+  acquireConnectLock(lockMode);
+  process.on("exit", releaseConnectLock);
+  let shuttingDown = false;
+  let shutdownPromise = null;
+  const lifecycleAbort = new AbortController();
+  const shutdownAbort = new AbortController();
+  const runSlots = createRunSlotPool();
+  const activeTasks = /* @__PURE__ */ new Set();
+  const activeRuns = /* @__PURE__ */ new Map();
+  const pendingCancels = /* @__PURE__ */ new Set();
+  let currentConnectionAbort = null;
+  const sessionCtx = {
+    cfg,
+    clientMachineId,
+    shutdownAbort,
+    runSlots,
+    activeTasks,
+    activeRuns,
+    pendingCancels,
+    isShuttingDown: () => shuttingDown
+  };
+  const drainAndExit = async (code = 0) => {
+    const drainMs = isRunningUnderPm2() ? 500 : SHUTDOWN_DRAIN_MS;
+    lifecycleAbort.abort();
+    currentConnectionAbort?.abort();
+    logAbortSignalStats(shutdownAbort.signal, "connect:shutdown-before-abort");
+    shutdownAbort.abort();
+    logAbortSignalStats(shutdownAbort.signal, "connect:shutdown-after-abort");
+    try {
+      await Promise.race([Promise.all(activeTasks), delay2(drainMs)]);
+    } catch {
+    }
+    releaseConnectLock();
+    process.exit(code);
+  };
+  const shutdown = (code = 0) => {
+    if (shuttingDown) return shutdownPromise ?? Promise.resolve();
+    shuttingDown = true;
+    shutdownPromise = drainAndExit(code);
+    return shutdownPromise;
+  };
+  const onStopSignal = (code = 0) => {
+    console.log("[apm] \u6B63\u5728\u5173\u95ED\u2026");
+    void shutdown(code);
+  };
+  process.on("SIGINT", () => onStopSignal(0));
+  process.on("SIGTERM", () => onStopSignal(0));
+  if (isRunningUnderPm2()) {
+    process.on("message", (msg) => {
+      if (msg === "shutdown") onStopSignal(0);
+    });
+  }
+  let reconnectDelay = RECONNECT_MIN_MS;
+  while (!shuttingDown) {
+    currentConnectionAbort = new AbortController();
+    const connectionSignal = AbortSignal.any([
+      lifecycleAbort.signal,
+      currentConnectionAbort.signal
+    ]);
+    const url = buildAgentWsUrl(cfg.baseUrl, resolveApiKey(cfg));
+    console.log(`[apm] \u8FDE\u63A5 ${cfg.baseUrl} \u2026`);
+    try {
+      await connectOnce(url, sessionCtx, connectionSignal, () => {
+        reconnectDelay = RECONNECT_MIN_MS;
+      });
+      if (shuttingDown) break;
+      console.log(`[apm] ${reconnectDelay}ms \u540E\u5C1D\u8BD5\u91CD\u8FDE\u2026`);
+      await interruptibleSleep(reconnectDelay, lifecycleAbort.signal);
+      if (shuttingDown) break;
+      reconnectDelay = Math.min(reconnectDelay * 2, RECONNECT_MAX_MS);
+    } catch (err) {
+      if (shuttingDown) break;
+      const detail = err instanceof Error ? err.message : String(err);
+      if (detail === "shutdown") break;
+      console.error("[apm] \u8FDE\u63A5\u5931\u8D25:", detail);
+      console.log(`[apm] ${reconnectDelay}ms \u540E\u5C1D\u8BD5\u91CD\u8FDE\u2026`);
+      await interruptibleSleep(reconnectDelay, lifecycleAbort.signal);
+      if (shuttingDown) break;
+      reconnectDelay = Math.min(reconnectDelay * 2, RECONNECT_MAX_MS);
+    } finally {
+      currentConnectionAbort = null;
+    }
+  }
+  if (!shuttingDown) {
+    void shutdown(0);
+    return;
+  }
+  if (shutdownPromise) {
+    await shutdownPromise;
+  }
+}
 
 // src/commands/create-pr-errors.ts
 import { ApiError as ApiError2 } from "listpage-http";
@@ -4391,7 +4757,7 @@ import { spawnSync as spawnSync5 } from "node:child_process";
 import path5 from "node:path";
 
 // src/commands/deploy/internal/apm-config.ts
-import { existsSync as existsSync15, readFileSync as readFileSync12 } from "node:fs";
+import { existsSync as existsSync15, readFileSync as readFileSync13 } from "node:fs";
 import { homedir as homedir2 } from "node:os";
 import { join as join16, resolve as resolve4 } from "node:path";
 function loadApmConfig(options) {
@@ -4404,7 +4770,7 @@ function loadApmConfig(options) {
     process.exit(1);
   }
   try {
-    const raw = readFileSync12(p, "utf8");
+    const raw = readFileSync13(p, "utf8");
     return JSON.parse(raw);
   } catch (e) {
     console.error(`\u65E0\u6CD5\u89E3\u6790 apm.config.json\uFF1A${p}`, e);
@@ -4593,7 +4959,7 @@ function readMavenLocalRepoFromSettings() {
     return null;
   }
   try {
-    const xml = readFileSync12(settingsPath, "utf8");
+    const xml = readFileSync13(settingsPath, "utf8");
     const match = xml.match(
       /<localRepository>\s*([^<]+?)\s*<\/localRepository>/
     );
@@ -4735,7 +5101,7 @@ var DeployExecutionError = class extends Error {
 };
 
 // src/commands/deploy/internal/wisdom-auto-deploy.ts
-import { existsSync as existsSync17, readFileSync as readFileSync14, statSync as statSync7 } from "node:fs";
+import { existsSync as existsSync17, readFileSync as readFileSync15, statSync as statSync7 } from "node:fs";
 import path4 from "node:path";
 import { spawnSync as spawnSync4 } from "node:child_process";
 
@@ -4744,7 +5110,7 @@ import {
   existsSync as existsSync16,
   mkdirSync as mkdirSync8,
   readdirSync as readdirSync5,
-  readFileSync as readFileSync13,
+  readFileSync as readFileSync14,
   statSync as statSync6,
   writeFileSync as writeFileSync14
 } from "node:fs";
@@ -4788,6 +5154,56 @@ async function zipDirectory(distDir, zipPath) {
   console.error(`\u5DF2\u751F\u6210: ${zipPath} (${sizeMb} MB)`);
   return content.length;
 }
+var SFTP_UPLOAD_MAX_ATTEMPTS = 3;
+var SFTP_FAST_PUT_OPTIONS = {
+  chunkSize: 64 * 1024,
+  concurrency: 4
+};
+function buildSftpConnectOptions(settings) {
+  return {
+    host: settings.host,
+    port: settings.port,
+    username: settings.username,
+    password: settings.password,
+    readyTimeout: 3e4,
+    tryKeyboard: true,
+    keepaliveInterval: 1e4,
+    keepaliveCountMax: 3
+  };
+}
+async function sleep(ms) {
+  await new Promise((resolve5) => setTimeout(resolve5, ms));
+}
+async function uploadZipWithRetry(settings, localZip, remoteZipPath) {
+  let lastError;
+  for (let attempt = 1; attempt <= SFTP_UPLOAD_MAX_ATTEMPTS; attempt++) {
+    const sftp = new SftpClient();
+    try {
+      if (attempt > 1) {
+        console.error(
+          `SFTP \u4E0A\u4F20\u91CD\u8BD5 (${attempt}/${SFTP_UPLOAD_MAX_ATTEMPTS})...`
+        );
+      }
+      await sftp.connect(buildSftpConnectOptions(settings));
+      await ensureRemoteDir(sftp, settings.remotePath);
+      await sftp.fastPut(localZip, remoteZipPath, SFTP_FAST_PUT_OPTIONS);
+      return sftp;
+    } catch (err) {
+      lastError = err;
+      try {
+        await sftp.end();
+      } catch {
+      }
+      if (attempt < SFTP_UPLOAD_MAX_ATTEMPTS) {
+        const message = err instanceof Error ? err.message : String(err);
+        const delaySec = attempt * 2;
+        console.error(`SFTP \u4E0A\u4F20\u5931\u8D25 (${message})\uFF0C${delaySec}s \u540E\u91CD\u8BD5...`);
+        await sleep(delaySec * 1e3);
+      }
+    }
+  }
+  throw lastError;
+}
 async function ensureRemoteDir(sftp, dir) {
   const parts = dir.replace(/\\/g, "/").split("/").filter(Boolean);
   let current = dir.startsWith("/") ? "" : ".";
@@ -4847,18 +5263,8 @@ async function uploadAndMaybeExtract(settings, localZip, extract) {
   console.error(
     `\u8FDE\u63A5 ${settings.username}@${settings.host}:${settings.port} ...`
   );
-  const sftp = new SftpClient();
+  const sftp = await uploadZipWithRetry(settings, localZip, remoteZipPath);
   try {
-    await sftp.connect({
-      host: settings.host,
-      port: settings.port,
-      username: settings.username,
-      password: settings.password,
-      readyTimeout: 2e4,
-      tryKeyboard: true
-    });
-    await ensureRemoteDir(sftp, settings.remotePath);
-    await sftp.put(localZip, remoteZipPath);
     console.error(`  \u2713 ${localZip} -> ${remoteZipPath}`);
     if (extract) {
       const target = settings.remotePath.replace(/\/$/, "");
@@ -4974,7 +5380,7 @@ function loadManifest4() {
   if (!existsSync16(manifestPath2)) {
     return {};
   }
-  return JSON.parse(readFileSync13(manifestPath2, "utf8"));
+  return JSON.parse(readFileSync14(manifestPath2, "utf8"));
 }
 function saveManifest4(manifest) {
   const dir = deployCacheDir();
@@ -5040,7 +5446,7 @@ async function createUpdatePackage(entries, packageName) {
   log(`\u521B\u5EFA\u66F4\u65B0\u5305: ${path3.basename(zipPath)}\uFF08${entries.length} \u4E2A\u6587\u4EF6\uFF09`);
   const zip = new JSZip2();
   for (const entry of entries) {
-    const content = readFileSync13(entry.path);
+    const content = readFileSync14(entry.path);
     zip.file(entry.arcname, content);
     log(`  \u6253\u5305: ${entry.arcname} (${entry.reason})`);
   }
@@ -5606,7 +6012,7 @@ function readPackageScripts(cwd) {
     return {};
   }
   try {
-    const raw = readFileSync14(pkgPath, "utf8");
+    const raw = readFileSync15(pkgPath, "utf8");
     const parsed = JSON.parse(raw);
     return parsed.scripts ?? {};
   } catch {
@@ -6130,7 +6536,7 @@ import path9 from "node:path";
 import Docker from "dockerode";
 
 // src/commands/deploy/internal/backend-deploy/dockerode-client/connection-options.ts
-import { existsSync as existsSync18, readFileSync as readFileSync15 } from "node:fs";
+import { existsSync as existsSync18, readFileSync as readFileSync16 } from "node:fs";
 import path6 from "node:path";
 function asOptionalTlsBuffer(value) {
   if (typeof value !== "string") {
@@ -6143,7 +6549,7 @@ function asOptionalTlsBuffer(value) {
     return void 0;
   }
   if (existsSync18(normalized)) {
-    return readFileSync15(normalized);
+    return readFileSync16(normalized);
   }
   const looksLikePath = /[\\/]/.test(normalized) || normalized.endsWith(".pem");
   if (looksLikePath) {
@@ -6353,7 +6759,7 @@ var DockerodeClient = class {
 var createDockerodeClient = (config) => new DockerodeClient(config);
 
 // src/commands/deploy/internal/backend-deploy/dockerode-client/env.ts
-import { existsSync as existsSync19, readFileSync as readFileSync16, statSync as statSync8 } from "node:fs";
+import { existsSync as existsSync19, readFileSync as readFileSync17, statSync as statSync8 } from "node:fs";
 import path7 from "node:path";
 function stripSurroundingQuotes(value) {
   const t = value.trim();
@@ -6373,7 +6779,7 @@ function loadEnvFromFile(envFilePath) {
   if (!existsSync19(targetPath) || !statSync8(targetPath).isFile()) {
     return {};
   }
-  const raw = readFileSync16(targetPath, "utf-8");
+  const raw = readFileSync17(targetPath, "utf-8");
   const result = {};
   for (const line of raw.split(/\r?\n/)) {
     const normalized = line.trim();
@@ -7034,7 +7440,7 @@ function buildProgram() {
     "\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\u5F53\u524D\u5927\u7248\u672C\u6700\u65B0\u7248"
   ).option("--server <url>", "API \u6839\u5730\u5740\uFF0C\u8986\u76D6 config \u4E2D\u7684 baseUrl").option(
     "--daemon",
-    "\u540E\u53F0\u5B88\u62A4\u8FD0\u884C\uFF08\u5185\u7F6E PM2\uFF0C\u65AD\u7EBF\u6216\u9000\u51FA\u540E\u81EA\u52A8\u91CD\u542F\uFF1B\u63A8\u8350\u7528\u4E8E\u957F\u671F\u5728\u7EBF\uFF09"
+    "\u540E\u53F0\u5B88\u62A4\u8FD0\u884C\uFF08\u5168\u5C40 PM2\uFF0C\u65AD\u7EBF\u6216\u9000\u51FA\u540E\u81EA\u52A8\u91CD\u542F\uFF1B\u63A8\u8350\u7528\u4E8E\u957F\u671F\u5728\u7EBF\uFF09"
   ).option("-f, --follow", "\u4E0E --daemon \u5408\u7528\uFF1A\u542F\u52A8\u540E\u5728\u5F53\u524D\u7EC8\u7AEF\u5B9E\u65F6\u8DDF\u8E2A\u65E5\u5FD7").action(
     async (opts) => {
       if (opts.follow && !opts.daemon) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-project-manage-cli",
-  "version": "6.0.93",
+  "version": "6.0.95",
   "description": "命令行工具：后续用于调用平台后端 API 完成运维与自动化操作",
   "type": "module",
   "private": false,
@@ -44,7 +44,6 @@
     "dockerode": "~5.0.0",
     "ssh2": "~1.16.0",
     "ssh2-sftp-client": "~12.0.1",
-    "jszip": "~3.10.1",
-    "pm2": "~5.4.3"
+    "jszip": "~3.10.1"
   }
 }

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

@@ -0,0 +1,78 @@
+# apm-write-assumptions：编写并同步待确认口径
+
+## 何时使用
+
+`apm-write-plan` 步骤 3 编写 `*-ASSUMPTIONS.md` 时；或需重写/补写假设文档时。
+
+| 角色 | 产出                           |
+| ---- | ------------------------------ |
+| 前端 | `docs/FRONTEND-ASSUMPTIONS.md` |
+| 后端 | `docs/BACKEND-ASSUMPTIONS.md`  |
+
+---
+
+## 工作流程
+
+### 1. 按模板编写
+
+1. **Read** `.apm/skills/apm-write-assumptions/assumptions-template.md`
+2. **Write** 本端 `docs/*-ASSUMPTIONS.md`（写作时对照下方 **PM 校验规则**）
+3. 无假设时正文仅一行：`无，口径均有依据。`
+
+### 2. 直接 sync
+
+```bash
+apm sync-document <sessionId> --file FRONTEND-ASSUMPTIONS.md
+# 或 BACKEND-ASSUMPTIONS.md
+```
+
+**成功**须看到：
+
+```text
+[apm] 假设解析: 标记 N 条，入库 N 条（PM 可确认 N 条）
+```
+
+无假设时无 `假设解析` 行，属正常。
+
+### 3. 报错则改完重 sync
+
+`sync-document` 失败时会打印具体假设编号与原因（如 `假设 A2 未通过 PM 校验: …`）。
+
+1. 按报错修正对应 `A*` 的 **问 / 场景 / 选项**（规则见下）
+2. 再次执行步骤 2
+3. **禁止**在未成功 sync 前 @ 项目经理、sync PLAN、或声称「请在 Web 待确认」
+
+---
+
+## PM 校验规则（与服务端一致）
+
+每条假设（`#### A1` …）必须包含：
+
+| 字段         | 要求                                                            |
+| ------------ | --------------------------------------------------------------- |
+| **问**       | 业务语言；≥6 字；含下列业务动词之一；禁止字段名/路径/SQL/反引号 |
+| **场景**     | 非空                                                            |
+| **选项**     | ≥2 项，格式 `- opt_id：说明`                                    |
+| **研发备注** | 可选；技术细节放这里，**不要**写进「问」                        |
+
+**问句须含以下动词之一**：
+
+`提交` `展示` `校验` `驳回` `审批` `允许` `禁止` `筛选` `列表` `详情` `暂存` `删除` `新增` `修改` `导出` `导入`
+
+**问句禁止**：`status=`、文件扩展名、反引号代码、SQL、`类.字段`、snake_case 字段名。
+
+### 正反例
+
+| 假设    | 问句                                           | 结果                   |
+| ------- | ---------------------------------------------- | ---------------------- |
+| A2      | 编辑已有记录时，「落实人员」应如何处理？       | **失败**（无业务动词） |
+| A2 修正 | 编辑已有记录时，是否**允许修改**「落实人员」？ | 通过                   |
+| A3      | 「落实人员」可选择的范围是？                   | **失败**               |
+| A3 修正 | 「落实人员」下拉**列表**应**展示**哪些人员？   | 通过                   |
+
+---
+
+## 与其他技能
+
+- 由 **`apm-write-plan`** 在 sync PLAN 前调用本技能
+- PM 确认后由 **`apm-update-plan`** 更新 PLAN

package/template/skills/{apm-write-plan → apm-write-assumptions}/assumptions-template.md

@@ -2,9 +2,11 @@
 
 > 本文件由 apm sync-document 写入；PM 确认后服务端回写「状态/确认结果」。
 > **禁止**手动编辑；已确认条目 AI 禁止修改。
+> 编写与校验规则见 `.apm/skills/apm-write-assumptions/SKILL.md`。
 
 #### A1
-- **问**：（业务语言问句，禁止字段名/文件路径）
+
+- **问**：（业务语言问句；须含：提交/展示/校验/驳回/审批/允许/禁止/筛选/列表/详情/暂存/删除/新增/修改/导出/导入 之一）
 - **场景**：（需求未说明的背景）
 - **选项**：
   - opt_a：（选项说明）

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

@@ -4,11 +4,11 @@
 
 前端 / 后端工程师在任务启动后**直接读原始需求写实现计划**，不经过 PRD。
 
-| 角色 | 产出文档 | 路径 |
-| ---- | -------- | ---- |
-| 后端 | `BACKEND-PLAN.md` + `API.md` | `docs/BACKEND-PLAN.md`、`docs/API.md` |
+| 角色 | 产出文档                                       | 路径                                                    |
+| ---- | ---------------------------------------------- | ------------------------------------------------------- |
+| 后端 | `BACKEND-PLAN.md` + `API.md`                   | `docs/BACKEND-PLAN.md`、`docs/API.md`                   |
 | 前端 | `FRONTEND-PLAN.md` + `FRONTEND-ASSUMPTIONS.md` | `docs/FRONTEND-PLAN.md`、`docs/FRONTEND-ASSUMPTIONS.md` |
-| 后端 | 同上 | `docs/BACKEND-ASSUMPTIONS.md` |
+| 后端 | 同上                                           | `docs/BACKEND-ASSUMPTIONS.md`                           |
 
 ---
 
@@ -27,27 +27,18 @@
 2. 代码调研预算：**最多 15 个文件**。
 3. 口径不清 → 记入 **ASSUMPTIONS 文件**，禁止编造。
 
-### 步骤 3：按模板写计划与假设
+### 步骤 3：写计划与假设
 
 1. **Read** `.apm/skills/apm-write-plan/plan-template.md`，**Write** 本端 `*-PLAN.md`（**不含**假设章节）。
-2. **Read** `.apm/skills/apm-write-plan/assumptions-template.md`，**Write** 本端 `*-ASSUMPTIONS.md`。
-3. 无假设时在 ASSUMPTIONS 中写「无，口径均有依据」。
+2. **Read** 并完整执行 **`.apm/skills/apm-write-assumptions/SKILL.md`**（编写 `*-ASSUMPTIONS.md` → sync；报错则改完重 sync）。
 
-### 步骤 3.5：假设 PM 友好自检（sync 前必做）
+### 步骤 4：同步 PLAN 与回复
 
-每条假设必须含 **问 / 场景 / 选项（≥2 项，id + label）**：
+1. `apm sync-document --file FRONTEND-PLAN.md`（或 BACKEND）。
+2. **有假设且 ASSUMPTIONS 已成功 sync**：@项目经理 请其在 Web **「待您确认」** Panel 点选；说明「以上假设确认前不开始开发」。
+3. **无假设**：`append_message` 发送「本端需求理解」摘要并 @项目经理 请确认。
 
-- **问** 禁止：`status=`、字段名、表名、类路径、SQL。
-- **禁止多选**；复合口径由 PM 在 Web「其他」中填写。
-- 能自己查清的代码含义 → 移入 PLAN「依据」，删除假设。
-- 技术发现 → 写进 **研发备注**，问句用业务语言。
-
-### 步骤 4：同步与回复
-
-1. `apm sync-document --file FRONTEND-ASSUMPTIONS.md`（或 BACKEND）**先于** PLAN。
-2. `apm sync-document --file FRONTEND-PLAN.md`（或 BACKEND）。
-3. **有假设**：@项目经理 请其在 Web **「待您确认」** Panel 点选；说明「以上假设确认前不开始开发」。
-4. **无假设**：`append_message` 发送「本端需求理解」摘要并 @项目经理 请确认。
+> **禁止**在 ASSUMPTIONS sync 未成功时 @ 项目经理确认假设；PLAN 中「待确认 N 项」由服务端 sync ASSUMPTIONS 后自动更新，AI 不要手写具体数字。
 
 ### 假设确认后更新计划
 

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

@@ -1,26 +0,0 @@
-## 工作流程
-
-### 步骤 1: 获取当前版本 PRD 的内容
-
-先用 **Read** 工具阅读 `.apm/sessions/<会话ID>/docs/PRD.md`，如果存在则这个目录下的内容为需求文档，否则用 **Read** 工具阅读 `.apm/sessions/<会话ID>/TASK.md`，并把这个文件里面的内容视为需求文档
-
-### 步骤 2: 理解代码，给出评审意见，具体要求如下：
-
-#### 评审目标如下：
-
-1. 梳理需求边界：发现文档中未写清的口径
-2. 调研实现难度：在实现难度较高时给出提示
-3. 禁止为了凑问题而提问，当 PRD 已足够清晰且无高难度改造时，可直接说此任务没问题
-4. 你只需要站在自己的角度去评审，禁止站在全局思考问题。结合代码进行评审即可：
-   - 前端关注 UI 交互还原，交互逻辑的各种边界，不考虑一些与后端接口之类的问题
-   - 后端则关注数据表设计，需求对应的数据接口是否合理，能否获取
-   - 全栈则关注前面两者，可以把这些问题合并起来提出来
-
-**难度高的定义**：预估改动的文件可能比较多，超过 10 个；或者改动逻辑比较复杂；
-
-#### 表达规范如下
-
-1. **产品语言优先**：页面定位用「医德考评弹窗」「行风办审批页」等说法；**禁止**用文件路径、组件名、函数名作为论据主体。
-2. **后端可略宽**：必要时可写**表名 / 主表字段名**帮助产品理解数据口径，但仍避免贴大段代码或接口路径。
-3. **锚定 PRD**：当需要引用到任务文档中的某一条时可以直接说行号，比如：需求原文[1-3]说 xxx；
-4. **问题 = 文档缺口**：只写 PRD **未写清**且**影响本端理解边界**的点。已写清楚的规则不要重复质疑。

package/template/skills/apm-rewrite-assumptions/SKILL.md

@@ -1,12 +0,0 @@
-# apm-rewrite-assumptions：重写 PM 不友好的假设问法
-
-## 何时使用
-
-`apm sync-document` 同步 ASSUMPTIONS 失败（问法校验不通过），或计划被退回需重写「问 / 场景 / 选项」。
-
-## 工作流程
-
-1. **Read** 本端 `docs/FRONTEND-ASSUMPTIONS.md` 或 `docs/BACKEND-ASSUMPTIONS.md`（及 sync 报错中的 qualityIssues）。
-2. 将研发术语移入 **研发备注**；**问** 改为 PM 可理解的业务句子；补全 **场景** 与 **≥2 个选项**（含 id + label）。
-3. **禁止多选**；复合口径说明写在 Other 指引中。
-4. 重新 **`apm sync-document --file *-ASSUMPTIONS.md`** 同步。