batter-pixso-mcp 0.5.0 → 0.6.0

package/dist/index.js

@@ -1,21 +1,17 @@
 #!/usr/bin/env node
 
-// src/plugin/assets.ts
-import { createHash } from "node:crypto";
-import { mkdir, readdir, stat, unlink, writeFile } from "node:fs/promises";
-import { join as join2 } from "node:path";
-
 // src/config.ts
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-var VERSION = true ? "0.5.0" : "0.0.0-dev";
+var VERSION = true ? "0.6.0" : "0.0.0-dev";
 var HUB_NAME = "batter-pixso-mcp";
 var ASSETS_DIR = join(tmpdir(), "batter-pixso-assets");
 var config = {
   /** 插件通信 HTTP 端口，仅监听 127.0.0.1。与插件 UI 的 DEFAULT_PORT 互为默认对端，改默认需同步 */
   httpPort: Number(process.env.HTTP_PORT ?? 3210),
-  /** hub 空闲自毁阈值（无插件、无 agent 请求），默认 30 分钟 */
-  hubIdleMs: Number(process.env.HUB_IDLE_MS ?? 30 * 60 * 1e3),
+  // hub 常驻（不自毁）：升级由 proxy 版本比对自动换血，手动停止用 --stop
+  /** MCP HTTP 会话空闲 TTL：超时清扫防泄漏（proxy 对失效会话有自动重建兜底），默认 30 分钟 */
+  mcpSessionTtlMs: Number(process.env.MCP_SESSION_TTL_MS ?? 30 * 60 * 1e3),
   /** 产物图片保留时长，默认 7 天 */
   assetTtlMs: Number(process.env.ASSET_TTL_DAYS ?? 7) * 24 * 60 * 60 * 1e3
 };
@@ -36,6 +32,9 @@ function withResolvers() {
 }
 
 // src/plugin/assets.ts
