ai-project-manage-cli 8.1.26 → 9.0.0

package/dist/index.js

@@ -16,15 +16,6 @@ function resolveClientMachineId(cfg) {
 function resolveApiKey(cfg) {
   return (cfg.apiKey ?? cfg.token ?? "").trim();
 }
-function stripTrailingSlash(raw) {
-  return raw.trim().replace(/\/+$/, "");
-}
-function readConfigSocketServer(cfg) {
-  const fromNew = typeof cfg.socketServer === "string" ? cfg.socketServer.trim().replace(/\/+$/, "") : "";
-  if (fromNew) return fromNew;
-  const fromLegacy = typeof cfg.wsUrl === "string" ? cfg.wsUrl.trim().replace(/\/+$/, "") : "";
-  return fromLegacy;
-}
 function tryReadApmConfig() {
   try {
     const raw = readFileSync(APM_CONFIG_PATH, "utf8");
@@ -40,12 +31,10 @@ function tryReadApmConfig() {
     if (!apiKey) return null;
     const cfg = v;
     const clientMachineId = resolveClientMachineId(cfg);
-    const socketServer = readConfigSocketServer(cfg);
     return {
       baseUrl: cfg.baseUrl.trim().replace(/\/+$/, ""),
       apiKey,
-      ...clientMachineId ? { clientMachineId } : {},
-      ...socketServer ? { socketServer } : {}
+      ...clientMachineId ? { clientMachineId } : {}
     };
   } catch {
     return null;
@@ -58,80 +47,11 @@ function defaultApmConfig() {
     apiKey: ""
   };
 }
-function assertHttpBase(raw, label) {
-  const u = stripTrailingSlash(raw);
-  if (!u.startsWith("https://") && !u.startsWith("http://")) {
-    throw new Error(`${label} \u5FC5\u987B\u4EE5 http:// \u6216 https:// \u5F00\u5934`);
-  }
-  return new URL(u).origin;
-}
-function normalizeSocketBase(raw) {
-  const u = stripTrailingSlash(raw);
-  if (u.startsWith("https://") || u.startsWith("http://") || u.startsWith("wss://") || u.startsWith("ws://")) {
-    return new URL(u).origin;
-  }
-  throw new Error(
-    "socket server \u5FC5\u987B\u4EE5 http://\u3001https://\u3001ws:// \u6216 wss:// \u5F00\u5934"
-  );
-}
-function httpBaseToWsOrigin(httpOrWsBase) {
-  const u = stripTrailingSlash(httpOrWsBase);
-  if (u.startsWith("wss://") || u.startsWith("ws://")) return u;
+function httpBaseToWsOrigin(httpBase) {
+  const u = httpBase.trim().replace(/\/+$/, "");
   if (u.startsWith("https://")) return "wss://" + u.slice("https://".length);
   if (u.startsWith("http://")) return "ws://" + u.slice("http://".length);
-  throw new Error("socket server \u5FC5\u987B\u4EE5 http(s):// \u6216 ws(s):// \u5F00\u5934");
-}
-function splitHistoricalServer(server) {
-  const url = new URL(assertHttpBase(server, "server"));
-  const socketServer = url.origin;
-  if (url.port) {
-    url.port = "";
-    return { baseUrl: url.origin, socketServer };
-  }
-  return { baseUrl: url.origin, socketServer: url.origin };
-}
-function resolveApmEndpoints(input = {}) {
-  const serverOpt = stripTrailingSlash(
-    input.server?.trim() || process.env.APM_SERVER?.trim() || ""
-  );
-  const socketOpt = stripTrailingSlash(
-    input.socketServer?.trim() || process.env.APM_SOCKET_SERVER?.trim() || ""
-  );
-  const configBase = stripTrailingSlash(input.configBaseUrl?.trim() || "");
-  const configSocket = stripTrailingSlash(
-    input.configSocketServer?.trim() || ""
-  );
-  if (serverOpt && socketOpt) {
-    return {
-      baseUrl: assertHttpBase(serverOpt, "server"),
-      socketServer: normalizeSocketBase(socketOpt)
-    };
-  }
-  if (serverOpt) {
-    return splitHistoricalServer(serverOpt);
-  }
-  if (configBase && socketOpt) {
-    return {
-      baseUrl: assertHttpBase(configBase, "baseUrl"),
-      socketServer: normalizeSocketBase(socketOpt)
-    };
-  }
-  if (configBase && configSocket) {
-    return {
-      baseUrl: assertHttpBase(configBase, "baseUrl"),
-      socketServer: normalizeSocketBase(configSocket)
-    };
-  }
-  if (configBase) {
-    return splitHistoricalServer(configBase);
-  }
-  if (socketOpt) {
-    return {
-      baseUrl: assertHttpBase(DEFAULT_BASE_URL, "server"),
-      socketServer: normalizeSocketBase(socketOpt)
-    };
-  }
-  return splitHistoricalServer(DEFAULT_BASE_URL);
+  throw new Error("baseUrl \u5FC5\u987B\u4EE5 http:// \u6216 https:// \u5F00\u5934");
 }
 async function ensureApmConfig() {
   const existing = await tryReadApmConfig();
@@ -143,25 +63,20 @@ async function ensureApmConfig() {
 async function writeApmConfig(cfg) {
   const clientMachineId = resolveClientMachineId(cfg);
   const apiKey = resolveApiKey(cfg);
-  const socketServer = stripTrailingSlash(
-    cfg.socketServer?.trim() || cfg.wsUrl?.trim() || ""
-  );
   const normalized = {
     baseUrl: cfg.baseUrl.trim().replace(/\/+$/, ""),
     apiKey,
-    ...clientMachineId ? { clientMachineId } : {},
-    ...socketServer ? { socketServer } : {}
+    ...clientMachineId ? { clientMachineId } : {}
   };
   mkdirSync(APM_CONFIG_DIR, { recursive: true });
   writeFileSync(APM_CONFIG_PATH, JSON.stringify(normalized, null, 2) + "\n", {
     mode: 384
   });
 }
-function buildAgentWsUrl(socketServer, apiKey) {
-  const url = new URL(httpBaseToWsOrigin(socketServer));
-  url.pathname = "/ws/agent";
-  url.search = new URLSearchParams({ apiKey }).toString();
-  return url.toString();
+function buildAgentWsUrl(httpBase, apiKey) {
+  const origin = httpBaseToWsOrigin(httpBase);
+  const q = new URLSearchParams({ apiKey });
+  return `${origin}/ws/agent?${q.toString()}`;
 }
 
 // src/commands/sync-webide-agent.ts
@@ -289,10 +204,38 @@ var requestConfig = {
       method: "POST",
       path: "/cli/webide/pull-requests/merge"
     }),
+    getProjectDocumentManifest: defineEndpoint({
+      method: "GET",
+      path: "/cli/project-documents/manifest"
+    }),
+    listProjectDocuments: defineEndpoint({
+      method: "GET",
+      path: "/cli/project-documents"
+    }),
+    upsertProjectDocument: defineEndpoint({
+      method: "PUT",
+      path: "/cli/project-documents/upsert"
+    }),
+    removeProjectDocument: defineEndpoint({
+      method: "DELETE",
+      path: "/cli/project-documents"
+    }),
     getApmLogStorage: defineEndpoint({
       method: "GET",
       path: "/cli/apm-log-storage"
     }),
+    projectPackageUpdateStatus: defineEndpoint({
+      method: "PUT",
+      path: "/cli/project-packages/status"
+    }),
+    projectPackageAppendContent: defineEndpoint({
+      method: "PUT",
+      path: "/cli/project-packages/content"
+    }),
+    projectPackageEnsureContent: defineEndpoint({
+      method: "PUT",
+      path: "/cli/project-packages/ensure-content"
+    }),
     cursorStoreUpsertAgent: defineEndpoint({
       method: "PUT",
       path: "/cli/cursor-store/agents"
@@ -407,6 +350,9 @@ async function ensureLoggedConfig() {
   }
   return cfg;
 }
+async function ensureDirExists(dir) {
+  mkdirSync2(dir, { recursive: true });
+}
 async function ensureWorkspaceApmDirForInit(cwd = resolveWorkdirPath()) {
   const dir = workspaceApmDir(cwd);
   const fsDir = toFsPath(dir);
@@ -507,20 +453,15 @@ async function runInit() {
 // src/commands/login.ts
 import { ApiError } from "listpage-http";
 async function runLogin(opts) {
-  const endpoints = resolveApmEndpoints({
-    server: opts.server,
-    socketServer: opts.socketServer
-  });
+  const baseUrl = (opts.server?.trim() || process.env.AI_PM_SERVER?.trim() || DEFAULT_BASE_URL).replace(/\/+$/, "");
   const apiKey = (opts.apiKey?.trim() || process.env.APM_API_KEY?.trim() || "").replace(/^Bearer\s+/i, "");
   if (!apiKey.startsWith("cm_")) {
     console.error("[apm] \u8BF7\u63D0\u4F9B\u6709\u6548\u7684 API Key\uFF08cm_ \u5F00\u5934\uFF09");
-    console.error(
-      "[apm] \u7528\u6CD5: apm login --api-key cm_xxx [--server URL] [--socket-server URL]"
-    );
+    console.error("[apm] \u7528\u6CD5: apm login --api-key cm_xxx [--server URL]");
     process.exit(1);
   }
   const api = createApmApiClient({
-    baseUrl: endpoints.baseUrl,
+    baseUrl,
     clientMachineId: "",
     apiKey
   });
@@ -545,8 +486,7 @@ async function runLogin(opts) {
     process.exit(1);
   }
   const cfg = {
-    baseUrl: endpoints.baseUrl,
-    socketServer: endpoints.socketServer,
+    baseUrl,
     clientMachineId,
     apiKey
   };
@@ -557,8 +497,7 @@ async function runLogin(opts) {
       {
         clientMachineId: cfg.clientMachineId,
         clientName: data.clientName,
-        baseUrl: cfg.baseUrl,
-        socketServer: cfg.socketServer
+        baseUrl: cfg.baseUrl
       },
       null,
       2
@@ -568,6 +507,8 @@ async function runLogin(opts) {
 
 // src/commands/update.ts
 import { spawnSync } from "child_process";
+import { existsSync as existsSync3 } from "fs";
+import { join as join5 } from "path";
 
 // src/version.ts
 import { readFileSync as readFileSync3 } from "fs";
@@ -586,6 +527,7 @@ function readCliVersion() {
 }
 
 // src/commands/update.ts
+var APM_SKIP_SELF_UPDATE_ENV = "APM_SKIP_SELF_UPDATE";
 var useNpmShell = process.platform === "win32";
 function runNpm(args, options = {}) {
   return spawnSync(useNpmShell ? "npm.cmd" : "npm", args, {
@@ -678,10 +620,17 @@ function npmAvailable() {
   return !r.error && r.status === 0;
 }
 async function runUpdate(options = {}) {
+  if (process.env[APM_SKIP_SELF_UPDATE_ENV] === "1") {
+    return { didUpdate: false };
+  }
   const current = readCliVersion();
   const currentMajor = parseMajorVersion(current);
   const globalLatest = await fetchLatestPublishedVersion();
   const latestInMajor = options.allowMajorUpgrade ? null : await fetchLatestPublishedVersionInMajor(currentMajor);
+  if (options.quietIfCurrent && !options.allowMajorUpgrade && !latestInMajor && !globalLatest) {
+    console.warn(`[apm] \u65E0\u6CD5\u68C0\u6D4B\u6700\u65B0\u7248\u672C\uFF0C\u7EE7\u7EED\u4F7F\u7528\u5F53\u524D ${current}`);
+    return { didUpdate: false };
+  }
   const resolved = resolveUpdateTarget({
     current,
     allowMajorUpgrade: options.allowMajorUpgrade,
@@ -689,8 +638,10 @@ async function runUpdate(options = {}) {
     globalLatest
   });
   if (resolved.action === "skip") {
-    console.log(`[apm] \u5DF2\u662F\u6700\u65B0\u7248\u672C ${current}`);
-    return;
+    if (!options.quietIfCurrent) {
+      console.log(`[apm] \u5DF2\u662F\u6700\u65B0\u7248\u672C ${current}`);
+    }
+    return { didUpdate: false };
   }
   if (resolved.majorUpgradeAvailable) {
     console.log(
@@ -727,14 +678,57 @@ async function runUpdate(options = {}) {
   } else {
     console.log(`[apm] \u5DF2\u662F\u6700\u65B0\u7248\u672C ${current}`);
   }
+  return { didUpdate: expectedBump };
+}
+function resolveApmEntryPath(entryArg = process.argv[1]) {
+  const npmResult = runNpm(["root", "-g"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  if (npmResult.status === 0) {
+    const globalRoot = npmResult.stdout?.toString().trim();
+    if (globalRoot) {
+      const candidate = join5(globalRoot, CLI_PACKAGE_NAME, "dist", "index.js");
+      if (existsSync3(candidate)) {
+        return candidate;
+      }
+    }
+  }
+  const fromArgv = entryArg?.trim();
+  if (fromArgv && existsSync3(fromArgv)) {
+    return fromArgv;
+  }
+  if (fromArgv) {
+    return fromArgv;
+  }
+  console.error("[apm] \u65E0\u6CD5\u89E3\u6790 apm \u5165\u53E3\u8DEF\u5F84");
+  process.exit(1);
+}
+function reexecConnectAfterUpdate(options) {
+  console.log("[apm] \u66F4\u65B0\u5B8C\u6210\uFF0C\u6B63\u5728\u4EE5\u65B0\u7248\u672C\u91CD\u65B0\u8FDE\u63A5\u2026");
+  const apmScript = resolveApmEntryPath();
+  const args = [apmScript, "connect"];
+  const server = options.server?.trim();
+  if (server) {
+    args.push("--server", server);
+  }
+  const result = spawnSync(process.execPath, args, {
+    stdio: "inherit",
+    env: { ...process.env, [APM_SKIP_SELF_UPDATE_ENV]: "1" }
+  });
+  if (result.error) {
+    console.error("[apm] \u91CD\u542F connect \u5931\u8D25:", result.error.message);
+    process.exit(1);
+  }
+  process.exit(result.status ?? 0);
 }
 
 // src/commands/update-skills.ts
-import { existsSync as existsSync3, statSync as statSync2 } from "fs";
+import { existsSync as existsSync4, statSync as statSync2 } from "fs";
 async function syncWorkspaceSkills(workdir) {
   const apmDir = workspaceApmDir(workdir);
   const fsApmDir = toFsPath(apmDir);
-  if (!existsSync3(fsApmDir)) {
+  if (!existsSync4(fsApmDir)) {
     throw new Error("[apm] \u672A\u627E\u5230 .apm \u76EE\u5F55\uFF0C\u8BF7\u5148\u6267\u884C apm init");
   }
   const apmStat = statSync2(fsApmDir);
@@ -749,7 +743,7 @@ async function syncWorkspaceSkills(workdir) {
 }
 async function runUpdateSkills() {
   const apmDir = workspaceApmDir();
-  if (!existsSync3(apmDir)) {
+  if (!existsSync4(apmDir)) {
     console.error("[apm] \u672A\u627E\u5230 .apm \u76EE\u5F55\uFF0C\u8BF7\u5148\u6267\u884C apm init");
     process.exit(1);
   }
@@ -760,11 +754,363 @@ async function runUpdateSkills() {
   await syncWorkspaceSkills(resolveWorkdirPath());
 }
 
+// src/utils/project-documents.ts
+import {
+  existsSync as existsSync5,
+  readdirSync as readdirSync3,
+  readFileSync as readFileSync4,
+  rmSync,
+  writeFileSync as writeFileSync3
+} from "fs";
+import { createHash } from "crypto";
+import { dirname as dirname2, join as join6, relative, sep } from "path";
+
+// src/utils/git.ts
+import { execFile as execFile2 } from "child_process";
+import { promisify as promisify2 } from "util";
+
+// src/utils/git-remote.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+
+// src/utils/git.ts
+var execFileAsync2 = promisify2(execFile2);
+function gitExecEnv() {
+  const existing = process.env.GIT_SSH_COMMAND?.trim();
+  const acceptNew = "-o StrictHostKeyChecking=accept-new";
+  let gitSshCommand;
+  if (!existing) {
+    gitSshCommand = `ssh ${acceptNew}`;
+  } else if (/\bStrictHostKeyChecking=/.test(existing)) {
+    gitSshCommand = existing;
+  } else {
+    gitSshCommand = `${existing} ${acceptNew}`;
+  }
+  return { ...process.env, GIT_SSH_COMMAND: gitSshCommand };
+}
+async function execGit(cwd, args, quiet = false) {
+  try {
+    const { stdout, stderr } = await execFileAsync2("git", args, {
+      cwd,
+      env: gitExecEnv(),
+      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 getCurrentBranch(cwd) {
+  return (await execGit(cwd, ["rev-parse", "--abbrev-ref", "HEAD"], true)).trim();
+}
+async function resolveGitRepoRoot(cwd) {
+  return (await execGit(cwd, ["rev-parse", "--show-toplevel"], true)).trim();
+}
+var FEATURE_BRANCH_RE = /^feat\/task-(.+)$/;
+function taskIdFromFeatureBranch(branch) {
+  const name = branch.trim().replace(/^origin\//, "");
+  const match = name.match(FEATURE_BRANCH_RE);
+  const id = match?.[1]?.trim() ?? "";
+  return id || null;
+}
+
+// src/utils/project-documents.ts
+var MANIFEST_FILE = "manifest.json";
+function normalizeProjectIdForPath(projectId) {
+  const id = projectId.trim();
+  if (!id) {
+    throw new Error("projectId \u4E0D\u80FD\u4E3A\u7A7A");
+  }
+  if (id.includes("..") || id.includes("/") || id.includes("\\") || id.includes("\0")) {
+    throw new Error(`\u975E\u6CD5 projectId: ${projectId}`);
+  }
+  return id;
+}
+function projectDocumentsDir(apmRoot, projectId) {
+  const id = normalizeProjectIdForPath(projectId);
+  return join6(apmRoot ?? workspaceApmDir(), "project", id);
+}
+function projectDocumentLocalPath(apmRoot, projectId, documentPath) {
+  const normalized = normalizeLocalDocumentPath(documentPath);
+  return join6(
+    projectDocumentsDir(apmRoot, projectId),
+    ...normalized.split("/")
+  );
+}
+function normalizeLocalDocumentPath(path) {
+  const trimmed = path.trim().replace(/\\/g, "/");
+  if (!trimmed || trimmed.startsWith("/") || /^[a-zA-Z]:/.test(trimmed)) {
+    throw new Error(`\u975E\u6CD5\u6587\u6863\u8DEF\u5F84: ${path}`);
+  }
+  const segments = trimmed.split("/").filter(Boolean);
+  if (segments.some((segment) => segment === ".." || segment === ".")) {
+    throw new Error(`\u975E\u6CD5\u6587\u6863\u8DEF\u5F84: ${path}`);
+  }
+  return segments.join("/");
+}
+function hashLocalFileContent(content) {
+  return createHash("sha256").update(content, "utf8").digest("hex");
+}
+function readLocalManifest(apmRoot, projectId) {
+  const manifestPath = join6(
+    projectDocumentsDir(apmRoot, projectId),
+    MANIFEST_FILE
+  );
+  if (!existsSync5(manifestPath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(
+      readFileSync4(manifestPath, "utf8")
+    );
+  } catch {
+    return null;
+  }
+}
+function listLocalDocumentPaths(apmRoot, projectId) {
+  const root = projectDocumentsDir(apmRoot, projectId);
+  if (!existsSync5(root)) {
+    return [];
+  }
+  const paths = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync3(dir, { withFileTypes: true })) {
+      const abs = join6(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(abs);
+        continue;
+      }
+      if (entry.isFile() && entry.name === MANIFEST_FILE) {
+        continue;
+      }
+      const rel = relative(root, abs).split(sep).join("/");
+      paths.push(rel);
+    }
+  };
+  walk(root);
+  return paths.sort();
+}
+function diffManifestPaths(remote, local) {
+  const remoteMap = new Map(
+    (remote?.documents ?? []).map((doc) => [doc.path, doc.contentHash])
+  );
+  const localMap = new Map(
+    (local?.documents ?? []).map((doc) => [doc.path, doc.contentHash])
+  );
+  const download = [];
+  for (const [path, hash] of remoteMap) {
+    if (localMap.get(path) !== hash) {
+      download.push(path);
+    }
+  }
+  const deleteLocal = [];
+  for (const path of localMap.keys()) {
+    if (!remoteMap.has(path)) {
+      deleteLocal.push(path);
+    }
+  }
+  return { download, deleteLocal };
+}
+async function resolveProjectIdForSync(api, workdirPath, options) {
+  const explicit = options?.projectId?.trim();
+  if (explicit) {
+    return { projectId: explicit, diagnostic: null };
+  }
+  try {
+    const gitRoot = await resolveGitRepoRoot(workdirPath);
+    const current = await getCurrentBranch(gitRoot);
+    const taskId = taskIdFromFeatureBranch(current);
+    if (!taskId) {
+      return {
+        projectId: null,
+        diagnostic: `\u5F53\u524D\u5206\u652F ${current} \u4E0D\u662F feat/task-*\uFF0C\u65E0\u6CD5\u89E3\u6790\u6240\u5C5E\u9879\u76EE\u3002
+\u8BF7\u5728\u7279\u6027\u5206\u652F\u4E0A\u6267\u884C\uFF0C\u6216\u663E\u5F0F\u6307\u5B9A projectId\u3002`
+      };
+    }
+    const baseline = await api.cli.projectBaseBranch({ taskId });
+    const projectId = baseline.projectId?.trim() || null;
+    if (!projectId) {
+      return {
+        projectId: null,
+        diagnostic: `\u4EFB\u52A1 ${taskId} \u672A\u5173\u8054\u9879\u76EE\uFF0C\u65E0\u6CD5\u540C\u6B65\u9879\u76EE\u6587\u6863\u3002`
+      };
+    }
+    return { projectId, diagnostic: null };
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    return {
+      projectId: null,
+      diagnostic: detail.replace(/^\[apm\]\s*/, "")
+    };
+  }
+}
+async function syncProjectDocumentsPull(workdirPath, apmDir, options) {
+  const empty = {
+    synced: false,
+    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\u9879\u76EE\u6587\u6863\u540C\u6B65\u3002\n[apm] \u8BF7\u5148\u6267\u884C apm login\u3002"
+    );
+    return empty;
+  }
+  const api = createApmApiClient(cfg);
+  const { projectId, diagnostic } = await resolveProjectIdForSync(
+    api,
+    workdirPath,
+    options
+  );
+  if (!projectId) {
+    console.log(`[apm] \u672A\u80FD\u540C\u6B65\u9879\u76EE\u6587\u6863\u3002
+${diagnostic ?? ""}`);
+    return empty;
+  }
+  const targetApmDir = apmDir ?? workspaceApmDir(workdirPath);
+  const docsDir = projectDocumentsDir(targetApmDir, projectId);
+  await ensureDirExists(docsDir);
+  const { manifest: remoteManifest } = await api.cli.getProjectDocumentManifest(
+    { projectId }
+  );
+  if (!remoteManifest) {
+    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, projectId);
+  const { download, deleteLocal } = diffManifestPaths(
+    remoteManifest,
+    localManifest
+  );
+  let downloaded = 0;
+  if (download.length > 0) {
+    const { list } = await api.cli.listProjectDocuments({
+      projectId,
+      paths: download.join(",")
+    });
+    for (const doc of list) {
+      const absPath = toFsPath(
+        projectDocumentLocalPath(targetApmDir, projectId, doc.path)
+      );
+      await ensureDirExists(dirname2(absPath));
+      writeFileSync3(absPath, doc.content, "utf8");
+      downloaded += 1;
+    }
+  }
+  let deleted = 0;
+  for (const path of deleteLocal) {
+    const absPath = toFsPath(
+      projectDocumentLocalPath(targetApmDir, projectId, path)
+    );
+    if (existsSync5(absPath)) {
+      rmSync(absPath, { force: true });
+      deleted += 1;
+    }
+  }
+  writeFileSync3(
+    toFsPath(join6(docsDir, MANIFEST_FILE)),
+    `${JSON.stringify(remoteManifest, null, 2)}
+`,
+    "utf8"
+  );
+  console.log(
+    `[apm] \u5DF2\u540C\u6B65\u9879\u76EE\u6587\u6863: projectId=${projectId} \u4E0B\u8F7D ${downloaded}\uFF0C\u5220\u9664\u672C\u5730 ${deleted} \u2192 .apm/project/${projectId}/`
+  );
+  return {
+    synced: true,
+    projectId,
+    downloaded,
+    deleted
+  };
+}
+async function syncProjectDocumentsPush(cfg, workdirPath, apmRoot, options) {
+  const api = createApmApiClient(cfg);
+  const { projectId } = await resolveProjectIdForSync(
+    api,
+    workdirPath,
+    options
+  );
+  if (!projectId) {
+    return 0;
+  }
+  const targetApmDir = apmRoot ?? workspaceApmDir(workdirPath);
+  const localPaths = listLocalDocumentPaths(targetApmDir, projectId);
+  if (localPaths.length === 0) {
+    console.log("[apm] \u9879\u76EE\u6587\u6863\u65E0\u672C\u5730\u6587\u4EF6\uFF0C\u8DF3\u8FC7\u63A8\u9001");
+    return 0;
+  }
+  const remoteManifest = (await api.cli.getProjectDocumentManifest({ projectId })).manifest ?? null;
+  const remoteHashByPath = new Map(
+    (remoteManifest?.documents ?? []).map((doc) => [doc.path, doc.contentHash])
+  );
+  const remoteDescriptionByPath = new Map(
+    (remoteManifest?.documents ?? []).map((doc) => [doc.path, doc.description])
+  );
+  let synced = 0;
+  for (const path of localPaths) {
+    const absPath = toFsPath(
+      projectDocumentLocalPath(targetApmDir, projectId, path)
+    );
+    const content = readFileSync4(absPath, "utf8");
+    const contentHash = hashLocalFileContent(content);
+    if (remoteHashByPath.get(path) === contentHash) {
+      continue;
+    }
+    await api.cli.upsertProjectDocument({
+      projectId,
+      path,
+      content,
+      description: remoteDescriptionByPath.get(path) ?? void 0
+    });
+    synced += 1;
+    console.log(`[apm] \u5DF2\u540C\u6B65\u9879\u76EE\u6587\u6863: ${path}`);
+  }
+  if (synced === 0) {
+    console.log("[apm] \u9879\u76EE\u6587\u6863\u65E0\u53D8\u5316\uFF0C\u8DF3\u8FC7\u63A8\u9001");
+  }
+  return synced;
+}
+
+// src/commands/sync-project-documents.ts
+async function runSyncProjectDocuments(options) {
+  const workdir = resolveWorkdirPath();
+  const apmRoot = workspaceApmDir(workdir);
+  const doPush = Boolean(options.push);
+  const doPull = Boolean(options.pull) || !doPush;
+  if (doPull) {
+    await syncProjectDocumentsPull(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);
+  }
+}
+
 // src/commands/connect.ts
 import WebSocket from "ws";
-import { setTimeout as delay2 } from "node:timers/promises";
+import { setTimeout as delay } from "node:timers/promises";
 
 // src/ws/protocol.ts
+function isWebIdeStartProjectTarget(value) {
+  return value === "frontend" || value === "backend" || value === "mobile";
+}
+function isWebIdePackageTarget(value) {
+  return value === "frontend" || value === "backend";
+}
 function nonEmptyString(v) {
   return typeof v === "string" && v.trim().length > 0;
 }
@@ -775,6 +1121,18 @@ function parseAgentWsMessage(raw) {
     return null;
   }
 }
+function serializeAgentWsMessage(msg) {
+  return JSON.stringify(msg);
+}
+function validateHeartbeat(o) {
+  if (o.type !== "heartbeat") {
+    return { ok: false, reason: "\u671F\u671B heartbeat" };
+  }
+  if (!nonEmptyString(o.userId)) {
+    return { ok: false, reason: "heartbeat \u7F3A\u5C11 userId" };
+  }
+  return { ok: true, data: { type: "heartbeat", userId: o.userId.trim() } };
+}
 function validateWebIdeMessagePush(o) {
   if (o.type !== "webide-message") {
     return { ok: false, reason: "\u671F\u671B webide-message" };
@@ -853,56 +1211,178 @@ function validateSteer(o) {
     }
   };
 }
-function validateAgentWsMessage(value, _kind = "outbound") {
-  if (typeof value !== "object" || value === null) {
-    return { ok: false, reason: "\u6D88\u606F\u4F53\u4E0D\u662F JSON \u5BF9\u8C61" };
+function validateWebIdeStopTerminals(o) {
+  if (o.type !== "webide-stop-terminals") {
+    return { ok: false, reason: "\u671F\u671B webide-stop-terminals" };
   }
-  const o = value;
-  const type = o.type;
-  if (type !== "webide-message" && type !== "cancel" && type !== "steer") {
-    return { ok: false, reason: `\u672A\u77E5 type: ${String(type)}` };
+  if (!nonEmptyString(o.taskId)) {
+    return { ok: false, reason: "webide-stop-terminals \u7F3A\u5C11 taskId" };
   }
-  if (type === "cancel") {
-    return validateCancel(o);
+  return {
+    ok: true,
+    data: {
+      type: "webide-stop-terminals",
+      taskId: o.taskId.trim()
+    }
+  };
+}
+function validateWebIdeStartProjectPush(o) {
+  if (o.type !== "webide-start-project") {
+    return { ok: false, reason: "\u671F\u671B webide-start-project" };
   }
-  if (type === "steer") {
-    return validateSteer(o);
+  if (!nonEmptyString(o.taskId)) {
+    return { ok: false, reason: "webide-start-project \u7F3A\u5C11 taskId" };
   }
-  return validateWebIdeMessagePush(o);
-}
-
-// src/commands/connect/actions/cancel.ts
-function handleCancelAction(payload, ctx) {
-  const { messageId } = payload;
-  ctx.pendingCancels.add(messageId);
-  ctx.activeRuns.get(messageId)?.abort();
-}
-
-// src/commands/connect/actions/steer.ts
-function registerRunSteer(ctx, messageId, target) {
-  const send = (text) => target.steer(messageId, text);
-  ctx.steerRuns.set(messageId, send);
-  const queued = ctx.pendingSteers.get(messageId);
-  if (!queued) return;
-  ctx.pendingSteers.delete(messageId);
-  send(queued);
-}
-function unregisterRunSteer(ctx, messageId) {
-  ctx.steerRuns.delete(messageId);
-  ctx.pendingSteers.delete(messageId);
-}
-function handleSteerAction(payload, ctx) {
-  const send = ctx.steerRuns.get(payload.messageId);
-  if (!send) {
-    ctx.pendingSteers.set(payload.messageId, payload.text);
-    console.log(`[apm] steer \u5DF2\u6392\u961F messageId=${payload.messageId}`);
-    return;
+  if (!nonEmptyString(o.messageId)) {
+    return { ok: false, reason: "webide-start-project \u7F3A\u5C11 messageId" };
   }
-  send(payload.text);
-}
-
-// src/commands/connect/core/worker/worker.ts
-import { dirname as dirname2, join as join5 } from "path";
+  if (!isWebIdeStartProjectTarget(o.target)) {
+    return { ok: false, reason: "webide-start-project \u7F3A\u5C11\u6709\u6548 target" };
+  }
+  if (!nonEmptyString(o.content)) {
+    return { ok: false, reason: "webide-start-project \u7F3A\u5C11 content" };
+  }
+  if (!nonEmptyString(o.model)) {
+    return { ok: false, reason: "webide-start-project \u7F3A\u5C11 model" };
+  }
+  if (!nonEmptyString(o.apiKey)) {
+    return { ok: false, reason: "webide-start-project \u7F3A\u5C11 apiKey" };
+  }
+  if (!nonEmptyString(o.workdir)) {
+    return { ok: false, reason: "webide-start-project \u7F3A\u5C11 workdir" };
+  }
+  if (!nonEmptyString(o.user)) {
+    return { ok: false, reason: "webide-start-project \u7F3A\u5C11 user" };
+  }
+  return {
+    ok: true,
+    data: {
+      type: "webide-start-project",
+      taskId: o.taskId.trim(),
+      messageId: o.messageId.trim(),
+      target: o.target,
+      restart: o.restart === true,
+      content: o.content,
+      model: o.model.trim(),
+      apiKey: o.apiKey.trim(),
+      workdir: o.workdir.trim(),
+      user: o.user.trim()
+    }
+  };
+}
+function validateWebIdePackagePush(o) {
+  if (o.type !== "webide-package") {
+    return { ok: false, reason: "\u671F\u671B webide-package" };
+  }
+  if (!nonEmptyString(o.packageId)) {
+    return { ok: false, reason: "webide-package \u7F3A\u5C11 packageId" };
+  }
+  if (!nonEmptyString(o.messageId)) {
+    return { ok: false, reason: "webide-package \u7F3A\u5C11 messageId" };
+  }
+  if (!nonEmptyString(o.projectId)) {
+    return { ok: false, reason: "webide-package \u7F3A\u5C11 projectId" };
+  }
+  if (!isWebIdePackageTarget(o.target)) {
+    return { ok: false, reason: "webide-package \u7F3A\u5C11\u6709\u6548 target" };
+  }
+  if (!nonEmptyString(o.baseBranch)) {
+    return { ok: false, reason: "webide-package \u7F3A\u5C11 baseBranch" };
+  }
+  if (!nonEmptyString(o.content)) {
+    return { ok: false, reason: "webide-package \u7F3A\u5C11 content" };
+  }
+  if (!nonEmptyString(o.model)) {
+    return { ok: false, reason: "webide-package \u7F3A\u5C11 model" };
+  }
+  if (!nonEmptyString(o.apiKey)) {
+    return { ok: false, reason: "webide-package \u7F3A\u5C11 apiKey" };
+  }
+  if (!nonEmptyString(o.workdir)) {
+    return { ok: false, reason: "webide-package \u7F3A\u5C11 workdir" };
+  }
+  if (!nonEmptyString(o.user)) {
+    return { ok: false, reason: "webide-package \u7F3A\u5C11 user" };
+  }
+  return {
+    ok: true,
+    data: {
+      type: "webide-package",
+      packageId: o.packageId.trim(),
+      messageId: o.messageId.trim(),
+      projectId: o.projectId.trim(),
+      target: o.target,
+      baseBranch: o.baseBranch.trim().replace(/^origin\//, ""),
+      content: o.content,
+      model: o.model.trim(),
+      apiKey: o.apiKey.trim(),
+      workdir: o.workdir.trim(),
+      user: o.user.trim()
+    }
+  };
+}
+function validateAgentWsMessage(value, kind) {
+  if (typeof value !== "object" || value === null) {
+    return { ok: false, reason: "\u6D88\u606F\u4F53\u4E0D\u662F JSON \u5BF9\u8C61" };
+  }
+  const o = value;
+  const type = o.type;
+  if (type !== "heartbeat" && type !== "webide-message" && type !== "cancel" && type !== "steer" && type !== "webide-start-project" && type !== "webide-stop-terminals" && type !== "webide-package") {
+    return { ok: false, reason: `\u672A\u77E5 type: ${String(type)}` };
+  }
+  if (kind === "heartbeat" || type === "heartbeat") {
+    return validateHeartbeat(o);
+  }
+  if (type === "cancel") {
+    return validateCancel(o);
+  }
+  if (type === "steer") {
+    return validateSteer(o);
+  }
+  if (type === "webide-start-project") {
+    return validateWebIdeStartProjectPush(o);
+  }
+  if (type === "webide-stop-terminals") {
+    return validateWebIdeStopTerminals(o);
+  }
+  if (type === "webide-package") {
+    return validateWebIdePackagePush(o);
+  }
+  return validateWebIdeMessagePush(o);
+}
+
+// src/commands/connect/actions/cancel.ts
+function handleCancelAction(payload, ctx) {
+  const { messageId } = payload;
+  ctx.pendingCancels.add(messageId);
+  ctx.activeRuns.get(messageId)?.abort();
+}
+
+// src/commands/connect/actions/steer.ts
+function registerRunSteer(ctx, messageId, target) {
+  const send = (text) => target.steer(messageId, text);
+  ctx.steerRuns.set(messageId, send);
+  const queued = ctx.pendingSteers.get(messageId);
+  if (!queued) return;
+  ctx.pendingSteers.delete(messageId);
+  send(queued);
+}
+function unregisterRunSteer(ctx, messageId) {
+  ctx.steerRuns.delete(messageId);
+  ctx.pendingSteers.delete(messageId);
+}
+function handleSteerAction(payload, ctx) {
+  const send = ctx.steerRuns.get(payload.messageId);
+  if (!send) {
+    ctx.pendingSteers.set(payload.messageId, payload.text);
+    console.log(`[apm] steer \u5DF2\u6392\u961F messageId=${payload.messageId}`);
+    return;
+  }
+  send(payload.text);
+}
+
+// src/commands/connect/core/worker/worker.ts
+import { dirname as dirname3, join as join7 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { Worker } from "node:worker_threads";
 
@@ -928,8 +1408,8 @@ function resolveWebIdeWorkerHeapMb(env = process.env, totalMemoryBytes = totalme
 }
 
 // src/commands/connect/core/worker/worker.ts
-var workerFile = join5(
-  dirname2(fileURLToPath2(import.meta.url)),
+var workerFile = join7(
+  dirname3(fileURLToPath2(import.meta.url)),
   "worker-script.js"
 );
 var ActionWorker = class {
@@ -948,8 +1428,8 @@ var ActionWorker = class {
     }
     this.msg = msg;
     this.apmClient = createApmApiClient(cfg);
-    this.promise = new Promise((resolve5, reject) => {
-      this.resolve = resolve5;
+    this.promise = new Promise((resolve3, reject) => {
+      this.resolve = resolve3;
       this.reject = reject;
     });
     this.worker = new Worker(workerFile, {
@@ -1005,6 +1485,14 @@ var ActionWorker = class {
   failIfStillQueued = async (reason) => {
     if (this.status !== "pending") return;
     try {
+      if (this.msg.type === "webide-package") {
+        await this.apmClient.cli.projectPackageUpdateStatus({
+          id: this.msg.packageId,
+          status: "CANCELLED",
+          error: reason
+        });
+        return;
+      }
       await this.apmClient.cli.webideSetMessageError({
         id: this.msg.messageId,
         error: reason,
@@ -1077,9 +1565,191 @@ function handleWebIdeMessageAction(payload, ctx) {
   trackActionTask(ctx, task);
 }
 
+// src/commands/connect/actions/start-project.ts
+function handleStartProjectAction(payload, ctx) {
+  const perMessageController = new AbortController();
+  ctx.activeRuns.set(payload.messageId, perMessageController);
+  if (ctx.pendingCancels.has(payload.messageId)) {
+    ctx.activeRuns.delete(payload.messageId);
+    ctx.pendingCancels.delete(payload.messageId);
+    const cancelTask = (async () => {
+      try {
+        const api = createApmApiClient(ctx.cfg);
+        await api.cli.webideUpdateMessageStatus({
+          id: payload.messageId,
+          status: "CANCELLED"
+        });
+      } catch (err) {
+        console.error(
+          `[apm] webide-start-project \u9884\u53D6\u6D88\u5199\u7EC8\u6001\u5931\u8D25 messageId=${payload.messageId}:`,
+          err instanceof Error ? err.message : err
+        );
+      }
+    })();
+    trackActionTask(ctx, cancelTask);
+    return;
+  }
+  const task = (async () => {
+    const handle = new ActionWorker(payload);
+    registerRunSteer(ctx, payload.messageId, handle);
+    const onAbort = () => handle.cancel(payload.messageId);
+    perMessageController.signal.addEventListener("abort", onAbort, {
+      once: true
+    });
+    try {
+      await handle.done;
+    } finally {
+      perMessageController.signal.removeEventListener("abort", onAbort);
+      unregisterRunSteer(ctx, payload.messageId);
+      ctx.activeRuns.delete(payload.messageId);
+    }
+  })();
+  trackActionTask(ctx, task);
+}
+
+// src/commands/connect/mcps/pty-session-mcp.ts
+var DEFAULT_PTY_SESSION_PORT = "7788";
+function resolvePtySessionBaseUrl(env = process.env) {
+  const explicit = env.LOCAL_TERMINAL_URL?.trim();
+  if (explicit) return explicit.replace(/\/+$/, "");
+  const port = env.LOCAL_TERMINAL_PORT?.trim() || DEFAULT_PTY_SESSION_PORT;
+  return `http://127.0.0.1:${port}`;
+}
+function asSessionList(data) {
+  if (Array.isArray(data)) return data;
+  if (data && typeof data === "object") {
+    const sessions = data.sessions;
+    if (Array.isArray(sessions)) return sessions;
+  }
+  return [];
+}
+async function requestPtyJson(url, token, init) {
+  const res = await fetch(url, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      ...init?.headers ?? {}
+    }
+  });
+  if (!res.ok) {
+    throw new Error(`pty-session HTTP ${res.status}`);
+  }
+  try {
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+async function killAllPtySessions(cfg) {
+  const token = resolveApiKey(cfg);
+  if (!token) return 0;
+  const baseUrl = resolvePtySessionBaseUrl();
+  let body;
+  try {
+    body = await requestPtyJson(`${baseUrl}/sessions`, token);
+  } catch (err) {
+    console.warn(
+      "[apm] \u5217\u51FA PTY \u4F1A\u8BDD\u5931\u8D25:",
+      err instanceof Error ? err.message : err
+    );
+    return 0;
+  }
+  const payload = body;
+  if (payload && typeof payload === "object" && payload.ok === false) {
+    return 0;
+  }
+  const data = payload && typeof payload === "object" && "data" in payload ? payload.data : body;
+  const sessions = asSessionList(data);
+  let killed = 0;
+  for (const session of sessions) {
+    const id = session.id?.trim();
+    if (!id) continue;
+    if (session.running === false) continue;
+    try {
+      await requestPtyJson(
+        `${baseUrl}/sessions/${encodeURIComponent(id)}`,
+        token,
+        {
+          method: "DELETE"
+        }
+      );
+      killed += 1;
+    } catch (err) {
+      console.warn(
+        `[apm] \u7ED3\u675F PTY \u4F1A\u8BDD\u5931\u8D25 id=${id}:`,
+        err instanceof Error ? err.message : err
+      );
+    }
+  }
+  return killed;
+}
+
+// src/commands/connect/actions/stop-terminals.ts
+function handleStopTerminalsAction(payload, ctx) {
+  const task = (async () => {
+    try {
+      const killed = await killAllPtySessions(ctx.cfg);
+      console.log(
+        `[apm] webide-stop-terminals taskId=${payload.taskId} killed=${killed}`
+      );
+    } catch (err) {
+      console.warn(
+        `[apm] webide-stop-terminals \u5931\u8D25 taskId=${payload.taskId}:`,
+        err instanceof Error ? err.message : err
+      );
+    }
+  })();
+  trackActionTask(ctx, task);
+}
+
+// src/commands/connect/actions/package.ts
+function handleWebIdePackageAction(payload, ctx) {
+  const perMessageController = new AbortController();
+  ctx.activeRuns.set(payload.messageId, perMessageController);
+  if (ctx.pendingCancels.has(payload.messageId)) {
+    ctx.activeRuns.delete(payload.messageId);
+    ctx.pendingCancels.delete(payload.messageId);
+    const cancelTask = (async () => {
+      try {
+        const api = createApmApiClient(ctx.cfg);
+        await api.cli.projectPackageUpdateStatus({
+          id: payload.packageId,
+          status: "CANCELLED",
+          error: "\u5DF2\u53D6\u6D88"
+        });
+      } catch (err) {
+        console.error(
+          `[apm] webide-package \u9884\u53D6\u6D88\u5199\u7EC8\u6001\u5931\u8D25 packageId=${payload.packageId}:`,
+          err instanceof Error ? err.message : err
+        );
+      }
+    })();
+    trackActionTask(ctx, cancelTask);
+    return;
+  }
+  const task = (async () => {
+    const handle = new ActionWorker(payload);
+    registerRunSteer(ctx, payload.messageId, handle);
+    const onAbort = () => handle.cancel(payload.messageId);
+    perMessageController.signal.addEventListener("abort", onAbort, {
+      once: true
+    });
+    try {
+      await handle.done;
+    } finally {
+      perMessageController.signal.removeEventListener("abort", onAbort);
+      unregisterRunSteer(ctx, payload.messageId);
+      ctx.activeRuns.delete(payload.messageId);
+    }
+  })();
+  trackActionTask(ctx, task);
+}
+
 // src/commands/connect/actions/index.ts
 function dispatchConnectAction(payload, ctx) {
   switch (payload.type) {
+    case "heartbeat":
+      return;
     case "cancel":
       handleCancelAction(payload, ctx);
       return;
@@ -1089,22 +1759,28 @@ function dispatchConnectAction(payload, ctx) {
     case "webide-message":
       handleWebIdeMessageAction(payload, ctx);
       return;
+    case "webide-start-project":
+      handleStartProjectAction(payload, ctx);
+      return;
+    case "webide-stop-terminals":
+      handleStopTerminalsAction(payload, ctx);
+      return;
+    case "webide-package":
+      handleWebIdePackageAction(payload, ctx);
+      return;
   }
 }
 
 // src/commands/connect-lock.ts
 import {
-  existsSync as existsSync4,
+  existsSync as existsSync6,
   mkdirSync as mkdirSync4,
-  readFileSync as readFileSync4,
+  readFileSync as readFileSync5,
   unlinkSync as unlinkSync2,
-  writeFileSync as writeFileSync3
+  writeFileSync as writeFileSync4
 } from "fs";
-import { setTimeout as delay } from "node:timers/promises";
-import { join as join6 } from "path";
-var CONNECT_LOCK_PATH = join6(APM_CONFIG_DIR, "connect.lock");
-var ACQUIRE_RETRY_MS = 5e3;
-var ACQUIRE_RETRY_INTERVAL_MS = 200;
+import { join as join8 } from "path";
+var CONNECT_LOCK_PATH = join8(APM_CONFIG_DIR, "connect.lock");
 function isProcessAlive(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false;
   try {
@@ -1115,9 +1791,9 @@ function isProcessAlive(pid) {
   }
 }
 function readConnectLock() {
-  if (!existsSync4(CONNECT_LOCK_PATH)) return null;
+  if (!existsSync6(CONNECT_LOCK_PATH)) return null;
   try {
-    const raw = readFileSync4(CONNECT_LOCK_PATH, "utf8");
+    const raw = readFileSync5(CONNECT_LOCK_PATH, "utf8");
     const parsed = JSON.parse(raw);
     if (typeof parsed.pid !== "number" || typeof parsed.startedAt !== "string") {
       return null;
@@ -1139,44 +1815,27 @@ function pruneStaleConnectLock() {
   } catch {
   }
 }
-function writeConnectLock() {
+function acquireConnectLock() {
+  pruneStaleConnectLock();
+  const existing = readConnectLock();
+  if (existing && isProcessAlive(existing.pid)) {
+    if (existing.pid === process.pid) {
+      return;
+    }
+    console.error(`[apm] \u5DF2\u6709 apm connect \u5728\u8FD0\u884C (pid=${existing.pid})`);
+    process.exit(1);
+  }
   mkdirSync4(APM_CONFIG_DIR, { recursive: true });
   const lock = {
     pid: process.pid,
     startedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
-  writeFileSync3(
+  writeFileSync4(
     CONNECT_LOCK_PATH,
     JSON.stringify(lock, null, 2) + "\n",
     "utf8"
   );
 }
-async function acquireConnectLock() {
-  const deadline = Date.now() + ACQUIRE_RETRY_MS;
-  let loggedWait = false;
-  for (; ; ) {
-    pruneStaleConnectLock();
-    const existing = readConnectLock();
-    if (!existing || !isProcessAlive(existing.pid)) {
-      writeConnectLock();
-      return;
-    }
-    if (existing.pid === process.pid) {
-      return;
-    }
-    if (Date.now() >= deadline) {
-      console.error(`[apm] \u5DF2\u6709 apm connect \u5728\u8FD0\u884C (pid=${existing.pid})`);
-      process.exit(1);
-    }
-    if (!loggedWait) {
-      console.log(
-        `[apm] \u7B49\u5F85\u65E7 connect \u91CA\u653E\u9501 (pid=${existing.pid})\u2026`
-      );
-      loggedWait = true;
-    }
-    await delay(ACQUIRE_RETRY_INTERVAL_MS);
-  }
-}
 function releaseConnectLock() {
   const lock = readConnectLock();
   if (lock?.pid !== process.pid) return;
@@ -1187,20 +1846,36 @@ function releaseConnectLock() {
 }
 
 // src/commands/connect.ts
+var HEARTBEAT_MS = 3e4;
 var RECONNECT_MIN_MS = 1e3;
 var RECONNECT_MAX_MS = 6e4;
 var SHUTDOWN_DRAIN_MS = 3e3;
 function interruptibleSleep(ms, signal) {
   if (signal.aborted) return Promise.resolve();
-  return new Promise((resolve5) => {
-    const timer = setTimeout(resolve5, ms);
+  return new Promise((resolve3) => {
+    const timer = setTimeout(resolve3, ms);
     const onAbort = () => {
       clearTimeout(timer);
-      resolve5();
+      resolve3();
     };
     signal.addEventListener("abort", onAbort, { once: true });
   });
 }
+function startHeartbeat(ws, clientMachineId) {
+  const send = () => {
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(
+        serializeAgentWsMessage({
+          type: "heartbeat",
+          userId: clientMachineId
+        })
+      );
+    }
+  };
+  send();
+  const timer = setInterval(send, HEARTBEAT_MS);
+  return () => clearInterval(timer);
+}
 function attachWsHandlers(ws, ctx, onOpen) {
   const { isShuttingDown } = ctx;
   ws.on("open", () => {
@@ -1215,6 +1890,9 @@ function attachWsHandlers(ws, ctx, onOpen) {
       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}`);
@@ -1224,13 +1902,15 @@ function attachWsHandlers(ws, ctx, onOpen) {
   });
 }
 function connectOnce(url, ctx, connectionAbort, onConnected) {
-  return new Promise((resolve5, reject) => {
+  return new Promise((resolve3, 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 = () => {
@@ -1239,7 +1919,10 @@ function connectOnce(url, ctx, connectionAbort, onConnected) {
       }
     };
     connectionAbort.addEventListener("abort", onConnectionAbort);
-    attachWsHandlers(ws, ctx, onConnected);
+    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()}` : ""}`
@@ -1248,7 +1931,7 @@ function connectOnce(url, ctx, connectionAbort, onConnected) {
         finish(() => reject(new Error("shutdown")));
         return;
       }
-      finish(resolve5);
+      finish(resolve3);
     });
     ws.on("error", (err) => {
       console.error("[apm] WebSocket \u9519\u8BEF:", err.message);
@@ -1262,22 +1945,33 @@ function connectOnce(url, ctx, connectionAbort, onConnected) {
     });
   });
 }
+function resolveConnectServerOption(options) {
+  const fromOption = options.server?.trim();
+  if (fromOption) {
+    return fromOption.replace(/\/+$/, "");
+  }
+  const fromEnv = process.env.AI_PM_SERVER?.trim();
+  if (fromEnv) {
+    return fromEnv.replace(/\/+$/, "");
+  }
+  return void 0;
+}
 async function runConnect(options) {
+  const { didUpdate } = await runUpdate({ quietIfCurrent: true });
+  if (didUpdate) {
+    reexecConnectAfterUpdate(options);
+  }
   const cfg = await ensureLoggedConfig();
-  const endpoints = resolveApmEndpoints({
-    server: options.server,
-    socketServer: options.socketServer,
-    configBaseUrl: cfg.baseUrl,
-    configSocketServer: cfg.socketServer
-  });
-  cfg.baseUrl = endpoints.baseUrl;
-  cfg.socketServer = endpoints.socketServer;
+  const serverOverride = resolveConnectServerOption(options);
+  if (serverOverride) {
+    cfg.baseUrl = serverOverride;
+  }
   const clientMachineId = resolveClientMachineId(cfg);
   if (!clientMachineId) {
     console.error("[apm] config \u7F3A\u5C11 clientMachineId\uFF0C\u8BF7\u91CD\u65B0 apm login");
     process.exit(1);
   }
-  await acquireConnectLock();
+  acquireConnectLock();
   process.on("exit", releaseConnectLock);
   let shuttingDown = false;
   let shutdownPromise = null;
@@ -1304,11 +1998,11 @@ async function runConnect(options) {
     lifecycleAbort.abort();
     currentConnectionAbort?.abort();
     shutdownAbort.abort();
-    releaseConnectLock();
     try {
-      await Promise.race([Promise.all(activeTasks), delay2(drainMs)]);
+      await Promise.race([Promise.all(activeTasks), delay(drainMs)]);
     } catch {
     }
+    releaseConnectLock();
     process.exit(code);
   };
   const shutdown = (code = 0) => {
@@ -1330,12 +2024,8 @@ async function runConnect(options) {
       lifecycleAbort.signal,
       currentConnectionAbort.signal
     ]);
-    const url = buildAgentWsUrl(
-      cfg.socketServer ?? cfg.baseUrl,
-      resolveApiKey(cfg)
-    );
-    const visible = url.replace(/([?&]apiKey=)[^&]+/, "$1***");
-    console.log(`[apm] \u8FDE\u63A5 ${visible} \u2026`);
+    const url = buildAgentWsUrl(cfg.baseUrl, resolveApiKey(cfg));
+    console.log(`[apm] \u8FDE\u63A5 ${cfg.baseUrl} \u2026`);
     try {
       await connectOnce(url, connectCtx, connectionSignal, () => {
         reconnectDelay = RECONNECT_MIN_MS;
@@ -1367,606 +2057,18 @@ async function runConnect(options) {
   }
 }
 
-// src/utils/home-repository.ts
-import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
-import { join as join7, resolve as resolve3 } from "path";
-var DEFAULT_REPOS_MANIFEST = "/home/repository.json";
-function isSimpleChildDirName(name) {
-  if (!name || name === "." || name === "..") return false;
-  if (name.includes("/") || name.includes("\\")) return false;
-  return true;
-}
-function resolveReposManifestPath(explicit) {
-  const fromOpt = explicit?.trim() || "";
-  if (fromOpt) return fromOpt;
-  const fromEnv = process.env.APM_REPOS_MANIFEST?.trim() || "";
-  if (fromEnv) return fromEnv;
-  return null;
-}
-function resolveCliReposManifestPath(explicit) {
-  return resolveReposManifestPath(explicit) ?? DEFAULT_REPOS_MANIFEST;
-}
-function loadHomeRepositoryEntries(manifestPath2) {
-  const label = manifestPath2.trim();
-  if (!label) {
-    throw new Error("[apm] \u591A\u4ED3\u6E05\u5355\u8DEF\u5F84\u4E3A\u7A7A");
-  }
-  const path = toFsPath(label);
-  if (!existsSync5(path)) {
-    throw new Error(`[apm] \u672A\u627E\u5230\u591A\u4ED3\u6E05\u5355 ${label}`);
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(readFileSync5(path, "utf8"));
-  } catch (err) {
-    const detail = err instanceof Error ? err.message : String(err);
-    throw new Error(`[apm] \u89E3\u6790 ${label} \u5931\u8D25: ${detail}`);
-  }
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error(
-      `[apm] ${label} \u987B\u4E3A\u5BF9\u8C61\uFF1Akey=\u4E0B\u7EA7\u76EE\u5F55\uFF0Cvalue=git \u5730\u5740`
-    );
-  }
-  const entries = [];
-  for (const [rawKey, rawVal] of Object.entries(
-    parsed
-  )) {
-    const pathKey = rawKey.trim();
-    if (!isSimpleChildDirName(pathKey)) {
-      throw new Error(
-        `[apm] ${label} \u975E\u6CD5\u76EE\u5F55 key: ${JSON.stringify(rawKey)}\uFF08\u987B\u4E3A\u5F53\u524D\u4E0B\u7EA7\u76EE\u5F55\u540D\uFF09`
-      );
-    }
-    if (typeof rawVal !== "string" || !rawVal.trim()) {
-      throw new Error(
-        `[apm] ${label}[${pathKey}] \u987B\u4E3A\u975E\u7A7A git \u5730\u5740\u5B57\u7B26\u4E32`
-      );
-    }
-    entries.push({ path: pathKey, remoteUrl: rawVal.trim() });
-  }
-  entries.sort((a, b) => a.path.localeCompare(b.path));
-  if (entries.length === 0) {
-    throw new Error(`[apm] ${label} \u4E3A\u7A7A\uFF0C\u65E0\u4ED3\u5E93\u53EF\u786E\u8BA4`);
-  }
-  return entries;
-}
-function resolveHomeRepositoryAbsolutePaths(workdirInput, entries) {
-  const workdir = resolveWorkdirPath(workdirInput);
-  return entries.map((entry) => resolve3(join7(workdir, entry.path)));
-}
-
-// src/utils/git.ts
-import { execFile } from "child_process";
-import { dirname as dirname3, join as join8 } from "path";
-import { fileURLToPath as fileURLToPath3 } from "url";
-import { promisify } from "util";
-var execFileAsync = promisify(execFile);
-var GIT_NETWORK_TIMEOUT_MS = 9e4;
-var GIT_PUSH_TIMEOUT_MS = 12e4;
-var GIT_LOCAL_TIMEOUT_MS = 6e4;
-var GIT_NETWORK_CMDS = /* @__PURE__ */ new Set([
-  "fetch",
-  "push",
-  "ls-remote",
-  "clone",
-  "pull"
-]);
-function mergeGitSshCommand(existing) {
-  const base = existing?.trim() || "ssh";
-  const extras = [];
-  if (!/\bStrictHostKeyChecking=/.test(base)) {
-    extras.push("-o", "StrictHostKeyChecking=accept-new");
-  }
-  if (!/\bBatchMode=/.test(base)) {
-    extras.push("-o", "BatchMode=yes");
-  }
-  if (!/\bConnectTimeout=/.test(base)) {
-    extras.push("-o", "ConnectTimeout=20");
-  }
-  if (!/\bServerAliveInterval=/.test(base)) {
-    extras.push("-o", "ServerAliveInterval=10");
-  }
-  if (!/\bServerAliveCountMax=/.test(base)) {
-    extras.push("-o", "ServerAliveCountMax=3");
-  }
-  return extras.length ? `${base} ${extras.join(" ")}` : base;
-}
-function gitExecEnv() {
-  return {
-    ...process.env,
-    GIT_SSH_COMMAND: mergeGitSshCommand(process.env.GIT_SSH_COMMAND),
-    // 避免 credential helper / askpass 在无 TTY 时挂起
-    GIT_TERMINAL_PROMPT: "0"
-  };
-}
-function defaultGitTimeoutMs(args) {
-  const cmd = args[0] ?? "";
-  if (cmd === "push") return GIT_PUSH_TIMEOUT_MS;
-  if (GIT_NETWORK_CMDS.has(cmd)) return GIT_NETWORK_TIMEOUT_MS;
-  return GIT_LOCAL_TIMEOUT_MS;
-}
-async function execGit(cwd, args, quietOrOptions = false) {
-  const options = typeof quietOrOptions === "boolean" ? { quiet: quietOrOptions } : quietOrOptions;
-  const quiet = options.quiet ?? false;
-  const timeoutMs = options.timeoutMs === void 0 ? defaultGitTimeoutMs(args) : options.timeoutMs;
-  try {
-    const { stdout, stderr } = await execFileAsync("git", args, {
-      cwd,
-      env: gitExecEnv(),
-      encoding: "utf8",
-      maxBuffer: 10 * 1024 * 1024,
-      ...timeoutMs > 0 ? { timeout: timeoutMs, killSignal: "SIGTERM" } : {}
-    });
-    if (!quiet && stderr.trim()) {
-      process.stderr.write(stderr);
-    }
-    return stdout;
-  } catch (err) {
-    const e = err;
-    if (e.killed || e.signal === "SIGTERM" || e.code === "ETIMEDOUT") {
-      throw new Error(
-        `[apm] git ${args.join(" ")} \u8D85\u65F6\uFF08>${timeoutMs}ms\uFF09\uFF0C\u8BF7\u68C0\u67E5\u5230\u8FDC\u7A0B\u7684\u7F51\u7EDC/SSH\uFF1B\u53EF\u7A0D\u540E\u91CD\u8BD5`
-      );
-    }
-    const detail = (e.stderr ?? e.message ?? String(err)).trim();
-    throw new Error(
-      `[apm] git ${args.join(" ")} \u5931\u8D25${detail ? `: ${detail}` : ""}`
-    );
-  }
-}
-async function ensureGitRepo(cwd) {
-  await execGit(cwd, ["rev-parse", "--git-dir"], true);
-}
-async function resolveGitRepoRoot(cwd) {
-  return (await execGit(cwd, ["rev-parse", "--show-toplevel"], true)).trim();
-}
-function resolveGitScript(name) {
-  return join8(dirname3(fileURLToPath3(import.meta.url)), "scripts", name);
-}
-async function runGitScript(name, options) {
-  const skipCode = options.skipCode ?? 2;
-  const timeoutMs = options.timeoutMs ?? GIT_NETWORK_TIMEOUT_MS;
-  const script = resolveGitScript(name);
-  const args = [script, ...options.args ?? []];
-  try {
-    const { stdout, stderr } = await execFileAsync("bash", args, {
-      cwd: options.cwd,
-      env: gitExecEnv(),
-      encoding: "utf8",
-      maxBuffer: 10 * 1024 * 1024,
-      timeout: timeoutMs,
-      killSignal: "SIGTERM"
-    });
-    if (stdout.trim()) process.stdout.write(stdout);
-    if (stderr.trim()) process.stderr.write(stderr);
-    return true;
-  } catch (err) {
-    const e = err;
-    if (e.stdout?.trim()) process.stdout.write(e.stdout);
-    if (e.stderr?.trim()) process.stderr.write(e.stderr);
-    if (e.code === skipCode) {
-      return false;
-    }
-    if (e.killed || e.signal === "SIGTERM" || e.code === "ETIMEDOUT") {
-      throw new Error(
-        `[apm] ${name} \u8D85\u65F6\uFF08>${timeoutMs}ms\uFF09\uFF0C\u8BF7\u68C0\u67E5\u5230\u8FDC\u7A0B\u7684\u7F51\u7EDC/SSH\uFF1B\u53EF\u7A0D\u540E\u91CD\u8BD5`
-      );
-    }
-    const detail = (e.stderr ?? e.message ?? String(err)).trim();
-    throw new Error(`[apm] ${name} \u5931\u8D25${detail ? `: ${detail}` : ""}`);
-  }
-}
-async function commitWorkingTreeIfDirty(cwd, message) {
-  await ensureGitRepo(cwd);
-  return runGitScript("commit_if_dirty.sh", {
-    cwd,
-    args: message?.trim() ? [message.trim()] : [],
-    timeoutMs: GIT_LOCAL_TIMEOUT_MS
-  });
-}
-async function ensureFeatureBranch(cwd, branch, baselineBranch) {
-  await runGitScript("ensure_feature_branch.sh", {
-    cwd,
-    args: [branch, baselineBranch],
-    timeoutMs: GIT_PUSH_TIMEOUT_MS
-  });
-}
-async function pushCurrentBranch(cwd) {
-  return runGitScript("push_code.sh", {
-    cwd,
-    timeoutMs: GIT_PUSH_TIMEOUT_MS
-  });
-}
-
-// src/commands/branch.ts
-import { basename as basename2 } from "path";
-
-// src/utils/workspace-repos.ts
-import {
-  existsSync as existsSync6,
-  mkdirSync as mkdirSync5,
-  readFileSync as readFileSync6,
-  readdirSync as readdirSync3,
-  statSync as statSync3,
-  writeFileSync as writeFileSync4
-} from "fs";
-import { basename, dirname as dirname4, join as join9, relative, resolve as resolve4 } from "path";
-
-// src/utils/git-remote.ts
-import { execFile as execFile2 } from "child_process";
-import { promisify as promisify2 } from "util";
-var execFileAsync2 = promisify2(execFile2);
-
-// src/utils/workspace-repos.ts
-var WORKSPACE_REPOS_MANIFEST = "workspace-repos.json";
-var WORKSPACE_REPOS_VERSION = 1;
-function manifestPath(workdir) {
-  return join9(workspaceApmDir(workdir), WORKSPACE_REPOS_MANIFEST);
-}
-function absoluteRepoPath(workdir, entry) {
-  return resolve4(workdir, entry.path);
-}
-function toRelativeRepoPath(workdir, repoAbs) {
-  return relative(workdir, repoAbs).replace(/\\/g, "/");
-}
-function normalizeRepoEntry(raw) {
-  if (!raw || typeof raw !== "object") return null;
-  const o = raw;
-  if (typeof o.path !== "string" || !o.path.trim()) return null;
-  const path = o.path.trim().replace(/\\/g, "/");
-  if (path === "." || path.includes("/")) return null;
-  const entry = { path };
-  if (typeof o.remoteUrl === "string" && o.remoteUrl.trim()) {
-    entry.remoteUrl = o.remoteUrl.trim();
-  } else if (o.remoteUrl === null) {
-    entry.remoteUrl = null;
-  }
-  return entry;
-}
-function readManifest(workdir) {
-  const path = toFsPath(manifestPath(workdir));
-  if (!existsSync6(path)) {
-    return null;
-  }
-  try {
-    const raw = JSON.parse(
-      readFileSync6(path, "utf8")
-    );
-    if (raw?.version !== WORKSPACE_REPOS_VERSION) {
-      return null;
-    }
-    if (raw.kind !== "multi") {
-      return null;
-    }
-    if (!Array.isArray(raw.repos) || raw.repos.length === 0) {
-      return null;
-    }
-    if (typeof raw.workdir !== "string" || !raw.workdir.trim()) {
-      return null;
-    }
-    const repos = raw.repos.map((item) => normalizeRepoEntry(item)).filter((item) => item != null);
-    if (repos.length === 0) {
-      return null;
-    }
-    return {
-      version: WORKSPACE_REPOS_VERSION,
-      kind: "multi",
-      workdir: raw.workdir,
-      repos,
-      scannedAt: typeof raw.scannedAt === "string" && raw.scannedAt.trim() ? raw.scannedAt : (/* @__PURE__ */ new Date()).toISOString()
-    };
-  } catch {
-    return null;
-  }
-}
-function loadWorkspaceReposCache(workdirInput) {
-  const workdir = resolveWorkdirPath(workdirInput);
-  const cached = readManifest(workdir);
-  if (!cached) {
-    throw new Error(
-      `[apm] \u672A\u627E\u5230\u5DE5\u4F5C\u533A\u4ED3\u5E93\u7F13\u5B58 .apm/${WORKSPACE_REPOS_MANIFEST}\uFF0C\u8BF7\u5148\u6267\u884C\u4ED3\u5E93\u68C0\u6D4B`
-    );
-  }
-  if (normalizeWorkdirPath(cached.workdir) !== normalizeWorkdirPath(workdir)) {
-    throw new Error(
-      `[apm] \u5DE5\u4F5C\u533A\u4ED3\u5E93\u7F13\u5B58 workdir \u4E0D\u5339\u914D\uFF1A\u7F13\u5B58=${cached.workdir} \u5F53\u524D=${workdir}\uFF0C\u8BF7\u5F3A\u5236\u91CD\u65B0\u626B\u63CF`
-    );
-  }
-  if (!Array.isArray(cached.repos) || cached.repos.length === 0) {
-    throw new Error(`[apm] \u5DE5\u4F5C\u533A\u4ED3\u5E93\u7F13\u5B58\u65E0\u6548\uFF08repos \u4E3A\u7A7A\uFF09\uFF0C\u8BF7\u5F3A\u5236\u91CD\u65B0\u626B\u63CF`);
-  }
-  console.log(
-    `[apm] \u8BFB\u53D6\u5DE5\u4F5C\u533A\u4ED3\u5E93\u7F13\u5B58 repos=${cached.repos.map((r) => r.path).join(", ")}`
-  );
-  return {
-    ...cached,
-    workdir
-  };
-}
-function resolveWorkspaceRepoAbsolutePaths(manifest) {
-  return manifest.repos.map(
-    (entry) => absoluteRepoPath(manifest.workdir, entry)
-  );
-}
-function formatRepoLabel(workdir, repoAbs) {
-  const rel = toRelativeRepoPath(resolveWorkdirPath(workdir), repoAbs);
-  return rel || basename(repoAbs) || repoAbs;
-}
-
-// src/commands/branch.ts
-import { existsSync as existsSync7 } from "fs";
-var TASK_BRANCH_PREFIX = "feat/task-";
-async function syncTaskRepos(workdir, options = {}) {
-  const opts = typeof options === "string" ? { message: options } : options;
-  const workdirPath = resolveWorkdirPath(workdir);
-  const repoRoots = resolveTaskBranchRepoRoots(
-    workdirPath,
-    opts.reposManifest
-  );
-  let committed = 0;
-  let commitSkipped = 0;
-  let pushed = 0;
-  let pushSkipped = 0;
-  const failed = [];
-  const message = opts.message;
-  for (const gitRoot of repoRoots) {
-    const label = formatRepoLabel(workdirPath, gitRoot);
-    try {
-      const didCommit = await commitWorkingTreeIfDirty(gitRoot, message);
-      if (didCommit) {
-        committed += 1;
-        console.log(`[apm] \u5DF2\u63D0\u4EA4 @ ${label}`);
-      } else {
-        commitSkipped += 1;
-      }
-    } catch (err) {
-      const detail = err instanceof Error ? err.message : String(err);
-      console.error(`[apm] \u4ED3\u5E93 ${label} \u63D0\u4EA4\u5931\u8D25\uFF08\u7EE7\u7EED\u5176\u5B83\u4ED3\uFF09: ${detail}`);
-      failed.push(label);
-      continue;
-    }
-    try {
-      const didPush = await pushCurrentBranch(gitRoot);
-      if (didPush) {
-        pushed += 1;
-        console.log(`[apm] \u5DF2 push @ ${label}`);
-      } else {
-        pushSkipped += 1;
-      }
-    } catch (err) {
-      const detail = err instanceof Error ? err.message : String(err);
-      console.error(`[apm] \u4ED3\u5E93 ${label} push \u5931\u8D25\uFF08\u7EE7\u7EED\u5176\u5B83\u4ED3\uFF09: ${detail}`);
-      failed.push(label);
-    }
-  }
-  return {
-    committed,
-    commitSkipped,
-    pushed,
-    pushSkipped,
-    failed,
-    repos: repoRoots
-  };
-}
-function branchNameForTask(taskId) {
-  const id = taskId.trim();
-  if (!id) {
-    throw new Error("[apm] \u4EFB\u52A1 ID \u4E0D\u80FD\u4E3A\u7A7A");
-  }
-  if (/[\s/\\]/.test(id)) {
-    throw new Error(
-      "[apm] \u4EFB\u52A1 ID \u4E0D\u80FD\u5305\u542B\u7A7A\u767D\u6216\u8DEF\u5F84\u5206\u9694\u7B26\uFF0C\u8BF7\u4F7F\u7528\u5B57\u6BCD\u3001\u6570\u5B57\u3001._- \u7B49"
-    );
-  }
-  return `${TASK_BRANCH_PREFIX}${id}`;
-}
-async function ensureTaskFeatureBranch(branch, projectId, options) {
-  const cwd = options.cwd ?? process.cwd();
-  const gitRoot = await resolveGitRepoRoot(cwd);
-  await ensureFeatureBranch(gitRoot, branch, projectId);
-  return branch;
-}
-function isWorkspaceReposManifestFile(manifestPath2) {
-  return basename2(manifestPath2.replace(/\\/g, "/")) === WORKSPACE_REPOS_MANIFEST;
-}
-function resolveTaskBranchRepoRoots(workdirPath, reposManifest) {
-  const manifestPath2 = resolveReposManifestPath(reposManifest);
-  if (manifestPath2 && !isWorkspaceReposManifestFile(manifestPath2)) {
-    const entries = loadHomeRepositoryEntries(manifestPath2);
-    const roots2 = resolveHomeRepositoryAbsolutePaths(workdirPath, entries);
-    console.log(
-      `[apm] \u8BFB\u53D6\u5916\u90E8\u591A\u4ED3\u6E05\u5355 ${manifestPath2} repos=${entries.map((e) => `${e.path}\u2192${e.remoteUrl}`).join(", ")}`
-    );
-    return roots2;
-  }
-  if (manifestPath2 && isWorkspaceReposManifestFile(manifestPath2)) {
-    const fsPath = toFsPath(manifestPath2);
-    if (!existsSync7(fsPath)) {
-      throw new Error(`[apm] \u672A\u627E\u5230\u5DE5\u4F5C\u533A\u4ED3\u5E93\u6E05\u5355 ${manifestPath2}`);
-    }
-    console.log(`[apm] \u4F7F\u7528\u663E\u5F0F\u5DE5\u4F5C\u533A\u4ED3\u5E93\u6E05\u5355 ${manifestPath2}`);
-  }
-  const workspace = loadWorkspaceReposCache(workdirPath);
-  const roots = resolveWorkspaceRepoAbsolutePaths(workspace);
-  console.log(
-    `[apm] \u8BFB\u53D6\u5DE5\u4F5C\u533A\u4ED3\u5E93\u6E05\u5355 repos=${workspace.repos.map(
-      (r) => r.remoteUrl ? `${r.path}\u2192${r.remoteUrl}` : r.path
-    ).join(", ")}`
-  );
-  return roots;
-}
-async function runTaskBranch(taskId, projectId, options = {}) {
-  const trimmedTaskId = taskId.trim();
-  if (!trimmedTaskId) {
-    throw new Error("[apm] taskId \u4E0D\u80FD\u4E3A\u7A7A");
-  }
-  const trimmedProjectId = projectId.trim();
-  if (!trimmedProjectId) {
-    throw new Error("[apm] projectId\uFF08\u9879\u76EE ID\uFF09\u4E0D\u80FD\u4E3A\u7A7A");
-  }
-  if (/[\s\\]/.test(trimmedProjectId) || trimmedProjectId.includes("..")) {
-    throw new Error("[apm] \u9879\u76EE ID \u975E\u6CD5");
-  }
-  const cwd = options.cwd ?? process.cwd();
-  const workdirPath = resolveWorkdirPath(cwd);
-  const repoRoots = resolveTaskBranchRepoRoots(
-    workdirPath,
-    options.reposManifest
-  );
-  if (repoRoots.length === 0) {
-    throw new Error("[apm] \u5DE5\u4F5C\u533A\u4ED3\u5E93\u6E05\u5355\u4E3A\u7A7A\uFF0C\u65E0\u6CD5\u786E\u8BA4\u7279\u6027\u5206\u652F");
-  }
-  const branch = branchNameForTask(trimmedTaskId);
-  const repoLabels = repoRoots.map(
-    (gitRoot) => formatRepoLabel(workdirPath, gitRoot)
-  );
-  console.log(
-    `[apm] \u591A\u4ED3\u786E\u8BA4\u7279\u6027\u5206\u652F ${branch} projectId=${trimmedProjectId} repos=${repoLabels.join(",")}`
-  );
-  for (const gitRoot of repoRoots) {
-    const label = formatRepoLabel(workdirPath, gitRoot);
-    console.log(
-      `[apm] \u4EFB\u52A1\u5206\u652F ${branch} @ ${label} (projectId=${trimmedProjectId})`
-    );
-    try {
-      await ensureTaskFeatureBranch(branch, trimmedProjectId, {
-        ...options,
-        cwd: gitRoot
-      });
-    } catch (err) {
-      const detail = err instanceof Error ? err.message : String(err);
-      throw new Error(
-        `[apm] \u4ED3\u5E93 ${label} \u786E\u8BA4\u7279\u6027\u5206\u652F\u5931\u8D25\uFF08\u591A\u4ED3\u4EFB\u4E00\u5931\u8D25\u5219\u6574\u6B21\u5931\u8D25\uFF09: ${detail}`
-      );
-    }
-  }
-  return {
-    branch,
-    projectId: trimmedProjectId,
-    kind: "multi",
-    repos: repoRoots
-  };
-}
-
-// src/commands/ensure-task-branch.ts
-async function runEnsureTaskBranchCli(options = {}) {
-  const workdir = resolveWorkdirPath(options.cwd ?? process.cwd());
-  const taskId = options.taskId?.trim() || "";
-  const projectId = options.projectId?.trim() || "";
-  if (!taskId) {
-    throw new Error("[apm] \u7F3A\u5C11 taskId\uFF1A\u8BF7\u4F20\u5165\u53C2\u6570");
-  }
-  if (!projectId) {
-    throw new Error("[apm] \u7F3A\u5C11 projectId\uFF1A\u8BF7\u4F20\u5165\u53C2\u6570");
-  }
-  const result = await runTaskBranch(taskId, projectId, {
-    cwd: workdir,
-    reposManifest: resolveCliReposManifestPath(options.reposManifest)
-  });
-  console.log(
-    `[apm] \u7279\u6027\u5206\u652F\u5DF2\u5C31\u7EEA\uFF08\u5168\u90E8 ${result.repos.length} \u4E2A\u4ED3\uFF09 branch=${result.branch} projectId=${result.projectId}`
-  );
-}
-
-// src/utils/user-prompt-cache.ts
-import { createHash } from "crypto";
-import { existsSync as existsSync8, mkdirSync as mkdirSync6, readFileSync as readFileSync7, writeFileSync as writeFileSync5 } from "fs";
-import { join as join10 } from "path";
-import { tmpdir } from "os";
-var CACHE_ROOT = join10(tmpdir(), "apm-hooks");
-var PROMPT_FILE = "user-prompt.txt";
-var COMMIT_SUBJECT_MAX_LEN = 100;
-function workdirKey(workdir) {
-  return createHash("sha256").update(resolveWorkdirPath(workdir)).digest("hex").slice(0, 16);
-}
-function userPromptCachePath(workdirInput) {
-  const workdir = resolveWorkdirPath(workdirInput);
-  return join10(CACHE_ROOT, workdirKey(workdir), PROMPT_FILE);
-}
-function formatUserPromptAsCommitMessage(prompt) {
-  const oneLine = prompt.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n").map((l) => l.trim()).find((l) => l.length > 0);
-  if (!oneLine) return "";
-  const cleaned = oneLine.replace(/\s+/g, " ").trim();
-  if (cleaned.length <= COMMIT_SUBJECT_MAX_LEN) return cleaned;
-  return `${cleaned.slice(0, COMMIT_SUBJECT_MAX_LEN - 1)}\u2026`;
-}
-function loadUserPromptCommitMessage(workdirInput) {
-  const path = toFsPath(userPromptCachePath(workdirInput));
-  if (!existsSync8(path)) return null;
-  try {
-    const raw = readFileSync7(path, "utf8");
-    const msg = formatUserPromptAsCommitMessage(raw);
-    return msg || null;
-  } catch {
-    return null;
-  }
-}
-
-// src/commands/commit-task-repos.ts
-function resolveCommitTaskMessage(workdir, explicit) {
-  const fromOpt = explicit?.trim() ?? "";
-  if (fromOpt) return fromOpt;
-  const fromPrompt = loadUserPromptCommitMessage(workdir);
-  if (fromPrompt) return fromPrompt;
-  const taskId = process.env.APM_TASK_ID?.trim() || "";
-  const projectId = process.env.APM_PROJECT_ID?.trim() || "";
-  if (taskId) {
-    let branch = "";
-    try {
-      branch = branchNameForTask(taskId);
-    } catch {
-      branch = `feat/task-${taskId}`;
-    }
-    if (projectId) {
-      return `chore(apm): sync ${branch} (project ${projectId})`;
-    }
-    return `chore(apm): sync ${branch}`;
-  }
-  if (projectId) {
-    return `chore(apm): sync workspace (project ${projectId})`;
-  }
-  return void 0;
-}
-async function runCommitTaskReposCli(options = {}) {
-  const workdir = resolveWorkdirPath(options.cwd ?? process.cwd());
-  const message = resolveCommitTaskMessage(workdir, options.message);
-  if (message) {
-    console.log(`[apm] commit message: ${message}`);
-  }
-  const result = await syncTaskRepos(workdir, {
-    message,
-    reposManifest: resolveCliReposManifestPath(options.reposManifest)
-  });
-  console.log(
-    `[apm] \u591A\u4ED3\u6536\u5C3E\u5B8C\u6210 committed=${result.committed} commitSkipped=${result.commitSkipped} pushed=${result.pushed} pushSkipped=${result.pushSkipped} failed=${result.failed.length} repos=${result.repos.length}`
-  );
-  if (result.failed.length > 0) {
-    throw new Error(
-      `[apm] \u591A\u4ED3\u6536\u5C3E\u90E8\u5206\u5931\u8D25: ${result.failed.join(", ")}`
-    );
-  }
-}
-
 // src/index.ts
 function buildProgram() {
   const program = new Command();
   program.name("apm").description(
     `\u6BD4\u90BB\u661F\u56FE\u547D\u4EE4\u884C\uFF08WebIDE \u5DE5\u4F5C\u533A\u4E0E\u7814\u53D1\u81EA\u52A8\u5316\uFF09\u3002
-\u5730\u5740\u53EF\u7528 --server / --socket-server\uFF0C\u6216\u73AF\u5883\u53D8\u91CF APM_SERVER / APM_SOCKET_SERVER\uFF1B\u672A\u8BBE\u7F6E\u65F6\u9ED8\u8BA4 ${DEFAULT_BASE_URL}\u3002`
+\u672A\u4F20 --server \u65F6\u4F18\u5148\u4F7F\u7528\u73AF\u5883\u53D8\u91CF AI_PM_SERVER\uFF0C\u5426\u5219\u9ED8\u8BA4 ${DEFAULT_BASE_URL}\u3002`
   ).version(readCliVersion(), "-V, --version", "\u663E\u793A\u7248\u672C\u53F7").helpOption("-h, --help", "\u663E\u793A\u5E2E\u52A9").showHelpAfterError(true);
   program.command("login").description(
     "\u9A8C\u8BC1 API Key \u5E76\u5199\u5165 ~/.config/apm/config.json\uFF08GET /api/v1/cli/me\uFF09"
-  ).option("--api-key <key>", "\u8FDC\u7A0B\u4E3B\u673A API Key\uFF08cm_ \u5F00\u5934\uFF09").option(
-    "--server <url>",
-    "API \u6839\u5730\u5740\uFF1B\u82E5\u53EA\u4F20\u6B64\u9879\u4E14\u5E26\u7AEF\u53E3\uFF0C\u5219\u7AEF\u53E3\u89C6\u4E3A Socket \u7AEF\u53E3\uFF08API \u53BB\u6389\u7AEF\u53E3\uFF09"
-  ).option(
-    "--socket-server <url>",
-    "Agent WebSocket \u6839\u5730\u5740\uFF08\u53EF\u4E0E API \u4E0D\u540C\uFF09\uFF0C\u4F8B\u5982 wss://ws.example.com"
-  ).action(
-    async (opts) => {
-      await runLogin(opts);
-    }
-  );
+  ).option("--api-key <key>", "\u8FDC\u7A0B\u4E3B\u673A API Key\uFF08cm_ \u5F00\u5934\uFF09").option("--server <url>", "API \u6839\u5730\u5740\uFF0C\u4F8B\u5982 http://127.0.0.1:3000").action(async (opts) => {
+    await runLogin(opts);
+  });
   program.command("init").description("\u5728\u5F53\u524D\u5DE5\u4F5C\u76EE\u5F55\u6309 WebIDE \u5DE5\u4F5C\u533A\u521D\u59CB\u5316\uFF1A\u4ECE\u5E73\u53F0\u5199\u5165\u6307\u5357\u4E0E\u89C4\u5219").action(async () => {
     await runInit();
   });
@@ -1983,52 +2085,15 @@ function buildProgram() {
   program.command("update-skills").description("\u4ECE\u5E73\u53F0\u540C\u6B65 .apm/ \u4E0B\u7684 WebIDE \u6307\u5357\u4E0E\u89C4\u5219").action(async () => {
     await runUpdateSkills();
   });
-  program.command("ensure-task-branch").description(
-    "\u6309\u591A\u4ED3\u6E05\u5355\u786E\u4FDD\u5404\u4ED3\u4F4D\u4E8E feat/task-<\u4EFB\u52A1ID>\uFF08\u4E0D\u5B58\u5728\u5219\u57FA\u4E8E\u9879\u76EE\u5206\u652F\u4ECE\u8FDC\u7A0B\u521B\u5EFA\uFF09\u3002ACP \u4E0D\u4F1A\u8DD1 Cursor hooks\uFF0C\u5F00\u59CB\u4EFB\u52A1\u65F6\u7531\u670D\u52A1\u7AEF\u6216\u624B\u52A8\u8C03\u7528\u672C\u547D\u4EE4"
-  ).argument("<taskId>", "\u4EFB\u52A1 ID\uFF08\u521B\u5EFA/\u5207\u6362\u5206\u652F\uFF09").argument(
-    "<projectId>",
-    "\u9879\u76EE ID\uFF08\u4EC5\u521B\u5EFA\u65F6\u7528\uFF1B\u89C4\u8303\u4E0E\u9879\u76EE\u5206\u652F\u540C\u540D\uFF09"
-  ).option("--cwd <dir>", "\u5DE5\u4F5C\u533A\u6839\u76EE\u5F55\uFF08\u9ED8\u8BA4\u5F53\u524D\u76EE\u5F55\uFF09").option(
-    "--repos <file>",
-    "\u591A\u4ED3\u6E05\u5355 JSON\uFF08key=\u4E0B\u7EA7\u76EE\u5F55\uFF0Cvalue=git \u5730\u5740\uFF09\uFF1B\u7701\u7565\u65F6\u8BFB APM_REPOS_MANIFEST\uFF0C\u518D\u9ED8\u8BA4 /home/repository.json"
-  ).action(
-    async (taskId, projectId, opts) => {
-      await runEnsureTaskBranchCli({
-        taskId,
-        projectId,
-        cwd: opts.cwd,
-        reposManifest: opts.repos
-      });
-    }
-  );
-  program.command("commit-task-repos").description(
-    "\u6267\u884C\u7ED3\u675F\u6536\u5C3E\uFF1A\u591A\u4ED3\u6E05\u5355\u5404\u4ED3\u6709\u53D8\u66F4\u624D commit\uFF0C\u518D push\uFF08\u65E0\u53D8\u66F4\u4E0D\u7A7A\u63D0\u4EA4\uFF09"
-  ).option("--cwd <dir>", "\u5DE5\u4F5C\u533A\u6839\u76EE\u5F55\uFF08\u9ED8\u8BA4\u5F53\u524D\u76EE\u5F55\uFF09").option(
-    "--repos <file>",
-    "\u591A\u4ED3\u6E05\u5355 JSON\uFF1B\u7701\u7565\u65F6\u8BFB APM_REPOS_MANIFEST\uFF0C\u518D\u9ED8\u8BA4 /home/repository.json"
-  ).option(
-    "-m, --message <msg>",
-    "commit message\uFF1B\u7701\u7565\u5219\u4F18\u5148\u7528\u6237\u95EE\u9898\u7F13\u5B58\uFF0C\u5426\u5219\u6309 APM_TASK_ID / APM_PROJECT_ID \u751F\u6210"
-  ).action(async (opts) => {
-    await runCommitTaskReposCli({
-      cwd: opts.cwd,
-      reposManifest: opts.repos,
-      message: opts.message
-    });
+  program.command("sync-project-documents").description(
+    "\u540C\u6B65\u9879\u76EE\u6587\u6863\uFF1A\u9ED8\u8BA4 pull \u5230 .apm/project/<\u9879\u76EEID>/\uFF1B\u52A0 --push \u5C06\u672C\u5730\u53D8\u66F4\u63A8\u9001\u5230\u5E73\u53F0"
+  ).option("--push", "\u63A8\u9001\u672C\u5730 .apm/project/<\u9879\u76EEID>/ \u5230\u5E73\u53F0").option("--pull", "\u4ECE\u5E73\u53F0\u62C9\u53D6\u5230 .apm/project/<\u9879\u76EEID>/").action(async (opts) => {
+    await runSyncProjectDocuments(opts);
   });
   program.command("connect").description(
-    "\u8FDE\u63A5\u5E73\u53F0 WebSocket\uFF08/ws/agent\uFF09\uFF0C\u63A5\u624B WebIDE \u5DE5\u4F5C\u6D41\u6D88\u606F\uFF1B\u4E0D\u81EA\u52A8\u5347\u7EA7 CLI"
-  ).option(
-    "--server <url>",
-    "API \u6839\u5730\u5740\uFF1B\u82E5\u53EA\u4F20\u6B64\u9879\u4E14\u5E26\u7AEF\u53E3\uFF0C\u5219\u7AEF\u53E3\u89C6\u4E3A Socket \u7AEF\u53E3\uFF08\u8986\u76D6 config / APM_SERVER\uFF09"
-  ).option(
-    "--socket-server <url>",
-    "Agent WebSocket \u6839\u5730\u5740\uFF08\u8986\u76D6 config / APM_SOCKET_SERVER\uFF09"
-  ).action(async (opts) => {
-    await runConnect({
-      server: opts.server,
-      socketServer: opts.socketServer
-    });
+    "\u8FDE\u63A5\u524D\u68C0\u6D4B\u5E76\u66F4\u65B0\u5230\u5F53\u524D\u5927\u7248\u672C\u6700\u65B0 CLI\uFF0C\u518D\u8FDE\u63A5\u5E73\u53F0 WebSocket\uFF08/ws/agent\uFF09"
+  ).option("--server <url>", "API \u6839\u5730\u5740\uFF0C\u8986\u76D6 config \u4E2D\u7684 baseUrl").action(async (opts) => {
+    await runConnect({ server: opts.server });
   });
   return program;
 }