@xiaobuyu/nodesign 0.0.1

package/server/engine/mcp/tools/roll-film.js

@@ -0,0 +1,266 @@
+/**
+ * mcp/tools/roll-film.js — roll_film MCP tool（2026-08-08；批量制同晚补上）
+ *
+ * 自部署 MiniMax-H3 视频产线。一次调用 = 一批镜头（1-16 条），全批共用一个
+ * seed（成片纪律）；盒上串行渲，每出一镜当场落盘上墙。后端两档：
+ *   box（默认）  站主 5090 盒子（h3box.py video over SSH），模型常驻零冷启动。
+ *   modal        Modal H100+sage 备用档，NODESIGN_FILM_BACKEND=modal 显式才走。
+ * 配方恒定：Turbo 8 步 / 1344×768 / 单镜 ≤12.25s。批准制：admin+获批账号。
+ * 只回文本路径，不回 image block；agent 可以自己抽帧看（2026-08-18 解禁），
+ * 但"这条好不好"归用户判。
+ */
+
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { Events } from '../../agent/events.js';
+import { getProject } from '../../../projects/store.js';
+import { getUserById } from '../../../auth/users-store.js';
+import { can, localGenApproved, DENIAL } from '../../../auth/tier.js';
+import { boxConfig, runBox, sshArgs, scpArgs, localBoxEnabled, BOX_OFF_MSG } from './h3box-ssh.js';
+
+const H3_REPO = process.env.NODESIGN_H3_REPO || '/home/wangang-dev/projects/minimax-h3-modal';
+const MODAL_BIN = process.env.NODESIGN_MODAL_BIN || path.join(os.homedir(), '.local/bin/modal');
+const PER_SHOT_TIMEOUT_MS = Number(process.env.NODESIGN_FILM_TIMEOUT_MS) || 900_000;
+
+function frameCount(durationS) {
+  const f = Math.max(5, Math.round(durationS * 24));
+  return f + ((5 - (f % 17)) % 17 + 17) % 17;
+}
+
+function estCostUsd(d, backend) {
+  const pts = backend === 'modal'
+    ? [[5.17, 0.10], [8, 0.16], [10, 0.21], [12.25, 0.28]]
+    : [[5.17, 0.015], [8, 0.02], [12.25, 0.03]];
+  if (d <= pts[0][0]) return pts[0][1];
+  for (let i = 1; i < pts.length; i++) {
+    if (d <= pts[i][0]) {
+      const [x0, y0] = pts[i - 1]; const [x1, y1] = pts[i];
+      return Math.round((y0 + (d - x0) * (y1 - y0) / (x1 - x0)) * 1000) / 1000;
+    }
+  }
+  return pts[pts.length - 1][1];
+}
+
+function runModal(args, { cwd, signal, timeoutMs }) {
+  return new Promise((resolve) => {
+    const child = spawn(MODAL_BIN, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
+    let out = ''; let err = '';
+    child.stdout.on('data', (d) => { out = (out + d).slice(-8000); });
+    child.stderr.on('data', (d) => { err = (err + d).slice(-4000); });
+    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) }); });
+  });
+}
+
+/** 单镜落盘 + sidecar + 上墙事件；返回 caption 行 */
+async function landShot({ localMp4, shot, seed, backend, wallS, outDir, ctx, sessionId }) {
+  const fileName = `${shot.name}-${shot.jobId.slice(5)}.mp4`;
+  const absOut = path.join(outDir, fileName);
+  await fs.rename(localMp4, absOut).catch(async () => {
+    await fs.copyFile(localMp4, absOut); await fs.unlink(localMp4).catch(() => { /* */ });
+  });
+  const sizeBytes = (await fs.stat(absOut)).size;
+  const cost = estCostUsd(shot.duration, backend);
+  try {
+    const metaDir = path.join(outDir, '.meta');
+    await fs.mkdir(metaDir, { recursive: true });
+    await fs.writeFile(path.join(metaDir, `${path.parse(fileName).name}.json`), JSON.stringify({
+      prompt: shot.prompt, kind: 'film', durationS: shot.duration, frames: frameCount(shot.duration),
+      seed, model: backend === 'modal' ? 'minimax-h3-turbo8-h100-sage' : 'minimax-h3-turbo8-5090-sage2',
+      estCostUsd: cost, wallClockS: wallS,
+      firstFrame: shot.first_frame || null, lastFrame: shot.last_frame || null,
+      sessionId: ctx?.sessionId || sessionId || null, runId: ctx?.runId || null,
+      ts: new Date().toISOString(),
+    }, null, 2));
+  } catch (e) { console.warn(`[roll-film] meta sidecar failed: ${e.message}`); }
+  // MCP 工具写盘不走自动 file_changed —— 手动发，出一镜上墙一镜
+  // 工作区相对路径（fileChanged 正字法，2026-08-14 普查改；绝对路径=前端寻址哑弹）
+  try { ctx?.emit?.(Events.fileChanged(path.posix.join('assets', 'generated', fileName), 'add')); } catch { /* */ }
+  return `[${shot.name}] assets/generated/${fileName} — ${shot.duration}s ${(sizeBytes / 1e6).toFixed(1)}MB ${Math.floor(wallS / 60)}m${wallS % 60}s ~$${cost}`;
+}
+
+export async function rollFilm(
+  { workspaceRoot, sharedRoot, projectId, sessionId, ctx },
+  { shots, seed },
+) {
+  const asText = (text, isError = false) =>
+    ({ content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) });
+  try {
+    const project = getProject(projectId);
+    if (!project) return asText('错误：项目不存在', true);
+    const owner = project.ownerId ? getUserById(project.ownerId) : null;
+    if (!owner) return asText('错误：找不到项目归属用户', true);
+    // 档位闸 + 逐人批准（auth/tier.js）：basic 档不开本地产线；pro 档还要被站主批过
+    if (!can(owner, 'localGen')) return asText(DENIAL.localGenTier, true);
+    if (!localGenApproved(owner)) return asText(DENIAL.localGenApproval, true);
+
+    // 全批先验完再花钱：帧域 + 关键帧存在性 + 名字唯一
+    const names = new Set();
+    for (const s of shots) {
+      const frames = frameCount(s.duration);
+      if (frames > 294) return asText(`[${s.name}] ${frames} 帧超产线安全域 294（12.25s），拆镜`, true);
+      if (names.has(s.name)) return asText(`镜名重复：${s.name}`, true);
+      names.add(s.name);
+      for (const slot of ['first_frame', 'last_frame']) {
+        if (!s[slot]) continue;
+        const abs = path.resolve(workspaceRoot || process.cwd(), s[slot]);
+        try {
+          if (!(await fs.stat(abs)).isFile()) throw new Error('x');
+        } catch { return asText(`[${s.name}] ${slot} 找不到：${s[slot]}`, true); }
+        s[`_abs_${slot}`] = abs;
+      }
+    }
+
+    const backend = (process.env.NODESIGN_FILM_BACKEND || 'box').toLowerCase();
+    // 只拦 box 后端：modal 是另一台机器，站主关本地盒子不影响它
+    if (backend === 'box' && !localBoxEnabled()) {
+      return asText(BOX_OFF_MSG, true);
+    }
+    const signal = ctx?.abortController?.signal;
+    const outDir = path.join(sharedRoot || workspaceRoot, 'assets', 'generated');
+    await fs.mkdir(outDir, { recursive: true });
+    const batch = Date.now().toString(36);
+    const lines = []; const failed = [];
+
+    let box = null;
+    if (backend !== 'modal') {
+      box = boxConfig();
+      if (!box) return asText('视频盒子未配置（站主没开机）。转告用户；备用 Modal 档要站主设 NODESIGN_FILM_BACKEND=modal。', true);
+      const mk = await runBox(box, 'ssh', [...sshArgs(box), 'mkdir -p nd_jobs'], { timeoutMs: 30_000, signal });
+      if (mk.code !== 0) return asText(`盒子连不上（没开机/地址过期）：\n${(mk.err || '').slice(-400)}\n转告用户。`, true);
+    }
+
+    // 逐镜串行：一镜完整走完（渲→取回→上墙）再下一镜，agent 中途被打断也保住已出的
+    for (let i = 0; i < shots.length; i++) {
+      const shot = shots[i];
+      shot.jobId = `film-${batch}s${i}`;
+      const job = { name: shot.jobId, prompt: shot.prompt, seed, duration: shot.duration, width: 1344, height: 768 };
+      if (shot.steps) job.steps = shot.steps;
+      const t0 = Date.now();
+      let localMp4 = null; let failMsg = null;
+
+      if (backend === 'modal') {
+        if (shot._abs_first_frame) job.first_frame = shot._abs_first_frame;
+        if (shot._abs_last_frame) job.last_frame = shot._abs_last_frame;
+        const jp = path.join(os.tmpdir(), `nd-${shot.jobId}.json`);
+        await fs.writeFile(jp, JSON.stringify([job]));
+        const r = await runModal(['run', 'h3_comfy.py', '--jobs-file', jp], { cwd: H3_REPO, signal, timeoutMs: PER_SHOT_TIMEOUT_MS });
+        fs.unlink(jp).catch(() => { /* */ });
+        if (r.code !== 0) failMsg = (r.err || r.out).slice(-600);
+        else {
+          const hits = (await fs.readdir(path.join(H3_REPO, 'outputs'))).filter((f) => f.startsWith(`${shot.jobId}_`) && f.endsWith('.mp4'));
+          if (hits.length) localMp4 = path.join(H3_REPO, 'outputs', hits[0]);
+          else failMsg = `无成片。输出尾：${r.out.slice(-400)}`;
+        }
+      } else {
+        for (const slot of ['first_frame', 'last_frame']) {
+          const abs = shot[`_abs_${slot}`];
+          if (!abs) continue;
+          const remote = `nd_jobs/${shot.jobId}-${slot}${path.extname(abs) || '.png'}`;
+          const up = await runBox(box, 'scp', [...scpArgs(box), abs, `${box.target}:${remote}`], { timeoutMs: 60_000, signal });
+          if (up.code !== 0) { failMsg = `关键帧上传失败：${up.err.slice(-300)}`; break; }
+          job[slot] = `~/${remote}`;
+        }
+        if (!failMsg) {
+          const jl = path.join(os.tmpdir(), `nd-${shot.jobId}.json`);
+          await fs.writeFile(jl, JSON.stringify([job]));
+          const upJ = await runBox(box, 'scp', [...scpArgs(box), jl, `${box.target}:nd_jobs/${shot.jobId}.json`], { timeoutMs: 30_000, signal });
+          fs.unlink(jl).catch(() => { /* */ });
+          if (upJ.code !== 0) failMsg = `任务上传失败：${upJ.err.slice(-300)}`;
+          else {
+            const gen = await runBox(box, 'ssh', [...sshArgs(box), `python3 ~/h3box.py video ~/nd_jobs/${shot.jobId}.json`], { timeoutMs: PER_SHOT_TIMEOUT_MS, signal });
+            if (gen.code !== 0 || !gen.out.includes('success')) failMsg = `渲染失败（exit ${gen.code}）：${(gen.err || gen.out).slice(-600)}`;
+            else {
+              const pd = await fs.mkdtemp(path.join(os.tmpdir(), 'nd-film-'));
+              const pull = await runBox(box, 'scp', [...scpArgs(box), `${box.target}:outputs/${shot.jobId}_*.mp4`, pd], { timeoutMs: 120_000, signal });
+              const got = pull.code === 0 ? (await fs.readdir(pd)).filter((f) => f.endsWith('.mp4')) : [];
+              if (got.length) localMp4 = path.join(pd, got[0]);
+              else failMsg = `成片取回失败：${pull.err.slice(-300)}`;
+            }
+          }
+        }
+      }
+
+      const wallS = Math.round((Date.now() - t0) / 1000);
+      if (localMp4) {
+        lines.push(await landShot({ localMp4, shot, seed, backend, wallS, outDir, ctx, sessionId }));
+      } else {
+        failed.push(`[${shot.name}] ${failMsg}`);
+        if (signal?.aborted) break;
+        break;   // 串行批中途失败即停：后镜大概率同因失败，别空烧
+      }
+    }
+
+    const head = `Batch done ${lines.length}/${shots.length} shots, seed=${seed}, via ${backend === 'modal' ? 'Modal H100+sage' : '5090 盒子 sage2'}`;
+    // 2026-08-18：解禁。mp4 塞不进视觉通道，要看就 ffmpeg 抽帧再看那几张图。
+    const tail = 'You may check these: pull two or three frames with ffmpeg and look at them '
+      + 'for technical breakage (colour cast, duplicated figures, broken limbs, mush, first '
+      + 'frame not matching the anchor) and re-roll those yourself; delete the temp frames after. '
+      + 'Do NOT judge whether a shot is good — hand the paths to the user for that.';
+    if (failed.length) {
+      return asText([head, ...lines, 'FAILED（批在此中断，未渲镜不再空烧）：', ...failed, tail].join('\n'), lines.length === 0);
+    }
+    return asText([head, ...lines, tail].join('\n'));
+  } catch (err) {
+    return asText(`roll_film 失败：${err.message}`, true);
+  }
+}
+
+/**
+ * @param {object} deps
+ */
+export function makeRollFilmTool(deps) {
+  return tool(
+    'roll_film',
+    ((localBoxEnabled() || (process.env.NODESIGN_FILM_BACKEND || 'box').toLowerCase() === 'modal')
+      ? ''
+      : '⛔ CURRENTLY UNAVAILABLE — the owner powers this GPU box on and off by hand, '
+        + 'and it is off right now. Do not call this tool; tell the user the local box is off.\n\n')
+    + `Generate video shots (picture + native audio) on the owner's self-hosted
+MiniMax-H3 lane (RTX 5090 box, SageAttention, Turbo 8-step, 24fps). One call =
+one batch of 1-16 shots rendered back-to-back; each finished shot lands on the
+canvas immediately. Max 12.25s per shot — longer stories are multiple shots.
+
+Call ONLY when the user explicitly asks for video, and align the shot list with
+the user before rolling a multi-shot batch. Roughly 3-5 minutes per shot,
+serial; tell the user the camera is rolling. Never auto-retry shots you already
+got back. Requires the GPU box online — if unreachable, relay that and stop.
+
+Prompts must follow the H3 three-field English format (cookbook arrives as a
+system reminder attached to your FIRST call — treat your first batch as the
+learning pass and refine from it). Keep character/style blocks verbatim
+identical across shots; the whole batch shares ONE seed automatically. Keyframe
+anchors (first_frame/last_frame) accept paths like "assets/generated/kf1.png"
+(make them with paint_still or generate_image, ideally 1344x768).
+
+Clips land at assets/generated/<name>-*.mp4. To check one, pull a couple of
+frames with ffmpeg and look at those — catch colour cast, duplicated figures,
+broken limbs, mush, or a first frame that does not match its anchor, and re-roll
+those yourself (delete the temp frames after). Whether a shot is GOOD is the
+user's call, not yours: report paths
+and move on.`,
+    {
+      shots: z.array(z.object({
+        prompt: z.string().describe('H3 three-field English prompt'),
+        duration: z.number().min(5.2).max(12.25).default(8),
+        name: z.string().regex(/^[\w-]{1,40}$/).describe('shot slug, unique in batch'),
+        first_frame: z.string().optional(),
+        last_frame: z.string().optional(),
+        steps: z.number().int().min(4).max(8).optional().describe('default 8; 4 = fast draft'),
+      })).min(1).max(16).describe('shots rendered serially in one batch'),
+      seed: z.number().int().default(1101).describe('ONE seed shared by the whole batch (film discipline)'),
+    },
+    (args) => rollFilm(deps, args),
+  );
+}

