@xiaobuyu/nodesign 0.0.1 → 0.0.3

package/server/engine/mcp/tools/get-pending-changes.js

@@ -1,205 +1,205 @@
-/**
- * mcp/tools/get-pending-changes.js — get_pending_changes MCP tool
- *
- * 用户在 canvas 上的"直接编辑（双击文本改字）"和"评论"会被前端 push 到
- * workspace/pending-changes.json。下次用户发 chat 消息时，turn.js 在
- * composeUserMessage 里 prepend 一个 system 提示告诉 agent "有 N 处变更，
- * 可调本工具查看详情"。agent 决定要不要拉详情。
- *
- * pending-changes.json schema：
- *   {
- *     items: [{
- *       id: string,
- *       kind: 'edit' | 'comment'
- *           | 'pending-move' | 'pending-style' | 'pending-duplicate' | 'pending-delete'
- *           | 'applied-move' | 'applied-style' | 'applied-duplicate',
- *       anchor: { dataId, path, textHint, bbox },
- *       aiContext: { tag, role?, pageInfo?, outerHtml?, computed?, siblings?,
- *                    targetContainerTag?, alignmentHints? },
- *       diff?: { oldText, newText },                          // edit 时有
- *       text?: string,                                        // comment 时有
- *       move?: { container: anchor, before: anchor|null },    // pending-move / -duplicate 时有
- *       styleDelta?: { left?, top?, marginLeft?, ... },       // pending-style 时有
- *       reactMount?: boolean,                                  // 涉及 React mount 区→改 JSX 源码
- *       ts: ISO,
- *     }]
- *   }
- *
- * 2026-05-12 新增 4 个 pending-* kind（画布拖移工具产物）：
- *   - pending-move      用户拖动元素跨/内容器；按 move.container + move.before 改 DOM 树位置
- *   - pending-duplicate 用户 alt-drag 复制；先 clone source 再插入 target
- *   - pending-style     用户 nudge / 调对齐；按 styleDelta 改 inline style 或 class
- *   - pending-delete    用户按 Del 删元素；按 anchor 删 source 节点
- *
- *  reactMount=true 的 item 走 `<script id="__nd-app">` 里的 JSX 改动（不是改 HTML 段）。
- *
- * 2026-07-29 新增 applied-* kind（站点窗拖拽直接落盘）：用户在站点页拖完，
- * 前端已把整页序列化写回文件 —— 这些是 FYI 记录（applied:true），**不要再应用一遍**，
- * 只用来理解用户动了什么；有 path 字段指明改的是哪份文件。
- *
- * 拉完后建议调 mcp__nodesign__clear_pending_changes 清 buffer，避免重复处理。
- */
-
-import path from 'node:path';
-import fs from 'node:fs/promises';
-import { tool } from '@anthropic-ai/claude-agent-sdk';
-import { z } from 'zod';
-
-/** 一次调用最多附几张圈选截图（更早的留路径让 agent 按需自己读） */
-const MAX_REGION_SHOTS = 3;
-
-/**
- * @param {object} deps
- * @param {string} deps.workspaceRoot
- * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
- */
-export function makeGetPendingChangesTool({ workspaceRoot, ctx: _ctx }) {
-  return tool(
-    'get_pending_changes',
-    `Read the user's pending changes buffer — a list of direct edits, inline
-comments, and drag-tool moves the user made on the canvas in between chat
-turns.
-
-When to use:
-- You see a <system>用户在过去时段做了 N 处变更...</system> hint at the top
-  of the user's message → call this tool to read the actual changes.
-- The user references "the change I just made" / "the edit I did" / "the move
-  I just did" → check the buffer first.
-
-Each item has:
-- kind: one of
-    'edit'             (user changed text by double-clicking in the canvas —
-                        ALREADY saved to the file; informational)
-    'comment'          (user wrote a comment for an element)
-    'pending-move'     (user dragged an element to a new container/position)
-    'pending-duplicate'(user alt-dragged to copy an element to a new spot)
-    'pending-style'    (user nudged / adjusted alignment → inline style delta)
-    'pending-delete'   (user deleted an element)
-    'applied-move' / 'applied-style' / 'applied-duplicate'
-                       (user dragged inside a site page window — the frontend
-                        ALREADY serialized the page and wrote it to the file.
-                        Do NOT re-apply these; they are FYI so you know what
-                        the user changed. You may tidy the source afterwards
-                        — e.g. lift baked inline left/top into the stylesheet —
-                        but only if asked or clearly beneficial.)
-- path (optional): which file the change belongs to (workspace-relative, e.g. about.html or 稿件/about.html).
-  Absent = the current session's canvas.html.
-- anchor: stable element reference (dataId / path / textHint / bbox)
-- aiContext: element role, page info, outerHTML, computed styles, siblings,
-             plus targetContainerTag / alignmentHints for moves
-- diff (edit): { oldText, newText }
-- becameEmpty (edit): true means the user CLEARED that text. The element is still
-  in the source and still takes up vertical space — usually you should delete the
-  whole element, not just leave it empty. Ask if you are unsure.
-- text (comment): the comment body
-- linkedToEditId (comment, optional): when present, this comment is a follow-up
-  instruction tied to another pending edit (e.g. "for that drag I just did, keep
-  the neighbor element fixed"). Always read the linked edit and treat them as
-  one combined operation; both get cleared together.
-- move (pending-move / pending-duplicate): { container: anchor, before: anchor|null }
-- styleDelta (pending-style): { left?, top?, marginLeft?, ... }
-- reactMount: when true, the change touches a React mount subtree → modify
-              the JSX inside <script id="__nd-app"> rather than the static HTML
-
-'region-comment' items are different in shape — the user lassoed an AREA of
-the preview rather than clicking one element:
-- region: { x, y, w, h } in page CSS px, and viewport: the size they saw it at
-- elements: what sits inside that box, innermost-first, each with anchor / tag /
-  a text excerpt / its own rect / coverage (how much of it the box covers).
-  Containers much larger than the box are deliberately excluded — the user was
-  pointing at what's inside, not at the wrapper.
-- container: the innermost element that fully encloses the box — i.e. WHERE on
-  the page this is. The elements list alone can't tell you header from footer.
-- text: what they said about it (may be empty — the box itself is the message)
-- shot: a screenshot of that area (plus a little margin), attached to this
-  tool result as an image right after the JSON. Look at it: it is the ground
-  truth of what the user was looking at, and the elements list is only an
-  index into it.
-- docxPage (present when path is a .docx): the user lassoed on a rendered page
-  image of a word document — docxPage is the 1-based page number, region is in
-  page-image pixels, and there are NO elements/container (a page image has no
-  DOM). The shot is cropped from the same LibreOffice page render the user was
-  looking at. To act on it, edit the token JSON source and rebuild with
-  build_docx — never edit the .docx itself.
-
-After processing, call mcp__nodesign__clear_pending_changes to clear the
-buffer so subsequent turns don't see the same changes again.`,
-    {
-      // No params; reading is unconditional.
-      _placeholder: z.string().optional().describe('Unused; reserved for future filters'),
-    },
-    async () => {
-      try {
-        if (!workspaceRoot) {
-          return {
-            content: [{ type: 'text', text: 'No workspace bound; cannot read pending changes.' }],
-            isError: true,
-          };
-        }
-
-        const bufPath = path.join(workspaceRoot, 'pending-changes.json');
-        let buf = { items: [] };
-        try {
-          const raw = await fs.readFile(bufPath, 'utf8');
-          const parsed = JSON.parse(raw);
-          if (parsed && Array.isArray(parsed.items)) buf = parsed;
-        } catch (err) {
-          if (err.code !== 'ENOENT') throw err;
-          // file doesn't exist = empty buffer
-        }
-
-        const items = buf.items;
-        if (items.length === 0) {
-          return {
-            content: [{
-              type: 'text',
-              text: 'No pending changes. The user has not made any direct edits or comments since the last clear.',
-            }],
-          };
-        }
-
-        const content = [{
-          type: 'text',
-          text: `Pending changes (${items.length} item${items.length === 1 ? '' : 's'}):\n\n`
-            + JSON.stringify(items, null, 2),
-        }];
-
-        // 圈选的截图直接挂在结果里 —— 那张图就是用户当时看着的画面，让 agent
-        // 再去 Read 一次纯属多一跳，而且它多半不会主动去读。
-        // 只带最近 MAX_REGION_SHOTS 张：一次拉出十张图，token 全烧在这上面。
-        const shots = items.filter(it => it.kind === 'region-comment' && it.shot);
-        const attach = shots.slice(-MAX_REGION_SHOTS);
-        for (const it of attach) {
-          try {
-            const buf = await fs.readFile(path.join(workspaceRoot, it.shot));
-            content.push({ type: 'text', text: `↓ 圈选 ${it.id}（${it.path}）用户框住的那一块：`
-              + (it.shotNote ? `\n${it.shotNote}（所以这张图不等于用户当时看到的画面）` : '') });
-            content.push({ type: 'image', data: buf.toString('base64'), mimeType: 'image/webp' });
-          } catch (err) {
-            content.push({
-              type: 'text',
-              text: `圈选 ${it.id} 的截图读不到（${err?.code || err?.message}）—— 按 elements 清单和 region 坐标处理。`,
-            });
-          }
-        }
-        if (shots.length > attach.length) {
-          content.push({
-            type: 'text',
-            text: `另有 ${shots.length - attach.length} 张更早的圈选截图没有附上（一次最多 ${MAX_REGION_SHOTS} 张）。`
-              + `需要的话按 item 里的 shot 路径自己 Read。`,
-          });
-        }
-
-        return { content };
-      } catch (err) {
-        return {
-          content: [{
-            type: 'text',
-            text: `get_pending_changes failed: ${err?.message || String(err)}`,
-          }],
-          isError: true,
-        };
-      }
-    },
-  );
-}
+/**
+ * mcp/tools/get-pending-changes.js — get_pending_changes MCP tool
+ *
+ * 用户在 canvas 上的"直接编辑（双击文本改字）"和"评论"会被前端 push 到
+ * workspace/pending-changes.json。下次用户发 chat 消息时，turn.js 在
+ * composeUserMessage 里 prepend 一个 system 提示告诉 agent "有 N 处变更，
+ * 可调本工具查看详情"。agent 决定要不要拉详情。
+ *
+ * pending-changes.json schema：
+ *   {
+ *     items: [{
+ *       id: string,
+ *       kind: 'edit' | 'comment'
+ *           | 'pending-move' | 'pending-style' | 'pending-duplicate' | 'pending-delete'
+ *           | 'applied-move' | 'applied-style' | 'applied-duplicate',
+ *       anchor: { dataId, path, textHint, bbox },
+ *       aiContext: { tag, role?, pageInfo?, outerHtml?, computed?, siblings?,
+ *                    targetContainerTag?, alignmentHints? },
+ *       diff?: { oldText, newText },                          // edit 时有
+ *       text?: string,                                        // comment 时有
+ *       move?: { container: anchor, before: anchor|null },    // pending-move / -duplicate 时有
+ *       styleDelta?: { left?, top?, marginLeft?, ... },       // pending-style 时有
+ *       reactMount?: boolean,                                  // 涉及 React mount 区→改 JSX 源码
+ *       ts: ISO,
+ *     }]
+ *   }
+ *
+ * 2026-05-12 新增 4 个 pending-* kind（画布拖移工具产物）：
+ *   - pending-move      用户拖动元素跨/内容器；按 move.container + move.before 改 DOM 树位置
+ *   - pending-duplicate 用户 alt-drag 复制；先 clone source 再插入 target
+ *   - pending-style     用户 nudge / 调对齐；按 styleDelta 改 inline style 或 class
+ *   - pending-delete    用户按 Del 删元素；按 anchor 删 source 节点
+ *
+ *  reactMount=true 的 item 走 `<script id="__nd-app">` 里的 JSX 改动（不是改 HTML 段）。
+ *
+ * 2026-07-29 新增 applied-* kind（站点窗拖拽直接落盘）：用户在站点页拖完，
+ * 前端已把整页序列化写回文件 —— 这些是 FYI 记录（applied:true），**不要再应用一遍**，
+ * 只用来理解用户动了什么；有 path 字段指明改的是哪份文件。
+ *
+ * 拉完后建议调 mcp__nodesign__clear_pending_changes 清 buffer，避免重复处理。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+
+/** 一次调用最多附几张圈选截图（更早的留路径让 agent 按需自己读） */
+const MAX_REGION_SHOTS = 3;
+
+/**
+ * @param {object} deps
+ * @param {string} deps.workspaceRoot
+ * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
+ */
+export function makeGetPendingChangesTool({ workspaceRoot, ctx: _ctx }) {
+  return tool(
+    'get_pending_changes',
+    `Read the user's pending changes buffer — a list of direct edits, inline
+comments, and drag-tool moves the user made on the canvas in between chat
+turns.
+
+When to use:
+- You see a <system>用户在过去时段做了 N 处变更...</system> hint at the top
+  of the user's message → call this tool to read the actual changes.
+- The user references "the change I just made" / "the edit I did" / "the move
+  I just did" → check the buffer first.
+
+Each item has:
+- kind: one of
+    'edit'             (user changed text by double-clicking in the canvas —
+                        ALREADY saved to the file; informational)
+    'comment'          (user wrote a comment for an element)
+    'pending-move'     (user dragged an element to a new container/position)
+    'pending-duplicate'(user alt-dragged to copy an element to a new spot)
+    'pending-style'    (user nudged / adjusted alignment → inline style delta)
+    'pending-delete'   (user deleted an element)
+    'applied-move' / 'applied-style' / 'applied-duplicate'
+                       (user dragged inside a site page window — the frontend
+                        ALREADY serialized the page and wrote it to the file.
+                        Do NOT re-apply these; they are FYI so you know what
+                        the user changed. You may tidy the source afterwards
+                        — e.g. lift baked inline left/top into the stylesheet —
+                        but only if asked or clearly beneficial.)
+- path (optional): which file the change belongs to (workspace-relative, e.g. about.html or 稿件/about.html).
+  Absent = the current session's canvas.html.
+- anchor: stable element reference (dataId / path / textHint / bbox)
+- aiContext: element role, page info, outerHTML, computed styles, siblings,
+             plus targetContainerTag / alignmentHints for moves
+- diff (edit): { oldText, newText }
+- becameEmpty (edit): true means the user CLEARED that text. The element is still
+  in the source and still takes up vertical space — usually you should delete the
+  whole element, not just leave it empty. Ask if you are unsure.
+- text (comment): the comment body
+- linkedToEditId (comment, optional): when present, this comment is a follow-up
+  instruction tied to another pending edit (e.g. "for that drag I just did, keep
+  the neighbor element fixed"). Always read the linked edit and treat them as
+  one combined operation; both get cleared together.
+- move (pending-move / pending-duplicate): { container: anchor, before: anchor|null }
+- styleDelta (pending-style): { left?, top?, marginLeft?, ... }
+- reactMount: when true, the change touches a React mount subtree → modify
+              the JSX inside <script id="__nd-app"> rather than the static HTML
+
+'region-comment' items are different in shape — the user lassoed an AREA of
+the preview rather than clicking one element:
+- region: { x, y, w, h } in page CSS px, and viewport: the size they saw it at
+- elements: what sits inside that box, innermost-first, each with anchor / tag /
+  a text excerpt / its own rect / coverage (how much of it the box covers).
+  Containers much larger than the box are deliberately excluded — the user was
+  pointing at what's inside, not at the wrapper.
+- container: the innermost element that fully encloses the box — i.e. WHERE on
+  the page this is. The elements list alone can't tell you header from footer.
+- text: what they said about it (may be empty — the box itself is the message)
+- shot: a screenshot of that area (plus a little margin), attached to this
+  tool result as an image right after the JSON. Look at it: it is the ground
+  truth of what the user was looking at, and the elements list is only an
+  index into it.
+- docxPage (present when path is a .docx): the user lassoed on a rendered page
+  image of a word document — docxPage is the 1-based page number, region is in
+  page-image pixels, and there are NO elements/container (a page image has no
+  DOM). The shot is cropped from the same LibreOffice page render the user was
+  looking at. To act on it, edit the token JSON source and rebuild with
+  build_docx — never edit the .docx itself.
+
+After processing, call mcp__nodesign__clear_pending_changes to clear the
+buffer so subsequent turns don't see the same changes again.`,
+    {
+      // No params; reading is unconditional.
+      _placeholder: z.string().optional().describe('Unused; reserved for future filters'),
+    },
+    async () => {
+      try {
+        if (!workspaceRoot) {
+          return {
+            content: [{ type: 'text', text: 'No workspace bound; cannot read pending changes.' }],
+            isError: true,
+          };
+        }
+
+        const bufPath = path.join(workspaceRoot, 'pending-changes.json');
+        let buf = { items: [] };
+        try {
+          const raw = await fs.readFile(bufPath, 'utf8');
+          const parsed = JSON.parse(raw);
+          if (parsed && Array.isArray(parsed.items)) buf = parsed;
+        } catch (err) {
+          if (err.code !== 'ENOENT') throw err;
+          // file doesn't exist = empty buffer
+        }
+
+        const items = buf.items;
+        if (items.length === 0) {
+          return {
+            content: [{
+              type: 'text',
+              text: 'No pending changes. The user has not made any direct edits or comments since the last clear.',
+            }],
+          };
+        }
+
+        const content = [{
+          type: 'text',
+          text: `Pending changes (${items.length} item${items.length === 1 ? '' : 's'}):\n\n`
+            + JSON.stringify(items, null, 2),
+        }];
+
+        // 圈选的截图直接挂在结果里 —— 那张图就是用户当时看着的画面，让 agent
+        // 再去 Read 一次纯属多一跳，而且它多半不会主动去读。
+        // 只带最近 MAX_REGION_SHOTS 张：一次拉出十张图，token 全烧在这上面。
+        const shots = items.filter(it => it.kind === 'region-comment' && it.shot);
+        const attach = shots.slice(-MAX_REGION_SHOTS);
+        for (const it of attach) {
+          try {
+            const buf = await fs.readFile(path.join(workspaceRoot, it.shot));
+            content.push({ type: 'text', text: `↓ 圈选 ${it.id}（${it.path}）用户框住的那一块：`
+              + (it.shotNote ? `\n${it.shotNote}（所以这张图不等于用户当时看到的画面）` : '') });
+            content.push({ type: 'image', data: buf.toString('base64'), mimeType: 'image/webp' });
+          } catch (err) {
+            content.push({
+              type: 'text',
+              text: `圈选 ${it.id} 的截图读不到（${err?.code || err?.message}）—— 按 elements 清单和 region 坐标处理。`,
+            });
+          }
+        }
+        if (shots.length > attach.length) {
+          content.push({
+            type: 'text',
+            text: `另有 ${shots.length - attach.length} 张更早的圈选截图没有附上（一次最多 ${MAX_REGION_SHOTS} 张）。`
+              + `需要的话按 item 里的 shot 路径自己 Read。`,
+          });
+        }
+
+        return { content };
+      } catch (err) {
+        return {
+          content: [{
+            type: 'text',
+            text: `get_pending_changes failed: ${err?.message || String(err)}`,
+          }],
+          isError: true,
+        };
+      }
+    },
+  );
+}

