ai-project-manage-cli 5.0.7 → 5.0.9

package/dist/index.js

@@ -40,6 +40,12 @@ function defaultApmConfig() {
     email: ""
   };
 }
+function httpBaseToWsOrigin(httpBase) {
+  const u = httpBase.trim().replace(/\/+$/, "");
+  if (u.startsWith("https://")) return "wss://" + u.slice("https://".length);
+  if (u.startsWith("http://")) return "ws://" + u.slice("http://".length);
+  throw new Error("baseUrl \u5FC5\u987B\u4EE5 http:// \u6216 https:// \u5F00\u5934");
+}
 async function ensureApmConfig() {
   const existing = await readApmConfig();
   if (existing) return existing;
@@ -59,6 +65,11 @@ async function writeApmConfig(cfg) {
     mode: 384
   });
 }
+function buildAgentWsUrl(httpBase, token) {
+  const origin = httpBaseToWsOrigin(httpBase);
+  const q = new URLSearchParams({ token });
+  return `${origin}/ws/agent?${q.toString()}`;
+}
 
 // src/commands/init.ts
 import { join as join3 } from "path";
@@ -456,33 +467,17 @@ function escapeXmlAttr(value) {
 function wrapCdata(value) {
   return `<![CDATA[${value.replace(/]]>/g, "]]]]><![CDATA[>")}]]>`;
 }
-function optionalAttr(name, value) {
-  if (value == null || value === "") {
-    return "";
-  }
-  return ` ${name}="${escapeXmlAttr(value)}"`;
-}
 function formatSessionMessagesXml(sessionId, messages) {
   const lines = [
     '<?xml version="1.0" encoding="UTF-8"?>',
     `<messages sessionId="${escapeXmlAttr(sessionId)}">`
   ];
   for (const message of messages) {
-    const attrs = [
-      `id="${escapeXmlAttr(message.id)}"`,
-      `senderId="${escapeXmlAttr(message.senderId)}"`,
-      message.sender ? `senderName="${escapeXmlAttr(message.sender.displayName)}"` : "",
-      message.sender ? `senderPosition="${escapeXmlAttr(message.sender.position)}"` : "",
-      message.sender ? `proxyMode="${escapeXmlAttr(message.sender.proxyMode)}"` : "",
-      `status="${escapeXmlAttr(message.status)}"`,
-      `createdAt="${escapeXmlAttr(message.createdAt)}"`,
-      `contentUpdatedAt="${escapeXmlAttr(message.contentUpdatedAt)}"`
-    ].filter(Boolean).join(" ");
+    const roundAttr = message.round != null && message.round > 0 ? ` round="${message.round}"` : "";
     lines.push(
-      `  <message ${attrs}${optionalAttr(
-        "roundId",
-        message.roundId
-      )}${optionalAttr("sentAt", message.sentAt)}>`,
+      `  <message id="${escapeXmlAttr(message.id)}" name="${escapeXmlAttr(
+        message.name
+      )}" position="${escapeXmlAttr(message.position)}"${roundAttr}>`,
       `    <content>${wrapCdata(message.content)}</content>`,
       "  </message>"
     );
@@ -662,43 +657,126 @@ async function runUpdate() {
 }
 
 // src/commands/update-skills.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync3, rmSync, statSync as statSync2, writeFileSync as writeFileSync5 } from "fs";
+import { existsSync as existsSync3, mkdirSync as mkdirSync4, statSync as statSync3 } from "fs";
+import { join as join8 } from "path";
+
+// src/skills-sync.ts
+import {
+  copyFileSync,
+  cpSync as cpSync2,
+  existsSync as existsSync2,
+  mkdirSync as mkdirSync3,
+  readdirSync as readdirSync2,
+  rmSync,
+  statSync as statSync2,
+  writeFileSync as writeFileSync5
+} from "fs";
 import { join as join7 } from "path";
-function sanitizeDirName(name) {
+var AGENTS_TEMPLATE_PATH = join7(CLI_TEMPLATE_DIR, "AGENTS.md");
+var BASE_SKILLS_TEMPLATE_DIR = join7(CLI_TEMPLATE_DIR, "skills");
+function sanitizeSkillDirName(name) {
   const trimmed = name.trim();
   if (!trimmed) return "skill";
   return trimmed.replace(/[/\\:*?"<>|]/g, "_");
 }
+function listBaseSkillDirNames() {
+  if (!existsSync2(BASE_SKILLS_TEMPLATE_DIR)) return [];
+  return readdirSync2(BASE_SKILLS_TEMPLATE_DIR).filter((name) => {
+    const path8 = join7(BASE_SKILLS_TEMPLATE_DIR, name);
+    return statSync2(path8).isDirectory();
+  });
+}
+function syncAgentsGuide(apmDir) {
+  if (!existsSync2(AGENTS_TEMPLATE_PATH)) return false;
+  mkdirSync3(apmDir, { recursive: true });
+  copyFileSync(AGENTS_TEMPLATE_PATH, join7(apmDir, "AGENTS.md"));
+  return true;
+}
+function syncBaseSkills(skillsDir) {
+  mkdirSync3(skillsDir, { recursive: true });
+  const names = listBaseSkillDirNames();
+  for (const name of names) {
+    const src = join7(BASE_SKILLS_TEMPLATE_DIR, name);
+    const dest = join7(skillsDir, name);
+    cpSync2(src, dest, { recursive: true, force: true });
+  }
+  return names;
+}
+function syncSupplementarySkills(skillsDir, list) {
+  const baseNames = new Set(listBaseSkillDirNames());
+  const apiDirNames = /* @__PURE__ */ new Set();
+  const written = [];
+  const skipped = [];
+  for (const skill of list) {
+    const dirName = sanitizeSkillDirName(skill.name);
+    apiDirNames.add(dirName);
+    if (baseNames.has(dirName)) {
+      skipped.push(dirName);
+      continue;
+    }
+    const skillDir = join7(skillsDir, dirName);
+    mkdirSync3(skillDir, { recursive: true });
+    writeFileSync5(join7(skillDir, "SKILL.md"), skill.content ?? "", "utf8");
+    written.push(dirName);
+  }
+  const removed = [];
+  if (!existsSync2(skillsDir)) return { written, skipped, removed };
+  for (const entry of readdirSync2(skillsDir)) {
+    const full = join7(skillsDir, entry);
+    if (!statSync2(full).isDirectory()) continue;
+    if (baseNames.has(entry)) continue;
+    if (apiDirNames.has(entry)) continue;
+    rmSync(full, { recursive: true, force: true });
+    removed.push(entry);
+  }
+  return { written, skipped, removed };
+}
+
+// src/commands/update-skills.ts
 async function runUpdateSkills() {
   const apmDir = workspaceApmDir();
-  if (!existsSync2(apmDir)) {
+  if (!existsSync3(apmDir)) {
     console.error("[apm] \u672A\u627E\u5230 .apm \u76EE\u5F55\uFF0C\u8BF7\u5148\u6267\u884C apm init");
     process.exit(1);
   }
-  const apmStat = statSync2(apmDir);
+  const apmStat = statSync3(apmDir);
   if (!apmStat.isDirectory()) {
     throw new Error(`[apm] \u8DEF\u5F84\u5DF2\u5B58\u5728\u4F46\u4E0D\u662F\u76EE\u5F55: ${apmDir}`);
   }
   const cfg = await ensureLoggedConfig();
   const api = createApmApiClient(cfg);
   const { list } = await api.cli.listSkills({});
-  const skillsDir = join7(apmDir, "skills");
-  if (existsSync2(skillsDir)) {
-    rmSync(skillsDir, { recursive: true, force: true });
+  if (syncAgentsGuide(apmDir)) {
+    console.log("[apm] \u5DF2\u540C\u6B65 APM \u6307\u5357: .apm/AGENTS.md");
+  }
+  const skillsDir = join8(apmDir, "skills");
+  mkdirSync4(skillsDir, { recursive: true });
+  const baseNames = syncBaseSkills(skillsDir);
+  for (const name of baseNames) {
+    console.log(`[apm] \u5DF2\u540C\u6B65\u57FA\u7840\u6280\u80FD: skills/${name}/`);
+  }
+  const { written, skipped, removed } = syncSupplementarySkills(
+    skillsDir,
+    list
+  );
+  for (const name of written) {
+    console.log(`[apm] \u5DF2\u5199\u5165\u8865\u5145\u6280\u80FD: skills/${name}/SKILL.md`);
   }
-  mkdirSync3(skillsDir, { recursive: true });
-  for (const skill of list) {
-    const dirName = sanitizeDirName(skill.name);
-    const skillDir = join7(skillsDir, dirName);
-    mkdirSync3(skillDir, { recursive: true });
-    writeFileSync5(join7(skillDir, "SKILL.md"), skill.content ?? "", "utf8");
-    console.log(`[apm] \u5DF2\u5199\u5165\u6280\u80FD: skills/${dirName}/SKILL.md`);
+  for (const name of skipped) {
+    console.log(
+      `[apm] \u5DF2\u8DF3\u8FC7\u4E0E\u57FA\u7840\u6280\u80FD\u540C\u540D\u7684\u8865\u5145\u6280\u80FD: ${name}\uFF08\u4FDD\u7559\u6A21\u677F\u7248\u672C\uFF09`
+    );
+  }
+  for (const name of removed) {
+    console.log(`[apm] \u5DF2\u79FB\u9664\u5DF2\u4E0B\u7EBF\u7684\u8865\u5145\u6280\u80FD: skills/${name}/`);
   }
-  console.log(`[apm] \u5DF2\u66F4\u65B0 ${list.length} \u4E2A\u6280\u80FD\u5230 .apm/skills`);
+  console.log(
+    `[apm] \u6280\u80FD\u540C\u6B65\u5B8C\u6210\uFF1A${baseNames.length} \u4E2A\u57FA\u7840\u6280\u80FD\uFF0C${written.length} \u4E2A\u8865\u5145\u6280\u80FD`
+  );
 }
 
 // src/commands/sync-document.ts
-import { existsSync as existsSync3, readFileSync as readFileSync4 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
 async function runSyncDocument(sessionId, options) {
   const trimmedSessionId = sessionId.trim();
   if (!trimmedSessionId) {
@@ -711,7 +789,7 @@ async function runSyncDocument(sessionId, options) {
     process.exit(1);
   }
   const absPath = resolveSessionDocumentPath(trimmedSessionId, fileArg);
-  if (!existsSync3(absPath)) {
+  if (!existsSync4(absPath)) {
     const docsDir = sessionDocsDir(trimmedSessionId);
     console.error(
       `[apm] \u6587\u6863\u4E0D\u5B58\u5728: ${absPath}
@@ -775,18 +853,307 @@ async function runUpdateMessageStatus(options) {
   console.log(`[apm] \u5DF2\u66F4\u65B0\u6D88\u606F\u72B6\u6001: ${messageId} \u2192 ${status}`);
 }
 
+// src/commands/connect.ts
+import WebSocket from "ws";
+
+// src/ws/protocol.ts
+function nonEmptyString(v) {
+  return typeof v === "string" && v.trim().length > 0;
+}
+function parseAgentWsMessage(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function serializeAgentWsMessage(msg) {
+  return JSON.stringify(msg);
+}
+function validateAgentWsMessage(value, kind) {
+  if (typeof value !== "object" || value === null) {
+    return { ok: false, reason: "\u6D88\u606F\u4F53\u4E0D\u662F JSON \u5BF9\u8C61" };
+  }
+  const o = value;
+  const type = o.type;
+  if (type !== "heartbeat" && type !== "message") {
+    return { ok: false, reason: `\u672A\u77E5 type: ${String(type)}` };
+  }
+  if (kind === "heartbeat" || type === "heartbeat") {
+    if (type !== "heartbeat") {
+      return { ok: false, reason: "\u671F\u671B heartbeat" };
+    }
+    if (!nonEmptyString(o.userId)) {
+      return { ok: false, reason: "heartbeat \u7F3A\u5C11 userId" };
+    }
+    return { ok: true, data: { type: "heartbeat", userId: o.userId.trim() } };
+  }
+  if (type !== "message") {
+    return { ok: false, reason: "\u671F\u671B message" };
+  }
+  if (!nonEmptyString(o.messageId)) {
+    return { ok: false, reason: "message \u7F3A\u5C11 messageId" };
+  }
+  if (!nonEmptyString(o.sessionId)) {
+    return { ok: false, reason: "message \u7F3A\u5C11 sessionId" };
+  }
+  if (!nonEmptyString(o.content)) {
+    return { ok: false, reason: "message \u7F3A\u5C11 content" };
+  }
+  if (!nonEmptyString(o.model)) {
+    return { ok: false, reason: "message \u7F3A\u5C11 model" };
+  }
+  if (!nonEmptyString(o.apiKey)) {
+    return { ok: false, reason: "message \u7F3A\u5C11 apiKey" };
+  }
+  if (!nonEmptyString(o.workdir)) {
+    return { ok: false, reason: "message \u7F3A\u5C11 workdir" };
+  }
+  if (!nonEmptyString(o.user)) {
+    return { ok: false, reason: "message \u7F3A\u5C11 user" };
+  }
+  return {
+    ok: true,
+    data: {
+      type: "message",
+      messageId: o.messageId.trim(),
+      sessionId: o.sessionId.trim(),
+      content: o.content,
+      model: o.model.trim(),
+      apiKey: o.apiKey.trim(),
+      workdir: o.workdir.trim(),
+      user: o.user.trim()
+    }
+  };
+}
+
+// src/commands/connect/cursor-agent.ts
+import { resolve as resolve3 } from "path";
+import { Agent, CursorAgentError } from "@cursor/sdk";
+var DEFAULT_CURSOR_MODEL = "default";
+function resolveModelId(model) {
+  const id = model.trim();
+  return id || DEFAULT_CURSOR_MODEL;
+}
+function buildPrompt(ctx) {
+  const lines = [
+    `\u4F60\u662F${ctx.user}`,
+    `\u4F1A\u8BDDID: ${ctx.sessionId}`,
+    `\u6D88\u606FID: ${ctx.messageId}`,
+    `\u4EFB\u52A1: ${ctx.content}`,
+    `\u8BF7\u5148\u9605\u8BFBAPM\u6307\u5357\uFF1A [AGENTS.md](.apm/AGENTS.md)\uFF0C\u4E25\u683C\u6309\u7167\u6307\u5357\u7684\u5DE5\u4F5C\u6D41\u7A0B\u5B8C\u6210\u4EFB\u52A1`
+  ];
+  return lines.join("\n");
+}
+function extractAssistantTextFromStream(event) {
+  if (event.type !== "assistant") {
+    return "";
+  }
+  const msg = event.message;
+  if (!msg?.content) {
+    return "";
+  }
+  let text = "";
+  for (const block of msg.content) {
+    if (block.type === "text" && block.text) {
+      text += block.text;
+    }
+  }
+  return text;
+}
+async function runCursorAgent(_cfg, ctx) {
+  const apiKey = ctx.apiKey.trim();
+  if (!apiKey) {
+    throw new Error("\u7F3A\u5C11 apiKey\uFF0C\u65E0\u6CD5\u8C03\u7528 Cursor SDK");
+  }
+  const cwd = resolve3(ctx.workdir);
+  const prompt = buildPrompt(ctx);
+  console.log(
+    `[apm] Cursor Agent \u5F00\u59CB messageId=${ctx.messageId} sessionId=${ctx.sessionId} cwd=${cwd}`
+  );
+  const agent = await Agent.create({
+    apiKey,
+    model: { id: resolveModelId(ctx.model) },
+    local: {
+      cwd,
+      settingSources: []
+    }
+  });
+  try {
+    const run = await agent.send(prompt);
+    console.log(`[apm] Cursor run id=${run.id} agentId=${agent.agentId}`);
+    for await (const event of run.stream()) {
+      const chunk = extractAssistantTextFromStream(event);
+      if (chunk) {
+        process.stdout.write(chunk);
+      }
+    }
+    const result = await run.wait();
+    if (result.status === "error") {
+      throw new Error(`Cursor run \u5931\u8D25: ${result.id}`);
+    }
+    if (result.status === "cancelled") {
+      throw new Error(`Cursor run \u5DF2\u53D6\u6D88: ${result.id}`);
+    }
+    console.log(`[apm] Cursor Agent \u5B8C\u6210 messageId=${ctx.messageId}`);
+  } catch (err) {
+    if (err instanceof CursorAgentError) {
+      throw new Error(
+        `Cursor \u542F\u52A8\u5931\u8D25: ${err.message}${err.isRetryable ? "\uFF08\u53EF\u91CD\u8BD5\uFF09" : ""}`
+      );
+    }
+    throw err;
+  } finally {
+    await agent[Symbol.asyncDispose]();
+  }
+}
+
+// src/commands/connect.ts
+var HEARTBEAT_MS = 3e4;
+async function updateMessageStatus(cfg, messageId, status) {
+  const api = createApmApiClient(cfg);
+  await api.cli.updateMessageStatus({ id: messageId, status });
+  console.log(`[apm] \u5DF2\u66F4\u65B0\u6D88\u606F\u72B6\u6001: ${messageId} \u2192 ${status}`);
+}
+async function appendMessageContent(cfg, messageId, content) {
+  const api = createApmApiClient(cfg);
+  await api.cli.appendMessageContent({ id: messageId, content });
+  console.log(`[apm] \u5DF2\u8FFD\u52A0\u6D88\u606F\u5185\u5BB9: ${messageId}`);
+}
+async function handleInboundMessage(cfg, raw) {
+  const parsed = parseAgentWsMessage(raw);
+  if (parsed === null) {
+    console.error("[apm] \u6536\u5230\u65E0\u6548 JSON");
+    return;
+  }
+  if (typeof parsed === "object" && parsed !== null && parsed.type === "heartbeat") {
+    return;
+  }
+  const validated = validateAgentWsMessage(parsed, "outbound");
+  if (!validated.ok) {
+    console.error(`[apm] \u6536\u5230\u65E0\u6548 message: ${validated.reason}`);
+    return;
+  }
+  if (validated.data.type !== "message") {
+    return;
+  }
+  const msg = validated.data;
+  const messageId = msg.messageId;
+  try {
+    await runBranch(msg.sessionId, { cwd: msg.workdir });
+    await runPull(msg.sessionId, msg.workdir);
+    await updateMessageStatus(cfg, messageId, "TYPING");
+    await runCursorAgent(cfg, {
+      messageId: msg.messageId,
+      sessionId: msg.sessionId,
+      content: msg.content,
+      model: msg.model,
+      apiKey: msg.apiKey,
+      workdir: msg.workdir,
+      user: msg.user
+    });
+    await updateMessageStatus(cfg, messageId, "SUCCESS");
+  } catch (err) {
+    console.error(
+      "[apm] \u5904\u7406\u6D88\u606F\u5931\u8D25:",
+      err instanceof Error ? err.message : err
+    );
+    try {
+      await appendMessageContent(
+        cfg,
+        messageId,
+        `\u5904\u7406\u6D88\u606F\u5931\u8D25: ${err instanceof Error ? err.message : String(err)}
+`
+      );
+      await updateMessageStatus(cfg, messageId, "FAILED");
+    } catch (statusErr) {
+      console.error(
+        "[apm] \u66F4\u65B0 FAILED \u72B6\u6001\u5931\u8D25:",
+        statusErr instanceof Error ? statusErr.message : statusErr
+      );
+    }
+  }
+}
+function startHeartbeat(ws, userId) {
+  const send = () => {
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(
+        serializeAgentWsMessage({
+          type: "heartbeat",
+          userId
+        })
+      );
+    }
+  };
+  send();
+  const timer = setInterval(send, HEARTBEAT_MS);
+  return () => clearInterval(timer);
+}
+async function runConnect(options) {
+  const cfg = await ensureLoggedConfig();
+  if (options.server?.trim()) {
+    cfg.baseUrl = options.server.trim().replace(/\/+$/, "");
+  }
+  if (!cfg.userId?.trim()) {
+    console.error("[apm] config \u7F3A\u5C11 userId\uFF0C\u8BF7\u91CD\u65B0 apm login");
+    process.exit(1);
+  }
+  const url = buildAgentWsUrl(cfg.baseUrl, cfg.token);
+  console.log(`[apm] \u8FDE\u63A5 ${cfg.baseUrl} \u2026`);
+  await new Promise((resolve5, reject) => {
+    const ws = new WebSocket(url);
+    let stopHeartbeat;
+    let shuttingDown = false;
+    const shutdown = (code = 0) => {
+      if (shuttingDown) return;
+      shuttingDown = true;
+      stopHeartbeat?.();
+      if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+        ws.close();
+      }
+      resolve5();
+      if (code !== 0) {
+        process.exit(code);
+      }
+    };
+    ws.on("open", () => {
+      console.log("[apm] WebSocket \u5DF2\u8FDE\u63A5");
+      stopHeartbeat = startHeartbeat(ws, cfg.userId);
+    });
+    ws.on("message", (data) => {
+      const text = Buffer.isBuffer(data) ? data.toString("utf8") : String(data);
+      void handleInboundMessage(cfg, text);
+    });
+    ws.on("close", (code, reason) => {
+      console.log(
+        `[apm] \u8FDE\u63A5\u5DF2\u65AD\u5F00 code=${code}${reason ? ` reason=${reason.toString()}` : ""}`
+      );
+      shutdown();
+    });
+    ws.on("error", (err) => {
+      console.error("[apm] WebSocket \u9519\u8BEF:", err.message);
+      reject(err);
+    });
+    process.on("SIGINT", () => {
+      console.log("[apm] \u6B63\u5728\u5173\u95ED\u2026");
+      shutdown();
+    });
+    process.on("SIGTERM", () => shutdown());
+  });
+}
+
 // src/commands/deploy/backend.ts
 import path5 from "node:path";
 
 // src/commands/deploy/internal/apm-config.ts
-import { existsSync as existsSync4, readFileSync as readFileSync5 } from "node:fs";
-import { resolve as resolve3 } from "node:path";
+import { existsSync as existsSync5, readFileSync as readFileSync5 } from "node:fs";
+import { resolve as resolve4 } from "node:path";
 function loadApmConfig(options) {
-  const p = resolve3(
+  const p = resolve4(
     process.cwd(),
-    options?.configPath ?? resolve3(workspaceApmDir(), "apm.config.json")
+    options?.configPath ?? resolve4(workspaceApmDir(), "apm.config.json")
   );
-  if (!existsSync4(p)) {
+  if (!existsSync5(p)) {
     console.error(`\u672A\u627E\u5230\u914D\u7F6E\u6587\u4EF6\uFF1A${p}`);
     process.exit(1);
   }
@@ -888,7 +1255,7 @@ import path4 from "node:path";
 import Docker from "dockerode";
 
 // src/commands/deploy/internal/backend-deploy/dockerode-client/connection-options.ts
-import { existsSync as existsSync5, readFileSync as readFileSync6 } from "node:fs";
+import { existsSync as existsSync6, readFileSync as readFileSync6 } from "node:fs";
 import path from "node:path";
 function asOptionalTlsBuffer(value) {
   if (typeof value !== "string") {
@@ -900,7 +1267,7 @@ function asOptionalTlsBuffer(value) {
   if (normalized === "") {
     return void 0;
   }
-  if (existsSync5(normalized)) {
+  if (existsSync6(normalized)) {
     return readFileSync6(normalized);
   }
   const looksLikePath = /[\\/]/.test(normalized) || normalized.endsWith(".pem");
@@ -1026,17 +1393,17 @@ var DockerodeClient = class {
     await this.client.getImage(image).remove({ force: true });
   }
   async pullImage(image, auth) {
-    const stream = await new Promise((resolve4, reject) => {
+    const stream = await new Promise((resolve5, reject) => {
       const pullOptions = auth ? { authconfig: auth } : void 0;
       this.client.pull(image, pullOptions, (err, output) => {
         if (err || !output) {
           reject(err ?? new Error("docker pull \u8FD4\u56DE\u7A7A\u8F93\u51FA"));
           return;
         }
-        resolve4(output);
+        resolve5(output);
       });
     });
-    await new Promise((resolve4, reject) => {
+    await new Promise((resolve5, reject) => {
       this.client.modem.followProgress(
         stream,
         (err) => {
@@ -1044,7 +1411,7 @@ var DockerodeClient = class {
             reject(err);
             return;
           }
-          resolve4();
+          resolve5();
         },
         () => void 0
       );
@@ -1111,7 +1478,7 @@ var DockerodeClient = class {
 var createDockerodeClient = (config) => new DockerodeClient(config);
 
 // src/commands/deploy/internal/backend-deploy/dockerode-client/env.ts
-import { existsSync as existsSync6, readFileSync as readFileSync7, statSync as statSync3 } from "node:fs";
+import { existsSync as existsSync7, readFileSync as readFileSync7, statSync as statSync4 } from "node:fs";
 import path2 from "node:path";
 function stripSurroundingQuotes(value) {
   const t = value.trim();
@@ -1128,7 +1495,7 @@ function loadEnvFromFile(envFilePath) {
     return {};
   }
   const targetPath = path2.resolve(envFilePath);
-  if (!existsSync6(targetPath) || !statSync3(targetPath).isFile()) {
+  if (!existsSync7(targetPath) || !statSync4(targetPath).isFile()) {
     return {};
   }
   const raw = readFileSync7(targetPath, "utf-8");
@@ -1302,12 +1669,12 @@ function dockerPushImage(params, cwd) {
 }
 
 // src/commands/deploy/internal/backend-deploy/resolve-dockerfile.ts
-import { existsSync as existsSync7 } from "node:fs";
+import { existsSync as existsSync8 } 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 (!existsSync7(dockerfilePath)) {
+  if (!existsSync8(dockerfilePath)) {
     throw new Error(`Dockerfile \u4E0D\u5B58\u5728\uFF1A${dockerfilePath}`);
   }
   Logger.info("\u2713 Dockerfile \u5B58\u5728");
@@ -1436,11 +1803,11 @@ 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 existsSync8, readFileSync as readFileSync8 } from "node:fs";
-import { join as join8 } from "node:path";
+import { existsSync as existsSync9, readFileSync as readFileSync8 } from "node:fs";
+import { join as join9 } from "node:path";
 function loadApmDotEnvIfPresent() {
-  const p = join8(workspaceApmDir(), ".env");
-  if (!existsSync8(p)) {
+  const p = join9(workspaceApmDir(), ".env");
+  if (!existsSync9(p)) {
     return;
   }
   let text;
@@ -1470,14 +1837,14 @@ function loadApmDotEnvIfPresent() {
 }
 
 // src/commands/deploy/internal/minio.ts
-import { statSync as statSync4 } from "node:fs";
+import { statSync as statSync5 } 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 = statSync4(dir);
+    const st = statSync5(dir);
     return st.isDirectory();
   } catch {
     return false;
@@ -1507,7 +1874,7 @@ async function collectFiles(root) {
       if (e.isDirectory()) {
         await walk(abs, rel);
       } else if (e.isFile()) {
-        const st = statSync4(abs);
+        const st = statSync5(abs);
         out.push({
           absPath: abs,
           relativePath: rel.replace(/\\/g, "/"),
@@ -1569,14 +1936,14 @@ var MinioClient = class {
   async deleteObjectsByPrefix(bucket, prefix) {
     const objectsStream = this.inner.listObjectsV2(bucket, prefix, true);
     const keys = [];
-    await new Promise((resolve4, reject) => {
+    await new Promise((resolve5, reject) => {
       objectsStream.on("data", (obj) => {
         if (obj.name) {
           keys.push(obj.name);
         }
       });
       objectsStream.on("error", reject);
-      objectsStream.on("end", resolve4);
+      objectsStream.on("end", resolve5);
     });
     const chunkSize = 500;
     for (let i = 0; i < keys.length; i += chunkSize) {
@@ -1821,7 +2188,9 @@ function buildProgram() {
   ).action(async () => {
     await runUpdate();
   });
-  program.command("update-skills").description("\u4ECE\u5E73\u53F0\u62C9\u53D6\u5F53\u524D\u7528\u6237\u53EF\u8BBF\u95EE\u6280\u80FD\u5230 .apm/skills/").action(async () => {
+  program.command("update-skills").description(
+    "\u540C\u6B65\u6280\u80FD\u5230 .apm/skills/\uFF1A\u57FA\u7840\u6280\u80FD\u6765\u81EA CLI \u6A21\u677F\uFF0C\u8865\u5145\u6280\u80FD\u6765\u81EA\u5E73\u53F0"
+  ).action(async () => {
     await runUpdateSkills();
   });
   program.command("pull").description(
@@ -1841,6 +2210,11 @@ function buildProgram() {
   program.command("update-message-status").description("\u66F4\u65B0\u5E73\u53F0\u4F1A\u8BDD\u6D88\u606F\u72B6\u6001").requiredOption("--id <messageId>", "\u6D88\u606F ID").requiredOption("--status <status>", "CREATED | TYPING | SUCCESS | FAILED").action(async (opts) => {
     await runUpdateMessageStatus(opts);
   });
+  program.command("connect").description(
+    "\u8FDE\u63A5\u5E73\u53F0 WebSocket\uFF08/ws/agent\uFF09\uFF0C\u7EF4\u6301\u5FC3\u8DF3\u5E76\u5904\u7406\u4E0B\u884C message\uFF08TYPING \u2192 Cursor \u2192 SUCCESS/FAILED\uFF09"
+  ).option("--server <url>", "API \u6839\u5730\u5740\uFF0C\u8986\u76D6 config \u4E2D\u7684 baseUrl").action(async (opts) => {
+    await runConnect(opts);
+  });
   program.command("branch").description("\u5207\u6362\u6216\u521B\u5EFA\u4F1A\u8BDD\u5206\u652F feat/session-<sessionId>").argument("<sessionId>", "\u6C9F\u901A\u7FA4 ID").option(
     "-m, --message <text>",
     "\u5DF2\u5728\u76EE\u6807\u5206\u652F\u4E14\u9700\u63D0\u4EA4\u672C\u5730\u6539\u52A8\u65F6\u4F7F\u7528\u7684\u63D0\u4EA4\u8BF4\u660E"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-project-manage-cli",
-  "version": "5.0.7",
+  "version": "5.0.9",
   "description": "命令行工具：后续用于调用平台后端 API 完成运维与自动化操作",
   "type": "module",
   "private": false,
@@ -18,6 +18,7 @@
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
+    "@types/ws": "~8.5.14",
     "@types/node": "^22.0.0",
     "typescript": "~5.6.0",
     "esbuild": "~0.28.0",
@@ -28,6 +29,8 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@cursor/sdk": "~1.0.17",
+    "ws": "~8.18.0",
     "listpage-http": "~0.0.318",
     "commander": "~14.0.3",
     "yaml": "~2.8.4",

package/template/AGENTS.md

@@ -3,20 +3,26 @@
 ### 回复消息命令
 
 - 命令: `apm append-message --id=<消息ID> --content=<消息内容>`
-- 注意事项：如果消息内容中包含文档地址，不要把前缀也写出来，直接用文档名称即可，并且文档名称要用倒引号包裹
+- 注意事项：
+  - 如果消息内容中包含文档地址，不要把前缀也写出来，直接用文档名称即可，并且文档名称要用倒引号包裹
+  - 这个是补充消息内容，只要消息没有结束，都可以用这个命令来继续补充发言。
 
 ### 创建/更新群文档命令
 
 - 命令: `apm sync-document <会话ID> --file <文档名称>`
-- 注意事项：文档名称是指`.apm/sessions/<会话ID>/` 这个目录下的某个文档，参数直接文档名称，比如 PRD.md。
+- 注意事项：`apm sync-document` 的 `--file` 为**文档名称**（如 `PRD.md`），对应磁盘路径 `.apm/sessions/<会话ID>/docs/PRD.md`（群文档在 `docs/` 下）。
 
 ## 工作流程
 
-- 读取 `.apm/sessions/<会话ID>/session.yaml`，必要时读取`messages.xml` 了解当前会话状态与历史消息
-- 根据用户提示找到你对应的人设(system_persona)
-- 根据人设完成用户指定的任务
+1. 读取 `.apm/sessions/<会话ID>/session.yaml`，必要时读取`messages.xml` 了解当前会话状态与历史消息
+2. 根据你的名字从 session.yaml 中找到你对应的人设(system_persona)
+3. 根据人设完成用户指定的任务
+4. 任务有阶段行进展或者任务完成后必须使用 `apm append-message` 回复消息
 
 ## 目录声明
 
-- 技能目录: ./skills
-- 群文档目录: ./sessions/<会话 ID>/docs
+- APM 指南: `.apm/AGENTS.md`
+- 技能: `.apm/skills/<技能名称>/SKILL.md`，当 `system_persona` 依赖相关技能时可以在这里按需查找
+- 群文档: `.apm/sessions/<会话 ID>/docs/xxxx.md`，当需要相关上下文可以在这里查找
+- 协作规则: `.apm/sessions/<会话 ID>/RULE.md`，在这里可以看到不同成员的协作规则
+- 历史消息记录: `.apm/sessions/<会话 ID>/message.xml`，当需要查看历史消息记录时可以阅读这个文档

package/template/skills/apm-apply-change/SKILL.md

@@ -0,0 +1,178 @@
+# APM 工作项：按任务实现
+
+根据工作项目录下的 **`tasks.md`** 驱动实现：**读规划 → 做代码 → 对账元数据 → 勾选 → 单独 commit**，直至全部完成或遇硬阻塞；上下文以 **`.apm/sessions/<sessionId>/`** 内文件为准。
+
+---
+
+## 输入
+
+若本轮未提供 `sessionId`：
+
+1. 若对话中已能**唯一**确定工作项目录名，则用之。
+2. 否则直接停止工作即可，**不要**调用 AskUserQuestion，**不要**停下来让用户当场选择。
+
+## 停止执行（优先于继续推进）
+
+若在实施过程中**发现**任一情况，**立即停止**本技能所驱动的后续实现与勾选（不再继续下一项任务），仅在会话中输出：
+
+1. **客观事实**：已读到的文件/路径、与代码或任务条目的**具体矛盾点**（可摘引，避免主观评价）。
+2. **当前进度**：处理到 `tasks.md` 的哪一条、仓库是否已有未提交改动（若有，说明范围）。
+3. **需要用户提供什么**：为继续推进所**缺的信息或决策**（例如：以何者为准、是否接受某类改动、需确认的业务口径）。用**清单**列出，**一句一项**。
+
+**禁止**：给出「建议你先改 A / 再改 B」「可选方案 1/2/3」「宜采用…」等**替用户决策**或**行动建议**；不指导用户如何改文档、不预设优先级。
+
+**允许**：描述「若不补充某信息则无法继续」的**逻辑关系**（仍不展开成方案）。
+
+---
+
+## 工作项路径与必备文件
+
+- **根路径**：**`.apm/sessions/<sessionId>/`**
+- **必备**：**`tasks.md`**（含 `- [ ]` / `- [x]` 待办）。若不存在或无可执行条目：**阻塞**，说明须先完成 **apm-propose**（或手工补齐 `tasks.md`）。
+- **强烈建议读**：**`docs/PRD.md`**（`.apm/sessions/<sessionId>/docs/PRD.md`，范围与验收）；实现时按需 **Read** **`proposal.md`**、**`design.md`**、**`specs/`**（与 **`tasks-instruction.md`** 中每条任务的元数据一致）。
+- **进度**：仅由 **`tasks.md`** 中复选框统计「已完成 / 总数」。
+
+### 单会话读取（可选减负）
+
+同一轮连续执行多项任务时：**`docs/PRD.md` / `design.md` / 各 spec** 若已在会话内读过且无疑虑，不必每个任务重复全文 Read；以**当前任务行**及元数据指向的 spec/设计段落为准，必要时对文件 **Read（偏移）** 或再读全文。
+
+---
+
+## Steps
+
+### 1. 锚定工作项
+
+确定 **`sessionId`** 与工作项根路径；声明 **使用工作项：`<sessionId>`**（若依上节规则自动选定，须说明如何覆盖）。
+
+### 2. 读取 `tasks.md` 并判断状态
+
+- **Read** **`.apm/sessions/<sessionId>/tasks.md`**。
+- 若文件缺失、为空、或无任何 `- [ ]`：**停止**，提示先具备可执行 `tasks`（规划阶段）。
+- 若全部已为 `- [x]`：**可**直接汇报「已全部完成」（仅作事实陈述，不建议是否提交或发 MR）。
+
+### 3. 读取实现上下文（按任务需要）
+
+开始**第一个**未勾选任务前，至少 **Read**：
+
+- **`docs/PRD.md`**（`.apm/sessions/<sessionId>/docs/PRD.md`；若存在，与验收相关条款）
+- 与任务相关的 **`design.md`** 片段、**`specs/`** 下对应文件（见任务条目的 **需求编号** / 描述）
+
+不要求每次任务都重读全部规划文件；以 **`tasks.md` 当前项** + **缺口再 Read** 为准。
+
+### 4. 展示当前进度
+
+在对话中简要展示：
+
+- **工作项**：`sessionId`
+- **进度**：「N/M 个任务已完成」（由 `tasks.md` 勾选统计）
+- **当前将处理**：下一条 `- [ ]` 的摘要（含组号/编号如 `2.1`）
+
+### 5. 实现任务（循环直至完成或阻塞）
+
+对每一条 **未勾选** 任务（建议按 `tasks.md` 自上而下顺序）：
+
+1. **说明**正在处理哪一项（编号 + 简述）。
+2. **实现**所需代码/配置/迁移等；改动保持**最小**、与该项描述一致。
+3. **标记完成前**在回复或备注中收集依据（与 **`tasks-instruction.md`** 子列表字段对齐即可）：
+   - **需求编号**：本实现对应 specs / tasks 中的哪条需求或场景。
+   - **预期改动路径** 与 **实际改动文件**：若有合理偏差，简要说明原因。
+   - **验证用例编号**（若任务中有）。
+   - **验证结果** / **完成标准**：如何确认本项已达成（可简短）。
+4. 仅在依据已齐、且自洽通过后，将 **`tasks.md`** 中对应行 **`- [ ]` 改为 `- [x]`**。
+5. **Git**：本待办对应的**实现 + 勾选**等改动，**单独 `git commit` 一次**（**一项待办 = 一个 commit**；勿把多项待办混在同一 commit）。提交信息建议包含 `requirementId` 与任务编号或简述。
+
+**何时停止（不继续下一项）**——与上文 **「停止执行」** 一致：
+
+- **`design` / `specs` / `tasks` 与当前代码或彼此严重不一致**，以致无法按任务字面含义在**不臆造**的前提下完成 → **按「停止执行」输出**（事实 + 需用户提供的材料），**不**建议先改哪份文档、不改哪些。
+- 命令失败、环境错误、权限等**硬阻塞** → 说明原因、失败点、已执行步骤；**不**给排障步骤或替代命令建议（除非任务本身要求执行某命令且该命令已写在任务/文档中）。
+- 用户中断。
+
+**何时仍可继续**（仅当满足）：任务表述略含糊，但可在 **docs/PRD.md / design / specs / tasks** 已有文字内**自洽**完成；若有**假设**，在回复中写清**假设**（仍不反问）。一旦假设会触及「以谁为准」的**产品/架构决策**，转 **「停止执行」**。
+
+### 6. 完成或暂停时展示状态
+
+- **本会话**完成了哪些任务（可列勾选项摘要）。
+- **总体进度**：「N/M 个任务已完成」。
+- 若**全部完成**：仅陈述事实（进度与勾选状态），**不**建议后续流程（MR/发布/归档等）。
+- 若**暂停**：按 **「停止执行」** 或硬阻塞格式输出，**无**「可选后续」或方案建议。
+
+---
+
+## 实现过程中的输出（示例）
+
+```
+## 正在实施：<sessionId>
+
+处理任务 3/7：2.1 实现导出接口
+[...实现过程...]
+✓ 任务完成 · commit <short-sha> <subject>
+
+处理任务 4/7：2.2 …
+```
+
+---
+
+## 全部完成时的输出（示例）
+
+```
+## 实现完成
+
+**工作项：** <sessionId>
+**进度：** 7/7 个任务已完成 ✓
+
+### 本会话已完成
+- [x] …
+- [x] …
+
+（每项待办均已对应独立 commit。）
+```
+
+---
+
+## 暂停时的输出（示例）
+
+```
+## 实现已暂停
+
+**工作项：** <sessionId>
+**进度：** 4/7 个任务已完成
+
+### 事实与原因
+<客观描述：文件/行/与任务或代码的矛盾点>
+
+### 需要用户提供（或决策）
+- …
+- …
+```
+
+（无方案列表、无「建议」；用户补充信息后可再次运行本技能。）
+
+---
+
+## 约束
+
+- 持续执行待办直至完成、**停止执行**或硬阻塞。
+- 开始前须已能对照 **`tasks.md`** 与 **`docs/PRD.md`**（及任务所需的 design/spec）；**不要**在未读清当前任务依赖时盲改。
+- 任务表述有歧义时，仅在**无需用户决策**的前提下依据 **specs / design / docs/PRD.md** 推断；一旦涉及**以谁为准**或**严重不一致**，**停止执行**（见上文）。
+- **不**因「发现规划与代码不符」而**主动建议**修改 `design.md` / `specs/` / `tasks.md`；**停止**并说明事实与需用户提供的材料即可。
+- 代码改动保持最小、与**当前任务**范围一致。
+- 未完成需求/验证对账前，**不要**将任务勾为完成。
+- 验证失败或依据不足时，保持 **`- [ ]`**，并明确写出缺口。
+- 若任务元数据缺失（需求编号、预期改动路径、完成标准等），在可能范围内于实现前**补全或按 tasks 模板推断**，并在说明中注明。
+- 每完成一项任务并记录依据后，**立即**更新勾选并**随即**单独 `git commit`。
+- 遇硬阻塞时暂停并说明原因（**不**给出替代命令或排查建议，除非任务/文档已写明）；
+- 需求不清且无法自洽推断时，**停止执行**并列出需用户提供的材料；**不反问用户**。
+
+---
+
+## 与规划流程的衔接
+
+- **`tasks.md`** 须由 **apm-propose**（或等价流程）生成并符合 **`tasks-instruction.md`** 格式（`- [ ]`、元数据子列表等），否则本技能无法可靠追踪。
+- 若执行中发现 **`design` / `specs` 与代码严重不一致**：**停止执行**，按上文输出事实与**需用户提供**的决策/信息；**不**建议先改哪类工件、不代用户排优先级。
+
+---
+
+## 流动工作流
+
+- **可分段调用**：可在部分任务完成后结束会话，下次同一工作项继续。
+- **规划修订**：由用户在**流程外**修订 `design.md` / `specs/` / `tasks.md` 后，再触发本技能；本技能执行中**不因发现不符**而主动改规划文件或提出修改方案。

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

@@ -0,0 +1,21 @@
+## 工作流程
+
+### 步骤1: 阅读部署文档  
+
+使用**Read**工具阅读 `.apm/deploy/README.md`（这个目录可能被忽略了，也可能不存在）
+
+### 步骤2: 判断能否部署
+
+遇到以下情况拒绝部署，直接退出即可
+1. 没有找到部署文档，或者部署文档没有可执行的部署命令（或者说部署不可执行）
+2. 用户没有明确部署环境
+
+### 步骤3: 按照文档执行部署
+
+**严格对照** README：顺序、工作目录（若文档指定 `cd`）、环境变量、所用 CLI（如 `rush`、`docker`、`kubectl` 等）均以文档为准；将步骤 3 得到的 **`env` 等**按 README 约定注入命令或环境（禁止凭猜测填值）。**默认在 `<repoRoot>` 执行**；
+
+## Guardrails
+
+- **gitignore 不等于不存在**：`.apm` 下文件可能不入 Git 索引；**禁止**用「搜索无结果」代替 **Read** 或磁盘校验。
+- **不臆造**：README 未写的命令、环境、目标集群/命名空间，**不补充**；工作项 YAML **未提供**的字段**不得**编造。
+- **不报假成功**：命令失败或未完成 README 目标时，结论必须为「否」或等价表述。

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

@@ -0,0 +1,28 @@
+## 工作流程
+1. 选择开发模式：**Quick/Spec**
+
+**Quick 开发**（满足越多越适用）: 
+    - 影响范围局部：少量文件或单一层次（例如仅前端组件、或仅一个后端模块小改）。
+    - 无新表结构/大规模迁移/权限模型变更。
+    - PRD 验收点清晰且数量少（经验上 **≤3** 条独立验收维度）。
+    - 不需要跨多服务的架构裁定即可开工。
+**Spec 开发**：（命中任一条即可）：
+    - 前后端联动、多包改造或新公共抽象。
+    - 新数据模型、迁移、或安全/审计/权限相关。
+    - PRD 范围大、条款多，或存在明显「待确认/多方案」需先规划。
+    - 评估认为不先产出 **proposal / design / specs / 
+
+2. 如果为 **Quick 开发**（子Agent中）执行：
+
++ 父 Agent 已通过 **Read** 掌握 `PRD.md`；若启动新子 Agent，在委派提示中写明会话ID、消息ID、工作项路径、以及「实现须严格对照 PRD，改动范围最小化」。
++ 使用 **Task** 工具，`subagent_type: generalPurpose`，**readonly: false**，委派子 Agent：
+    - 按需 **Read** `.apm/sessions/<会话ID>/docs/PRD.md`
+    - 按 PRD 直接改代码；遵守本仓库构建与依赖约定（AGENTS.md）。
+    - 完成后在返回中说明：改了哪些路径、如何对照验收、是否通过本地可执行的检查（若子 Agent 跑了 `rushx build` / 测试等则写明结果）。
+
+3. 如果为  **Spec 开发** （子Agent中）执行：
+
+- 父 Agent **Read** **apm-propose**、**apm-apply-change** 的 `SKILL.md`（**仅** `.apm/skills/` 下路径，见上节）。
+- **子 Agent A（规划）**：Task `generalPurpose`，提示其自行 **Read** `.apm/skills/apm-propose/SKILL.md` 并完整遵循：在 `.apm/sessions/<sessionId>/` 生成 **proposal、design、specs、tasks** 等工件（顺序与依赖以 SKILL 为准）。
+- **子 Agent B（实现）**：待 A 成功落盘后，再 Task `generalPurpose`，提示其自行 **Read** `.apm/skills/apm-apply-change/SKILL.md` 并完整遵循：按 **`tasks.md`** 驱动实现与勾选；遵守该技能中的停止条件与 commit 约定。
+- 若 **apm-propose** 未产出可用 **`tasks.md`**，不得强行进入 **apm-apply-change**；表格中标记阻塞原因。

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

@@ -0,0 +1,191 @@
+# APM 工作项：规划工件
+
+在 `.apm/sessions/<sessionId>/docs/PRD.md` 上生成 **proposal → design / specs → tasks** 四类规划工件。各工件写什么、依赖谁，见下方对应章节；**不要**把 SKILL 说明或内部推理写进产出文件。
+
+---
+
+## 输入
+
+| 字段            | 规则                                                   |
+| --------------- | ------------------------------------------------------ |
+| **`sessionId`** | **必填**。与 `.apm/sessions/<sessionId>/` 目录名一致。 |
+| **需求正文**    | **唯一权威**：`.apm/sessions/<sessionId>/docs/PRD.md`。 |
+
+用户补充仅在与 PRD 兼容时写入，并标注 **「会话补充（PRD 未载明）」**。PRD 未写明的**不反问用户**，写入后续工件的假设 / 待确认。
+
+---
+
+## 流程
+
+**顺序**：`proposal` → `design` 与 `specs`（可并行，均依赖 proposal；specs 不依赖 design）→ `tasks`（依赖 design 与 specs 均已落盘）。
+
+用 **TodoWrite** 跟踪四工件（`ready` / `blocked` / `done`），**每完成一工件即落盘并标 `done`**；依赖未满足时**不得**写下一工件。
+
+1. **Read `docs/PRD.md` 全文**（路径：`.apm/sessions/<sessionId>/docs/PRD.md`）；必要时 **SemanticSearch** / **Read** 仓库代码，便于 tasks 中 **预期改动路径** 可落地。
+2. 按解锁顺序撰写各工件（见下方章节）。
+3. 全部完成后汇总：工作项路径、已创建文件、PRD 与各工件的对应关系（一两句）；回复含各工件一句话用途。
+
+### 单会话读取策略
+
+同一会话连续跑完时，可省略重复 Read，但**不得**省略依赖关系；断点续写或新会话须按各工件「依赖」重新 Read 磁盘文件。
+
+| 文件                   | 建议                                                              |
+| ---------------------- | ----------------------------------------------------------------- |
+| `docs/PRD.md`          | 进入流程时至少读一次全文；后续按需再读。                          |
+| `proposal.md`          | 落盘后写 design/specs 时，若会话内已有刚写入的全文可不重复 Read。 |
+| `design.md` / `specs/` | 写 tasks 时若无可靠记忆须 Read；以落盘文件为准。                  |
+
+---
+
+## proposal 工件
+
+**路径**：`.apm/sessions/<sessionId>/proposal.md`
+
+**依赖**：`docs/PRD.md`（全文）
+
+以 PRD 为事实来源写变更提案（**Why**，不写实现细节）。精短即可。
+
+**Capabilities** 是 proposal 与 specs 的契约：每一项须在后续 `specs/` 可追溯。
+
+- **New Capabilities**：每条对应 `specs/<kebab-name>.md`（如 `user-auth`）。
+- **Modified Capabilities**：规格层行为变更；无则写「无」。
+
+```markdown
+## Why
+
+<!-- 1～2 句：解决什么、为何是现在 -->
+
+## What Changes
+
+<!-- 变更要点；破坏性变更标注 BREAKING -->
+
+## Capabilities
+
+### New Capabilities
+
+- `<name>`: <brief description>
+
+### Modified Capabilities
+
+- `<existing-name>`: <what requirement behavior changes> <!-- 无则写 无 -->
+
+## Impact
+
+<!-- 受影响代码、API、依赖、系统 -->
+```
+
+---
+
+## design 工件
+
+**路径**：`.apm/sessions/<sessionId>/design.md`
+
+**依赖**：`docs/PRD.md`、`proposal.md`
+
+说明 **如何实现**（HOW）：架构与决策，不写逐行代码，不替代 tasks 里的步骤枚举。
+
+跨模块、新依赖、安全/性能/迁移复杂或方案待拍板时写完整版；否则可精简，但保留 **Context** 与 **Decisions**。
+
+```markdown
+## Context
+
+## Goals / Non-Goals
+
+**Goals:**
+**Non-Goals:**
+
+## Decisions
+
+<!-- 每项：备选 + 取舍理由 -->
+
+## Risks / Trade-offs
+
+<!-- [风险] → 缓解 -->
+
+## Migration Plan
+
+<!-- 无则写 无 / 不适用 -->
+
+## Open Questions
+
+<!-- 无则写 无 -->
+```
+
+---
+
+## specs 工件
+
+**路径**：`.apm/sessions/<sessionId>/specs/`
+
+**依赖**：`docs/PRD.md`、`proposal.md`（不依赖 design）
+
+定义系统 **应做什么**；与 proposal **Capabilities** 逐条对齐，**不得**虚构 PRD/proposal 未出现的能力。
+
+**文件组织**：一能力一文件 `specs/<短横线名称>.md`（或 `specs/<名称>/规格.md`，同一工作项内择一，勿混用）。
+
+**结构**：
+
+- 分块（`##`）：**新增需求** / **变更需求** / **移除需求** / **重命名需求**（按需组合；纯新增只用「新增需求」）。
+- 需求：`**### 需求：<名称>**`；行为用 **须、必须**。
+- 场景：`**#### 场景：<名称>**`（固定四个 `#`）；正文 `- **当** …` / `- **则** …`。
+- **每条需求至少一个场景**；变更需求须写**完整替换段落**（从需求到全部场景），禁止只贴片段。
+
+```markdown
+## 新增需求
+
+### 需求：<名称>
+
+系统须 …
+
+#### 场景：<名称>
+
+- **当** …
+- **则** …
+
+## 变更需求
+
+<!-- 完整替换后的需求 + 全部场景 -->
+
+## 移除需求
+
+### 需求：<名称>
+
+**原因**：… **迁移说明**：…
+
+## 重命名需求
+
+- **原名称：** … **新名称：** …
+```
+
+---
+
+## tasks 工件
+
+**路径**：`.apm/sessions/<sessionId>/tasks.md`
+
+**依赖**：`docs/PRD.md`、`proposal.md`、`design.md`、`specs/`
+
+拆成可勾选待办；**apm-apply-change** 依赖 `- [ ]` / `- [x]` 推进。
+
+**格式**：
+
+- 行首 **`- [ ]`**；分组 **`## 1. 名称`**；编号 **`- [ ] 1.1 说明`**（组号.序号）。
+- 每项下方缩进子列表：**需求编号**（对应 specs 中需求/场景）、**预期改动路径**、**验证用例编号**（可选）、**完成标准**。
+- **做什么**以 specs 为准，**改哪里**以 design 为准；按技术依赖排序。
+
+```markdown
+## 1. 数据层
+
+- [ ] 1.1 新增合同状态字段
+  - **需求编号**：需求：合同状态同步（见 specs/contract.md）
+  - **预期改动路径**：`servers/be/prisma/schema.prisma`
+  - **完成标准**：迁移可执行；已有合同默认状态正确
+```
+
+---
+
+## Guardrails
+
+- 后写须与 PRD 及已落盘前序文件一致。
+- 四个工件缺一不可（specs 至少一个 `.md`）；落盘非空后再进下一工件。
+- **默认不覆盖**已有规划文件；用户明确要求「整目录覆盖重生成」时除外。

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

@@ -0,0 +1,30 @@
+## 输入
+
+需求文档：使用 **Read** 工具读 `.apm/sessions/<sessionId>/docs/PRD.md`；若文档存在才进行下面的需求评审流程，否则直接退出并输出：没有看到需求内容。
+
+## 评审目标
+
+1. 梳理需求边界：发现文档中未写清的口径
+2. 调研实现难度：在实现难度较高时给出提示
+3. 禁止为了凑问题而提问，当 PRD 已足够清晰且无高难度改造时，可直接说此需求没问题
+4. 你只需要站在自己的角度去评审，禁止站在全局思考问题。结合代码进行评审即可：
+   - 前端关注 UI 交互还原，交互逻辑的各种边界，不考虑一些与后端接口之类的问题
+   - 后端则关注数据表设计，需求对应的数据接口是否合理，能否获取
+   - 全栈则关注前面两者，可以把这些问题合并起来提出来
+
+**难度高的定义**：预估改动的文件可能比较多，超过 10 个；或者改动逻辑比较复杂；
+
+## 表达规范
+
+1. **产品语言优先**：页面定位用「医德考评弹窗」「行风办审批页」等说法；**禁止**用文件路径、组件名、函数名作为论据主体。
+2. **后端可略宽**：必要时可写**表名 / 主表字段名**帮助产品理解数据口径，但仍避免贴大段代码或接口路径。
+3. **锚定 PRD**：当需要引用到需求文档中的某一条时可以直接说行号，比如：需求原文[1-3]说 xxx；
+4. **问题 = 文档缺口**：只写 PRD **未写清**且**影响本端理解边界**的点。已写清楚的规则不要重复质疑。
+
+## 工作流程
+
+### 步骤 1: 读取 PRD 内容，具体见第一节输入输入
+
+### 步骤 2: 理解代码，评估 PRD
+
+### 步骤 3: 回复用户

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

@@ -0,0 +1,69 @@
+## 输入
+1. 口头需求要求：如果是用户口头需求要求则根据下面需求模板编写PRD
+2. 已有PRD+用户提要求：这个场景是润色现有的PRD文档，一般是原有PRD中的一些问题被解决了
+
+**注意**：
+- 编写/润色PRD时禁止提出额外的问题，一切以用户要求为准。
+- 已有PRD的地址为:  `../../sessions/<需求ID>/docs/PRD.md`，可用 **Read** 工具读取。
+- 需求要始终保持干净，模板规定以外的，比如历史沟通记录不需要
+
+## 工作流程
+### 步骤1: 读取PRD
+### 步骤2: 按照下面的模板要求编写PRD
+### 步骤3: 同步PRD到远程
+
+
+## 需求模板
+### 正文骨架
+```markdown
+## 背景
+（1 ～ 3 句：业务背景、要解决的问题、预期效果，如果没有可空着，不要强行编）
+
+## 范围
+- **包含**：…
+- **不包含**：…
+
+## 需求说明
+
+### 需求点 1：[简短名称]
+- …
+- …
+
+### 需求点 2：…
+```
+
+### 需求点编写规范
+
+每条 bullet 写清一个可验收点，优先覆盖：
+
+| 类型      | 写法要点                                               |
+| --------- | ------------------------------------------------------ |
+| 展示/选项 | 展示或隐藏；保留/去掉哪些选项；新建默认值              |
+| 文案      | 原名称 → 新名称；界面、提示、校验文案一并统一          |
+| 按钮      | 场景 + 按钮名 + 行为（对照哪个既有按钮、是否仅改文案） |
+| 校验      | 场景 + 字段展示条件 + 必填时机（暂存 / 提交分别怎样）  |
+| 边界      | **不考虑** …（历史数据、迁移、导出等明确排除项）       |
+
+材料中的技术名可译为业务表述，例如：`audit1` → 一级审批；保存不推进流程 → **暂存**；办理并推进流程 → **提交**。
+
+编写示例如下：
+
+```markdown
+### 需求点 2：新增/编辑弹窗底部操作
+
+- 在**新增、编辑**场景下，弹窗底部新增 **「暂存」** 按钮。
+- **「暂存」**：沿用原 **「确定」** 按钮的业务逻辑（含校验与保存/流程行为），**仅将按钮展示文案改为「暂存」**。
+
+### 需求点 3：「科室医德考评小组人员名单」字段
+
+- 原字段展示名 **「科室医德考评人员名单」** 统一改为 **「科室医德考评小组人员名单」**；凡界面、提示、校验文案等涉及该名称处**一并修改**。
+- 当流程处于 **一级审批** 且该字段**展示**时，须校验为**必填**（在展示场景下触发，而非所有保存入口一律校验）。
+```
+
+### 自检列表
+- [ ] 含 **背景与目标、范围、需求说明** 三章，叙述完整
+- [ ] 2 分钟内可通读；每个需求点 2 ～ 5 条 bullet，一层列表
+- [ ] 场景、按钮行为、校验时机表述清楚，前后一致
+- [ ] 「范围」与需求点中的 **「不考虑」** 口径一致
+- [ ] 全文使用业务语言，术语统一
+- [ ] 仅材料明确涉及时才有「非功能」「待确认」