package/server/engine/mcp/tools/screenshot-docx.js

@@ -0,0 +1,138 @@
+/**
+ * screenshot-docx.js — screenshot 工具的 docx 分支。
+ *
+ * 为什么单独一个模块：docx 跟 deck / site 走的是**两条完全不同的管线**
+ * （LibreOffice → PDF → PNG vs playwright），共享的只有「返回一张图 + 一句
+ * caption」这个出口形状。塞进 screenshot.js 会变成一个大 if 横在中间。
+ *
+ * agent 那边**动词不变**：还是 screenshot。形态注册表的 `renderable` 能力位
+ * 负责分流，工具签名和使用习惯零变化 —— 「做完看一眼」这条纪律是跨形态的，
+ * 不该因为产物换了种类就让 agent 重新学一个工具名。
+ *
+ * ⚠️ 这只眼睛有两处**已知失真**，caption 里必须说出来，不能让 agent 拿它当
+ * 终审（写进 SKILL 的同一套话）：
+ *   1. 中文字体是替身（服务器没有宋体/黑体/仿宋，用 Noto / LXGW 代显）——
+ *      断行一致但**行高不一致**（multiple 行距乘字体自带行高，替身≈1.24 vs
+ *      真雅黑≈1.32 / 苹方≈1.4），multiple 行距下页数不可照图判
+ *   2. **TOC 域**显示的是缓存占位文案，不是真目录（Word 打开更新域才生成）。
+ *      ⚠️ 别把这条写成「域都不更新」—— 实测 PAGE 域 LO 是**正常求值**的，
+ *      页脚页码看到几就是几。假警报会训练 agent 忽略警报。
+ */
+
+import fs from 'node:fs/promises';
+import { execFileSync } from 'node:child_process';
+import { renderDocx, cleanupRender } from '../../../lib/docx/render.js';
+import { normalizeShot } from './helpers/shot-pipeline.js';
+
+/** 一次最多回几页 —— 40 页文档全渲回来是上下文炸弹 */
+const MAX_PAGES = 6;
+/** 不指定范围时默认看几页 */
+const DEFAULT_PAGES = 2;
+
+const DPI = { normal: 100, high: 150 };
+
+/** PDF 总页数。拿不到就返回 null，不为了一个数字让整次截图失败 */
+function pdfPageCount(pdfPath) {
+  try {
+    const out = execFileSync('pdfinfo', [pdfPath], { encoding: 'utf8', timeout: 15000 });
+    const m = out.match(/^Pages:\s+(\d+)/m);
+    return m ? Number(m[1]) : null;
+  } catch { return null; }
+}
+
+/**
+ * 解析页码范围。`pages` 收 "3"、"2-5"、"all" 三种写法。
+ * @returns {{from:number, to:number, explicit:boolean}}
+ */
+export function parsePageRange(pages) {
+  if (!pages) return { from: 1, to: DEFAULT_PAGES, explicit: false };
+  const s = String(pages).trim();
+  if (/^all$/i.test(s)) return { from: 1, to: MAX_PAGES, explicit: true };
+  const range = s.match(/^(\d+)\s*-\s*(\d+)$/);
+  if (range) {
+    const from = Math.max(1, Number(range[1]));
+    return { from, to: Math.max(from, Math.min(Number(range[2]), from + MAX_PAGES - 1)), explicit: true };
+  }
+  const one = s.match(/^(\d+)$/);
+  if (one) { const n = Math.max(1, Number(one[1])); return { from: n, to: n, explicit: true }; }
+  return { from: 1, to: DEFAULT_PAGES, explicit: false };
+}
+
+/**
+ * @param {{absPath:string, relPath:string}} target  已解析的产物目标
+ * @param {{pages?:string, detail?:'normal'|'high'}} opts
+ * @returns {Promise<{content:Array, isError?:boolean}>}  MCP 工具返回体
+ */
+export async function screenshotDocx(target, opts = {}) {
+  try {
+    await fs.access(target.absPath);
+  } catch {
+    return {
+      content: [{ type: 'text', text: `${target.relPath} 还没构建出来。先写 token 源再 build，或者确认文件名。` }],
+      isError: true,
+    };
+  }
+
+  const { from, to, explicit } = parsePageRange(opts.pages);
+  const dpi = DPI[opts.detail === 'high' ? 'high' : 'normal'];
+
+  let res;
+  try {
+    // pdftoppm 的 -l 超过实际页数会自动截断，所以这里不用先问总页数
+    res = await renderDocx(target.absPath, { pngPages: [from, to], dpi });
+  } catch (err) {
+    return {
+      content: [{
+        type: 'text',
+        text: `渲染失败：${String(err.message || err).slice(0, 400)}\n`
+          + '这是渲染链路的问题不是文档的问题，别靠猜改文档 —— 先看 soffice 在不在、文件是不是完整的 docx。',
+      }],
+      isError: true,
+    };
+  }
+
+  try {
+    const total = pdfPageCount(res.pdf);
+    if (!res.pngs.length) {
+      return {
+        content: [{ type: 'text', text: `${target.relPath} 渲染出来是空的（共 ${total ?? '?'} 页，请求 ${from}-${to}）。` }],
+        isError: true,
+      };
+    }
+
+    const shown = `${from}${res.pngs.length > 1 ? `-${from + res.pngs.length - 1}` : ''}`;
+    const caption = [
+      `${target.relPath} · 第 ${shown} 页${total ? ` / 共 ${total} 页` : ''} · ${dpi}dpi · ${res.ms}ms`,
+    ];
+    // 没看完就说没看完 —— 静默只给前两页，agent 会以为自己看过全文
+    if (total && from + res.pngs.length - 1 < total) {
+      caption.push(`⚠️ 还有 ${total - (from + res.pngs.length - 1)} 页没看：pages:"3-6" 指定范围，一次最多 ${MAX_PAGES} 页。`);
+    }
+    if (!explicit && total && total > DEFAULT_PAGES) {
+      caption.push('（没传 pages 时默认只渲前两页）');
+    }
+    caption.push(
+      '已知失真：① 中文是**替身字体**（雅黑/等线→MiSans、仿宋→朱雀仿宋、宋体→Noto Serif、'
+      + '楷体→LXGW），字形跟用户 Word 里仍有差；CJK 全角等宽所以**断行位置**一致，但行高只有'
+      + '雅黑档对齐了（MiSans 1.326 ≈ 真雅黑 1.32）—— 宋体等其它档、以及 Mac 上替到苹方（≈1.4）'
+      + '的行高仍不同（2026-08-19 真 Word 实证：2 页简历在 Word 里变过 4 页）；'
+      + '② **TOC 域**这里显示的是占位文案不是真目录（Word 打开更新域才生成）——'
+      + '页码域是正常的，看到几就是几。'
+      + '版式、间距、缩进、层级可以照这张图判；字形观感、目录内容不能，'
+      + '**multiple 行距下的页数和分页位置也不能**（排满的页真 Word 会多出页；'
+      + '页数敏感的文档行距用 exact/atLeast 磅值，两边就一样高了）。',
+    );
+
+    // 跟全站眼睛同口径（08-21）：过 normalizeShot → 视觉档尺寸 + webp q82。视觉模型按像素
+    // 网格计 token，PNG 原图多出来的字节它看不见；公文页 PNG 260KB → webp 97KB，放大
+    // 对比字形无差。少的是传给上游的字节和 CLI 按字符估算的假仪表，真 token 账不变。
+    const images = await Promise.all(res.pngs.map(async (p) => {
+      const n = await normalizeShot(await fs.readFile(p));
+      return { type: 'image', data: n.data, mimeType: n.mimeType };
+    }));
+
+    return { content: [{ type: 'text', text: caption.join('\n') }, ...images] };
+  } finally {
+    await cleanupRender(res);
+  }
+}

