ai-project-manage-cli 3.0.5 → 3.0.7

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync9 } from "fs";
-import { dirname as dirname2, join as join7 } from "path";
+import { readFileSync as readFileSync10 } from "fs";
+import { dirname as dirname2, join as join8 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import { Command } from "commander";
 
@@ -115,6 +115,24 @@ var requestConfig = {
       method: "POST",
       path: "/cli/requirements/update-dev-status"
     })
+  },
+  requirementArtifact: {
+    list: defineEndpoint({
+      method: "GET",
+      path: "/requirement-artifacts/list"
+    }),
+    create: defineEndpoint({
+      method: "POST",
+      path: "/requirement-artifacts/create"
+    }),
+    update: defineEndpoint({
+      method: "POST",
+      path: "/requirement-artifacts/update"
+    }),
+    delete: defineEndpoint({
+      method: "POST",
+      path: "/requirement-artifacts/delete"
+    })
   }
 };
 
@@ -136,6 +154,9 @@ import { fileURLToPath } from "url";
 var __dirname = dirname(fileURLToPath(import.meta.url));
 var CLI_TEMPLATE_DIR = resolve(__dirname, "../template");
 var WORKSPACE_APM_DIR = resolve(process.cwd(), ".apm");
+function requirementWorkitemsDir(requirementId) {
+  return join2(WORKSPACE_APM_DIR, "workitems", requirementId);
+}
 async function ensureLoggedConfig() {
   const cfg = await ensureApmConfig();
   if (!cfg.token) {
@@ -499,7 +520,7 @@ async function runPull(requirementId) {
   const cfg = await ensureLoggedConfig();
   const api = createApmApiClient(cfg);
   const data = await api.cliRequirements.pull({ requirementId });
-  const WORKITEMS_DIR = join4(WORKSPACE_APM_DIR, "workitems", requirementId);
+  const WORKITEMS_DIR = requirementWorkitemsDir(requirementId);
   await ensureDirExists(WORKITEMS_DIR);
   const req2 = data.requirement;
   const statusYaml = yamlStringify(
@@ -584,23 +605,118 @@ async function runUpdateStatus(requirementId, status) {
   console.log(JSON.stringify(data, null, 2));
 }
 
+// src/commands/upload-artifact.ts
+import { existsSync as existsSync2, readFileSync as readFileSync5, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+import { join as join6, relative, sep } from "path";
+var EXCLUDED_RELATIVE_PATHS = /* @__PURE__ */ new Set([
+  "defect.xml",
+  "prd.md",
+  "requirement-status.yaml",
+  "reviews.xml",
+  "testcase.xml"
+]);
+function toPosixRelative(root, absoluteFile) {
+  return relative(root, absoluteFile).split(sep).join("/");
+}
+function artifactTagFromRelPath(relPosix) {
+  const parts = relPosix.split("/");
+  const fileName = parts[parts.length - 1] ?? relPosix;
+  if (parts.length > 1) {
+    return parts[0] ?? fileName;
+  }
+  const dot = fileName.lastIndexOf(".");
+  return dot > 0 ? fileName.slice(0, dot) : fileName;
+}
+function* walkMarkdownFiles(dir) {
+  const names = readdirSync2(dir);
+  for (const name of names) {
+    if (name.startsWith(".")) continue;
+    const full = join6(dir, name);
+    const st = statSync2(full);
+    if (st.isDirectory()) {
+      yield* walkMarkdownFiles(full);
+      continue;
+    }
+    if (!st.isFile()) continue;
+    if (!name.toLowerCase().endsWith(".md")) continue;
+    yield full;
+  }
+}
+async function deleteAllArtifactsForRequirement(api, requirementId) {
+  const pageSize = 100;
+  let page = 1;
+  const rows = [];
+  while (true) {
+    const batch = await api.requirementArtifact.list({
+      requirementId,
+      page,
+      pageSize
+    });
+    rows.push(...batch.items);
+    if (batch.total === 0 || rows.length >= batch.total) break;
+    page += 1;
+  }
+  for (const row of rows) {
+    await api.requirementArtifact.delete({ artifactId: row.id });
+  }
+  return rows.length;
+}
+async function runUploadArtifact(requirementId) {
+  const cfg = await ensureLoggedConfig();
+  const api = createApmApiClient(cfg);
+  const root = requirementWorkitemsDir(requirementId);
+  if (!existsSync2(root)) {
+    console.error(
+      `[apm] \u76EE\u5F55\u4E0D\u5B58\u5728: ${root}
+\u8BF7\u5148\u6267\u884C: apm pull ${requirementId}`
+    );
+    process.exit(1);
+  }
+  const deleted = await deleteAllArtifactsForRequirement(api, requirementId);
+  console.log(`[apm] \u5DF2\u6E05\u7A7A\u9700\u6C42\u4EA7\u7269\u6587\u6863 ${deleted} \u6761`);
+  const paths = [...walkMarkdownFiles(root)];
+  let created = 0;
+  let skipped = 0;
+  for (const abs of paths) {
+    const relPosix = toPosixRelative(root, abs);
+    if (EXCLUDED_RELATIVE_PATHS.has(relPosix)) {
+      skipped += 1;
+      console.log(`[apm] \u8DF3\u8FC7\uFF08\u6392\u9664\u5217\u8868\uFF09: ${relPosix}`);
+      continue;
+    }
+    const content = readFileSync5(abs, "utf8");
+    const tag = artifactTagFromRelPath(relPosix);
+    await api.requirementArtifact.create({
+      requirementId,
+      tag,
+      fileName: relPosix,
+      content
+    });
+    created += 1;
+    console.log(`[apm] \u5DF2\u4E0A\u4F20\u4EA7\u7269: ${relPosix} (tag=${tag})`);
+  }
+  console.log(
+    `[apm] \u5B8C\u6210\uFF1A\u5220\u9664 ${deleted}\uFF0C\u65B0\u5EFA ${created}\uFF0C\u8DF3\u8FC7\uFF08\u6392\u9664\uFF09 ${skipped}\uFF0C\u5171\u626B\u63CF ${paths.length} \u4E2A Markdown \u6587\u4EF6`
+  );
+}
+
 // src/commands/deploy/backend.ts
 import path5 from "node:path";
 
 // src/commands/deploy/lib/apm-config.ts
-import { existsSync as existsSync2, readFileSync as readFileSync5 } from "node:fs";
+import { existsSync as existsSync3, readFileSync as readFileSync6 } from "node:fs";
 import { resolve as resolve3 } from "node:path";
 function loadApmConfig(options) {
   const p = resolve3(
     process.cwd(),
     options?.configPath ?? resolve3(WORKSPACE_APM_DIR, "apm.config.json")
   );
-  if (!existsSync2(p)) {
+  if (!existsSync3(p)) {
     console.error(`\u672A\u627E\u5230\u914D\u7F6E\u6587\u4EF6\uFF1A${p}`);
     process.exit(1);
   }
   try {
-    const raw = readFileSync5(p, "utf8");
+    const raw = readFileSync6(p, "utf8");
     return JSON.parse(raw);
   } catch (e) {
     console.error(`\u65E0\u6CD5\u89E3\u6790 apm.config.json\uFF1A${p}`, e);
@@ -634,18 +750,16 @@ function resolveBackendDeployFromApmConfig(cfg) {
     process.exit(1);
   }
   const remoteProtocol = protoRaw;
-  if (!Array.isArray(b.containerPortsMappings)) {
-    console.error(
-      "apm.config.json \u4E2D backendDeploy.containerPortsMappings \u987B\u4E3A\u975E\u7A7A\u6570\u7EC4"
-    );
-    process.exit(1);
-  }
-  const mappings = b.containerPortsMappings.map((x) => String(x).trim()).filter(Boolean);
-  if (mappings.length === 0) {
-    console.error(
-      "apm.config.json \u4E2D backendDeploy.containerPortsMappings \u987B\u81F3\u5C11\u5305\u542B\u4E00\u9879\u7AEF\u53E3\u6620\u5C04"
-    );
-    process.exit(1);
+  let mappings = [];
+  const rawPorts = b.containerPortsMappings;
+  if (rawPorts !== void 0 && rawPorts !== null) {
+    if (!Array.isArray(rawPorts)) {
+      console.error(
+        "apm.config.json \u4E2D backendDeploy.containerPortsMappings \u987B\u4E3A\u5B57\u7B26\u4E32\u6570\u7EC4\uFF08\u53EF\u4E3A\u7A7A\uFF0C\u7701\u7565\u5219\u4E0D\u52A0\u7AEF\u53E3\u6620\u5C04\uFF09"
+      );
+      process.exit(1);
+    }
+    mappings = rawPorts.map((x) => String(x).trim()).filter(Boolean);
   }
   return {
     name: req(b.name, "name").trim(),
@@ -691,7 +805,7 @@ import path4 from "node:path";
 import Docker from "dockerode";
 
 // src/commands/deploy/lib/backend-deploy/dockerode-client/connection-options.ts
-import { existsSync as existsSync3, readFileSync as readFileSync6 } from "node:fs";
+import { existsSync as existsSync4, readFileSync as readFileSync7 } from "node:fs";
 import path from "node:path";
 function asOptionalTlsBuffer(value) {
   if (typeof value !== "string") {
@@ -703,8 +817,8 @@ function asOptionalTlsBuffer(value) {
   if (normalized === "") {
     return void 0;
   }
-  if (existsSync3(normalized)) {
-    return readFileSync6(normalized);
+  if (existsSync4(normalized)) {
+    return readFileSync7(normalized);
   }
   const looksLikePath = /[\\/]/.test(normalized) || normalized.endsWith(".pem");
   if (looksLikePath) {
@@ -914,17 +1028,17 @@ var DockerodeClient = class {
 var createDockerodeClient = (config) => new DockerodeClient(config);
 
 // src/commands/deploy/lib/backend-deploy/dockerode-client/env.ts
-import { existsSync as existsSync4, readFileSync as readFileSync7, statSync as statSync2 } from "node:fs";
+import { existsSync as existsSync5, readFileSync as readFileSync8, statSync as statSync3 } from "node:fs";
 import path2 from "node:path";
 function loadEnvFromFile(envFilePath) {
   if (!envFilePath) {
     return {};
   }
   const targetPath = path2.resolve(envFilePath);
-  if (!existsSync4(targetPath) || !statSync2(targetPath).isFile()) {
+  if (!existsSync5(targetPath) || !statSync3(targetPath).isFile()) {
     return {};
   }
-  const raw = readFileSync7(targetPath, "utf-8");
+  const raw = readFileSync8(targetPath, "utf-8");
   const result = {};
   for (const line of raw.split(/\r?\n/)) {
     const normalized = line.trim();
@@ -1095,12 +1209,12 @@ function dockerPushImage(params, cwd) {
 }
 
 // src/commands/deploy/lib/backend-deploy/resolve-dockerfile.ts
-import { existsSync as existsSync5 } from "node:fs";
+import { existsSync as existsSync6 } 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 (!existsSync5(dockerfilePath)) {
+  if (!existsSync6(dockerfilePath)) {
     throw new Error(`Dockerfile \u4E0D\u5B58\u5728\uFF1A${dockerfilePath}`);
   }
   Logger.info("\u2713 Dockerfile \u5B58\u5728");
@@ -1229,16 +1343,16 @@ import { copyFile, readdir as readdir2, stat } from "node:fs/promises";
 import path7 from "node:path";
 
 // src/commands/deploy/lib/load-apm-dotenv.ts
-import { existsSync as existsSync6, readFileSync as readFileSync8 } from "node:fs";
-import { join as join6 } from "node:path";
+import { existsSync as existsSync7, readFileSync as readFileSync9 } from "node:fs";
+import { join as join7 } from "node:path";
 function loadApmDotEnvIfPresent() {
-  const p = join6(WORKSPACE_APM_DIR, ".env");
-  if (!existsSync6(p)) {
+  const p = join7(WORKSPACE_APM_DIR, ".env");
+  if (!existsSync7(p)) {
     return;
   }
   let text;
   try {
-    text = readFileSync8(p, "utf8");
+    text = readFileSync9(p, "utf8");
   } catch {
     return;
   }
@@ -1263,14 +1377,14 @@ function loadApmDotEnvIfPresent() {
 }
 
 // src/commands/deploy/lib/minio.ts
-import { statSync as statSync3 } from "node:fs";
+import { statSync as statSync4 } from "node:fs";
 import { readdir } 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 = statSync3(dir);
+    const st = statSync4(dir);
     return st.isDirectory();
   } catch {
     return false;
@@ -1300,7 +1414,7 @@ async function collectFiles(root) {
       if (e.isDirectory()) {
         await walk(abs, rel);
       } else if (e.isFile()) {
-        const st = statSync3(abs);
+        const st = statSync4(abs);
         out.push({
           absPath: abs,
           relativePath: rel.replace(/\\/g, "/"),
@@ -1597,8 +1711,8 @@ function registerDeployCommands(program) {
 function readCliVersion() {
   try {
     const dir = dirname2(fileURLToPath2(import.meta.url));
-    const pkgPath = join7(dir, "..", "package.json");
-    const pkg = JSON.parse(readFileSync9(pkgPath, "utf8"));
+    const pkgPath = join8(dir, "..", "package.json");
+    const pkg = JSON.parse(readFileSync10(pkgPath, "utf8"));
     return pkg.version ?? "0.0.0";
   } catch {
     return "0.0.0";
@@ -1626,6 +1740,11 @@ function buildProgram() {
   program.command("pull").description("GET /api/cli/requirements/pull\uFF0C\u540C\u6B65\u6570\u636E\u5230 .apm \u76EE\u5F55").argument("<requirementId>", "\u9700\u6C42 ID").action(async (requirementId) => {
     await runPull(requirementId);
   });
+  program.command("upload-artifact").description(
+    "\u5148\u6E05\u7A7A\u8BE5\u9700\u6C42\u5728\u5E73\u53F0\u4E0A\u7684\u4EA7\u7269\u6587\u6863\uFF0C\u518D\u5C06 .apm/workitems/<\u9700\u6C42ID> \u4E0B Markdown \u540C\u6B65\u4E0A\u53BB\uFF08\u6392\u9664 pull \u7CFB\u7EDF\u6587\u4EF6\uFF09"
+  ).argument("<requirementId>", "\u9700\u6C42 ID").action(async (requirementId) => {
+    await runUploadArtifact(requirementId);
+  });
   program.command("branch").description(
     "\u5207\u6362\u6216\u521B\u5EFA\u9700\u6C42\u5206\u652F feat/req-<ID>\uFF1A\u8FDC\u7AEF\u5B58\u5728\u5219\u62C9\u53D6\u6700\u65B0\uFF1B\u8FDC\u7AEF\u5C1A\u65E0\u8BE5\u5206\u652F\u4E14\u672C\u5730\u4E5F\u65E0\u540C\u540D\u5206\u652F\u65F6\uFF0C\u9700\u5DF2 login\uFF0C\u5E76\u7531\u5E73\u53F0\u6839\u636E\u5F53\u524D\u76EE\u5F55\u8DEF\u5F84\u89E3\u6790\u4ED3\u5E93\u57FA\u7EBF\u5206\u652F\u540E\u4ECE origin \u68C0\u51FA\u518D\u63A8\u9001\uFF1B\u6709\u672C\u5730\u672A\u63D0\u4EA4\u6539\u52A8\u65F6\u5728\u975E\u76EE\u6807\u5206\u652F\u5148 stash\uFF08\u4E0D\u81EA\u52A8\u6062\u590D\uFF09\uFF0C\u5728\u76EE\u6807\u5206\u652F\u5219\u5148 commit"
   ).argument("<requirementId>", "\u9700\u6C42 ID").option(

package/package.json

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

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

@@ -0,0 +1,132 @@
+---
+name: apm-deploy
+description: 路径相对仓库根 `<repoRoot>`；`.apm` 常被 gitignore，须直接 Read 或用 Shell 验磁盘，勿仅靠索引/搜索。用户仅提供需求 ID，读 deploy README 与 workitems（常用 requirement-status.yaml 的 env）后按 README 执行并汇总；不足则终止；@ 本技能、自动部署或「apm-deploy」时使用。
+---
+
+# APM 自动部署（按 `.apm/deploy/README.md`）
+
+- **部署怎么做**：**唯一**以仓库 **`.apm/deploy/README.md`** 为准（用户/团队维护）。文档有问题时**不得**猜着部署或绕过文档擅自执行生产级危险操作。
+- **参数从哪来**：用户**只需提供需求 ID**（`requirementId`）；其余上下文从 **`.apm/workitems/<requirementId>/`** 内按需 **Read**，**不向用户追问**环境名、分支等部署参数。
+
+---
+
+## 路径基准：项目（仓库）根目录 **`<repoRoot>`**
+
+本技能中出现的 **`.apm/...` 路径一律相对于 `<repoRoot>`**，**不得**相对于当前打开的文件、编辑器所在子目录、终端当前工作目录或其它隐含目录拼接。**找错文件视为执行错误**：若首次 Read 失败且路径明显可能在子目录下被误解析，**允许**仅因「路径基准错误」纠正一次——改为从 `<repoRoot>` 起算后重试该 Read。
+
+**如何确定 `<repoRoot>`**
+
+1. **优先**：当前 Cursor **工作区根**（Workspace Folder）即为本 Rush/Git 仓库根（通常含 **`rush.json`**、**`.apm/`**、**`apps/`** 等同级结构的那一层）。
+2. **若工作区误开在子目录**：向上查找同时存在 **`rush.json`**（或根 **`package.json`** + 单仓约定）且存在 **`.apm/`** 的目录，该目录即为 `<repoRoot>`；**不得**把仅有嵌套 `.apm` 副本的深层目录当作根（除非 README 明确声明）。
+3. **工具调用**：**Read / 编辑 / 执行 Shell** 时，凡本技能写明的路径均写成 **从 `<repoRoot>` 起的相对路径**（例如 `.apm/deploy/README.md`、`.apm/workitems/<requirementId>/requirement-status.yaml`）。需要绝对路径时，用 `<repoRoot>` 拼接，**不要**使用 `./apps/.../.apm/...` 这类错误前缀。
+4. **Shell**：默认 **`cwd` = `<repoRoot>`**；仅当 README **明确**要求 `cd` 到子目录时再切换，执行完若需继续本技能后续步骤应回到 `<repoRoot>` 或严格按 README 指定目录执行下一步。
+
+### `.gitignore`：被忽略的目录仍可能在磁盘上
+
+**`.apm/`**（及其中 `deploy`、`workitems` 等）在多数仓库里会被 **`.gitignore`**，因此：
+
+- **语义搜索、代码索引、默认排除 gitignore 的 ripgrep/grep** 往往**扫不到**这些路径 → **绝不能**因为「搜不到」就认定文件不存在或跳过本技能。
+- **必须以磁盘为准**：对 `.apm/deploy/README.md`、`.apm/workitems/<requirementId>/...` 使用 **Read 工具并给出从 `<repoRoot>` 起的完整相对路径**（不要先依赖「在全仓搜索 `.apm`」来发现路径）。
+- 若 **Read** 报错且不确定是真不存在还是被工具策略拦截：在仓库根执行 Shell（**`cwd`** = `<repoRoot>`），例如 **`test -e .apm/deploy/README.md`**、**`ls .apm/workitems/<requirementId>`**（读磁盘，**不依赖** `git ls-files`）。
+- **`git status` 不列出未跟踪/被 ignore 的文件是正常的**，不代表本地没有该文件。
+
+---
+
+## 输入与前置
+
+| 字段 | 规则 |
+| --- | --- |
+| **`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 要什么 / 已查了哪些路径 / 缺什么」。 |
+
+---
+
+## 流程总览
+
+| 序号 | 步骤 | 说明 |
+| --- | --- | --- |
+| 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：阅读 `.apm/deploy/README.md`
+
+1. 在 **`<repoRoot>`** 下 **Read**（相对路径）：`.apm/deploy/README.md`。路径**必须**以仓库根为前缀，**禁止**从子项目目录推导同名路径。**禁止**仅用 codebase 搜索来找该文件（易被 gitignore 漏掉）；**直接 Read** 上述路径。
+2. **文件不存在或不可读**：先用上节「`.gitignore`」方式区分是真不存在还是路径基准错误；确认路径正确且磁盘上仍无文件时**立即停止**本流程。在对话中明确写出：路径、错误（如 ENOENT、权限），**不要**尝试默认部署命令或猜测流程。
+3. **存在则读全文**（含其指向的同级/子路径文档时：若 README 写明「须同时阅读某文件」，则 **Read** 该文件；若链断裂或文件缺失，按「文档验收 → 文档缺陷」处理）。
+
+---
+
+## 步骤 2：文档验收（门禁，失败即终止）
+
+在阅读完成后、加载工作项上下文与执行任何部署命令前，必须自检下列项。**任一条不满足**：**不得执行部署**；在对话中**逐条列出问题**（引用 README 片段或章节标题即可），然后**终止本技能流程**。
+
+| 验收项 | 不满足时的表现（示例） |
+| --- | --- |
+| **可执行性** | 缺少前置条件（账号、CLI、密钥、目标环境）、缺少具体命令或顺序混乱到无法唯一确定下一步。 |
+| **一致性** | 前后矛盾（例如同一环境两套冲突命令）、版本/工具要求互相打架。 |
+| **完整性** | 引用不存在的脚本/配置文件、Broken link、关键占位符未替换说明。 |
+| **清晰性** | 读完仍**不知道**该如何在本仓库完成一次部署（步骤含糊到无法落地）。 |
+
+**特别约定（用户维护文档）**
+
+- 文档若有错别字、过时链接、危险指令描述不清等：**直接报出问题**，**不**替用户「纠正文档后继续」。
+- **阅读之后仍然不知道如何部署**：视为「清晰性」不满足，**终止**，说明「依据当前 README 无法确定可执行步骤」及缺失项。
+- **不要**因文档差而自行检索互联网或套用其它项目的部署习惯来代替 README。
+
+---
+
+## 步骤 3：加载工作项上下文
+
+仅在「文档验收」**全部通过**后执行。
+
+1. 确认目录 **`<repoRoot>/.apm/workitems/<requirementId>/`**（工具相对路径：`.apm/workitems/<requirementId>/`）存在；不存在则**终止**（不要假想 ID）。
+2. 根据 README 描述的占位符或变量（如「目标环境」「部署 env」），**Read** 该目录内相应文件（路径同样锚定 `<repoRoot>`）；**默认优先** **`requirement-status.yaml`**，提取 **`env`**（及 README 明确要求的其它字段）。
+3. 若 README 需要的某项信息在工作项内**不存在或未填写**：**终止**，说明缺失字段与文件路径；**不**请用户在对话里补充（用户约定仅提供需求 ID）。
+
+---
+
+## 步骤 4：按文档执行
+
+仅在「工作项上下文」**已满足 README 对参数的要求**后执行。
+
+1. **严格对照** README：顺序、工作目录（若文档指定 `cd`）、环境变量、所用 CLI（如 `rush`、`docker`、`kubectl` 等）均以文档为准；将步骤 3 得到的 **`env` 等**按 README 约定注入命令或环境（禁止凭猜测填值）。**默认在 `<repoRoot>` 执行**；遵守本仓库 **AGENTS.md**（如 Rush 安装/构建约定），但**不**执行 README **未写出**的额外构建/发布步骤。
+2. **每条命令**记录：是否成功、退出码或关键输出摘要、失败时的 stderr（可截断至可读长度）。
+3. **失败处理**：与 **Guardrails** 一致——默认**失败即终止**后续部署步骤，在表格与摘要中写明失败命令与原因；**不因网络抖动等做无文档依据的多轮重试**（除非 README **明确**要求重试策略）。
+4. **安全**：若 README 要求确认交互（如 `Are you sure?`），按文档处理；文档要求人工审批而 Agent 无法完成时，执行到该步即停止，并标明「需人工完成」。
+
+---
+
+## 步骤 5：对用户回复（状态汇总）
+
+回复中**必须包含**一张汇总表，建议结构：
+
+| 阶段 | 内容 | 结果 |
+| --- | --- | --- |
+| 阅读 | `.apm/deploy/README.md`（及 README 要求阅读的附属文档） | 成功 / 失败（原因） |
+| 验收 | 文档是否足以执行 | 通过 / **未通过**（列具体问题） |
+| 上下文 | `.apm/workitems/<requirementId>/`（含 `requirement-status.yaml` / `env` 等） | 成功 / **失败**（缺文件或缺字段） |
+| 执行 | 按 README 执行的命令或步骤摘要（可按行拆分） | 每步 成功 / 失败 / 跳过 / 需人工 |
+| 结论 | 部署是否完成 README 所述目标 | 是 / 否 / 未执行（门禁或上下文未过） |
+
+若门禁或上下文未通过：**不要**出现「已尝试部署」的误导性表述；表格中「执行」阶段填 **未执行（原因）**。
+
+**可选**：表格外一两句话概括当前阻塞点或已成功完成的范围。
+
+---
+
+## Guardrails
+
+- **gitignore 不等于不存在**：`.apm` 下文件可能不入 Git 索引；**禁止**用「搜索无结果」代替 **Read** 或磁盘校验。
+- **路径锚定 `<repoRoot>`**：凡 `.apm/deploy`、`.apm/workitems` 等路径**仅**相对仓库根；**禁止**因当前焦点在 monorepo 内某一子目录而在错误基底上拼路径。
+- **文档优先**：无合格 `.apm/deploy/README.md` 解读结果，**不部署**。
+- **用户只给 ID**：除 **`requirementId`** 外，**不依赖**用户在对话中口头提供环境、密钥说明等；这些信息须来自 **工作项目录** 或 README 已写明的本地/CI 约定。缺数据则**终止并写明缺口**，而非让用户「现场补一句」。
+- **失败即终止**：在文档与上下文明确的前提下，任一步骤失败 → 停止后续步骤，仅记录状态；**例外**仅允许 Agent **自身**错误（如错目录）纠正后对**同一步**再试一次，仍失败则终止。
+- **不臆造**：README 未写的命令、环境、目标集群/命名空间，**不补充**；工作项 YAML **未提供**的字段**不得**编造。
+- **不报假成功**：命令失败或未完成 README 目标时，结论必须为「否」或等价表述。

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

@@ -1,6 +1,6 @@
 ---
 name: apm-dev
-description: 按需求 ID 全自动开发：切分支、读 PRD、按改动规模选择 Quick 或 Spec 路径实现代码、提交并推送；子 Agent 承担编码与规划落地；当用户 @ 本技能、提及全自动开发或「apm-dev」时使用。
+description: 按需求 ID 全自动开发：切分支、读 PRD、按改动规模选择 Quick 或 Spec 路径实现代码、提交并推送、同步产物；子 Agent 承担编码与规划落地；当用户 @ 本技能、提及全自动开发或「apm-dev」时使用。
 ---
 
 # APM 全自动开发（按需求 ID）
@@ -38,7 +38,8 @@ instruction 子文件随该目录类推（如 `.apm/skills/apm-propose/propose-i
 | 3 | **Quick 开发** | 仅当判定为「改动成本较小」时执行；由 **子 Agent** 写代码 |
 | 4 | **Spec 开发** | 仅当判定为「改动成本较大」时执行；先 **apm-propose** 再 **apm-apply-change**，均由 **子 Agent** 按对应技能执行 |
 | 5 | **提交与推送** | `git` 提交并 `push`，工作区干净 |
-| 6 | **对用户回复** | **一张 Markdown 表格**汇总各步执行结果（见文末模板） |
+| 6 | **同步产物** | `apm upload-artifact <requirementId>`，将工作项目录内 Markdown 产物同步到平台 |
+| 7 | **对用户回复** | **一张 Markdown 表格**汇总各步执行结果（见文末模板） |
 
 ---
 
@@ -118,9 +119,23 @@ instruction 子文件随该目录类推（如 `.apm/skills/apm-propose/propose-i
 
 ---
 
-## 步骤 6：对用户回复（表格）
+## 步骤 6：同步产物
 
-对用户回复 **必须包含一张 Markdown 表格**，汇总 **步骤 1～5**（步骤 6 为呈现表格本身，可不单独成行）。表头建议：
+在**仓库/工作区根目录**（与步骤 1、5 一致）执行：
+
+```bash
+apm upload-artifact <requirementId>
+```
+
+1. 该命令会**先清空**平台上该需求的产物文档，再将 `.apm/workitems/<requirementId>/` 下符合条件的 Markdown 重新上传（排除 `prd.md`、状态 YAML、reviews/defect/testcase 等 pull 系统文件；详见 CLI 行为）。
+2. 若本地未放置需同步的 `.md` 产物，仍会清空平台侧产物；若有文档仅在仓库其它路径，须先复制或生成到工作项目录再执行。
+3. 将命令是否成功、上传条数或错误摘要写入表格。
+
+---
+
+## 步骤 7：对用户回复（表格）
+
+对用户回复 **必须包含一张 Markdown 表格**，汇总 **步骤 1～6**（步骤 7 为呈现表格本身，可不单独成行）。表头建议：
 
 | 步骤 | 内容 | 结果 |
 | --- | --- | --- |
@@ -129,6 +144,7 @@ instruction 子文件随该目录类推（如 `.apm/skills/apm-propose/propose-i
 | 3 | Quick 开发（子 Agent） | 成功 / 失败 / **跳过** |
 | 4 | Spec：apm-propose → apm-apply-change（子 Agent） | 成功 / 失败 / **跳过**；可注明子步骤 |
 | 5 | commit & push；工作区干净 | 成功 / 失败（原因） |
+| 6 | `apm upload-artifact <requirementId>` | 成功 / 失败（原因） |
 
 **可选**：在表格外增加**简短**一句话摘要（例如当前分支名、阻塞点）；若用户此前约定「仅表格」，则可仅输出表格。
 
@@ -136,7 +152,7 @@ instruction 子文件随该目录类推（如 `.apm/skills/apm-propose/propose-i
 
 ## Guardrails
 
-- **失败即终止**：在用户提供的 **`requirementId`** 等参数合法、命令与路径按本技能书写的前提下，任一步骤（含 `apm branch`、`apm pull`、读文件、子 Agent、`git`）**一旦失败**：**停止后续所有步骤**，仅在表格中记录失败步骤与原因；**不要**为登录、依赖、网络、命令结果等做**多次**或「轮番」重试。
+- **失败即终止**：在用户提供的 **`requirementId`** 等参数合法、命令与路径按本技能书写的前提下，任一步骤（含 `apm branch`、`apm pull`、`apm upload-artifact`、读文件、子 Agent、`git`）**一旦失败**：**停止后续所有步骤**，仅在表格中记录失败步骤与原因；**不要**为登录、依赖、网络、命令结果等做**多次**或「轮番」重试。
 - **例外（Agent 自身失误）**：若失败明显由执行 Agent **用错工作目录、读错/漏写路径** 等导致，**允许**纠正 `cwd` 或路径后**仅对该失败步骤再执行一次**；纠正后仍失败则**立即终止**，不再扩展尝试。
 - **不要**在无 `prd.md`（且 `apm pull` 后仍无）的情况下编造需求实现。
 - **子 Agent** 提示中须带 **`requirementId`** 与仓库根路径意识，避免改错工作树。

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

@@ -3,10 +3,20 @@ name: apm-refine
 description: 根据需求 ID 读取工作项 prd.md 与 reviews.xml，按「修订稿」标准结构（修订说明、背景与目标、范围、需求点、非功能、待确认/问题与局限等）润色并回写，再执行 apm refine 同步平台；当用户在对话中 @ 本技能或提出需求润色时使用。
 ---
 
-# APM 需求润色（PRD 标准化）
+# APM 需求润色
 
 用户仅提供 **需求 ID**（workitem id）。**缺 ID 时索要，不猜测。**
 
+## 合并原则
+
+1. **正文依据 = 需求原文 + 补充信息**：只把用户在补充信息中**明确**要体现的内容（补充、修改、删除、拍板口径）合并进修订稿；用户没说到的，**保持原文或不写**，**不自作主张**补需求、不替用户「落实」评审建议。
+2. **未回应的评审**：不列入「待确认」、不改成待办、不推断「仍有问题」；视为用户未要求在本次修订中处理（可能无此问题、暂不改、或评审误解）。
+3. **评审的定位**：仅辅助理解补充信息在回应什么；补充信息与评审不一致时，**以补充信息为准**。
+4. **消除重复**：同一议题在原文与补充信息中多处出现时，合并为**一处**表述。
+5. **可追溯（轻量）**：可选「修订说明」概括相对原文的变化，且**只写补充信息实际带来的变化**，不罗列未采纳的评审。
+6. **与仓库一致**：对照 `AGENTS.md`、`.apm/product-capability-inventory` 等，避免修订稿与用户已确认表述冲突；**禁止**用代码路径当需求论据。
+7. **图片引用保持原样**：若原文含图片（如 `<img ...>`），在修订稿中直接保留对应 `img` 标签原文；不要改写成“图片见原始文档”等占位说明。
+
 ## 强制执行顺序（四步）
 
 ### 步骤 1：读取 `prd.md` 与 `reviews.xml`
@@ -29,8 +39,9 @@ description: 根据需求 ID 读取工作项 prd.md 与 reviews.xml，按「修
 2. **落盘结构：标准「修订稿」模板（写入 `prd.md` 须遵循）**  
    使用 **Read** 读取与 `SKILL.md` 同目录的 **[apm-refine-template.md](./apm-refine-template.md)**，按其中**修订稿骨架**与章节说明组织正文（默认全文润色形态）。执行本技能时**须**读取该文件，不以记忆代替。
 
-   **改动与边界（仍须满足）**  
-   - **修订说明**中的「本次合并的要点」须**分点**写清本次相对原文的变更与**范围边界**（影响面、不做的事）。若改动项多于 3 条，可在「修订说明」后续追加小节 **「相对原文的变更」** 继续分点罗列。  
+   **改动与边界（仍须满足）**
+
+   - **修订说明**中的「本次合并的要点」须**分点**写清本次相对原文的变更与**范围边界**（影响面、不做的事）。若改动项多于 3 条，可在「修订说明」后续追加小节 **「相对原文的变更」** 继续分点罗列。
    - 全文润色时**不要机械留空标题**：无内容的章节可删除（如无非功能则不写该章），但**背景与目标 / 范围 / 需求说明**一般应完整可读。
 
    **局部替换（不必强行铺满模板）**  
@@ -55,21 +66,15 @@ apm refine <需求ID>
 
 ### 步骤 5：回复用户
 
-对用户可见回复 **仅限一张 Markdown 表格**，**仅填写步骤 1～4 每步的执行状态**。**不得**在表格外输出任何其他内容（不粘贴 prd 正文、不另写摘要或提示）。
+对用户可见回复 **仅限一张 Markdown 表格**，**仅填写步骤 1 ～ 4 每步的执行状态**。**不得**在表格外输出任何其他内容（不粘贴 prd 正文、不另写摘要或提示）。
 
 建议表头（每行「状态」仅填 **成功** / **失败** / **跳过**；失败时可加简短原因，如 `失败：文件不存在`）：
 
-| 步骤 | 状态 |
-|------|------|
-| 1. 读取 `prd.md` 与 `reviews.xml` |  |
-| 2. 润色为「标准需求文档」 |  |
-| 3. 回写 `prd.md` |  |
-| 4. 执行 `apm refine <需求ID>` |  |
+| 步骤                              | 状态 |
+| --------------------------------- | ---- |
+| 1. 读取 `prd.md` 与 `reviews.xml` |      |
+| 2. 润色为「标准需求文档」         |      |
+| 3. 回写 `prd.md`                  |      |
+| 4. 执行 `apm refine <需求ID>`     |      |
 
 ---
-
-## 内部编排要点
-
-**通读 prd → Read [apm-refine-template.md](./apm-refine-template.md) →（若有）解析 reviews 与 reply → 按修订稿骨架写入 → 写回 `prd.md` → `apm refine`。**
-
-唯 **对用户可见** 的回复遵守上文「步骤 5」的表格约束。

package/template/skills/apm-refine/apm-refine-template.md

@@ -1,28 +1,20 @@
-# APM 需求「修订稿」落盘模板
-
-由 **`apm-refine`** 技能引用：润色并写回 `.apm/workitems/<需求ID>/prd.md` 时，按下列骨架组织正文。
-
-文中 **「补充信息」** 指 **`reviews.xml`** 中的评审意见与 `reply`（及评审记录中已写明的事实），不单指对话里的用户发言。
-
----
-
 # [需求标题]（修订稿）
 
-**修订说明**（可选，但在依据评审合并或全文润色时**建议必备**）
+**修订说明**（可选）
 
-- 基于评审日期 / 评审记录：简要一句（若有可溯源的 review id、模型名可写）
-- 本次合并的要点：1～3 条 bullet（写清相对原文合并了什么、边界在哪）
+- 基于评审日期 / 评审记录：简要一句
+- 本次合并的要点：1～3 条 bullet
 
 ---
 
 ## 背景与目标
 
-（合并原文与补充信息中明确补充/修正的表述）
+（合并原文与用户补充信息中明确补充/修正的表述）
 
 ## 范围
 
 - **包含**：
-- **不包含**：（若补充信息或原文中明确收窄/排除）
+- **不包含**：（若**补充信息**或原文中明确收窄/排除）
 
 ## 需求说明
 
@@ -36,12 +28,12 @@
 
 （性能、权限、兼容、埋点等——仅当原文或补充信息涉及）
 
-## 待确认（可选；整节省略）
+## 待确认
 
-仅当**原文、`reviews` 的 reply 或评审记录中**明确留下未拍板事项、或写明「待定」「再议」等时列出：
+仅当**用户自己在补充信息里**留下未拍板事项、或写明「待定」「再议」等时列出（可选章节，可整节省略）：
 
-- [ ] （未决口径摘要）— 用户原话或简要归纳
+- [ ] （用户未决口径摘要）— 用户原话或简要归纳
 
-## 问题与局限（按条件出现；与「待确认」区分）
+---
 
-**待确认**承载「材料里用户/评审已标明的未决项」。本节承载润色过程中发现的：**评审缺失或 XML 不可解析、reviews 与 prd 冲突、关键口径无法从现有材料唯一确定**等；**禁止**为此向用户追问，仅列事实与风险。
+若用户只需要「替换某几段」而非全文，可仅在回复中给出**修改后的完整段落** + 简短「相对原文的变更摘要」，不必机械填满所有章节。

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

@@ -1,27 +1,46 @@
 ---
 name: apm-review
-description: 根据需求 ID 读取工作项 prd.md，对照代码做需求评审；评审立场依可见代码而定（仅前台 / 仅后台 / 全栈）；提交到评论的正文用 Markdown 拉出层次与重点，业务白话、避免代码与工程术语；结合代码交付面过滤与现状无关的空头边界质疑，当用户在对话中 @ 本技能时使用。
+description: 结合本仓库上下文对需求做结构化评审，只有当用户主动提及该技能时才可被使用，该技能调用依赖需求ID。
 ---
 
-# APM 需求评审（对照代码）
+# 需求评审
 
 用户仅提供 **需求 ID**（workitem id）。缺 ID 时索要，不猜测。
 
-**评审规范与评审模板**（受众与用语、立场与范围、书写约束、正文示例等）见同目录 **[apm-review-reference.md](./apm-review-reference.md)**；执行本技能时须按该文件撰写评审正文。
+## 评审原则
 
-## 强制执行顺序（三步）
+1. **产品视角优先**：用户侧影响、业务闭环、风险与待确认点；避免晦涩技术术语堆砌。
+2. **与仓库对齐（能力边界）**：阅读 `AGENTS.md`、子项目说明、`.apm/product-capability-inventory` 等与需求相关的部分，判断需求是否与既有能力/术语冲突、是否超出现有边界。**禁止**用「某文件某行」证明 PRD 对错；**禁止**根据代码**猜测** PRD 未写清的口径——口径不清应归入「问题」待产品澄清。
+3. **业务合理性（按需）**：结合仓库可读的业务/产品上下文，判断需求是否想清楚、方案是否当下较优、是否与业务目标或流程冲突。**仅当**不合理、需再商榷或非当下较优时，才写 `- **业务合理性：**:`；合理则**不写**该字段。
+4. **信息完备与落地（互斥规则）**：
+   - 仅当 PRD/需求信息**不足以**形成开发可执行描述（关键落点、口径、范围、汇总规则等无法确定）时，写 `- **问题：**`，此时**不写**可行性与风险点。
+   - 若已足以判断「可以实现」（非关键细节不阻塞落地），写 `- **可行性：**`（成本低/中/高 + 精简说明）；影响面大时再追加 `- **风险点：**`。
+5. **澄清优先但不泛问**：不阻塞落地则不提问；不问可推断的琐碎问题。
+6. **隐性知识沉淀可执行**：对用户单独输出的每条沉淀建议应能回答「在仓库里补什么、能消除哪类隐性歧义」；若本次未发现值得沉淀的差异点，仍须给出一句结论（例如「未发现与通用假设显著偏离、需单独成文的隐性规则」）。
+
+
+## 执行步骤
 
 ### 步骤 1：读取 `prd.md`
 
 1. 使用 **Read** 读取 `.apm/workitems/<需求ID>/prd.md`。
 2. 若 Read **失败**（文件不存在或无法读取）：本步骤记为失败，**终止**，不执行步骤 2、3。
 
-### 步骤 2：撰写评审、落盘、推送、清理
+### 步骤 2：读代码
+阅读仓库源码以及 `.apm/product-capability-inventory` 中与需求相关的条目；不展开无关模块代码。
+
+### 步骤 3：评审
+1. **拆条**：多条诉求时拆成 `### 需求点 1..N`，每条独立走完「业务合理性（可选）→ 问题 或 可行性（+风险）」逻辑。
+
+2. **成文（仅评审模板）**：按 `output-template.md` 拼出写入 comment 的 Markdown（顶格可加 `### 评审人` + 当前模型名）；**不含**「隐性知识沉淀」段落；
 
-1. 使用 **Read** 读取 [apm-review-reference.md](./apm-review-reference.md)（与 `SKILL.md` 同目录），并依其中规范对照代码撰写 **Markdown 评审正文**：**只写确实存在的问题**；用「需求背景 / 需求范围 / 交互与功能要求第 X 节 / 非目标」等文档自有结构**点名条款**，不先单独铺一节「对用户意图的理解」。撰写前须完成代码检索并锁定本轮**评审立场**（见 reference 中「评审立场」），正文内容与措辞须与该立场一致，**不得超越可见范围下断定**。
-2. 使用 **Write** 将正文写入**临时文件**，路径建议使用**绝对路径**，例如 `/tmp/apm-review-<需求ID>.md`（避免与相对 cwd 混淆）。
-3. 在项目根目录下执行：`apm comment <需求ID> --file=<临时文件绝对路径> --model=<评论使用的模型名称>`。
-4. 命令结束后 **删除临时文件**（**Delete** 工具或 `rm`），无论命令成功或失败都尽量清理（失败时保留文件仅供用户排错——技能默认仍删除，若需保留应在表格备注中说明）。
+3. 使用 **Write** 将正文写入**临时文件**，路径建议使用**绝对路径**，例如 `/tmp/apm-review-<需求ID>.md`。**Markdown 评审正文**：**只写确实存在的问题**；用「需求背景 / 需求范围 / 交互与功能要求第 X 节 / 非目标」等文档自有结构**点名条款**（半句锚定即可），不先单独铺一节「对用户意图的理解」，**不写与 `prd-review` 类似的整条「需求描述」复述**。撰写前须完成代码检索并锁定本轮**评审立场**（见 reference 中「评审立场」），正文内容与措辞须与该立场一致，**不得超越可见范围下断定**。
+
+4. **自检**：每条是否都有「需求描述」；「问题」与「可行性/风险」是否互斥符合 `output-template.md`；是否误引代码路径作论据；comment 全文是否**未混入**隐性知识段落。
+
+5. **提交评审记录**：在项目根目录下执行：`apm comment <需求ID> --file=<临时文件绝对路径> --model=<评论使用的模型名称>`。
+
+6. 命令结束后 **删除临时文件**（**Delete** 工具或 `rm`），无论命令成功或失败都尽量清理（失败时保留文件仅供用户排错——技能默认仍删除，若需保留应在表格备注中说明）。
 
 ### 步骤 3：回复用户
 
@@ -33,6 +52,4 @@ description: 根据需求 ID 读取工作项 prd.md，对照代码做需求评
 |------|------|------|
 | 1. 读取 prd.md | 成功 / 失败 | 例如实际读取路径；失败时写错误原因 |
 | 2. 评审与 comment | 成功 / 失败 | 临时文件路径（已删可写「已清理」）；`apm comment` 退出情况或 API 返回摘要；**建议**注明本轮评审立场（仅前台 / 仅后台 / 全栈） |
-| 3. 清理临时文件 | 成功 / 失败 | — |
-
-内部编排：**通读 prd → 检索并对照与需求相关的代码 → 判定本轮可见范围（仅前台 / 仅后台 / 全栈）并选定评审立场 → 将技术发现改写为业务白话 → 只输出有问题之处**；唯**对用户输出**遵守上表约束。
+| 3. 清理临时文件 | 成功 / 失败 | — |

package/template/skills/apm-review/output-template.md

@@ -0,0 +1,43 @@
+### 需求点 1
+
+- **需求描述：**: （一句话概括要做什么，产品视角）
+  - （关键点 1）
+  - （关键点 2）
+
+### 需求点 2
+
+- **需求描述：**: （一句话概括要做什么，产品视角）
+
+- **问题：**
+  - （问题 1：必须澄清“页面/表/口径/范围/汇总规则”等）
+  - （问题 2）
+  - （问题 3）
+
+### 需求点 3
+
+- **需求描述：**: （一句话概括要做什么，产品视角）
+
+- **可行性：**
+  - 成本：低/中/高
+  - （在不引入猜测的前提下，说明成本对应的业务/口径/环节调整）
+
+### 需求点 4
+
+- **需求描述：**: （一句话概括要做什么，产品视角）
+- **可行性：**
+  - 成本：中/高
+  - （在不引入猜测的前提下，说明成本对应的业务/口径/环节调整）
+- **风险点：**
+  - （风险 1：可能影响的不止是展示文案，例如统计口径/汇总逻辑/跨模块联动等）
+  - （风险 2）
+
+### 需求点 5（业务合理性：仅不合理时出现）
+
+- **需求描述：**: （一句话概括要做什么，产品视角）
+- **业务合理性：**
+  - （为何不合理/与用户目标或现有业务冲突/用户方案非当下较优；可写更可取的替代思路或需产品先拍板的点）
+- **可行性：**
+  - 成本：低/中/高
+  - （仍可在指出业务问题的同时评估落地成本；若信息仍不足以落地，则改用「需求点 2」结构：业务合理性 + **问题**，不出现可行性/风险点）
+
+字段顺序与并存：`需求描述` 始终第一；`业务合理性` 仅在不合理时出现在 `需求描述` 之后。其后仍遵循「有问题则只写问题，无问题则写可行性（可加风险点）」。

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

@@ -1,142 +0,0 @@
----
-name: apm-dev
-description: 按需求 ID 全自动开发：切分支、读 PRD、按改动规模选择 Quick 或 Spec 路径实现代码、提交并推送；子 Agent 承担编码与规划落地；当用户 @ 本技能、提及全自动开发或「apm-dev」时使用。
----
-
-# APM 全自动开发（按需求 ID）
-
-用户给出 **需求 ID**（`requirementId`，与工作项目录名一致）。**缺 ID 时索要，不猜测。**
----
-
-## 输入
-
-| 字段 | 规则 |
-| --- | --- |
-| **`requirementId`** | **必填**。与 `.apm/workitems/<requirementId>/` 目录名一致。 |
-
----
-
-## 技能文件定位（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/skills`），并停止步骤 4。
-
----
-
-## 流程总览
-
-| 序号 | 步骤 | 说明 |
-| --- | --- | --- |
-| 1 | **切分支** | 在仓库根目录执行 `apm branch <requirementId>` |
-| 2 | **读 PRD + 成本评估** | **Read** `.apm/workitems/<requirementId>/prd.md`，判定 Quick / Spec |
-| 3 | **Quick 开发** | 仅当判定为「改动成本较小」时执行；由 **子 Agent** 写代码 |
-| 4 | **Spec 开发** | 仅当判定为「改动成本较大」时执行；先 **apm-propose** 再 **apm-apply-change**，均由 **子 Agent** 按对应技能执行 |
-| 5 | **提交与推送** | `git` 提交并 `push`，工作区干净 |
-| 6 | **对用户回复** | **一张 Markdown 表格**汇总各步执行结果（见文末模板） |
-
----
-
-## 步骤 1：`apm branch`
-
-1. 在**仓库/工作区根目录**执行：
-
-   ```bash
-   apm branch <requirementId>
-   ```
-
-2. 记录：命令是否成功、简要输出或错误信息（写入最终表格）。**失败则按「Guardrails → 失败即终止」处理**，不为此命令做多轮重试（除非属 Agent 用错目录等可纠正失误）。
-
----
-
-## 步骤 2：读取 PRD 并评估改动成本
-
-1. **Read** 全文：`.apm/workitems/<requirementId>/prd.md`。
-2. 若无法读取：在仓库根目录执行 **`apm pull <requirementId>`**（同步工作项），再 **Read** 一次；仍失败则**停止后续实现**，仅在表格中标记失败原因。
-3. **不**为评估向用户发起追问；信息不足时倾向 **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`；若启动新子 Agent，在委派提示中写明 **`requirementId`**、工作项路径、以及「实现须严格对照 PRD，改动范围最小化」。
-2. 使用 **Task** 工具，`subagent_type: generalPurpose`，**readonly: false**，委派子 Agent：
-   - 自行 **Read** `.apm/workitems/<requirementId>/prd.md`（若会话未带全文）。
-   - 按 PRD 直接改代码；遵守本仓库构建与依赖约定（AGENTS.md）。
-   - 完成后在返回中说明：改了哪些路径、如何对照验收、是否通过本地可执行的检查（若子 Agent 跑了 `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/workitems/<requirementId>/` 生成 **proposal、design、specs、tasks** 等工件（顺序与依赖以 SKILL 为准）。
-3. **子 Agent B（实现）**：待 A 成功落盘后，再 Task `generalPurpose`，提示其自行 **Read** `.apm/skills/apm-apply-change/SKILL.md` 并完整遵循：按 **`tasks.md`** 驱动实现与勾选；遵守该技能中的停止条件与 commit 约定。
-4. 若 **apm-propose** 未产出可用 **`tasks.md`**，不得强行进入 **apm-apply-change**；表格中标记阻塞原因。
-5. 表格中步骤 3 填 **跳过**；步骤 4 分两行或合并一行写清 propose / apply 状态（见表格模板）。
-
----
-
-## 步骤 5：提交并推送
-
-在仓库根目录执行（可用一条复合命令或分步；以实际仓库远程为准）：
-
-1. `git status`：确认变更范围。
-2. 若有未提交变更：`git add -A`，然后 `git commit -m "feat(req-<requirementId>): <简短说明>"`（说明应概括本轮需求实现；若子 Agent 已按任务多次 commit，则可能无需新 commit，以 `status` 为准）。
-3. `git push`：推送到当前分支对应远程（首次必要时 `-u origin <branch>`）。
-4. 再次 `git status`：**须为干净工作区**（无未提交、未跟踪的重要残留；若有应记录为失败或说明例外）。
-
-将命令结果、最终分支名、是否已 push、工作区是否干净写入表格。
-
----
-
-## 步骤 6：对用户回复（表格）
-
-对用户回复 **必须包含一张 Markdown 表格**，汇总 **步骤 1～5**（步骤 6 为呈现表格本身，可不单独成行）。表头建议：
-
-| 步骤 | 内容 | 结果 |
-| --- | --- | --- |
-| 1 | `apm branch <requirementId>` | 成功 / 失败（原因） |
-| 2 | 读 PRD + 成本评估 | Quick 或 Spec；一行理由 |
-| 3 | Quick 开发（子 Agent） | 成功 / 失败 / **跳过** |
-| 4 | Spec：apm-propose → apm-apply-change（子 Agent） | 成功 / 失败 / **跳过**；可注明子步骤 |
-| 5 | commit & push；工作区干净 | 成功 / 失败（原因） |
-
-**可选**：在表格外增加**简短**一句话摘要（例如当前分支名、阻塞点）；若用户此前约定「仅表格」，则可仅输出表格。
-
----
-
-## Guardrails
-
-- **失败即终止**：在用户提供的 **`requirementId`** 等参数合法、命令与路径按本技能书写的前提下，任一步骤（含 `apm branch`、`apm pull`、读文件、子 Agent、`git`）**一旦失败**：**停止后续所有步骤**，仅在表格中记录失败步骤与原因；**不要**为登录、依赖、网络、命令结果等做**多次**或「轮番」重试。
-- **例外（Agent 自身失误）**：若失败明显由执行 Agent **用错工作目录、读错/漏写路径** 等导致，**允许**纠正 `cwd` 或路径后**仅对该失败步骤再执行一次**；纠正后仍失败则**立即终止**，不再扩展尝试。
-- **不要**在无 `prd.md`（且 `apm pull` 后仍无）的情况下编造需求实现。
-- **子 Agent** 提示中须带 **`requirementId`** 与仓库根路径意识，避免改错工作树。

package/template/skills/apm-review/apm-review-reference.md

@@ -1,89 +0,0 @@
-# APM 需求评审规范与模板
-
-> 供 `apm-review` 技能使用：撰写并落盘到临时文件的评审正文时，遵守本节全文。
-
-## 评论受众与用语（写入 `apm comment` 的正文）
-
-- **读者**：产品经理与业务方为主；评论会作为协作记录，应**全程可读、可转发**，不假设读者会写代码或熟悉工程名词。
-- **禁止出现在评论正文里**：代码片段、文件路径、类名/函数名/接口名、库名、数据库表字段名、配置项名、命令行等与实现绑定的符号；也避免堆叠「中间件、DTO、ORM、幂等、熔断」等纯工程术语（除非已在 `prd.md` 里作为约定用语出现且别无说法）。
-- **推荐写法**：用日常中文说明「用户会看到什么」「缺了哪条规则大家会各猜各的」「和现有能力会不会打架」等；若必须指向实现，只说「与当前后台/前台的既有能力有关」或「需要和技术同事确认某某板块是否已有」，**不把符号留给 PM 去对号入座**。
-- **立场声明（业务白话，一两句即可）**：若本轮仅为**单侧**对照（只看清浏览器端或只看清服务端），正文**开头**用不加术语的一句话标明**评审视角**（例如「本轮主要对照当前浏览器里可见的界面与流程」或「本轮主要对照当前服务端已暴露的能力与数据边界」），让读者知道评论**不是**全链路结论；**两侧均已实质核对**时，可写一句「前后台实现均已对照」或省略。**禁止**用「从前端角度」「站在后端」等角色标签式套话堆砌，一句说清范围即可。
-- **内部核对**：Agent 读代码时仍可自用路径与符号做推理；**落盘到临时文件、提交评论前**须把「代码依据」改写成上述白话，不复制粘贴技术标识符。
-
-## 正文形态与语气（写入临时文件的评审）
-
-- **像真人写的**：自然段落或简短条目均可；**禁止**行政腔、教程腔套话，例如「请先确认」「建议补一句」「会上拍板」「建议各方对齐」等指向「写作动作」的提示——只陈述**文档里哪里不顺、会导致什么后果**。
-- **直入问题**：不写「对用户意图的理解」这类总起段；意图若与某条缺陷强相关，**并入该条一句带过**即可。
-- **只写有内容的条目**：某类问题不存在则**整段不写**；**禁止**用「未发现矛盾」「未见明显问题」「在已对照范围内无……」等否定句凑篇幅。若通读后没有可写问题：正文可仅为一两句说明「按当前正文暂无新增评审意见」，**仍不写**空洞分类标题。
-- **Markdown 结构与可读性（写入评论的正文）**：平台讨论区按 Markdown 渲染。正文宜用 **`##` 二级标题**按条拆分（标题里点明文档位置），条内可用 **「要点 / 后果」** 或等价两项列表；**关键短语加粗**，必要时用 `---` 分隔大段，避免「一整块纯叙述」难以扫读。结构服从内容：**没有问题则不硬凑条目**。
-
-## 评审立场（依可见代码）
-
-对照需求完成检索后，根据**本轮实际读过、且作为依据写入评论的代码范围**选定立场；**评论写什么、写到哪一层，以该可见范围为上限**。
-
-| 可见范围                               | 评审立场     | 写入评论时的要求                                                                                                                                                        |
-| -------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 主要只见 **浏览器端 / 前台界面与交互** | **前台视角** | 只评界面入口、流程、状态与交互缺口；涉及持久化、权限、接口形态时，用白话写成「须与服务端/后台约定」「单凭当前界面看不出是否已有支撑」，**不下「后台一定如何」的断定**。 |
-| 主要只见 **服务端 / API 与数据层**     | **后台视角** | 只评服务能力、数据含义、权限与边界；涉及页面怎么摆、按钮文案时，用「展示层须另侧对齐」一类表述，**不代替产品写 UI 细则**。                                              |
-| **前台与后台均已就本需求相关链路核对** | **全栈视角** | 可写前后衔接断层、端到端验收风险（仍用业务白话、禁止符号）。                                                                                                            |
-
-**禁止**：只读过一侧却在评论中写超出该侧可见范围的**全称断定**（例如仅对照前台却断言「库里不会有某类数据」）。单侧视角下若发现需求显然依赖另一侧而未写明，应写「文档未约定与后台/前台的衔接点，易导致联调分歧」，而非编造另一侧实现细节。
-
----
-
-## 立场：专业评审，而非复述原文
-
-- `prd.md` 可能口语化、不完整；正文用**清晰、可决策**的语言（业务名词与文档对齐），**对准具体条款**写缺口或风险。
-- **禁止**空洞表态（例如「技术上都能做」）；谈可行性须**建立在已读相关代码与模块边界之上**（且不超过上文「评审立场」准许的范围），说明与**现有能力划分、数据含义、产品约定**的关系及**后续改版成本**，用语落在「需求若坚持某种表述会带来何种**产品规则或协作上的代价**」，而非教人怎么写代码。
-
-## 评审范围
-
-### 要做（需求侧 + 基于代码的落地风险）
-
-| 类别                      | 说明                                                                                                                                                                                                                                     |
-| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **意图与表述**            | 业务目标、约束、成功画面是否可从文中唯一推断；关键名词是否需统一                                                                                                                                                                         |
-| **歧义**                  | 多种合理解读并存                                                                                                                                                                                                                         |
-| **遗漏 / 不完整**         | 边界、异常、权限、状态组合未写清；代码已覆盖场景文档未提                                                                                                                                                                                 |
-| **矛盾**                  | 章节或枚举互斥                                                                                                                                                                                                                           |
-| **不可验收**              | 缺可观测判据或主语不明                                                                                                                                                                                                                   |
-| **与现状冲突 / 迭代风险** | **须在读完相关代码后**再写，且**不超出**上文「评审立场」准许的范围：与现有能力划分、数据含义、权限或流程约定抵触，或大牵连、难演进——**需求层取舍提醒**；正文只用**白话概括依据**，不写路径与符号（见「评论受众与用语」），非代码好坏评判 |
-
-### 不要做
-
-代码风格与微重构、与需求清晰度无关的性能闲话、替写完整正式 PRD（除非用户明确要求）、长篇复述 `prd.md` 全文。
-
-若「实现与文档不一致」，表述落在**需求如何写清或与现状对齐**，不指责实现错误。
-
-**与代码交付面脱节的「空头边界」**：对照代码后若已能判断**实际交付仅为 Web**（仓库无独立 App、小程序等其它端实现），且 `prd.md` **已写明**某条范围或非目标（例如「本期不考虑移动端 ×× 适配」），则**不再**单独写「未界定移动端是否包含窄屏桌面浏览器、平板横竖屏」等与**当前单一 Web 交付**无实质冲突、也不会改变验收判据的抠字条款——除非文档与「仅 Web」或验收环境约定**明显矛盾**，或 PRD 自己承诺了多终端却与代码不符。
-
-## 书写约束（针对写入文件的评审正文）
-
-- 每条问题须说清「指向文档哪一句 / 哪一节」+「会卡在哪」。篇幅上**优先简洁**：段落式宜控制在**两三句话量级**；若采用 **Markdown 分条**，每条下的「要点 / 后果」也各自保持简短，**禁止**为套模板而重复空话。
-- 引用需求文档用章节名、小节编号或口语转述条款；**不写**代码或工程标识符，技术边界用「评论受众与用语」中的白话改写。
-- **简洁优先**：宁可少写几条，也不要为显得「全面」而重复或空话。
-- 不对「业务价值高低」做主观评判；可说明「需求未定义清楚会导致何种决策瘫痪或返工风险」。
-
----
-
-## 评审模板（写入临时文件的正文示例，结构仅供参考）
-
-按问题组织，**每条尽量点明文档位置**（章节名、小节编号、列表要点均可）。可读性要求高时优先采用 **Markdown 分条 + 要点/后果**（见上文「正文形态与语气」）。
-
-**示例（标题 + 要点/后果 + 加粗）：**
-
-```markdown
-## 「需求范围」第三条：主链路落在哪一屏没说死
-
-- **要点**：……
-- **后果**：……
-
----
-
-## 「交互与功能要求」第 4 节：类型认定规则缺失
-
-- **要点**：……
-- **后果**：……
-```
-
-（以上为示例：实际只保留**本轮确有依据**的条目；没有问题则不硬写。）