ai-project-manage-cli 4.0.21 → 4.0.23

package/dist/index.js

@@ -154,7 +154,33 @@ var requestConfig = {
       path: "/requirement-artifacts/delete"
     })
   },
+  theaterSessionArtifact: {
+    upsert: defineEndpoint({
+      method: "POST",
+      path: "/theater-session-artifacts/upsert"
+    }),
+    create: defineEndpoint({
+      method: "POST",
+      path: "/theater-session-artifacts/create"
+    }),
+    update: defineEndpoint({
+      method: "POST",
+      path: "/theater-session-artifacts/update"
+    }),
+    list: defineEndpoint({
+      method: "GET",
+      path: "/theater-session-artifacts/list"
+    }),
+    get: defineEndpoint({
+      method: "GET",
+      path: "/theater-session-artifacts/get"
+    })
+  },
   theater: {
+    sessionBranchBaseline: defineEndpoint({
+      method: "GET",
+      path: "/theater/sessions/branch-baseline"
+    }),
     reportMemberAgentProgress: defineEndpoint({
       method: "POST",
       path: "/theater/sessions/report-member-agent-progress"
@@ -203,6 +229,20 @@ var WORKSPACE_APM_DIR = resolve(process.cwd(), ".apm");
 function requirementWorkitemsDir(requirementId, workspaceDir = WORKSPACE_APM_DIR) {
   return join2(workspaceDir, "workitems", requirementId);
 }
+function theaterSessionDir(sessionId, apmRoot = WORKSPACE_APM_DIR) {
+  return join2(apmRoot, "theater-sessions", sessionId);
+}
+function normalizeTheaterArtifactFileName(fileName) {
+  return fileName.trim().replace(/\\/g, "/").replace(/^\/+/, "").replace(/^docs\//, "");
+}
+function theaterArtifactLocalRelativePath(fileName) {
+  const base = normalizeTheaterArtifactFileName(fileName);
+  return `docs/${base}`;
+}
+function theaterSessionDocumentPath(sessionId, fileName = "prd.md", apmRoot = WORKSPACE_APM_DIR) {
+  const localRelative = theaterArtifactLocalRelativePath(fileName);
+  return join2(theaterSessionDir(sessionId, apmRoot), localRelative);
+}
 async function ensureLoggedConfig() {
   const cfg = await ensureApmConfig();
   if (!cfg.token) {
@@ -377,7 +417,7 @@ async function runComment(requirementId, file, options) {
 import { randomUUID as randomUUID2 } from "crypto";
 import WebSocket from "ws";
 import { Agent } from "@cursor/sdk";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 
 // src/session-utils.ts
 import { appendFileSync } from "fs";
@@ -780,6 +820,243 @@ async function runPull(requirementId, workspaceDir) {
   return WORKITEMS_DIR;
 }
 
+// src/commands/pull-theater-session.ts
+import { writeFileSync as writeFileSync4 } from "fs";
+import { dirname as dirname2, join as join6 } from "path";
+function normalizeRelativePath(fileName) {
+  return theaterArtifactLocalRelativePath(fileName);
+}
+async function runPullTheaterSession(sessionId, apmRoot = WORKSPACE_APM_DIR) {
+  const trimmedSessionId = sessionId.trim();
+  if (!trimmedSessionId) {
+    throw new Error("sessionId \u4E0D\u80FD\u4E3A\u7A7A");
+  }
+  const cfg = await ensureLoggedConfig();
+  const api = createApmApiClient(cfg);
+  const sessionDir = theaterSessionDir(trimmedSessionId, apmRoot);
+  await ensureDirExists(sessionDir);
+  await ensureDirExists(join6(sessionDir, "docs"));
+  const pageSize = 500;
+  let page = 1;
+  const items = [];
+  while (true) {
+    const batch = await api.theaterSessionArtifact.list({
+      sessionId: trimmedSessionId,
+      page,
+      pageSize
+    });
+    items.push(...batch.items);
+    if (batch.total === 0 || items.length >= batch.total) break;
+    page += 1;
+  }
+  for (const item of items) {
+    const art = await api.theaterSessionArtifact.get({
+      sessionId: trimmedSessionId,
+      artifactId: item.id
+    });
+    const relativePath = normalizeRelativePath(art.fileName);
+    const destPath = join6(sessionDir, relativePath);
+    await ensureDirExists(dirname2(destPath));
+    writeFileSync4(destPath, art.content, "utf8");
+    console.log(`[apm] \u5DF2\u8986\u76D6\u4F1A\u8BDD\u6587\u6863: ${relativePath}`);
+  }
+  return sessionDir;
+}
+
+// src/commands/branch.ts
+import { execFile } from "child_process";
+import { resolve as resolve3 } from "path";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+async function fetchBaselineBranchFromApi(requirementId, cwd) {
+  const cfg = await ensureLoggedConfig();
+  const api = createApmApiClient(cfg);
+  const workdirPath = resolve3(cwd);
+  const res = await api.cliRequirements.branchBaseline({
+    requirementId,
+    workdirPath
+  });
+  if (!res.repositoryId) {
+    throw new Error(
+      `[apm] \u672A\u5728\u5E73\u53F0\u627E\u5230\u4E0E\u5F53\u524D\u76EE\u5F55\u5339\u914D\u7684\u5DE5\u4F5C\u76EE\u5F55\u767B\u8BB0\uFF1A${workdirPath}
+\u8BF7\u5148\u5728\u5E73\u53F0\u767B\u8BB0\u8BE5\u8DEF\u5F84\u5BF9\u5E94\u7684\u5DE5\u4F5C\u76EE\u5F55\u4E0E\u4ED3\u5E93\u3002`
+    );
+  }
+  const name = (res.defaultBranch ?? "").trim();
+  if (!name) {
+    throw new Error("[apm] \u5E73\u53F0\u8FD4\u56DE\u7684\u57FA\u7EBF\u5206\u652F\u540D\u4E3A\u7A7A");
+  }
+  return name;
+}
+async function fetchTheaterBaselineBranchFromApi(sessionId, cwd) {
+  const cfg = await ensureLoggedConfig();
+  const api = createApmApiClient(cfg);
+  const workdirPath = resolve3(cwd);
+  const res = await api.theater.sessionBranchBaseline({
+    sessionId,
+    workdirPath
+  });
+  if (!res.repositoryId) {
+    throw new Error(
+      `[apm] \u672A\u5728\u5E73\u53F0\u627E\u5230\u4E0E\u5F53\u524D\u76EE\u5F55\u5339\u914D\u7684\u5DE5\u4F5C\u76EE\u5F55\u767B\u8BB0\uFF1A${workdirPath}
+\u8BF7\u5148\u5728\u5E73\u53F0\u767B\u8BB0\u8BE5\u8DEF\u5F84\u5BF9\u5E94\u7684\u5DE5\u4F5C\u76EE\u5F55\u4E0E\u4ED3\u5E93\u3002`
+    );
+  }
+  const name = (res.defaultBranch ?? "").trim();
+  if (!name) {
+    throw new Error("[apm] \u5E73\u53F0\u8FD4\u56DE\u7684\u57FA\u7EBF\u5206\u652F\u540D\u4E3A\u7A7A");
+  }
+  return name;
+}
+function branchNameForRequirement(requirementId) {
+  const id = requirementId.trim();
+  if (!id) {
+    throw new Error("[apm] \u9700\u6C42 ID \u4E0D\u80FD\u4E3A\u7A7A");
+  }
+  if (/[\s/\\]/.test(id)) {
+    throw new Error(
+      "[apm] \u9700\u6C42 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 `feat/req-${id}`;
+}
+var branchNameForTheaterSession = branchNameForRequirement;
+async function execGit(cwd, args, quiet) {
+  try {
+    const { stdout, stderr } = await execFileAsync("git", args, {
+      cwd,
+      encoding: "utf8",
+      maxBuffer: 10 * 1024 * 1024
+    });
+    if (!quiet && stderr.trim()) {
+      process.stderr.write(stderr);
+    }
+    return stdout;
+  } catch (err) {
+    const e = err;
+    const detail = (e.stderr ?? e.message ?? String(err)).trim();
+    throw new Error(
+      `[apm] git ${args.join(" ")} \u5931\u8D25${detail ? `: ${detail}` : ""}`
+    );
+  }
+}
+async function ensureGitRepo(cwd) {
+  await execGit(cwd, ["rev-parse", "--git-dir"], true);
+}
+async function getCurrentBranch(cwd) {
+  const name = (await execGit(cwd, ["rev-parse", "--abbrev-ref", "HEAD"], true)).trim();
+  return name;
+}
+async function isWorkingTreeDirty(cwd) {
+  const out = await execGit(cwd, ["status", "--porcelain"], true);
+  return out.trim().length > 0;
+}
+async function remoteHeadBranchExists(cwd, branch) {
+  const out = await execGit(
+    cwd,
+    ["ls-remote", "--heads", "origin", branch],
+    true
+  );
+  return out.trim().length > 0;
+}
+async function localBranchExists(cwd, branch) {
+  try {
+    await execGit(
+      cwd,
+      ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`],
+      true
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+function theaterSessionCommitMessage(sessionId, memberKey) {
+  const id = sessionId.trim();
+  const key = memberKey?.trim();
+  return key ? `feat(req-${id}): ${key} theater agent` : `feat(req-${id}): theater agent`;
+}
+async function commitWorkingTreeIfDirty(cwd, message) {
+  await ensureGitRepo(cwd);
+  if (!await isWorkingTreeDirty(cwd)) {
+    return false;
+  }
+  const commitMessage = message?.trim() || `chore(apm): \u540C\u6B65\u5DE5\u4F5C\u533A (${await getCurrentBranch(cwd)})`;
+  await execGit(cwd, ["add", "-A"]);
+  await execGit(cwd, ["commit", "-m", commitMessage]);
+  console.log(`[apm] \u5DF2\u63D0\u4EA4\u5DE5\u4F5C\u533A\u53D8\u66F4: ${commitMessage}`);
+  return true;
+}
+async function ensureFeatureBranch(branch, options, fetchBaseline) {
+  const cwd = options.cwd ?? process.cwd();
+  const commitMessage = options.message?.trim() || `chore(apm): \u540C\u6B65\u5DE5\u4F5C\u533A (${branch})`;
+  await ensureGitRepo(cwd);
+  const current = await getCurrentBranch(cwd);
+  const dirty = await isWorkingTreeDirty(cwd);
+  if (dirty) {
+    if (current === branch) {
+      await commitWorkingTreeIfDirty(cwd, commitMessage);
+    } else {
+      await execGit(cwd, [
+        "stash",
+        "push",
+        "-u",
+        "-m",
+        `apm: switch to ${branch}`
+      ]);
+    }
+  }
+  const remoteExists = await remoteHeadBranchExists(cwd, branch);
+  if (remoteExists) {
+    await execGit(cwd, ["fetch", "origin", branch]);
+    const hasLocal = await localBranchExists(cwd, branch);
+    if (hasLocal) {
+      await execGit(cwd, ["checkout", branch]);
+      await execGit(cwd, ["pull", "--no-edit"]);
+    } else {
+      await execGit(cwd, ["checkout", "-b", branch, `origin/${branch}`]);
+    }
+  } else {
+    const onBranch = await getCurrentBranch(cwd) === branch;
+    if (!onBranch) {
+      const hasLocal = await localBranchExists(cwd, branch);
+      if (hasLocal) {
+        await execGit(cwd, ["checkout", branch]);
+      } else {
+        const baselineBranch = await fetchBaseline();
+        await execGit(cwd, ["fetch", "origin", baselineBranch]);
+        await execGit(cwd, [
+          "checkout",
+          "-b",
+          branch,
+          `origin/${baselineBranch}`
+        ]);
+      }
+    }
+    await execGit(cwd, ["push", "-u", "origin", branch]);
+  }
+  console.log(`[apm] \u5DF2\u5C31\u7EEA\u5206\u652F ${branch}`);
+  return branch;
+}
+async function runBranch(requirementId, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const branch = branchNameForRequirement(requirementId);
+  return ensureFeatureBranch(
+    branch,
+    options,
+    () => fetchBaselineBranchFromApi(requirementId, cwd)
+  );
+}
+async function runTheaterSessionBranch(sessionId, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const branch = branchNameForTheaterSession(sessionId);
+  return ensureFeatureBranch(
+    branch,
+    options,
+    () => fetchTheaterBaselineBranchFromApi(sessionId, cwd)
+  );
+}
+
 // src/theater-job-report.ts
 import { randomUUID } from "crypto";
 function extractErrorMessage(err) {
@@ -987,6 +1264,7 @@ async function handleTheaterJob(api, ws, payload) {
     throw new Error("THEATER_JOB \u7F3A\u5C11 memberKey");
   }
   console.log("[apm] \u5267\u573A\u4F1A\u8BDD:", sessionId, "\u6210\u5458:", memberKey);
+  const apmRoot = join7(payload.cwd, ".apm");
   let agentId = payload.agentId?.trim() || void 0;
   try {
     await reportTheaterProgress(api, ws, { sessionId, memberKey, logId });
@@ -1002,11 +1280,56 @@ async function handleTheaterJob(api, ws, payload) {
     });
     return;
   }
+  try {
+    await runTheaterSessionBranch(sessionId, { cwd: payload.cwd });
+  } catch (branchErr) {
+    logTheaterJobError("\u5207\u6362\u5206\u652F", branchErr, { sessionId, memberKey });
+    await submitTheaterFailure(api, ws, {
+      sessionId,
+      memberKey,
+      logId,
+      agentId,
+      stage: "\u5207\u6362\u5206\u652F",
+      error: extractErrorMessage(branchErr)
+    });
+    return;
+  }
+  try {
+    await runPullTheaterSession(sessionId, apmRoot);
+  } catch (pullErr) {
+    logTheaterJobError("\u62C9\u53D6\u4F1A\u8BDD\u6587\u6863", pullErr, { sessionId, memberKey });
+    await submitTheaterFailure(api, ws, {
+      sessionId,
+      memberKey,
+      logId,
+      agentId,
+      stage: "\u62C9\u53D6\u4F1A\u8BDD\u6587\u6863",
+      error: extractErrorMessage(pullErr)
+    });
+    return;
+  }
   try {
     const eventSession = new EventSession(payload.prompt);
     const agent = await createAgentForJob(payload);
     const runResult = await runAgentStream(payload, eventSession, agent);
     agentId = runResult.agentId;
+    try {
+      await commitWorkingTreeIfDirty(
+        payload.cwd,
+        theaterSessionCommitMessage(sessionId, memberKey)
+      );
+    } catch (commitErr) {
+      logTheaterJobError("\u63D0\u4EA4\u5DE5\u4F5C\u533A", commitErr, { sessionId, memberKey });
+      await submitTheaterFailure(api, ws, {
+        sessionId,
+        memberKey,
+        logId,
+        agentId,
+        stage: "\u63D0\u4EA4\u5DE5\u4F5C\u533A",
+        error: extractErrorMessage(commitErr)
+      });
+      return;
+    }
     const assistantText = eventSession.getAssistantText();
     const content = runResult.failed ? runResult.failReason || assistantText || "\u672A\u77E5\u9519\u8BEF" : assistantText || "[Agent \u672A\u4EA7\u751F\u6587\u672C\u8F93\u51FA]";
     await submitTheaterResult(api, ws, {
@@ -1037,7 +1360,7 @@ async function handleTheaterJob(api, ws, payload) {
   }
 }
 async function handleWorkflowJob(api, payload) {
-  const apmRoot = join6(payload.cwd, ".apm");
+  const apmRoot = join7(payload.cwd, ".apm");
   console.log("[apm] ROOT:", apmRoot);
   console.log("[apm] workflow node:", payload.nodeId);
   try {
@@ -1163,17 +1486,17 @@ function runConnect(opts) {
 }
 
 // src/commands/init.ts
-import { join as join7 } from "path";
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "fs";
+import { join as join8 } from "path";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync5 } from "fs";
 async function runInit(name) {
   await ensureWorkspaceApmDirForInit();
   await copyTemplateFiles(WORKSPACE_APM_DIR);
   if (name) {
-    const apmConfigPath = join7(WORKSPACE_APM_DIR, "apm.config.json");
+    const apmConfigPath = join8(WORKSPACE_APM_DIR, "apm.config.json");
     const config = readFileSync4(apmConfigPath, "utf8");
     const configJson = JSON.parse(config);
     configJson.name = name;
-    writeFileSync4(apmConfigPath, JSON.stringify(configJson, null, 2), "utf8");
+    writeFileSync5(apmConfigPath, JSON.stringify(configJson, null, 2), "utf8");
   }
 }
 
@@ -1222,156 +1545,12 @@ async function runLogin(opts) {
   console.log(JSON.stringify({ userId: cfg.userId, baseUrl: cfg.baseUrl }, null, 2));
 }
 
-// src/commands/branch.ts
-import { execFile } from "child_process";
-import { resolve as resolve3 } from "path";
-import { promisify } from "util";
-var execFileAsync = promisify(execFile);
-async function fetchBaselineBranchFromApi(requirementId, cwd) {
-  const cfg = await ensureLoggedConfig();
-  const api = createApmApiClient(cfg);
-  const workdirPath = resolve3(cwd);
-  const res = await api.cliRequirements.branchBaseline({
-    requirementId,
-    workdirPath
-  });
-  if (!res.repositoryId) {
-    throw new Error(
-      `[apm] \u672A\u5728\u5E73\u53F0\u627E\u5230\u4E0E\u5F53\u524D\u76EE\u5F55\u5339\u914D\u7684\u5DE5\u4F5C\u76EE\u5F55\u767B\u8BB0\uFF1A${workdirPath}
-\u8BF7\u5148\u5728\u5E73\u53F0\u767B\u8BB0\u8BE5\u8DEF\u5F84\u5BF9\u5E94\u7684\u5DE5\u4F5C\u76EE\u5F55\u4E0E\u4ED3\u5E93\u3002`
-    );
-  }
-  const name = (res.defaultBranch ?? "").trim();
-  if (!name) {
-    throw new Error("[apm] \u5E73\u53F0\u8FD4\u56DE\u7684\u57FA\u7EBF\u5206\u652F\u540D\u4E3A\u7A7A");
-  }
-  return name;
-}
-function branchNameForRequirement(requirementId) {
-  const id = requirementId.trim();
-  if (!id) {
-    throw new Error("[apm] \u9700\u6C42 ID \u4E0D\u80FD\u4E3A\u7A7A");
-  }
-  if (/[\s/\\]/.test(id)) {
-    throw new Error(
-      "[apm] \u9700\u6C42 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 `feat/req-${id}`;
-}
-async function execGit(cwd, args, quiet) {
-  try {
-    const { stdout, stderr } = await execFileAsync("git", args, {
-      cwd,
-      encoding: "utf8",
-      maxBuffer: 10 * 1024 * 1024
-    });
-    if (!quiet && stderr.trim()) {
-      process.stderr.write(stderr);
-    }
-    return stdout;
-  } catch (err) {
-    const e = err;
-    const detail = (e.stderr ?? e.message ?? String(err)).trim();
-    throw new Error(
-      `[apm] git ${args.join(" ")} \u5931\u8D25${detail ? `: ${detail}` : ""}`
-    );
-  }
-}
-async function ensureGitRepo(cwd) {
-  await execGit(cwd, ["rev-parse", "--git-dir"], true);
-}
-async function getCurrentBranch(cwd) {
-  const name = (await execGit(cwd, ["rev-parse", "--abbrev-ref", "HEAD"], true)).trim();
-  return name;
-}
-async function isWorkingTreeDirty(cwd) {
-  const out = await execGit(cwd, ["status", "--porcelain"], true);
-  return out.trim().length > 0;
-}
-async function remoteHeadBranchExists(cwd, branch) {
-  const out = await execGit(
-    cwd,
-    ["ls-remote", "--heads", "origin", branch],
-    true
-  );
-  return out.trim().length > 0;
-}
-async function localBranchExists(cwd, branch) {
-  try {
-    await execGit(
-      cwd,
-      ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`],
-      true
-    );
-    return true;
-  } catch {
-    return false;
-  }
-}
-async function runBranch(requirementId, options = {}) {
-  const cwd = options.cwd ?? process.cwd();
-  const branch = branchNameForRequirement(requirementId);
-  const commitMessage = options.message?.trim() || `chore(apm): \u540C\u6B65\u5DE5\u4F5C\u533A (${branch})`;
-  await ensureGitRepo(cwd);
-  const current = await getCurrentBranch(cwd);
-  const dirty = await isWorkingTreeDirty(cwd);
-  if (dirty) {
-    if (current === branch) {
-      await execGit(cwd, ["add", "-A"]);
-      await execGit(cwd, ["commit", "-m", commitMessage]);
-    } else {
-      await execGit(cwd, [
-        "stash",
-        "push",
-        "-u",
-        "-m",
-        `apm: switch to ${branch}`
-      ]);
-    }
-  }
-  const remoteExists = await remoteHeadBranchExists(cwd, branch);
-  if (remoteExists) {
-    await execGit(cwd, ["fetch", "origin", branch]);
-    const hasLocal = await localBranchExists(cwd, branch);
-    if (hasLocal) {
-      await execGit(cwd, ["checkout", branch]);
-      await execGit(cwd, ["pull", "--no-edit"]);
-    } else {
-      await execGit(cwd, ["checkout", "-b", branch, `origin/${branch}`]);
-    }
-  } else {
-    const onBranch = await getCurrentBranch(cwd) === branch;
-    if (!onBranch) {
-      const hasLocal = await localBranchExists(cwd, branch);
-      if (hasLocal) {
-        await execGit(cwd, ["checkout", branch]);
-      } else {
-        const baselineBranch = await fetchBaselineBranchFromApi(
-          requirementId,
-          cwd
-        );
-        await execGit(cwd, ["fetch", "origin", baselineBranch]);
-        await execGit(cwd, [
-          "checkout",
-          "-b",
-          branch,
-          `origin/${baselineBranch}`
-        ]);
-      }
-    }
-    await execGit(cwd, ["push", "-u", "origin", branch]);
-  }
-  console.log(`[apm] \u5DF2\u5C31\u7EEA\u5206\u652F ${branch}`);
-  return branch;
-}
-
 // src/commands/refine.ts
 import { readFileSync as readFileSync5 } from "fs";
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 async function runRefine(requirementId) {
   const cfg = await ensureLoggedConfig();
-  const filePath = join8(WORKSPACE_APM_DIR, "workitems", requirementId, "prd.md");
+  const filePath = join9(WORKSPACE_APM_DIR, "workitems", requirementId, "prd.md");
   const content = readFileSync5(filePath, "utf8");
   const api = createApmApiClient(cfg);
   const data = await api.cliRequirements.refine({ requirementId, content });
@@ -1383,13 +1562,13 @@ import { spawnSync } from "child_process";
 
 // src/version.ts
 import { readFileSync as readFileSync6 } from "fs";
-import { dirname as dirname2, join as join9 } from "path";
+import { dirname as dirname3, join as join10 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 var CLI_PACKAGE_NAME = "ai-project-manage-cli";
 function readCliVersion() {
   try {
-    const dir = dirname2(fileURLToPath2(import.meta.url));
-    const pkgPath = join9(dir, "..", "package.json");
+    const dir = dirname3(fileURLToPath2(import.meta.url));
+    const pkgPath = join10(dir, "..", "package.json");
     const pkg = JSON.parse(readFileSync6(pkgPath, "utf8"));
     return pkg.version ?? "0.0.0";
   } catch {
@@ -1458,8 +1637,8 @@ async function runUpdate() {
 
 // src/commands/update-skills.ts
 import { cpSync as cpSync2, existsSync as existsSync4, rmSync, statSync as statSync3 } from "fs";
-import { join as join10 } from "path";
-var TEMPLATE_SKILLS_DIR = join10(CLI_TEMPLATE_DIR, "skills");
+import { join as join11 } from "path";
+var TEMPLATE_SKILLS_DIR = join11(CLI_TEMPLATE_DIR, "skills");
 async function runUpdateSkills() {
   const apmDir = WORKSPACE_APM_DIR;
   if (!existsSync4(apmDir)) {
@@ -1479,7 +1658,7 @@ async function runUpdateSkills() {
   if (!templateStat.isDirectory()) {
     throw new Error(`[apm] \u5185\u7F6E\u6280\u80FD\u6A21\u677F\u4E0D\u662F\u76EE\u5F55: ${TEMPLATE_SKILLS_DIR}`);
   }
-  const skillsDir = join10(apmDir, "skills");
+  const skillsDir = join11(apmDir, "skills");
   if (existsSync4(skillsDir)) {
     rmSync(skillsDir, { recursive: true, force: true });
   }
@@ -1488,6 +1667,77 @@ async function runUpdateSkills() {
   console.log("[apm] \u5DF2\u66F4\u65B0 .apm/skills");
 }
 
+// src/commands/update-theater-skills.ts
+import { cpSync as cpSync3, existsSync as existsSync5, rmSync as rmSync2, statSync as statSync4 } from "fs";
+import { join as join12 } from "path";
+var TEMPLATE_THEATER_SKILLS_DIR = join12(CLI_TEMPLATE_DIR, "theater-skills");
+async function runUpdateTheaterSkills() {
+  const apmDir = WORKSPACE_APM_DIR;
+  if (!existsSync5(apmDir)) {
+    console.error("[apm] \u672A\u627E\u5230 .apm \u76EE\u5F55\uFF0C\u8BF7\u5148\u6267\u884C apm init");
+    process.exit(1);
+  }
+  const apmStat = statSync4(apmDir);
+  if (!apmStat.isDirectory()) {
+    throw new Error(`[apm] \u8DEF\u5F84\u5DF2\u5B58\u5728\u4F46\u4E0D\u662F\u76EE\u5F55: ${apmDir}`);
+  }
+  let templateStat;
+  try {
+    templateStat = statSync4(TEMPLATE_THEATER_SKILLS_DIR);
+  } catch {
+    throw new Error(
+      `[apm] \u5185\u7F6E\u5267\u573A\u6280\u80FD\u6A21\u677F\u4E0D\u5B58\u5728: ${TEMPLATE_THEATER_SKILLS_DIR}`
+    );
+  }
+  if (!templateStat.isDirectory()) {
+    throw new Error(
+      `[apm] \u5185\u7F6E\u5267\u573A\u6280\u80FD\u6A21\u677F\u4E0D\u662F\u76EE\u5F55: ${TEMPLATE_THEATER_SKILLS_DIR}`
+    );
+  }
+  const theaterSkillsDir = join12(apmDir, "theater-skills");
+  if (existsSync5(theaterSkillsDir)) {
+    rmSync2(theaterSkillsDir, { recursive: true, force: true });
+  }
+  await ensureDirExists(apmDir);
+  cpSync3(TEMPLATE_THEATER_SKILLS_DIR, theaterSkillsDir, { recursive: true });
+  console.log("[apm] \u5DF2\u66F4\u65B0 .apm/theater-skills");
+}
+
+// src/commands/sync-session-document.ts
+import { existsSync as existsSync6, readFileSync as readFileSync7 } from "fs";
+var DEFAULT_FILE = "prd.md";
+async function runSyncSessionDocument(sessionId, options) {
+  const trimmedSessionId = sessionId.trim();
+  if (!trimmedSessionId) {
+    console.error("[apm] sessionId \u4E0D\u80FD\u4E3A\u7A7A");
+    process.exit(1);
+  }
+  const fileArg = (options?.file?.trim() || DEFAULT_FILE).replace(/\\/g, "/");
+  const apmRoot = options?.apmRoot ?? WORKSPACE_APM_DIR;
+  const localRelativePath = theaterArtifactLocalRelativePath(fileArg);
+  const absPath = theaterSessionDocumentPath(
+    trimmedSessionId,
+    fileArg,
+    apmRoot
+  );
+  if (!existsSync6(absPath)) {
+    console.error(`[apm] \u6587\u6863\u4E0D\u5B58\u5728: ${absPath}
+\u8BF7\u5148\u521B\u5EFA\u8BE5\u6587\u4EF6\u540E\u518D\u540C\u6B65`);
+    process.exit(1);
+  }
+  const content = readFileSync7(absPath, "utf8");
+  const cfg = await ensureLoggedConfig();
+  const api = createApmApiClient(cfg);
+  const data = await api.theaterSessionArtifact.upsert({
+    sessionId: trimmedSessionId,
+    fileName: normalizeTheaterArtifactFileName(fileArg),
+    content
+  });
+  console.log(
+    `[apm] \u5DF2\u540C\u6B65\u4F1A\u8BDD\u6587\u6863: ${localRelativePath} \u2192 ${data.fileName} (artifactId=${data.id})`
+  );
+}
+
 // src/commands/update-dev-status.ts
 async function runUpdateDevStatus(requirementId, status) {
   const cfg = await ensureLoggedConfig();
@@ -1514,19 +1764,19 @@ async function runUpdateStatus(requirementId, status) {
 import path5 from "node:path";
 
 // src/commands/deploy/internal/apm-config.ts
-import { existsSync as existsSync5, readFileSync as readFileSync7 } from "node:fs";
+import { existsSync as existsSync7, readFileSync as readFileSync8 } from "node:fs";
 import { resolve as resolve4 } from "node:path";
 function loadApmConfig(options) {
   const p = resolve4(
     process.cwd(),
     options?.configPath ?? resolve4(WORKSPACE_APM_DIR, "apm.config.json")
   );
-  if (!existsSync5(p)) {
+  if (!existsSync7(p)) {
     console.error(`\u672A\u627E\u5230\u914D\u7F6E\u6587\u4EF6\uFF1A${p}`);
     process.exit(1);
   }
   try {
-    const raw = readFileSync7(p, "utf8");
+    const raw = readFileSync8(p, "utf8");
     return JSON.parse(raw);
   } catch (e) {
     console.error(`\u65E0\u6CD5\u89E3\u6790 apm.config.json\uFF1A${p}`, e);
@@ -1625,7 +1875,7 @@ import path4 from "node:path";
 import Docker from "dockerode";
 
 // src/commands/deploy/internal/backend-deploy/dockerode-client/connection-options.ts
-import { existsSync as existsSync6, readFileSync as readFileSync8 } from "node:fs";
+import { existsSync as existsSync8, readFileSync as readFileSync9 } from "node:fs";
 import path from "node:path";
 function asOptionalTlsBuffer(value) {
   if (typeof value !== "string") {
@@ -1637,8 +1887,8 @@ function asOptionalTlsBuffer(value) {
   if (normalized === "") {
     return void 0;
   }
-  if (existsSync6(normalized)) {
-    return readFileSync8(normalized);
+  if (existsSync8(normalized)) {
+    return readFileSync9(normalized);
   }
   const looksLikePath = /[\\/]/.test(normalized) || normalized.endsWith(".pem");
   if (looksLikePath) {
@@ -1848,7 +2098,7 @@ var DockerodeClient = class {
 var createDockerodeClient = (config) => new DockerodeClient(config);
 
 // src/commands/deploy/internal/backend-deploy/dockerode-client/env.ts
-import { existsSync as existsSync7, readFileSync as readFileSync9, statSync as statSync4 } from "node:fs";
+import { existsSync as existsSync9, readFileSync as readFileSync10, statSync as statSync5 } from "node:fs";
 import path2 from "node:path";
 function stripSurroundingQuotes(value) {
   const t = value.trim();
@@ -1865,10 +2115,10 @@ function loadEnvFromFile(envFilePath) {
     return {};
   }
   const targetPath = path2.resolve(envFilePath);
-  if (!existsSync7(targetPath) || !statSync4(targetPath).isFile()) {
+  if (!existsSync9(targetPath) || !statSync5(targetPath).isFile()) {
     return {};
   }
-  const raw = readFileSync9(targetPath, "utf-8");
+  const raw = readFileSync10(targetPath, "utf-8");
   const result = {};
   for (const line of raw.split(/\r?\n/)) {
     const normalized = line.trim();
@@ -2039,12 +2289,12 @@ function dockerPushImage(params, cwd) {
 }
 
 // src/commands/deploy/internal/backend-deploy/resolve-dockerfile.ts
-import { existsSync as existsSync8 } from "node:fs";
+import { existsSync as existsSync10 } from "node:fs";
 import path3 from "node:path";
 function resolveDockerBuildPaths(cwd) {
   const dockerfilePath = path3.join(cwd, "Dockerfile");
   Logger.info(`\u67E5\u627EDockerfile\u6587\u4EF6\uFF0C\u8DEF\u5F84: ${dockerfilePath}`);
-  if (!existsSync8(dockerfilePath)) {
+  if (!existsSync10(dockerfilePath)) {
     throw new Error(`Dockerfile \u4E0D\u5B58\u5728\uFF1A${dockerfilePath}`);
   }
   Logger.info("\u2713 Dockerfile \u5B58\u5728");
@@ -2173,16 +2423,16 @@ import { copyFile, readdir as readdir2, stat } from "node:fs/promises";
 import path7 from "node:path";
 
 // src/commands/deploy/internal/load-apm-dotenv.ts
-import { existsSync as existsSync9, readFileSync as readFileSync10 } from "node:fs";
-import { join as join11 } from "node:path";
+import { existsSync as existsSync11, readFileSync as readFileSync11 } from "node:fs";
+import { join as join13 } from "node:path";
 function loadApmDotEnvIfPresent() {
-  const p = join11(WORKSPACE_APM_DIR, ".env");
-  if (!existsSync9(p)) {
+  const p = join13(WORKSPACE_APM_DIR, ".env");
+  if (!existsSync11(p)) {
     return;
   }
   let text;
   try {
-    text = readFileSync10(p, "utf8");
+    text = readFileSync11(p, "utf8");
   } catch {
     return;
   }
@@ -2207,14 +2457,14 @@ function loadApmDotEnvIfPresent() {
 }
 
 // src/commands/deploy/internal/minio.ts
-import { statSync as statSync5 } from "node:fs";
+import { statSync as statSync6 } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
 import path6 from "node:path";
 import * as Minio from "minio";
 var DEFAULT_MAX_FILE_SIZE_MB = 50;
 async function isDirectoryPath(dir) {
   try {
-    const st = statSync5(dir);
+    const st = statSync6(dir);
     return st.isDirectory();
   } catch {
     return false;
@@ -2244,7 +2494,7 @@ async function collectFiles(root) {
       if (e.isDirectory()) {
         await walk(abs, rel);
       } else if (e.isFile()) {
-        const st = statSync5(abs);
+        const st = statSync6(abs);
         out.push({
           absPath: abs,
           relativePath: rel.replace(/\\/g, "/"),
@@ -2566,6 +2816,25 @@ function buildProgram() {
   ).action(async () => {
     await runUpdateSkills();
   });
+  program.command("update-theater-skills").description(
+    "\u5220\u9664\u5DE5\u4F5C\u533A .apm/theater-skills \u540E\uFF0C\u4ECE\u5F53\u524D CLI \u5185\u7F6E\u6A21\u677F\u91CD\u65B0\u590D\u5236\u5267\u573A\u6280\u80FD\u76EE\u5F55"
+  ).action(async () => {
+    await runUpdateTheaterSkills();
+  });
+  program.command("pull-session").description(
+    "\u5C06\u5E73\u53F0\u5267\u573A\u4F1A\u8BDD\u4EA7\u7269\u6587\u6863\u4E0B\u8F7D\u5230 .apm/theater-sessions/<sessionId>/\uFF08\u5982 docs/prd.md\uFF09\uFF1B\u672C\u5730\u5DF2\u6709\u540C\u540D\u6587\u4EF6\u65F6\u8986\u76D6"
+  ).argument("<sessionId>", "\u5267\u573A\u4F1A\u8BDD ID").action(async (sessionId) => {
+    const dir = await runPullTheaterSession(sessionId);
+    console.log(`[apm] \u4F1A\u8BDD\u6587\u6863\u76EE\u5F55: ${dir}`);
+  });
+  program.command("sync-session-document").description(
+    "\u5C06 .apm/theater-sessions/<sessionId>/docs/ \u4E0B Markdown \u6587\u6863 upsert \u5230\u5E73\u53F0\u4F1A\u8BDD\u4EA7\u7269\uFF08\u4E0D\u542B\u5BF9\u8BDD\u65E5\u5FD7\uFF09"
+  ).argument("<sessionId>", "\u5267\u573A\u4F1A\u8BDD ID").option(
+    "--file <path>",
+    "\u6587\u6863\u540D\u6216\u76F8\u5BF9\u8DEF\u5F84\uFF08\u5982 prd.md\u3001docs/backend.md\uFF1B\u672C\u5730\u56FA\u5B9A\u843D\u5728 docs/ \u4E0B\uFF09"
+  ).action(async (sessionId, opts) => {
+    await runSyncSessionDocument(sessionId, { file: opts.file });
+  });
   program.command("pull").description(
     "GET /api/cli/requirements/pull\uFF0C\u540C\u6B65\u6570\u636E\u4E0E\u9644\u4EF6\u5230 .apm/workitems/<\u9700\u6C42ID>"
   ).argument("<requirementId>", "\u9700\u6C42 ID").action(async (requirementId) => {