@twinsearth/dsh-master 0.0.0-stage → 3.2.8

package/dist-worker/tools.js

@@ -0,0 +1,542 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+/**
+ * Worker 的安全工具集（v3.2.3）。
+ *
+ * v3.2.2 安全审计后的加固：
+ *   * Shell 使用白名单环境变量（剥离 KEY/TOKEN/SECRET/DSH_*），防密钥回灌模型；
+ *   * Shell 超时/中止时 kill 整个进程树（Windows taskkill /T /F；POSIX 进程组），
+ *     不再出现“工具已返回但后台进程继续跑”；
+ *   * fs_write_file 的 Mandate 来自每次调用的 context.mandate（而非构造闭包），
+ *     并默认拒绝 .git/.dsh/.env 等敏感路径；
+ *   * 路径 jail + realpath 防 symlink 逃逸保持不变。
+ *
+ * 仍然坚持：Shell 的高危语义无法用黑名单彻底解决，**VM/容器隔离是主防线**；
+ * allowShell 应与“已证明隔离的 VM”绑定（见 docs/SECURITY.md）。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+export const LONG_SYNC_COMMAND_THRESHOLD_MS = 5000;
+const MAX_READ_BYTES = 256 * 1024;
+const MAX_WRITE_BYTES = 1024 * 1024;
+const MAX_SHELL_OUTPUT_CHARS = 16_000;
+const SHELL_ENV_ALLOWLIST = new Set([
+    'PATH', 'Path', 'PATHEXT', 'SYSTEMROOT', 'SystemRoot', 'WINDIR', 'COMSPEC', 'ComSpec',
+    'TEMP', 'TMP', 'HOME', 'USERPROFILE', 'HOMEDRIVE', 'HOMEPATH', 'LANG', 'LC_ALL', 'TZ', 'SHELL',
+]);
+/** 默认拒绝写入的敏感路径（相对 workspace；可在 config 覆盖）。 */
+export const DEFAULT_DENY_WRITE_PATHS = ['.git', '.dsh', '.env', '.env.local', '.ssh', 'node_modules/.cache'];
+/**
+ * 命令级禁锢（v3.2.5 P0-2 纵深防御）：
+ *
+ * 黑名单**不是**安全边界—— type ../x / echo > ../x / sh -c ... / powershell -Command ...
+ * 都能绕过字面黑名单。这里在命令串层面硬拒绝能逃出 jail 的构造：
+ *   * 重定向与管道（> >> < | && || ;）：可把输出写到任意路径、可串联任意解释器；
+ *   * 目录切换（cd / chdir / pushd / popd）：一旦 cd 出 jail，后续相对路径全部逃离；
+ *   * 父目录穿越（..）：相对逃逸的主要形式；
+ *   * 绝对路径（盘符 / 前导斜杠 / ~）：jail 外的绝对路径；
+ *   * 环境变量展开（%VAR% / $VAR / ${VAR}）：可拼出密钥名或路径；
+ *   * 解释器（sh/bash/cmd/powershell/node/python/...）：等价任意代码执行。
+ *
+ * 真正的边界仍是 VM/容器（见 docs/SECURITY.md）：本函数只保证「未证明隔离时不可用」。
+ */
+const SHELL_INTERPRETERS = new Set([
+    'sh', 'bash', 'zsh', 'dash', 'ksh', 'fish',
+    'cmd', 'cmd.exe', 'powershell', 'powershell.exe', 'pwsh', 'pwsh.exe',
+    'node', 'nodejs', 'python', 'python3', 'perl', 'ruby', 'php', 'deno', 'bun',
+    'wscript', 'cscript', 'mshta', 'rundll32', 'regsvr32', 'certutil', 'bitsadmin',
+]);
+/** 返回拒绝原因；null 表示通过命令级禁锢检查。 */
+export function shellConfinementViolation(command) {
+    const raw = String(command ?? '');
+    if (!raw.trim())
+        return 'empty-command';
+    // 1) 重定向 / 管道 / 串联 / 命令替换
+    if (/[<>|&;`]/.test(raw))
+        return 'shell-redirection-or-chaining';
+    if (/\$\(/.test(raw))
+        return 'shell-substitution';
+    // 2) 目录切换
+    if (/\b(cd|chdir|pushd|popd)\b/i.test(raw))
+        return 'shell-cd';
+    // 3) 父目录穿越（路径段形式，避免误伤 a..b 文件名）
+    if (/(^|[\s"'])\.\.([\\/]|$)/.test(raw))
+        return 'shell-parent-traversal';
+    // 4) 绝对路径（盘符 / 前导斜杠 / UNC / ~）
+    if (/[A-Za-z]:[\\/]/.test(raw))
+        return 'shell-absolute-path';
+    if (/(^|[\s"'])[\\/]{1,2}[^\s"']/.test(raw))
+        return 'shell-absolute-path';
+    if (/(^|[\s"'])~[\\/]/.test(raw))
+        return 'shell-home-path';
+    // 5) 环境变量展开（可能拼出密钥名或 jail 外路径）
+    if (/%[A-Za-z_][A-Za-z0-9_]*%/.test(raw))
+        return 'shell-env-expansion';
+    if (/\$\{?[A-Za-z_][A-Za-z0-9_]*\}?/.test(raw))
+        return 'shell-env-expansion';
+    // 6) 解释器作为命令词（任意代码执行）
+    const firstWord = raw.trim().split(/\s+/)[0].replace(/^["']|["']$/g, '').toLowerCase();
+    const base = firstWord.split(/[\\/]/).pop() ?? firstWord;
+    if (SHELL_INTERPRETERS.has(base))
+        return 'shell-interpreter:' + base;
+    // 7) git 危险子命令（含 -C / --git-dir / -c 变体）
+    if (/\bgit\b[^;&|]*\b(push|remote|config|credential|submodule)\b/i.test(raw))
+        return 'shell-git-write';
+    return null;
+}
+/** 危险 Shell 模式（最小黑名单；VM 网络/资源隔离仍是主防线）。 */
+export const DEFAULT_DENY_PATTERNS = [
+    /\bsudo\b/i,
+    /\bmkfs\b/i,
+    /\bdd\s+if=/i,
+    /\bshutdown\b/i,
+    /\breboot\b/i,
+    /\b(curl|wget)\b/i,
+    /\b(ssh|scp|nc|ncat|telnet)\b/i,
+    /\bchmod\s+777\b/i,
+    /\brm\s+-[a-z]*r[a-z]*f[a-z]*\s+\/(\s|$)/i,
+    /\bgit\s+push\b/i,
+    /\bgh\s+(auth|token)\b/i,
+    /\bpowershell(\.exe)?\b.*\s-(enc|e)\b/i,
+    /\b(base64\s+-d|frombase64string)\b.*\|\s*(sh|bash|powershell)/i,
+    // 解释器 -e/-c 任意代码执行：黑名单挡不住，直接拒绝（VM 内也应尽量少用）。
+    /\b(node|python|python3|perl|ruby|php)\b.*\s-(e|c)\b/i,
+];
+/** 只保留安全环境变量；任何 KEY/TOKEN/SECRET/PASSWORD/AUTH/DSH_* 一律剔除。 */
+export function sanitizeShellEnv(env = process.env) {
+    const safe = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (value === undefined)
+            continue;
+        if (!SHELL_ENV_ALLOWLIST.has(key))
+            continue;
+        safe[key] = value;
+    }
+    // 最小可运行集：没有 PATH 时用系统默认（exec 会在 shell 内置 PATH，但显式更稳）。
+    if (!safe.PATH && !safe.Path)
+        safe.PATH = process.platform === 'win32' ? 'C:\\Windows\\System32;C:\\Windows' : '/usr/local/bin:/usr/bin:/bin';
+    return safe;
+}
+/** 杀掉整棵进程树（Windows 用 taskkill /T；POSIX 用负 pid 信号）。 */
+export function killProcessTree(child, platform = process.platform) {
+    const pid = Number(child?.pid);
+    if (!Number.isInteger(pid) || pid <= 0)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        try {
+            if (platform === 'win32') {
+                const killer = spawn('taskkill', ['/pid', String(pid), '/T', '/F'], { windowsHide: true });
+                killer.on('close', () => resolve());
+                killer.on('error', () => resolve());
+            }
+            else {
+                try {
+                    process.kill(-pid, 'SIGKILL');
+                }
+                catch { /* already gone */ }
+                try {
+                    process.kill(pid, 'SIGKILL');
+                }
+                catch { /* already gone */ }
+                resolve();
+            }
+        }
+        catch {
+            resolve();
+        }
+    });
+}
+/**
+ * 在 workspace 内执行 Shell；超时/中止时杀死进程树并等待退出。
+ * 输出上限 2MB（超出 kill），返回值再截断到 16k 字符。
+ */
+export function runShell(command, options) {
+    return new Promise((resolve) => {
+        const child = spawn(command, {
+            cwd: options.cwd,
+            env: sanitizeShellEnv(options.env ?? process.env),
+            shell: true,
+            windowsHide: true,
+            detached: process.platform !== 'win32',
+        });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        let timedOut = false;
+        let aborted = false;
+        let size = 0;
+        let killTimer;
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (killTimer)
+                clearTimeout(killTimer);
+            options.signal.removeEventListener('abort', onAbort);
+            // close 表示 stdio 已关闭；只有超时/中止/输出爆量时才需补杀进程树。
+            // 不再对每次成功命令都调用 taskkill，也不等待一个可能永远不来的第二次 close。
+            resolve({ stdout, stderr, code, timedOut, aborted });
+        };
+        const killAndSettle = () => {
+            void killProcessTree(child);
+            // 某些孙进程持有管道时 close 可能迟到；给正常关闭一个短窗口后硬结算。
+            if (killTimer)
+                clearTimeout(killTimer);
+            killTimer = setTimeout(() => finish(null), 500);
+            killTimer.unref?.();
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killAndSettle();
+        }, Math.max(1, options.timeoutMs));
+        const onAbort = () => {
+            aborted = true;
+            killAndSettle();
+        };
+        options.signal.addEventListener('abort', onAbort, { once: true });
+        child.stdout?.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > 2 * 1024 * 1024) {
+                killAndSettle();
+                return;
+            }
+            if (stdout.length < MAX_SHELL_OUTPUT_CHARS * 2)
+                stdout += chunk.toString('utf8');
+        });
+        child.stderr?.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > 2 * 1024 * 1024) {
+                killAndSettle();
+                return;
+            }
+            if (stderr.length < MAX_SHELL_OUTPUT_CHARS * 2)
+                stderr += chunk.toString('utf8');
+        });
+        child.on('error', (error) => { stderr += `\n${error.message}`; void finish(null); });
+        child.on('close', (code) => { void finish(code); });
+    });
+}
+/** 解析 Mandate.scope 为写 jail 根；scope 是 threadId/非路径时退回 workspace。 */
+export function resolveMandateRoot(workspace, scope) {
+    const root = path.resolve(workspace);
+    const raw = String(scope ?? '').trim();
+    if (!raw)
+        return root;
+    // scope 首先是一张 Ticket 的逻辑边界（GitHub issue/飞书 thread），不是路径。
+    // 仅当配置明确给出已存在的仓库子目录时才收窄写 jail，绝不把飞书 ID 当成路径。
+    if (raw.includes('#') || raw.includes(':'))
+        return root;
+    const candidate = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(root, raw);
+    const rel = path.relative(root, candidate);
+    if (rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel)))
+        return candidate;
+    return root;
+}
+function isInside(root, candidate) {
+    const rel = path.relative(root, candidate);
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+async function realpathNearest(target) {
+    let current = target;
+    for (let i = 0; i < 32; i += 1) {
+        try {
+            return await fs.realpath(current);
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current)
+                return current;
+            current = parent;
+        }
+    }
+    return target;
+}
+export async function resolveInside(root, target) {
+    const text = String(target ?? '').trim();
+    if (!text || text.includes('\u0000'))
+        throw new Error('invalid-path');
+    const base = path.resolve(root);
+    const resolved = path.isAbsolute(text) ? path.resolve(text) : path.resolve(base, text);
+    if (!isInside(base, resolved))
+        throw new Error('path-outside-workspace');
+    const realBase = await realpathNearest(base);
+    const realTarget = await realpathNearest(resolved);
+    if (!isInside(realBase, realTarget))
+        throw new Error('path-outside-workspace');
+    return resolved;
+}
+function requireString(args, key) {
+    const value = args[key];
+    if (typeof value !== 'string')
+        throw new Error(`argument ${key} must be a string`);
+    return value;
+}
+function truncateOutput(text) {
+    if (text.length <= MAX_SHELL_OUTPUT_CHARS)
+        return text;
+    return text.slice(0, MAX_SHELL_OUTPUT_CHARS) + `\n…[输出截断，共 ${text.length} 字符]`;
+}
+function commandDenied(command, patterns) {
+    for (const pattern of patterns)
+        if (pattern.test(command))
+            return String(pattern);
+    return null;
+}
+/** 写入前检查敏感相对路径；在 workspace 与 mandateRoot 之间都检查。 */
+function deniedWritePath(workspace, target, denyPaths) {
+    const rel = path.relative(workspace, target).split(path.sep).join('/');
+    for (const denied of denyPaths) {
+        const normalized = denied.replace(/\\/g, '/').replace(/^\/+/, '');
+        if (normalized && (rel === normalized || rel.startsWith(normalized + '/')))
+            return normalized;
+    }
+    // v3.2.5 P2：.env 的所有变体（.env、.env.local、.env.production、.env.example…）一律拒绝写入，
+    // 避免仅靠枚举漏掉 .env.production 之类。
+    const baseName = rel.split('/').pop() ?? '';
+    if (/^\.env(\.|$)/i.test(baseName))
+        return '.env*';
+    return null;
+}
+function createPrTool(client) {
+    return {
+        name: 'create_pr',
+        description: '在允许的仓库创建一个 Pull Request（需要宿主注入 PR 客户端；默认不可用）',
+        parameters: {
+            type: 'object',
+            properties: {
+                title: { type: 'string' }, body: { type: 'string' },
+                branch: { type: 'string' }, base: { type: 'string' },
+            },
+            required: ['title', 'body'],
+        },
+        async execute(args) {
+            if (!client)
+                return '【系统拒绝】PR 后端未配置；请输出最终报告，由 Router/宿主完成回写。';
+            // v3.2.5 P2：分支/base 白名单校验——Worker 不得直接对默认分支开 PR，也不得使用非法分支名。
+            const PROTECTED_BASES = ['main', 'master', 'trunk', 'release', 'production', 'stable'];
+            const branch = typeof args.branch === 'string' ? args.branch.trim() : '';
+            const base = typeof args.base === 'string' && args.base.trim() ? args.base.trim() : undefined;
+            if (!branch)
+                return '【系统拒绝】create_pr 必须显式提供 branch（分支需由宿主/分身先推送）。';
+            if (!/^[A-Za-z0-9._/-]{1,120}$/.test(branch))
+                return '【系统拒绝】branch 含非法字符。';
+            if (branch.startsWith('-') || branch.includes('..') || branch.includes('//'))
+                return '【系统拒绝】branch 不合法。';
+            if (PROTECTED_BASES.includes(branch.toLowerCase()))
+                return '【系统拒绝】不能直接向受保护分支开 PR（branch=' + branch + '）。';
+            if (base && PROTECTED_BASES.includes(base.toLowerCase()) === false)
+                return '【系统拒绝】base 必须是受保护主干分支，当前 base=' + base + '。';
+            if (base && branch.toLowerCase() === base.toLowerCase())
+                return '【系统拒绝】branch 与 base 相同。';
+            try {
+                const url = await client.createPullRequest({
+                    title: requireString(args, 'title'),
+                    body: requireString(args, 'body'),
+                    branch,
+                    base,
+                });
+                return `PR created: ${url}`;
+            }
+            catch (error) {
+                return `创建 PR 失败: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        },
+    };
+}
+export function createSandboxTools(options) {
+    const workspace = path.resolve(options.workspace);
+    const denyPatterns = [...DEFAULT_DENY_PATTERNS, ...(options.denyPatterns ?? [])];
+    const denyWritePaths = [...DEFAULT_DENY_WRITE_PATHS, ...(options.denyWritePaths ?? [])];
+    const backgroundAfterMs = Math.max(20, Number(options.backgroundAfterMs ?? LONG_SYNC_COMMAND_THRESHOLD_MS) || LONG_SYNC_COMMAND_THRESHOLD_MS);
+    const shellJobs = new Map();
+    let shellJobSeq = 0;
+    const formatShellResult = (result, timeoutMs) => {
+        const stdout = truncateOutput(result.stdout);
+        const stderr = truncateOutput(result.stderr);
+        if (result.timedOut || result.aborted)
+            return `执行报错: 超时（>${timeoutMs}ms）或已中止；进程树已终止\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}`;
+        return `STDOUT:\n${stdout}\nSTDERR:\n${stderr}`;
+    };
+    const startShellJob = (command, context) => {
+        if (shellJobs.size >= 50) {
+            const oldestDone = [...shellJobs.values()].find((job) => job.status === 'done');
+            if (oldestDone) {
+                if (oldestDone.cleanup)
+                    clearTimeout(oldestDone.cleanup);
+                shellJobs.delete(oldestDone.id);
+            }
+            else
+                throw new Error('too-many-background-shell-jobs');
+        }
+        const id = `vm-job-${Date.now().toString(36)}-${(++shellJobSeq).toString(36)}`;
+        const job = { id, status: 'running', startedAt: Date.now(), timeoutMs: Math.max(1, context.timeoutMs) };
+        shellJobs.set(id, job);
+        void runShell(command, { cwd: workspace, timeoutMs: Math.max(1, context.timeoutMs), signal: context.signal })
+            .then((result) => {
+            job.result = result;
+            job.status = 'done';
+            job.cleanup = setTimeout(() => shellJobs.delete(id), 10 * 60_000);
+            job.cleanup.unref?.();
+        })
+            .catch((error) => {
+            job.result = { stdout: '', stderr: String(error instanceof Error ? error.message : error), code: null, timedOut: false, aborted: false };
+            job.status = 'done';
+        });
+        return job;
+    };
+    return [
+        {
+            name: 'fs_read_file',
+            description: '读取 workspace 内文件的 UTF-8 内容（最大 256KB）',
+            parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+            async execute(args) {
+                const file = await resolveInside(workspace, requireString(args, 'path'));
+                const stat = await fs.stat(file);
+                if (!stat.isFile())
+                    throw new Error('not-a-file');
+                if (stat.size > MAX_READ_BYTES)
+                    throw new Error('file-too-large');
+                return await fs.readFile(file, 'utf8');
+            },
+        },
+        {
+            name: 'fs_list_dir',
+            description: '列出 workspace 内目录条目（最多 200 项）',
+            parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+            async execute(args) {
+                const dir = await resolveInside(workspace, args.path === undefined ? '.' : requireString(args, 'path'));
+                const entries = await fs.readdir(dir, { withFileTypes: true });
+                return entries.slice(0, 200).map((entry) => `${entry.isDirectory() ? 'dir ' : 'file'} ${entry.name}`).join('\n') || '(empty)';
+            },
+        },
+        {
+            name: 'fs_write_file',
+            description: '写入文件（workspace 内且位于 Mandate.scope；拒绝 .git/.env 等敏感路径）',
+            parameters: { type: 'object', properties: { path: { type: 'string' }, content: { type: 'string' } }, required: ['path', 'content'] },
+            async execute(args, context) {
+                // v3.2.3：Mandate 每次从 context 取，避免构造闭包与本次 Ticket 不一致。
+                const mandateRoot = resolveMandateRoot(workspace, context.mandate.scope);
+                const target = await resolveInside(workspace, requireString(args, 'path'));
+                if (!isInside(mandateRoot, target))
+                    throw new Error('path-outside-mandate');
+                const denied = deniedWritePath(workspace, target, denyWritePaths);
+                if (denied)
+                    throw new Error(`sensitive-path-denied:${denied}`);
+                const content = requireString(args, 'content');
+                if (Buffer.byteLength(content, 'utf8') > MAX_WRITE_BYTES)
+                    throw new Error('content-too-large');
+                await fs.mkdir(path.dirname(target), { recursive: true });
+                const realParent = await realpathNearest(path.dirname(target));
+                if (!isInside(await realpathNearest(mandateRoot), realParent))
+                    throw new Error('path-outside-mandate');
+                await fs.writeFile(target, content, 'utf8');
+                return `written ${Buffer.byteLength(content, 'utf8')} bytes to ${path.relative(workspace, target)}`;
+            },
+        },
+        {
+            name: 'exec_shell_in_vm',
+            description: '在分身 workspace 内执行 Shell（需 Mandate.allowShell；脱敏环境、黑名单、进程树超时）',
+            parameters: { type: 'object', properties: { command: { type: 'string' } }, required: ['command'] },
+            async execute(args, context) {
+                // P0-2 fail-closed：没有隔离证明就不允许 Shell（黑名单不是安全边界）。
+                if (options.vmIsolation !== true) {
+                    return '【系统拒绝】Shell 仅在已证明隔离的 VM/容器内可用；当前运行态未提供隔离证明（DSH_MASTER_VM_ISOLATION=attested）。';
+                }
+                if (context.mandate.allowShell !== true)
+                    return '【系统拒绝】当前工单未授权执行 Shell 命令。';
+                const command = requireString(args, 'command').trim();
+                if (!command)
+                    throw new Error('command-required');
+                const denied = commandDenied(command, denyPatterns);
+                if (denied)
+                    return `【系统拒绝】命令命中安全黑名单（${denied}）。`;
+                // P0-2：命令级禁锢（重定向/管道/cd/../绝对路径/env 展开/解释器/git 写操作）。
+                const escaped = shellConfinementViolation(command);
+                if (escaped)
+                    return `【系统拒绝】命令试图逃出 workspace/Mandate jail（${escaped}）。`;
+                const job = startShellJob(command, context);
+                let timer;
+                try {
+                    return await Promise.race([
+                        (async () => {
+                            while (job.status === 'running')
+                                await new Promise((resolve) => setTimeout(resolve, 10));
+                            return formatShellResult(job.result, context.timeoutMs);
+                        })(),
+                        new Promise((resolve) => {
+                            timer = setTimeout(() => resolve(`后台任务 ${job.id} 已启动（超过 ${backgroundAfterMs}ms）；请调用 vm_job_result 查询，参数 {"jobId":"${job.id}"}。`), backgroundAfterMs);
+                            timer.unref?.();
+                        }),
+                    ]);
+                }
+                finally {
+                    if (timer)
+                        clearTimeout(timer);
+                }
+            },
+        },
+        {
+            name: 'vm_job_result',
+            description: '查询 exec_shell_in_vm 后台作业的终态与输出；参数 jobId',
+            parameters: { type: 'object', properties: { jobId: { type: 'string' } }, required: ['jobId'] },
+            async execute(args) {
+                const id = requireString(args, 'jobId');
+                const job = shellJobs.get(id);
+                if (!job)
+                    return `【系统拒绝】未知或已过期的后台任务: ${id}`;
+                if (job.status === 'running')
+                    return `{"jobId":"${id}","status":"running"}`;
+                return formatShellResult(job.result, job.timeoutMs);
+            },
+        },
+        createPrTool(options.prClient),
+    ];
+}
+export function createToolRegistry(tools) {
+    const byName = new Map(tools.map((tool) => [tool.name, tool]));
+    return {
+        schemas() {
+            return tools.map((tool) => ({ name: tool.name, description: tool.description, parameters: tool.parameters }));
+        },
+        async execute(call, context) {
+            const tool = byName.get(String(call?.name ?? ''));
+            if (!tool)
+                return `【系统拒绝】未知工具: ${String(call?.name ?? '')}`;
+            let args = {};
+            try {
+                const parsed = JSON.parse(String(call?.arguments ?? '{}'));
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+                    args = parsed;
+                else
+                    return '执行报错: 工具参数必须是 JSON object';
+            }
+            catch (error) {
+                return `执行报错: 参数 JSON 解析失败: ${error instanceof Error ? error.message : String(error)}`;
+            }
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), Math.max(1, context.timeoutMs));
+            const onAbort = () => controller.abort();
+            context.signal.addEventListener('abort', onAbort, { once: true });
+            try {
+                return await Promise.race([
+                    tool.execute(args, { ...context, signal: controller.signal }),
+                    new Promise((resolve) => {
+                        controller.signal.addEventListener('abort', () => resolve(`执行报错: 工具超时或被中止（>${context.timeoutMs}ms）`), { once: true });
+                    }),
+                ]);
+            }
+            catch (error) {
+                return `执行报错: ${error instanceof Error ? error.message : String(error)}`;
+            }
+            finally {
+                clearTimeout(timer);
+                context.signal.removeEventListener('abort', onAbort);
+            }
+        },
+    };
+}
+export function isPathInside(root, target) {
+    return isInside(path.resolve(root), path.resolve(target));
+}

