ai-project-manage-cli 7.1.12 → 7.1.13

package/dist/webide-message-worker.js

@@ -1,5 +1,5 @@
 // src/commands/connect/webide-message-worker.ts
-import { parentPort, workerData } from "node:worker_threads";
+import { parentPort as parentPort2, workerData } from "node:worker_threads";
 
 // src/api/client.ts
 import { createApiClient } from "listpage-http";
@@ -100,6 +100,22 @@ var requestConfig = {
       method: "PUT",
       path: "/cli/webide/test-cases"
     }),
+    webideListTerminals: defineEndpoint({
+      method: "GET",
+      path: "/cli/webide/terminals"
+    }),
+    webideUpsertTerminal: defineEndpoint({
+      method: "POST",
+      path: "/cli/webide/terminals"
+    }),
+    webideUpdateTerminalStatus: defineEndpoint({
+      method: "PUT",
+      path: "/cli/webide/terminals/status"
+    }),
+    webideUpdateTerminalMeta: defineEndpoint({
+      method: "PUT",
+      path: "/cli/webide/terminals/meta"
+    }),
     branchBaseline: defineEndpoint({
       method: "GET",
       path: "/cli/tasks/branch-baseline"
@@ -1559,13 +1575,13 @@ ${payload}`;
 function createMergeWebIdePullRequestsTool(options) {
   const { cfg, taskId } = options;
   return {
-    description: "Merge all open pull requests for this WebIDE task after conflicts are resolved locally and pushed. Call once with no arguments. Do NOT call if conflicts contradict the task requirements \u2014 report the conflict and fail instead.",
+    description: "Merge all open pull requests for this WebIDE task. Call once with confirmedConflictFree=true. No baseline sync or review is required before calling.",
     inputSchema: {
       type: "object",
       properties: {
         confirmedConflictFree: {
           type: "boolean",
-          description: "Must be true: you have checked each repo, resolved mergeable conflicts consistently with requirements, and pushed. If conflicts contradict requirements, do not call this tool."
+          description: "Must be true to confirm you intend to merge this task's open PRs now."
         }
       },
       required: ["confirmedConflictFree"]
@@ -1573,7 +1589,7 @@ function createMergeWebIdePullRequestsTool(options) {
     execute: async (args) => {
       if (args.confirmedConflictFree !== true) {
         throw new Error(
-          "MergeWebIdePullRequests \u8981\u6C42 confirmedConflictFree=true\u3002\u82E5\u5B58\u5728\u4E0E\u9700\u6C42\u76F8\u6096\u7684\u51B2\u7A81\uFF0C\u8BF7\u52FF\u8C03\u7528\u672C\u5DE5\u5177\uFF0C\u7528 AppendMessage \u8BF4\u660E\u5E76\u5931\u8D25\u7ED3\u675F\u3002"
+          "MergeWebIdePullRequests \u8981\u6C42 confirmedConflictFree=true\u3002"
         );
       }
       const api = createApmApiClient(cfg);
@@ -1738,6 +1754,164 @@ function createUpsertWebIdeTestCasesTool(options) {
   };
 }
 
+// src/commands/connect/webide-terminal-tools.ts
+function asString3(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+function asPorts(value) {
+  if (!Array.isArray(value)) return void 0;
+  const ports = value.map((p) => typeof p === "number" ? p : Number(p)).filter((p) => Number.isFinite(p) && p > 0 && p < 65536).map((p) => Math.trunc(p));
+  return ports.length ? ports : void 0;
+}
+function createWebIdeTerminalTools(options) {
+  const { cfg, taskId, workdir, rpc } = options;
+  const StartWebIdeTerminal = {
+    description: "Start a long-running WebIDE terminal (e.g. frontend/backend dev server). Process outlives this message. Same key already RUNNING/READY returns idempotently. Do NOT use Shell for long-lived dev servers. Returns terminalId, pid, ports.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        key: {
+          type: "string",
+          description: "Stable key, e.g. frontend / backend"
+        },
+        name: { type: "string", description: "Display name" },
+        cwd: {
+          type: "string",
+          description: "Working directory (absolute or under workspace)"
+        },
+        command: {
+          type: "string",
+          description: "Shell command to run, e.g. pnpm dev"
+        },
+        readyPattern: {
+          type: "string",
+          description: "Optional regex; when matched in logs, status becomes READY"
+        },
+        portsHint: {
+          type: "array",
+          items: { type: "number" },
+          description: "Optional expected listen ports"
+        }
+      },
+      required: ["key", "cwd", "command"]
+    },
+    execute: async (args) => {
+      const key = asString3(args.key);
+      const cwd = asString3(args.cwd) || workdir;
+      const command = asString3(args.command);
+      if (!key || !command) {
+        return {
+          content: [{ type: "text", text: "key / command \u4E0D\u80FD\u4E3A\u7A7A" }],
+          isError: true
+        };
+      }
+      try {
+        const result = rpc ? await rpc.start({
+          taskId,
+          key,
+          name: asString3(args.name) || void 0,
+          cwd,
+          command,
+          readyPattern: asString3(args.readyPattern) || void 0,
+          portsHint: asPorts(args.portsHint)
+        }) : await (async () => {
+          throw new Error("Terminal RPC \u4E0D\u53EF\u7528\uFF08\u9700\u5728 connect \u4E3B\u8FDB\u7A0B\uFF09");
+        })();
+        return JSON.stringify(result, null, 2);
+      } catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `\u542F\u52A8\u7EC8\u7AEF\u5931\u8D25: ${detail}` }],
+          isError: true
+        };
+      }
+    }
+  };
+  const StopWebIdeTerminal = {
+    description: "Stop a WebIDE terminal and kill its process tree. Soft-terminates (status EXITED, record kept).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        key: { type: "string", description: "Terminal key" },
+        terminalId: { type: "string", description: "Server terminal id" }
+      }
+    },
+    execute: async (args) => {
+      const key = asString3(args.key) || void 0;
+      const terminalId = asString3(args.terminalId) || void 0;
+      if (!key && !terminalId) {
+        return {
+          content: [{ type: "text", text: "\u9700\u8981 key \u6216 terminalId" }],
+          isError: true
+        };
+      }
+      try {
+        const result = rpc ? await rpc.stop({ taskId, key, terminalId }) : await (async () => {
+          throw new Error("Terminal RPC \u4E0D\u53EF\u7528\uFF08\u9700\u5728 connect \u4E3B\u8FDB\u7A0B\uFF09");
+        })();
+        return JSON.stringify(result, null, 2);
+      } catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `\u505C\u6B62\u7EC8\u7AEF\u5931\u8D25: ${detail}` }],
+          isError: true
+        };
+      }
+    }
+  };
+  const StopAllWebIdeTerminals = {
+    description: "Stop all living WebIDE terminals for the current task (kill process trees). Use before re-running local dev to avoid port conflicts. Soft-terminates records.",
+    inputSchema: {
+      type: "object",
+      properties: {}
+    },
+    execute: async () => {
+      try {
+        const result = rpc ? await rpc.stopAll({ taskId }) : await (async () => {
+          throw new Error("Terminal RPC \u4E0D\u53EF\u7528\uFF08\u9700\u5728 connect \u4E3B\u8FDB\u7A0B\uFF09");
+        })();
+        return JSON.stringify(result, null, 2);
+      } catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `\u5168\u90E8\u505C\u6B62\u5931\u8D25: ${detail}` }],
+          isError: true
+        };
+      }
+    }
+  };
+  const ListWebIdeTerminals = {
+    description: "List living WebIDE terminals for the current task (STARTING/RUNNING/READY/STOPPING only). Does NOT include EXITED/FAILED. Returns id, key, status, pid, ports.",
+    inputSchema: {
+      type: "object",
+      properties: {}
+    },
+    execute: async () => {
+      try {
+        if (rpc) {
+          const result2 = await rpc.list({ taskId });
+          return JSON.stringify(result2, null, 2);
+        }
+        const api = createApmApiClient(cfg);
+        const result = await api.cli.webideListTerminals({ taskId });
+        return JSON.stringify(result, null, 2);
+      } catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `\u5217\u51FA\u7EC8\u7AEF\u5931\u8D25: ${detail}` }],
+          isError: true
+        };
+      }
+    }
+  };
+  return {
+    StartWebIdeTerminal,
+    StopWebIdeTerminal,
+    StopAllWebIdeTerminals,
+    ListWebIdeTerminals
+  };
+}
+
 // src/commands/connect/cursor-custom-tools.ts
 var PLAN_MODE_ASK_QUESTION_HINT = `[SDK \u73AF\u5883\u8BF4\u660E]
 AskQuestion \u5DF2\u901A\u8FC7 MCP \u670D\u52A1\u5668 custom-user-tools \u6CE8\u518C\uFF0C\u5DE5\u5177\u540D\u4E3A AskQuestion\u3002
@@ -1775,6 +1949,17 @@ function createCursorCustomTools(cfg, messageId, options) {
       cfg,
       taskId: options.taskId
     });
+    if (options.workdir) {
+      Object.assign(
+        tools,
+        createWebIdeTerminalTools({
+          cfg,
+          taskId: options.taskId,
+          workdir: options.workdir,
+          rpc: options.terminalRpc
+        })
+      );
+    }
   }
   return tools;
 }