package/server/engine/mcp/tools/h3box-ssh.js

@@ -1,84 +1,84 @@
-/**
- * mcp/tools/h3box-ssh.js — GPU 盒子 SSH 公用件（roll_film / paint_still 共用）
- *
- * 盒子 = featurize 按时租的 5090（.env NODESIGN_H3BOX_SSH/PORT/PASS，每次租机
- * 都换）。密码走 sshpass -e（SSHPASS 环境变量），没配密码就当 key 认证。
- */
-
-import { spawn } from 'node:child_process';
-import os from 'node:os';
-
-/**
- * 盒子总开关（2026-08-17）。
- *
- * 盒子是站主手动开关的物理机，但 SSH 地址常年配在 .env 里 —— 所以「机器关着」
- * 跟「没配过」在代码里长得完全不一样：后者 boxConfig() 返回 null 能立刻兜底，
- * 前者会一路 SSH 到超时才失败（paint_still 单张 240s、krea2 400s，整批还要乘
- * 系数；roll_film 每镜 900s），agent 和用户一起干等几分钟，还看不出为什么。
- *
- * 这个开关让工具在**调用的第一行**就诚实说不可用。开机后把 .env 里那行改回 on
- * （或整行删掉，默认就是 on）。它管的是整台机器：paint_still 的五个模型和
- * roll_film 的 box 后端都住在上面。
- */
-export const localBoxEnabled = () => (process.env.NODESIGN_LOCAL_BOX || 'on').toLowerCase() !== 'off';
-
-/** 关机时给 agent 的统一说辞：说清原因、给替代路径、明确别重试 */
-export const BOX_OFF_MSG = '本地 GPU 盒子当前关着（站主手动开关机）。这台机器上的东西'
-  + '现在都用不了：paint_still 的 noobai / noobai-eps / pony / anima / krea2 五个模型，'
-  + '以及 roll_film 的本地后端。转告用户，生图改走 generate_image；要用本地产线得先开机。'
-  + '别重试，重试也是同样的结果。';
-
-export function boxConfig() {
-  const target = process.env.NODESIGN_H3BOX_SSH || '';
-  if (!target) return null;
-  return {
-    target,
-    port: process.env.NODESIGN_H3BOX_PORT || '22',
-    pass: process.env.NODESIGN_H3BOX_PASS || '',
-  };
-}
-
-/** POSIX 单引号转义（远端 zsh/bash 规则相同） */
-export const shq = (s) => `'${String(s).replace(/'/g, "'\\''")}'`;
-
-/**
- * 跑一条 ssh/scp。永不 throw，resolve {code, out, err}；code=-1 表示本地 spawn 失败。
- * @param {{target:string,port:string,pass:string}} box
- * @param {'ssh'|'scp'} bin
- */
-export function runBox(box, bin, args, { timeoutMs = 240_000, signal } = {}) {
-  return new Promise((resolve) => {
-    const env = { ...process.env };
-    let cmd = bin; let argv = args;
-    if (box.pass) {
-      env.SSHPASS = box.pass;
-      cmd = 'sshpass'; argv = ['-e', bin, ...args];
-    }
-    const child = spawn(cmd, argv, { stdio: ['ignore', 'pipe', 'pipe'], env });
-    let out = ''; let err = '';
-    child.stdout.on('data', (d) => { out = (out + d).slice(-8000); });
-    child.stderr.on('data', (d) => { err = (err + d).slice(-2000); });
-    const timer = setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* */ } }, timeoutMs);
-    const onAbort = () => { try { child.kill('SIGKILL'); } catch { /* */ } };
-    signal?.addEventListener?.('abort', onAbort, { once: true });
-    child.on('close', (code) => {
-      clearTimeout(timer);
-      signal?.removeEventListener?.('abort', onAbort);
-      resolve({ code, out, err });
-    });
-    child.on('error', (e) => { clearTimeout(timer); resolve({ code: -1, out, err: String(e.message) }); });
-  });
-}
-
-// 连接复用：首连付一次完整握手（跨境实测 ~4s），之后 10 分钟内的 ssh/scp 走同一条
-// 隧道，每次 ~0.1s。socket 名带主机+端口，换租新盒（端口必变）不会撞旧 socket；
-// master 空闲 10 分钟自灭，盒子重启后 auto 会自动弃掉死 socket 重连。
-const CTRL = [
-  '-o', 'ControlMaster=auto',
-  '-o', `ControlPath=${os.tmpdir()}/h3box-cm-%r@%h-%p`,
-  '-o', 'ControlPersist=600',
-];
-
-/** ssh 公共参数（-p 端口）；scp 用 scpArgs（-P 端口） */
-export const sshArgs = (box) => [...CTRL, '-o', 'StrictHostKeyChecking=no', '-o', 'ConnectTimeout=10', '-p', box.port, box.target];
-export const scpArgs = (box) => [...CTRL, '-o', 'StrictHostKeyChecking=no', '-o', 'ConnectTimeout=10', '-P', box.port];
+/**
+ * mcp/tools/h3box-ssh.js — GPU 盒子 SSH 公用件（roll_film / paint_still 共用）
+ *
+ * 盒子 = featurize 按时租的 5090（.env NODESIGN_H3BOX_SSH/PORT/PASS，每次租机
+ * 都换）。密码走 sshpass -e（SSHPASS 环境变量），没配密码就当 key 认证。
+ */
+
+import { spawn } from 'node:child_process';
+import os from 'node:os';
+
+/**
+ * 盒子总开关（2026-08-17）。
+ *
+ * 盒子是站主手动开关的物理机，但 SSH 地址常年配在 .env 里 —— 所以「机器关着」
+ * 跟「没配过」在代码里长得完全不一样：后者 boxConfig() 返回 null 能立刻兜底，
+ * 前者会一路 SSH 到超时才失败（paint_still 单张 240s、krea2 400s，整批还要乘
+ * 系数；roll_film 每镜 900s），agent 和用户一起干等几分钟，还看不出为什么。
+ *
+ * 这个开关让工具在**调用的第一行**就诚实说不可用。开机后把 .env 里那行改回 on
+ * （或整行删掉，默认就是 on）。它管的是整台机器：paint_still 的五个模型和
+ * roll_film 的 box 后端都住在上面。
+ */
+export const localBoxEnabled = () => (process.env.NODESIGN_LOCAL_BOX || 'on').toLowerCase() !== 'off';
+
+/** 关机时给 agent 的统一说辞：说清原因、给替代路径、明确别重试 */
+export const BOX_OFF_MSG = '本地 GPU 盒子当前关着（站主手动开关机）。这台机器上的东西'
+  + '现在都用不了：paint_still 的 noobai / noobai-eps / pony / anima / krea2 五个模型，'
+  + '以及 roll_film 的本地后端。转告用户，生图改走 generate_image；要用本地产线得先开机。'
+  + '别重试，重试也是同样的结果。';
+
+export function boxConfig() {
+  const target = process.env.NODESIGN_H3BOX_SSH || '';
+  if (!target) return null;
+  return {
+    target,
+    port: process.env.NODESIGN_H3BOX_PORT || '22',
+    pass: process.env.NODESIGN_H3BOX_PASS || '',
+  };
+}
+
+/** POSIX 单引号转义（远端 zsh/bash 规则相同） */
+export const shq = (s) => `'${String(s).replace(/'/g, "'\\''")}'`;
+
+/**
+ * 跑一条 ssh/scp。永不 throw，resolve {code, out, err}；code=-1 表示本地 spawn 失败。
+ * @param {{target:string,port:string,pass:string}} box
+ * @param {'ssh'|'scp'} bin
+ */
+export function runBox(box, bin, args, { timeoutMs = 240_000, signal } = {}) {
+  return new Promise((resolve) => {
+    const env = { ...process.env };
+    let cmd = bin; let argv = args;
+    if (box.pass) {
+      env.SSHPASS = box.pass;
+      cmd = 'sshpass'; argv = ['-e', bin, ...args];
+    }
+    const child = spawn(cmd, argv, { stdio: ['ignore', 'pipe', 'pipe'], env });
+    let out = ''; let err = '';
+    child.stdout.on('data', (d) => { out = (out + d).slice(-8000); });
+    child.stderr.on('data', (d) => { err = (err + d).slice(-2000); });
+    const timer = setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* */ } }, timeoutMs);
+    const onAbort = () => { try { child.kill('SIGKILL'); } catch { /* */ } };
+    signal?.addEventListener?.('abort', onAbort, { once: true });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      signal?.removeEventListener?.('abort', onAbort);
+      resolve({ code, out, err });
+    });
+    child.on('error', (e) => { clearTimeout(timer); resolve({ code: -1, out, err: String(e.message) }); });
+  });
+}
+
+// 连接复用：首连付一次完整握手（跨境实测 ~4s），之后 10 分钟内的 ssh/scp 走同一条
+// 隧道，每次 ~0.1s。socket 名带主机+端口，换租新盒（端口必变）不会撞旧 socket；
+// master 空闲 10 分钟自灭，盒子重启后 auto 会自动弃掉死 socket 重连。
+const CTRL = [
+  '-o', 'ControlMaster=auto',
+  '-o', `ControlPath=${os.tmpdir()}/h3box-cm-%r@%h-%p`,
+  '-o', 'ControlPersist=600',
+];
+
+/** ssh 公共参数（-p 端口）；scp 用 scpArgs（-P 端口） */
+export const sshArgs = (box) => [...CTRL, '-o', 'StrictHostKeyChecking=no', '-o', 'ConnectTimeout=10', '-p', box.port, box.target];
+export const scpArgs = (box) => [...CTRL, '-o', 'StrictHostKeyChecking=no', '-o', 'ConnectTimeout=10', '-P', box.port];