+import { createHash } from "node:crypto";
+import { mkdir, readdir, stat, unlink, writeFile } from "node:fs/promises";
+import { join as join2 } from "node:path";
 var EXT_BY_FORMAT = {
   PNG: ".png",
   SVG: ".svg",
@@ -89,114 +88,138 @@ async function cleanOldAssets(ttlMs) {
   return removed;
 }
 
-// src/plugin/sessions.ts
-import { randomUUID } from "node:crypto";
-var ONLINE_WINDOW_MS = 45e3;
-function unknownTargetError(target) {
-  return new Error(`\u627E\u4E0D\u5230\u76EE\u6807\u63D2\u4EF6\u4F1A\u8BDD\uFF1A${target}\u3002\u53EF\u7528 list_sessions \u67E5\u770B\u5F53\u524D\u8FDE\u63A5\u7684\u4F1A\u8BDD`);
-}
-var SessionRegistry = class {
-  sessions = /* @__PURE__ */ new Map();
-  lastActiveId = null;
-  /** 会话亲和：fileKey → 上一次路由使用的 sessionId（仍在线时优先，避免同文件多实例间漂移） */
-  lastUsedByFileKey = /* @__PURE__ */ new Map();
-  isOnline(s) {
-    return s.connected || Date.now() - s.lastSeen < ONLINE_WINDOW_MS;
-  }
-  /** fileKey 寻址候选：该文件的在线会话（谁先 pong 由 ping 竞速决定，此处不排序） */
-  candidatesForFileKey(fileKey) {
-    return [...this.sessions.values()].filter((s) => s.meta.fileKey === fileKey && this.isOnline(s));
-  }
-  /** 亲和查询：上一次为该 fileKey 服务的 sessionId */
-  affinityIdOf(fileKey) {
-    return this.lastUsedByFileKey.get(fileKey);
-  }
-  /** 亲和钉住：fileKey 寻址探活成功后记录（下次优先） */
-  pinAffinity(fileKey, sessionId) {
-    this.lastUsedByFileKey.set(fileKey, sessionId);
+// src/process/hub-process.ts
+import { spawn } from "node:child_process";
+import { closeSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir as tmpdir2 } from "node:os";
+import { join as join3 } from "node:path";
+import { fileURLToPath } from "node:url";
+async function probeHub() {
+  try {
+    const res = await fetch(`${hubBaseUrl()}/health`, { signal: AbortSignal.timeout(1500) });
+    if (!res.ok) return { state: "foreign" };
+    const body = await res.json();
+    if (body.ok === true && body.name === HUB_NAME) return { state: "alive", health: body };
+    return { state: "foreign" };
+  } catch (err) {
+    const hung = err instanceof Error && err.name === "TimeoutError";
+    return { state: hung ? "hung" : "down" };
   }
-  /** 剔除会话（幽灵剔除/ping 判死共用）：清理亲和引用；存活但繁忙被误剔的插件会在 SSE 断开或上报 404 后自重注册 */
-  evict(id) {
-    if (this.sessions.delete(id)) {
-      for (const [k, v] of this.lastUsedByFileKey) {
-        if (v === id) this.lastUsedByFileKey.delete(k);
-      }
-      log(`session evicted: ${id.slice(0, 8)}`);
-    }
+}
+var PORT_FIX_HINT = `\u7528 netstat -ano | findstr :${config.httpPort} \u67E5\u5230 PID \u540E taskkill /PID <pid> /F \u7ED3\u675F\uFF0C\u518D\u91CD\u8BD5`;
+function hubStateError(state) {
+  if (state === "hung") {
+    return new Error(`\u7AEF\u53E3 ${config.httpPort} \u4E0A\u7684\u670D\u52A1\u65E0\u54CD\u5E94\uFF08\u53EF\u80FD\u6302\u6B7B\uFF09\u4E14\u65E0\u6CD5\u5B9A\u4F4D pid\u3002${PORT_FIX_HINT}`);
   }
-  register(meta = {}) {
-    if (meta.fileKey) {
-      for (const s of [...this.sessions.values()]) {
-        if (s.meta.fileKey === meta.fileKey && !this.isOnline(s)) {
-          this.evict(s.id);
-        }
+  return new Error(`\u7AEF\u53E3 ${config.httpPort} \u88AB\u5176\u4ED6\u7A0B\u5E8F\u5360\u7528\u3002${PORT_FIX_HINT}\uFF0C\u6216\u4FEE\u6539 HTTP_PORT \u6362\u7AEF\u53E3`);
+}
+var HUB_LOG = join3(tmpdir2(), "batter-pixso-mcp-hub.log");
+var PID_FILE = join3(tmpdir2(), "batter-pixso-mcp-hub.pid");
+function writePidFile(pid) {
+  try {
+    writeFileSync(PID_FILE, String(pid), "utf8");
+    process.on("exit", () => {
+      try {
+        rmSync(PID_FILE);
+      } catch {
       }
-    }
-    const session = { id: randomUUID(), meta, lastSeen: Date.now(), connected: false };
-    this.sessions.set(session.id, session);
-    this.lastActiveId = session.id;
-    log(`session registered: ${session.id} (${meta.fileName ?? "unknown file"})`);
-    return this.toInfo(session);
+    });
+  } catch {
   }
-  /** 心跳/连接状态用：只刷 lastSeen，不影响 lastActiveId（"最近活跃"= 用户行为，心跳不算） */
-  touchSeen(id) {
-    const s = this.sessions.get(id);
-    if (!s) return null;
-    s.lastSeen = Date.now();
-    return s;
+}
+function readPidFile() {
+  try {
+    const pid = Number(readFileSync(PID_FILE, "utf8").trim());
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+  } catch {
+    return null;
   }
-  /** 用户行为（选区上报/命令服务/注册）：刷 lastSeen 并标记最近活跃 */
-  touch(id) {
-    const s = this.touchSeen(id);
-    if (!s) return null;
-    this.lastActiveId = id;
-    return s;
+}
+function removePidFile() {
+  try {
+    rmSync(PID_FILE);
+  } catch {
   }
-  setConnected(id, connected) {
-    const s = this.touchSeen(id);
-    if (!s) return false;
-    s.connected = connected;
+}
+function killHubByPid(pid) {
+  try {
+    process.kill(pid);
     return true;
+  } catch {
+    return false;
   }
-  updateContext(id, meta) {
-    const s = this.touch(id);
-    if (!s) return false;
-    s.meta = { ...s.meta, ...meta };
-    log(
-      `context updated [${id.slice(0, 8)}]: ${s.meta.fileName ?? "?"} / ${s.meta.pageName ?? "?"} / ${s.meta.selection?.length ?? 0} selected`
-    );
-    return true;
+}
+function killHubByPidFile() {
+  const pid = readPidFile();
+  if (!pid) return false;
+  if (!killHubByPid(pid)) return false;
+  removePidFile();
+  return true;
+}
+function spawnHub() {
+  const out = openSync(HUB_LOG, "a");
+  const entry = process.argv[1] ?? fileURLToPath(import.meta.url);
+  const SKIP_FLAGS = /* @__PURE__ */ new Set(["--eval", "-e", "--print", "-p", "--watch", "--watch-preserve-output"]);
+  const SKIP_PREFIXES = [...SKIP_FLAGS].map((f) => f + "=");
+  const execArgv = process.execArgv.filter(
+    (a, i, arr) => !SKIP_FLAGS.has(a) && !SKIP_PREFIXES.some((p) => a.startsWith(p)) && !(i > 0 && SKIP_FLAGS.has(arr[i - 1]))
+  );
+  const child = spawn(process.execPath, [...execArgv, entry, "--hub"], {
+    detached: true,
+    stdio: ["ignore", out, out],
+    windowsHide: true,
+    env: { ...process.env }
+  });
+  child.on("error", (err) => log("hub spawn \u5931\u8D25:", err.message));
+  child.unref();
+  closeSync(out);
+  log(`hub spawned (pid ${child.pid}), log: ${HUB_LOG}`);
+}
+async function waitForHub(timeoutMs = 15e3) {
+  const deadline = Date.now() + timeoutMs;
+  for (; ; ) {
+    const { state } = await probeHub();
+    if (state === "alive") return;
+    if (state !== "down") throw hubStateError(state);
+    if (Date.now() > deadline) throw new Error(`\u7B49\u5F85 hub \u5C31\u7EEA\u8D85\u65F6\uFF08${timeoutMs / 1e3}s\uFF09`);
+    await new Promise((r) => setTimeout(r, 200));
   }
-  list() {
-    return [...this.sessions.values()].map((s) => this.toInfo(s));
+}
+async function waitForHubDown(timeoutMs = 5e3) {
+  const deadline = Date.now() + timeoutMs;
+  for (; ; ) {
+    const { state } = await probeHub();
+    if (state === "down") return;
+    if (Date.now() > deadline) throw new Error(`\u7B49\u5F85 hub \u9000\u51FA\u8D85\u65F6\uFF08${timeoutMs / 1e3}s\uFF09`);
+    await new Promise((r) => setTimeout(r, 100));
   }
-  /** 纯查找（不判活）：工具层寻址用——离线会话也可取到 fileKey 用于候选扩展与故障转移 */
-  get(id) {
-    return this.sessions.get(id);
+}
+async function stopHub() {
+  const { state, health } = await probeHub();
+  if (state === "down") {
+    log(`hub \u672A\u8FD0\u884C\uFF08\u7AEF\u53E3 ${config.httpPort} \u65E0\u670D\u52A1\uFF09`);
+    return;
   }
-  /** 缺省路由：最近活跃在线会话 > 任意在线会话（显式 target 由工具层 get/candidatesForFileKey + ping 完成） */
-  resolve() {
-    if (this.lastActiveId) {
-      const s = this.sessions.get(this.lastActiveId);
-      if (s && this.isOnline(s)) return s;
+  if (state === "foreign") {
+    log(`\u7AEF\u53E3 ${config.httpPort} \u4E0A\u4E0D\u662F batter-pixso-mcp\uFF0C\u672A\u5904\u7406`);
+    return;
+  }
+  if (state === "hung") {
+    if (killHubByPidFile()) {
+      log("hub \u65E0\u54CD\u5E94\uFF08\u50F5\u5C38\u8FDB\u7A0B\uFF09\uFF0C\u5DF2\u6309 pid \u6587\u4EF6\u5F3A\u6740\u3002\u4E0B\u6B21 agent \u8BF7\u6C42\u4F1A\u81EA\u52A8\u62C9\u8D77\u65B0\u7248\u672C");
+      return;
     }
-    const fallback = [...this.sessions.values()].find((s) => this.isOnline(s));
-    if (fallback) return fallback;
-    throw new Error("Pixso \u63D2\u4EF6\u672A\u8FDE\u63A5\uFF1A\u8BF7\u5728 Pixso \u5BA2\u6237\u7AEF\u4E2D\u8FD0\u884C Batter Pixso Bridge \u63D2\u4EF6");
+    log(`\u7AEF\u53E3 ${config.httpPort} \u4E0A\u7684\u670D\u52A1\u65E0\u54CD\u5E94\u4E14\u65E0\u6CD5\u5B9A\u4F4D pid\u3002${PORT_FIX_HINT}`);
+    return;
   }
-  toInfo(s) {
-    return {
-      sessionId: s.id,
-      fileKey: s.meta.fileKey,
-      fileName: s.meta.fileName,
-      pageName: s.meta.pageName,
-      selectionCount: s.meta.selection?.length,
-      online: this.isOnline(s),
-      lastSeen: s.lastSeen
-    };
+  const pid = health.pid;
+  if (killHubByPid(pid)) {
+    removePidFile();
+    log(`hub \u5DF2\u505C\u6B62\uFF08pid ${pid}\uFF09\u3002\u4E0B\u6B21 agent \u8BF7\u6C42\u4F1A\u81EA\u52A8\u62C9\u8D77\u65B0\u7248\u672C`);
+  } else {
+    log(`\u505C\u6B62 pid ${pid} \u5931\u8D25\u3002${PORT_FIX_HINT}`);
   }
-};
-var sessions = new SessionRegistry();
+}
 
 // src/http.ts
 import { createServer } from "node:http";
@@ -302,13 +325,13 @@ var INTRO = `# batter-pixso-mcp \u4F7F\u7528\u6307\u5357
 
 ## \u591A\u6587\u4EF6\u573A\u666F
 
-\u6BCF\u4E2A\u8FD0\u884C\u63D2\u4EF6\u7684\u8BBE\u8BA1\u6587\u4EF6\u662F\u4E00\u4E2A\u4F1A\u8BDD\u3002\u591A\u4E2A\u6587\u4EF6\u540C\u65F6\u6253\u5F00\u65F6\uFF1A
-\u5148\u7528 \`list_sessions\` \u786E\u8BA4\u76EE\u6807\u6587\u4EF6\uFF0C\u518D\u628A\u8FD4\u56DE\u7684 \`sessionId\` \u6216 \`fileKey\`
-\u4F5C\u4E3A\u5176\u4ED6\u5DE5\u5177\u7684 \`target\` \u53C2\u6570\u4F20\u5165\uFF1B\u4E0D\u4F20 \`target\` \u65F6\u8DEF\u7531\u5230\u6700\u8FD1\u6D3B\u8DC3\u7684\u6587\u4EF6\u3002
+\u6BCF\u4E2A\u8FD0\u884C\u63D2\u4EF6\u7684\u8BBE\u8BA1\u6587\u4EF6\u662F\u4E00\u4E2A\u4F1A\u8BDD\u3002\u8282\u70B9\u7C7B\u5DE5\u5177\uFF08\`get_node_dsl\`/\`get_metadata\`/\`get_screenshot\`/\`export_image\`\uFF09
+\u7684 \`guid\` \u5FC5\u4F20\uFF0C\u4E14 \`fileKey\`/\`sessionId\` \u4E8C\u9009\u4E00\u5FC5\u4F20\uFF1A\u5148\u7528 \`list_sessions\` \u786E\u8BA4\u76EE\u6807\u6587\u4EF6\uFF0C\u628A\u8FD4\u56DE\u7684 \`fileKey\`
+\u4F5C\u4E3A\u8DEF\u7531\u53C2\u6570\u4F20\u5165\uFF08\u8DE8\u91CD\u5F00\u7A33\u5B9A\uFF0C\u4F18\u5148\u4E8E \`sessionId\`\uFF09\uFF1B\u4EC5 \`get_selected\`/\`list_sessions\` \u53EF\u7F3A\u7701\u8DEF\u7531\u53C2\u6570\u505A\u63A2\u67E5\u3002
 
-**\u4F1A\u8BDD\u89E3\u6790\u4E0E\u4FE1\u5C01**\uFF1A\u63D2\u4EF6\u7C7B\u5DE5\u5177\u7684\u8FD4\u56DE\u7EDF\u4E00\u4E3A \`{sessionId, data}\`\u2014\u2014\`sessionId\` \u662F\u672C\u6B21\u5B9E\u9645\u670D\u52A1\u7684\u4F1A\u8BDD
-\uFF08\u6BCF\u6B21\u8C03\u7528\u7ECF ping/pong \u63A2\u6D3B\u91CD\u65B0\u786E\u8BA4\uFF0C\u4E0D\u662F\u53EF\u957F\u671F\u9489\u4F4F\u7684\u56FA\u5B9A\u6807\u8BC6\uFF09\u3002\u63A8\u8350 \`target\` \u7528 \`fileKey\`\uFF1A
-\u6BCF\u6B21\u8C03\u7528\u6309 fileKey \u91CD\u65B0\u5BFB\u5740\u2014\u2014\u540C fileKey \u591A\u4F1A\u8BDD\u65F6\u4F18\u5148\u4E0A\u4E00\u6B21\u4F7F\u7528\u7684\uFF08\u4EB2\u548C\uFF09\uFF0C\u6587\u4EF6\u5173\u95ED\u91CD\u5F00\u3001\u63D2\u4EF6\u91CD\u8DD1\u540E
+**\u4F1A\u8BDD\u89E3\u6790\u4E0E\u4FE1\u5C01**\uFF1A\u63D2\u4EF6\u7C7B\u5DE5\u5177\u7684\u8FD4\u56DE\u7EDF\u4E00\u4E3A \`{sessionId, fileKey, data}\`\u2014\u2014\`sessionId\` \u662F\u672C\u6B21\u5B9E\u9645\u670D\u52A1\u7684\u4F1A\u8BDD
+\uFF08\u6BCF\u6B21\u8C03\u7528\u7ECF ping/pong \u63A2\u6D3B\u91CD\u65B0\u786E\u8BA4\uFF0C\u4E0D\u662F\u53EF\u957F\u671F\u9489\u4F4F\u7684\u56FA\u5B9A\u6807\u8BC6\uFF09\uFF1B\`fileKey\` \u662F\u8DE8\u91CD\u5F00\u7A33\u5B9A\u7684\u53E5\u67C4\uFF0C\u540E\u7EED\u8C03\u7528
+\u7528\u5B83\u505A\u8DEF\u7531\u53C2\u6570\uFF1A\u6BCF\u6B21\u8C03\u7528\u6309 fileKey \u91CD\u65B0\u5BFB\u5740\u2014\u2014\u540C fileKey \u591A\u4F1A\u8BDD\u65F6\u4F18\u5148\u4E0A\u4E00\u6B21\u4F7F\u7528\u7684\uFF08\u4EB2\u548C\uFF09\uFF0C\u6587\u4EF6\u5173\u95ED\u91CD\u5F00\u3001\u63D2\u4EF6\u91CD\u8DD1\u540E
 \u81EA\u52A8\u89E3\u6790\u5230\u5F53\u524D\u5B58\u6D3B\u5B9E\u4F8B\uFF0Cagent \u65E0\u9700\u5173\u5FC3 sessionId \u7684\u5931\u6548\u3002
 
 \u8BE6\u7EC6\u5DE5\u4F5C\u6D41\u89C1\u8D44\u6E90 \`batter://guides/design-to-code\`\u3002
@@ -336,12 +359,12 @@ var DESIGN_TO_CODE = `# \u8BBE\u8BA1\u8F6C\u4EE3\u7801\u5DE5\u4F5C\u6D41
 
 1. **\u786E\u8BA4\u76EE\u6807\u8282\u70B9**
    - \u7528\u6237\u7ED9\u4E86 Pixso \u94FE\u63A5\uFF1A\u6309\u4E0A\u65B9\u786C\u6027\u89C4\u5219\u7B2C 2 \u6761\u63D0\u53D6 guid\uFF0C\u76F4\u63A5\u7EE7\u7EED\u3002
-   - \u7528\u6237\u660E\u786E\u8BF4\u4E86"\u8FD9\u4E2A/\u6211\u9009\u4E2D\u7684"\uFF1A\u8C03 \`get_selected\` \u62FF guid\uFF0C\u76F4\u63A5\u7EE7\u7EED\u3002
+   - \u7528\u6237\u660E\u786E\u8BF4\u4E86"\u8FD9\u4E2A/\u6211\u9009\u4E2D\u7684"\uFF1A\u8C03 \`get_selected\` \u62FF guid \u4E0E fileKey\uFF0C\u76F4\u63A5\u7EE7\u7EED\u3002
    - \u5176\u4F59\u4F9D\u8D56\u5F53\u524D\u9009\u533A\u7684\u573A\u666F\uFF1A**\u4E25\u7981\u9690\u5F0F\u4F7F\u7528\u9009\u533A guid**\u2014\u2014\u8C03 \`get_selected\` \u540E
      \u5FC5\u987B\u5148\u628A\u9009\u4E2D\u56FE\u5C42\u540D\u79F0\u62A5\u7ED9\u7528\u6237\u786E\u8BA4\uFF08"\u5F53\u524D\u9009\u4E2D\u7684\u662F\u300CXX\u300D\uFF0C\u786E\u8BA4\u5904\u7406\u5B83\u5417\uFF1F"\uFF09\uFF0C\u786E\u8BA4\u540E\u518D\u7EE7\u7EED\u3002
-     \`get_node_dsl\` / \`get_screenshot\` \u7684 guid \u7F3A\u7701\u56DE\u9000\u540C\u6837\u9002\u7528\u672C\u89C4\u5219\u3002
-2. **\u53D6\u7ED3\u6784**\uFF1A\u63D2\u4EF6\u7C7B\u5DE5\u5177\u8FD4\u56DE\u7EDF\u4E00\u4E3A \`{sessionId, data}\` \u4FE1\u5C01\u2014\u2014DSL \u5728 \`data\` \u5B57\u6BB5\u91CC\u3002
-   \`get_node_dsl(guid)\` \u62FF\u7CBE\u7B80 DSL\u3002
+     \u786E\u8BA4\u540E\u7684\u8C03\u7528\u91CC guid \u7528\u8FD4\u56DE\u7684\u9009\u4E2D\u56FE\u5C42 id\u3001\u8DEF\u7531\u53C2\u6570\u7528\u8FD4\u56DE\u7684 fileKey\uFF08guid \u5FC5\u4F20\u3001fileKey/sessionId \u5FC5\u4F20\u5176\u4E00\uFF09\u3002
+2. **\u53D6\u7ED3\u6784**\uFF1A\u63D2\u4EF6\u7C7B\u5DE5\u5177\u8FD4\u56DE\u7EDF\u4E00\u4E3A \`{sessionId, fileKey, data}\` \u4FE1\u5C01\u2014\u2014DSL \u5728 \`data\` \u5B57\u6BB5\u91CC\u3002
+   \`get_node_dsl(guid, fileKey)\` \u62FF\u7CBE\u7B80 DSL\uFF08guid \u5FC5\u4F20\uFF0CfileKey/sessionId \u5FC5\u4F20\u5176\u4E00\uFF09\u3002
    **\u9996\u6B21\u63A5\u89E6\u4E00\u4E2A\u8BBE\u8BA1\u7A3F/\u9875\u9762**\uFF08\u8FD8\u6CA1\u6709\u76EE\u6807\u8282\u70B9\u7684\u4E0A\u4E0B\u6587\u65F6\uFF09\uFF1A\u5148 \`get_metadata(guid)\`
    \u62FF\u5168\u6811\u9AA8\u67B6\uFF08\u4EC5 id/name/type/kids\uFF0C\u65E0\u6837\u5F0F/\u5750\u6807/\u8D44\u6E90\uFF0C\u4F53\u79EF\u6781\u5C0F\uFF09+ \`get_screenshot(guid)\` \u62FF\u89C6\u89C9\u5168\u8C8C\uFF0C
    \u636E\u6B64\u5B9A\u4F4D\u76EE\u6807\u8282\u70B9\uFF0C\u518D\u5BF9\u76EE\u6807\u6B63\u5E38\u53D6 DSL\u3002\u9AA8\u67B6\u4E2D ICON/IMAGE \u53F6\u5B50\u65E0 \`img\`\u2014\u2014\u9700\u8D44\u6E90\u65F6\u6309\u5176 \`id\` \u4E0B\u94BB\u5168\u91CF DSL\u3002
@@ -407,7 +430,7 @@ DSL \u662F\u5355\u884C\u7D27\u51D1 JSON\uFF1A\u77ED key\u3001\u4F4D\u7F6E\u6570\
 - **\u7F3A guid**\uFF1A\u5411\u7528\u6237\u8981\u5B8C\u6574\u7684 Pixso \u94FE\u63A5\uFF08\u542B item-id \u67E5\u8BE2\u53C2\u6570\uFF09\uFF0C\u4E0D\u8981\u731C\u6D4B\u8282\u70B9 id\u3002
 - **\u547D\u4EE4\u8D85\u65F6/\u7ED3\u679C\u8FC7\u5927**\uFF1A\u5BF9\u76EE\u6807\u8282\u70B9\u7684\u5B50\u8282\u70B9\u7528 \`get_node_dsl\` + \u8F83\u4F4E \`maxDepth\` \u5206\u6BB5\u53D6\uFF0C\u4E0D\u8981\u6574\u6811\u4E00\u6B21\u62C9\u3002
 - **\u7ED3\u679C\u7591\u4F3C\u8FC7\u671F**\uFF08\u8BBE\u8BA1\u7A3F\u521A\u6539\u8FC7\uFF09\uFF1A\u7ED9\u5BFC\u51FA\u7C7B\u5DE5\u5177\u52A0 \`cache: "refresh"\` \u5F3A\u5236\u5237\u65B0\u3002
-- **\u63D2\u4EF6\u65E0\u54CD\u5E94**\uFF08ping \u63A2\u6D4B\u8D85\u65F6\uFF09\uFF1A\u63D2\u4EF6\u672A\u8FD0\u884C\u6216\u6B63\u5728\u6267\u884C\u957F\u547D\u4EE4\u2014\u2014\u7A0D\u540E\u91CD\u8BD5\uFF1B\u6587\u4EF6\u91CD\u5F00\u573A\u666F \`target\` \u7528 fileKey \u4F1A\u81EA\u52A8\u89E3\u6790\u5230\u65B0\u5B9E\u4F8B\u3002
+- **\u63D2\u4EF6\u65E0\u54CD\u5E94**\uFF08ping \u63A2\u6D4B\u8D85\u65F6\uFF09\uFF1A\u63D2\u4EF6\u672A\u8FD0\u884C\u6216\u6B63\u5728\u6267\u884C\u957F\u547D\u4EE4\u2014\u2014\u7A0D\u540E\u91CD\u8BD5\uFF1B\u6587\u4EF6\u91CD\u5F00\u573A\u666F\u7528 fileKey \u5BFB\u5740\u4F1A\u81EA\u52A8\u89E3\u6790\u5230\u65B0\u5B9E\u4F8B\u3002
 - **\u7981\u6B62\u4EC5\u51ED\u622A\u56FE\u786C\u7F16\u7801**\uFF1A\u622A\u56FE\u662F\u6821\u9A8C\u4E0E\u610F\u56FE\u53C2\u7167\uFF0C\u4E0D\u662F\u7ED3\u6784\u6765\u6E90\u2014\u2014\u7ED3\u6784\u4E00\u5F8B\u8D70 DSL\u3002
 
 ## \u7EC4\u4EF6\u5173\u8054\uFF08comp \u5B57\u6BB5\uFF09
@@ -435,7 +458,7 @@ INSTANCE / COMPONENT / COMPONENT_SET \u8282\u70B9\u5E26 \`comp\` \u5B57\u6BB5\uF
 - DSL \u662F**\u6709\u635F\u7CBE\u7B80**\uFF1A\u7701\u7565\u4E86\u5E03\u5C14\u8FD0\u7B97\u8DEF\u5F84\u3001\u8499\u7248\u7B49\u7EAF\u8BBE\u8BA1\u7EC6\u8282\uFF0C\u89C6\u89C9\u590D\u6742\u8282\u70B9\u4EE5\u622A\u56FE\u4E3A\u51C6\u3002
 - \u5BFC\u51FA\u7C7B\u5DE5\u5177\uFF08\`get_node_dsl\`/\`get_screenshot\`/\`export_image\`\uFF09\u5E26 15 \u5206\u949F\u7ED3\u679C\u7F13\u5B58\uFF08\u63D2\u4EF6\u4FA7 TTL\uFF09\uFF1B
   \u8BBE\u8BA1\u7A3F\u521A\u6539\u8FC7\u4F46\u7ED3\u679C\u5BF9\u4E0D\u4E0A\u65F6\uFF0C\u52A0 \`cache: "refresh"\` \u5F3A\u5236\u5237\u65B0\u3002
-- \u591A\u6587\u4EF6\u573A\u666F\u6240\u6709\u5DE5\u5177\u90FD\u652F\u6301 \`target\` \u53C2\u6570\uFF08sessionId/fileKey\uFF09\uFF0C\u89C1 \`batter://guides/intro\`\u3002
+- \u591A\u6587\u4EF6\u573A\u666F\u8282\u70B9\u7C7B\u5DE5\u5177\u7528 \`fileKey\`/\`sessionId\` \u53C2\u6570\u8DEF\u7531\uFF08\u4E8C\u9009\u4E00\u5FC5\u4F20\uFF09\uFF0C\u89C1 \`batter://guides/intro\`\u3002
 `;
 var GUIDES = [
   {
@@ -480,7 +503,7 @@ var DESIGN_TO_CODE2 = {
             `## \u6267\u884C\u6D41\u7A0B`,
             ``,
             `1. \u786E\u8BA4\u76EE\u6807\u8282\u70B9\uFF1A${targetLine}`,
-            `2. \u53D6\u6570\u636E\uFF1A\u63D2\u4EF6\u7C7B\u5DE5\u5177\u8FD4\u56DE\u7EDF\u4E00\u4E3A \`{sessionId, data}\` \u4FE1\u5C01\uFF0C\u53D6 \`data\` \u5B57\u6BB5\u3002\u9996\u6B21\u63A5\u89E6\u8BBE\u8BA1\u7A3F\uFF1A\u5148 \`get_metadata(guid)\` \u62FF\u5168\u6811\u9AA8\u67B6\u5B9A\u4F4D\u76EE\u6807 + \`get_screenshot(guid)\` \u62FF\u89C6\u89C9\u5168\u8C8C\uFF1B\u968F\u540E \`get_node_dsl(guid)\` \u62FF\u5168\u91CF DSL\uFF08\u7ED3\u6784\u5F88\u5927\u65F6\u7528 \`maxDepth\` \u5206\u6BB5\u4E0B\u63A2\u2014\u2014\u622A\u65AD\u5904\u8282\u70B9\u5E26 \`more\` \u6807\u8BB0\u4E0E \`kidsSummary\` \u6D45\u9884\u89C8\uFF0C\u62FF\u5176 \`id\` \u56DE\u4F20 \`guid\` \u4E0B\u94BB\uFF09\u3002DSL \u4E2D\u5DF2\u5E26 \`img\` \u7684\u8282\u70B9\uFF08ICON/IMAGE \u53F6\u5B50\uFF09\u5DF2\u5B8C\u6210\u5BFC\u51FA\uFF0C\u76F4\u63A5\u7528\u5176\u6587\u4EF6\u540D\uFF0C\u4E0D\u8981\u518D\u8C03 \`export_image\`\u3002`,
+            `2. \u53D6\u6570\u636E\uFF1A\u63D2\u4EF6\u7C7B\u5DE5\u5177\u8FD4\u56DE\u7EDF\u4E00\u4E3A \`{sessionId, fileKey, data}\` \u4FE1\u5C01\uFF0C\u53D6 \`data\` \u5B57\u6BB5\u3002\u8282\u70B9\u7C7B\u5DE5\u5177\u7684 guid \u5FC5\u4F20\uFF0CfileKey/sessionId \u5FC5\u4F20\u5176\u4E00\uFF08\u4F18\u5148 fileKey\uFF1B\u9009\u533A\u573A\u666F\u7528 \`get_selected\` \u8FD4\u56DE\u7684 fileKey\uFF09\u3002\u9996\u6B21\u63A5\u89E6\u8BBE\u8BA1\u7A3F\uFF1A\u5148 \`get_metadata(guid, fileKey)\` \u62FF\u5168\u6811\u9AA8\u67B6\u5B9A\u4F4D\u76EE\u6807 + \`get_screenshot(guid, fileKey)\` \u62FF\u89C6\u89C9\u5168\u8C8C\uFF1B\u968F\u540E \`get_node_dsl(guid, fileKey)\` \u62FF\u5168\u91CF DSL\uFF08\u7ED3\u6784\u5F88\u5927\u65F6\u7528 \`maxDepth\` \u5206\u6BB5\u4E0B\u63A2\u2014\u2014\u622A\u65AD\u5904\u8282\u70B9\u5E26 \`more\` \u6807\u8BB0\u4E0E \`kidsSummary\` \u6D45\u9884\u89C8\uFF0C\u62FF\u5176 \`id\` \u56DE\u4F20 \`guid\` \u4E0B\u94BB\uFF09\u3002DSL \u4E2D\u5DF2\u5E26 \`img\` \u7684\u8282\u70B9\uFF08ICON/IMAGE \u53F6\u5B50\uFF09\u5DF2\u5B8C\u6210\u5BFC\u51FA\uFF0C\u76F4\u63A5\u7528\u5176\u6587\u4EF6\u540D\uFF0C\u4E0D\u8981\u518D\u8C03 \`export_image\`\u3002`,
             `3. \u751F\u6210\u4EE3\u7801\uFF1A\u6309\u6307\u5357\u4E2D\u7684 DSL \u5B57\u6BB5\u8BED\u4E49\u6620\u5C04\u5230\u76EE\u6807\u6846\u67B6\u3002`,
             `4. \u81EA\u68C0\uFF1A\u518D\u6B21\u8C03 \`get_screenshot(guid)\`\uFF0C\u4E0E\u4EE3\u7801\u6E32\u67D3\u7ED3\u679C\u5BF9\u6BD4\uFF0C\u6709\u504F\u5DEE\u5C31\u4FEE\u6B63\u540E\u518D\u6BD4\u4E00\u8F6E\uFF08\u5BFC\u51FA\u7C7B\u5DE5\u5177\u5E26 15 \u5206\u949F\u7F13\u5B58\uFF1B\u7ED3\u679C\u7591\u4F3C\u8FC7\u671F\u65F6\u52A0 \`cache: "refresh"\` \u5F3A\u5236\u5237\u65B0\uFF09\u3002`,
             ``,
@@ -568,15 +591,131 @@ var CommandBus = class {
 };
 var commandBus = new CommandBus();
 
+// src/plugin/sessions.ts
+import { randomUUID } from "node:crypto";
+var ONLINE_WINDOW_MS = 45e3;
+function unknownRouteError(route) {
+  if (route.fileKey) {
+    return new Error(`\u627E\u4E0D\u5230 fileKey \u4E3A ${route.fileKey} \u7684\u5B58\u6D3B\u63D2\u4EF6\u4F1A\u8BDD\u3002\u53EF\u7528 list_sessions \u67E5\u770B\u5F53\u524D\u8FDE\u63A5\u7684\u4F1A\u8BDD`);
+  }
+  return new Error(`\u627E\u4E0D\u5230 sessionId \u4E3A ${route.sessionId} \u7684\u5B58\u6D3B\u63D2\u4EF6\u4F1A\u8BDD\uFF08\u53EF\u80FD\u5DF2\u88AB\u5254\u9664\uFF09\u3002\u53EF\u7528 list_sessions \u67E5\u770B\u5F53\u524D\u8FDE\u63A5\u7684\u4F1A\u8BDD`);
+}
+var SessionRegistry = class {
+  sessions = /* @__PURE__ */ new Map();
+  lastActiveId = null;
+  /** 会话亲和：fileKey → 上一次路由使用的 sessionId（仍在线时优先，避免同文件多实例间漂移） */
+  lastUsedByFileKey = /* @__PURE__ */ new Map();
+  isOnline(s) {
+    return s.connected || Date.now() - s.lastSeen < ONLINE_WINDOW_MS;
+  }
+  /** fileKey 寻址候选：该文件的在线会话（谁先 pong 由 ping 竞速决定，此处不排序） */
+  candidatesForFileKey(fileKey) {
+    return [...this.sessions.values()].filter((s) => s.meta.fileKey === fileKey && this.isOnline(s));
+  }
+  /** 亲和查询：上一次为该 fileKey 服务的 sessionId */
+  affinityIdOf(fileKey) {
+    return this.lastUsedByFileKey.get(fileKey);
+  }
+  /** 亲和钉住：fileKey 寻址探活成功后记录（下次优先） */
+  pinAffinity(fileKey, sessionId) {
+    this.lastUsedByFileKey.set(fileKey, sessionId);
+  }
+  /** 剔除会话（幽灵剔除/ping 判死共用）：清理亲和引用；存活但繁忙被误剔的插件会在 SSE 断开或上报 404 后自重注册；
+   *  失效 sessionId 的 failover 不靠墓碑——工具结果信封带 fileKey，agent 手里的稳定句柄一直是 fileKey */
+  evict(id) {
+    if (this.sessions.delete(id)) {
+      for (const [k, v] of this.lastUsedByFileKey) {
+        if (v === id) this.lastUsedByFileKey.delete(k);
+      }
+      log(`session evicted: ${id.slice(0, 8)}`);
+    }
+  }
+  register(meta = {}) {
+    if (meta.fileKey) {
+      for (const s of [...this.sessions.values()]) {
+        if (s.meta.fileKey === meta.fileKey && !this.isOnline(s)) {
+          this.evict(s.id);
+        }
+      }
+    }
+    const session = { id: randomUUID(), meta, lastSeen: Date.now(), connected: false };
+    this.sessions.set(session.id, session);
+    this.lastActiveId = session.id;
+    log(`session registered: ${session.id} (${meta.fileName ?? "unknown file"})`);
+    return this.toInfo(session);
+  }
+  /** 心跳/连接状态用：只刷 lastSeen，不影响 lastActiveId（"最近活跃"= 用户行为，心跳不算） */
+  touchSeen(id) {
+    const s = this.sessions.get(id);
+    if (!s) return null;
+    s.lastSeen = Date.now();
+    return s;
+  }
+  /** 用户行为（选区上报/命令服务/注册）：刷 lastSeen 并标记最近活跃 */
+  touch(id) {
+    const s = this.touchSeen(id);
+    if (!s) return null;
+    this.lastActiveId = id;
+    return s;
+  }
+  setConnected(id, connected) {
+    const s = this.touchSeen(id);
+    if (!s) return false;
+    s.connected = connected;
+    return true;
+  }
+  updateContext(id, meta) {
+    const s = this.touch(id);
+    if (!s) return false;
+    s.meta = { ...s.meta, ...meta };
+    log(
+      `context updated [${id.slice(0, 8)}]: ${s.meta.fileName ?? "?"} / ${s.meta.pageName ?? "?"} / ${s.meta.selection?.length ?? 0} selected`
+    );
+    return true;
+  }
+  list() {
+    return [...this.sessions.values()].map((s) => this.toInfo(s));
+  }
+  /** 纯查找（不判活）：工具层寻址用——离线会话也可取到 fileKey 用于候选扩展与故障转移 */
+  get(id) {
+    return this.sessions.get(id);
+  }
+  /** 缺省路由：最近活跃在线会话 > 任意在线会话（显式 fileKey/sessionId 由工具层 get/candidatesForFileKey + ping 完成） */
+  resolve() {
+    if (this.lastActiveId) {
+      const s = this.sessions.get(this.lastActiveId);
+      if (s && this.isOnline(s)) return s;
+    }
+    const fallback = [...this.sessions.values()].find((s) => this.isOnline(s));
+    if (fallback) return fallback;
+    throw new Error("Pixso \u63D2\u4EF6\u672A\u8FDE\u63A5\uFF1A\u8BF7\u5728 Pixso \u5BA2\u6237\u7AEF\u4E2D\u8FD0\u884C Batter Pixso Bridge \u63D2\u4EF6");
+  }
+  toInfo(s) {
+    return {
+      sessionId: s.id,
+      fileKey: s.meta.fileKey,
+      fileName: s.meta.fileName,
+      pageName: s.meta.pageName,
+      selectionCount: s.meta.selection?.length,
+      online: this.isOnline(s),
+      lastSeen: s.lastSeen
+    };
+  }
+};
+var sessions = new SessionRegistry();
+
 // src/agent/tools/shared.ts
 var PING_TIMEOUT_MS = 800;
 async function run(type, args, signal) {
-  const { target, ...rest } = args;
+  const { fileKey, sessionId, ...rest } = args;
   try {
-    const session = await resolveAndPing(target, signal);
+    const session = await resolveAndPing(
+      { fileKey, sessionId },
+      signal
+    );
     const data = await commandBus.execute(type, rest, { sessionId: session.id, signal });
     sessions.touch(session.id);
-    return jsonResult({ sessionId: session.id, data });
+    return jsonResult({ sessionId: session.id, fileKey: session.meta.fileKey, data });
   } catch (err) {
     return errorResult(err);
   }
@@ -605,29 +744,36 @@ async function pingCandidates(candidates, affinityId, signal) {
     return null;
   }
 }
-async function resolveAndPing(target, signal) {
-  const s = target ? sessions.get(target) : sessions.resolve();
-  const fileKey = s ? s.meta.fileKey : target;
+async function resolveAndPing(route, signal) {
+  const s = route.sessionId ? sessions.get(route.sessionId) : route.fileKey ? void 0 : sessions.resolve();
+  if (route.sessionId && !s) throw unknownRouteError(route);
+  const fileKey = s ? s.meta.fileKey : route.fileKey;
   const candidates = s && !fileKey ? [s] : sessions.candidatesForFileKey(fileKey);
   if (candidates.length === 0) {
     if (s) throw new Error(`\u76EE\u6807\u63D2\u4EF6\u5DF2\u79BB\u7EBF\uFF1A${s.meta.fileName ?? s.id}\uFF08\u91CD\u65B0\u6253\u5F00\u6587\u4EF6\u5E76\u8FD0\u884C\u63D2\u4EF6\u540E\u91CD\u8BD5\uFF09`);
-    throw unknownTargetError(target);
+    throw unknownRouteError(route);
   }
   const winner = await pingCandidates(candidates, fileKey ? sessions.affinityIdOf(fileKey) : void 0, signal);
   if (!winner) {
     for (const c of candidates) sessions.evict(c.id);
     throw new Error(
-      `\u63D2\u4EF6\u65E0\u54CD\u5E94\uFF08${PING_TIMEOUT_MS}ms \u672A\u56DE pong\uFF09\uFF1A${fileKey ?? target}\u2014\u2014\u63D2\u4EF6\u672A\u8FD0\u884C\uFF0C\u6216\u6B63\u5728\u6267\u884C\u957F\u547D\u4EE4\uFF08\u7A0D\u540E\u91CD\u8BD5\uFF09`
+      `\u63D2\u4EF6\u65E0\u54CD\u5E94\uFF08${PING_TIMEOUT_MS}ms \u672A\u56DE pong\uFF09\uFF1A${fileKey ?? route.sessionId}\u2014\u2014\u63D2\u4EF6\u672A\u8FD0\u884C\uFF0C\u6216\u6B63\u5728\u6267\u884C\u957F\u547D\u4EE4\uFF08\u7A0D\u540E\u91CD\u8BD5\uFF09`
     );
   }
   if (fileKey) sessions.pinAffinity(fileKey, winner.id);
   return winner;
 }
-var ENVELOPE_NOTE = "\u8FD4\u56DE\u5C01\u88C5\u4E3A {sessionId, data}\uFF08\u9519\u8BEF\u4E3A isError \u6587\u672C\uFF0C\u4E0D\u542B\u4FE1\u5C01\uFF09\uFF1AsessionId \u662F ping/pong \u786E\u8BA4\u7684\u5B9E\u9645\u670D\u52A1\u4F1A\u8BDD\uFF1Btarget \u7528 fileKey \u6700\u7A33\u2014\u2014\u6587\u4EF6\u91CD\u5F00\u540E\u81EA\u52A8\u89E3\u6790\u5230\u5B58\u6D3B\u5B9E\u4F8B\uFF08\u591A\u5B9E\u4F8B\u4F18\u5148\u4E0A\u4E00\u6B21\u4F7F\u7528\u7684\uFF09\u3002";
+var ENVELOPE_NOTE = "\u8FD4\u56DE\u5C01\u88C5\u4E3A {sessionId, fileKey, data}\uFF08\u9519\u8BEF\u4E3A isError \u6587\u672C\uFF0C\u4E0D\u542B\u4FE1\u5C01\uFF09\uFF1AsessionId \u662F ping/pong \u786E\u8BA4\u7684\u5B9E\u9645\u670D\u52A1\u4F1A\u8BDD\uFF0CfileKey \u662F\u8DE8\u91CD\u5F00\u7A33\u5B9A\u7684\u53E5\u67C4\u2014\u2014\u540E\u7EED\u8C03\u7528\u7528 fileKey \u5BFB\u5740\u3002";
 var GUIDES_PTR = "\u5B8C\u6574\u89C4\u5219\uFF08\u8D44\u6E90\u53D6\u7528/\u7EC4\u4EF6\u6620\u5C04/\u9519\u8BEF\u6062\u590D/\u7981\u6B62\u622A\u56FE\u786C\u7F16\u7801\uFF09\u89C1\u8D44\u6E90 batter://guides/design-to-code\u3002";
-var TARGET_PROP = {
+var FILE_KEY_PROP = {
   type: "string",
-  description: "\u76EE\u6807\u63D2\u4EF6\u4F1A\u8BDD\uFF08sessionId \u6216 fileKey\uFF09\u3002\u591A\u4E2A Pixso \u6587\u4EF6\u540C\u65F6\u5F00\u63D2\u4EF6\u65F6\u624D\u9700\u8981\uFF1B\u7F3A\u7701\u8DEF\u7531\u5230\u6700\u8FD1\u6D3B\u8DC3\u6587\u4EF6\u3002\u53EF\u7528 list_sessions \u67E5\u770B\u5F53\u524D\u4F1A\u8BDD\u3002"
+  minLength: 1,
+  description: "\u76EE\u6807\u8BBE\u8BA1\u6587\u4EF6\u7684 fileKey\uFF08\u8DE8\u91CD\u5F00\u7A33\u5B9A\uFF0C\u4F18\u5148\uFF09\u3002\u4E0E sessionId \u4E8C\u9009\u4E00\uFF1B\u7528 list_sessions \u67E5\u770B\u5F53\u524D\u4F1A\u8BDD\u3002"
+};
+var SESSION_ID_PROP = {
+  type: "string",
+  minLength: 1,
+  description: "\u76EE\u6807\u63D2\u4EF6\u4F1A\u8BDD\u7684 sessionId\uFF08ping/pong \u786E\u8BA4\u7684\u5B58\u6D3B\u5B9E\u4F8B\uFF09\u3002\u4E0E fileKey \u4E8C\u9009\u4E00\u3002"
 };
 var CACHE_PROP = {
   type: "string",
@@ -636,7 +782,8 @@ var CACHE_PROP = {
 };
 var GUID_PROP = {
   type: "string",
-  description: '\u8282\u70B9 GUID\uFF08\u5982 "297:133032"\uFF09\u3002\u94FE\u63A5\u8F93\u5165\uFF1A\u4ECE item-id \u63D0\u53D6\u5E76 URL \u89E3\u7801\u540E\u4F20\u5165\uFF1B\u7F3A\u7701\u56DE\u9000\u5F53\u524D\u9009\u4E2D\u56FE\u5C42\uFF08\u7981\u6B62\u9690\u5F0F\u4F7F\u7528\u2014\u2014\u9009\u4E2D\u786E\u8BA4\u89C4\u5219\u89C1 get_selected\uFF09\u3002'
+  minLength: 1,
+  description: '\u8282\u70B9 GUID\uFF08\u5982 "297:133032"\uFF09\uFF0C\u5FC5\u4F20\u3002\u94FE\u63A5\u8F93\u5165\uFF1A\u4ECE item-id \u63D0\u53D6\u5E76 URL \u89E3\u7801\u540E\u4F20\u5165\uFF1B\u8981\u64CD\u4F5C\u5F53\u524D\u9009\u4E2D\u56FE\u5C42\u65F6\uFF0C\u5148\u7528 get_selected \u53D6\u5176 guid \u518D\u4F20\u5165\u3002'
 };
 function jsonResult(data) {
   return { content: [{ type: "text", text: JSON.stringify(data) }] };
@@ -651,40 +798,42 @@ function errorResult(err) {
 // src/agent/tools/export_image.ts
 var exportImage = {
   description: '\u3010\u7528\u9014\u3011\u5BFC\u51FA\u8282\u70B9\u7684\u56FE\u7247\u7D20\u6750\uFF08\u5207\u56FE\uFF09\uFF0C\u4F9B\u4EA4\u4ED8\u4EE3\u7801\u4F7F\u7528\u3002\u5355\u8282\u70B9\u4F20 guid\uFF1B\u591A\u8282\u70B9\u4F20 guids \u6570\u7EC4\u6279\u91CF\u3002DSL \u4E2D\u5DF2\u5E26 img \u7684\u8282\u70B9\uFF08ICON/IMAGE \u53F6\u5B50\uFF09\u5728\u53D6 DSL \u65F6\u5DF2\u5BFC\u51FA\uFF0C\u76F4\u63A5\u7528\u5176\u6587\u4EF6\u540D\uFF0C\u4E25\u7981\u5BF9\u672C\u7C7B\u8282\u70B9\u91CD\u590D\u8C03\u7528\u3002\u3010\u547D\u4E2D\u4FE1\u53F7\u3011"\u5207\u56FE/\u5BFC\u51FA\u56FE\u6807/\u5BFC\u51FA\u56FE\u7247\u7D20\u6750/\u628A\u67D0\u4E2A\u8282\u70B9\u5B58\u6210\u56FE\u7247"\u3002\u8981\u89C6\u89C9\u53C2\u7167\u7528 get_screenshot\u3002\u3010\u8FD4\u56DE\u3011\u5355\u8282\u70B9 {width, height, exports: [{img, format, scale?, suffix?}]}\uFF1B\u6279\u91CF {items: [{guid, width, height, exports}]}\u3002\u8282\u70B9\u5E26\u8BBE\u8BA1\u5E08\u5BFC\u51FA\u8BBE\u7F6E\u65F6\u6309\u5176\u8BBE\u7F6E\u9010\u4EFD\u5BFC\u51FA\uFF08format/scale \u53C2\u6570\u5931\u6548\uFF09\uFF1B\u65E0\u6807\u8BB0\u6309\u53C2\u6570\u5BFC\u51FA\u5355\u4EFD\uFF08\u9ED8\u8BA4 PNG\u30012x\uFF09\u3002suffix\uFF08\u5982 "@2x"\uFF09\u590D\u5236\u8FDB\u9879\u76EE\u65F6\u4FDD\u7559\u547D\u540D\u3002\u3010\u786C\u6027\u89C4\u5219\u3011' + GUIDES_PTR + " " + ENVELOPE_NOTE,
-  inputSchema: {
-    type: "object",
-    properties: {
-      guid: GUID_PROP,
-      guids: {
-        type: "array",
-        items: { type: "string" },
-        description: "\u6279\u91CF\u5BFC\u51FA\uFF1A\u8282\u70B9 GUID \u6570\u7EC4\uFF08\u4E0E guid \u4E8C\u9009\u4E00\uFF09\u3002\u591A\u8282\u70B9\u573A\u666F\u4F18\u5148\u7528\u6279\u91CF\uFF0C\u907F\u514D\u9010\u4E2A\u8C03\u7528\u3002"
-      },
-      format: {
-        type: "string",
-        enum: ["PNG", "SVG", "JPG"],
-        description: "\u65E0\u5BFC\u51FA\u6807\u8BB0\u65F6\u7684\u515C\u5E95\u683C\u5F0F\uFF0C\u9ED8\u8BA4 PNG\u3002\u8282\u70B9\u5E26\u5BFC\u51FA\u6807\u8BB0\u65F6\u6B64\u53C2\u6570\u65E0\u6548\u3002"
-      },
-      scale: {
-        type: "number",
-        description: "\u65E0\u5BFC\u51FA\u6807\u8BB0\u65F6\u7684\u515C\u5E95\u500D\u7387\uFF0C\u9ED8\u8BA4 2\u3002\u8282\u70B9\u5E26\u5BFC\u51FA\u6807\u8BB0\u65F6\u6B64\u53C2\u6570\u65E0\u6548\u3002"
-      },
-      cache: CACHE_PROP,
-      target: TARGET_PROP
-    }
+  // 两组互斥各取其一：guid|guids（单节点|批量）× fileKey|sessionId（路由）
+  requires: [
+    ["guid", "guids"],
+    ["fileKey", "sessionId"]
+  ],
+  properties: {
+    guid: GUID_PROP,
+    guids: {
+      type: "array",
+      items: { type: "string" },
+      description: "\u6279\u91CF\u5BFC\u51FA\uFF1A\u8282\u70B9 GUID \u6570\u7EC4\uFF08\u4E0E guid \u4E8C\u9009\u4E00\uFF09\u3002\u591A\u8282\u70B9\u573A\u666F\u4F18\u5148\u7528\u6279\u91CF\uFF0C\u907F\u514D\u9010\u4E2A\u8C03\u7528\u3002"
+    },
+    format: {
+      type: "string",
+      enum: ["PNG", "SVG", "JPG"],
+      description: "\u65E0\u5BFC\u51FA\u6807\u8BB0\u65F6\u7684\u515C\u5E95\u683C\u5F0F\uFF0C\u9ED8\u8BA4 PNG\u3002\u8282\u70B9\u5E26\u5BFC\u51FA\u6807\u8BB0\u65F6\u6B64\u53C2\u6570\u65E0\u6548\u3002"
+    },
+    scale: {
+      type: "number",
+      description: "\u65E0\u5BFC\u51FA\u6807\u8BB0\u65F6\u7684\u515C\u5E95\u500D\u7387\uFF0C\u9ED8\u8BA4 2\u3002\u8282\u70B9\u5E26\u5BFC\u51FA\u6807\u8BB0\u65F6\u6B64\u53C2\u6570\u65E0\u6548\u3002"
+    },
+    cache: CACHE_PROP,
+    fileKey: FILE_KEY_PROP,
+    sessionId: SESSION_ID_PROP
   }
 };
 
 // src/agent/tools/get_metadata.ts
 var getMetadata = {
   description: '\u3010\u7528\u9014\u3011\u5168\u6811\u7ED3\u6784\u9AA8\u67B6\uFF08\u4EC5 id/name/type/kids\uFF0C\u65E0\u6837\u5F0F/\u5750\u6807/\u8D44\u6E90\uFF0C\u4F53\u79EF\u6781\u5C0F\uFF09\u3002\u9996\u6B21\u63A5\u89E6\u8BBE\u8BA1\u7A3F\u65F6\uFF1A\u672C\u5DE5\u5177 + get_screenshot \u5B9A\u4F4D\u76EE\u6807\u8282\u70B9\uFF0C\u518D\u5BF9\u76EE\u6807\u8C03 get_node_dsl \u53D6\u5168\u91CF\u3002\u3010\u547D\u4E2D\u4FE1\u53F7\u3011\u9996\u6B21\u63A5\u89E6\u8BBE\u8BA1\u7A3F\uFF1B"\u9875\u9762\u91CC\u6709\u6CA1\u6709 XX"\uFF1B\u6309\u540D\u5B57\u627E\u8282\u70B9\uFF1B\u53EA\u8981\u7ED3\u6784\u6982\u89C8\u4E0D\u8981\u6837\u5F0F\u3002\u3010\u8FD4\u56DE\u3011\u7D27\u51D1 JSON\uFF1A{id, name?, type, kids: \u9012\u5F52}\uFF1BICON/IMAGE \u53F6\u5B50\u65E0 img\uFF08\u9700\u8D44\u6E90\u65F6\u6309 id \u8C03 get_node_dsl\uFF09\u3002\u3010\u786C\u6027\u89C4\u5219\u3011' + GUIDES_PTR + " " + ENVELOPE_NOTE,
-  inputSchema: {
-    type: "object",
-    properties: {
-      guid: GUID_PROP,
-      cache: CACHE_PROP,
-      target: TARGET_PROP
-    }
+  requires: ["guid", ["fileKey", "sessionId"]],
+  properties: {
+    guid: GUID_PROP,
+    cache: CACHE_PROP,
+    fileKey: FILE_KEY_PROP,
+    sessionId: SESSION_ID_PROP
   }
 };
 
@@ -693,52 +842,50 @@ var URL_RULE = '1. \u94FE\u63A5\u8F93\u5165\uFF1A\u5FC5\u987B\u4ECE item-id \u67
 var DSL_LEGEND = '\u5B57\u6BB5\u56FE\u4F8B\uFF1Aid=\u8282\u70B9 guid\uFF08\u53EF\u56DE\u4F20 guid \u4E0B\u94BB\uFF09\uFF1Bname=\u56FE\u5C42\u540D\uFF08\u81EA\u52A8\u547D\u540D\u5DF2\u7701\u7565\uFF09\uFF1Btype=\u8282\u70B9\u7C7B\u578B\uFF08ICON/IMAGE \u4E3A\u584C\u7F29\u53F6\u5B50\uFF09\uFF1Brect=[x,y,w,h] \u7EDD\u5BF9\u5B9A\u4F4D\uFF1Blayout={dir:row|column, gap, pad:[\u4E0A,\u53F3,\u4E0B,\u5DE6], align:[\u4E3B\u8F74,\u4EA4\u53C9\u8F74], sizing:[hug|fixed|fill]\xD72}\uFF1Bconstraints={h,v}\uFF08\u9ED8\u8BA4 left/top \u7701\u7565\uFF09\uFF1Btext={content, size, font, weight, lh, align, color, deco, ls, link, segs=\u6DF7\u6392\u5206\u6BB5\uFF08\u4EC5\u5DEE\u5F02\u5B57\u6BB5\uFF0C\u987A\u5E8F\u5373\u5B57\u7B26\u504F\u79FB\uFF09}\uFF1Bimg=\u8D44\u6E90\u6587\u4EF6\u540D\uFF1Bkids=\u5B50\u8282\u70B9\u9012\u5F52\uFF1Bpalette=\u8C03\u8272\u677F\uFF08\u4EC5\u6839\u8282\u70B9\uFF09\uFF1A\u22652 \u6B21\u7684\u5355\u8272\u63D0\u53D6\u4E3A\u6570\u7EC4\uFF0Cfills/text.color/stroke \u4E2D "p0""p1" \u4E3A\u4E0B\u6807\u5F15\u7528\uFF08\u590D\u5408 CSS \u4E32\u5185\u989C\u8272\u4E0D\u67E5\u8868\uFF09\uFF1Bnotes=\u8BBE\u8BA1\u6807\u6CE8\u6587\u672C\uFF08\u4EC5\u5B58\u5728\u65F6\uFF09\uFF1Bcomp=\u7EC4\u4EF6\u5173\u8054\uFF08INSTANCE/COMPONENT/COMPONENT_SET\uFF09\uFF1Akey=\u8DE8\u6587\u4EF6\u7A33\u5B9A\u6807\u8BC6\uFF0Cname=\u7EC4\u4EF6\u540D\uFF08\u6620\u5C04\u6743\u91CD\u6700\u9AD8\u7684\u4F9D\u636E\u2014\u2014\u5728\u9879\u76EE\u7EC4\u4EF6\u5E93\u627E\u5BF9\u5E94\uFF0C\u4E0D\u9010\u5B57\u76F4\u7528\uFF09\uFF0Cprops=variant \u5C5E\u6027\uFF0Cset=variant \u7EC4\uFF1Bdepth=\u6574\u6811\u5B9E\u9645\u6DF1\u5EA6\uFF08\u4EC5\u6839\u8282\u70B9\uFF0C\u603B\u662F\u8F93\u51FA\uFF09\uFF1Bmore=\u622A\u65AD\u5904\u5269\u4F59\u5C42\u7EA7\u6570\uFF08\u4EC5 maxDepth \u622A\u65AD\u65F6\uFF0C\u62FF id \u56DE\u4F20 guid \u4E0B\u94BB\uFF09\uFF1BkidsSummary=\u622A\u65AD\u5904\u6216\u584C\u7F29\u53F6\u5B50\uFF08img \u8282\u70B9\uFF09\u7684\u76F4\u63A5\u5B50\u8282\u70B9\u6D45\u9884\u89C8 [{id, name?, type}]\uFF08\u8F85\u52A9\u9009\u62E9\u4E0B\u94BB\u5206\u652F\uFF09\u3002\u7701\u7565\u89C4\u5219\uFF1A\u9ED8\u8BA4\u503C\u4E0D\u8F93\u51FA\uFF08text.align=left\u3001lh=normal\u3001weight=Regular\u3001gap=0\u3001pad \u5168 0\uFF09\u3002';
 var getNodeDsl = {
   description: '\u3010\u7528\u9014\u3011\u751F\u6210\u8282\u70B9\u7684\u5F00\u53D1\u5411\u7D27\u51D1 DSL\uFF08\u7ED3\u6784+\u6837\u5F0F+\u8D44\u6E90\u6587\u4EF6\u540D\uFF09\uFF0C\u8BBE\u8BA1\u8F6C\u4EE3\u7801\u7684\u6838\u5FC3\u5165\u53E3\u3002\u3010\u547D\u4E2D\u4FE1\u53F7\u3011"\u6837\u5F0F\u8FD8\u539F/\u8BBE\u8BA1\u8FD8\u539F/UI \u8FD8\u539F/\u8BBE\u8BA1\u8F6C\u4EE3\u7801/\u6839\u636E\u8BBE\u8BA1\u7A3F\u5199\u9875\u9762\u3001\u7EC4\u4EF6"\uFF0C\u6216\u7ED9\u51FA Pixso \u94FE\u63A5\uFF08\u4EFB\u610F\u57DF\u540D\uFF09\u65F6\uFF0C\u9ED8\u8BA4\u4ECE\u672C\u5DE5\u5177\u5F00\u59CB\u3002\u9996\u6B21\u63A5\u89E6\u8BBE\u8BA1\u7A3F\uFF1A\u5148 get_metadata \u9AA8\u67B6 + get_screenshot \u89C6\u89C9\uFF0C\u5B9A\u4F4D\u76EE\u6807\u540E\u518D\u7528\u672C\u5DE5\u5177\u3002\u7ED3\u6784\u590D\u6742\uFF1AmaxDepth \u4F20 0 \u9884\u5224\u89C4\u6A21\uFF08\u6839\u8282\u70B9 depth=\u6574\u6811\u6DF1\u5EA6\uFF09\uFF0C\u518D\u5BF9\u5E26 more \u6807\u8BB0\u7684\u5B50\u6811\u6309 id \u4E0B\u94BB\uFF08kidsSummary \u8F85\u52A9\u9009\u5206\u652F\uFF09\u3002\u3010\u8FD4\u56DE\u3011\u5355\u884C\u7D27\u51D1 JSON\u3002' + DSL_LEGEND + "\u584C\u7F29\u53F6\u5B50\uFF1A\u7EAF\u77E2\u91CF\u7EC4\u4EF6\u5B9E\u4F8B\u2192SVG\u3001\u56FE\u7247\u586B\u5145\u2192PNG\u3001\u8BBE\u8BA1\u5E08\u6807\u8BB0\u6309\u5176\u8BBE\u7F6E\uFF1B\u5DF2\u5E26 img \u7684\u8282\u70B9\u5DF2\u5B8C\u6210\u5BFC\u51FA\uFF0C\u76F4\u63A5\u7528\u5176\u6587\u4EF6\u540D\uFF0C\u52FF\u518D\u8C03 export_image\u3002DSL \u6709\u635F\u7CBE\u7B80\uFF08\u7701\u7565\u8499\u7248/\u5E03\u5C14\u8DEF\u5F84\u7B49\uFF09\uFF0C\u89C6\u89C9\u590D\u6742\u8282\u70B9\u914D\u5408 get_screenshot \u5BF9\u7167\u3002\u3010\u786C\u6027\u89C4\u5219\u3011" + URL_RULE + " " + GUIDES_PTR + " " + ENVELOPE_NOTE,
-  inputSchema: {
-    type: "object",
-    properties: {
-      guid: GUID_PROP,
-      maxDepth: {
-        type: "number",
-        description: "\u4E0B\u63A2\u5B50\u8282\u70B9\u7684\u6700\u5927\u6DF1\u5EA6\uFF08\u6839\u8282\u70B9\u4E3A\u7B2C 0 \u5C42\uFF09\uFF0C\u7F3A\u7701\u4E0D\u9650\u3002\u622A\u65AD\u8282\u70B9\u5E26 more\uFF08\u5269\u4F59\u5C42\u7EA7\u6570\uFF09+ kidsSummary\uFF08\u5B50\u8282\u70B9\u6D45\u9884\u89C8\uFF09\uFF0C\u62FF\u5176 id \u56DE\u4F20 guid \u7EE7\u7EED\u4E0B\u94BB\uFF1B\u4F20 0 \u53EA\u8FD4\u56DE\u6839\u8282\u70B9\uFF08\u914D\u5408 depth \u5B57\u6BB5\u9884\u5224\u89C4\u6A21\uFF09\u3002"
-      },
-      cache: CACHE_PROP,
-      target: TARGET_PROP
-    }
+  requires: ["guid", ["fileKey", "sessionId"]],
+  properties: {
+    guid: GUID_PROP,
+    maxDepth: {
+      type: "number",
+      description: "\u4E0B\u63A2\u5B50\u8282\u70B9\u7684\u6700\u5927\u6DF1\u5EA6\uFF08\u6839\u8282\u70B9\u4E3A\u7B2C 0 \u5C42\uFF09\uFF0C\u7F3A\u7701\u4E0D\u9650\u3002\u622A\u65AD\u8282\u70B9\u5E26 more\uFF08\u5269\u4F59\u5C42\u7EA7\u6570\uFF09+ kidsSummary\uFF08\u5B50\u8282\u70B9\u6D45\u9884\u89C8\uFF09\uFF0C\u62FF\u5176 id \u56DE\u4F20 guid \u7EE7\u7EED\u4E0B\u94BB\uFF1B\u4F20 0 \u53EA\u8FD4\u56DE\u6839\u8282\u70B9\uFF08\u914D\u5408 depth \u5B57\u6BB5\u9884\u5224\u89C4\u6A21\uFF09\u3002"
+    },
+    cache: CACHE_PROP,
+    fileKey: FILE_KEY_PROP,
+    sessionId: SESSION_ID_PROP
   }
 };
 
 // src/agent/tools/get_screenshot.ts
 var getScreenshot = {
   description: '\u3010\u7528\u9014\u3011\u5BFC\u51FA\u5355\u4E2A\u8282\u70B9\u7684\u622A\u56FE\uFF0C\u4F5C\u89C6\u89C9\u53C2\u7167\u3002\u3010\u547D\u4E2D\u4FE1\u53F7\u3011"\u770B\u770B\u8FD9\u4E2A\u8BBE\u8BA1\u7A3F\u957F\u4EC0\u4E48\u6837"/"\u7ED9\u6211\u622A\u56FE"\uFF1B\u8FD8\u539F\u4EFB\u52A1\u9700\u8981\u89C6\u89C9\u53C2\u7167\u6216\u8FD8\u539F\u5EA6\u6821\u9A8C\u3002\u8981\u5207\u56FE\u7D20\u6750\u7528 export_image\u3002\u751F\u6210\u4EE3\u7801\u540E\u53EF\u518D\u6B21\u8C03\u7528\u672C\u5DE5\u5177\u5BF9\u6BD4\u8FD8\u539F\u5EA6\uFF1B\u5EFA\u8BAE\u4E0E get_node_dsl \u914D\u5408\uFF1ADSL \u5B9A\u7ED3\u6784\uFF0C\u622A\u56FE\u6821\u9A8C\u89C6\u89C9\u3002\u3010\u8FD4\u56DE\u3011{img: \u4EA7\u7269\u6587\u4EF6\u540D, width, height, format}\u3002\u3010\u786C\u6027\u89C4\u5219\u3011' + GUIDES_PTR + " " + ENVELOPE_NOTE,
-  inputSchema: {
-    type: "object",
-    properties: {
-      guid: GUID_PROP,
-      format: {
-        type: "string",
-        enum: ["PNG", "SVG"],
-        description: "\u5BFC\u51FA\u683C\u5F0F\uFF0C\u9ED8\u8BA4 PNG\u3002\u622A\u56FE\u7528\u9014\u7528 PNG\uFF1B\u7EAF\u56FE\u5F62\u60F3\u62FF\u77E2\u91CF\u518D\u9009 SVG\u3002"
-      },
-      scale: {
-        type: "number",
-        description: "\u5BFC\u51FA\u500D\u7387\uFF0C\u9ED8\u8BA4 2\u3002"
-      },
-      cache: CACHE_PROP,
-      target: TARGET_PROP
-    }
+  requires: ["guid", ["fileKey", "sessionId"]],
+  properties: {
+    guid: GUID_PROP,
+    format: {
+      type: "string",
+      enum: ["PNG", "SVG"],
+      description: "\u5BFC\u51FA\u683C\u5F0F\uFF0C\u9ED8\u8BA4 PNG\u3002\u622A\u56FE\u7528\u9014\u7528 PNG\uFF1B\u7EAF\u56FE\u5F62\u60F3\u62FF\u77E2\u91CF\u518D\u9009 SVG\u3002"
+    },
+    scale: {
+      type: "number",
+      description: "\u5BFC\u51FA\u500D\u7387\uFF0C\u9ED8\u8BA4 2\u3002"
+    },
+    cache: CACHE_PROP,
+    fileKey: FILE_KEY_PROP,
+    sessionId: SESSION_ID_PROP
   }
 };
 
 // src/agent/tools/get_selected.ts
 var getSelected = {
-  description: '\u3010\u7528\u9014\u3011\u5B9E\u65F6\u8BFB\u53D6 Pixso \u753B\u5E03\u5F53\u524D\u9009\u4E2D\u7684\u56FE\u5C42\uFF08guid\u3001\u540D\u79F0\u3001\u7C7B\u578B\uFF09\u3002\u3010\u547D\u4E2D\u4FE1\u53F7\u3011\u7528\u6237\u8BF4"\u8FD9\u4E2A/\u5F53\u524D\u9009\u4E2D\u7684"\u56FE\u5C42\u3001\u7EC4\u4EF6\u3002\u5DF2\u7ED9 Pixso \u94FE\u63A5\u65F6\u4E0D\u8981\u7528\u672C\u5DE5\u5177\u2014\u2014\u76F4\u63A5\u4ECE\u94FE\u63A5\u63D0\u53D6 guid\uFF08\u89C1 get_node_dsl\uFF09\u3002\u3010\u8FD4\u56DE\u3011{fileKey, fileName, pageName, selection: [{id, name, type}]}\u3002\u3010\u786C\u6027\u89C4\u5219\u3011\u4E25\u7981\u9690\u5F0F\u4F7F\u7528\u8FD4\u56DE\u7684 guid\uFF1A\u9664\u975E\u7528\u6237\u660E\u786E\u8BF4\u4E86"\u6211\u9009\u4E2D\u7684/\u5F53\u524D\u9009\u4E2D\u7684"\uFF0C\u5FC5\u987B\u5148\u628A\u9009\u4E2D\u56FE\u5C42\u540D\u79F0\u62A5\u7ED9\u7528\u6237\u786E\u8BA4\uFF08"\u5F53\u524D\u9009\u4E2D\u7684\u662F\u300CXX\u300D\uFF0C\u786E\u8BA4\u5904\u7406\u5B83\u5417\uFF1F"\uFF09\uFF0C\u786E\u8BA4\u540E\u624D\u80FD\u4F20\u7ED9\u5176\u4ED6\u5DE5\u5177\u3002 ' + ENVELOPE_NOTE,
-  inputSchema: { type: "object", properties: { target: TARGET_PROP } }
+  description: '\u3010\u7528\u9014\u3011\u5B9E\u65F6\u8BFB\u53D6 Pixso \u753B\u5E03\u5F53\u524D\u9009\u4E2D\u7684\u56FE\u5C42\uFF08guid\u3001\u540D\u79F0\u3001\u7C7B\u578B\uFF09\u3002\u3010\u547D\u4E2D\u4FE1\u53F7\u3011\u7528\u6237\u8BF4"\u8FD9\u4E2A/\u5F53\u524D\u9009\u4E2D\u7684"\u56FE\u5C42\u3001\u7EC4\u4EF6\u3002\u5DF2\u7ED9 Pixso \u94FE\u63A5\u65F6\u4E0D\u8981\u7528\u672C\u5DE5\u5177\u2014\u2014\u76F4\u63A5\u4ECE\u94FE\u63A5\u63D0\u53D6 guid\uFF08\u89C1 get_node_dsl\uFF09\u3002\u3010\u8FD4\u56DE\u3011{fileKey, fileName, pageName, selection: [{id, name, type}]}\u3002\u3010\u786C\u6027\u89C4\u5219\u3011\u4E25\u7981\u9690\u5F0F\u4F7F\u7528\u8FD4\u56DE\u7684 guid\uFF1A\u9664\u975E\u7528\u6237\u660E\u786E\u8BF4\u4E86"\u6211\u9009\u4E2D\u7684/\u5F53\u524D\u9009\u4E2D\u7684"\uFF0C\u5FC5\u987B\u5148\u628A\u9009\u4E2D\u56FE\u5C42\u540D\u79F0\u62A5\u7ED9\u7528\u6237\u786E\u8BA4\uFF08"\u5F53\u524D\u9009\u4E2D\u7684\u662F\u300CXX\u300D\uFF0C\u786E\u8BA4\u5904\u7406\u5B83\u5417\uFF1F"\uFF09\uFF0C\u786E\u8BA4\u540E\u624D\u80FD\u4F20\u7ED9\u5176\u4ED6\u5DE5\u5177\u3002\u672C\u5DE5\u5177\u7684 fileKey/sessionId \u53EF\u7F3A\u7701\uFF08\u8DEF\u7531\u5230\u6700\u8FD1\u6D3B\u8DC3\u6587\u4EF6\uFF09\uFF1B\u5176\u4ED6\u5DE5\u5177\u4E24\u8005\u5FC5\u4F20\u5176\u4E00\u3002 ' + ENVELOPE_NOTE,
+  properties: { fileKey: FILE_KEY_PROP, sessionId: SESSION_ID_PROP }
 };
 
 // src/agent/tools/list_sessions.ts
 var listSessions = {
-  description: "\u3010\u7528\u9014\u3011\u5217\u51FA\u5B58\u6D3B\u7684\u8BBE\u8BA1\u7A3F\u63D2\u4EF6\u4F1A\u8BDD\uFF08sessionId\u3001\u6587\u4EF6\u3001\u9875\u9762\u3001\u9009\u4E2D\u6570\uFF09\u2014\u2014\u6BCF\u6B21\u8C03\u7528\u7ECF ping/pong \u5B9E\u6D4B\uFF0C\u65E0\u54CD\u5E94\u7684\u4E0D\u51FA\u73B0\u3002\u6BCF\u4E2A\u8FD0\u884C\u63D2\u4EF6\u7684\u8BBE\u8BA1\u6587\u4EF6\u5BF9\u5E94\u4E00\u4E2A\u4F1A\u8BDD\u3002\u3010\u547D\u4E2D\u4FE1\u53F7\u3011\u591A\u4E2A Pixso \u6587\u4EF6\u540C\u65F6\u5F00\u63D2\u4EF6\u65F6\uFF0C\u5148\u7528\u672C\u5DE5\u5177\u786E\u8BA4\u76EE\u6807\u6587\u4EF6\uFF1B\u53EA\u6709\u4E00\u4E2A\u4F1A\u8BDD\u65F6\u65E0\u9700\u5173\u6CE8\u672C\u5DE5\u5177\u3002\u3010\u8FD4\u56DE\u3011\u4F1A\u8BDD\u5217\u8868 JSON\u3002\u628A sessionId \u6216 fileKey \u4F5C\u4E3A\u5176\u4ED6\u5DE5\u5177\u7684 target \u53C2\u6570\u4F20\u5165\u5373\u8DEF\u7531\u5230\u5BF9\u5E94\u6587\u4EF6\uFF1B\u4E0D\u4F20 target \u65F6\u8DEF\u7531\u5230\u6700\u8FD1\u6D3B\u8DC3\u7684\u6587\u4EF6\u3002\u8BE6\u89C1\u8D44\u6E90 batter://guides/intro\u3002",
-  inputSchema: { type: "object", properties: {} },
+  description: "\u3010\u7528\u9014\u3011\u5217\u51FA\u5B58\u6D3B\u7684\u8BBE\u8BA1\u7A3F\u63D2\u4EF6\u4F1A\u8BDD\uFF08sessionId\u3001\u6587\u4EF6\u3001\u9875\u9762\u3001\u9009\u4E2D\u6570\uFF09\u2014\u2014\u6BCF\u6B21\u8C03\u7528\u7ECF ping/pong \u5B9E\u6D4B\uFF0C\u65E0\u54CD\u5E94\u7684\u4E0D\u51FA\u73B0\u3002\u6BCF\u4E2A\u8FD0\u884C\u63D2\u4EF6\u7684\u8BBE\u8BA1\u6587\u4EF6\u5BF9\u5E94\u4E00\u4E2A\u4F1A\u8BDD\u3002\u3010\u547D\u4E2D\u4FE1\u53F7\u3011\u591A\u4E2A Pixso \u6587\u4EF6\u540C\u65F6\u5F00\u63D2\u4EF6\u65F6\uFF0C\u5148\u7528\u672C\u5DE5\u5177\u786E\u8BA4\u76EE\u6807\u6587\u4EF6\uFF1B\u53EA\u6709\u4E00\u4E2A\u4F1A\u8BDD\u65F6\u65E0\u9700\u5173\u6CE8\u672C\u5DE5\u5177\u3002\u3010\u8FD4\u56DE\u3011\u4F1A\u8BDD\u5217\u8868 JSON\u3002\u628A fileKey\uFF08\u8DE8\u91CD\u5F00\u7A33\u5B9A\uFF0C\u4F18\u5148\uFF09\u6216 sessionId \u4F5C\u4E3A\u5176\u4ED6\u5DE5\u5177\u7684\u540C\u540D\u53C2\u6570\u4F20\u5165\u5373\u8DEF\u7531\u5230\u5BF9\u5E94\u6587\u4EF6\uFF08\u8282\u70B9\u7C7B\u5DE5\u5177\u4E8C\u8005\u5FC5\u4F20\u5176\u4E00\uFF1B\u4EC5 get_selected \u4E0E\u672C\u5DE5\u5177\u53EF\u7F3A\u7701\uFF09\u3002\u8BE6\u89C1\u8D44\u6E90 batter://guides/intro\u3002",
+  properties: {},
   handler: async () => {
     const list = sessions.list();
     if (!list.length) {
@@ -779,16 +926,48 @@ var TOOL_REGISTRY = {
   get_screenshot: getScreenshot,
   list_sessions: listSessions
 };
+function buildInputSchema(requires, properties) {
+  const singles = requires.filter((r) => typeof r === "string");
+  const xorGroups = requires.filter((r) => Array.isArray(r));
+  const groupSchemas = xorGroups.map((g) => ({ oneOf: g.map((p) => ({ required: [p] })) }));
+  return {
+    type: "object",
+    ...singles.length ? { required: singles } : {},
+    ...groupSchemas.length === 1 ? groupSchemas[0] : {},
+    ...groupSchemas.length > 1 ? { allOf: groupSchemas } : {},
+    properties
+  };
+}
+function validateArgs(requires, args) {
+  const present = (k) => args[k] !== void 0 && args[k] !== null && args[k] !== "";
+  for (const req of requires) {
+    if (typeof req === "string") {
+      if (!present(req)) return `\u7F3A\u5C11\u5FC5\u4F20\u53C2\u6570\uFF1A${req}`;
+      continue;
+    }
+    const given = req.filter(present);
+    if (given.length === 0) return `\u7F3A\u5C11\u53C2\u6570\uFF1A${req.join(" / ")} \u9700\u4F20\u4E00\u4E2A`;
+    if (given.length > 1) return `\u53C2\u6570\u4E92\u65A5\uFF1A${req.join(" / ")} \u53EA\u80FD\u4F20\u4E00\u4E2A`;
+  }
+  return null;
+}
 var TOOLS = Object.fromEntries(
   Object.entries(TOOL_REGISTRY).map(([name, def]) => {
-    const handler = def.handler ?? ((args, ctx) => run(name, args, ctx?.signal));
-    const resolvedDef = { description: def.description, inputSchema: def.inputSchema, handler };
-    return [name, { def: resolvedDef, tool: { name, description: def.description, inputSchema: def.inputSchema } }];
+    const requires = def.requires ?? [];
+    const inputSchema = buildInputSchema(requires, def.properties);
+    const base = def.handler ?? ((args, ctx) => run(name, args, ctx?.signal));
+    const handler = (args, ctx) => {
+      const err = requires.length ? validateArgs(requires, args) : null;
+      if (err) return Promise.resolve(errorResult(err));
+      return base(args, ctx);
+    };
+    const resolvedDef = { description: def.description, inputSchema, handler };
+    return [name, { def: resolvedDef, tool: { name, description: def.description, inputSchema } }];
   })
 );
 
 // src/agent/mcp.ts
-var INSTRUCTIONS = `Pixso \u8BBE\u8BA1\u7A3F\u8F6C\u4EE3\u7801\u670D\u52A1\u3002\u6309\u7528\u6237\u8F93\u5165\u8DEF\u7531\uFF1A1. \u7ED9\u51FA Pixso \u94FE\u63A5\uFF08\u4EFB\u610F\u57DF\u540D\uFF09\u2192 \u4ECE item-id \u63D0\u53D6 guid\uFF08URL \u89E3\u7801\uFF09\uFF0C\u76F4\u63A5\u8C03 get_node_dsl / get_screenshot / export_image\uFF1B2. \u8BF4"\u6211\u9009\u4E2D\u7684/\u5F53\u524D\u9009\u4E2D\u7684"\u2192 get_selected \u62FF guid\uFF1B\u5176\u4ED6\u4F9D\u8D56\u9009\u533A\u7684\u573A\u666F\u5148 get_selected \u518D\u5411\u7528\u6237\u62A5\u540D\u79F0\u786E\u8BA4\uFF1B3. "\u6837\u5F0F\u8FD8\u539F/\u8BBE\u8BA1\u8FD8\u539F/UI \u8FD8\u539F/\u8BBE\u8BA1\u8F6C\u4EE3\u7801"\u2192 get_node_dsl \u53D6\u7ED3\u6784 + get_screenshot \u53D6\u89C6\u89C9\u53C2\u7167\uFF1B4. "\u5207\u56FE/\u5BFC\u51FA\u56FE\u6807\u6216\u56FE\u7247\u7D20\u6750"\u2192 export_image\uFF08DSL \u91CC\u5DF2\u5E26 img \u7684\u8282\u70B9\u76F4\u63A5\u7528\u5176\u6587\u4EF6\u540D\uFF0C\u4E0D\u8981\u91CD\u590D\u5BFC\u51FA\uFF09\uFF1B5. \u9996\u6B21\u63A5\u89E6\u8BBE\u8BA1\u7A3F/\u53EA\u8981\u7ED3\u6784\u6982\u89C8 \u2192 get_metadata \u62FF\u5168\u6811\u9AA8\u67B6\uFF08\u65E0\u6837\u5F0F\u65E0\u8D44\u6E90\uFF0C\u4F53\u79EF\u6781\u5C0F\uFF09\u5B9A\u4F4D\u76EE\u6807\u8282\u70B9\uFF1B\u7ED3\u6784\u590D\u6742 \u2192 get_node_dsl \u7528 maxDepth \u5206\u6BB5\u4E0B\u63A2\uFF08\u622A\u65AD\u5904 more \u6807\u8BB0 + kidsSummary \u6D45\u9884\u89C8\uFF0C\u6309 id \u4E0B\u94BB\uFF09\uFF1B6. \u751F\u6210\u540E\u5BF9\u6BD4\u8FD8\u539F\u5EA6 \u2192 get_screenshot \u6821\u9A8C\u5FAA\u73AF\uFF1B7. \u591A\u4E2A Pixso \u6587\u4EF6\u540C\u65F6\u6253\u5F00 \u2192 list_sessions + target \u53C2\u6570\u8DEF\u7531\u3002\u786C\u6027\u89C4\u5219\uFF08\u8D44\u6E90\u53D6\u7528/\u7EC4\u4EF6\u6620\u5C04/\u9519\u8BEF\u6062\u590D/\u7981\u6B62\u622A\u56FE\u786C\u7F16\u7801\uFF09\u89C1\u8D44\u6E90 batter://guides/design-to-code\u2014\u2014\u5199\u4EE3\u7801\u524D\u5FC5\u8BFB\u3002`;
+var INSTRUCTIONS = `Pixso \u8BBE\u8BA1\u7A3F\u8F6C\u4EE3\u7801\u670D\u52A1\u3002\u6309\u7528\u6237\u8F93\u5165\u8DEF\u7531\uFF1A1. \u7ED9\u51FA Pixso \u94FE\u63A5\uFF08\u4EFB\u610F\u57DF\u540D\uFF09\u2192 \u4ECE item-id \u63D0\u53D6 guid\uFF08URL \u89E3\u7801\uFF09\uFF0C\u76F4\u63A5\u8C03 get_node_dsl / get_screenshot / export_image\uFF1B2. \u8BF4"\u6211\u9009\u4E2D\u7684/\u5F53\u524D\u9009\u4E2D\u7684"\u2192 get_selected \u62FF guid\uFF1B\u5176\u4ED6\u4F9D\u8D56\u9009\u533A\u7684\u573A\u666F\u5148 get_selected \u518D\u5411\u7528\u6237\u62A5\u540D\u79F0\u786E\u8BA4\uFF1B3. "\u6837\u5F0F\u8FD8\u539F/\u8BBE\u8BA1\u8FD8\u539F/UI \u8FD8\u539F/\u8BBE\u8BA1\u8F6C\u4EE3\u7801"\u2192 get_node_dsl \u53D6\u7ED3\u6784 + get_screenshot \u53D6\u89C6\u89C9\u53C2\u7167\uFF1B4. "\u5207\u56FE/\u5BFC\u51FA\u56FE\u6807\u6216\u56FE\u7247\u7D20\u6750"\u2192 export_image\uFF08DSL \u91CC\u5DF2\u5E26 img \u7684\u8282\u70B9\u76F4\u63A5\u7528\u5176\u6587\u4EF6\u540D\uFF0C\u4E0D\u8981\u91CD\u590D\u5BFC\u51FA\uFF09\uFF1B5. \u9996\u6B21\u63A5\u89E6\u8BBE\u8BA1\u7A3F/\u53EA\u8981\u7ED3\u6784\u6982\u89C8 \u2192 get_metadata \u62FF\u5168\u6811\u9AA8\u67B6\uFF08\u65E0\u6837\u5F0F\u65E0\u8D44\u6E90\uFF0C\u4F53\u79EF\u6781\u5C0F\uFF09\u5B9A\u4F4D\u76EE\u6807\u8282\u70B9\uFF1B\u7ED3\u6784\u590D\u6742 \u2192 get_node_dsl \u7528 maxDepth \u5206\u6BB5\u4E0B\u63A2\uFF08\u622A\u65AD\u5904 more \u6807\u8BB0 + kidsSummary \u6D45\u9884\u89C8\uFF0C\u6309 id \u4E0B\u94BB\uFF09\uFF1B6. \u751F\u6210\u540E\u5BF9\u6BD4\u8FD8\u539F\u5EA6 \u2192 get_screenshot \u6821\u9A8C\u5FAA\u73AF\uFF1B7. \u591A\u4E2A Pixso \u6587\u4EF6\u540C\u65F6\u6253\u5F00 \u2192 list_sessions + fileKey/sessionId \u53C2\u6570\u8DEF\u7531\uFF08\u8282\u70B9\u7C7B\u5DE5\u5177\u4E8C\u8005\u5FC5\u4F20\u5176\u4E00\uFF09\u3002\u786C\u6027\u89C4\u5219\uFF08\u8D44\u6E90\u53D6\u7528/\u7EC4\u4EF6\u6620\u5C04/\u9519\u8BEF\u6062\u590D/\u7981\u6B62\u622A\u56FE\u786C\u7F16\u7801\uFF09\u89C1\u8D44\u6E90 batter://guides/design-to-code\u2014\u2014\u5199\u4EE3\u7801\u524D\u5FC5\u8BFB\u3002`;
 function createMcpServer() {
   const server = new McpServer(
     { name: HUB_NAME, version: VERSION },
@@ -844,15 +1023,28 @@ function createMcpServer() {
 // src/agent/sessions.ts
 var transports = /* @__PURE__ */ new Map();
 function getMcpTransport(sessionId) {
-  return transports.get(sessionId);
+  const entry = transports.get(sessionId);
+  if (entry) entry.lastSeen = Date.now();
+  return entry?.transport;
 }
 function registerMcpTransport(sessionId, transport) {
-  transports.set(sessionId, transport);
+  transports.set(sessionId, { transport, lastSeen: Date.now() });
   log(`MCP HTTP session initialized: ${sessionId.slice(0, 8)} (total ${transports.size})`);
   transport.onclose = () => {
     if (transport.sessionId) transports.delete(transport.sessionId);
   };
 }
+var sweeper = setInterval(() => {
+  const now = Date.now();
+  for (const [id, entry] of transports) {
+    if (now - entry.lastSeen <= config.mcpSessionTtlMs) continue;
+    transports.delete(id);
+    void entry.transport.close().catch(() => {
+    });
+    log(`MCP HTTP session expired: ${id.slice(0, 8)} (total ${transports.size})`);
+  }
+}, 6e4);
+sweeper.unref();
 
 // src/agent/http.ts
 function handleMcp(req, res, url) {
@@ -908,18 +1100,18 @@ var MCP_ROUTES = [
 // src/install/dist-resolver.ts
 import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { join as join3 } from "node:path";
-import { fileURLToPath } from "node:url";
+import { join as join4 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 function resolvePluginDir() {
   const candidates = [
-    fileURLToPath(new URL("./plugin/", import.meta.url)),
+    fileURLToPath2(new URL("./plugin/", import.meta.url)),
     // bundle: dist/index.js → dist/plugin/
-    fileURLToPath(new URL("../../plugin/dist/", import.meta.url)),
+    fileURLToPath2(new URL("../../plugin/dist/", import.meta.url)),
     // bundle 开发: dist/index.js → packages/plugin/dist/
-    fileURLToPath(new URL("../../../plugin/dist/", import.meta.url))
+    fileURLToPath2(new URL("../../../plugin/dist/", import.meta.url))
     // tsx 开发: src/install/ → packages/plugin/dist/
   ];
-  return candidates.find((p) => existsSync(join3(p, "manifest.json"))) ?? null;
+  return candidates.find((p) => existsSync(join4(p, "manifest.json"))) ?? null;
 }
 var resolved = null;
 function pluginDir() {
@@ -932,7 +1124,7 @@ function hasPluginDist() {
 async function pluginManifest() {
   const dir = pluginDir();
   if (!dir) return null;
-  const raw = JSON.parse(await readFile(join3(dir, "manifest.json"), "utf8"));
+  const raw = JSON.parse(await readFile(join4(dir, "manifest.json"), "utf8"));
   raw.networkAccess = {
     allowedDomains: [`http://localhost:${config.httpPort}`, `http://127.0.0.1:${config.httpPort}`]
   };
@@ -942,7 +1134,7 @@ async function readPluginFile(name) {
   const dir = pluginDir();
   if (!dir) return null;
   try {
-    return await readFile(join3(dir, name));
+    return await readFile(join4(dir, name));
   } catch {
     return null;
   }
@@ -1590,14 +1782,22 @@ var PLUGIN_ROUTES = [
 
 `);
       });
+      const teardown = () => {
+        clearInterval(heartbeat);
+        unsubscribe();
+        sessions.setConnected(session, false);
+      };
       const heartbeat = setInterval(() => {
+        if (!res.write(": ping\n\n")) {
+          teardown();
+          res.end();
+          log(`SSE ghost reaped: session ${session.slice(0, 8)}`);
+          return;
+        }
         sessions.touchSeen(session);
-        res.write(": ping\n\n");
       }, 15e3);
       req.on("close", () => {
-        clearInterval(heartbeat);
-        unsubscribe();
-        sessions.setConnected(session, false);
+        teardown();
         log(`SSE channel closed: session ${session.slice(0, 8)}`);
       });
     }
@@ -1627,14 +1827,9 @@ var PLUGIN_ROUTES = [
 ];
 
 // src/http.ts
-var lastActivity = Date.now();
-function getLastActivity() {
-  return lastActivity;
-}
 var ROUTES = [handleInstall, handleMcp, handlePluginApi];
 function startHttpServer() {
   const server = createServer((req, res) => {
-    lastActivity = Date.now();
     res.setHeader("Access-Control-Allow-Origin", "*");
     res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
     res.setHeader("Access-Control-Allow-Headers", "Content-Type, mcp-session-id");
@@ -1685,19 +1880,11 @@ async function runHub() {
     log(`\u7AEF\u53E3 ${config.httpPort} \u5DF2\u6709 hub \u5728\u8FD0\u884C\uFF0C\u672C\u8FDB\u7A0B\u9000\u51FA`);
     process.exit(0);
   }
-  log(`hub ready (idle TTL ${config.hubIdleMs / 6e4}min)`);
+  writePidFile(process.pid);
+  log("hub ready\uFF08\u5E38\u9A7B\uFF0C\u4E0D\u81EA\u6BC1\uFF1B\u7248\u672C\u4E0D\u7B26\u65F6\u7531 proxy \u81EA\u52A8\u6362\u8840\uFF0C\u6216 --stop \u624B\u52A8\u505C\u6B62\uFF09");
   void cleanOldAssets(config.assetTtlMs);
-  let tick = 0;
-  const watchdog = setInterval(() => {
-    const idle = Date.now() - getLastActivity();
-    const anyPluginOnline = sessions.list().some((s) => s.online);
-    if (idle > config.hubIdleMs && !anyPluginOnline) {
-      log(`\u7A7A\u95F2 ${Math.round(idle / 6e4)} \u5206\u949F\u4E14\u65E0\u5728\u7EBF\u63D2\u4EF6\uFF0Chub \u81EA\u52A8\u9000\u51FA`);
-      process.exit(0);
-    }
-    if (++tick % 60 === 0) void cleanOldAssets(config.assetTtlMs);
-  }, 6e4);
-  watchdog.unref();
+  const sweeper2 = setInterval(() => void cleanOldAssets(config.assetTtlMs), 60 * 6e4);
+  sweeper2.unref();
 }
 
 // src/process/stdio-proxy.ts
@@ -1706,64 +1893,6 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { ResultSchema } from "@modelcontextprotocol/sdk/types.js";
-
-// src/process/hub-process.ts
-import { spawn } from "node:child_process";
-import { closeSync, openSync } from "node:fs";
-import { tmpdir as tmpdir2 } from "node:os";
-import { join as join4 } from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
-async function probeHub() {
-  try {
-    const res = await fetch(`${hubBaseUrl()}/health`, { signal: AbortSignal.timeout(1500) });
-    if (!res.ok) return "foreign";
-    const body = await res.json();
-    if (body.ok === true && body.name === HUB_NAME) return "alive";
-    if (body.ok === true) return "legacy";
-    return "foreign";
-  } catch {
-    return "down";
-  }
-}
-var PORT_FIX_HINT = `\u7528 netstat -ano | findstr :${config.httpPort} \u67E5\u5230 PID \u540E taskkill /PID <pid> /F \u7ED3\u675F\uFF0C\u518D\u91CD\u8BD5`;
-function hubStateError(state) {
-  if (state === "legacy") {
-    return new Error(
-      `\u7AEF\u53E3 ${config.httpPort} \u4E0A\u662F\u65E7\u7248\u672C batter-pixso-mcp \u5B9E\u4F8B\uFF08\u4E0D\u652F\u6301\u591A agent \u590D\u7528\uFF09\u3002${PORT_FIX_HINT}`
-    );
-  }
-  return new Error(`\u7AEF\u53E3 ${config.httpPort} \u88AB\u5176\u4ED6\u7A0B\u5E8F\u5360\u7528\u3002${PORT_FIX_HINT}\uFF0C\u6216\u4FEE\u6539 HTTP_PORT \u6362\u7AEF\u53E3`);
-}
-var HUB_LOG = join4(tmpdir2(), "batter-pixso-mcp-hub.log");
-function spawnHub() {
-  const out = openSync(HUB_LOG, "a");
-  const entry = process.argv[1] ?? fileURLToPath2(import.meta.url);
-  const SKIP_FLAGS = /* @__PURE__ */ new Set(["--eval", "-e", "--print", "-p", "--watch", "--watch-preserve-output"]);
-  const execArgv = process.execArgv.filter(
-    (a, i, arr) => !SKIP_FLAGS.has(a) && !(i > 0 && SKIP_FLAGS.has(arr[i - 1]))
-  );
-  const child = spawn(process.execPath, [...execArgv, entry, "--hub"], {
-    detached: true,
-    stdio: ["ignore", out, out],
-    windowsHide: true,
-    env: { ...process.env }
-  });
-  child.unref();
-  closeSync(out);
-  log(`hub spawned (pid ${child.pid}), log: ${HUB_LOG}`);
-}
-async function waitForHub(timeoutMs = 15e3) {
-  const deadline = Date.now() + timeoutMs;
-  for (; ; ) {
-    const state = await probeHub();
-    if (state === "alive") return;
-    if (state !== "down") throw hubStateError(state);
-    if (Date.now() > deadline) throw new Error(`\u7B49\u5F85 hub \u5C31\u7EEA\u8D85\u65F6\uFF08${timeoutMs / 1e3}s\uFF09`);
-    await new Promise((r) => setTimeout(r, 200));
-  }
-}
-
-// src/process/stdio-proxy.ts
 async function startStdioProxy() {
   const mcpUrl = `${hubBaseUrl()}/mcp`;
   let upstream = null;
@@ -1777,14 +1906,40 @@ async function startStdioProxy() {
   }
   async function ensureUpstream() {
     if (upstream) return upstream;
-    const state = await probeHub();
-    if (state === "down") spawnHub();
-    if (state === "legacy" || state === "foreign") throw hubStateError(state);
-    await waitForHub();
+    const { state, health } = await probeHub();
+    if (state === "alive" && health?.version !== VERSION) {
+      log(`hub \u7248\u672C\u4E0D\u7B26\uFF08\u8FD0\u884C ${health?.version} / \u5F53\u524D ${VERSION}\uFF09\uFF0C\u81EA\u52A8\u91CD\u542F\u2026`);
+      if (!killHubByPid(health.pid)) await stopHub();
+      await waitForHubDown();
+      spawnHub();
+    } else if (state === "hung") {
+      log("hub \u65E0\u54CD\u5E94\uFF08\u50F5\u5C38\u8FDB\u7A0B\uFF09\uFF0C\u5F3A\u6740\u540E\u91CD\u5EFA\u2026");
+      if (!killHubByPidFile()) throw hubStateError("hung");
+      await waitForHubDown(1e4);
+      spawnHub();
+    } else if (state === "down") {
+      spawnHub();
+    } else if (state === "foreign") {
+      throw hubStateError(state);
+    }
+    await waitForHub(3e4);
     upstream = await connectUpstream();
     log(`proxy connected to ${mcpUrl}`);
     return upstream;
   }
+  let rebuilding = null;
+  function rebuildUpstream() {
+    rebuilding ??= (async () => {
+      const stale = upstream;
+      upstream = null;
+      if (stale) await stale.close().catch(() => {
+      });
+      return ensureUpstream();
+    })().finally(() => {
+      rebuilding = null;
+    });
+    return rebuilding;
+  }
   async function callWithRecovery(fn) {
     const client = await ensureUpstream();
     try {
@@ -1796,8 +1951,7 @@ async function startStdioProxy() {
       );
       if (alive) throw err;
       log("hub \u4F1A\u8BDD\u5931\u8054\uFF0C\u91CD\u5EFA\u540E\u91CD\u8BD5\u2026");
-      upstream = null;
-      const rebuilt = await ensureUpstream();
+      const rebuilt = await rebuildUpstream();
       return await fn(rebuilt);
     }
   }
@@ -1823,6 +1977,14 @@ async function main() {
     await runHub();
     return;
   }
+  if (process.argv.includes("--stop")) {
+    await stopHub();
+    return;
+  }
+  if (process.argv.includes("--version") || process.argv.includes("-v")) {
+    log(VERSION);
+    return;
+  }
   await startStdioProxy();
 }