@twinsearth/dsh-master 3.2.9 → 3.3.0

package/dist-worker/sink-http.js

@@ -83,6 +83,7 @@ export function createHttpSink(options) {
         step: (step) => enqueue({ type: 'step', payload: step, at: Date.now() }),
         stream: (delta) => enqueue({ type: 'stream', payload: delta, at: Date.now() }),
         log: (message) => enqueue({ type: 'log', payload: { message }, at: Date.now() }),
+        cost: (event) => enqueue({ type: 'cost', payload: event, at: Date.now() }),
         async flush() {
             while (queue.length > 0)
                 await flush();

package/dist-worker/spill.js

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+/**
+ * 3.3.0 · A1 spill 存储（设计 §6「强制约束」）。
+ *
+ * 「一次压缩后原文仍可经 spill 文件回读」——大输出先落盘，模型只看到摘要 + 回读路径，
+ * 避免「省 token 换瞎眼」。
+ *
+ * 安全边界：
+ *   * 只能写在 `<workspace>/.dsh-master/spill/` 之内（路径由本模块生成，不接受外部传入）；
+ *   * 写入前由调用方**脱敏**（Agent Loop 传入已 redact 的文本）；
+ *   * 总量与单文件都有上限，超出后按最旧淘汰（有界，不会把分身磁盘写满）；
+ *   * 文件名只含 `ticketId` 的安全片段 + step + 序号，不反射工具参数。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+const safeSegment = (value, fallback) => {
+    // 只保留字母数字与 _-：点号也剔除，确保文件名里不可能出现 `..` 片段。
+    const cleaned = String(value ?? '').replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 48);
+    return cleaned === '' ? fallback : cleaned;
+};
+export function createSpillStore(options) {
+    const workspace = path.resolve(String(options.workspace));
+    const relDir = String(options.dir ?? path.join('.dsh-master', 'spill'));
+    const dir = path.resolve(workspace, relDir);
+    // 路径 jail：解析后必须仍在 workspace 内。
+    const inside = dir === workspace || dir.startsWith(`${workspace}${path.sep}`);
+    const maxFileBytes = Math.max(1024, Number(options.maxFileBytes ?? 512 * 1024) || 512 * 1024);
+    const maxTotalBytes = Math.max(maxFileBytes, Number(options.maxTotalBytes ?? 8 * 1024 * 1024) || 8 * 1024 * 1024);
+    const maxFiles = Math.max(1, Number(options.maxFiles ?? 40) || 40);
+    const clock = typeof options.clock === 'function' ? options.clock : () => Date.now();
+    let seq = 0;
+    function listFiles() {
+        try {
+            return fs.readdirSync(dir)
+                .map((name) => {
+                try {
+                    const stat = fs.statSync(path.join(dir, name));
+                    return stat.isFile() ? { name, size: stat.size, at: stat.mtimeMs } : null;
+                }
+                catch {
+                    return null;
+                }
+            })
+                .filter((item) => item !== null);
+        }
+        catch {
+            return [];
+        }
+    }
+    /** 淘汰：文件数 / 总字节超限时按最旧删除。 */
+    function evict() {
+        const files = listFiles().sort((a, b) => a.at - b.at);
+        let total = files.reduce((sum, file) => sum + file.size, 0);
+        let count = files.length;
+        for (const file of files) {
+            if (count <= maxFiles && total <= maxTotalBytes)
+                break;
+            try {
+                fs.rmSync(path.join(dir, file.name), { force: true });
+            }
+            catch { /* ignore */ }
+            total -= file.size;
+            count -= 1;
+        }
+    }
+    function save(input) {
+        if (!inside)
+            return null;
+        const text = String(input?.text ?? '');
+        if (text.length === 0)
+            return null;
+        const bytes = Buffer.byteLength(text, 'utf8');
+        seq += 1;
+        const name = `${safeSegment(input?.ticketId ?? '', 'ticket')}__s${Number(input?.stepIndex) || 0}__${seq}__${safeSegment(input?.toolName ?? 'tool', 'tool')}.txt`;
+        const abs = path.resolve(dir, name);
+        if (!abs.startsWith(`${dir}${path.sep}`))
+            return null;
+        try {
+            fs.mkdirSync(dir, { recursive: true });
+            // 单文件超限：拒绝落盘（调用方按「无法回读」降级，不静默截断原文）。
+            if (bytes > maxFileBytes)
+                return null;
+            fs.writeFileSync(abs, text, 'utf8');
+            evict();
+            return { relPath: path.relative(workspace, abs).split(path.sep).join('/'), bytes, lines: text.split('\n').length };
+        }
+        catch {
+            return null;
+        }
+    }
+    function read(relPath) {
+        const abs = path.resolve(workspace, String(relPath ?? ''));
+        if (!abs.startsWith(`${workspace}${path.sep}`))
+            return null;
+        try {
+            return fs.readFileSync(abs, 'utf8');
+        }
+        catch {
+            return null;
+        }
+    }
+    function stats() {
+        const files = listFiles();
+        return { dir: path.relative(workspace, dir).split(path.sep).join('/'), files: files.length, bytes: files.reduce((sum, file) => sum + file.size, 0) };
+    }
+    function clear() {
+        try {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+        catch { /* ignore */ }
+        void clock;
+    }
+    return Object.freeze({ save, read, stats, clear });
+}

package/dist-worker/tool-batch.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+/** 单次批量教学文本（一次性；之后不再重复注入）。 */
+export const BATCH_GUIDANCE = [
+    '【批量调用提示（一次性）】',
+    '你可以在同一轮里返回多个 tool_calls：它们会按返回顺序依次执行，每个结果都会回灌给你。',
+    '把互不依赖的读取/检索/写入合并到同一轮，能减少往返次数；有依赖时必须分轮。',
+    '不要把一个列表塞进单个工具的参数里伪装成批量（例如把多个路径写进一个 path 字段）；',
+    '请直接发多个 tool_calls。',
+].join('\n');
+export function createBatchAdvisor(options = {}) {
+    const mode = options.mode === 'ptc' ? 'ptc' : 'native';
+    const maxBatchPerTurn = Math.max(1, Number(options.maxBatchPerTurn ?? 4) || 4);
+    const enabled = options.enabled !== false;
+    let taught = false;
+    let corrections = 0;
+    // 本项目 Worker 走 chat/HTTP 工具回路，没有 PTC（程序化工具调用）执行器：
+    // 请求 PTC ⇒ 显式 skipped，而不是偷偷降级成 native。
+    const unsupported = mode === 'ptc';
+    const status = () => (enabled && !unsupported
+        ? { state: 'active', reason: null, mode, maxBatchPerTurn }
+        : { state: 'skipped', reason: unsupported ? 'unsupported-host' : 'disabled-by-config', mode, maxBatchPerTurn });
+    function review(calls) {
+        if (status().state !== 'active')
+            return { ok: true, correction: null, reason: null };
+        const list = Array.isArray(calls) ? calls : [];
+        if (list.length > maxBatchPerTurn) {
+            corrections += 1;
+            return {
+                ok: false,
+                reason: 'batch-too-large',
+                correction: `【批量形状纠偏】本轮 ${list.length} 个 tool_calls 超过单轮上限 ${maxBatchPerTurn}；已全部按序执行，下一轮请拆分。`,
+            };
+        }
+        // 形状纠偏：单个工具的参数里出现「看起来像批量」的数组（>=2 项字符串），提示改发多个 tool_calls。
+        for (const call of list) {
+            let args = {};
+            try {
+                const parsed = JSON.parse(String(call?.args ?? '{}'));
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+                    args = parsed;
+            }
+            catch {
+                continue;
+            }
+            const arrayish = Object.entries(args).filter(([, value]) => Array.isArray(value) && value.length >= 2 && value.every((item) => typeof item === 'string'));
+            if (arrayish.length > 0 && list.length === 1) {
+                corrections += 1;
+                return {
+                    ok: false,
+                    reason: 'array-faked-batch',
+                    correction: `【批量形状纠偏】把多个值塞进了 ${call.name} 的 ${arrayish.map(([key]) => key).join('/')} 参数；这不会被执行器当成批量。下一轮请改为在同一轮返回多个 tool_calls。`,
+                };
+            }
+        }
+        return { ok: true, correction: null, reason: null };
+    }
+    return Object.freeze({
+        status,
+        guidance: () => BATCH_GUIDANCE,
+        review,
+        taught: () => taught,
+        markTaught: () => { taught = true; },
+        stats: () => ({ taught, corrections }),
+    });
+}

package/dist-worker/tool-compact.js

@@ -0,0 +1,275 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+/**
+ * 3.3.0 模块层 A · A1 `tool-compact`（工具输出紧凑化）。
+ *
+ * 只处理**已知内置工具**的输出形状，未知工具一律原样透传。三档模式：
+ *   * `off`     —— 不计算；
+ *   * `shadow`  —— 真算「本可节省多少」，但**仍返回原文**（默认档，零行为变化）；
+ *   * `enforce` —— 紧凑结果确实更短时才替换。
+ *
+ * 安全边界：紧凑化只作用于模型可见的工具回执文本，不改工具执行、不改权限、
+ * 不改错误码；`applied` 仅在 `compactChars < originalChars` 时为 true。
+ *
+ * 归因（设计 §5.4）：`estimatedTokens` 不是 `savedChars/4` 的近似，而是
+ * `baselineOutputTokens(toolName, 原始长度) − actualOutputTokens(紧凑长度)`，
+ * 拟合参数在 `worker/baseline-fit.ts` 冻结、版本随参数变更。
+ */
+import { attributedSavedTokens, A1_FIT_VERSION } from "./baseline-fit.js";
+const MODES = Object.freeze(['off', 'shadow', 'enforce']);
+export function normalizeCompactMode(value) {
+    const raw = String(value ?? '').trim().toLowerCase();
+    return MODES.includes(raw) ? raw : 'shadow';
+}
+function compactListDir(text) {
+    if (text === '(empty)')
+        return text;
+    const lines = text.split('\n');
+    const compact = [];
+    for (const line of lines) {
+        if (line.startsWith('dir '))
+            compact.push(`${line.slice(4)}/`);
+        else if (line.startsWith('file '))
+            compact.push(line.slice(5));
+        else
+            return null; // 未知形状：不猜
+    }
+    return compact.join('\n');
+}
+function compactWriteFile(text) {
+    const match = /^written (\d+) bytes to (.+)$/u.exec(text);
+    if (!match)
+        return null;
+    return `ok ${match[2]} (+${match[1]} B)`;
+}
+function compactShell(text) {
+    if (!/^STDOUT:/u.test(text))
+        return null;
+    const match = /^STDOUT:\n([\s\S]*?)\nSTDERR:\n([\s\S]*)$/u.exec(text);
+    if (!match)
+        return null;
+    const stdout = match[1].replace(/[ \t]+$/gmu, '').replace(/\n{3,}/gu, '\n\n').trim();
+    const stderr = match[2].replace(/[ \t]+$/gmu, '').replace(/\n{3,}/gu, '\n\n').trim();
+    if (!stdout && !stderr)
+        return '(no output)';
+    // grep -n 形态（path:line:text）优先进「命中行合并」，能省掉重复文件名。
+    if (!stderr) {
+        const grep = compactGrepLike(stdout);
+        if (grep !== null)
+            return grep;
+    }
+    if (!stderr)
+        return stdout;
+    if (!stdout)
+        return `[stderr]\n${stderr}`;
+    return `${stdout}\n[stderr]\n${stderr}`;
+}
+/**
+ * 文件读取：**去冗余空行但保留行号**。
+ *
+ * 行号本身要花字符，所以这里算两个候选，取更短者（且必须短于原文才替换）：
+ *   a) 带行号 + 空行游程压缩 —— 定位性最好；
+ *   b) 只压空白/空行、不带行号 —— 兜底，保证绝不「越压越长」。
+ */
+function compactReadFile(text) {
+    if (text === '')
+        return null;
+    const lines = text.split('\n');
+    if (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    const plainOut = [];
+    let plainBlank = 0;
+    for (const rawLine of lines) {
+        const line = rawLine.replace(/[ \t]+$/u, '');
+        if (line.trim() === '') {
+            plainBlank += 1;
+            if (plainBlank > 1)
+                continue;
+        }
+        else {
+            plainBlank = 0;
+        }
+        plainOut.push(line);
+    }
+    while (plainOut.length > 0 && plainOut[plainOut.length - 1] === '')
+        plainOut.pop();
+    const plain = plainOut.join('\n');
+    const numberedOut = [];
+    let blankStart = -1;
+    const flushBlanks = (endLine) => {
+        if (blankStart < 0)
+            return;
+        numberedOut.push(blankStart === endLine ? `⋯${blankStart}` : `⋯${blankStart}-${endLine}`);
+        blankStart = -1;
+    };
+    for (let index = 0; index < lines.length; index += 1) {
+        const lineNo = index + 1;
+        const line = lines[index].replace(/[ \t]+$/u, '');
+        if (line.trim() === '') {
+            if (blankStart < 0)
+                blankStart = lineNo;
+            continue;
+        }
+        flushBlanks(lineNo - 1);
+        numberedOut.push(`${lineNo}: ${line}`);
+    }
+    flushBlanks(lines.length);
+    const numbered = numberedOut.join('\n');
+    const candidates = [numbered, plain].filter((candidate) => candidate.length < text.length);
+    if (candidates.length === 0)
+        return null;
+    // 优先带行号（定位性），但它必须确实更短。
+    return candidates.includes(numbered) ? numbered : plain;
+}
+/* ------------------------------------------------------------------ *
+ * grep 形态（设计 §6：命中行 + 上下文一行）
+ *
+ * 本项目的 Worker 工具面暂无独立 grep 工具，但 shell 里的 `grep -n` 结果就是
+ * `path:line:text` 形态；这里对它做「同文件合并 + 每条命中带一处上下文」的压缩。
+ * ------------------------------------------------------------------ */
+const GREP_LINE = /^([^\s:][^:]*):(\d+):(.*)$/u;
+function compactGrepLike(text) {
+    const lines = text.split('\n').filter((line) => line !== '');
+    if (lines.length < 3)
+        return null;
+    const parsed = [];
+    for (const line of lines) {
+        const match = GREP_LINE.exec(line);
+        if (!match)
+            return null; // 形状不符：不猜，原样返回
+        parsed.push({ file: match[1], line: Number(match[2]), text: match[3].trim() });
+    }
+    const byFile = new Map();
+    for (const hit of parsed) {
+        const list = byFile.get(hit.file) ?? [];
+        list.push({ line: hit.line, text: hit.text });
+        byFile.set(hit.file, list);
+    }
+    const out = [];
+    for (const [file, hits] of byFile) {
+        const sorted = [...hits].sort((a, b) => a.line - b.line);
+        // 同文件命中合并成一行：`path: 12: text | 13: text`
+        out.push(`${file}: ${sorted.map((hit) => `${hit.line}: ${hit.text}`).join(' | ')}`);
+    }
+    const compact = out.join('\n');
+    return compact.length < text.length ? compact : null;
+}
+/* ------------------------------------------------------------------ *
+ * 错误回执：给「可执行的下一步」
+ * ------------------------------------------------------------------ */
+const ERROR_HINTS = [
+    { match: /path-outside-mandate/u, hint: '改用 Mandate.scope 内的路径' },
+    { match: /sensitive-path-denied/u, hint: '该路径被禁止写入，换普通源码文件' },
+    { match: /file-too-large/u, hint: '先用 fs_list_dir 定位，再分段读取' },
+    { match: /not-a-file/u, hint: '该路径不是文件，先用 fs_list_dir 查看' },
+    { match: /content-too-large/u, hint: '拆成多次写入或改用片段修改' },
+    { match: /shell-(?:redirection|substitution|cd|parent-traversal|absolute-path|home-path|env-expansion)/u, hint: '去掉重定向/变量/绝对路径，只用单条只读命令' },
+    { match: /shell-git-write/u, hint: '写操作交给 create_pr，不要在 shell 里改远端' },
+    { match: /未授权执行 Shell|vmIsolation|隔离证明/u, hint: '当前 Manifest 未授权 Shell，改用文件工具' },
+    { match: /超时|aborted/u, hint: '缩小操作范围或拆分命令后重试' },
+];
+function compactError(text) {
+    const isError = /^(?:执行报错|【系统拒绝】|错误[:：]|Error[:：])/u.test(text)
+        || /^(?:ENOENT|EACCES|EPERM|EISDIR|ENOTDIR)\b/u.test(text);
+    if (!isError)
+        return null;
+    const hint = ERROR_HINTS.find((item) => item.match.test(text))?.hint;
+    if (!hint)
+        return null;
+    // 保留原始错误码/首行（可定位），把冗长堆栈压掉，再补一条可执行建议。
+    const firstLine = text.split('\n').map((line) => line.trim()).filter(Boolean)[0] ?? '';
+    const compact = `${firstLine}\n→ 建议: ${hint}`;
+    return compact.length < text.length ? compact : null;
+}
+function formatterFor(toolName) {
+    if (toolName === 'fs_read_file')
+        return (text) => compactError(text) ?? compactReadFile(text);
+    if (toolName === 'fs_list_dir')
+        return (text) => compactError(text) ?? compactListDir(text);
+    if (toolName === 'fs_write_file')
+        return (text) => compactError(text) ?? compactWriteFile(text);
+    if (toolName === 'exec_shell_in_vm')
+        return (text) => compactError(text) ?? compactGrepLike(text) ?? compactShell(text);
+    return null;
+}
+/** 头尾摘要 + 回读提示（大输出用）。 */
+function headTailSummary(text, spilled, head, tail) {
+    const lines = text.split('\n');
+    const headLines = lines.slice(0, head);
+    const tailLines = tail > 0 ? lines.slice(Math.max(head, lines.length - tail)) : [];
+    const marker = `⋯[已落盘 ${spilled.relPath}：${spilled.bytes} B / ${spilled.lines} 行；完整内容用 fs_read_file 读取该路径]`;
+    return [...headLines, marker, ...tailLines].join('\n');
+}
+export function createToolCompactor(options = {}) {
+    const mode = normalizeCompactMode(options.mode);
+    const spill = options.spill ?? null;
+    const spillThresholdChars = Math.max(500, Number(options.spillThresholdChars ?? 6000) || 6000);
+    const spillHeadLines = Math.max(1, Number(options.spillHeadLines ?? 20) || 20);
+    const spillTailLines = Math.max(0, Number(options.spillTailLines ?? 5) || 5);
+    function compact(input) {
+        const text = String(input?.text ?? '');
+        const toolName = String(input?.toolName ?? '');
+        // §6 强制约束：大输出先落盘（**只在 enforce**，shadow 不得产生副作用），再给摘要。
+        if (mode === 'enforce' && spill && text.length >= spillThresholdChars) {
+            const spilled = spill.save({ text });
+            if (spilled) {
+                const summary = headTailSummary(text, spilled, spillHeadLines, spillTailLines);
+                if (summary.length < text.length) {
+                    return {
+                        module: 'a1-compact',
+                        toolName,
+                        mode,
+                        applicable: true,
+                        evaluated: true,
+                        applied: true,
+                        text: summary,
+                        originalChars: text.length,
+                        compactChars: summary.length,
+                        savedChars: text.length - summary.length,
+                        estimatedTokens: attributedSavedTokens(toolName, text.length, summary.length),
+                        fitVersion: A1_FIT_VERSION,
+                        spill: spilled,
+                    };
+                }
+            }
+        }
+        const base = {
+            module: 'a1-compact',
+            toolName,
+            mode,
+            applicable: false,
+            applied: false,
+            evaluated: false,
+            text,
+            originalChars: text.length,
+            compactChars: text.length,
+            savedChars: 0,
+            estimatedTokens: 0,
+            fitVersion: A1_FIT_VERSION,
+        };
+        if (mode === 'off')
+            return base;
+        const formatter = formatterFor(toolName);
+        if (!formatter)
+            return base;
+        const compacted = formatter(text);
+        if (compacted === null)
+            return { ...base, applicable: true, evaluated: true };
+        const compactChars = compacted.length;
+        const savedChars = Math.max(0, text.length - compactChars);
+        const applied = mode === 'enforce' && compactChars < text.length;
+        return {
+            ...base,
+            applicable: true,
+            evaluated: true,
+            applied,
+            text: applied ? compacted : text,
+            compactChars,
+            savedChars,
+            // §5.4：归因用固定拟合式的差额，而不是 savedChars/4 的近似。
+            estimatedTokens: attributedSavedTokens(toolName, text.length, compactChars),
+            fitVersion: A1_FIT_VERSION,
+        };
+    }
+    return Object.freeze({ mode, compact });
+}

package/dist-worker/tool-disclosure.js

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+/** 默认常驻：只保留最基础的四类能力 + 加载入口本身。 */
+export const DEFAULT_RESIDENT_TOOLS = Object.freeze(['fs_read_file', 'fs_list_dir', 'fs_write_file', 'exec_shell_in_vm', 'load_tools']);
+const tokensOf = (text) => (text.length > 0 ? Math.ceil(text.length / 4) : 0);
+export function createDisclosureState(options = {}) {
+    const enabled = options.enabled === true;
+    const resident = new Set((Array.isArray(options.resident) && options.resident.length > 0 ? options.resident : DEFAULT_RESIDENT_TOOLS)
+        .map((name) => String(name ?? '')));
+    const allowlist = new Set((Array.isArray(options.allowlist) ? options.allowlist : []).map((name) => String(name ?? '')));
+    const hideNonResident = options.hideNonResident !== false;
+    const loadedSet = new Set();
+    let loadEvents = 0;
+    let schemaTokens = 0;
+    let schemaCount = 0;
+    function visible(allNames) {
+        const names = allNames.map((name) => String(name ?? '')).filter(Boolean);
+        // 关闭（或未启用隐藏）⇒ 恢复全量工具面：fail-open 到原行为。
+        if (!enabled || !hideNonResident)
+            return names;
+        return names.filter((name) => resident.has(name) || loadedSet.has(name));
+    }
+    function canLoad(name) {
+        const tool = String(name ?? '');
+        if (!tool)
+            return false;
+        if (resident.has(tool))
+            return true;
+        if (allowlist.size === 0)
+            return true;
+        return allowlist.has(tool);
+    }
+    function load(input) {
+        const requested = (Array.isArray(input?.names) ? input.names : []).map((name) => String(name ?? '')).filter(Boolean);
+        const newly = requested.filter((name) => !resident.has(name) && !loadedSet.has(name) && canLoad(name));
+        if (newly.length > 0) {
+            for (const name of newly)
+                loadedSet.add(name);
+            loadEvents += 1;
+            const schemas = (Array.isArray(input?.schemas) ? input.schemas : []).filter((schema) => newly.includes(String(schema?.name ?? '')));
+            schemaCount += schemas.length;
+            schemaTokens += tokensOf(JSON.stringify(schemas));
+        }
+        return { loaded: [...loadedSet], schemaTokens, schemaCount, events: loadEvents };
+    }
+    return Object.freeze({
+        enabled,
+        visible,
+        loaded: () => [...loadedSet],
+        load,
+        canLoad,
+        stats: () => ({ loadEvents, schemaTokens, schemaCount, loaded: [...loadedSet] }),
+    });
+}
+/**
+ * `load_tools` 元工具：模型用它「按需加载」高级工具，返回值里带完整 schema。
+ * 常驻于工具面（否则模型无法表达加载意图）。
+ */
+export function createLoadToolsTool(state, tools) {
+    return {
+        name: 'load_tools',
+        description: '按需加载高级工具（返回其完整 schema）。参数 names 为工具名数组。',
+        parameters: {
+            type: 'object',
+            properties: { names: { type: 'array', items: { type: 'string' } } },
+            required: ['names'],
+        },
+        async execute(args) {
+            const requested = Array.isArray(args?.names) ? args.names.map((name) => String(name ?? '')) : [];
+            if (requested.length === 0)
+                return '执行报错: names 不能为空';
+            const known = new Set(tools.map((tool) => tool.name));
+            const unknown = requested.filter((name) => !known.has(name));
+            const denied = requested.filter((name) => known.has(name) && !state.canLoad(name));
+            const schemas = tools
+                .filter((tool) => requested.includes(tool.name) && known.has(tool.name) && state.canLoad(tool.name))
+                .map((tool) => ({ name: tool.name, description: tool.description, parameters: tool.parameters }));
+            const result = state.load({ names: schemas.map((schema) => schema.name), schemas });
+            const lines = [];
+            if (schemas.length > 0)
+                lines.push(`已加载 ${schemas.length} 个工具，完整 schema：\n${JSON.stringify(schemas, null, 2)}`);
+            if (unknown.length > 0)
+                lines.push(`未知工具: ${unknown.join(', ')}`);
+            if (denied.length > 0)
+                lines.push(`不在 allowlist，拒绝加载: ${denied.join(', ')}`);
+            lines.push(`累计加载 ${result.events} 次，schema token ≈ ${result.schemaTokens}`);
+            return lines.join('\n');
+        },
+    };
+}

package/dist-worker/tools.js

@@ -17,6 +17,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
+import { schemaHashOf } from "./edg.js";
 export const LONG_SYNC_COMMAND_THRESHOLD_MS = 5000;
 const MAX_READ_BYTES = 256 * 1024;
 const MAX_WRITE_BYTES = 1024 * 1024;
@@ -303,6 +304,7 @@ function createPrTool(client) {
     return {
         name: 'create_pr',
         description: '在允许的仓库创建一个 Pull Request（需要宿主注入 PR 客户端；默认不可用）',
+        destructive: true,
         parameters: {
             type: 'object',
             properties: {
@@ -414,6 +416,7 @@ export function createSandboxTools(options) {
         {
             name: 'fs_write_file',
             description: '写入文件（workspace 内且位于 Mandate.scope；拒绝 .git/.env 等敏感路径）',
+            destructive: true,
             parameters: { type: 'object', properties: { path: { type: 'string' }, content: { type: 'string' } }, required: ['path', 'content'] },
             async execute(args, context) {
                 // v3.2.3：Mandate 每次从 context 取，避免构造闭包与本次 Ticket 不一致。
@@ -438,6 +441,7 @@ export function createSandboxTools(options) {
         {
             name: 'exec_shell_in_vm',
             description: '在分身 workspace 内执行 Shell（需 Mandate.allowShell；脱敏环境、黑名单、进程树超时）',
+            destructive: true,
             parameters: { type: 'object', properties: { command: { type: 'string' } }, required: ['command'] },
             async execute(args, context) {
                 // P0-2 fail-closed：没有隔离证明就不允许 Shell（黑名单不是安全边界）。
@@ -497,9 +501,21 @@ export function createSandboxTools(options) {
 export function createToolRegistry(tools) {
     const byName = new Map(tools.map((tool) => [tool.name, tool]));
     return {
+        names() {
+            return tools.map((tool) => tool.name);
+        },
         schemas() {
             return tools.map((tool) => ({ name: tool.name, description: tool.description, parameters: tool.parameters }));
         },
+        destructive(name) {
+            return byName.get(String(name))?.destructive === true;
+        },
+        schemaHash(name) {
+            const tool = byName.get(String(name));
+            if (!tool)
+                return '';
+            return schemaHashOf(tool.name, tool.parameters, tool.description);
+        },
         async execute(call, context) {
             const tool = byName.get(String(call?.name ?? ''));
             if (!tool)