ai-project-manage-cli 7.1.13 → 7.1.15

package/README.md

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

package/dist/index.js

@@ -212,10 +212,18 @@ var init_request_config = __esm({
           method: "PUT",
           path: "/cli/webide/terminals/meta"
         }),
+        acquireSteelBrowser: defineEndpoint({
+          method: "POST",
+          path: "/cli/steel-browser/acquire"
+        }),
         branchBaseline: defineEndpoint({
           method: "GET",
           path: "/cli/tasks/branch-baseline"
         }),
+        projectBaseBranch: defineEndpoint({
+          method: "GET",
+          path: "/cli/tasks/project-base-branch"
+        }),
         listSessionsForBranchCleanup: defineEndpoint({
           method: "GET",
           path: "/cli/sessions/branch-cleanup"
@@ -252,21 +260,21 @@ var init_request_config = __esm({
           method: "POST",
           path: "/cli/webide/pull-requests/merge"
         }),
-        getRepositoryProjectDocumentManifest: defineEndpoint({
+        getProjectDocumentManifest: defineEndpoint({
           method: "GET",
-          path: "/cli/repository-project-documents/manifest"
+          path: "/cli/project-documents/manifest"
         }),
-        listRepositoryProjectDocuments: defineEndpoint({
+        listProjectDocuments: defineEndpoint({
           method: "GET",
-          path: "/cli/repository-project-documents"
+          path: "/cli/project-documents"
         }),
-        upsertRepositoryProjectDocument: defineEndpoint({
+        upsertProjectDocument: defineEndpoint({
           method: "PUT",
-          path: "/cli/repository-project-documents/upsert"
+          path: "/cli/project-documents/upsert"
         }),
-        removeRepositoryProjectDocument: defineEndpoint({
+        removeProjectDocument: defineEndpoint({
           method: "DELETE",
-          path: "/cli/repository-project-documents"
+          path: "/cli/project-documents"
         }),
         createTaskDeployment: defineEndpoint({
           method: "POST",
@@ -648,11 +656,33 @@ function forceKillProcessTree(pid) {
     }
   }
 }
+async function listProcessTreePids(rootPid) {
+  const pids = [rootPid];
+  const queue = [rootPid];
+  while (queue.length > 0) {
+    const parent = queue.shift();
+    try {
+      const { stdout } = await execFileAsync3("pgrep", ["-P", String(parent)], {
+        timeout: 2e3
+      });
+      for (const line of stdout.split("\n")) {
+        const child = Number(line.trim());
+        if (child > 0 && !pids.includes(child)) {
+          pids.push(child);
+          queue.push(child);
+        }
+      }
+    } catch {
+    }
+  }
+  return pids;
+}
 async function probeListenPorts(pid) {
   try {
+    const treePids = await listProcessTreePids(pid);
     const { stdout } = await execFileAsync3(
       "lsof",
-      ["-nP", `-p${pid}`, "-iTCP", "-sTCP:LISTEN"],
+      ["-nP", "-a", `-p${treePids.join(",")}`, "-iTCP", "-sTCP:LISTEN"],
       { timeout: 3e3, maxBuffer: 1024 * 1024 }
     );
     const ports = /* @__PURE__ */ new Set();
@@ -944,23 +974,16 @@ var init_webide_terminal_registry = __esm({
         if (!session.pid) return;
         const ports = await probeListenPorts(session.pid);
         if (ports.length === 0) return;
-        let changed = false;
-        for (const p of ports) {
-          if (!session.ports.includes(p)) {
-            session.ports.push(p);
-            changed = true;
-          }
+        const same = ports.length === session.ports.length && ports.every((p, i) => p === session.ports[i]);
+        if (same) return;
+        session.ports = ports;
+        if (!session.primaryUrl && session.ports[0]) {
+          session.primaryUrl = `http://127.0.0.1:${session.ports[0]}`;
         }
-        if (changed) {
-          session.ports.sort((a, b) => a - b);
-          if (!session.primaryUrl && session.ports[0]) {
-            session.primaryUrl = `http://127.0.0.1:${session.ports[0]}`;
-          }
-          if (session.status === "RUNNING" || session.status === "STARTING") {
-            session.status = "READY";
-          }
-          void this.syncStatus(session);
+        if (session.status === "RUNNING" || session.status === "STARTING") {
+          session.status = "READY";
         }
+        void this.syncStatus(session);
       }
       async syncStatus(session) {
         const api = createApmApiClient(this.cfg);
@@ -1629,7 +1652,7 @@ ${diagnostic ?? ""}
   return { synced: true, repositoryId, configName: config.name };
 }
 
-// src/repository-project-documents-sync.ts
+// src/project-documents-sync.ts
 init_client();
 init_config();
 import {
@@ -1643,7 +1666,7 @@ import { createHash } from "crypto";
 import { dirname as dirname2, join as join4, relative, sep } from "path";
 var MANIFEST_FILE = "manifest.json";
 function projectDocumentsDir(apmRoot) {
-  return join4(apmRoot ?? workspaceApmDir(), "project");
+  return join4(apmRoot ?? workspaceApmDir(), "docs");
 }
 function projectDocumentLocalPath(apmRoot, documentPath) {
   const normalized = normalizeLocalDocumentPath(documentPath);
@@ -1720,41 +1743,65 @@ function diffManifestPaths(remote, local) {
   }
   return { download, deleteLocal };
 }
-async function syncRepositoryProjectDocumentsPull(workdirPath, apmDir) {
+async function resolveProjectIdForSync(api, workdirPath) {
+  try {
+    const baseline = await api.cli.workspaceBaseline({ workdirPath });
+    const projectId = baseline.projectId?.trim() || null;
+    if (projectId) {
+      return { projectId, diagnostic: null };
+    }
+    const projectIds = baseline.projectIds ?? [];
+    if (projectIds.length === 0) {
+      return {
+        projectId: null,
+        diagnostic: baseline.diagnostic?.message ?? `\u5DE5\u4F5C\u7A7A\u95F4\u672A\u5173\u8054\u9879\u76EE\uFF0C\u65E0\u6CD5\u540C\u6B65\u9879\u76EE\u6587\u6863\uFF08\u76EE\u5F55\uFF1A${workdirPath}\uFF09\u3002
+\u8BF7\u5728\u5E73\u53F0\u5C06\u5DE5\u4F5C\u7A7A\u95F4\u5173\u8054\u5230\u552F\u4E00\u9879\u76EE\u3002`
+      };
+    }
+    return {
+      projectId: null,
+      diagnostic: `\u5DE5\u4F5C\u7A7A\u95F4\u5173\u8054\u4E86 ${projectIds.length} \u4E2A\u9879\u76EE\uFF0C\u65E0\u6CD5\u786E\u5B9A\u540C\u6B65\u76EE\u6807\u3002
+\u8BF7\u786E\u4FDD\u8BE5\u5DE5\u4F5C\u7A7A\u95F4\u53EA\u5173\u8054\u4E00\u4E2A\u9879\u76EE\u540E\u518D\u540C\u6B65\u9879\u76EE\u6587\u6863\u3002`
+    };
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    return {
+      projectId: null,
+      diagnostic: detail.replace(/^\[apm\]\s*/, "")
+    };
+  }
+}
+async function syncProjectDocumentsPull(workdirPath, apmDir) {
   const empty = {
     synced: false,
-    repositoryId: null,
+    projectId: null,
     downloaded: 0,
     deleted: 0
   };
   const cfg = await tryReadApmConfig();
   if (!cfg || !resolveApiKey(cfg)) {
     console.log(
-      "[apm] \u672A\u68C0\u6D4B\u5230\u767B\u5F55\u4FE1\u606F\uFF0C\u8DF3\u8FC7\u4ED3\u5E93\u9879\u76EE\u6587\u6863\u540C\u6B65\u3002\n[apm] \u8BF7\u5148\u6267\u884C apm login\u3002"
+      "[apm] \u672A\u68C0\u6D4B\u5230\u767B\u5F55\u4FE1\u606F\uFF0C\u8DF3\u8FC7\u9879\u76EE\u6587\u6863\u540C\u6B65\u3002\n[apm] \u8BF7\u5148\u6267\u884C apm login\u3002"
     );
     return empty;
   }
   const api = createApmApiClient(cfg);
-  const { repositoryId, diagnostic } = await resolveRepositoryIdForSync(
+  const { projectId, diagnostic } = await resolveProjectIdForSync(
     api,
     workdirPath
   );
-  if (!repositoryId) {
-    console.log(
-      `[apm] \u672A\u80FD\u540C\u6B65\u4ED3\u5E93\u9879\u76EE\u6587\u6863\u3002
-${diagnostic ?? ""}`
-    );
+  if (!projectId) {
+    console.log(`[apm] \u672A\u80FD\u540C\u6B65\u9879\u76EE\u6587\u6863\u3002
+${diagnostic ?? ""}`);
     return empty;
   }
   const targetApmDir = apmDir ?? workspaceApmDir(workdirPath);
-  const projectDir = projectDocumentsDir(targetApmDir);
-  await ensureDirExists(projectDir);
-  const { manifest: remoteManifest } = await api.cli.getRepositoryProjectDocumentManifest({ repositoryId });
+  const docsDir = projectDocumentsDir(targetApmDir);
+  await ensureDirExists(docsDir);
+  const { manifest: remoteManifest } = await api.cli.getProjectDocumentManifest({ projectId });
   if (!remoteManifest) {
-    console.log(
-      `[apm] \u4ED3\u5E93 ${repositoryId} \u65E0\u9879\u76EE\u6587\u6863 manifest\uFF0C\u8DF3\u8FC7\u540C\u6B65\u3002`
-    );
-    return { ...empty, repositoryId };
+    console.log(`[apm] \u9879\u76EE ${projectId} \u65E0\u9879\u76EE\u6587\u6863 manifest\uFF0C\u8DF3\u8FC7\u540C\u6B65\u3002`);
+    return { ...empty, projectId };
   }
   const localManifest = readLocalManifest(targetApmDir);
   const { download, deleteLocal } = diffManifestPaths(
@@ -1763,12 +1810,14 @@ ${diagnostic ?? ""}`
   );
   let downloaded = 0;
   if (download.length > 0) {
-    const { list } = await api.cli.listRepositoryProjectDocuments({
-      repositoryId,
+    const { list } = await api.cli.listProjectDocuments({
+      projectId,
       paths: download.join(",")
     });
     for (const doc of list) {
-      const absPath = toFsPath(projectDocumentLocalPath(targetApmDir, doc.path));
+      const absPath = toFsPath(
+        projectDocumentLocalPath(targetApmDir, doc.path)
+      );
       await ensureDirExists(dirname2(absPath));
       writeFileSync4(absPath, doc.content, "utf8");
       downloaded += 1;
@@ -1783,34 +1832,34 @@ ${diagnostic ?? ""}`
     }
   }
   writeFileSync4(
-    toFsPath(join4(projectDir, MANIFEST_FILE)),
+    toFsPath(join4(docsDir, MANIFEST_FILE)),
     `${JSON.stringify(remoteManifest, null, 2)}
 `,
     "utf8"
   );
   console.log(
-    `[apm] \u5DF2\u540C\u6B65\u4ED3\u5E93\u9879\u76EE\u6587\u6863: \u4E0B\u8F7D ${downloaded}\uFF0C\u5220\u9664\u672C\u5730 ${deleted}`
+    `[apm] \u5DF2\u540C\u6B65\u9879\u76EE\u6587\u6863: \u4E0B\u8F7D ${downloaded}\uFF0C\u5220\u9664\u672C\u5730 ${deleted}`
   );
   return {
     synced: true,
-    repositoryId,
+    projectId,
     downloaded,
     deleted
   };
 }
-async function syncRepositoryProjectDocumentsPush(cfg, workdirPath, apmRoot) {
+async function syncProjectDocumentsPush(cfg, workdirPath, apmRoot) {
   const api = createApmApiClient(cfg);
-  const { repositoryId } = await resolveRepositoryIdForSync(api, workdirPath);
-  if (!repositoryId) {
+  const { projectId } = await resolveProjectIdForSync(api, workdirPath);
+  if (!projectId) {
     return 0;
   }
   const targetApmDir = apmRoot ?? workspaceApmDir(workdirPath);
   const localPaths = listLocalDocumentPaths(targetApmDir);
   if (localPaths.length === 0) {
-    console.log("[apm] \u4ED3\u5E93\u9879\u76EE\u6587\u6863\u65E0\u672C\u5730\u6587\u4EF6\uFF0C\u8DF3\u8FC7\u63A8\u9001");
+    console.log("[apm] \u9879\u76EE\u6587\u6863\u65E0\u672C\u5730\u6587\u4EF6\uFF0C\u8DF3\u8FC7\u63A8\u9001");
     return 0;
   }
-  const remoteManifest = (await api.cli.getRepositoryProjectDocumentManifest({ repositoryId })).manifest ?? null;
+  const remoteManifest = (await api.cli.getProjectDocumentManifest({ projectId })).manifest ?? null;
   const remoteHashByPath = new Map(
     (remoteManifest?.documents ?? []).map((doc) => [doc.path, doc.contentHash])
   );
@@ -1828,17 +1877,17 @@ async function syncRepositoryProjectDocumentsPush(cfg, workdirPath, apmRoot) {
     if (remoteHashByPath.get(path19) === contentHash) {
       continue;
     }
-    await api.cli.upsertRepositoryProjectDocument({
-      repositoryId,
+    await api.cli.upsertProjectDocument({
+      projectId,
       path: path19,
       content,
       description: remoteDescriptionByPath.get(path19) ?? void 0
     });
     synced += 1;
-    console.log(`[apm] \u5DF2\u540C\u6B65\u4ED3\u5E93\u9879\u76EE\u6587\u6863: ${path19}`);
+    console.log(`[apm] \u5DF2\u540C\u6B65\u9879\u76EE\u6587\u6863: ${path19}`);
   }
   if (synced === 0) {
-    console.log("[apm] \u4ED3\u5E93\u9879\u76EE\u6587\u6863\u65E0\u53D8\u5316\uFF0C\u8DF3\u8FC7\u63A8\u9001");
+    console.log("[apm] \u9879\u76EE\u6587\u6863\u65E0\u53D8\u5316\uFF0C\u8DF3\u8FC7\u63A8\u9001");
   }
   return synced;
 }
@@ -1859,7 +1908,7 @@ async function ensureWorkspaceInitialized(workdir, options) {
   const apmDir = workspaceApmDir(workdir);
   await copyTemplateFiles(apmDir, workdir);
   const syncResult = await syncRemoteDeploymentConfig(workdir, apmDir);
-  await syncRepositoryProjectDocumentsPull(workdir, apmDir);
+  await syncProjectDocumentsPull(workdir, apmDir);
   const trimmedName = options?.name?.trim();
   if (trimmedName) {
     const apmConfigPath = toFsPath(join5(apmDir, "apm.config.json"));
@@ -2773,7 +2822,7 @@ async function runPull(sessionId, remoteWorkdir) {
   await syncSessionAttachments(cfg, trimmedId, attachments, apmRoot);
   await syncPlatformRules(cfg, trimmedId, workdir, apmRoot);
   await syncRemoteDeploymentConfig(workdir, apmRoot);
-  await syncRepositoryProjectDocumentsPull(workdir, apmRoot);
+  await syncProjectDocumentsPull(workdir, apmRoot);
   console.log(`[apm] \u5DF2\u540C\u6B65\u4F1A\u8BDD\u5DE5\u4F5C\u533A: ${dir}`);
   return dir;
 }
@@ -3026,17 +3075,21 @@ async function runSyncDeployConfig() {
 }
 
 // src/commands/sync-project-documents.ts
+init_config();
 async function runSyncProjectDocuments(options) {
-  const pull = options?.pull ?? !options?.push;
-  const push = options?.push ?? false;
   const workdir = resolveWorkdirPath();
   const apmRoot = workspaceApmDir(workdir);
-  if (pull) {
-    await syncRepositoryProjectDocumentsPull(workdir, apmRoot);
+  const doPush = Boolean(options.push);
+  const doPull = Boolean(options.pull) || !doPush;
+  if (doPull) {
+    await syncProjectDocumentsPull(workdir, apmRoot);
   }
-  if (push) {
-    const cfg = await ensureLoggedConfig();
-    await syncRepositoryProjectDocumentsPush(cfg, workdir, apmRoot);
+  if (doPush) {
+    const cfg = await tryReadApmConfig();
+    if (!cfg) {
+      throw new Error("[apm] \u672A\u68C0\u6D4B\u5230\u767B\u5F55\u4FE1\u606F\uFF0C\u8BF7\u5148\u6267\u884C apm login");
+    }
+    await syncProjectDocumentsPush(cfg, workdir, apmRoot);
   }
 }
 
@@ -7491,7 +7544,7 @@ function createRecommendPlanTool(options) {
 function createUpsertWebIdePlanTool(options) {
   const { cfg, taskId } = options;
   return {
-    description: "Persist the implementation plan markdown for this WebIDE task and mark the plan as ready for human confirmation. Call once with the full plan document.",
+    description: "Persist or replace the implementation plan markdown for this WebIDE task and mark it ready for human confirmation. Call with the full plan document (not a diff). Use after generating or revising the plan.",
     inputSchema: {
       type: "object",
       properties: {
@@ -7878,8 +7931,8 @@ async function obtainAgent(ctx) {
         settingSources: ["project"]
       } : {}
     },
-    ...ctx.mode ? { mode: ctx.mode } : {}
-    // mcpServers: createPlaywrightMcpServers(),
+    ...ctx.mode ? { mode: ctx.mode } : {},
+    ...ctx.mcpServers ? { mcpServers: ctx.mcpServers } : {}
   };
   const explicitAgentId = ctx.resumeAgentId?.trim();
   const savedAgentId = explicitAgentId || (ctx.user ? loadSessionAgentId(ctx.workdir, ctx.sessionId, ctx.user) : void 0);
@@ -7976,7 +8029,6 @@ async function runCursorAgent(cfg, ctx, options) {
   try {
     const run = await agent.send(prompt, {
       ...ctx.mode ? { mode: ctx.mode } : {},
-      // mcpServers: createPlaywrightMcpServers(),
       local: {
         ...options?.forceSend ? { force: true } : {},
         customTools
@@ -8409,7 +8461,7 @@ async function handleInboundMessage(cfg, msg, signal, ctx) {
     if (!pullRan) {
       await runStep(
         "sync-project-documents-pull",
-        () => syncRepositoryProjectDocumentsPull(workdir, apmRoot)
+        () => syncProjectDocumentsPull(workdir, apmRoot)
       );
     }
     const agentResult = await runStep(
@@ -8442,7 +8494,7 @@ async function handleInboundMessage(cfg, msg, signal, ctx) {
     );
     await runStep(
       "sync-project-documents",
-      () => syncRepositoryProjectDocumentsPush(cfg, workdir, apmRoot)
+      () => syncProjectDocumentsPush(cfg, workdir, apmRoot)
     );
     await runStep(
       "commit-files",
@@ -9979,12 +10031,12 @@ function buildProgram() {
     await runSyncDeployConfig();
   });
   program.command("sync-project-documents").description(
-    "\u540C\u6B65\u4ED3\u5E93\u9879\u76EE\u6587\u6863\uFF1A\u9ED8\u8BA4 pull \u5230 .apm/project/\uFF1B\u52A0 --push \u5C06\u672C\u5730\u53D8\u66F4\u63A8\u9001\u5230\u5E73\u53F0"
-  ).option("--push", "\u63A8\u9001\u672C\u5730 .apm/project/ \u5230\u5E73\u53F0").option("--pull", "\u4ECE\u5E73\u53F0\u62C9\u53D6\u5230 .apm/project/").action(async (opts) => {
+    "\u540C\u6B65\u9879\u76EE\u6587\u6863\uFF1A\u9ED8\u8BA4 pull \u5230 .apm/docs/\uFF1B\u52A0 --push \u5C06\u672C\u5730\u53D8\u66F4\u63A8\u9001\u5230\u5E73\u53F0"
+  ).option("--push", "\u63A8\u9001\u672C\u5730 .apm/docs/ \u5230\u5E73\u53F0").option("--pull", "\u4ECE\u5E73\u53F0\u62C9\u53D6\u5230 .apm/docs/").action(async (opts) => {
     await runSyncProjectDocuments(opts);
   });
   program.command("pull").description(
-    "\u62C9\u53D6\u6C9F\u901A\u7FA4\u6570\u636E\u5230 .apm/sessions/<sessionId>/\uFF0C\u5E76\u540C\u6B65\u90E8\u7F72\u914D\u7F6E\u4E0E\u4ED3\u5E93\u9879\u76EE\u6587\u6863\u5230 .apm/project/"
+    "\u62C9\u53D6\u6C9F\u901A\u7FA4\u6570\u636E\u5230 .apm/sessions/<sessionId>/\uFF0C\u5E76\u540C\u6B65\u90E8\u7F72\u914D\u7F6E\u4E0E\u9879\u76EE\u6587\u6863\u5230 .apm/docs/"
   ).argument("<sessionId>", "\u6C9F\u901A\u7FA4 ID").action(async (sessionId) => {
     await runPull(sessionId);
   });

package/dist/webide-message-worker.js

@@ -116,10 +116,18 @@ var requestConfig = {
       method: "PUT",
       path: "/cli/webide/terminals/meta"
     }),
+    acquireSteelBrowser: defineEndpoint({
+      method: "POST",
+      path: "/cli/steel-browser/acquire"
+    }),
     branchBaseline: defineEndpoint({
       method: "GET",
       path: "/cli/tasks/branch-baseline"
     }),
+    projectBaseBranch: defineEndpoint({
+      method: "GET",
+      path: "/cli/tasks/project-base-branch"
+    }),
     listSessionsForBranchCleanup: defineEndpoint({
       method: "GET",
       path: "/cli/sessions/branch-cleanup"
@@ -156,21 +164,21 @@ var requestConfig = {
       method: "POST",
       path: "/cli/webide/pull-requests/merge"
     }),
-    getRepositoryProjectDocumentManifest: defineEndpoint({
+    getProjectDocumentManifest: defineEndpoint({
       method: "GET",
-      path: "/cli/repository-project-documents/manifest"
+      path: "/cli/project-documents/manifest"
     }),
-    listRepositoryProjectDocuments: defineEndpoint({
+    listProjectDocuments: defineEndpoint({
       method: "GET",
-      path: "/cli/repository-project-documents"
+      path: "/cli/project-documents"
     }),
-    upsertRepositoryProjectDocument: defineEndpoint({
+    upsertProjectDocument: defineEndpoint({
       method: "PUT",
-      path: "/cli/repository-project-documents/upsert"
+      path: "/cli/project-documents/upsert"
     }),
-    removeRepositoryProjectDocument: defineEndpoint({
+    removeProjectDocument: defineEndpoint({
       method: "DELETE",
-      path: "/cli/repository-project-documents"
+      path: "/cli/project-documents"
     }),
     createTaskDeployment: defineEndpoint({
       method: "POST",
@@ -207,6 +215,7 @@ import { homedir } from "os";
 import { join } from "path";
 var APM_CONFIG_DIR = join(homedir(), ".config", "apm");
 var APM_CONFIG_PATH = join(APM_CONFIG_DIR, "config.json");
+var DEFAULT_BASE_URL = "http://127.0.0.1:3000";
 function resolveClientMachineId(cfg) {
   return (cfg.clientMachineId ?? cfg.userId ?? "").trim();
 }
@@ -237,6 +246,33 @@ async function tryReadApmConfig() {
     return null;
   }
 }
+function defaultApmConfig() {
+  return {
+    baseUrl: DEFAULT_BASE_URL,
+    clientMachineId: "",
+    apiKey: ""
+  };
+}
+async function ensureApmConfig() {
+  const existing = await tryReadApmConfig();
+  if (existing) return existing;
+  const defaults = defaultApmConfig();
+  await writeApmConfig(defaults);
+  return defaults;
+}
+async function writeApmConfig(cfg) {
+  const clientMachineId = resolveClientMachineId(cfg);
+  const apiKey = resolveApiKey(cfg);
+  const normalized = {
+    baseUrl: cfg.baseUrl.trim().replace(/\/+$/, ""),
+    apiKey,
+    ...clientMachineId ? { clientMachineId } : {}
+  };
+  mkdirSync(APM_CONFIG_DIR, { recursive: true });
+  writeFileSync(APM_CONFIG_PATH, JSON.stringify(normalized, null, 2) + "\n", {
+    mode: 384
+  });
+}
 
 // src/api/client.ts
 function createApmApiClient(cfg) {
@@ -375,24 +411,6 @@ async function ensureRemoteBaselineBranch(cwd, baselineBranch) {
     `[apm] \u8FDC\u7A0B\u4E0D\u5B58\u5728\u57FA\u7EBF\u5206\u652F origin/${baselineBranch}\uFF0C\u8BF7\u786E\u8BA4\u4ED3\u5E93\u9ED8\u8BA4\u5206\u652F\u5DF2\u63A8\u9001\u5230 origin`
   );
 }
-async function resolveDefaultRemoteBranch(cwd) {
-  try {
-    const ref = (await execGit(cwd, ["symbolic-ref", "refs/remotes/origin/HEAD"], true)).trim();
-    const match = ref.match(/^refs\/remotes\/origin\/(.+)$/);
-    if (match?.[1]) {
-      return match[1];
-    }
-  } catch {
-  }
-  for (const candidate of ["main", "master"]) {
-    if (await remoteBranchExists(cwd, candidate)) {
-      return candidate;
-    }
-  }
-  throw new Error(
-    "[apm] \u65E0\u6CD5\u786E\u5B9A\u8FDC\u7A0B\u9ED8\u8BA4\u5206\u652F\uFF08origin/HEAD\u3001main\u3001master \u5747\u4E0D\u53EF\u7528\uFF09"
-  );
-}
 async function hasUpstream(cwd) {
   try {
     await execGit(cwd, ["rev-parse", "--abbrev-ref", "@{upstream}"], true);
@@ -573,6 +591,16 @@ function assertApmGitignoredInRepo(workdir) {
     );
   }
 }
+async function ensureLoggedConfig() {
+  const cfg = await ensureApmConfig();
+  if (!resolveApiKey(cfg)) {
+    console.error(
+      "[apm] \u672A\u68C0\u6D4B\u5230 API Key\uFF0C\u8BF7\u5148\u6267\u884C: apm login --api-key cm_xxx"
+    );
+    process.exit(1);
+  }
+  return cfg;
+}
 async function ensureDirExists(dir) {
   mkdirSync2(dir, { recursive: true });
 }
@@ -977,6 +1005,17 @@ async function runTaskBranch(taskId, options = {}) {
   if (!trimmedTaskId) {
     throw new Error("[apm] taskId \u4E0D\u80FD\u4E3A\u7A7A");
   }
+  const cfg = await ensureLoggedConfig();
+  const api = createApmApiClient(cfg);
+  const projectBaseline = await api.cli.projectBaseBranch({
+    taskId: trimmedTaskId
+  });
+  const baselineBranch = projectBaseline.baseBranch?.trim() ?? "";
+  if (!baselineBranch) {
+    throw new Error(
+      "[apm] \u9879\u76EE\u672A\u914D\u7F6E\u57FA\u7840\u5206\u652F\uFF0C\u65E0\u6CD5\u521B\u5EFA WebIDE \u7279\u6027\u5206\u652F"
+    );
+  }
   const cwd = options.cwd ?? process.cwd();
   const workdirPath = resolveWorkdirPath(cwd);
   const manifest = loadWorkspaceReposCache(workdirPath);
@@ -984,9 +1023,8 @@ async function runTaskBranch(taskId, options = {}) {
   const branch = branchNameForTask(trimmedTaskId);
   for (const gitRoot of repoRoots) {
     const label = formatRepoLabel(workdirPath, gitRoot);
-    const baselineBranch = await resolveDefaultRemoteBranch(gitRoot);
     console.log(
-      `[apm] \u4EFB\u52A1\u5206\u652F ${branch} @ ${label} (baseline=${baselineBranch})`
+      `[apm] \u4EFB\u52A1\u5206\u652F ${branch} @ ${label} (project baseline=${baselineBranch})`
     );
     await ensureFeatureBranch(branch, baselineBranch, {
       ...options,
@@ -1643,7 +1681,7 @@ function createRecommendPlanTool(options) {
 function createUpsertWebIdePlanTool(options) {
   const { cfg, taskId } = options;
   return {
-    description: "Persist the implementation plan markdown for this WebIDE task and mark the plan as ready for human confirmation. Call once with the full plan document.",
+    description: "Persist or replace the implementation plan markdown for this WebIDE task and mark it ready for human confirmation. Call with the full plan document (not a diff). Use after generating or revising the plan.",
     inputSchema: {
       type: "object",
       properties: {
@@ -2028,8 +2066,8 @@ async function obtainAgent(ctx) {
         settingSources: ["project"]
       } : {}
     },
-    ...ctx.mode ? { mode: ctx.mode } : {}
-    // mcpServers: createPlaywrightMcpServers(),
+    ...ctx.mode ? { mode: ctx.mode } : {},
+    ...ctx.mcpServers ? { mcpServers: ctx.mcpServers } : {}
   };
   const explicitAgentId = ctx.resumeAgentId?.trim();
   const savedAgentId = explicitAgentId || (ctx.user ? loadSessionAgentId(ctx.workdir, ctx.sessionId, ctx.user) : void 0);
@@ -2126,7 +2164,6 @@ async function runCursorAgent(cfg, ctx, options) {
   try {
     const run = await agent.send(prompt, {
       ...ctx.mode ? { mode: ctx.mode } : {},
-      // mcpServers: createPlaywrightMcpServers(),
       local: {
         ...options?.forceSend ? { force: true } : {},
         customTools
@@ -2622,7 +2659,7 @@ ${diagnostic ?? ""}
   return { synced: true, repositoryId, configName: config.name };
 }
 
-// src/repository-project-documents-sync.ts
+// src/project-documents-sync.ts
 import {
   existsSync as existsSync5,
   readdirSync as readdirSync3,
@@ -2633,7 +2670,7 @@ import {
 import { dirname as dirname4, join as join6, relative as relative2, sep } from "path";
 var MANIFEST_FILE = "manifest.json";
 function projectDocumentsDir(apmRoot) {
-  return join6(apmRoot ?? workspaceApmDir(), "project");
+  return join6(apmRoot ?? workspaceApmDir(), "docs");
 }
 function projectDocumentLocalPath(apmRoot, documentPath) {
   const normalized = normalizeLocalDocumentPath(documentPath);
@@ -2684,41 +2721,65 @@ function diffManifestPaths(remote, local) {
   }
   return { download, deleteLocal };
 }
-async function syncRepositoryProjectDocumentsPull(workdirPath, apmDir) {
+async function resolveProjectIdForSync(api, workdirPath) {
+  try {
+    const baseline = await api.cli.workspaceBaseline({ workdirPath });
+    const projectId = baseline.projectId?.trim() || null;
+    if (projectId) {
+      return { projectId, diagnostic: null };
+    }
+    const projectIds = baseline.projectIds ?? [];
+    if (projectIds.length === 0) {
+      return {
+        projectId: null,
+        diagnostic: baseline.diagnostic?.message ?? `\u5DE5\u4F5C\u7A7A\u95F4\u672A\u5173\u8054\u9879\u76EE\uFF0C\u65E0\u6CD5\u540C\u6B65\u9879\u76EE\u6587\u6863\uFF08\u76EE\u5F55\uFF1A${workdirPath}\uFF09\u3002
+\u8BF7\u5728\u5E73\u53F0\u5C06\u5DE5\u4F5C\u7A7A\u95F4\u5173\u8054\u5230\u552F\u4E00\u9879\u76EE\u3002`
+      };
+    }
+    return {
+      projectId: null,
+      diagnostic: `\u5DE5\u4F5C\u7A7A\u95F4\u5173\u8054\u4E86 ${projectIds.length} \u4E2A\u9879\u76EE\uFF0C\u65E0\u6CD5\u786E\u5B9A\u540C\u6B65\u76EE\u6807\u3002
+\u8BF7\u786E\u4FDD\u8BE5\u5DE5\u4F5C\u7A7A\u95F4\u53EA\u5173\u8054\u4E00\u4E2A\u9879\u76EE\u540E\u518D\u540C\u6B65\u9879\u76EE\u6587\u6863\u3002`
+    };
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    return {
+      projectId: null,
+      diagnostic: detail.replace(/^\[apm\]\s*/, "")
+    };
+  }
+}
+async function syncProjectDocumentsPull(workdirPath, apmDir) {
   const empty = {
     synced: false,
-    repositoryId: null,
+    projectId: null,
     downloaded: 0,
     deleted: 0
   };
   const cfg = await tryReadApmConfig();
   if (!cfg || !resolveApiKey(cfg)) {
     console.log(
-      "[apm] \u672A\u68C0\u6D4B\u5230\u767B\u5F55\u4FE1\u606F\uFF0C\u8DF3\u8FC7\u4ED3\u5E93\u9879\u76EE\u6587\u6863\u540C\u6B65\u3002\n[apm] \u8BF7\u5148\u6267\u884C apm login\u3002"
+      "[apm] \u672A\u68C0\u6D4B\u5230\u767B\u5F55\u4FE1\u606F\uFF0C\u8DF3\u8FC7\u9879\u76EE\u6587\u6863\u540C\u6B65\u3002\n[apm] \u8BF7\u5148\u6267\u884C apm login\u3002"
     );
     return empty;
   }
   const api = createApmApiClient(cfg);
-  const { repositoryId, diagnostic } = await resolveRepositoryIdForSync(
+  const { projectId, diagnostic } = await resolveProjectIdForSync(
     api,
     workdirPath
   );
-  if (!repositoryId) {
-    console.log(
-      `[apm] \u672A\u80FD\u540C\u6B65\u4ED3\u5E93\u9879\u76EE\u6587\u6863\u3002
-${diagnostic ?? ""}`
-    );
+  if (!projectId) {
+    console.log(`[apm] \u672A\u80FD\u540C\u6B65\u9879\u76EE\u6587\u6863\u3002
+${diagnostic ?? ""}`);
     return empty;
   }
   const targetApmDir = apmDir ?? workspaceApmDir(workdirPath);
-  const projectDir = projectDocumentsDir(targetApmDir);
-  await ensureDirExists(projectDir);
-  const { manifest: remoteManifest } = await api.cli.getRepositoryProjectDocumentManifest({ repositoryId });
+  const docsDir = projectDocumentsDir(targetApmDir);
+  await ensureDirExists(docsDir);
+  const { manifest: remoteManifest } = await api.cli.getProjectDocumentManifest({ projectId });
   if (!remoteManifest) {
-    console.log(
-      `[apm] \u4ED3\u5E93 ${repositoryId} \u65E0\u9879\u76EE\u6587\u6863 manifest\uFF0C\u8DF3\u8FC7\u540C\u6B65\u3002`
-    );
-    return { ...empty, repositoryId };
+    console.log(`[apm] \u9879\u76EE ${projectId} \u65E0\u9879\u76EE\u6587\u6863 manifest\uFF0C\u8DF3\u8FC7\u540C\u6B65\u3002`);
+    return { ...empty, projectId };
   }
   const localManifest = readLocalManifest(targetApmDir);
   const { download, deleteLocal } = diffManifestPaths(
@@ -2727,12 +2788,14 @@ ${diagnostic ?? ""}`
   );
   let downloaded = 0;
   if (download.length > 0) {
-    const { list } = await api.cli.listRepositoryProjectDocuments({
-      repositoryId,
+    const { list } = await api.cli.listProjectDocuments({
+      projectId,
       paths: download.join(",")
     });
     for (const doc of list) {
-      const absPath = toFsPath(projectDocumentLocalPath(targetApmDir, doc.path));
+      const absPath = toFsPath(
+        projectDocumentLocalPath(targetApmDir, doc.path)
+      );
       await ensureDirExists(dirname4(absPath));
       writeFileSync7(absPath, doc.content, "utf8");
       downloaded += 1;
@@ -2747,17 +2810,17 @@ ${diagnostic ?? ""}`
     }
   }
   writeFileSync7(
-    toFsPath(join6(projectDir, MANIFEST_FILE)),
+    toFsPath(join6(docsDir, MANIFEST_FILE)),
     `${JSON.stringify(remoteManifest, null, 2)}
 `,
     "utf8"
   );
   console.log(
-    `[apm] \u5DF2\u540C\u6B65\u4ED3\u5E93\u9879\u76EE\u6587\u6863: \u4E0B\u8F7D ${downloaded}\uFF0C\u5220\u9664\u672C\u5730 ${deleted}`
+    `[apm] \u5DF2\u540C\u6B65\u9879\u76EE\u6587\u6863: \u4E0B\u8F7D ${downloaded}\uFF0C\u5220\u9664\u672C\u5730 ${deleted}`
   );
   return {
     synced: true,
-    repositoryId,
+    projectId,
     downloaded,
     deleted
   };
@@ -2779,7 +2842,7 @@ async function ensureWorkspaceInitialized(workdir, options) {
   const apmDir = workspaceApmDir(workdir);
   await copyTemplateFiles(apmDir, workdir);
   const syncResult = await syncRemoteDeploymentConfig(workdir, apmDir);
-  await syncRepositoryProjectDocumentsPull(workdir, apmDir);
+  await syncProjectDocumentsPull(workdir, apmDir);
   const trimmedName = options?.name?.trim();
   if (trimmedName) {
     const apmConfigPath = toFsPath(join7(apmDir, "apm.config.json"));
@@ -3214,7 +3277,7 @@ async function handleWebIdeInboundMessage(cfg, msg, signal, options) {
       id: messageId,
       content: fallback
     });
-    if (msg.action === "write-plan" && outcome.createPlan && outcome.createPlan.trim()) {
+    if ((msg.action === "write-plan" || msg.action === "revise-plan") && outcome.createPlan && outcome.createPlan.trim()) {
       try {
         await api.cli.webideUpsertPlan({
           taskId,
@@ -3222,7 +3285,7 @@ async function handleWebIdeInboundMessage(cfg, msg, signal, options) {
         });
       } catch (err) {
         console.warn(
-          "[apm] write-plan \u8865\u5199\u8BA1\u5212\u5931\u8D25:",
+          `[apm] ${msg.action} \u8865\u5199\u8BA1\u5212\u5931\u8D25:`,
           err instanceof Error ? err.message : err
         );
       }

package/package.json

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

package/template/AGENTS.md

@@ -33,10 +33,10 @@
     - webide_testcase.md：WebIDE 生成测试用例时读取，按规范编写并提交用例
     - webide_merge.md：WebIDE 验收通过后读取；直接调用 MergeWebIdePullRequests 合并代码
 
-- 仓库项目上下文（`.apm/project/`）:
+- 项目文档（`.apm/docs/`）:
 
-  - 索引: `.apm/project/manifest.json` — 本仓库在平台登记的文档列表
-  - 文档文件: `.apm/project/{path}` — 与 manifest 中 path 对应；`apm pull` 自动同步，`apm connect` 消息结束后自动推回平台
+  - 索引: `.apm/docs/manifest.json` — 本项目在平台登记的文档列表
+  - 文档文件: `.apm/docs/{path}` — 与 manifest 中 path 对应；`apm pull` 自动同步，`apm connect` 消息结束后自动推回平台
   - 任务涉及菜单名、路由、业务术语等时，**先 Read manifest 与相关文档**，禁止猜测路径
 
 - 本轮任务需要关注的文档指引（.apm/sessions/<会话 ID>/\*）:

package/template/rules/webide_terminal.md

@@ -13,23 +13,25 @@
 
 ## 启动命令来源
 
-必须 Read `.apm/project/deploy.md`，按文档中的 cwd / command / 服务划分调用 `StartWebIdeTerminal`。
+必须 Read `.apm/docs/deploy.md`，按文档中的 cwd / command / 服务划分调用 `StartWebIdeTerminal`。
 
 - 文档不存在或未写明启动方式 → 用 AppendMessage 说明无法启动本地环境，**禁止猜测命令**。
 
-## 时机
+## 时机（打开本地 dev）
 
-1. **首次**（`start-develop` / 跳过计划后的开发轮次）：实现完成后需要本地环境时
-   - 先 `ListWebIdeTerminals`
-   - 若无活终端 → Read `deploy.md` → 按前后端分别 `StartWebIdeTerminal`
-   - 等待 READY / 端口出现后，告知用户可在 WebIDE「终端」面板观察日志（勿粘贴整段 stdout）
-2. **后续改码**（热更新）：有活终端则**复用，不重起**
-3. **显式重跑**（端口冲突、命令变更、或平台「重跑本地环境」指令）：  
-   `StopAllWebIdeTerminals` → 再 Read `deploy.md` → 重新 Start  
-   不要在已死进程上糊弄；需要换命令时也是先停再建
+固定顺序：
+
+1. **`ListWebIdeTerminals`**
+2. 若无活终端 → Read `deploy.md` → 按前后端分别 `StartWebIdeTerminal`；已有活终端则复用
+3. 等待 READY / 端口即可
+4. AppendMessage：可在「终端」面板观察本地日志；「浏览器」面板由平台打开本客户机外网地址（勿粘贴整段 stdout；无需 Agent 打开浏览器）
+
+后续改码（热更新）：有活终端则**复用，不重起**。
+
+显式重跑：`StopAllWebIdeTerminals` → 再 Read `deploy.md` → 重新 Start。
 
 ## 规范
 
 1. 禁止用 Shell / 后台进程方式起 `dev` / `serve` 等长驻命令。
-2. 观察日志请用户看 WebIDE「终端」面板。
+2. 观察日志请用户看 WebIDE「终端」面板；页面请用户看「浏览器」面板（客户机外网地址）。
 3. 任务结束或不再需要时可 Stop；不要留下孤儿进程。