ai-project-manage-cli 4.0.22 → 4.0.23

package/dist/index.js

@@ -177,6 +177,10 @@ var requestConfig = {
     })
   },
   theater: {
+    sessionBranchBaseline: defineEndpoint({
+      method: "GET",
+      path: "/theater/sessions/branch-baseline"
+    }),
     reportMemberAgentProgress: defineEndpoint({
       method: "POST",
       path: "/theater/sessions/report-member-agent-progress"
@@ -228,9 +232,16 @@ function requirementWorkitemsDir(requirementId, workspaceDir = WORKSPACE_APM_DIR
 function theaterSessionDir(sessionId, apmRoot = WORKSPACE_APM_DIR) {
   return join2(apmRoot, "theater-sessions", sessionId);
 }
-function theaterSessionDocumentPath(sessionId, relativePath = "docs/prd.md", apmRoot = WORKSPACE_APM_DIR) {
-  const normalized = relativePath.replace(/\\/g, "/").replace(/^\/+/, "");
-  return join2(theaterSessionDir(sessionId, apmRoot), normalized);
+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();
@@ -813,7 +824,7 @@ async function runPull(requirementId, workspaceDir) {
 import { writeFileSync as writeFileSync4 } from "fs";
 import { dirname as dirname2, join as join6 } from "path";
 function normalizeRelativePath(fileName) {
-  return fileName.trim().replace(/\\/g, "/").replace(/^\/+/, "");
+  return theaterArtifactLocalRelativePath(fileName);
 }
 async function runPullTheaterSession(sessionId, apmRoot = WORKSPACE_APM_DIR) {
   const trimmedSessionId = sessionId.trim();
@@ -824,6 +835,7 @@ async function runPullTheaterSession(sessionId, apmRoot = WORKSPACE_APM_DIR) {
   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 = [];
@@ -851,6 +863,200 @@ async function runPullTheaterSession(sessionId, apmRoot = WORKSPACE_APM_DIR) {
   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) {
@@ -1074,6 +1280,20 @@ 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) {
@@ -1093,6 +1313,23 @@ async function handleTheaterJob(api, ws, payload) {
     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, {
@@ -1308,150 +1545,6 @@ 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 join9 } from "path";
@@ -1612,21 +1705,19 @@ async function runUpdateTheaterSkills() {
 
 // src/commands/sync-session-document.ts
 import { existsSync as existsSync6, readFileSync as readFileSync7 } from "fs";
-var DEFAULT_RELATIVE_PATH = "docs/prd.md";
+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 relativePath = (options?.file?.trim() || DEFAULT_RELATIVE_PATH).replace(
-    /\\/g,
-    "/"
-  );
+  const fileArg = (options?.file?.trim() || DEFAULT_FILE).replace(/\\/g, "/");
   const apmRoot = options?.apmRoot ?? WORKSPACE_APM_DIR;
+  const localRelativePath = theaterArtifactLocalRelativePath(fileArg);
   const absPath = theaterSessionDocumentPath(
     trimmedSessionId,
-    relativePath,
+    fileArg,
     apmRoot
   );
   if (!existsSync6(absPath)) {
@@ -1639,10 +1730,12 @@ async function runSyncSessionDocument(sessionId, options) {
   const api = createApmApiClient(cfg);
   const data = await api.theaterSessionArtifact.upsert({
     sessionId: trimmedSessionId,
-    fileName: relativePath,
+    fileName: normalizeTheaterArtifactFileName(fileArg),
     content
   });
-  console.log(`[apm] \u5DF2\u540C\u6B65\u4F1A\u8BDD\u6587\u6863: ${relativePath} (artifactId=${data.id})`);
+  console.log(
+    `[apm] \u5DF2\u540C\u6B65\u4F1A\u8BDD\u6587\u6863: ${localRelativePath} \u2192 ${data.fileName} (artifactId=${data.id})`
+  );
 }
 
 // src/commands/update-dev-status.ts
@@ -2738,7 +2831,7 @@ function buildProgram() {
     "\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>",
-    "\u76F8\u5BF9\u4F1A\u8BDD\u76EE\u5F55\u7684\u6587\u4EF6\u8DEF\u5F84\uFF08\u9ED8\u8BA4 docs/prd.md\uFF1B\u540E\u7AEF\u5E38\u7528 docs/backend.md\u3001docs/api.md\uFF09"
+    "\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 });
   });

package/package.json

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

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

@@ -1,13 +1,19 @@
 ---
 name: apm-theater-dev
-description: 按剧场会话 ID 全自动编码：切分支、读会话 PRD（及 backend/api 文档）、按改动规模选择 Quick 或 Spec、提交并推送、同步 docs 产物；子 Agent 承担编码与规划落地；当用户 @ 本技能、提及剧场全自动开发或「apm-theater-dev」时使用。
+description: 按剧场会话 ID 全自动编码：按需读会话 PRD（及 backend/api 文档）、按改动规模选择 Quick 或 Spec、推送代码；子 Agent 承担编码与规划落地；当用户 @ 本技能、提及剧场全自动开发或「apm-theater-dev」时使用。
 ---
 
 # 剧场全自动开发（按会话 ID）
 
 用户给出 **剧场会话 ID**（`sessionId`，与 `.apm/theater-sessions/<sessionId>/` 目录名一致）。**缺 ID 时索要，不猜测。**
 
-`THEATER_JOB` 开始时会自动 pull 平台文档到本地。Agent **对话日志不上传**；`docs/` 等业务文档在变更后须 `sync-session-document`。
+由 **`THEATER_JOB` / `apm connect`** 自动完成（**无需在本技能中切分支**）：
+
+- 检出或创建 **`feat/req-<sessionId>`** 并拉取最新
+- **pull** 平台会话文档到 `.apm/theater-sessions/<sessionId>/docs/`
+- Agent 结束后若有未提交变更，CLI 自动 **`git add` & `commit`**
+
+Agent **对话日志不上传**。**不要**执行 `apm sync-session-document`（会话文档由网页或其他角色维护）。
 
 ---
 
@@ -19,60 +25,47 @@ description: 按剧场会话 ID 全自动编码：切分支、读会话 PRD（
 | **会话上下文**  | 若由 `THEATER_JOB` 触发，`theaterSessionId` 即 `sessionId`；缺省时向用户索要，不猜测。 |
 
 **会话根目录**：`.apm/theater-sessions/<sessionId>/`  
-**PRD**：`.apm/theater-sessions/<sessionId>/docs/prd.md`  
-**可选参考**：`docs/backend.md`、`docs/api.md`
+**PRD（按需）**：`docs/prd.md`  
+**可选参考（按需）**：`docs/backend.md`、`docs/api.md`
 
 ---
 
 ## 技能文件定位（apm-propose / apm-apply-change）
 
-Spec 路径依赖的技能**仅**来自 **`.apm/skills/`**。执行前父 Agent **须 Read**：
+Spec 路径依赖的技能**仅**来自 **`.apm/skills/`**。进入 Spec 子流程前父 Agent **须 Read**：
 
 | 技能                 | 路径                                    |
 | -------------------- | --------------------------------------- |
 | **apm-propose**      | `.apm/skills/apm-propose/SKILL.md`      |
 | **apm-apply-change** | `.apm/skills/apm-apply-change/SKILL.md` |
 
-instruction 子文件随该目录类推（如 `.apm/skills/apm-propose/propose-instruction.md`）。若上述 `SKILL.md` **不存在或不可读**：**不得**进入 Spec 子流程；在表格中标记失败原因（例如需先 `apm init` 或 `apm update-skills`），并停止步骤 4。
+instruction 子文件随该目录类推（如 `.apm/skills/apm-propose/propose-instruction.md`）。若上述 `SKILL.md` **不存在或不可读**：**不得**进入 Spec 子流程；在表格中标记失败原因（例如需先 `apm init` 或 `apm update-skills`），并停止步骤 3。
 
-委派子 Agent 时须说明：本轮为**剧场会话**，**`sessionId`** 替代需求 ID；PRD 在 **`docs/prd.md`**；Spec 工件落在 **`.apm/theater-sessions/<sessionId>/`**（非 `workitems`）。
+委派子 Agent 时须说明：本轮为**剧场会话**，**`sessionId`** 替代需求 ID；PRD 在 **`docs/prd.md`**（按需阅读）；Spec 工件落在 **`.apm/theater-sessions/<sessionId>/`**（非 `workitems`）。
 
 ---
 
 ## 流程总览
 
-| 序号 | 步骤                  | 说明                                                                                     |
-| ---- | --------------------- | ---------------------------------------------------------------------------------------- |
-| 1    | **切分支**            | 检出或创建 `feat/theater-<sessionId>`（git，无 `apm branch` 剧场命令）                   |
-| 2    | **读 PRD + 成本评估** | **Read** `docs/prd.md`（及需要的 `backend.md` / `api.md`），判定 Quick / Spec            |
-| 3    | **Quick 开发**        | 仅当判定为「改动成本较小」时执行；由 **子 Agent** 写代码                                 |
-| 4    | **Spec 开发**         | 仅当判定为「改动成本较大」时执行；先 **apm-propose** 再 **apm-apply-change**（子 Agent） |
-| 5    | **提交与推送**        | `git` 提交并 `push`，工作区干净                                                          |
-| 6    | **同步会话文档**      | 对本轮有改动的 `.md` 逐一 `apm sync-session-document`（仅 `docs/` 等业务文档，不含日志） |
-| 7    | **对用户回复**        | **一张 Markdown 表格**汇总各步执行结果（见文末模板）                                     |
-
----
-
-## 步骤 1：切分支
-
-1. 在**仓库/工作区根目录**执行（分支名固定为 `feat/theater-<sessionId>`）：
-
-   ```bash
-   git fetch origin
-   git switch feat/theater-<sessionId> 2>/dev/null || git switch -c feat/theater-<sessionId>
-   ```
+| 序号 | 步骤                      | 说明                                                                                      |
+| ---- | ------------------------- | ----------------------------------------------------------------------------------------- |
+| 1    | **按需读文档 + 成本评估** | 按本轮任务**按需 Read** `docs/prd.md` 及需要的 `backend.md` / `api.md`，判定 Quick / Spec |
+| 2    | **Quick 开发**            | 仅当判定为「改动成本较小」时执行；由 **子 Agent** 写代码                                  |
+| 3    | **Spec 开发**             | 仅当判定为「改动成本较大」时执行；先 **apm-propose** 再 **apm-apply-change**（子 Agent）  |
+| 4    | **推送**                  | `git push`；确认工作区干净（提交通常已由 CLI 在 Agent 结束时完成）                        |
 
-   若远端已有该分支：`git switch feat/theater-<sessionId>` 后 `git pull --no-edit`（按需）。
-
-2. 记录：是否成功、当前分支名、简要输出或错误（写入最终表格）。**失败则按「Guardrails → 失败即终止」处理**。
+流程**仅以上 4 步**，**无**同步会话文档环节（不执行 `apm sync-session-document`）。
 
 ---
 
-## 步骤 2：读取 PRD 并评估改动成本
+## 步骤 1：按需读文档并评估改动成本
 
-1. **Read** 全文：`.apm/theater-sessions/<sessionId>/docs/prd.md`。
-2. 若实现涉及后端/接口，按需 **Read** `docs/backend.md`、`docs/api.md`。
-3. 若 `prd.md` 读失败则**停止后续实现**，仅在表格中标记失败原因。
+1. **不要**无差别全文 Read `prd.md`；根据主持委派任务、已有对话与实现范围，**按需**阅读：
+   - 需要理解需求范围或验收时 → **Read** `docs/prd.md`（全文或相关章节）
+   - 涉及后端实现思路 → **Read** `docs/backend.md`
+   - 涉及接口联调 → **Read** `docs/api.md`
+2. 若任务明确只需改代码、且上下文已足够，可**跳过**读 PRD，但在表格中注明依据（例如「主持任务已说明改 X 文件」）。
+3. 若判定需要 PRD/backend/api 但文件不存在或读失败，**停止后续实现**，仅在表格中标记失败原因。
 4. **不**为评估向用户发起追问；信息不足时倾向 **Spec**（保守）。
 
 ### Quick（较小）与 Spec（较大）判定参考
@@ -81,85 +74,67 @@ instruction 子文件随该目录类推（如 `.apm/skills/apm-propose/propose-i
 
 - 影响范围局部：少量文件或单一层次（例如仅前端组件、或仅一个后端模块小改）。
 - 无新表结构/大规模迁移/权限模型变更。
-- PRD 验收点清晰且数量少（经验上 **≤3** 条独立验收维度）。
+- 验收点清晰且数量少（经验上 **≤3** 条独立验收维度）。
 - 不需要跨多服务的架构裁定即可开工。
 
 **倾向 Spec**（命中任一条即可）：
 
 - 前后端联动、多包改造或新公共抽象。
 - 新数据模型、迁移、或安全/审计/权限相关。
-- PRD 范围大、条款多，或存在明显「待确认/多方案」需先规划。
+- 范围大、条款多，或存在明显「待确认/多方案」需先规划。
 - 评估认为不先产出 **proposal / design / specs / tasks** 则难以保证实现与验收对齐。
 
-在表格「步骤 2」中写明结论：**Quick** 或 **Spec**，以及**一行内**理由（关键词即可）。
+在表格「步骤 1」中写明结论：**Quick** 或 **Spec**，以及**一行内**理由（关键词即可）；若读了哪些文档也一并注明。
 
 ---
 
-## 步骤 3：Quick 开发模式（子 Agent）
+## 步骤 2：Quick 开发模式（子 Agent）
 
-**条件**：步骤 2 判定为 **Quick**。
+**条件**：步骤 1 判定为 **Quick**。
 
-1. 父 Agent 已通过 **Read** 掌握 `prd.md`（及需要的 backend/api）；委派时在提示中写明 **`sessionId`**、会话根路径、以及「实现须严格对照 PRD，改动范围最小化」。
+1. 父 Agent 已按需掌握必要文档；委派时在提示中写明 **`sessionId`**、会话根路径、以及「实现须对照已读文档与主持任务，改动范围最小化」。
 2. 使用 **Task** 工具，`subagent_type: generalPurpose`，**readonly: false**，委派子 Agent：
-   - 自行 **Read** `.apm/theater-sessions/<sessionId>/docs/prd.md`（及需要的 `backend.md` / `api.md`）。
-   - 按 PRD 直接改代码；遵守本仓库构建与依赖约定（AGENTS.md）。
+   - **按需 Read** `docs/prd.md` 及需要的 `backend.md` / `api.md`。
+   - 按任务与文档直接改代码；遵守本仓库构建与依赖约定（AGENTS.md）。
    - 完成后在返回中说明：改了哪些路径、如何对照验收、是否通过本地可执行的检查（若跑了 `rushx build` / 测试等则写明结果）。
-3. 父 Agent 根据子 Agent 返回在表格中填写步骤 3 **状态**；本模式下步骤 4 填 **跳过**。
+3. 父 Agent 根据子 Agent 返回在表格中填写步骤 2 **状态**；本模式下步骤 3 填 **跳过**。
 
 ---
 
-## 步骤 4：Spec 开发模式（子 Agent）
+## 步骤 3：Spec 开发模式（子 Agent）
 
-**条件**：步骤 2 判定为 **Spec**。
+**条件**：步骤 1 判定为 **Spec**。
 
 1. 父 Agent **Read** **apm-propose**、**apm-apply-change** 的 `SKILL.md`（**仅** `.apm/skills/` 下路径，见上节）。
-2. **子 Agent A（规划）**：Task `generalPurpose`，提示其自行 **Read** `.apm/skills/apm-propose/SKILL.md` 并遵循，但将工件目录改为 **`.apm/theater-sessions/<sessionId>/`**，PRD 来源为 **`docs/prd.md`**，上下文使用 **`sessionId`** 而非 `requirementId`；生成 **proposal、design、specs、tasks** 等（顺序以 SKILL 为准）。
+2. **子 Agent A（规划）**：Task `generalPurpose`，提示其自行 **Read** `.apm/skills/apm-propose/SKILL.md` 并遵循，但将工件目录改为 **`.apm/theater-sessions/<sessionId>/`**，PRD 来源为 **`docs/prd.md`**（按需阅读），上下文使用 **`sessionId`** 而非 `requirementId`；生成 **proposal、design、specs、tasks** 等（顺序以 SKILL 为准）。
 3. **子 Agent B（实现）**：待 A 成功落盘后，再 Task `generalPurpose`，提示其自行 **Read** `.apm/skills/apm-apply-change/SKILL.md` 并遵循：按 **`.apm/theater-sessions/<sessionId>/tasks.md`** 驱动实现与勾选。
 4. 若未产出可用 **`tasks.md`**，不得强行进入 **apm-apply-change**；表格中标记阻塞原因。
-5. 表格中步骤 3 填 **跳过**；步骤 4 分两行或合并一行写清 propose / apply 状态。
+5. 表格中步骤 2 填 **跳过**；步骤 3 分两行或合并一行写清 propose / apply 状态。
 
 ---
 
-## 步骤 5：提交并推送
+## 步骤 4：推送
 
 在仓库根目录执行：
 
-1. `git status`：确认变更范围。
-2. 若有未提交变更：`git add -A`，然后 `git commit -m "feat(theater-<sessionId>): <简短说明>"`（说明应概括本轮实现；若子 Agent 已多次 commit，以 `status` 为准）。
-3. `git push`：推送到当前分支对应远程（首次必要时 `-u origin feat/theater-<sessionId>`）。
-4. 再次 `git status`：**须为干净工作区**。
-
-将命令结果、最终分支名、是否已 push、工作区是否干净写入表格。
-
----
-
-## 步骤 6：同步会话文档
-
-对本轮**有内容变更**的 Markdown（通常在 `docs/`，Spec 模式可能含会话根目录下的 `proposal.md` 等），在仓库根目录逐一执行：
-
-```bash
-apm sync-session-document <sessionId> --file docs/prd.md
-apm sync-session-document <sessionId> --file <其他相对路径>
-```
+1. `git status`：确认变更范围；若仍有未提交变更（例如子 Agent 在 CLI 自动 commit 之后又改了文件），执行 `git add -A` 与 `git commit -m "feat(req-<sessionId>): <简短说明>"`。
+2. `git push`：推送到当前分支 **`feat/req-<sessionId>`**（首次必要时 `-u origin feat/req-<sessionId>`）。
+3. 再次 `git status`：**须为干净工作区**。
 
-- **仅同步业务文档**；**不要**同步 Agent 对话日志（`sessions/` 等）。
-- 若本轮未改动任何需上平台的文档，表格步骤 6 填 **跳过**。
-- 同步失败时如实记录，不假装成功。
+将命令结果、当前分支名、是否已 push、工作区是否干净写入表格（见下节「回复格式」）。
 
 ---
 
-## 步骤 7：对用户回复（表格）
+## 回复格式
 
-对用户回复 **必须包含一张 Markdown 表格**，汇总 **步骤 1 ～ 6**。表头建议：
+完成步骤 4 后，对用户回复 **必须包含一张 Markdown 表格**，汇总 **步骤 1 ～ 4**：
 
 | 步骤 | 内容                                             | 结果                           |
 | ---- | ------------------------------------------------ | ------------------------------ |
-| 1    | 切分支 `feat/theater-<sessionId>`                | 成功 / 失败（原因）            |
-| 2    | 读 PRD + 成本评估                                | Quick 或 Spec；一行理由 / 失败 |
-| 3    | Quick 开发（子 Agent）                           | 成功 / 失败 / **跳过**         |
-| 4    | Spec：apm-propose → apm-apply-change（子 Agent） | 成功 / 失败 / **跳过**         |
-| 5    | commit & push；工作区干净                        | 成功 / 失败（原因）            |
-| 6    | `sync-session-document`（有改动的文档）          | 成功 / 失败 / **跳过**         |
+| 1    | 按需读文档 + 成本评估                            | Quick 或 Spec；读了哪些 / 失败 |
+| 2    | Quick 开发（子 Agent）                           | 成功 / 失败 / **跳过**         |
+| 3    | Spec：apm-propose → apm-apply-change（子 Agent） | 成功 / 失败 / **跳过**         |
+| 4    | push；工作区干净                                 | 成功 / 失败（原因）            |
 
 **可选**：表格外增加**简短**摘要（当前分支、阻塞点）。
 
@@ -167,8 +142,8 @@ apm sync-session-document <sessionId> --file <其他相对路径>
 
 ## Guardrails
 
-- **失败即终止**：在用户提供的 **`sessionId`** 等参数合法、命令与路径按本技能书写的前提下，任一步骤（含切分支、读文件、子 Agent、`git`、同步文档）**一旦失败**：**停止后续所有步骤**，仅在表格中记录失败步骤与原因；**不要**为登录、依赖、网络等做**多次**重试。
+- **失败即终止**：在用户提供的 **`sessionId`** 等参数合法、命令与路径按本技能书写的前提下，任一步骤（含读文件、子 Agent、`git`）**一旦失败**：**停止后续所有步骤**，仅在表格中记录失败步骤与原因；**不要**为登录、依赖、网络等做**多次**重试。
 - **例外（Agent 自身失误）**：若失败明显由执行 Agent **用错工作目录、读错/漏写路径** 等导致，**允许**纠正后**仅对该失败步骤再执行一次**；纠正后仍失败则**立即终止**。
-- **不要**在无 `prd.md` 的情况下编造需求实现。
+- **不要**在无依据的情况下编造需求实现；需要 PRD 时须先 Read，读不到则停止。
 - **不要**上传或同步 Agent 对话日志。
 - **子 Agent** 提示中须带 **`sessionId`** 与会话根路径，避免改错工作树。