package/server/engine/mcp/tools/screenshot-url.js

@@ -0,0 +1,195 @@
+/**
+ * mcp/tools/screenshot-url.js — screenshot_url MCP tool（2026-07-29）
+ *
+ * 对任意外部 URL 截图。诞生背景：explorer 找视觉参考只能 WebFetch 拿文本，
+ * 再用文字向主 agent 转述"这个站是深色的、图占主导"—— 找视觉参考却看不见
+ * 视觉。这个工具让 explorer / 主 agent 直接看到参考站长什么样。
+ *
+ * 安全：
+ *   - 只放 http/https（file:// 会变成任意本地文件读取，硬拒）
+ *   - 拒绝内网/环回/link-local 字面量（localhost / 127.* / 10.* / 172.16-31.* /
+ *     192.168.* / 169.254.* / *.local / [::1]）—— explorer 会读不可信网页内容，
+ *     prompt injection 不该能借它窥探内网服务。DNS rebinding 不在防御范围
+ *     （截图只回图片，风险面已经很小）。
+ *
+ * 加载策略：外站经常永远到不了 networkidle（分析脚本长轮询），goto 超时不算
+ * 失败 —— 部分渲染的参考图也比纯文字转述强，超时记进 caption。
+ */
+
+import { tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { attachPageDiagnostics, runBeforeShot, normalizeShot, FIDELITY_LAUNCH_ARGS, detectPaintTransform } from './helpers/shot-pipeline.js';
+import { checkUrl, attachSsrfGuard } from '../../../lib/ssrf-guard.js';
+import { denyText } from './browse.js';
+import { startBrowseProxy } from '../../../lib/browse-proxy.js';
+
+const RASTER_SCALE = 0.6;
+const DEVICE_VIEWPORTS = {
+  desktop: { width: 1440, height: 900 },
+  tablet: { width: 834, height: 1112 },
+  mobile: { width: 390, height: 844 },
+};
+
+const PRIVATE_HOST_RE = new RegExp(
+  '^(localhost|0\\.0\\.0\\.0|127\\.|10\\.|192\\.168\\.|169\\.254\\.'
+  + '|172\\.(1[6-9]|2[0-9]|3[01])\\.'
+  + '|\\[::1\\]|\\[fc|\\[fd|\\[fe80)'
+  , 'i',
+);
+
+function validateUrl(raw) {
+  let u;
+  try {
+    u = new URL(raw);
+  } catch {
+    return { ok: false, message: `not a valid URL: ${raw}` };
+  }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+    return { ok: false, message: `only http/https URLs are allowed (got ${u.protocol})` };
+  }
+  // ⚠️ 这里**只做词法预筛**。真判据是 checkUrl（解析 DNS 按 IP 判）+ 页面上挂的
+  // CDP 闸（拦跳转与子资源）。留着这道是因为它便宜、能在解析之前挡掉最常见的字面量。
+  const host = u.hostname.toLowerCase();
+  if (PRIVATE_HOST_RE.test(host) || host.endsWith('.local')) {
+    return { ok: false, message: `refusing to screenshot private/internal address: ${host}` };
+  }
+  return { ok: true, url: u };
+}
+
+/**
+ * @param {object} deps
+ * @param {import('../../agent/context.js').AgentContext} [deps.ctx]
+ */
+export function makeScreenshotUrlTool({ projectId, ctx } = {}) {
+  return tool(
+    'screenshot_url',
+    `Take a screenshot of any external web page (http/https) and return it as an
+image you can see via vision. THE tool for gathering visual design references —
+when researching how other sites handle layout, typography, color, or imagery,
+look at them instead of reading their HTML and imagining.
+
+- device: render at a real device width (desktop=1440, tablet=834, mobile=390)
+- fullPage=true captures the whole scrollable page (auto-scrolls first so
+  lazy-loaded images and scroll reveals are triggered); default captures the
+  first viewport only — usually enough to judge a site's character, and much
+  cheaper in context
+- The caption reports console errors / failed resources of the target page —
+  ignore those unless they explain a broken-looking render.
+
+External pages can be slow; if the network never settles the shot is taken
+anyway after 12s and the caption says so. Only http/https and public hosts.`,
+    {
+      url: z.string().describe('The http/https URL to screenshot'),
+      device: z
+        .enum(['desktop', 'tablet', 'mobile'])
+        .optional()
+        .describe('Viewport width preset: desktop=1440 (default), tablet=834, mobile=390'),
+      fullPage: z
+        .boolean()
+        .optional()
+        .describe('Capture the full scrollable page (auto-scrolls through it first to trigger lazyload). Default false = first viewport only, much cheaper.'),
+      detail: z
+        .enum(['normal', 'high'])
+        .optional()
+        .describe("Raster detail. 'normal' (default) = 0.6x pixels, enough for layout/palette judgment. 'high' = full resolution, only when you must read small text."),
+    },
+    async ({ url: rawUrl, device, fullPage, detail }) => {
+      const check = validateUrl(rawUrl);
+      if (!check.ok) {
+        return { content: [{ type: 'text', text: check.message }], isError: true };
+      }
+      // ⛔ 2026-08-18 补：上面那道 `validateUrl` 是**纯词法**的 —— 挡得住
+      // `127.0.0.1` 这种字面量，挡不住一个 DNS 解析到内网的公网域名，也不管 302。
+      // 新闸（lib/ssrf-guard.js）本来就是来替换它的，但上线那天**忘了接这个工具**，
+      // 于是它自己一直是个活着的 SSRF 洞。现在：按解析出的 IP 判 + 页面上挂 CDP 闸
+      // 拦跳转与子资源。
+      const pre = await checkUrl(check.url.href);
+      if (!pre.ok) {
+        // 拒因分种类说（DNS 死域名 ≠ 策略拦截；文案与线上地址提示同 browse 工具）
+        const tail = denyText(pre, projectId, check.url.href).join('\n');
+        return { content: [{ type: 'text', text: `refusing to screenshot: ${pre.reason}\n${tail}` }], isError: true };
+      }
+
+      const vp = DEVICE_VIEWPORTS[device || 'desktop'];
+      let browser;
+      try {
+        const { chromium } = await import('playwright');
+        // ⭐ 走同一个出网代理（2026-08-18 二次修）。CDP 那道闸看不见四类东西：
+        // WebSocket 握手、`<link rel=prefetch>`、`sendBeacon`、还没装闸的弹窗
+        // —— 四条都是攻出来的，而这个工具吃的正是**任意用户给的 URL**，同一批
+        // 绕过一字不改就能用在它身上。代理是所有出网的必经之路，且连的是自己
+        // 解析并验过的那个 IP（顺带根除 DNS 重绑定）。
+        // `bypass: ''`：默认会放过 loopback，那正是最要拦的。
+        const { port: proxyPort } = await startBrowseProxy();
+        browser = await chromium.launch({
+          headless: true,
+          args: FIDELITY_LAUNCH_ARGS,
+          proxy: { server: `http://127.0.0.1:${proxyPort}`, bypass: '' },
+        });
+        const rasterScale = detail === 'high' ? 1 : RASTER_SCALE;
+        const ctx = await browser.newContext({ viewport: vp, deviceScaleFactor: rasterScale, colorScheme: 'light' });
+        const guard = await attachSsrfGuard(ctx, undefined, { proxied: true });
+        const page = await ctx.newPage();
+        await guard.armPage(page);   // ⭐ 必须 await 完才导航（竞态是攻出来的）
+        const diag = attachPageDiagnostics(page);
+
+        let gotoNote = null;
+        try {
+          await page.goto(check.url.href, { waitUntil: 'networkidle', timeout: 12000 });
+        } catch (err) {
+          // 超时（页面已部分渲染）→ 照截；真导航失败（DNS/refused）→ 报错
+          if (!/Timeout/i.test(String(err?.message))) {
+            return {
+              content: [{ type: 'text', text: `Failed to load ${rawUrl}: ${err?.message || err}` }],
+              isError: true,
+            };
+          }
+          gotoNote = 'network never settled (12s) — captured current render state';
+        }
+
+        if (fullPage) {
+          // 滚一遍触发 lazyload / scroll reveal，再回顶整页截
+          await runBeforeShot(page, 'scrollToBottom');
+        }
+        const buf = await page.screenshot({ fullPage: fullPage === true, type: 'png' });
+
+        try {
+          ctx?.emit?.({
+            type: 'run.screenshot_taken',
+            sizeBytes: buf.length,
+            viewport: vp,
+            mode: `url=${check.url.hostname}`,
+          });
+        } catch { /* emit fail-safe */ }
+
+        const paintNote = await detectPaintTransform(page);
+        const shot = await normalizeShot(buf);
+        const title = await page.title().catch(() => '');
+        const finalUrl = page.url();
+        const captionParts = [
+          `Screenshot of ${finalUrl}${title ? ` — "${title}"` : ''} (${device || 'desktop'} ${vp.width}x${vp.height} @${rasterScale}x, fullPage=${fullPage === true})`,
+        ];
+        if (shot.note) captionParts.push(shot.note);
+        if (gotoNote) captionParts.push(gotoNote);
+        if (paintNote) captionParts.push(paintNote);
+        captionParts.push(diag.summary());
+
+        return {
+          content: [
+            { type: 'text', text: captionParts.join('\n') },
+            { type: 'image', data: shot.data, mimeType: shot.mimeType },
+          ],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `screenshot_url failed: ${err?.message || String(err)}` }],
+          isError: true,
+        };
+      } finally {
+        if (browser) {
+          try { await browser.close(); } catch { /* ignore */ }
+        }
+      }
+    },
+  );
+}