ai-project-manage-cli 4.0.20 → 4.0.22

package/dist/index.js

@@ -154,6 +154,28 @@ 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: {
     reportMemberAgentProgress: defineEndpoint({
       method: "POST",
@@ -203,6 +225,13 @@ 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 theaterSessionDocumentPath(sessionId, relativePath = "docs/prd.md", apmRoot = WORKSPACE_APM_DIR) {
+  const normalized = relativePath.replace(/\\/g, "/").replace(/^\/+/, "");
+  return join2(theaterSessionDir(sessionId, apmRoot), normalized);
+}
 async function ensureLoggedConfig() {
   const cfg = await ensureApmConfig();
   if (!cfg.token) {
@@ -377,7 +406,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 +809,48 @@ 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 fileName.trim().replace(/\\/g, "/").replace(/^\/+/, "");
+}
+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);
+  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/theater-job-report.ts
 import { randomUUID } from "crypto";
 function extractErrorMessage(err) {
@@ -987,6 +1058,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,6 +1074,20 @@ async function handleTheaterJob(api, ws, payload) {
     });
     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);
@@ -1037,7 +1123,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 +1249,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");
   }
 }
 
@@ -1368,10 +1454,10 @@ async function runBranch(requirementId, options = {}) {
 
 // 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 +1469,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 +1544,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 +1565,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 +1574,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_RELATIVE_PATH = "docs/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 apmRoot = options?.apmRoot ?? WORKSPACE_APM_DIR;
+  const absPath = theaterSessionDocumentPath(
+    trimmedSessionId,
+    relativePath,
+    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: relativePath,
+    content
+  });
+  console.log(`[apm] \u5DF2\u540C\u6B65\u4F1A\u8BDD\u6587\u6863: ${relativePath} (artifactId=${data.id})`);
+}
+
 // src/commands/update-dev-status.ts
 async function runUpdateDevStatus(requirementId, status) {
   const cfg = await ensureLoggedConfig();
@@ -1514,19 +1671,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 +1782,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 +1794,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 +2005,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 +2022,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 +2196,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 +2330,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 +2364,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 +2401,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 +2723,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>",
+    "\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"
+  ).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) => {

package/package.json

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

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

@@ -1,12 +1,12 @@
 ---
 name: apm-deploy
-description: 路径相对仓库根 `<repoRoot>`；`.apm` 常被 gitignore，须直接 Read 或用 Shell 验磁盘，勿仅靠索引/搜索。用户仅提供需求 ID，读 deploy README 与 workitems（常用 requirement-status.yaml 的 env）后按 README 执行并汇总；不足则终止；@ 本技能、自动部署或「apm-deploy」时使用。
+description: 路径相对仓库根 `<repoRoot>`；`.apm` 常被 gitignore，须直接 Read 或用 Shell 验磁盘，勿仅靠索引/搜索。用户仅提供需求 ID；目标部署环境从当前任务说明读取（勿读 requirement-status.yaml 的 env）；读 deploy README 与 workitems 后按 README 执行并汇总；不足则终止；@ 本技能、自动部署或「apm-deploy」时使用。
 ---
 
 # APM 自动部署（按 `.apm/deploy/README.md`）
 
 - **部署怎么做**：**唯一**以仓库 **`.apm/deploy/README.md`** 为准（用户/团队维护）。文档有问题时**不得**猜着部署或绕过文档擅自执行生产级危险操作。
-- **参数从哪来**：用户**只需提供需求 ID**（`requirementId`）；其余上下文从 **`.apm/workitems/<requirementId>/`** 内按需 **Read**，**不向用户追问**环境名、分支等部署参数。
+- **参数从哪来**：用户**只需提供需求 ID**（`requirementId`）；**目标部署环境**（如 `test` / `online`）从**当前任务说明/指令**中解析（平台自动部署节点会在指令中写明「部署到 XX 环境」）；其余上下文从 **`.apm/workitems/<requirementId>/`** 内按需 **Read**，**不向用户追问**分支等 README 未写明的部署参数。
 
 ---
 
@@ -34,24 +34,25 @@ description: 路径相对仓库根 `<repoRoot>`；`.apm` 常被 gitignore，须
 
 ## 输入与前置
 
-| 字段 | 规则 |
-| --- | --- |
-| **`requirementId`** | **必填**。与 **`<repoRoot>/.apm/workitems/<requirementId>/`** 目录名一致；**缺则索要，不猜测**。 |
-| **`<repoRoot>`** | 见上节「路径基准」；所有 `.apm` 路径均锚定于此。 |
-| **工作项上下文** | 路径 **`<repoRoot>/.apm/workitems/<requirementId>/`**（工具里写相对路径则为 `.apm/workitems/<requirementId>/`）。README 需要何种信息（目标环境、命名空间、标签等），**优先在该目录下找对应文件**；**一般**阅读 **`requirement-status.yaml`** 中的 **`env`** 字段即可与 README 对齐（具体键名以仓库内实际 YAML 为准）。若 README 指向其它文件名（如任务状态、发布说明），在同一目录 **Read** 即可。 |
-| **参数仍不足** | 若 README 要求某信息且在工作项目录与 README 附属文档中**仍无法取得**：**不得**向用户口头凑参数；**终止**并列出「README 要什么 / 已查了哪些路径 / 缺什么」。 |
+| 字段                            | 规则                                                                                                                                                                                                                                                                                                                         |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`requirementId`**             | **必填**。与 **`<repoRoot>/.apm/workitems/<requirementId>/`** 目录名一致；**缺则索要，不猜测**。                                                                                                                                                                                                                             |
+| **`<repoRoot>`**                | 见上节「路径基准」；所有 `.apm` 路径均锚定于此。                                                                                                                                                                                                                                                                             |
+| **`deployEnv`（目标部署环境）** | **从当前任务说明/指令解析**（例如「将项目部署到 online 环境」→ `deployEnv=online`）。**禁止**从 **`requirement-status.yaml`** 读取 `env`——该文件由 `apm pull` 生成，**不含**部署环境字段。若任务说明未给出目标环境：**终止**，说明「任务说明未指定部署环境」。                                                               |
+| **工作项上下文**                | 路径 **`<repoRoot>/.apm/workitems/<requirementId>/`**。README 需要何种信息（命名空间、标签、产物说明等），**优先在该目录下找对应文件**；**`requirement-status.yaml`** 仅含 `id` / `status` / `title`，用于核对需求身份，**不作为部署环境来源**。若 README 指向其它文件名（如任务状态、发布说明），在同一目录 **Read** 即可。 |
+| **参数仍不足**                  | 若 README 要求某信息且在工作项目录、任务说明与 README 附属文档中**仍无法取得**：**不得**向用户口头凑参数；**终止**并列出「README 要什么 / 已查了哪些路径 / 缺什么」。                                                                                                                                                        |
 
 ---
 
 ## 流程总览
 
-| 序号 | 步骤 | 说明 |
-| --- | --- | --- |
-| 1 | **阅读部署文档** | **Read** 全文：`.apm/deploy/README.md`（及 README 明确要求阅读的附属文档）。 |
-| 2 | **文档验收（门禁）** | 判定 README 是否足以执行；不足则**终止**（见「文档验收」）。 |
-| 3 | **加载工作项上下文** | 门禁通过后：按 README 所需，**Read** `.apm/workitems/<requirementId>/` 下文件（**优先** `requirement-status.yaml` → **`env`**）；仍缺参数则**终止**（见「输入与前置」）。 |
-| 4 | **按文档执行** | **严格**按 README 的步骤、顺序与命令执行，并用上一步解析出的参数（如替换占位符、导出环境变量）；不添加 README 未要求的步骤。 |
-| 5 | **对用户回复** | 用** Markdown 表格**汇总各步与命令结果（见文末模板）；简述阻塞或跳过原因。 |
+| 序号 | 步骤                               | 说明                                                                                                                                                       |
+| ---- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | **阅读部署文档**                   | **Read** 全文：`.apm/deploy/README.md`（及 README 明确要求阅读的附属文档）。                                                                               |
+| 2    | **文档验收（门禁）**               | 判定 README 是否足以执行；不足则**终止**（见「文档验收」）。                                                                                               |
+| 3    | **解析部署环境并加载工作项上下文** | 门禁通过后：从**任务说明**解析 `deployEnv`；按 README 所需 **Read** `.apm/workitems/<requirementId>/` 下其它文件；仍缺参数则**终止**（见「输入与前置」）。 |
+| 4    | **按文档执行**                     | **严格**按 README 的步骤、顺序与命令执行，并用上一步解析出的参数（含 `deployEnv`、替换占位符、导出环境变量）；不添加 README 未要求的步骤。                 |
+| 5    | **对用户回复**                     | 用**Markdown 表格**汇总各步与命令结果（见文末模板）；简述阻塞或跳过原因。                                                                                  |
 
 ---
 
@@ -67,12 +68,12 @@ description: 路径相对仓库根 `<repoRoot>`；`.apm` 常被 gitignore，须
 
 在阅读完成后、加载工作项上下文与执行任何部署命令前，必须自检下列项。**任一条不满足**：**不得执行部署**；在对话中**逐条列出问题**（引用 README 片段或章节标题即可），然后**终止本技能流程**。
 
-| 验收项 | 不满足时的表现（示例） |
-| --- | --- |
+| 验收项       | 不满足时的表现（示例）                                                                  |
+| ------------ | --------------------------------------------------------------------------------------- |
 | **可执行性** | 缺少前置条件（账号、CLI、密钥、目标环境）、缺少具体命令或顺序混乱到无法唯一确定下一步。 |
-| **一致性** | 前后矛盾（例如同一环境两套冲突命令）、版本/工具要求互相打架。 |
-| **完整性** | 引用不存在的脚本/配置文件、Broken link、关键占位符未替换说明。 |
-| **清晰性** | 读完仍**不知道**该如何在本仓库完成一次部署（步骤含糊到无法落地）。 |
+| **一致性**   | 前后矛盾（例如同一环境两套冲突命令）、版本/工具要求互相打架。                           |
+| **完整性**   | 引用不存在的脚本/配置文件、Broken link、关键占位符未替换说明。                          |
+| **清晰性**   | 读完仍**不知道**该如何在本仓库完成一次部署（步骤含糊到无法落地）。                      |
 
 **特别约定（用户维护文档）**
 
@@ -82,13 +83,14 @@ description: 路径相对仓库根 `<repoRoot>`；`.apm` 常被 gitignore，须
 
 ---
 
-## 步骤 3：加载工作项上下文
+## 步骤 3：解析部署环境并加载工作项上下文
 
 仅在「文档验收」**全部通过**后执行。
 
-1. 确认目录 **`<repoRoot>/.apm/workitems/<requirementId>/`**（工具相对路径：`.apm/workitems/<requirementId>/`）存在；不存在则**终止**（不要假想 ID）。
-2. 根据 README 描述的占位符或变量（如「目标环境」「部署 env」），**Read** 该目录内相应文件（路径同样锚定 `<repoRoot>`）；**默认优先** **`requirement-status.yaml`**，提取 **`env`**（及 README 明确要求的其它字段）。
-3. 若 README 需要的某项信息在工作项内**不存在或未填写**：**终止**，说明缺失字段与文件路径；**不**请用户在对话里补充（用户约定仅提供需求 ID）。
+1. **解析 `deployEnv`**：从**当前任务说明/指令**提取目标部署环境（如 `test`、`online`）。平台自动部署节点典型表述为「将项目部署到 {环境} 环境」。**不得**打开 `requirement-status.yaml` 找 `env` 字段。
+2. 确认目录 **`<repoRoot>/.apm/workitems/<requirementId>/`**（工具相对路径：`.apm/workitems/<requirementId>/`）存在；不存在则**终止**（不要假想 ID）。
+3. 根据 README 描述的占位符或变量，**Read** 该目录内相应文件（路径锚定 `<repoRoot>`）；**`requirement-status.yaml`** 可用于核对 `id` / `status` / `title`，**不含**部署环境。
+4. 若 README 需要的某项信息在任务说明、工作项目录与 README 附属文档中**不存在或未填写**：**终止**，说明缺失字段与已查路径；**不**请用户在对话里补充（用户约定仅提供需求 ID 与任务说明中的环境）。
 
 ---
 
@@ -96,7 +98,7 @@ description: 路径相对仓库根 `<repoRoot>`；`.apm` 常被 gitignore，须
 
 仅在「工作项上下文」**已满足 README 对参数的要求**后执行。
 
-1. **严格对照** README：顺序、工作目录（若文档指定 `cd`）、环境变量、所用 CLI（如 `rush`、`docker`、`kubectl` 等）均以文档为准；将步骤 3 得到的 **`env` 等**按 README 约定注入命令或环境（禁止凭猜测填值）。**默认在 `<repoRoot>` 执行**；遵守本仓库 **AGENTS.md**（如 Rush 安装/构建约定），但**不**执行 README **未写出**的额外构建/发布步骤。
+1. **严格对照** README：顺序、工作目录（若文档指定 `cd`）、环境变量、所用 CLI（如 `rush`、`docker`、`kubectl`、`apm deploy-frontend` 等）均以文档为准；将步骤 3 得到的 **`deployEnv` 等**按 README 约定注入命令或环境（禁止凭猜测填值）。**默认在 `<repoRoot>` 执行**；遵守本仓库 **AGENTS.md**（如 Rush 安装/构建约定），但**不**执行 README **未写出**的额外构建/发布步骤。
 2. **每条命令**记录：是否成功、退出码或关键输出摘要、失败时的 stderr（可截断至可读长度）。
 3. **失败处理**：与 **Guardrails** 一致——默认**失败即终止**后续部署步骤，在表格与摘要中写明失败命令与原因；**不因网络抖动等做无文档依据的多轮重试**（除非 README **明确**要求重试策略）。
 4. **安全**：若 README 要求确认交互（如 `Are you sure?`），按文档处理；文档要求人工审批而 Agent 无法完成时，执行到该步即停止，并标明「需人工完成」。
@@ -107,13 +109,13 @@ description: 路径相对仓库根 `<repoRoot>`；`.apm` 常被 gitignore，须
 
 回复中**必须包含**一张汇总表，建议结构：
 
-| 阶段 | 内容 | 结果 |
-| --- | --- | --- |
-| 阅读 | `.apm/deploy/README.md`（及 README 要求阅读的附属文档） | 成功 / 失败（原因） |
-| 验收 | 文档是否足以执行 | 通过 / **未通过**（列具体问题） |
-| 上下文 | `.apm/workitems/<requirementId>/`（含 `requirement-status.yaml` / `env` 等） | 成功 / **失败**（缺文件或缺字段） |
-| 执行 | 按 README 执行的命令或步骤摘要（可按行拆分） | 每步 成功 / 失败 / 跳过 / 需人工 |
-| 结论 | 部署是否完成 README 所述目标 | 是 / 否 / 未执行（门禁或上下文未过） |
+| 阶段   | 内容                                                         | 结果                                  |
+| ------ | ------------------------------------------------------------ | ------------------------------------- |
+| 阅读   | `.apm/deploy/README.md`（及 README 要求阅读的附属文档）      | 成功 / 失败（原因）                   |
+| 验收   | 文档是否足以执行                                             | 通过 / **未通过**（列具体问题）       |
+| 上下文 | 任务说明中的 `deployEnv` + `.apm/workitems/<requirementId>/` | 成功 / **失败**（缺环境或未找到文件） |
+| 执行   | 按 README 执行的命令或步骤摘要（可按行拆分）                 | 每步 成功 / 失败 / 跳过 / 需人工      |
+| 结论   | 部署是否完成 README 所述目标                                 | 是 / 否 / 未执行（门禁或上下文未过）  |
 
 若门禁或上下文未通过：**不要**出现「已尝试部署」的误导性表述；表格中「执行」阶段填 **未执行（原因）**。
 
@@ -126,7 +128,8 @@ description: 路径相对仓库根 `<repoRoot>`；`.apm` 常被 gitignore，须
 - **gitignore 不等于不存在**：`.apm` 下文件可能不入 Git 索引；**禁止**用「搜索无结果」代替 **Read** 或磁盘校验。
 - **路径锚定 `<repoRoot>`**：凡 `.apm/deploy`、`.apm/workitems` 等路径**仅**相对仓库根；**禁止**因当前焦点在 monorepo 内某一子目录而在错误基底上拼路径。
 - **文档优先**：无合格 `.apm/deploy/README.md` 解读结果，**不部署**。
-- **用户只给 ID**：除 **`requirementId`** 外，**不依赖**用户在对话中口头提供环境、密钥说明等；这些信息须来自 **工作项目录** 或 README 已写明的本地/CI 约定。缺数据则**终止并写明缺口**，而非让用户「现场补一句」。
+- **部署环境来源**：`deployEnv` **只**来自当前任务说明/指令；**禁止**从 `requirement-status.yaml` 读取 `env`（该字段已不再由 `apm pull` 写入）。
+- **用户只给 ID + 任务环境**：除 **`requirementId`** 与任务说明中的**目标环境**外，**不依赖**用户在对话中口头补充密钥、分支等；这些信息须来自 **工作项目录** 或 README 已写明的本地/CI 约定。缺数据则**终止并写明缺口**，而非让用户「现场补一句」。
 - **失败即终止**：在文档与上下文明确的前提下，任一步骤失败 → 停止后续步骤，仅记录状态；**例外**仅允许 Agent **自身**错误（如错目录）纠正后对**同一步**再试一次，仍失败则终止。
-- **不臆造**：README 未写的命令、环境、目标集群/命名空间，**不补充**；工作项 YAML **未提供**的字段**不得**编造。
+- **不臆造**：README 未写的命令、环境、目标集群/命名空间，**不补充**；任务说明与工作项 **未提供**的字段**不得**编造。
 - **不报假成功**：命令失败或未完成 README 目标时，结论必须为「否」或等价表述。

package/template/theater-skills/README.md

@@ -0,0 +1,13 @@
+## 剧场技能
+
+供剧场（Theater）会话中各角色 Agent 使用的技能，由 `apm init` 复制到 `.apm/theater-skills/`，可用 `apm update-theater-skills` 从 CLI 内置模板重置。
+
+`THEATER_JOB` 开始时会自动 `pull-session`，将平台会话文档下载到 `.apm/theater-sessions/<sessionId>/docs/`。`docs/` 下文档变更后通过 `apm sync-session-document` 同步到平台；**Agent 对话日志不上传**。
+
+## 目录
+
+| 技能                   | 说明                                                                                                     |
+| ---------------------- | -------------------------------------------------------------------------------------------------------- |
+| `apm-theater-prd/`     | 产品经理：维护会话 PRD（`.apm/theater-sessions/<sessionId>/docs/prd.md`）并同步到平台                    |
+| `apm-theater-backend/` | 后端：`docs/backend.md`（技术评审实现思路）、`docs/api.md`（前端联调接口说明）；增删改查与同步规则同 PRD |
+| `apm-theater-dev/`     | 开发：按 `sessionId` 全自动编码（切分支、Quick/Spec、提交推送、同步 `docs/` 文档）                       |

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

@@ -0,0 +1,115 @@
+---
+name: apm-theater-backend
+description: 剧场会话后端文档：在 .apm/theater-sessions/<sessionId>/docs/ 维护 backend.md（技术评审用实现思路）与 api.md（前端联调用接口说明），落盘后同步到平台会话文档。仅当用户 @ 本技能时使用。
+disable-model-invocation: true
+---
+
+# 剧场会话后端文档
+
+在剧场会话上下文中维护后端交付文档：
+
+| 文件                  | 用途                                                         |
+| --------------------- | ------------------------------------------------------------ |
+| **`docs/backend.md`** | **后端技术文档**：如何实现该需求，实现思路写清，供技术评审   |
+| **`docs/api.md`**     | **接口联调文档**：涉及接口与参数，给前端；多接口协作须写清楚 |
+
+本地路径均在 **`.apm/theater-sessions/<sessionId>/docs/`**；落盘后须通过 CLI 同步到平台「会话文档」。
+
+`THEATER_JOB` 开始时会自动 pull 平台文档到本地。Agent **对话日志不上传**；仅 `docs/` 下业务文档在变更后同步。
+
+---
+
+## 输入
+
+| 字段            | 规则                                                                                   |
+| --------------- | -------------------------------------------------------------------------------------- |
+| **`sessionId`** | **必填**。剧场会话 ID，与 `.apm/theater-sessions/<sessionId>/` 目录名一致。            |
+| **目标文档**    | 按用户意图选择 `backend.md` 或 `api.md`；未指明时结合上下文判断，仍不明则询问。        |
+| **会话上下文**  | 若由 `THEATER_JOB` 触发，`theaterSessionId` 即 `sessionId`；缺省时向用户索要，不猜测。 |
+
+---
+
+## 文件路径
+
+以下规则对 **`backend.md`**、**`api.md`** 均适用（将 `<文件名>` 替换为对应文件）：
+
+| 操作     | 路径 / 方式                                                                           |
+| -------- | ------------------------------------------------------------------------------------- |
+| **新增** | 创建 `.apm/theater-sessions/<sessionId>/docs/<文件名>`（`docs` 目录不存在时一并创建） |
+| **编辑** | 更新上述文件（Write / StrReplace）                                                    |
+| **查阅** | 使用 **Read** 工具阅读上述文件                                                        |
+| **删除** | **不支持**。不要删除该文件，也不要尝试从平台删除对应文档。                            |
+
+---
+
+## 同步到平台（新增 / 编辑后必做）
+
+本地文档 **新增或内容变更后**执行：
+
+```bash
+apm sync-session-document <sessionId> --file docs/backend.md
+apm sync-session-document <sessionId> --file docs/api.md
+```
+
+- 命令会调用平台接口 **新增或更新** 该会话的产物文档（按 `fileName` 幂等）。
+- **查阅**（Read）**不需要**执行同步。
+- **不要**同步 Agent 对话日志（`sessions/` 等）；仅同步 `docs/` 业务文档。
+- 同步失败时：在回复中说明错误，**不要**声称已写入平台。
+
+---
+
+## 撰写要求
+
+撰写前建议 **Read** `.apm/theater-sessions/<sessionId>/docs/prd.md`（若存在），与需求范围对齐。
+
+### `backend.md`（技术评审）
+
+须 **Read** [apm-theater-backend-template.md](./apm-theater-backend-template.md)，按模板**章节粒度**组织正文（需求摘要 → 方案总览 → 库表 → 分层 → 核心流程 → 实现状态 → 待办 → 风险）。核心是 **实现思路写清楚**；接口参数明细放 `api.md`。
+
+### `api.md`（前端联调）
+
+须 **Read** [apm-theater-api-template.md](./apm-theater-api-template.md)，按模板**章节粒度**组织正文（基础约定 → 数据模型 → 接口清单 → 接口明细 → 页面配合 → 错误场景 → 联调清单）。写清每个功能的**方法、路径、参数、响应**；多接口协作须写**步骤、顺序、副作用与前端展示规则**。
+
+---
+
+## 流程
+
+### 1. 锚定会话与文档
+
+确认 **`sessionId`** 与目标文件（`backend.md` / `api.md`）。
+
+### 2. 查阅（只读）
+
+**Read** `.apm/theater-sessions/<sessionId>/docs/<文件名>`。
+
+- 文件不存在：说明尚未创建，询问是否新建；**不要**编造正文。
+
+### 3. 新增 `backend.md`
+
+1. **Read** `prd.md`（若存在）与 [apm-theater-backend-template.md](./apm-theater-backend-template.md)。
+2. **Write** 落盘至 `.apm/theater-sessions/<sessionId>/docs/backend.md`。
+3. **`apm sync-session-document <sessionId> --file docs/backend.md`**。
+
+### 4. 新增 `api.md`
+
+1. **Read** `prd.md`、必要时 `backend.md`，以及 [apm-theater-api-template.md](./apm-theater-api-template.md)。
+2. **Write** 落盘至 `.apm/theater-sessions/<sessionId>/docs/api.md`。
+3. **`apm sync-session-document <sessionId> --file docs/api.md`**。
+
+### 5. 编辑
+
+1. **Read** 现有文件与对应模板（若本会话尚未读过）。
+2. **Write** 或 **StrReplace** 落盘。
+3. **`apm sync-session-document <sessionId> --file docs/<文件名>`**。
+4. 简要说明变更要点。
+
+---
+
+## Guardrails
+
+- **不要删除** `backend.md`、`api.md`，也不要删除平台会话文档。
+- **不要**在无 `sessionId` 时写入任意目录。
+- **新增或编辑后必须同步** `docs/` 文档；仅 Read 时不同步。
+- **不要**上传或同步 Agent 对话日志。
+- 同步失败时如实报告，不假装成功。
+- `backend.md` 与 `api.md` 分工明确：方案在 backend，接口契约在 api；待确认项写入文档，避免阻塞主文。

package/template/theater-skills/apm-theater-backend/apm-theater-api-template.md

@@ -0,0 +1,146 @@
+# 接口联调文档模板
+
+**定位**：给**前端**联调用的接口说明——写清涉及到的接口、参数、响应与页面配合方式；若某功能需**多个接口配合**（如先上传再绑定），须写清**步骤、顺序与副作用**。
+
+撰写前建议 **Read** `prd.md`、必要时 **Read** `backend.md`，与需求及后端方案对齐。
+
+---
+
+## 正文骨架
+
+按下列章节组织（编号可依项目调整，但**顺序与粒度**保持一致）：
+
+```markdown
+# [需求标题] — 接口联调文档
+
+> 后端模块：`XxxController`（`/模块前缀`）
+
+## 1. 基础约定
+
+### 1.1 Base URL
+
+（开发/测试示例地址；是否带 context-path）
+
+### 1.2 鉴权
+
+（Header / Token 名称；本期是否有额外权限参数）
+
+### 1.3 统一响应体
+
+（字段表 + 成功/失败 JSON 示例；写明业务数据在哪个字段，如 `result` / `data`）
+
+### 1.4 特殊接口说明（若有）
+
+（如：文件流下载无 JSON 包装、预览返回路径给现网组件等）
+
+---
+
+## 2. 数据模型 `[实体名]`
+
+列表、详情、编辑共用的核心字段表（字段 | 类型 | 说明）；**前端展示规则**写进说明列（如某字段为 `null` 时列表留空）。
+
+---
+
+## 3. 接口清单
+
+| 方法 | 路径 | 说明 |
+| ---- | ---- | ---- |
+| …    | …    | …    |
+
+未落地接口在说明列标 **待后端实现/提供**。
+
+---
+
+## 4. 接口明细
+
+### 4.1 [接口名称]
+
+**[METHOD]** `完整路径`
+
+**Query / Body 参数表**（参数 | 必填 | 默认 | 说明）
+
+**响应**（`result` / `data` 结构；复杂时给 JSON 示例）
+
+**前端展示/交互要点**（与本接口直接相关的 UI 规则）
+
+**说明**（业务副作用、与 PRD 的对应关系）
+
+### 4.2 …
+
+#### 多步骤协作（如「行内上传 + 绑定」）
+
+分步骤写清，每步单独小节：
+
+1. **步骤 1**：上传接口 — 入参、成功时哪个字段是后续要用的路径
+2. **步骤 2**：编辑/保存接口 — Body 示例（首次 / 更换两种）、副作用（如是否更新 `submitDate`）、成功后是否刷新列表
+
+**注意**：只读页面不调写接口等 PRD 约束写在本节。
+
+### 4.x 易混淆接口对比（若存在）
+
+用表格对比「入口 | 接口 | 内容」，避免前端联调混用。
+
+---
+
+## 5. 前端页面与接口配合
+
+按页面用缩进树或列表写调用链，例如：
+
+### 5.1 列表页
+
+加载列表 → GET /list
+├─ 新增 → …
+├─ 删除 → …
+└─ 某列操作 → 多步 upload → edit
+
+### 5.2 新增页 / 详情页
+
+…
+
+---
+
+## 6. 错误场景
+
+| 场景 | 表现                                    |
+| ---- | --------------------------------------- |
+| …    | `success=false` 的 message 或 HTTP 状态 |
+
+---
+
+## 7. 联调检查清单
+
+- [ ] …
+- [ ] …
+```
+
+---
+
+## 写法要点
+
+| 类型       | 写法要点                                                                    |
+| ---------- | --------------------------------------------------------------------------- |
+| 接口清单   | 先总表后明细；路径、方法、一句话说明齐全                                    |
+| 单接口     | 参数表 + 响应结构 + **前端展示要点**；复杂 Body 给完整 JSON 示例            |
+| 多接口协作 | 分步骤编号；每步写清入参、成功判据、传给下一步的字段；写副作用与是否刷新    |
+| 数据模型   | 共用实体一次定义；`null` / 空值的 UI 处理写在字段说明或列表要点里           |
+| 页面配合   | 按列表/新增/详情分节；用树状流程串起接口，不只堆接口表                      |
+| 易混淆能力 | 同类下载/预览等多入口时，用对比表说明差异                                   |
+| 待实现     | 明确标 **待后端实现**；错误场景与检查清单可预留项                           |
+| 项目约定   | 遵循目标项目既有风格（如 Jeecg `Result`、APM `{ data }`）；不擅自改路径规范 |
+
+---
+
+## 落盘前自检
+
+- [ ] 含 **基础约定、数据模型、接口清单、接口明细、页面配合、错误场景、联调清单**
+- [ ] 每个 PRD 功能点在「页面配合」或明细中能找到对应接口
+- [ ] 多步骤流程（上传+保存等）顺序与字段传递写清
+- [ ] 列表/详情/空值展示规则前端可直接照做
+- [ ] 与 `backend.md` 不矛盾；未实现接口已标注
+- [ ] 检查清单覆盖 PRD 关键验收点
+
+---
+
+## 局部替换
+
+只改部分接口或页面时：同步更新 **§3 清单**、**§4 明细**、**§5 页面配合** 与 **§7 检查清单** 中相关条目。

package/template/theater-skills/apm-theater-backend/apm-theater-backend-template.md

@@ -0,0 +1,132 @@
+# 后端技术文档模板
+
+**定位**：说明后端**准备如何实现该需求**，实现思路写清楚，供**技术评审**。接口参数与前端联调细节放在 `api.md`，本文聚焦方案、数据、流程与实现状态。
+
+撰写前须 **Read** `.apm/theater-sessions/<sessionId>/docs/prd.md`（若存在）。
+
+---
+
+## 正文骨架
+
+```markdown
+# [需求标题] — 后端技术方案
+
+> 关联 PRD：[prd.md](./prd.md)
+
+## 1. 需求摘要
+
+（一段话概括本期做什么；**本期不做**单独列出）
+
+---
+
+## 2. 方案总览
+
+| 项       | 说明              |
+| -------- | ----------------- |
+| 模块     | …                 |
+| 数据表   | …                 |
+| 接口前缀 | …                 |
+| 实现风格 | …                 |
+| 代码现状 | 已落地 / 待完善项 |
+
+（与同类既有模块的差异、核心设计决策 1 ～ 3 句）
+
+---
+
+## 3. 数据库设计
+
+（迁移脚本路径若有则写）
+
+| 字段 | 类型 | 说明 |
+| ---- | ---- | ---- |
+| …    | …    | …    |
+
+**索引**、**约束**、注释与命名注意点。
+
+---
+
+## 4. 后端分层结构
+
+（目录树或包结构：entity / mapper / service / controller）
+
+---
+
+## 5. 核心业务流程
+
+按 PRD 场景分小节（如 5.1 新增、5.2 行内上传…），每节写清：
+
+1. 步骤顺序
+2. 校验规则与 **不做什么**
+3. 副作用（写库、写文件、更新时间等）
+4. **待实现** 项单独标出
+
+多接口协作写清与通用能力（如上传）的组合方式；易混淆能力用表格对比。
+
+---
+
+## 6. 接口能力对照（实现状态）
+
+| 能力 | 状态         | 备注 |
+| ---- | ------------ | ---- |
+| …    | ✅ / ⚠️ / ❌ | …    |
+
+（评审用速览表；细节不在此重复，见 `api.md`）
+
+---
+
+## 7. 菜单与权限（若涉及）
+
+---
+
+## 8. 配置与部署
+
+| 配置 | 说明 |
+| ---- | ---- |
+| …    | …    |
+
+---
+
+## 9. 待办清单（开发任务）
+
+1. …
+2. …
+
+---
+
+## 10. 风险与注意点
+
+- …
+```
+
+按需删减章节（如无独立菜单配置可省略 §7）；**核心业务流程**与 **待办清单** 不可省。
+
+---
+
+## 写法要点
+
+| 类型       | 写法要点                                                                |
+| ---------- | ----------------------------------------------------------------------- |
+| 需求摘要   | 与 PRD 一一对应；**本期不做** 写清，避免评审范围漂移                    |
+| 方案总览   | 模块、表、接口前缀、与存量模块关系；**代码现状** 如实（已做/待补）      |
+| 数据库     | 字段业务含义、NULL 语义、何时写入；索引与 PRD 约束（如不做唯一性）对齐  |
+| 核心流程   | 分场景编号；写清两步/多步协作、副作用、与 PRD 差异；**待实现** 醒目标注 |
+| 实现状态表 | 能力粒度与 PRD 验收点对齐；用 ✅ ⚠️ ❌ 或文字状态                       |
+| 待办清单   | 可执行任务，与 §6 中未完成项对应                                        |
+| 风险       | 安全、磁盘、与相似模块混淆等；不写接口 JSON                             |
+
+---
+
+## 落盘前自检
+
+- [ ] 评审人不读代码也能理解**怎么做、差什么**
+- [ ] 与 `prd.md` 范围一致，「本期不做」无遗漏
+- [ ] 核心流程覆盖 PRD 各场景，含多步协作与副作用
+- [ ] §6 实现状态与 §9 待办一致
+- [ ] 接口契约细节在 `api.md`，本文不重复参数表
+- [ ] 未臆造已完成功能；待做项已列出
+
+---
+
+## 局部替换
+
+只改部分能力时：同步更新 **§5 流程**、**§6 状态表**、**§9 待办** 与 **§10 风险** 中相关条目。

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

@@ -0,0 +1,174 @@
+---
+name: apm-theater-dev
+description: 按剧场会话 ID 全自动编码：切分支、读会话 PRD（及 backend/api 文档）、按改动规模选择 Quick 或 Spec、提交并推送、同步 docs 产物；子 Agent 承担编码与规划落地；当用户 @ 本技能、提及剧场全自动开发或「apm-theater-dev」时使用。
+---
+
+# 剧场全自动开发（按会话 ID）
+
+用户给出 **剧场会话 ID**（`sessionId`，与 `.apm/theater-sessions/<sessionId>/` 目录名一致）。**缺 ID 时索要，不猜测。**
+
+`THEATER_JOB` 开始时会自动 pull 平台文档到本地。Agent **对话日志不上传**；`docs/` 等业务文档在变更后须 `sync-session-document`。
+
+---
+
+## 输入
+
+| 字段            | 规则                                                                                   |
+| --------------- | -------------------------------------------------------------------------------------- |
+| **`sessionId`** | **必填**。与 `.apm/theater-sessions/<sessionId>/` 目录名一致。                         |
+| **会话上下文**  | 若由 `THEATER_JOB` 触发，`theaterSessionId` 即 `sessionId`；缺省时向用户索要，不猜测。 |
+
+**会话根目录**：`.apm/theater-sessions/<sessionId>/`  
+**PRD**：`.apm/theater-sessions/<sessionId>/docs/prd.md`  
+**可选参考**：`docs/backend.md`、`docs/api.md`
+
+---
+
+## 技能文件定位（apm-propose / apm-apply-change）
+
+Spec 路径依赖的技能**仅**来自 **`.apm/skills/`**。执行前父 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。
+
+委派子 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>
+   ```
+
+   若远端已有该分支：`git switch feat/theater-<sessionId>` 后 `git pull --no-edit`（按需）。
+
+2. 记录：是否成功、当前分支名、简要输出或错误（写入最终表格）。**失败则按「Guardrails → 失败即终止」处理**。
+
+---
+
+## 步骤 2：读取 PRD 并评估改动成本
+
+1. **Read** 全文：`.apm/theater-sessions/<sessionId>/docs/prd.md`。
+2. 若实现涉及后端/接口，按需 **Read** `docs/backend.md`、`docs/api.md`。
+3. 若 `prd.md` 读失败则**停止后续实现**，仅在表格中标记失败原因。
+4. **不**为评估向用户发起追问；信息不足时倾向 **Spec**（保守）。
+
+### Quick（较小）与 Spec（较大）判定参考
+
+**倾向 Quick**（满足越多越适用）：
+
+- 影响范围局部：少量文件或单一层次（例如仅前端组件、或仅一个后端模块小改）。
+- 无新表结构/大规模迁移/权限模型变更。
+- PRD 验收点清晰且数量少（经验上 **≤3** 条独立验收维度）。
+- 不需要跨多服务的架构裁定即可开工。
+
+**倾向 Spec**（命中任一条即可）：
+
+- 前后端联动、多包改造或新公共抽象。
+- 新数据模型、迁移、或安全/审计/权限相关。
+- PRD 范围大、条款多，或存在明显「待确认/多方案」需先规划。
+- 评估认为不先产出 **proposal / design / specs / tasks** 则难以保证实现与验收对齐。
+
+在表格「步骤 2」中写明结论：**Quick** 或 **Spec**，以及**一行内**理由（关键词即可）。
+
+---
+
+## 步骤 3：Quick 开发模式（子 Agent）
+
+**条件**：步骤 2 判定为 **Quick**。
+
+1. 父 Agent 已通过 **Read** 掌握 `prd.md`（及需要的 backend/api）；委派时在提示中写明 **`sessionId`**、会话根路径、以及「实现须严格对照 PRD，改动范围最小化」。
+2. 使用 **Task** 工具，`subagent_type: generalPurpose`，**readonly: false**，委派子 Agent：
+   - 自行 **Read** `.apm/theater-sessions/<sessionId>/docs/prd.md`（及需要的 `backend.md` / `api.md`）。
+   - 按 PRD 直接改代码；遵守本仓库构建与依赖约定（AGENTS.md）。
+   - 完成后在返回中说明：改了哪些路径、如何对照验收、是否通过本地可执行的检查（若跑了 `rushx build` / 测试等则写明结果）。
+3. 父 Agent 根据子 Agent 返回在表格中填写步骤 3 **状态**；本模式下步骤 4 填 **跳过**。
+
+---
+
+## 步骤 4：Spec 开发模式（子 Agent）
+
+**条件**：步骤 2 判定为 **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 为准）。
+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：提交并推送
+
+在仓库根目录执行：
+
+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 <其他相对路径>
+```
+
+- **仅同步业务文档**；**不要**同步 Agent 对话日志（`sessions/` 等）。
+- 若本轮未改动任何需上平台的文档，表格步骤 6 填 **跳过**。
+- 同步失败时如实记录，不假装成功。
+
+---
+
+## 步骤 7：对用户回复（表格）
+
+对用户回复 **必须包含一张 Markdown 表格**，汇总 **步骤 1 ～ 6**。表头建议：
+
+| 步骤 | 内容                                             | 结果                           |
+| ---- | ------------------------------------------------ | ------------------------------ |
+| 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`（有改动的文档）          | 成功 / 失败 / **跳过**         |
+
+**可选**：表格外增加**简短**摘要（当前分支、阻塞点）。
+
+---
+
+## Guardrails
+
+- **失败即终止**：在用户提供的 **`sessionId`** 等参数合法、命令与路径按本技能书写的前提下，任一步骤（含切分支、读文件、子 Agent、`git`、同步文档）**一旦失败**：**停止后续所有步骤**，仅在表格中记录失败步骤与原因；**不要**为登录、依赖、网络等做**多次**重试。
+- **例外（Agent 自身失误）**：若失败明显由执行 Agent **用错工作目录、读错/漏写路径** 等导致，**允许**纠正后**仅对该失败步骤再执行一次**；纠正后仍失败则**立即终止**。
+- **不要**在无 `prd.md` 的情况下编造需求实现。
+- **不要**上传或同步 Agent 对话日志。
+- **子 Agent** 提示中须带 **`sessionId`** 与会话根路径，避免改错工作树。

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

@@ -0,0 +1,98 @@
+---
+name: apm-theater-prd
+description: 剧场会话 PRD 文档：在 .apm/theater-sessions/<sessionId>/docs/prd.md 新增、编辑、查阅需求正文，落盘后同步到平台会话文档。仅当用户 @ 本技能时使用。
+disable-model-invocation: true
+---
+
+# 剧场会话 PRD
+
+在剧场会话上下文中维护 **产品需求文档（PRD）**。本地权威路径为 **`.apm/theater-sessions/<sessionId>/docs/prd.md`**；落盘后须通过 CLI 同步到平台「会话文档」。
+
+`THEATER_JOB` 开始时会自动 pull 平台文档到本地。Agent **对话日志不上传**；仅 `docs/` 下业务文档在变更后同步。
+
+---
+
+## 输入
+
+| 字段            | 规则                                                                                   |
+| --------------- | -------------------------------------------------------------------------------------- |
+| **`sessionId`** | **必填**。剧场会话 ID，与 `.apm/theater-sessions/<sessionId>/` 目录名一致。            |
+| **会话上下文**  | 若由 `THEATER_JOB` 触发，`theaterSessionId` 即 `sessionId`；缺省时向用户索要，不猜测。 |
+
+---
+
+## 文件路径
+
+| 操作     | 路径 / 方式                                                                         |
+| -------- | ----------------------------------------------------------------------------------- |
+| **新增** | 创建 `.apm/theater-sessions/<sessionId>/docs/prd.md`（`docs` 目录不存在时一并创建） |
+| **编辑** | 更新上述文件（Write / StrReplace）                                                  |
+| **查阅** | 使用 **Read** 工具阅读上述文件                                                      |
+| **删除** | **不支持**。不要删除该文件，也不要尝试从平台删除对应文档。                          |
+
+---
+
+## 同步到平台（新增 / 编辑后必做）
+
+本地 `prd.md` **新增或内容变更后**执行：
+
+```bash
+apm sync-session-document <sessionId>
+```
+
+- 默认同步 `docs/prd.md`；若同步其他相对路径，加 `--file <相对路径>`（相对于 `.apm/theater-sessions/<sessionId>/`）。
+- 命令会调用平台接口 **新增或更新** 该会话的产物文档（按 `fileName` 幂等）。
+- **查阅**（Read）**不需要**执行同步。
+- **不要**同步 Agent 对话日志（`sessions/` 等）；仅同步 `docs/` 业务文档。
+- 同步失败时：在回复中说明错误，**不要**声称已写入平台。
+
+---
+
+## 撰写要求（PRD 正文）
+
+撰写或修订 `prd.md` 前，须 **Read** [apm-refine-template.md](../../skills/apm-refine/apm-refine-template.md)，按其中正文骨架、需求点写法、示例与落盘自检组织正文。
+
+在此基础上补充：
+
+- **可验收**：产品、测试、开发不读代码也能写用例。
+- **业务化**：写界面、流程、规则与系统表现；避免堆砌实现细节。
+- **术语统一**：同一概念全文同一叫法。
+
+---
+
+## 流程
+
+### 1. 锚定会话
+
+确认 **`sessionId`**。根目录：`.apm/theater-sessions/<sessionId>/docs/`。
+
+### 2. 查阅（只读）
+
+**Read** `.apm/theater-sessions/<sessionId>/docs/prd.md`。
+
+- 文件不存在：说明尚未创建，询问是否新建；**不要**编造正文。
+
+### 3. 新增
+
+1. **Read** [apm-refine-template.md](../../skills/apm-refine/apm-refine-template.md)，按模板撰写完整 PRD 正文。
+2. **Write** 落盘至 `.apm/theater-sessions/<sessionId>/docs/prd.md`。
+3. 执行 **`apm sync-session-document <sessionId>`**。
+4. 简要确认：本地路径、已同步到会话文档。
+
+### 4. 编辑
+
+1. **Read** 现有 `prd.md`（若本会话尚未读过）。
+2. 按需 **Read** [apm-refine-template.md](../../skills/apm-refine/apm-refine-template.md)；按用户或场景要求修订；**Write** 或 **StrReplace** 落盘。
+3. 执行 **`apm sync-session-document <sessionId>`**。
+4. 简要说明变更要点。
+
+---
+
+## Guardrails
+
+- **不要删除** `prd.md`，也不要删除平台会话文档。
+- **不要**在无 `sessionId` 时写入任意目录。
+- **新增或编辑后必须同步** `docs/` 文档；仅 Read 时不同步。
+- **不要**上传或同步 Agent 对话日志。
+- 同步失败时如实报告，不假装成功。
+- 向用户澄清范围时，歧义写入 PRD 的「待确认」或「假设」，避免阻塞整篇文档。