ai-project-manage-cli 6.0.52 → 6.0.54

package/dist/index.js

@@ -81,7 +81,7 @@ function buildAgentWsUrl(httpBase, apiKey) {
 
 // src/commands/init.ts
 import { join as join4 } from "path";
-import { readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync4 } from "fs";
 
 // src/command-utils.ts
 import {
@@ -90,7 +90,8 @@ import {
   mkdirSync as mkdirSync2,
   readFileSync as readFileSync2,
   readdirSync,
-  statSync
+  statSync,
+  writeFileSync as writeFileSync2
 } from "fs";
 import { basename, dirname, extname, join as join2, resolve as resolve2 } from "path";
 import { fileURLToPath } from "url";
@@ -183,6 +184,28 @@ function gitignoreIgnoresApm(line) {
   if (!pattern) return false;
   return APM_GITIGNORE_PATTERNS.some((re) => re.test(pattern));
 }
+var APM_GITIGNORE_LINE = "**/.apm/**";
+function ensureApmGitignoredInRepo(workdir) {
+  const gitignorePath = join2(workdir, ".gitignore");
+  const fsGitignorePath = toFsPath(gitignorePath);
+  if (!existsSync(fsGitignorePath)) {
+    writeFileSync2(fsGitignorePath, `${APM_GITIGNORE_LINE}
+`, "utf8");
+    return true;
+  }
+  const content = readFileSync2(fsGitignorePath, "utf8");
+  if (content.split(/\r?\n/).some(gitignoreIgnoresApm)) {
+    return false;
+  }
+  const suffix = content.endsWith("\n") || content.length === 0 ? "" : "\n";
+  writeFileSync2(
+    fsGitignorePath,
+    `${content}${suffix}${APM_GITIGNORE_LINE}
+`,
+    "utf8"
+  );
+  return true;
+}
 function assertApmGitignoredInRepo(workdir) {
   const gitignorePath = join2(workdir, ".gitignore");
   const fsGitignorePath = toFsPath(gitignorePath);
@@ -346,7 +369,7 @@ async function copyTemplateFiles(targetDir, workdir = resolveWorkdirPath()) {
 
 // src/deployment-config-sync.ts
 import { join as join3 } from "path";
-import { writeFileSync as writeFileSync2 } from "fs";
+import { writeFileSync as writeFileSync3 } from "fs";
 
 // src/api/client.ts
 import { createApiClient } from "listpage-http";
@@ -529,11 +552,11 @@ ${diagnostic ?? ""}
   }
   const targetApmDir = apmDir ?? workspaceApmDir(workdirPath);
   const apmConfigPath = toFsPath(join3(targetApmDir, "apm.config.json"));
-  writeFileSync2(apmConfigPath, `${JSON.stringify(parsed, null, 2)}
+  writeFileSync3(apmConfigPath, `${JSON.stringify(parsed, null, 2)}
 `, "utf8");
   const deployDir = join3(targetApmDir, "deploy");
   await ensureDirExists(deployDir);
-  writeFileSync2(
+  writeFileSync3(
     toFsPath(join3(deployDir, "README.md")),
     config.deploymentDoc ?? "",
     "utf8"
@@ -543,10 +566,75 @@ ${diagnostic ?? ""}
   return { synced: true, repositoryId, configName: config.name };
 }
 
+// src/git-utils.ts
+import { execFile as execFile2 } from "child_process";
+import { promisify as promisify2 } from "util";
+var execFileAsync2 = promisify2(execFile2);
+async function execGit(cwd, args, quiet = false) {
+  try {
+    const { stdout, stderr } = await execFileAsync2("git", args, {
+      cwd,
+      encoding: "utf8",
+      maxBuffer: 10 * 1024 * 1024
+    });
+    if (!quiet && stderr.trim()) {
+      process.stderr.write(stderr);
+    }
+    return stdout;
+  } catch (err) {
+    const e = err;
+    const detail = (e.stderr ?? e.message ?? String(err)).trim();
+    throw new Error(
+      `[apm] git ${args.join(" ")} \u5931\u8D25${detail ? `: ${detail}` : ""}`
+    );
+  }
+}
+async function isGitRepo(cwd) {
+  try {
+    await execGit(cwd, ["rev-parse", "--git-dir"], true);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function hasUpstream(cwd) {
+  try {
+    await execGit(cwd, ["rev-parse", "--abbrev-ref", "@{upstream}"], true);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var GITIGNORE_COMMIT_MESSAGE = "chore(apm): ignore .apm directory";
+async function commitAndPushGitignore(workdir) {
+  if (!await isGitRepo(workdir)) {
+    console.log("[apm] \u5F53\u524D\u76EE\u5F55\u4E0D\u662F git \u4ED3\u5E93\uFF0C\u8BF7\u624B\u52A8\u63D0\u4EA4 .gitignore");
+    return;
+  }
+  await execGit(workdir, ["add", "--", ".gitignore"]);
+  await execGit(workdir, ["commit", "-m", GITIGNORE_COMMIT_MESSAGE]);
+  console.log(`[apm] \u5DF2\u63D0\u4EA4 .gitignore: ${GITIGNORE_COMMIT_MESSAGE}`);
+  const originUrl = await tryReadGitOriginUrl(workdir);
+  if (!originUrl) {
+    console.log("[apm] \u672A\u914D\u7F6E remote.origin\uFF0C\u8BF7\u7A0D\u540E\u624B\u52A8 push .gitignore");
+    return;
+  }
+  if (await hasUpstream(workdir)) {
+    await execGit(workdir, ["push"]);
+  } else {
+    await execGit(workdir, ["push", "-u", "origin", "HEAD"]);
+  }
+  console.log("[apm] \u5DF2\u63A8\u9001 .gitignore");
+}
+
 // src/commands/init.ts
 async function runInit(name) {
   const workdir = resolveWorkdirPath();
   await ensureWorkspaceApmDirForInit(workdir);
+  if (ensureApmGitignoredInRepo(workdir)) {
+    console.log("[apm] \u5DF2\u5728 .gitignore \u4E2D\u6DFB\u52A0 **/.apm/**");
+    await commitAndPushGitignore(workdir);
+  }
   const apmDir = workspaceApmDir(workdir);
   await copyTemplateFiles(apmDir, workdir);
   const syncResult = await syncRemoteDeploymentConfig(workdir, apmDir);
@@ -556,7 +644,7 @@ async function runInit(name) {
     const config = readFileSync3(apmConfigPath, "utf8");
     const configJson = JSON.parse(config);
     configJson.name = trimmedName;
-    writeFileSync3(
+    writeFileSync4(
       apmConfigPath,
       `${JSON.stringify(configJson, null, 2)}
 `,
@@ -635,9 +723,9 @@ async function runLogin(opts) {
 }
 
 // src/commands/branch.ts
-import { execFile as execFile2 } from "child_process";
-import { promisify as promisify2 } from "util";
-var execFileAsync2 = promisify2(execFile2);
+import { execFile as execFile3 } from "child_process";
+import { promisify as promisify3 } from "util";
+var execFileAsync3 = promisify3(execFile3);
 var SESSION_BRANCH_PREFIX = "feat/session-";
 function branchNameForSession(sessionId) {
   const id = sessionId.trim();
@@ -659,9 +747,9 @@ function sessionIdFromBranchName(branch) {
   const sessionId = name.slice(SESSION_BRANCH_PREFIX.length).trim();
   return sessionId || null;
 }
-async function execGit(cwd, args, quiet) {
+async function execGit2(cwd, args, quiet) {
   try {
-    const { stdout, stderr } = await execFileAsync2("git", args, {
+    const { stdout, stderr } = await execFileAsync3("git", args, {
       cwd,
       encoding: "utf8",
       maxBuffer: 10 * 1024 * 1024
@@ -679,18 +767,18 @@ async function execGit(cwd, args, quiet) {
   }
 }
 async function ensureGitRepo(cwd) {
-  await execGit(cwd, ["rev-parse", "--git-dir"], true);
+  await execGit2(cwd, ["rev-parse", "--git-dir"], true);
 }
 async function getCurrentBranch(cwd) {
-  const name = (await execGit(cwd, ["rev-parse", "--abbrev-ref", "HEAD"], true)).trim();
+  const name = (await execGit2(cwd, ["rev-parse", "--abbrev-ref", "HEAD"], true)).trim();
   return name;
 }
 async function isWorkingTreeDirty(cwd) {
-  const out = await execGit(cwd, ["status", "--porcelain"], true);
+  const out = await execGit2(cwd, ["status", "--porcelain"], true);
   return out.trim().length > 0;
 }
 async function remoteHeadBranchExists(cwd, branch) {
-  const out = await execGit(
+  const out = await execGit2(
     cwd,
     ["ls-remote", "--heads", "origin", branch],
     true
@@ -699,7 +787,7 @@ async function remoteHeadBranchExists(cwd, branch) {
 }
 async function localBranchExists(cwd, branch) {
   try {
-    await execGit(
+    await execGit2(
       cwd,
       ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`],
       true
@@ -715,8 +803,8 @@ async function commitWorkingTreeIfDirty(cwd, message) {
     return false;
   }
   const commitMessage = message?.trim() || `chore(apm): \u540C\u6B65\u5DE5\u4F5C\u533A (${await getCurrentBranch(cwd)})`;
-  await execGit(cwd, ["add", "-A"]);
-  await execGit(cwd, ["commit", "-m", commitMessage]);
+  await execGit2(cwd, ["add", "-A"]);
+  await execGit2(cwd, ["commit", "-m", commitMessage]);
   console.log(`[apm] \u5DF2\u63D0\u4EA4\u5DE5\u4F5C\u533A\u53D8\u66F4: ${commitMessage}`);
   return true;
 }
@@ -735,7 +823,7 @@ async function ensureFeatureBranch(branch, baselineBranch, options) {
     if (current === branch) {
       await commitWorkingTreeIfDirty(cwd, commitMessage);
     } else {
-      await execGit(cwd, [
+      await execGit2(cwd, [
         "stash",
         "push",
         "-u",
@@ -746,32 +834,32 @@ async function ensureFeatureBranch(branch, baselineBranch, options) {
   }
   const onTargetBranch = await getCurrentBranch(cwd) === branch;
   if (onTargetBranch) {
-    await execGit(cwd, ["fetch", "origin", baselineBranch]);
-    await execGit(cwd, ["merge", `origin/${baselineBranch}`, "--no-edit"]);
+    await execGit2(cwd, ["fetch", "origin", baselineBranch]);
+    await execGit2(cwd, ["merge", `origin/${baselineBranch}`, "--no-edit"]);
   } else {
     const remoteExists = await remoteHeadBranchExists(cwd, branch);
     if (remoteExists) {
-      await execGit(cwd, ["fetch", "origin", branch]);
-      await execGit(cwd, ["checkout", "-B", branch, `origin/${branch}`]);
+      await execGit2(cwd, ["fetch", "origin", branch]);
+      await execGit2(cwd, ["checkout", "-B", branch, `origin/${branch}`]);
     } else if (await localBranchExists(cwd, branch)) {
       if (await getCurrentBranch(cwd) !== branch) {
-        await execGit(cwd, ["checkout", branch]);
+        await execGit2(cwd, ["checkout", branch]);
       }
       console.log(`[apm] \u5206\u652F ${branch} \u5DF2\u5B58\u5728\uFF0C\u8DF3\u8FC7\u521B\u5EFA`);
     } else {
-      await execGit(cwd, ["fetch", "origin", baselineBranch]);
+      await execGit2(cwd, ["fetch", "origin", baselineBranch]);
       try {
-        await execGit(cwd, [
+        await execGit2(cwd, [
           "checkout",
           "-b",
           branch,
           `origin/${baselineBranch}`
         ]);
-        await execGit(cwd, ["push", "-u", "origin", branch]);
+        await execGit2(cwd, ["push", "-u", "origin", branch]);
       } catch (err) {
         if (await localBranchExists(cwd, branch)) {
           if (await getCurrentBranch(cwd) !== branch) {
-            await execGit(cwd, ["checkout", branch]);
+            await execGit2(cwd, ["checkout", branch]);
           }
           console.log(`[apm] \u5206\u652F ${branch} \u5DF2\u5B58\u5728\uFF0C\u8DF3\u8FC7\u521B\u5EFA`);
         } else {
@@ -811,12 +899,12 @@ async function runBranch(sessionId, options = {}) {
 }
 
 // src/commands/clean-branches.ts
-import { execFile as execFile3 } from "child_process";
-import { promisify as promisify3 } from "util";
-var execFileAsync3 = promisify3(execFile3);
-async function execGit2(cwd, args, quiet) {
+import { execFile as execFile4 } from "child_process";
+import { promisify as promisify4 } from "util";
+var execFileAsync4 = promisify4(execFile4);
+async function execGit3(cwd, args, quiet) {
   try {
-    const { stdout, stderr } = await execFileAsync3("git", args, {
+    const { stdout, stderr } = await execFileAsync4("git", args, {
       cwd,
       encoding: "utf8",
       maxBuffer: 10 * 1024 * 1024
@@ -834,21 +922,21 @@ async function execGit2(cwd, args, quiet) {
   }
 }
 async function ensureGitRepo2(cwd) {
-  await execGit2(cwd, ["rev-parse", "--git-dir"], true);
+  await execGit3(cwd, ["rev-parse", "--git-dir"], true);
 }
 async function getCurrentBranch2(cwd) {
-  return (await execGit2(cwd, ["rev-parse", "--abbrev-ref", "HEAD"], true)).trim();
+  return (await execGit3(cwd, ["rev-parse", "--abbrev-ref", "HEAD"], true)).trim();
 }
 async function resolveDefaultBranch(cwd) {
   try {
-    const ref = (await execGit2(cwd, ["symbolic-ref", "refs/remotes/origin/HEAD"], true)).trim();
+    const ref = (await execGit3(cwd, ["symbolic-ref", "refs/remotes/origin/HEAD"], true)).trim();
     const match = ref.match(/^refs\/remotes\/origin\/(.+)$/);
     if (match?.[1]) {
       return match[1];
     }
   } catch {
   }
-  const out = await execGit2(cwd, ["remote", "show", "origin"], true);
+  const out = await execGit3(cwd, ["remote", "show", "origin"], true);
   const headLine = out.split(/\r?\n/).find((line) => line.includes("HEAD branch"));
   const branch = headLine?.split(":").pop()?.trim();
   if (branch) {
@@ -857,7 +945,7 @@ async function resolveDefaultBranch(cwd) {
   throw new Error("[apm] \u65E0\u6CD5\u89E3\u6790 origin \u9ED8\u8BA4\u5206\u652F\uFF0C\u8BF7\u5148\u6267\u884C git fetch origin");
 }
 async function listLocalSessionBranches(cwd) {
-  const out = await execGit2(
+  const out = await execGit3(
     cwd,
     [
       "for-each-ref",
@@ -870,7 +958,7 @@ async function listLocalSessionBranches(cwd) {
   return out.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
 }
 async function listRemoteSessionBranches(cwd) {
-  const out = await execGit2(
+  const out = await execGit3(
     cwd,
     [
       "for-each-ref",
@@ -884,7 +972,7 @@ async function listRemoteSessionBranches(cwd) {
 }
 async function localBranchExists2(cwd, branch) {
   try {
-    await execGit2(
+    await execGit3(
       cwd,
       ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`],
       true
@@ -895,7 +983,7 @@ async function localBranchExists2(cwd, branch) {
   }
 }
 async function remoteBranchExists(cwd, branch) {
-  const out = await execGit2(
+  const out = await execGit3(
     cwd,
     ["ls-remote", "--heads", "origin", branch],
     true
@@ -915,7 +1003,7 @@ async function runCleanBranches(options = {}) {
   const cwd = options.cwd ?? process.cwd();
   const dryRun = options.dryRun ?? false;
   await ensureGitRepo2(cwd);
-  await execGit2(cwd, ["fetch", "--prune", "origin"], true);
+  await execGit3(cwd, ["fetch", "--prune", "origin"], true);
   const cfg = await ensureLoggedConfig();
   const api = createApmApiClient(cfg);
   const { sessions } = await api.cli.listSessionsForBranchCleanup({});
@@ -956,15 +1044,15 @@ async function runCleanBranches(options = {}) {
     }
     if (currentBranch === branch) {
       defaultBranch ??= await resolveDefaultBranch(cwd);
-      await execGit2(cwd, ["checkout", defaultBranch], true);
+      await execGit3(cwd, ["checkout", defaultBranch], true);
       currentBranch = defaultBranch;
     }
     if (await localBranchExists2(cwd, branch)) {
-      await execGit2(cwd, ["branch", "-D", branch], true);
+      await execGit3(cwd, ["branch", "-D", branch], true);
       console.log(`[apm] \u5DF2\u5220\u9664\u672C\u5730\u5206\u652F ${branch}`);
     }
     if (await remoteBranchExists(cwd, branch)) {
-      await execGit2(cwd, ["push", "origin", "--delete", branch], true);
+      await execGit3(cwd, ["push", "origin", "--delete", branch], true);
       console.log(`[apm] \u5DF2\u5220\u9664\u8FDC\u7A0B\u5206\u652F origin/${branch}`);
     }
   }
@@ -976,7 +1064,7 @@ async function runCleanBranches(options = {}) {
 }
 
 // src/commands/pull.ts
-import { writeFileSync as writeFileSync7 } from "fs";
+import { writeFileSync as writeFileSync8 } from "fs";
 import { join as join8 } from "path";
 import { stringify as yamlStringify } from "yaml";
 
@@ -1010,7 +1098,7 @@ function formatSessionMessagesXml(sessionId, messages) {
 }
 
 // src/commands/sync-session-attachments.ts
-import { existsSync as existsSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync5 } from "fs";
 import { join as join5 } from "path";
 var MANIFEST_FILE = ".sync-manifest.json";
 async function downloadAttachment(cfg, attachmentId) {
@@ -1041,7 +1129,7 @@ function loadManifest(dir) {
   return { version: 1, attachments: {} };
 }
 function saveManifest(dir, manifest) {
-  writeFileSync4(
+  writeFileSync5(
     join5(dir, MANIFEST_FILE),
     `${JSON.stringify(manifest, null, 2)}
 `,
@@ -1075,7 +1163,7 @@ async function syncSessionAttachments(cfg, sessionId, attachments, apmRoot) {
       continue;
     }
     const buffer = await downloadAttachment(cfg, item.id);
-    writeFileSync4(dest, buffer);
+    writeFileSync5(dest, buffer);
     nextManifest.attachments[item.id] = {
       name: item.name,
       createdAt
@@ -1087,7 +1175,7 @@ async function syncSessionAttachments(cfg, sessionId, attachments, apmRoot) {
 
 // src/rules-sync.ts
 import { basename as basename2, extname as extname2, join as join7 } from "path";
-import { existsSync as existsSync5, readFileSync as readFileSync5, rmSync as rmSync2, writeFileSync as writeFileSync6 } from "fs";
+import { existsSync as existsSync5, readFileSync as readFileSync5, rmSync as rmSync2, writeFileSync as writeFileSync7 } from "fs";
 
 // src/skills-sync.ts
 import {
@@ -1098,7 +1186,7 @@ import {
   readdirSync as readdirSync2,
   rmSync,
   statSync as statSync2,
-  writeFileSync as writeFileSync5
+  writeFileSync as writeFileSync6
 } from "fs";
 import { join as join6 } from "path";
 var AGENTS_TEMPLATE_PATH = join6(CLI_TEMPLATE_DIR, "AGENTS.md");
@@ -1163,7 +1251,7 @@ function syncSupplementarySkills(skillsDir, list) {
     }
     const skillDir = join6(skillsDir, dirName);
     mkdirSync3(skillDir, { recursive: true });
-    writeFileSync5(join6(skillDir, "SKILL.md"), skill.content ?? "", "utf8");
+    writeFileSync6(join6(skillDir, "SKILL.md"), skill.content ?? "", "utf8");
     written.push(dirName);
   }
   const removed = [];
@@ -1205,7 +1293,7 @@ function loadManifest2(rulesDir) {
   return { version: 1, rules: {} };
 }
 function saveManifest2(rulesDir, manifest) {
-  writeFileSync6(
+  writeFileSync7(
     toFsPath(join7(rulesDir, MANIFEST_FILE2)),
     `${JSON.stringify(manifest, null, 2)}
 `,
@@ -1253,7 +1341,7 @@ async function syncPlatformRules(cfg, sessionId, workdirPath, apmRoot) {
       console.log(`[apm] \u89C4\u5219\u65E0\u53D8\u5316\uFF0C\u5DF2\u8DF3\u8FC7: rules/${fileName}`);
       continue;
     }
-    writeFileSync6(toFsPath(dest), rule.content ?? "", "utf8");
+    writeFileSync7(toFsPath(dest), rule.content ?? "", "utf8");
     nextManifest.rules[rule.id] = { fileName, updatedAt };
     written.push(fileName);
     console.log(`[apm] \u5DF2\u540C\u6B65\u5E73\u53F0\u89C4\u5219: rules/${fileName}`);
@@ -1296,20 +1384,20 @@ async function runPull(sessionId, remoteWorkdir) {
   const dir = sessionDir(trimmedId, apmRoot);
   const docsDir = sessionDocsDir(trimmedId, apmRoot);
   await ensureDirExists(docsDir);
-  writeFileSync7(
+  writeFileSync8(
     sessionRulePath(trimmedId, apmRoot),
     detail.description ?? "",
     "utf8"
   );
-  writeFileSync7(
+  writeFileSync8(
     sessionTaskPath(trimmedId, apmRoot),
     detail.task.description ?? "",
     "utf8"
   );
-  writeFileSync7(sessionTodoPath(trimmedId, apmRoot), detail.todo ?? "", "utf8");
+  writeFileSync8(sessionTodoPath(trimmedId, apmRoot), detail.todo ?? "", "utf8");
   for (const doc of documents) {
     const fileName = documentLocalFileName(doc.name);
-    writeFileSync7(join8(docsDir, fileName), doc.content ?? "", "utf8");
+    writeFileSync8(join8(docsDir, fileName), doc.content ?? "", "utf8");
   }
   const sessionYaml = yamlStringify(
     {
@@ -1326,13 +1414,13 @@ async function runPull(sessionId, remoteWorkdir) {
     },
     { lineWidth: 0 }
   );
-  writeFileSync7(
+  writeFileSync8(
     sessionYamlPath(trimmedId, apmRoot),
     sessionYaml.endsWith("\n") ? sessionYaml : `${sessionYaml}
 `,
     "utf8"
   );
-  writeFileSync7(
+  writeFileSync8(
     sessionMessagesXmlPath(trimmedId, apmRoot),
     formatSessionMessagesXml(trimmedId, messages),
     "utf8"
@@ -1976,7 +2064,7 @@ ${JSON.stringify(event, null, 2)}
 }
 
 // src/commands/connect/agent-session-registry.ts
-import { existsSync as existsSync10, mkdirSync as mkdirSync5, readFileSync as readFileSync8, writeFileSync as writeFileSync8 } from "node:fs";
+import { existsSync as existsSync10, mkdirSync as mkdirSync5, readFileSync as readFileSync8, writeFileSync as writeFileSync9 } from "node:fs";
 import { dirname as dirname3, resolve as resolve3 } from "node:path";
 function registryPath(workdir, sessionId) {
   return resolve3(workdir, ".apm", "sessions", sessionId, "cursor-agents.json");
@@ -2004,7 +2092,7 @@ function readRegistry(path10) {
 }
 function writeRegistry(path10, registry) {
   mkdirSync5(dirname3(path10), { recursive: true });
-  writeFileSync8(path10, `${JSON.stringify(registry, null, 2)}
+  writeFileSync9(path10, `${JSON.stringify(registry, null, 2)}
 `, "utf8");
 }
 function loadSessionAgentId(workdir, sessionId, user) {
@@ -2333,7 +2421,7 @@ function markPullDone(sessionId, workdir) {
 }
 
 // src/commands/connect/run-slot-pool.ts
-var DEFAULT_MAX_CONCURRENT = 2;
+var DEFAULT_MAX_CONCURRENT = 5;
 function createRunSlotPool(maxConcurrent = DEFAULT_MAX_CONCURRENT) {
   let active = 0;
   const waiters = [];

package/package.json

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

package/template/deploy/README.md

@@ -4,12 +4,12 @@
 部署线上环境： `npm run deploy:online`
 
 ## 后端部署（不区分正式环境和测试环境）
-`python scripts/deploy.py`
+`python .apm/deploy/deploy.py`
 
 ## 前端产物下载地址
 
 http://<服务器地址>/dist.zip
-http://<服务器地址>/backend_update_jar.zip
+http://<服务器地址>/{name}.jar.zip
 
 ## 测试地址
-http://<测试环境>
+http://<服务器地址>

package/template/deploy/deploy.py

@@ -0,0 +1,564 @@
+#!/usr/bin/env python3
+"""自动部署脚本"""
+
+from __future__ import annotations
+
+import json
+import posixpath
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+import time
+import zipfile
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import paramiko
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+PROJECT_ROOT = SCRIPT_DIR.parent.parent
+APM_CONFIG_PATH = PROJECT_ROOT / ".apm" / "apm.config.json"
+DEPLOY_CACHE_DIR = SCRIPT_DIR / ".deploy_cache"
+MANIFEST_FILE = DEPLOY_CACHE_DIR / "manifest.json"
+SPRINGBOOT_SCRIPT = "springboot.sh"
+MAVEN_MODULE = "jeecg-module-system/jeecg-system-start"
+MAVEN_PROFILE = "dev"
+
+if sys.platform == "win32" and hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")
+    sys.stderr.reconfigure(encoding="utf-8")
+
+
+def log(message: str) -> None:
+    print(f"[{datetime.now().strftime('%H:%M:%S')}] {message}")
+
+
+def fail(message: str, code: int = 1) -> None:
+    log(f"ERROR: {message}")
+    sys.exit(code)
+
+
+def expand_path(path_str: str) -> Path:
+    return Path(path_str).expanduser().resolve()
+
+
+def load_apm_config(apm_path: Path) -> dict[str, Any]:
+    with apm_path.open("r", encoding="utf-8") as handle:
+        data = json.load(handle)
+
+    name = str(data["name"]).strip()
+    deploy = data["wisdomDeploy"]
+    health = data["healthCheck"]
+
+    jar_path = str(deploy["jarPath"]).strip()
+    remote_app_dir = posixpath.dirname(jar_path)
+
+    return {
+        "project_name": name,
+        "host": deploy["host"],
+        "port": deploy["port"],
+        "username": deploy["username"],
+        "password": deploy["password"],
+        "remote_vue_dist_dir": str(deploy["remotePath"]).strip(),
+        "remote_app_dir": remote_app_dir,
+        "remote_lib_dir": posixpath.join(remote_app_dir, "lib"),
+        "startup_jar": posixpath.basename(jar_path),
+        "package_name": f"{name}.jar.zip",
+        "maven_local_repo": str(deploy["mavenLocalRepo"]).strip(),
+        "health_check_port": health["port"],
+        "health_check_context": health["context"],
+        "health_check_timeout": health["timeout"],
+    }
+
+
+def load_config() -> dict[str, Any]:
+    return load_apm_config(APM_CONFIG_PATH)
+
+
+def get_target_dir() -> Path:
+    return PROJECT_ROOT / MAVEN_MODULE / "target"
+
+
+def get_maven_local_repo(config: dict[str, Any]) -> Path:
+    return expand_path(str(config["maven_local_repo"]).strip())
+
+
+@dataclass
+class UpdateEntry:
+    path: Path
+    arcname: str
+    reason: str
+
+
+def relative_key(path: Path) -> str:
+    return path.resolve().relative_to(PROJECT_ROOT.resolve()).as_posix()
+
+
+def file_signature(path: Path) -> dict[str, float | int]:
+    stat = path.stat()
+    return {"size": int(stat.st_size), "mtime": float(stat.st_mtime)}
+
+
+def load_manifest() -> dict[str, dict[str, float | int]]:
+    if not MANIFEST_FILE.exists():
+        return {}
+    with MANIFEST_FILE.open("r", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def save_manifest(manifest: dict[str, dict[str, float | int]]) -> None:
+    DEPLOY_CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    with MANIFEST_FILE.open("w", encoding="utf-8") as handle:
+        json.dump(manifest, handle, ensure_ascii=False, indent=2)
+
+
+def is_project_lib_jar(jar_name: str) -> bool:
+    return jar_name.startswith("jeecg-")
+
+
+def list_lib_files_to_upload(
+    local_lib_dir: Path,
+    remote_stats: dict[str, paramiko.SFTPAttributes],
+    *,
+    manifest: dict[str, dict[str, float | int]] | None = None,
+) -> list[UpdateEntry]:
+    entries: list[UpdateEntry] = []
+    for jar_file in sorted(local_lib_dir.glob("*.jar")):
+        remote_attr = remote_stats.get(jar_file.name)
+        should_upload, reason = should_upload_lib_file(
+            jar_file,
+            remote_attr,
+            manifest,
+        )
+        if should_upload:
+            entries.append(
+                UpdateEntry(
+                    path=jar_file,
+                    arcname=jar_file.name,
+                    reason=reason,
+                )
+            )
+    return entries
+
+
+def create_update_package(entries: list[UpdateEntry], package_name: str) -> Path:
+    DEPLOY_CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    zip_path = DEPLOY_CACHE_DIR / package_name
+
+    log(f"创建更新包: {zip_path.name}（{len(entries)} 个文件）")
+    with zipfile.ZipFile(zip_path, "w", compression=zipfile.ZIP_DEFLATED) as archive:
+        for entry in entries:
+            archive.write(entry.path, arcname=entry.arcname)
+            log(f"  打包: {entry.arcname} ({entry.reason})")
+
+    return zip_path
+
+
+def upload_update_package(
+    sftp: paramiko.SFTPClient,
+    zip_path: Path,
+    config: dict[str, Any],
+) -> str:
+    remote_dir = config["remote_vue_dist_dir"]
+    remote_path = f"{remote_dir}/{zip_path.name}"
+
+    log(f"上传更新包 -> {remote_path}")
+
+    try:
+        sftp.put(str(zip_path), remote_path)
+        log("更新包上传成功")
+    except OSError as exc:
+        fail(f"更新包上传失败: {exc}")
+
+    return remote_path
+
+
+def update_manifest_entries(
+    manifest: dict[str, dict[str, float | int]],
+    entries: list[UpdateEntry],
+) -> dict[str, dict[str, float | int]]:
+    for entry in entries:
+        manifest[relative_key(entry.path)] = file_signature(entry.path)
+    return manifest
+
+
+def get_remote_file_stats(
+    sftp: paramiko.SFTPClient,
+    remote_dir: str,
+) -> dict[str, paramiko.SFTPAttributes]:
+    stats: dict[str, paramiko.SFTPAttributes] = {}
+    try:
+        for attr in sftp.listdir_attr(remote_dir):
+            if attr.filename.endswith(".jar"):
+                stats[attr.filename] = attr
+    except FileNotFoundError:
+        pass
+    return stats
+
+
+def should_upload_lib_file(
+    local_path: Path,
+    remote_attr: paramiko.SFTPAttributes | None,
+    manifest: dict[str, dict[str, float | int]] | None = None,
+) -> tuple[bool, str]:
+    if remote_attr is None:
+        return False, "远程不存在，跳过"
+
+    local_size = int(local_path.stat().st_size)
+    remote_size = int(remote_attr.st_size)
+    if local_size != remote_size:
+        return True, f"大小变化 {remote_size} -> {local_size}"
+
+    if is_project_lib_jar(local_path.name) and manifest is not None:
+        key = relative_key(local_path)
+        current = file_signature(local_path)
+        previous = manifest.get(key)
+        if previous is None:
+            return True, "项目模块未记录"
+        if int(previous["size"]) != current["size"]:
+            return True, "项目模块大小变化"
+        if float(previous["mtime"]) < current["mtime"]:
+            return True, "项目模块重新构建"
+
+    return False, "大小一致，跳过"
+
+
+def get_mvn_executable() -> str:
+    candidates = ("mvn.cmd", "mvn.bat", "mvn") if sys.platform == "win32" else ("mvn",)
+    for name in candidates:
+        found = shutil.which(name)
+        if found:
+            return found
+    fail("未找到 mvn 命令，请确认 Maven 已安装并加入 PATH")
+
+
+def run_maven_build(config: dict[str, Any]) -> None:
+    profile = MAVEN_PROFILE
+    maven_repo = get_maven_local_repo(config)
+    cmd = [
+        get_mvn_executable(),
+        "clean",
+        "package",
+        f"-P{profile}",
+        f"-Dmaven.repo.local={maven_repo}",
+        "-DskipTests",
+    ]
+
+    log(f"开始 Maven 构建: {' '.join(cmd)}")
+    log(f"Maven 本地仓库: {maven_repo}")
+    result = subprocess.run(
+        cmd,
+        cwd=PROJECT_ROOT,
+    )
+    if result.returncode != 0:
+        fail(f"Maven 构建失败，退出码: {result.returncode}")
+
+
+def locate_lib_dir() -> Path:
+    target_dir = get_target_dir()
+    if not target_dir.exists():
+        fail(f"构建产物目录不存在: {target_dir}")
+
+    lib_dir = target_dir / "lib"
+    if not lib_dir.is_dir():
+        fail(f"lib 目录不存在: {lib_dir}")
+
+    lib_jars = list(lib_dir.glob("*.jar"))
+    if not lib_jars:
+        fail(f"lib 目录下没有依赖 JAR: {lib_dir}")
+
+    log(f"定位 lib 产物: {len(lib_jars)} 个")
+    return lib_dir
+
+
+def connect_ssh(config: dict[str, Any]) -> paramiko.SSHClient:
+    client = paramiko.SSHClient()
+    client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
+
+    log(f"连接服务器 {config['username']}@{config['host']}:{config['port']}")
+    connect_kwargs: dict[str, Any] = {
+        "hostname": config["host"],
+        "port": int(config["port"]),
+        "username": config["username"],
+        "password": config["password"],
+        "timeout": 30,
+        "allow_agent": False,
+        "look_for_keys": False,
+    }
+
+    try:
+        client.connect(**connect_kwargs)
+    except Exception as exc:
+        fail(f"SSH 连接失败: {exc}")
+
+    return client
+
+
+def read_channel_stream(channel: paramiko.Channel) -> str:
+    """流式读取 SSH 通道输出，避免长时间命令无回显。"""
+    chunks: list[str] = []
+    while not channel.closed:
+        if channel.recv_ready():
+            data = channel.recv(4096)
+            if not data:
+                break
+            text = data.decode("utf-8", errors="replace")
+            chunks.append(text)
+            print(text, end="", flush=True)
+        elif channel.exit_status_ready():
+            while channel.recv_ready():
+                data = channel.recv(4096)
+                if data:
+                    text = data.decode("utf-8", errors="replace")
+                    chunks.append(text)
+                    print(text, end="", flush=True)
+            break
+        else:
+            time.sleep(0.2)
+
+    combined = "".join(chunks)
+    if combined and not combined.endswith("\n"):
+        print()
+    return combined.strip()
+
+
+def run_remote_command(
+    client: paramiko.SSHClient,
+    command: str,
+    *,
+    check: bool = True,
+    get_pty: bool = False,
+    stream: bool = False,
+    timeout_secs: float | None = None,
+) -> tuple[int, str, str]:
+    log(f"远程执行: {command}")
+    _, stdout, stderr = client.exec_command(command, get_pty=get_pty)
+    channel = stdout.channel
+    if timeout_secs is not None:
+        channel.settimeout(timeout_secs)
+
+    if stream:
+        out = read_channel_stream(channel)
+        err = ""
+    else:
+        out = stdout.read().decode("utf-8", errors="replace").strip()
+        err = "" if get_pty else stderr.read().decode("utf-8", errors="replace").strip()
+
+    exit_code = channel.recv_exit_status()
+
+    if not stream:
+        if out:
+            print(out)
+        if err:
+            print(err, file=sys.stderr)
+
+    if check and exit_code != 0:
+        fail(f"远程命令失败 (exit {exit_code}): {command}")
+
+    return exit_code, out, err
+
+
+def extract_update_package_on_remote(
+    client: paramiko.SSHClient,
+    config: dict[str, Any],
+    remote_zip_path: str,
+) -> int:
+    """解压更新包到 lib 目录，仅覆盖远程已存在的 JAR。"""
+    remote_lib_dir = config["remote_lib_dir"]
+    quoted_zip = shlex.quote(remote_zip_path)
+    quoted_lib = shlex.quote(remote_lib_dir)
+
+    script = f"""
+set -e
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+unzip -oq {quoted_zip} -d "$TMP"
+updated=0
+while IFS= read -r -d '' src; do
+  name=$(basename "$src")
+  dest={quoted_lib}/"$name"
+  if [ -f "$dest" ]; then
+    cp -f "$src" "$dest"
+    echo "覆盖: $name"
+    updated=$((updated + 1))
+  else
+    echo "跳过(远程不存在): $name"
+  fi
+done < <(find "$TMP" -name '*.jar' -type f -print0)
+echo "UPDATED_COUNT=$updated"
+"""
+
+    _, out, _ = run_remote_command(client, script)
+    match = re.search(r"UPDATED_COUNT=(\d+)", out)
+    if not match:
+        fail(f"远程解压失败，未获取更新数量\n输出: {out or '(空)'}")
+
+    updated = int(match.group(1))
+    log(f"lib 解压完成: 覆盖 {updated} 个")
+    return updated
+
+
+def springboot_output_indicates_success(action: str, combined: str) -> bool:
+    """springboot.sh 经 SSH 执行时 exit code 不可靠，需结合输出判断。"""
+    lower = combined.lower()
+    if action == "health":
+        return "健康检查通过" in combined
+    if action in {"start", "restart"}:
+        return "is starting" in combined or "is running" in lower
+    if action == "stop":
+        return (
+            "is stopping" in combined
+            or "not running" in lower
+            or "please check it" in lower
+        )
+    if action == "status":
+        return "running" in lower or "not running" in lower
+    return True
+
+
+def run_springboot_action(
+    client: paramiko.SSHClient,
+    config: dict[str, Any],
+    action: str,
+    *args: str,
+) -> str:
+    if action in {"start", "restart"}:
+        if not args:
+            fail(f"远程 {action} 缺少 jar 参数")
+        jar = args[0].strip().splitlines()[0].strip()
+        if not jar:
+            fail(f"无效的 jar 名称: {args[0]!r}")
+
+    command = " && ".join(
+        [
+            f"cd {shlex.quote(config['remote_app_dir'])}",
+            " ".join(
+                [f"./{SPRINGBOOT_SCRIPT}", *map(shlex.quote, (action, *args))]
+            ),
+        ]
+    )
+    exit_code, out, err = run_remote_command(
+        client,
+        command,
+        check=False,
+    )
+    combined = f"{out}\n{err}".strip()
+    output_ok = springboot_output_indicates_success(action, combined)
+    if action == "health":
+        if exit_code != 0 or not output_ok:
+            fail(
+                f"健康检查失败\n"
+                f"命令: {command}\n输出: {combined or '(空)'}"
+            )
+        return combined
+    if exit_code != 0 and not output_ok:
+        fail(f"远程 {action} 失败: {' '.join(args)}\n{combined}")
+    if action in {"start", "restart"} and not output_ok:
+        fail(
+            f"远程 {action} 未成功: {' '.join(args)}\n"
+            f"命令: {command}\n输出: {combined or '(空)'}"
+        )
+    return combined
+
+
+def get_running_jar(
+    client: paramiko.SSHClient,
+    app_dir: str,
+    config: dict[str, Any],
+) -> str | None:
+    combined = run_springboot_action(
+        client, config, "status", config["startup_jar"]
+    )
+    text = re.sub(r"\x1b\[[0-?]*[ -/]*[@-~]", "", combined).strip().lower()
+    if "not running" in text:
+        return None
+    if "running" in text:
+        return config["startup_jar"]
+    return None
+
+
+def health_check_service(
+    client: paramiko.SSHClient,
+    config: dict[str, Any],
+) -> None:
+    port = str(int(config["health_check_port"]))
+    context = str(config["health_check_context"]).strip()
+    timeout = str(int(config["health_check_timeout"]))
+    log(f"健康检查: springboot.sh health {port} {context} {timeout}")
+    run_springboot_action(client, config, "health", port, context, timeout)
+
+
+def main() -> None:
+    config = load_config()
+
+    log(f"=== 自动部署: {config['project_name']} ===")
+    log(f"配置文件: {APM_CONFIG_PATH}")
+    log(f"项目根目录: {PROJECT_ROOT}")
+
+    run_maven_build(config)
+
+    lib_dir = locate_lib_dir()
+    manifest = load_manifest()
+
+    client = connect_ssh(config)
+    need_restart = False
+    lib_upload_entries: list[UpdateEntry] = []
+    try:
+        sftp = client.open_sftp()
+        try:
+            app_dir = config["remote_app_dir"]
+            remote_lib_stats = get_remote_file_stats(sftp, config["remote_lib_dir"])
+
+            log("收集 JAR 更新...")
+            lib_upload_entries = list_lib_files_to_upload(
+                lib_dir,
+                remote_lib_stats,
+                manifest=manifest,
+            )
+
+            updated = 0
+            if lib_upload_entries:
+                zip_path = create_update_package(
+                    lib_upload_entries,
+                    config["package_name"],
+                )
+                remote_zip_path = upload_update_package(sftp, zip_path, config)
+                log("远程解压 lib 目录（仅覆盖已有 JAR）...")
+                updated = extract_update_package_on_remote(
+                    client,
+                    config,
+                    remote_zip_path,
+                )
+            else:
+                log("无 JAR 需要更新，跳过更新包上传")
+
+            running_jar = get_running_jar(client, app_dir, config)
+            need_restart = updated > 0
+            if not need_restart and not running_jar:
+                log("服务未运行，需要启动")
+                need_restart = True
+            elif not need_restart:
+                log("没有文件需要更新，跳过重启")
+
+            if need_restart:
+                log("重启服务...")
+                run_springboot_action(client, config, "restart", config["startup_jar"])
+
+            health_check_service(client, config)
+
+            if lib_upload_entries:
+                save_manifest(update_manifest_entries(manifest, lib_upload_entries))
+        finally:
+            sftp.close()
+    finally:
+        client.close()
+
+    log("部署完成")
+
+
+if __name__ == "__main__":
+    main()

package/template/rules/write_doc.md

@@ -16,6 +16,13 @@
 保存位置: .apm/sessions/<会话 ID>/docs/<文件名>
 文档内容格式: 根据你的主题来，不限制，禁止记流水账。
 
+## SQL 变更文档（仅后端）
+
+固定文件名: `SQL.md`
+保存位置: `.apm/sessions/<会话 ID>/docs/SQL.md`
+适用场景: 后端开发涉及 SQL 改动（DDL/DML、表结构、Mapper/XML 中 SQL 等）时必须产出或追加更新，详见 `.apm/skills/apm-dev/SKILL.md` 中「后端 SQL 变更文档」章节。
+格式要求: 待执行的 SQL 语句须放在 ` ```sql ` 代码块中，按执行顺序逐条列出。
+
 ## 文档同步
 
 保存到 `docs/` 后，`apm connect` 会在每轮 Agent 结束时自动推送到平台，无需额外操作。
@@ -24,5 +31,5 @@
 
 1. 文档内容可以被其他团队成员看到，要有价值，禁止记流水账
 2. 你可以根据你的名字查到自己写的文档，并且禁止更改其他人写的文档
-3. 不要随便创建新文档，可以在已有文档的基础上添加内容
+3. 不要随便创建新文档，可以在已有文档的基础上添加内容（`SQL.md` 为后端 SQL 变更的固定交付文档，除外）
 4. 文档不可删除，不可更新文档名称，在写入时要谨慎

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

@@ -10,7 +10,7 @@
    - 「假设」仍有未确认项：**Read** `.apm/sessions/<会话ID>/messages.xml`，查找项目经理是否已回复确认；
    - 项目经理已回复：先按 `.apm/skills/apm-write-plan/SKILL.md` 步骤 5 把确认结果**回填进计划文档并同步**（确认的假设移入「依据」，否定的修订实现步骤与白名单），然后再开发；
    - 项目经理未回复：`@项目经理` 列出待确认假设，**停止本次开发**。
-   严禁带着未回填的澄清直接开发——项目经理在聊天里给过的口径若没落进计划，开发与 diff 评审都不会认。
+     严禁带着未回填的澄清直接开发——项目经理在聊天里给过的口径若没落进计划，开发与 diff 评审都不会认。
 
 ### 步骤 2: 明确开发模式
 
@@ -36,15 +36,41 @@
   - 按计划直接改代码；遵守本仓库构建与依赖约定（AGENTS.md）。
   - **白名单约束**：只改计划白名单内的文件。开发中确需新增文件或改动白名单外文件，先更新计划文档的白名单（写明原因），再动手；**禁止悄悄越界**。
   - **Git**：实现与自洽验收通过后，若有代码改动，**立即 `git add` + `git commit` 一次**（Quick 通常为单次交付，**一次实现 = 一个 commit**；勿拆成无意义碎 commit）。提交信息建议包含 `sessionId`（可从 `session.yaml` 获取）与需求摘要。
-  - 完成后在返回中说明：改了哪些路径、与白名单的对账结果（逐文件列出）、是否通过本地可执行的检查（若子 Agent 跑了构建/测试则写明结果）；若有 commit，写明 **short-sha** 与 **subject**，无代码改动则注明跳过 commit。
+  - **后端 SQL 文档**（仅后端）：改动涉及 SQL 时，须 **Write** `docs/SQL.md`（见下文「后端 SQL 变更文档」）。
+  - 完成后在返回中说明：改了哪些路径、与白名单的对账结果（逐文件列出）、是否产出/更新 `SQL.md`、是否通过本地可执行的检查（若子 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 约定；同样遵守计划「改动文件白名单」；**后端**改动涉及 SQL 时须产出 `docs/SQL.md`（见下文「后端 SQL 变更文档」）。
 4. 若 **apm-propose** 未产出可用 **`plans/tasks.md`**，不得强行进入 **apm-apply-change**；表格中标记阻塞原因。
 
+### 后端 SQL 变更文档（仅后端工程师）
+
+若本次改动涉及 SQL（DDL/DML、表结构、索引、数据修复、Mapper/XML 中新增或修改 SQL 语句等），开发阶段必须 **Write** `.apm/sessions/<会话ID>/docs/SQL.md`，内容包括：
+
+- 变更摘要（改了什么表/数据、为什么）
+- 完整 SQL 语句（按执行顺序排列；**每条须放在 ` ```sql ` 代码块中**，便于复制执行）
+- 执行环境说明（测试/生产是否一致、是否需人工执行）
+- 回滚方案（如适用；回滚 SQL 同样用 ` ```sql ` 代码块）
+
+示例：
+
+````markdown
+## 变更摘要
+
+为 inspection_class 表新增 is_project_add 字段。
+
+## 执行 SQL
+
+```sql
+ALTER TABLE inspection_class ADD COLUMN is_project_add VARCHAR(1) DEFAULT '0';
+```
+````
+
+`BACKEND-PLAN.md` 中不写大段 SQL，只可在实现步骤中注明「须产出 SQL.md」。若会话 `docs/` 下已有 `SQL.md`，在其上追加本次变更，勿另建其他 SQL 文档。
+
 ### 步骤 5: 提交并 push 代码，保证工作区干净
 
 - Quick / Spec 子 Agent 完成且本地已有 commit 时，父 Agent **立即 `git push`**（当前分支首次 push 用 `git push -u origin HEAD`）。
@@ -55,7 +81,7 @@
 开发完成的定义是以下三项**全部满足**，缺一不可：
 
 1. **构建通过**：执行本仓库的构建/检查命令（见 AGENTS.md 或部署文档），失败必须修复后重试。
-2. **发布测试环境**：**Read** `.apm/skills/apm-deploy/SKILL.md` 并按其流程部署；部署涉及 SQL 变更时，在回复中明确写出待执行的 SQL 文件名。
+2. **发布测试环境**：**Read** `.apm/skills/apm-deploy/SKILL.md` 并按其流程部署；**后端**涉及 SQL 变更时，须在回复中引用 `docs/SQL.md`，并写明待执行的 SQL 文件名或执行顺序。
 3. **白名单对账**：在回复中逐文件列出本次改动与计划白名单的对应关系。
 
 **注意：不做联调。** 前后端各自按 API 契约交付，接口对不上属于契约或实现问题，由 diff 评审与人工验收暴露后打回修复；禁止自行发起「联调」「接口实测」类的开放式动作。

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

@@ -16,13 +16,14 @@
 2. 在工作目录执行 `git log --oneline -20`，找到本任务相关的 commit（提交信息中含会话 ID 或需求关键词）。
 3. `git diff <基线>..HEAD --stat` 与 `git diff <基线>..HEAD` 查看完整改动。
 
-### 步骤 2：三项检查
-
-| 检查项         | 判定                                                                 |
-| -------------- | -------------------------------------------------------------------- |
-| **白名单对账** | diff 中出现白名单之外的文件，且计划未更新说明 → **不通过**           |
-| **需求相关性** | 存在与本需求无关的改动（顺手重构、改格式、动了无关逻辑）→ **不通过** |
-| **计划落实**   | 计划「实现步骤」中的关键点在 diff 中找不到对应实现 → **不通过**      |
+### 步骤 2：四项检查
+
+| 检查项         | 判定                                                                                                                      |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| **白名单对账** | diff 中出现白名单之外的文件，且计划未更新说明 → **不通过**                                                                |
+| **需求相关性** | 存在与本需求无关的改动（顺手重构、改格式、动了无关逻辑）→ **不通过**                                                      |
+| **计划落实**   | 计划「实现步骤」中的关键点在 diff 中找不到对应实现 → **不通过**                                                           |
+| **SQL 文档**   | **仅后端**：diff 涉及 SQL 改动（DDL/DML、表结构、Mapper/XML 中 SQL 等），但 `docs/SQL.md` 缺失或与改动不一致 → **不通过** |
 
 注意事项：
 

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

@@ -35,6 +35,7 @@
 1. **依据与假设**：每条关键口径标注来源（需求原文第几条 / 现有代码行为 / 已有文档）；标不出来源的就是「假设」，单独列出。
 2. **改动文件白名单**：本次允许改动的文件完整列表。后续开发与 diff 评审都以此为准，**开发时改了白名单之外的文件会被打回**。
 3. **后端专属——API 契约**：给前端看的接口定义（Path、参数、响应示例、错误码）。前端开发以契约为准，不等后端部署完成。
+4. **后端专属——SQL 变更声明**（仅当涉及表结构/数据变更时）：在「实现步骤」中注明开发须产出 `docs/SQL.md`；计划本身不写大段 SQL，完整语句由后端开发阶段写入该文档。
 
 ### 步骤 4：回复
 
@@ -62,7 +63,7 @@
 
 ## 写作要求
 
-- 篇幅 **40 ～ 100 行**，宁可少写；不要伪代码、不要大段 SQL。
+- 篇幅 **40 ～ 100 行**，宁可少写；不要伪代码、不要大段 SQL（完整语句写入 `docs/SQL.md`，由后端开发阶段产出）。
 - 用产品语言描述行为，文件路径只出现在「改动文件白名单」。
 - 前后端可同轮并行编写计划，不互相阻塞。
 

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

@@ -8,17 +8,17 @@
 
 ## 1. 需求理解
 
-用 3～5 行复述本端要做什么（产品语言），不复制需求原文。
+用 3 ～ 5 行复述本端要做什么（产品语言），不复制需求原文。
 
 ## 2. 依据与假设
 
 ### 依据（口径 + 来源）
 
-| # | 口径 | 来源 |
-|---|------|------|
-| 1 | 「是否加分」与「是否扣分」互斥 | 需求原文第 1 条 |
-| 2 | 加分项不汇总进分类分值 | 需求原文第 2 条 |
-| 3 | 分值字段现状为 varchar | 代码现状：inspection_class 表 |
+| #   | 口径                           | 来源                          |
+| --- | ------------------------------ | ----------------------------- |
+| 1   | 「是否加分」与「是否扣分」互斥 | 需求原文第 1 条               |
+| 2   | 加分项不汇总进分类分值         | 需求原文第 2 条               |
+| 3   | 分值字段现状为 varchar         | 代码现状：inspection_class 表 |
 
 ### 假设（待项目经理确认，确认前不开发）
 
@@ -31,7 +31,9 @@
 
 1. 第一步做什么（对应哪条口径）
 2. 第二步做什么
-3. ...（通常 3～6 步，不写代码细节）
+3. ...（通常 3 ～ 6 步，不写代码细节）
+
+> **后端**：若涉及表结构或数据变更，在步骤中注明「开发须产出 `docs/SQL.md`」，SQL 语句不写在本计划内。
 
 ## 4. 改动文件白名单
 
@@ -49,13 +51,13 @@
 - Path：`POST /inspection/project/save`
 - 新增入参：
 
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| isProjectAdd | string | 否 | "1"=加分项；与 isProjectDed 互斥 |
+| 字段         | 类型   | 必填 | 说明                             |
+| ------------ | ------ | ---- | -------------------------------- |
+| isProjectAdd | string | 否   | "1"=加分项；与 isProjectDed 互斥 |
 
 - 响应示例：
 
-    { "success": true, "result": { "id": "xxx" } }
+  { "success": true, "result": { "id": "xxx" } }
 
 - 错误码：互斥冲突返回 `success=false, message="加分与扣分不可同时勾选"`