ai-project-manage-cli 8.1.21 → 8.1.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-project-manage-cli",
-  "version": "8.1.21",
+  "version": "8.1.22",
   "description": "命令行工具：后续用于调用平台后端 API 完成运维与自动化操作",
   "type": "module",
   "private": false,
@@ -14,7 +14,7 @@
     "template"
   ],
   "scripts": {
-    "build": "rm -rf dist && esbuild src/index.ts --bundle --platform=node --format=esm --packages=external --outfile=dist/index.js && esbuild src/commands/connect/core/worker/worker-script.ts --bundle --platform=node --format=esm --packages=external --outfile=dist/worker-script.js && tsc --noEmit -p tsconfig.json",
+    "build": "rm -rf dist && esbuild src/index.ts --bundle --platform=node --format=esm --packages=external --outfile=dist/index.js && esbuild src/commands/connect/core/worker/worker-script.ts --bundle --platform=node --format=esm --packages=external --outfile=dist/worker-script.js && mkdir -p dist/scripts && cp src/scripts/*.sh dist/scripts/ && chmod +x dist/scripts/*.sh && tsc --noEmit -p tsconfig.json",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {

package/template/README.md

@@ -0,0 +1,13 @@
+# CLI template（新版星图 / ACP）
+
+本目录供**新版** Cursor ACP / 星图流程使用，与历史 WebIDE `apm connect` 路径**解耦**：
+
+| 内容 | 用途 |
+|------|------|
+| `mcp.json` | 远程 MCP（`x-task-id` / `x-project-id`） |
+| `hooks/` | ACP hooks：开对话切分支、结束 commit/push |
+| `skills/` | 星图等新版 skills（如 `starmap-requirement-align`） |
+
+历史 WebIDE 指南与规则仍由平台 `agent-config` 灌库，经 `apm update-skills` 写入 `.apm/`，**不读**本 template。
+
+请勿把本目录 hooks/mcp 默认拷进历史 WebIDE 工作区，以免与旧流程混用。

package/template/hooks/after-agent-commit-repos.cjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * Cursor stop（每次 Agent 执行结束一次）：
+ * 对 `/home/repository.json` 各仓 commit-if-dirty + push。
+ * 无变更不空 commit；单仓失败继续其它仓；本 hook 始终 exit 0。
+ *
+ * ACP 若不触发 stop：由启动方在进程结束后调用
+ *   apm commit-task-repos --cwd <workdir>
+ */
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const { existsSync, readFileSync } = require("node:fs");
+const { join, resolve } = require("node:path");
+
+function respond(obj) {
+  process.stdout.write(JSON.stringify(obj ?? {}));
+}
+
+function readStdin() {
+  try {
+    return readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function resolveWorkdir(payload) {
+  const cwd = typeof payload.cwd === "string" ? payload.cwd.trim() : "";
+  if (cwd) return resolve(cwd);
+  const roots = Array.isArray(payload.workspace_roots)
+    ? payload.workspace_roots
+    : [];
+  for (const root of roots) {
+    if (typeof root === "string" && root.trim()) return resolve(root.trim());
+  }
+  return process.cwd();
+}
+
+/** APM 工作区根 = ACP 启动目录，其下必须有 `.apm`（不向上查找） */
+function requireApmWorkdir(start) {
+  const workdir = resolve(start);
+  if (!existsSync(join(workdir, ".apm"))) return null;
+  return workdir;
+}
+
+function whichApm() {
+  const r = spawnSync("bash", ["-lc", "command -v apm"], {
+    encoding: "utf8",
+  });
+  if (r.status !== 0) return "";
+  return (r.stdout || "").trim();
+}
+
+function hasTaskContext() {
+  return Boolean(
+    (process.env.APM_TASK_ID || "").trim() ||
+      (process.env.APM_PROJECT_ID || "").trim()
+  );
+}
+
+function main() {
+  let input = {};
+  try {
+    const raw = readStdin();
+    if (raw.trim()) input = JSON.parse(raw);
+  } catch {
+    /* 收尾：输入坏了也尽量继续 */
+  }
+
+  const workdirHint = resolveWorkdir(input);
+  const workdir = requireApmWorkdir(workdirHint);
+  if (!workdir) {
+    process.stderr.write(
+      `[apm] ACP 启动目录下未找到 .apm，跳过收尾: ${resolve(workdirHint)}\n`
+    );
+    respond({});
+    process.exit(0);
+  }
+
+  if (!hasTaskContext() && !existsSync("/home/repository.json")) {
+    respond({});
+    process.exit(0);
+  }
+
+  const apm = whichApm();
+  if (!apm) {
+    process.stderr.write("[apm] commit-task-repos：未找到 apm，跳过收尾\n");
+    respond({});
+    process.exit(0);
+  }
+
+  const result = spawnSync(apm, ["commit-task-repos", "--cwd", workdir], {
+    encoding: "utf8",
+    env: process.env,
+  });
+
+  if (result.stdout?.trim()) process.stderr.write(result.stdout);
+  if (result.stderr?.trim()) process.stderr.write(result.stderr);
+
+  respond({});
+  process.exit(0);
+}
+
+try {
+  main();
+} catch (err) {
+  const detail = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`[apm] after-agent-commit-repos 异常: ${detail}\n`);
+  respond({});
+  process.exit(0);
+}

package/template/hooks/before-prompt-prepare.cjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/**
+ * Cursor beforeSubmitPrompt（对话 / 本轮用户提问开始之前）：
+ * 1. 缓存用户问题（供结束时 commit message）
+ * 2. 确保 /home/repository.json 内各仓位于 feat/task-<APM_TASK_ID>
+ *
+ * 失败则 continue:false，本轮不进入 Agent。
+ * ACP 若不触发本 hook：启动对话前由宿主执行
+ *   apm ensure-task-branch && 写入 user-prompt 缓存文件
+ */
+"use strict";
+
+const { createHash } = require("node:crypto");
+const { spawnSync } = require("node:child_process");
+const {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} = require("node:fs");
+const { tmpdir } = require("node:os");
+const { join, resolve } = require("node:path");
+
+function respond(obj) {
+  process.stdout.write(JSON.stringify(obj));
+}
+
+function allow() {
+  respond({ continue: true });
+  process.exit(0);
+}
+
+function deny(userMessage) {
+  respond({
+    continue: false,
+    user_message: userMessage,
+  });
+  process.exit(0);
+}
+
+function readStdin() {
+  return readFileSync(0, "utf8");
+}
+
+function resolveWorkdir(payload) {
+  const roots = Array.isArray(payload.workspace_roots)
+    ? payload.workspace_roots
+    : [];
+  for (const root of roots) {
+    if (typeof root === "string" && root.trim()) return resolve(root.trim());
+  }
+  const cwd = typeof payload.cwd === "string" ? payload.cwd.trim() : "";
+  if (cwd) return resolve(cwd);
+  return process.cwd();
+}
+
+/**
+ * APM 工作区根 = Cursor ACP 启动目录，其下必须有 `.apm`（不向上查找）。
+ * @returns {string | null}
+ */
+function requireApmWorkdir(start) {
+  const workdir = resolve(start);
+  if (!existsSync(join(workdir, ".apm"))) return null;
+  return workdir;
+}
+
+function promptCachePath(workdir) {
+  const key = createHash("sha256").update(workdir).digest("hex").slice(0, 16);
+  return join(tmpdir(), "apm-hooks", key, "user-prompt.txt");
+}
+
+function cacheUserPrompt(workdir, prompt) {
+  const text = typeof prompt === "string" ? prompt.trim() : "";
+  if (!text) return;
+  const path = promptCachePath(workdir);
+  try {
+    mkdirSync(join(path, ".."), { recursive: true });
+    writeFileSync(path, `${text}\n`, "utf8");
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[apm] 缓存用户问题失败: ${detail}\n`);
+  }
+}
+
+function expectedBranch(taskId) {
+  return `feat/task-${taskId}`;
+}
+
+function currentBranch(repoRoot) {
+  const r = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+    cwd: repoRoot,
+    encoding: "utf8",
+  });
+  if (r.status !== 0) return null;
+  return (r.stdout || "").trim();
+}
+
+const HOME_REPOSITORY_JSON = "/home/repository.json";
+
+function listReposNotOnBranch(workdir, branch) {
+  if (!existsSync(HOME_REPOSITORY_JSON)) return null;
+  let map;
+  try {
+    map = JSON.parse(readFileSync(HOME_REPOSITORY_JSON, "utf8"));
+  } catch {
+    return null;
+  }
+  if (!map || typeof map !== "object" || Array.isArray(map)) return null;
+  const keys = Object.keys(map)
+    .map((k) => String(k).trim())
+    .filter((k) => k && k !== "." && !k.includes("/") && !k.includes("\\"));
+  if (keys.length === 0) return null;
+  const off = [];
+  for (const rel of keys) {
+    if (currentBranch(join(workdir, rel)) !== branch) off.push(rel);
+  }
+  return off;
+}
+
+function whichApm() {
+  const r = spawnSync("bash", ["-lc", "command -v apm"], {
+    encoding: "utf8",
+  });
+  if (r.status !== 0) return "";
+  return (r.stdout || "").trim();
+}
+
+function main() {
+  let input;
+  try {
+    input = JSON.parse(readStdin() || "{}");
+  } catch {
+    deny("[apm] beforeSubmitPrompt 输入不是合法 JSON");
+  }
+
+  const workdirHint = resolveWorkdir(input);
+  const workdir = requireApmWorkdir(workdirHint);
+  if (!workdir) {
+    deny(
+      `[apm] ACP 启动目录下未找到 .apm：${resolve(workdirHint)}（必须为启动目录/.apm，不向上查找）`
+    );
+  }
+
+  cacheUserPrompt(workdir, input.prompt);
+
+  const taskId = (process.env.APM_TASK_ID || "").trim();
+  const projectId = (process.env.APM_PROJECT_ID || "").trim();
+
+  // 非 APM 任务：只缓存问题（若有），放行
+  if (!taskId && !projectId) {
+    allow();
+  }
+
+  if (!taskId || !projectId) {
+    deny(
+      "[apm] 缺少 APM_TASK_ID 或 APM_PROJECT_ID，无法在对话开始前确认特性分支"
+    );
+  }
+
+  const branch = expectedBranch(taskId);
+  const offBranch = listReposNotOnBranch(workdir, branch);
+  if (Array.isArray(offBranch) && offBranch.length === 0) {
+    allow();
+  }
+
+  const apm = whichApm();
+  if (!apm) {
+    deny("[apm] 未找到 apm CLI，无法确认特性分支");
+  }
+
+  if (Array.isArray(offBranch) && offBranch.length > 0) {
+    process.stderr.write(
+      `[apm] 对话开始前确认分支 ${branch}，未就绪: ${offBranch.join(", ")}\n`
+    );
+  }
+
+  const result = spawnSync(
+    apm,
+    ["ensure-task-branch", taskId, projectId, "--cwd", workdir],
+    {
+      encoding: "utf8",
+      env: process.env,
+    }
+  );
+
+  if (result.stdout?.trim()) process.stderr.write(result.stdout);
+  if (result.stderr?.trim()) process.stderr.write(result.stderr);
+
+  if (result.status === 0) {
+    allow();
+  }
+
+  const detail = `${result.stdout || ""}${result.stderr || ""}`.trim();
+  deny(
+    detail
+      ? `[apm] 对话开始前确认特性分支失败\n${detail}`
+      : `[apm] 对话开始前确认特性分支失败（exit=${result.status ?? "unknown"}）`
+  );
+}
+
+try {
+  main();
+} catch (err) {
+  const detail = err instanceof Error ? err.message : String(err);
+  deny(`[apm] before-prompt-prepare 异常: ${detail}`);
+}

package/template/hooks.json

@@ -0,0 +1,18 @@
+{
+  "version": 1,
+  "hooks": {
+    "beforeSubmitPrompt": [
+      {
+        "command": "./hooks/before-prompt-prepare.cjs",
+        "timeout": 180,
+        "failClosed": true
+      }
+    ],
+    "stop": [
+      {
+        "command": "./hooks/after-agent-commit-repos.cjs",
+        "timeout": 180
+      }
+    ]
+  }
+}

package/template/mcp.json

@@ -0,0 +1,18 @@
+{
+    "mcpServers": {
+        "apm": {
+            "url": "${env:APM_SERVER}/api/v1/mcp",
+            "headers": {
+                "Authorization": "Bearer ${env:APM_API_KEY}",
+                "x-task-id": "${env:APM_TASK_ID}",
+                "x-project-id": "${env:APM_PROJECT_ID}"
+            }
+        },
+        "billion-skill": {
+            "url": "https://wdxnhqgjbvib.sealosgzg.site/api/mcp",
+            "headers": {
+                "Authorization": "Bearer sk_ImOQHJZSGncproCHg6Q7ZnE_vGmylWtdYkG6TPkH2Jg"
+            }
+        }
+    }
+}

package/template/skills/webide-run-retro/SKILL.md

@@ -1,103 +0,0 @@
----
-name: webide-run-retro
-description: >-
-  Resolve a Cursor WebIDE run-id or agent-id to the local conversation
-  transcript, then produce two documents: conversation replay and defect
-  retrospective attribution (unclear requirements vs AI vs environment). Use
-  when the user pastes a run-id (run-<uuid>), agent-id (agent-<uuid>), asks to
-  查找对话, 对话回放, 复盘, 缺陷归因, or reviews WebIDE report-defect rounds.
----
-
-# WebIDE Run / Agent 复盘
-
-用户给出 `run-id` 或 `agent-id` 时：先还原对话，再只对 **report-defect**（及等价的用户缺陷反馈）做归因。回复用中文。
-
-产出必须是 **两份独立文档**（两份 Canvas），缺一不可：
-
-1. **对话回放** — 整段 agent 对话按轮次可浏览
-2. **复盘归因** — 对用户提出的缺陷做主因判定与改进建议
-
-## 1. 解析 ID
-
-执行（不要手写等价逻辑）：
-
-```bash
-node ~/.cursor/skills/webide-run-retro/scripts/inspect-run.mjs --id '<用户给的ID>'
-```
-
-脚本会：
-
-- 读 `AGENT_TRANSCRIPTS` 与 `~/.cursor/projects/*/agent-transcripts`
-- 查 SDK store `index.db`（活表 + 已删除页的字符串残留，因为 WebIDE 常 `purge` store）
-- 读 `.apm/webide/<taskId>/cursor-agent.json`
-- 打印 `agentId`、`matchedRunId`、`transcriptPath`、按轮次的 `conversation`
-
-`run-<uuid>` 是一次 `send()`；`agent-<uuid>` 是整段多轮会话。有 run-id 时仍要拉**整个 agent** 对话，否则看不到原需求。
-
-找不到 transcript 就停，说明缺了哪一层（store / transcripts / 已清理），不要编对话。
-
-## 2. 读对话
-
-用脚本输出的 `transcriptPath` 做补充阅读：
-
-- 第一轮 `action=start`（或首条用户需求）= **原需求原文**
-- `action=write-plan` / `start-develop` = AI 理解与实现范围
-- `action=report-defect` = 待归因缺陷（`【现状】` / `【预期】`）
-- 助手收尾句与 git 提交（`feat:` / `fix:`）用来核对手改了什么
-
-需要核对代码时，对比特性分支相对基线的首次实现提交 vs 后续 `fix:` 提交，避免把基线旧逻辑算成 AI 新引入。
-
-## 3. 归因（必做）
-
-细则见 [attribution.md](attribution.md)。对每条缺陷标**一个主因**：
-
-1. **需求没写清** — 原文没有该行为/边界/状态机
-2. **AI 理解或实现问题** — 原文或缺陷期望已写清，但理解偏了、修不彻底、工作流做半截
-3. **环境 / 工程** — 启动、构建、端口，与业务无关
-
-总判断先写：**原需求有没有被理解对**。后面的缺陷经常是测试挖出未写进需求的业务，不要误判成「字段理解反了」。
-
-给出两个动作建议：
-
-- 需求没写清 → 培训用户（过滤包含/排除、空值样例、暂存/提交状态机、字段可空、验收反例）
-- AI 理解/实现问题 → 补业务文档（组件默认过滤、审批暂存/startFlow、deploy 启动命令）
-
-## 4. 输出
-
-聊天里用 3–8 句中文给出：agent-id、任务名、回放轮次数、缺陷条数、总判断、两条动作建议。然后给出两份 Canvas 的 markdown 链接。不要用大 markdown 表代替 Canvas。
-
-先 Read `~/.cursor/skills-cursor/canvas/SKILL.md`。两份都写在 `~/.cursor/projects/<workspace>/canvases/`，文件名 kebab-case。
-
-### 文档 1：对话回放
-
-文件：`<agent-short-id>-conversation.canvas.tsx`
-
-必须包含：
-
-- ID 映射：run-id、agent-id、task-id
-- 任务标题与时间范围
-- 轮次一览表：序号、时间、动作、用户意图、工具次数
-- 对话正文：每轮可展开，用户请求摘要 + 助手收尾回复（不要堆工具调用细节）
-- 中断后重试的同一缺陷合并说明（若有）
-
-### 文档 2：复盘归因
-
-文件：`<agent-short-id>-retro.canvas.tsx`
-
-必须包含：
-
-- 总判断：原需求有没有被理解对
-- 主因分布（饼图或统计）：需求没写清 / AI 理解或实现 / 环境
-- 原需求实际覆盖了什么（对照评估与首轮实现）
-- 缺陷连锁关系（若有）
-- 逐条归因表：缺陷、主因、原需求是否覆盖、原因
-- 两块建议：培训用户写需求 vs 补 AI 业务文档
-
-无缺陷时：仍产出文档 2，写明「无 report-defect 轮次，不归因」，不要编缺陷。
-
-## 5. 禁止
-
-- 不要把对话回放和复盘归因合成一份 Canvas
-- 不要把缺陷单里新补的期望，回溯成「原需求 AI 理解错」
-- 不要只复述工具调用；归因要对照原文、评估结论、代码/提交
-- 不要输出密钥、API Key、MinIO 凭证

package/template/skills/webide-run-retro/attribution.md

@@ -1,26 +0,0 @@
-# 缺陷归因细则
-
-主因只标一个。对照物永远是**该 agent 第一轮用户需求原文**，不是后续缺陷单里补充的期望。
-
-## 三类主因
-
-| 主因 | 何时用 | 对应动作 |
-|------|--------|----------|
-| 需求没写清 | 缺陷所要的行为不在原文（含空值、过滤白名单、按钮/状态机、验收反例） | 培训用户把需求写完整 |
-| AI 理解或实现问题 | 原文已覆盖，或缺陷单已写清期望，但 AI 理解偏了、修不彻底、把工作流做半截 | 补业务/组件/工作流文档 |
-| 环境 / 工程 | 启动失败、端口、构建命令、与业务无关 | 补 deploy/启动文档 |
-
-不要把「测试中途新提出的暂存/提交」算成「AI 把原需求理解错」。原需求理解对、范围外行为在测试里才出现 → 需求缺口。
-
-## 连锁缺陷
-
-同一缺口连续爆出来时，在表里分开写，但复盘正文要标明因果链。例如：未写「无级别术式可申请」→ 选中后必填失败 → 库非空失败 → 改成暂存 → 列表/工作流半截。
-
-只把链尾的「做半截」标成 AI 实现问题；链头标需求缺口。
-
-## 评估阶段检查
-
-若第一轮评估写了「无开放问题」，但测试缺陷正好落在未提问的边界上，复盘里必须点出本该问的问题，并同时改进：
-
-- 用户需求模板（过滤包含/排除、空值样例、按钮状态机、字段可空、验收反例）
-- AI 评估检查单（空值、默认过滤、暂存 vs 提交、流程何时启动）