@@ -1898,7 +2083,9 @@ async function runCursorAgent(cfg, ctx, options) {
     appendMessageContent: options?.appendMessageContent,
     askQuestionExecute: options?.askQuestionExecute,
     enableWebIdePlanTools: options?.enableWebIdePlanTools,
-    taskId: options?.taskId
+    taskId: options?.taskId,
+    workdir,
+    terminalRpc: options?.terminalRpc
   });
   const enableSandbox = Boolean(options?.enableSandbox);
   let prompt = withPlanModeToolHint(ctx.prompt, ctx.mode);
@@ -2081,11 +2268,11 @@ function clearWebIdeAgentId(workdir, taskId) {
 // src/commands/connect/webide-ask-question.ts
 import { setTimeout as delay } from "node:timers/promises";
 var POLL_INTERVAL_MS = 2e3;
-function asString3(value) {
+function asString4(value) {
   return typeof value === "string" ? value.trim() : "";
 }
 function parseQuestions(args) {
-  const title = asString3(args.title) || void 0;
+  const title = asString4(args.title) || void 0;
   const raw = args.questions;
   if (!Array.isArray(raw) || raw.length === 0) {
     throw new Error("AskQuestion \u7F3A\u5C11 questions");
@@ -2094,16 +2281,16 @@ function parseQuestions(args) {
   for (const item of raw) {
     if (!item || typeof item !== "object" || Array.isArray(item)) continue;
     const row = item;
-    const id = asString3(row.id);
-    const prompt = asString3(row.prompt);
+    const id = asString4(row.id);
+    const prompt = asString4(row.prompt);
     const optionsRaw = row.options;
     if (!id || !prompt || !Array.isArray(optionsRaw)) continue;
     const options = [];
     for (const opt of optionsRaw) {
       if (!opt || typeof opt !== "object" || Array.isArray(opt)) continue;
       const o = opt;
-      const oid = asString3(o.id);
-      const label = asString3(o.label);
+      const oid = asString4(o.id);
+      const label = asString4(o.label);
       if (oid && label) options.push({ id: oid, label });
     }
     if (options.length < 2) {
@@ -2137,11 +2324,11 @@ function createWebIdeAskQuestionExecute(options) {
       const byId = new Map(
         list.assumptions.map((a) => [a.questionId, a])
       );
-      const pending = parsed.questions.filter((q) => {
+      const pending2 = parsed.questions.filter((q) => {
         const row = byId.get(q.id);
         return !row || row.status !== "RESOLVED";
       });
-      if (pending.length === 0) {
+      if (pending2.length === 0) {
         const answers = parsed.questions.map((q) => {
           const row = byId.get(q.id);
           return {
@@ -2626,8 +2813,9 @@ function markBranchDone(sessionId, workdir) {
 var TEST_START_ACTIONS = /* @__PURE__ */ new Set([
   "generate-cases",
   "run-auto-test",
-  "skip-test",
-  "enter-manual-test"
+  // 跳过/直接进手工测试不发 Cursor，PR 延后到部署或验收
+  "deploy",
+  "accept"
 ]);
 function shouldEnsureWebIdePullRequests(action) {
   return TEST_START_ACTIONS.has(action);
@@ -2680,70 +2868,6 @@ async function ensureWebIdePullRequests(cfg, taskId, workdir) {
   }
 }
 
-// src/commands/connect/webide-baseline-sync.ts
-async function abortMergeOrRebase(cwd) {
-  try {
-    await execGit(cwd, ["merge", "--abort"], true);
-  } catch {
-  }
-  try {
-    await execGit(cwd, ["rebase", "--abort"], true);
-  } catch {
-  }
-}
-async function syncWebIdeBaselineOrFail(workdir) {
-  let repoRoots;
-  try {
-    const manifest = loadWorkspaceReposCache(workdir);
-    repoRoots = resolveWorkspaceRepoAbsolutePaths(manifest);
-  } catch (err) {
-    return {
-      ok: false,
-      error: `\u8BFB\u53D6\u5DE5\u4F5C\u533A\u4ED3\u5E93\u6E05\u5355\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}`
-    };
-  }
-  const failures = [];
-  for (const repoRoot of repoRoots) {
-    const label = formatRepoLabel(workdir, repoRoot);
-    try {
-      const gitRoot = await resolveGitRepoRoot(repoRoot);
-      const baselineBranch = await resolveDefaultRemoteBranch(gitRoot);
-      await ensureRemoteBaselineBranch(gitRoot, baselineBranch);
-      const currentBranch = await getCurrentBranch(gitRoot);
-      console.log(
-        `[apm] webide accept sync ${label}: ${currentBranch} \u2190 origin/${baselineBranch}`
-      );
-      try {
-        await execGit(
-          gitRoot,
-          ["merge", `origin/${baselineBranch}`, "--no-edit"],
-          true
-        );
-      } catch (mergeErr) {
-        await abortMergeOrRebase(gitRoot);
-        const detail = mergeErr instanceof Error ? mergeErr.message : String(mergeErr);
-        failures.push(
-          `${label}\uFF1A\u5408\u5E76 origin/${baselineBranch} \u51B2\u7A81\uFF0C\u5DF2\u6267\u884C merge --abort \u64A4\u56DE\u672C\u6B21\u540C\u6B65\u3002${detail}`
-        );
-      }
-    } catch (err) {
-      failures.push(
-        `${label}\uFF1A${err instanceof Error ? err.message : String(err)}`
-      );
-    }
-  }
-  if (failures.length > 0) {
-    return {
-      ok: false,
-      error: [
-        "\u62C9\u53D6\u6700\u65B0\u57FA\u7EBF\u5931\u8D25\uFF0C\u5DF2\u64A4\u56DE\u672C\u6B21\u540C\u6B65\u64CD\u4F5C\uFF0C\u8BF7\u4EBA\u5DE5\u5904\u7406\u51B2\u7A81\u540E\u91CD\u8BD5\u9A8C\u6536\u5408\u5E76\u3002",
-        ...failures.map((f) => `- ${f}`)
-      ].join("\n")
-    };
-  }
-  return { ok: true };
-}
-
 // src/version.ts
 import { readFileSync as readFileSync8 } from "fs";
 import { dirname as dirname5, join as join8 } from "path";
@@ -2955,7 +3079,8 @@ var WEBIDE_CODE_CHANGE_ACTIONS = /* @__PURE__ */ new Set([
   "skip-plan",
   "start-develop",
   "fix-and-retest",
-  "report-defect"
+  "report-defect",
+  "deploy"
 ]);
 function shouldCommitAfterWebIdeMessage(action) {
   return WEBIDE_CODE_CHANGE_ACTIONS.has(action);
@@ -2972,7 +3097,7 @@ async function appendContent(cfg, messageId, content) {
   const api = createApmApiClient(cfg);
   await api.cli.webideAppendMessageContent({ id: messageId, content });
 }
-async function handleWebIdeInboundMessage(cfg, msg, signal) {
+async function handleWebIdeInboundMessage(cfg, msg, signal, options) {
   const workdir = requireRemoteWorkdir(msg.workdir);
   const messageId = msg.messageId;
   const taskId = msg.taskId;
@@ -3018,22 +3143,6 @@ async function handleWebIdeInboundMessage(cfg, msg, signal) {
       if (signal.aborted) throw new Error("\u4EFB\u52A1\u5DF2\u53D6\u6D88");
       await ensureWebIdePullRequests(cfg, taskId, workdir);
     }
-    if (msg.action === "accept") {
-      if (signal.aborted) throw new Error("\u4EFB\u52A1\u5DF2\u53D6\u6D88");
-      const sync = await syncWebIdeBaselineOrFail(workdir);
-      if (!sync.ok) {
-        await setError(cfg, messageId, sync.error);
-        return;
-      }
-      try {
-        await pushWorkspaceRepos(workdir);
-      } catch (err) {
-        console.warn(
-          "[apm] webide accept \u540C\u6B65\u540E push \u5931\u8D25:",
-          err instanceof Error ? err.message : err
-        );
-      }
-    }
     const savedAgentId = loadWebIdeAgentId(workdir, taskId);
     const logSyncRef = { current: null };
     const outcome = await runCursorAgent(
@@ -3060,6 +3169,7 @@ async function handleWebIdeInboundMessage(cfg, msg, signal) {
         // 本地 SDK sandbox 会拦截 custom-user-tools MCP，WebIDE 先关闭
         enableSandbox: false,
         taskId,
+        terminalRpc: options?.terminalRpc,
         createRemoteLogSync: (agentId) => {
           saveWebIdeAgentId(workdir, taskId, agentId);
           logSyncRef.current = createThrottledWebIdeMessageLogSync(
@@ -3154,19 +3264,68 @@ async function handleWebIdeInboundMessage(cfg, msg, signal) {
   }
 }
 
+// src/commands/connect/webide-terminal-rpc.ts
+import { parentPort } from "node:worker_threads";
+var nextId = 1;
+var pending = /* @__PURE__ */ new Map();
+function installTerminalRpcListener() {
+  parentPort?.on("message", (raw) => {
+    if (!raw || raw.type !== "terminal-rpc-result") return;
+    const p = pending.get(raw.id);
+    if (!p) return;
+    pending.delete(raw.id);
+    if (raw.ok) p.resolve(raw.result);
+    else p.reject(new Error(raw.error || "terminal rpc failed"));
+  });
+}
+function call(op, args) {
+  const id = nextId++;
+  return new Promise((resolve6, reject) => {
+    if (!parentPort) {
+      reject(new Error("parentPort \u4E0D\u53EF\u7528"));
+      return;
+    }
+    pending.set(id, { resolve: resolve6, reject });
+    parentPort.postMessage({
+      type: "terminal-rpc",
+      id,
+      op,
+      args
+    });
+    setTimeout(() => {
+      if (pending.has(id)) {
+        pending.delete(id);
+        reject(new Error(`terminal rpc timeout op=${op}`));
+      }
+    }, 12e4);
+  });
+}
+function createWorkerTerminalRpc() {
+  return {
+    start: (args) => call("start", args),
+    stop: (args) => call("stop", args),
+    stopAll: (args) => call("stopAll", args),
+    list: (args) => call("list", args)
+  };
+}
+
 // src/commands/connect/webide-message-worker.ts
 var controllers = /* @__PURE__ */ new Map();
+installTerminalRpcListener();
+var terminalRpc = createWorkerTerminalRpc();
 async function runJob(cfg, msg) {
   const controller = new AbortController();
   controllers.set(msg.messageId, controller);
   try {
-    await handleWebIdeInboundMessage(cfg, msg, controller.signal);
-    parentPort?.postMessage({
+    await handleWebIdeInboundMessage(cfg, msg, controller.signal, {
+      terminalRpc
+    });
+    parentPort2?.postMessage({
       type: "done",
       messageId: msg.messageId
     });
   } catch (err) {
-    parentPort?.postMessage({
+    parentPort2?.postMessage({
       type: "error",
       messageId: msg.messageId,
       error: err instanceof Error ? err.message : String(err)
@@ -3175,7 +3334,7 @@ async function runJob(cfg, msg) {
     controllers.delete(msg.messageId);
   }
 }
-parentPort?.on("message", (raw) => {
+parentPort2?.on("message", (raw) => {
   if (raw.type === "cancel") {
     controllers.get(raw.messageId)?.abort();
     return;

package/package.json

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

package/template/AGENTS.md

@@ -31,7 +31,7 @@
     - write_doc.md：当需要写文档时需要读取这个文档，记住写文档的规则
     - webide_git_commit.md：WebIDE 开发/修码时读取，按规范分轮 commit，结束前 push
     - webide_testcase.md：WebIDE 生成测试用例时读取，按规范编写并提交用例
-    - webide_merge.md：WebIDE 验收合并时读取；先解冲突再调 MergeWebIdePullRequests，需求相悖则拒绝合并
+    - webide_merge.md：WebIDE 验收通过后读取；直接调用 MergeWebIdePullRequests 合并代码
 
 - 仓库项目上下文（`.apm/project/`）:
 

package/template/rules/webide_merge.md

@@ -1,39 +1,16 @@
 ## WebIDE 合并规范
 
-适用场景：WebIDE 验收通过（`accept`）后：同步最新基线 → 对照原始任务审核 → 合并本任务 PR。
+适用场景：WebIDE 验收通过（`accept`）后合并本任务 PR。
 
 ### 目标
 
-将本任务各仓库 `feat/task-<taskId>` 分支上的变更安全合并进基线分支（通常为 `main`）。
+将本任务各仓库特性分支上的变更合并进基线分支（通常为 `main`）。
 
 ### 步骤
 
-1. **先拉取最新基线并处理冲突，再审核，最后调用合并工具**
-
-   - 在各相关仓库拉取最新基线（`git fetch`），将基线 merge/rebase 进特性分支。
-   - 有冲突时：在本地解冲突后 commit 并 `git push`（必要时 `--force-with-lease` 仅用于已 rebase 的特性分支）。
-   - 解冲突原则：保留本任务需求与已确认计划所要求的行为；吸收基线中合理且不冲突的改动。
-   - **解冲突失败或无法安全取舍**：立即 `git merge --abort` / `git rebase --abort` 撤回本次同步，保持特性分支为同步前状态；**禁止**调用合并工具。
-
-2. **不可调和冲突 / 同步失败 → 拒绝合并**
-
-   - 若冲突双方改动在需求/业务逻辑上相悖，或本地同步已 abort：
-     - **禁止**调用 `MergeWebIdePullRequests`
-     - 用 `AppendMessage` 说明冲突文件、矛盾点、为何无法自动取舍，以及已执行的回退
-     - 以错误结束本轮（抛错或明确失败），等待人工介入（前端将展示失败信息）
-
-3. **对照原始任务审核代码**
-
-   - 在合并前快速核对：改动是否覆盖任务需求与已确认计划；是否引入明显与需求相悖的行为。
-   - 若审核不通过：同样禁止合并，AppendMessage 说明问题并以错误结束。
-
-4. **确认可安全合并后**
-   - 调用一次 `MergeWebIdePullRequests`（无参数），由平台合并本任务全部 OPEN PR
-   - 再用 `AppendMessage` 汇总合并结果（PR 编号、仓库）
+1. 调用一次 `MergeWebIdePullRequests`（`confirmedConflictFree=true`），由平台合并本任务全部 OPEN PR。
+2. 用 `AppendMessage` 汇总合并结果（PR 编号、仓库）。
 
 ### 禁止
 
-- 未拉取最新基线 / 未检查冲突就直接调合并工具
-- 同步冲突未 abort 就继续合并
-- 为强行合并而删改与需求相悖的关键逻辑却不说明
-- 在仍有草稿 PR / 明显冲突未解决时假装成功
+- 在合并之外自行执行同步基线、代码审核、部署等额外流程

package/template/rules/webide_terminal.md

@@ -0,0 +1,35 @@
+# WebIDE 长驻终端
+
+长驻进程（如前后端 `dev`）必须用自定义工具管理，**禁止**用 Shell 启动会长期占用的 dev server。
+
+## 工具
+
+- `StartWebIdeTerminal`：`{ key, name?, cwd, command, readyPattern?, portsHint? }`
+  - `key` 稳定标识，如 `frontend` / `backend`；同 key 已在跑（RUNNING/READY）则幂等返回
+  - 进程挂在 CLI 主进程，跨多轮消息存活
+- `StopWebIdeTerminal`：`{ key }` 或 `{ terminalId }`；杀进程树，状态改为 EXITED（不删记录）
+- `StopAllWebIdeTerminals`：停掉本 task 全部仍存活的终端（重跑本地环境前使用）
+- `ListWebIdeTerminals`：列出**存活**终端（STARTING / RUNNING / READY / STOPPING），**不含** EXITED / FAILED
+
+## 启动命令来源
+
+必须 Read `.apm/project/deploy.md`，按文档中的 cwd / command / 服务划分调用 `StartWebIdeTerminal`。
+
+- 文档不存在或未写明启动方式 → 用 AppendMessage 说明无法启动本地环境，**禁止猜测命令**。
+
+## 时机
+
+1. **首次**（`start-develop` / 跳过计划后的开发轮次）：实现完成后需要本地环境时
+   - 先 `ListWebIdeTerminals`
+   - 若无活终端 → Read `deploy.md` → 按前后端分别 `StartWebIdeTerminal`
+   - 等待 READY / 端口出现后，告知用户可在 WebIDE「终端」面板观察日志（勿粘贴整段 stdout）
+2. **后续改码**（热更新）：有活终端则**复用，不重起**
+3. **显式重跑**（端口冲突、命令变更、或平台「重跑本地环境」指令）：  
+   `StopAllWebIdeTerminals` → 再 Read `deploy.md` → 重新 Start  
+   不要在已死进程上糊弄；需要换命令时也是先停再建
+
+## 规范
+
+1. 禁止用 Shell / 后台进程方式起 `dev` / `serve` 等长驻命令。
+2. 观察日志请用户看 WebIDE「终端」面板。
+3. 任务结束或不再需要时可 Stop；不要留下孤儿进程。