package/dist-worker/types.js

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+/** 默认限制（可被 config/构造参数覆盖，但不可关闭硬上限）。 */
+export const DEFAULT_LIMITS = {
+    maxSteps: 15,
+    maxTokens: 50_000,
+    maxWallClockMs: 15 * 60_000,
+    llmTimeoutMs: 120_000,
+    toolTimeoutMs: 120_000,
+    maxToolCallsPerStep: 4,
+    maxIdenticalToolRepeats: 3,
+    maxToolResultChars: 8_000,
+    maxContextChars: 400_000,
+};

package/docs/ARCHITECTURE.md

@@ -0,0 +1,114 @@
+# dsh-Master 架构（3.2.8）
+
+> 当前实现基线为 3.2.8；本文保留设计演进记录。最新实机证据与剩余限制见 `REVIEW-v3.2.7.md`。
+
+## 1. 为什么是“并行主插件”
+
+瓮城 dsh-Fang 负责**环境**：镜像（母体）、配置与调度（原身/元宝运行态）、隔离生产（分身）。
+房主 dsh-Master 负责**Agent 组织**：主动响应（SuperAgent Router/Worker）、成本（HarnessMM）、
+组织协同（PM/PJM）。
+
+两者是并列的 DSH bundle，而不是父子插件：
+
+- 各自独立的 `package.json`、`cordis.patch.yml`、版本与发布节奏；
+- 房主 patch 只 `insert` 自己的行，**不覆盖、不修改** fang 的任何行；
+- 协作只走 DSH 服务键（下方契约），房主不 import fang 源码，也不读取 fang profile；
+- 任一协作服务缺失时，房主子插件返回结构化错误（fail-closed），绝不在房主进程本地执行。
+
+## 2. 运行时拓扑（v3.2.1：Router / Worker 双层）
+
+```text
+外部事件（GitHub / 飞书）
+   │ 验签 + 归一化（不可信输入）
+   ▼
+┌──────────────────────────────┐
+│ Router（essence / 原身）      │  评估 → Ticket + Mandate → 派发
+│  master-superagent-router     │  trustMode: off / observe / auto
+│  不执行代码、不跑命令          │  Ticket 持久化（可选 dataDir）
+└──────────────┬───────────────┘
+               │ fangForker.spawn({ env: ticket })
+               ▼
+┌──────────────────────────────┐
+│ Worker（fork / 分身 VM）      │  每 Ticket 一个隔离环境
+│  master-superagent-worker     │  worker/agent-loop.ts：
+│  + worker preset (TS)         │  多轮工具调用 / 熔断 / 安全工具 / 审计快照
+└──────────────────────────────┘
+
+旁路（后续版本）：
+  cost-optimizer  → fork：HarnessMM observe 层（3.3.0）
+  dual-manager    → mother/essence：PM + PJM（3.4.0）
+```
+
+### 角色矩阵（代码强制，见 `src/kernel.mjs ROLE_MATRIX`）
+
+| 行 | mother | essence（原身/元宝运行态） | fork（分身） |
+|---|---|---|---|
+| `master-core` | ✅ | ✅ | ✅ |
+| `master-superagent-router` | ❌ | ✅ | ❌ |
+| `master-superagent-worker` | ❌ | ❌ | ✅ |
+| `master-superagent-loop` | ❌ | ❌ | ✅ |
+| `master-cost-optimizer` | ❌ | ❌ | ✅ |
+| `master-dual-manager` | ✅ | ✅ | ❌ |
+
+- Router 是纯控制面（评估/建票/派发），不执行任何代码改动，因此可以常驻原身；
+- Worker 是研究原型，**只在 fork**，用物理隔离兜底其不稳定性；
+- 母体（mother）不接纳任何 SuperAgent 行；
+- 3.2.0 的“SuperAgent 整体仅 fork”在 3.2.1 被 Router/Worker 拆分取代，底线是
+  “原型 Worker 绝不进入母体/元主”（见 `docs/SECURITY.md`）。
+
+## 3. 与瓮城的服务契约
+
+房主只依赖以下**服务键**（字符串来自 `dsh-fang >= 3.1.14` kernel SERVICE）：
+
+| 键 | fang 服务 | 用途 | 缺失时行为 |
+|---|---|---|---|
+| `fangForker` | `fangForker` | `spawn({homeDir,cliPath,profile,env})` 派生 Worker 分身 | Router auto 返回 `dispatch-unavailable`；不本地执行 |
+| `fangDecisionCenter` | `fangDecisionCenter` | PM 歧义澄清（`create`） | `pm.askUser` 返回 `fang-decision-center-unavailable` |
+| `fangSessionCatalog` | `fangSessionCatalog` | 会话归属（3.2.x） | 状态页显示 unavailable |
+| `fang` | `fang`（orchestrator） | 任务/状态视图（3.2.x） | 状态页显示 unavailable |
+
+契约基线：`FANG_CONTRACT_MIN = '3.1.14'`。
+
+> 部署现实：3.1.14 的 `fangForker` 只在母体激活。Router 在 essence 内派发需要
+> 瓮城提供跨进程 DerivedManager 桥（3.2.2）；在桥落地前 Router 的
+> `dispatch.available=false`，auto 模式返回 unavailable——这是 fail-closed。
+
+## 4. 插件行与 bundle
+
+`cordis.patch.yml` 只做一次 insert（6 行）：
+
+```yaml
+- insert:
+    - master-core
+    - master-superagent-router
+    - master-superagent-worker
+    - master-superagent-loop
+    - master-cost-optimizer
+    - master-dual-manager
+```
+
+子插件 `inject = ['dshMaster']` 等待 core 的 `dshMaster` 服务；core 不在时子插件不激活。
+
+## 5. 控制面与 UI
+
+- `master-core` 提供 `dshMaster` 服务：
+  - `status()`：角色、版本、子插件矩阵、与瓮城服务可用性；
+  - `health()`：缺协作服务时给出可读 warnings；
+  - `registerSubplugin()`：子插件注册能力，重复 id 直接抛错（fail loud）。
+- 只读路由：
+  - `/dsh-master/api/status`（核心状态）
+  - `/dsh-master/api/superagent/status`（Router 状态）
+  - `POST /dsh-master/api/superagent/github`、`POST /dsh-master/api/superagent/feishu`（Webhook）
+- Web Client：`sidebar.footer.action`（id `dsh-master-home`，label「房主」）打开只读状态抽屉；
+  不写业务状态，不接管宿主根节点。
+
+## 6. 3.2.3-dev 的边界
+
+- Worker preset 已 tsc 构建到 `dist-worker/` 并接入 bundle 行（fork only，有 Ticket 自动跑）；
+- Router 两种派发：本地 `fangForker.spawn`（母体/测试）或 HTTP 母体桥
+  `POST /dsh-master/api/bridge/spawn`（Bearer bridgeToken，仅透传 DSH_MASTER_* env）；
+- Worker→Router 实时事件：per-ticket token POST `/dsh-master/api/superagent/worker-events`，
+  Router 落库并推进 Ticket 状态；done 触发 webhook/GitHub 回写（默认关闭）；
+- 前端 SSE/WS、Worker 并发/配额看护、PR 创建仍待 3.2.4+；
+- 安全审计 P0/P1 已加固（env 脱敏、进程树 kill、Mandate 一致性、secret 脱敏、token 估算）；
+- 不安装、不发布；等审核。