ysagc-agent 0.9.5 → 0.9.14

package/dist/tools.js

@@ -38,14 +38,23 @@ exports.walkTree = walkTree;
 exports.globToRegex = globToRegex;
 exports.preExecute = preExecute;
 exports.postExecute = postExecute;
+exports.listMcpTools = listMcpTools;
+exports.mcpFailuresFor = mcpFailuresFor;
+exports.shutdownMcp = shutdownMcp;
 exports.createToolRegistry = createToolRegistry;
 const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const childProcess = __importStar(require("node:child_process"));
 const path_utils_1 = require("./path-utils");
 const security_1 = require("./security");
 const skills_1 = require("./skills");
 const executor_1 = require("./executor");
+const screenshot_1 = require("./screenshot");
+const browser_1 = require("./browser");
+const memory_1 = require("./memory");
+const hooks_1 = require("./hooks");
+const mcp_1 = require("./mcp");
 /** Thrown when a tool invocation is invalid or unsafe. */
 class ToolError extends Error {
     constructor(code, message) {
@@ -76,7 +85,11 @@ function optionalString(args, key, fallback) {
     return v;
 }
 function optionalInt(args, key, fallback, opts = {}) {
-    const v = args[key];
+    // 兼容平台下发的同义字段：平台工具 schema 用 timeoutMs，本机历史配置用 timeout
+    let v = args[key];
+    if ((v === undefined || v === null) && key === 'timeout' && args.timeoutMs !== undefined) {
+        v = args.timeoutMs;
+    }
     if (v === undefined || v === null)
         return fallback;
     const n = typeof v === 'number' ? v : Number(v);
@@ -142,6 +155,64 @@ function readUpTo(target, length, offset = 0) {
         fs.closeSync(fd);
     }
 }
+/**
+ * 备份目录：备份放在授权根的 `.ysagc/backups/` 下，**保持原相对路径**，而不是写在文件旁边。
+ *
+ * 为什么改：原来写 `<name>.bak`（和源文件同目录），等于往用户的项目里塞文件 ——
+ * 实测用户的 Vue 项目根目录出现 `README.md.bak`、`report.html.bak`，
+ * 一不小心就被提交进 git。平台虽然有「本次改动 + 一键还原」能回滚，
+ * 但备份本身还是该放在一个明显属于工具、不会被误提交的地方。
+ */
+function backupPathFor(root, target) {
+    const rel = path.relative(root, target);
+    const safe = rel.startsWith('..') || path.isAbsolute(rel) ? path.basename(target) : rel;
+    return path.join(root, '.ysagc', 'backups', `${safe}.bak`);
+}
+/**
+ * 原子写入：先写同目录临时文件并 fsync，再 rename 覆盖目标。
+ * rename 在同一文件系统上是原子操作，因此「目标文件要么是旧内容、要么是新内容」，
+ * 不会出现写一半的破损文件（进程被杀 / 断电 / 磁盘写满都安全）。
+ * 目标原本存在时先留一份备份到 .ysagc/backups/（仅保留最近一次），便于误改后恢复。
+ */
+function atomicWrite(target, data, opts = {}) {
+    const dir = path.dirname(target);
+    fs.mkdirSync(dir, { recursive: true });
+    const tmp = path.join(dir, `.${path.basename(target)}.${process.pid}.${Date.now().toString(36)}.tmp`);
+    let fd = null;
+    try {
+        fd = fs.openSync(tmp, 'w', opts.mode ?? 0o644);
+        fs.writeFileSync(fd, data);
+        try {
+            fs.fsyncSync(fd);
+        }
+        catch { /* 某些文件系统不支持，忽略 */ }
+        fs.closeSync(fd);
+        fd = null;
+        // 覆盖已有文件前留一份备份（只在目标确实存在且不是空文件时）
+        try {
+            if (fs.existsSync(target) && fs.statSync(target).size > 0 && opts.root) {
+                const bak = backupPathFor(opts.root, target);
+                fs.mkdirSync(path.dirname(bak), { recursive: true });
+                fs.copyFileSync(target, bak);
+            }
+        }
+        catch { /* 备份失败不影响主流程 */ }
+        fs.renameSync(tmp, target);
+    }
+    catch (err) {
+        try {
+            if (fd !== null)
+                fs.closeSync(fd);
+        }
+        catch { /* ignore */ }
+        try {
+            if (fs.existsSync(tmp))
+                fs.unlinkSync(tmp);
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
+}
 function rel(root, target) {
     return path.relative(root, target).replace(/\\/g, '/');
 }
@@ -294,6 +365,12 @@ const WRITE_OR_COMMAND_TOOLS = new Set([
     'mv',
     'cp',
     'delete_file',
+    // 截图会往工作区里写文件，所以同样算写操作：只读模式下必须被拒
+    'screenshot',
+    // 浏览器操作会驱动真实页面（点按 / 输入 / 提交表单），同样按写操作对待
+    'browser',
+    // 写项目记忆文件（.ysagc/memory.md）
+    'remember',
 ]);
 /** Reconstruct the shell command a command-tool intends to run, if any. */
 function commandForTool(tool, args) {
@@ -325,8 +402,35 @@ function pathArgsForTool(tool, args) {
     }
     return out;
 }
-/** Default preset used when the caller did not specify one on the context. */
-const DEFAULT_PRESET = 'workspace-write';
+/**
+ * 读取类工具的路径解析：允许落在**主授权根**或任一**只读参考根**内。
+ *
+ * 与 safeResolve 的区别只有一点：多了 readRoots。写入类工具一律继续用
+ * safeResolve（只看主根），所以参考目录天然是只读的——这是这个功能的安全边界。
+ * 相对路径仍按主根解析，参考目录里的文件用绝对路径访问。
+ */
+function resolveReadable(ctx, p) {
+    const primary = (0, path_utils_1.canonicalize)(ctx.root);
+    const raw = String(p ?? '').trim();
+    if (!raw)
+        throw new path_utils_1.PathError('ERR_EMPTY_PATH', 'Path is empty');
+    const abs = path.isAbsolute(raw) ? raw : path.resolve(primary, raw);
+    const cand = (0, path_utils_1.canonicalize)(abs);
+    if ((0, path_utils_1.isWithinRoot)(primary, cand, { allowEqual: true }))
+        return cand;
+    for (const r of ctx.readRoots || []) {
+        try {
+            const rr = (0, path_utils_1.canonicalize)(r);
+            if ((0, path_utils_1.isWithinRoot)(rr, cand, { allowEqual: true }))
+                return cand;
+        }
+        catch {
+            /* 无效的参考根（不存在/无权限）直接忽略 */
+        }
+    }
+    throw new path_utils_1.PathError('ERR_OUTSIDE_ROOT', `Path is outside the authorised root: ${p} (root: ${primary})`);
+}
+/** Default preset used when the caller did not specify one on the context. */ const DEFAULT_PRESET = 'workspace-write';
 /** Whether the active preset permits a danger-flagged command without an
  * approval prompt. Only the most-permissive mode allows non-critical danger
  * commands; every other mode blocks them at the gate. */
@@ -347,7 +451,9 @@ function preExecute(ctx, tool, args) {
     const preset = ctx.permissionPreset ?? DEFAULT_PRESET;
     // 1) Permission preset: read-only denies anything that writes or executes.
     if (preset === 'read-only') {
-        if (WRITE_OR_COMMAND_TOOLS.has(tool)) {
+        // MCP 工具对我们是黑盒：无法判断它到底写不写文件，所以保守地按写操作拦。
+        // 否则「只读模式」会变成一个能通过任意 MCP server 写盘的洞。
+        if (WRITE_OR_COMMAND_TOOLS.has(tool) || tool.startsWith('mcp__')) {
             return {
                 ok: false,
                 error: `Tool "${tool}" is blocked in read-only mode (preset: read-only).`,
@@ -382,11 +488,20 @@ function preExecute(ctx, tool, args) {
         }
     }
     // 3) Canonicalise + sensitive-path check for every path argument.
+    // 读取类工具允许落在「只读参考根」内；写入类工具一律只认主授权根——
+    // 参考目录因此天然只读，这是「让 AI 参考别的项目」时的安全边界。
+    const isWriteTool = WRITE_OR_COMMAND_TOOLS.has(tool);
     let realRoot;
     for (const p of pathArgsForTool(tool, args)) {
         try {
-            realRoot = realRoot ?? (0, path_utils_1.canonicalize)(ctx.root);
-            const target = (0, path_utils_1.safeResolve)(ctx.root, p, realRoot, { allowEqual: true });
+            let target;
+            if (isWriteTool) {
+                realRoot = realRoot ?? (0, path_utils_1.canonicalize)(ctx.root);
+                target = (0, path_utils_1.safeResolve)(ctx.root, p, realRoot, { allowEqual: true });
+            }
+            else {
+                target = resolveReadable(ctx, p);
+            }
             if ((0, security_1.isSensitivePath)(target)) {
                 return {
                     ok: false,
@@ -442,7 +557,7 @@ const listDir = async (ctx, args) => {
     const p = optionalString(args, 'path', '.') ?? '.';
     const depth = optionalInt(args, 'depth', 1, { min: 0, max: 10 });
     const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
-    const target = (0, path_utils_1.safeResolve)(ctx.root, p, realRoot, { allowEqual: true });
+    const target = resolveReadable(ctx, p);
     assertNotSensitive(target);
     let stat;
     try {
@@ -500,7 +615,7 @@ const readFile = async (ctx, args, signal) => {
     const hasLength = args.length !== undefined && args.length !== null;
     const length = optionalInt(args, hasLength ? 'length' : 'maxBytes', ctx.maxBytes, { min: 1, max: MAX_WRITE_BYTES });
     const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
-    const target = (0, path_utils_1.safeResolve)(ctx.root, targetStr, realRoot);
+    const target = resolveReadable(ctx, targetStr);
     assertNotSensitive(target);
     let stat;
     try {
@@ -552,13 +667,59 @@ const writeFile = async (ctx, args, signal) => {
     if (totalBytes > MAX_WRITE_BYTES) {
         throw new ToolError('TOO_LARGE', `Content exceeds ${MAX_WRITE_BYTES} bytes.`);
     }
-    fs.mkdirSync(path.dirname(target), { recursive: true });
-    fs.writeFileSync(target, content, { mode });
+    atomicWrite(target, content, { mode, root: ctx.root });
     return {
         ok: true,
         result: { path: rel(realRoot, target), bytesWritten: totalBytes, mode },
     };
 };
+/**
+ * 换行符归一化：Windows 上仓库里的文件普遍是 CRLF，而模型发过来的 oldText 是 LF。
+ *
+ * 实测踩到（用户报障的整条任务就是卡在这里）：`admin/server/index.ts` 是 CRLF 文件，
+ * 模型给的多行 oldText 用的是 `\n`，逐字面比较必然 "oldText was not found in the file."，
+ * 于是模型反复重试、最后放弃并给了用户一个错误的结论（说工作区路径不对）。
+ * 单行编辑不受影响（没有换行符），所以这个 bug 只在多行编辑上暴露 —— 更难被发现。
+ *
+ * 规则：**匹配时统一按 LF 比**，**写回时还原文件原本的换行风格**（不让 git 出现整文件 diff）。
+ */
+function detectEol(text) {
+    const crlf = (text.match(/\r\n/g) || []).length;
+    const lf = (text.match(/(?<!\r)\n/g) || []).length;
+    return crlf > lf ? '\r\n' : '\n';
+}
+function toLf(text) {
+    return text.replace(/\r\n/g, '\n');
+}
+function applyEol(text, eol) {
+    return eol === '\r\n' ? text.replace(/\n/g, '\r\n') : text;
+}
+/** 读文件：返回「LF 归一化后的正文」与「该文件原本的换行符」 */
+function readTextFile(target) {
+    const buf = fs.readFileSync(target);
+    if (!isUtf8(buf))
+        throw new ToolError('BINARY_FILE', 'only UTF-8 text files are supported.');
+    const raw = buf.toString('utf8');
+    return { text: toLf(raw), eol: detectEol(raw) };
+}
+/**
+ * 匹配失败时给模型**可操作**的信息，而不是干巴巴一句 not found。
+ * 做法：拿 oldText 的第一行去文件里找，找到就把那附近几行回给它 —— 模型据此就能
+ * 把 oldText 改对，而不是靠猜（实测它猜两轮就放弃了）。
+ */
+function noMatchHint(text, needle) {
+    const firstLine = needle.split('\n').map((l) => l.trim()).find((l) => l.length >= 8) || '';
+    const lines = text.split('\n');
+    const idx = firstLine ? lines.findIndex((l) => l.includes(firstLine)) : -1;
+    const head = 'oldText was not found in the file.';
+    if (idx < 0) {
+        return head + '（提示：oldText 必须与文件内容**逐字一致**，含缩进与标点；建议先用 read_file 或 str_replace_editor view 读一次再改）';
+    }
+    const from = Math.max(0, idx - 2);
+    const to = Math.min(lines.length, idx + 3);
+    const snippet = lines.slice(from, to).map((l, i) => `${from + i + 1}| ${l}`).join('\n');
+    return `${head}\n文件里最接近的位置在第 ${idx + 1} 行附近，实际内容如下（行号| 内容）：\n${snippet}\n请按上面的真实内容修正 oldText 后重试。`;
+}
 const editFile = async (ctx, args, signal) => {
     abortIfRequested(signal);
     const targetStr = requireString(args, 'path');
@@ -578,16 +739,15 @@ const editFile = async (ctx, args, signal) => {
     if (stat.isDirectory()) {
         throw new ToolError('IS_DIR', `Path is a directory, not a file: ${targetStr}`);
     }
-    const buf = fs.readFileSync(target);
-    if (!isUtf8(buf)) {
-        throw new ToolError('BINARY_FILE', 'edit_file only supports UTF-8 text files.');
-    }
-    const text = buf.toString('utf8');
-    const count = text.split(oldText).length - 1;
+    // 统一按 LF 匹配（CRLF 文件 + 模型给的 LF oldText 也能命中），写回时还原原文件的换行风格
+    const { text, eol } = readTextFile(target);
+    const needle = toLf(oldText);
+    const count = text.split(needle).length - 1;
     if (count === 0) {
-        throw new ToolError('NO_MATCH', 'oldText was not found in the file.');
+        throw new ToolError('NO_MATCH', noMatchHint(text, needle));
     }
-    fs.writeFileSync(target, text.split(oldText).join(newText), 'utf8');
+    const updated = text.split(needle).join(toLf(newText));
+    atomicWrite(target, applyEol(updated, eol), { root: ctx.root });
     return { ok: true, result: { path: rel(realRoot, target), replacements: count } };
 };
 const runCommandTool = async (ctx, args, signal, opts) => {
@@ -596,6 +756,21 @@ const runCommandTool = async (ctx, args, signal, opts) => {
     const timeout = optionalInt(args, 'timeout', ctx.timeoutMs, { min: 1 });
     const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
     const cwd = (0, path_utils_1.safeResolve)(ctx.root, cwdArg, realRoot, { allowEqual: true });
+    // 工作目录不存在时先说清楚。
+    // 实测踩过：用户把工作区目录删掉/改名之后，所有命令只回一个 `exit=127` 加空输出 ——
+    // 模型看不懂，用户更看不懂（127 是 shell 的「命令不存在」，这里的真实原因是
+    // 「进不去这个目录」）。宁可在这里明确拦住，也不要让它变成一串看不懂的退出码。
+    if (!fs.existsSync(cwd)) {
+        return {
+            ok: false,
+            error: `工作目录不存在：${cwd}。`
+                + `（工作区根目录 ${realRoot} 可能已被删除或改名）`
+                + '请在网页上重新选择/新建工作区后再试。',
+        };
+    }
+    if (!fs.statSync(cwd).isDirectory()) {
+        return { ok: false, error: `工作目录不是一个目录：${cwd}` };
+    }
     const assessment = (0, security_1.isDangerCommand)(cmd);
     if (assessment.danger && !permitsDangerCommand(ctx.permissionPreset, assessment.severity) && !opts?.preApproved) {
         return {
@@ -613,6 +788,7 @@ const runCommandTool = async (ctx, args, signal, opts) => {
             timeoutMs: timeout,
             maxBytes: ctx.maxBytes,
             signal,
+            ...(opts?.onOutput ? { onOutput: opts.onOutput } : {}),
         });
         return {
             ok: true,
@@ -754,7 +930,7 @@ const generate = async (ctx, args, signal) => {
         fs.mkdirSync(path.dirname(dest), { recursive: true });
         const content = tpl.content.replace(/\{NAME\}/g, name);
         const bytes = Buffer.byteLength(content);
-        fs.writeFileSync(dest, content, 'utf8');
+        atomicWrite(dest, content, { root: ctx.root });
         written.push({ path: rel(realRoot, dest), bytes });
     }
     return {
@@ -779,7 +955,7 @@ const search = async (ctx, args, signal) => {
         throw new ToolError('INVALID_REGEX', `Invalid search pattern: ${patternStr}`);
     }
     const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
-    const target = (0, path_utils_1.safeResolve)(ctx.root, targetStr, realRoot, { allowEqual: true });
+    const target = resolveReadable(ctx, targetStr);
     assertNotSensitive(target);
     let st;
     try {
@@ -883,7 +1059,7 @@ const glob = async (ctx, args, signal) => {
     const baseStr = optionalString(args, 'path', '.') ?? '.';
     const maxResults = optionalInt(args, 'maxResults', 1000, { min: 1, max: 5000 });
     const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
-    const base = (0, path_utils_1.safeResolve)(ctx.root, baseStr, realRoot, { allowEqual: true });
+    const base = resolveReadable(ctx, baseStr);
     assertNotSensitive(base);
     let st;
     try {
@@ -923,7 +1099,7 @@ const tree = async (ctx, args, signal) => {
     const maxEntries = optionalInt(args, 'maxEntries', 500, { min: 1, max: 5000 });
     const includeHidden = optionalBool(args, 'showHidden', false);
     const realRoot = (0, path_utils_1.canonicalize)(ctx.root);
-    const target = (0, path_utils_1.safeResolve)(ctx.root, targetStr, realRoot, { allowEqual: true });
+    const target = resolveReadable(ctx, targetStr);
     assertNotSensitive(target);
     let st;
     try {
@@ -1035,23 +1211,9 @@ const strReplaceEditor = async (ctx, args, signal) => {
             throw new ToolError('ROOT_PATH', 'The authorisation root itself cannot be edited.');
         }
     };
-    const ensureFile = () => {
-        let st;
-        try {
-            st = fs.statSync(target);
-        }
-        catch {
-            throw new ToolError('NOT_FOUND', `Path does not exist: ${pathStr}`);
-        }
-        if (st.isDirectory()) {
-            throw new ToolError('IS_DIR', `Path is a directory, not a file: ${pathStr}`);
-        }
-        const buf = fs.readFileSync(target);
-        if (!isUtf8(buf)) {
-            throw new ToolError('BINARY_FILE', 'str_replace_editor only supports UTF-8 text files.');
-        }
-        return buf.toString('utf8');
-    };
+    // 注：读文件的统一入口改成了 readTextFile()（它顺带做换行归一化并返回原文件 EOL）。
+    // 这里原先的 ensureFile() 已经没人用了 —— 它返回的是带 \r 的原始正文，
+    // 正是「CRLF 文件上多行匹配必然失败」的根源，留着容易再被误用，所以删掉。
     switch (command) {
         case 'create': {
             assertNotRootTarget();
@@ -1061,11 +1223,13 @@ const strReplaceEditor = async (ctx, args, signal) => {
                 throw new ToolError('EXISTS', `File already exists: ${pathStr} (pass allowOverwrite:true to replace it).`);
             }
             fs.mkdirSync(path.dirname(target), { recursive: true });
-            fs.writeFileSync(target, fileText, 'utf8');
+            atomicWrite(target, fileText, { root: ctx.root });
             return { ok: true, result: { path: rel(realRoot, target), bytesWritten: Buffer.byteLength(fileText) } };
         }
         case 'view': {
-            const text = ensureFile();
+            // 用 readTextFile：CRLF 文件的行尾 \r 会被归一化掉，否则 view 出来每行都带一个不可见字符，
+            // 模型照着它拼 old_str 就更不可能匹配上了。
+            const { text } = readTextFile(target);
             const allLines = text === '' ? [] : text.split('\n');
             const range = readLineRange(args);
             const selected = range ? allLines.slice(range[0] - 1, range[1]) : allLines;
@@ -1085,36 +1249,36 @@ const strReplaceEditor = async (ctx, args, signal) => {
         }
         case 'str_replace': {
             assertNotRootTarget();
-            const text = ensureFile();
-            const oldStr = requireString(args, 'old_str');
-            const newStr = typeof args.new_str === 'string' ? args.new_str : '';
+            const { text, eol } = readTextFile(target);
+            const oldStr = toLf(requireString(args, 'old_str'));
+            const newStr = toLf(typeof args.new_str === 'string' ? args.new_str : '');
             const replaceAll = optionalBool(args, 'replace_all', false);
             const count = text.split(oldStr).length - 1;
             if (count === 0) {
-                throw new ToolError('NO_MATCH', 'old_str was not found in the file.');
+                throw new ToolError('NO_MATCH', noMatchHint(text, oldStr));
             }
             if (!replaceAll && count !== 1) {
                 throw new ToolError('MULTIPLE_MATCHES', `old_str matched ${count} times; pass replace_all:true to replace all of them.`);
             }
             const updated = replaceAll ? text.split(oldStr).join(newStr) : text.replace(oldStr, newStr);
-            fs.writeFileSync(target, updated, 'utf8');
+            atomicWrite(target, applyEol(updated, eol), { root: ctx.root });
             return { ok: true, result: { path: rel(realRoot, target), replacements: count } };
         }
         case 'insert': {
             assertNotRootTarget();
-            const text = ensureFile();
-            const newStr = requireString(args, 'new_str');
+            const { text, eol } = readTextFile(target);
+            const newStr = toLf(requireString(args, 'new_str'));
             const insertLine = optionalInt(args, 'insert_line', 0, { min: 0 });
             const lines = text === '' ? [] : text.split('\n');
             // insert_line is 1-based; 0 or out-of-range appends.
             const pos = insertLine >= 1 && insertLine <= lines.length + 1 ? insertLine - 1 : lines.length;
             lines.splice(pos, 0, newStr);
-            fs.writeFileSync(target, lines.join('\n'), 'utf8');
+            atomicWrite(target, applyEol(lines.join('\n'), eol), { root: ctx.root });
             return { ok: true, result: { path: rel(realRoot, target), line: pos + 1, inserted: newStr } };
         }
         case 'delete': {
             assertNotRootTarget();
-            const text = ensureFile();
+            const { text, eol } = readTextFile(target);
             const range = readLineRange(args);
             if (!range) {
                 throw new ToolError('INVALID_ARG', '"delete" requires a "view_range" [start, end].');
@@ -1126,7 +1290,7 @@ const strReplaceEditor = async (ctx, args, signal) => {
             }
             const removed = lines.slice(start - 1, Math.min(end, lines.length));
             lines.splice(start - 1, Math.min(end, lines.length) - (start - 1));
-            fs.writeFileSync(target, lines.join('\n'), 'utf8');
+            atomicWrite(target, applyEol(lines.join('\n'), eol), { root: ctx.root });
             return { ok: true, result: { path: rel(realRoot, target), lineStart: start, lineEnd: Math.min(end, start + removed.length - 1), removed: removed.length } };
         }
         default:
@@ -1404,13 +1568,18 @@ const fsDrives = async (_ctx) => {
  * - 仍拦截敏感/凭证路径（.env、id_rsa、C:\Windows\System32 等）；
  * - 只返回元数据（名称/类型/大小/时间），不读文件内容。
  */
-const fsBrowse = async (_ctx, args) => {
+const fsBrowse = async (ctx, args) => {
     const p = String(args.path || '').trim();
     if (!p)
         return { ok: true, result: { drives: listDriveRoots(), prompt: 'drives' } };
     let abs;
     try {
-        abs = (0, path_utils_1.canonicalize)(p);
+        // 相对路径必须按【授权根】解析，与 read_file/glob 等所有其它工具保持一致。
+        // 历史实现直接 canonicalize(p)（= 进程 cwd），有两个真问题：
+        //  1) 平台传相对路径（如 'gen/music'）时会去找 <agent cwd>/gen/music，用户看到「路径不存在」；
+        //  2) 前置校验按授权根放行，工具本体却按 cwd 读——两边解析的不是同一个路径，
+        //     相对路径可以越出授权根去列别的目录。
+        abs = resolveReadable(ctx, p);
     }
     catch (e) {
         return { ok: false, error: `无效路径: ${e?.message || e}` };
@@ -1450,10 +1619,10 @@ const fsBrowse = async (_ctx, args) => {
     return { ok: true, result: { path: abs, entries } };
 };
 /** 用系统原生"选择文件夹"对话框返回绝对路径（Windows/Linux/macOS）。取消或不可用返回 null。 */
-function execFileP(cmd, args, timeoutMs) {
+function execFileP(cmd, args, timeoutMs, windowsHide = true) {
     return new Promise((resolve) => {
         try {
-            childProcess.execFile(cmd, args, { timeout: timeoutMs, windowsHide: true, maxBuffer: 1024 * 1024 }, (err, stdout, stderr) => {
+            childProcess.execFile(cmd, args, { timeout: timeoutMs, windowsHide, maxBuffer: 1024 * 1024 }, (err, stdout, stderr) => {
                 resolve(String(stdout || '').trim());
             });
         }
@@ -1462,22 +1631,57 @@ function execFileP(cmd, args, timeoutMs) {
         }
     });
 }
+async function pickFolderViaWindowsDialog() {
+    /**
+     * 用 WSH（wscript.exe 是 GUI 子系统，不会闪现控制台窗口）+ Shell.Application
+     * 弹出资源管理器风格的「选择文件夹」对话框，选中的路径写入临时文件后返回。
+     *
+     * 注意：子进程不能带 windowsHide:true（或其它隐藏控制台的方式）启动——实测在该
+     * 启动方式下模态对话框（WinForms FolderBrowserDialog / Shell BrowseForFolder）
+     * 都不会显示窗口，ShowDialog 一直挂到超时，用户毫无感知。wscript 无控制台，
+     * 用默认启动方式即可正常显示对话框。
+     */
+    const base = path.join(os.tmpdir(), `ysagc-pick-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+    const vbsPath = `${base}.vbs`;
+    const outPath = `${base}.txt`;
+    const vbs = [
+        'Set sh = CreateObject("Shell.Application")',
+        'Set f = sh.BrowseForFolder(0, "选择工作区目录", 65, "")',
+        'If Not f Is Nothing Then',
+        '  Set fs = CreateObject("Scripting.FileSystemObject")',
+        // 65 = BIF_NEWDIALOGSTYLE(64) + BIF_RETURNONLYFSDIRS(1)：现代风格 + 只选文件系统目录
+        `  Set out = fs.OpenTextFile("${outPath.replace(/"/g, '""')}", 2, True)`,
+        '  out.WriteLine f.Items().Item().Path',
+        '  out.Close',
+        'End If',
+    ].join('\r\n');
+    try {
+        // WSH 按系统 ANSI 代码页解析 .vbs，中文标题必须以 UTF-16LE + BOM 写入
+        fs.writeFileSync(vbsPath, Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(vbs, 'utf16le')]));
+        // 3 分钟内选完（含折叠目录的时间）；后端等待 200s，略大于此值
+        await execFileP('wscript.exe', ['//Nologo', vbsPath], 180000, false);
+        if (!fs.existsSync(outPath))
+            return null; // 用户取消
+        return fs.readFileSync(outPath, 'utf8').trim() || null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        try {
+            fs.unlinkSync(vbsPath);
+        }
+        catch { /* best-effort */ }
+        try {
+            fs.unlinkSync(outPath);
+        }
+        catch { /* best-effort */ }
+    }
+}
 async function pickFolderViaOsDialog() {
     try {
         if (process.platform === 'win32') {
-            // 系统原生"选择文件夹"对话框（WinForms FolderBrowserDialog，Windows 经典的 Browse for Folder）。
-            // 用 -STA 单线程 + EnableVisualStyles，确保对话框在交互式桌面上真实弹出。
-            const script = [
-                'Add-Type -AssemblyName System.Windows.Forms',
-                '[System.Windows.Forms.Application]::EnableVisualStyles()',
-                '$d = New-Object System.Windows.Forms.FolderBrowserDialog',
-                '$d.Description = "选择工作区目录"',
-                '$d.ShowNewFolderButton = $true',
-                '[System.Windows.Forms.DialogResult]$r = $d.ShowDialog()',
-                'if ($r -eq [System.Windows.Forms.DialogResult]::OK) { $d.SelectedPath }',
-            ].join('; ');
-            const out = await execFileP('powershell.exe', ['-NoProfile', '-STA', '-Command', script], 55000);
-            return out || null;
+            return await pickFolderViaWindowsDialog();
         }
         if (process.platform === 'linux') {
             const out = await execFileP('zenity', ['--file-selection', '--directory', '--title=选择工作区目录'], 55000);
@@ -1531,7 +1735,7 @@ const writeBinary = async (ctx, args) => {
         throw new ToolError('DENIED', `File type "."${ext || '(none)'}" is blocked by safety policy. Use install_app / run_command with approval for executables.`);
     }
     fs.mkdirSync(path.dirname(target), { recursive: true });
-    fs.writeFileSync(target, buf);
+    atomicWrite(target, buf, { root: ctx.root });
     return { ok: true, result: { path: rel(realRoot, target), bytes: buf.length, written: true } };
 };
 // --- open_app: 在本机打开网页/应用/文件夹（无副作用，默认浏览器/系统打开）---
@@ -1542,6 +1746,19 @@ const DENIED_APPS = new Set([
     'shutdown', 'sdelete', 'wevtutil', 'schtasks', 'taskkill', 'format', 'fdisk',
 ]);
 const ALLOWED_BIN_EXT = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'wav', 'mp3', 'json', 'html', 'htm', 'txt', 'md']);
+/**
+ * open_app 拒绝直接拉起的可执行/脚本扩展名。
+ *
+ * 为什么需要这一层：open_app 走的是「系统默认动作」，在 Windows 上 `cmd /c start` 一个
+ * .bat/.ps1/.exe 就等于执行它。而它既没有 run_command 的危险命令检测，也不在平台的确认门里，
+ * 于是形成一条绕过所有确认的代码执行路径：先 write_file 落一个脚本，再 open_app 打开它。
+ * 打开文档/图片/网页是「看」，打开脚本/程序是「执行」—— 后者必须走需确认的命令通道。
+ */
+const DENIED_OPEN_EXT = new Set([
+    'exe', 'com', 'scr', 'bat', 'cmd', 'ps1', 'psm1', 'vbs', 'vbe', 'js', 'jse', 'wsf', 'wsh',
+    'msi', 'msp', 'lnk', 'url', 'hta', 'reg', 'jar', 'py', 'pyw', 'sh', 'bash', 'zsh', 'pl', 'rb',
+    'app', 'dmg', 'pkg', 'deb', 'rpm', 'apk', 'gadget', 'cpl', 'scf', 'inf', 'chm',
+]);
 const openApp = async (ctx, args, signal) => {
     abortIfRequested(signal);
     const target = requireString(args, 'target').trim();
@@ -1550,11 +1767,23 @@ const openApp = async (ctx, args, signal) => {
         if (/^(https?:\/\/)/i.test(target)) {
             // 允许：默认浏览器打开
         }
-        else if (/^[a-zA-Z]:[\\/]/.test(target) || target.startsWith('/') || target.startsWith('\\\\')) {
+        else if (target.startsWith('\\\\') || target.startsWith('//')) {
+            // UNC 路径：既是「拉起远端可执行文件」，光做存在性探测就会把 NTLM 哈希发给对方主机。
+            throw new ToolError('DENIED', 'UNC/网络路径不允许通过 open_app 打开。');
+        }
+        else if (/^[a-zA-Z]:[\\/]/.test(target) || target.startsWith('/')) {
             if (!fs.existsSync(target))
                 throw new ToolError('NOT_FOUND', `Path does not exist: ${target}`);
             if ((0, security_1.isSensitivePath)(target))
                 throw new ToolError('SENSITIVE', 'Opening this path is blocked by safety policy.');
+            const ext = path.extname(target).replace(/^\./, '').toLowerCase();
+            if (DENIED_OPEN_EXT.has(ext)) {
+                throw new ToolError('DENIED', `Refusing to launch "${path.basename(target)}": executable/script targets must go through a confirm-required command.`);
+            }
+            const base = path.basename(target).toLowerCase().replace(/\.exe$|\.bat$|\.cmd$|\.ps1$/, '');
+            if (DENIED_APPS.has(base)) {
+                throw new ToolError('DENIED', `"${target}" is blocked by safety policy.`);
+            }
         }
         else {
             const base = path.basename(target).toLowerCase().replace(/\.exe$|\.bat$|\.cmd$|\.ps1$/, '');
@@ -1665,6 +1894,86 @@ const installApp = async (ctx, args, signal, opts) => {
         return { ok: false, error: `install error: ${msg}` };
     }
 };
+// ---------------------------------------------------------------------------
+// MCP：每个授权根一个管理器
+// ---------------------------------------------------------------------------
+/** MCP server 是按「工作区」配置拉起的，所以管理器也按授权根分桶 —— 切工作区互不干扰。 */
+const mcpManagers = new Map();
+function mcpManagerFor(ctx) {
+    const key = (0, path_utils_1.canonicalize)(ctx.root);
+    let m = mcpManagers.get(key);
+    if (!m) {
+        m = new mcp_1.McpManager(key, (msg) => ctx.logger.info(msg));
+        mcpManagers.set(key, m);
+    }
+    return m;
+}
+/**
+ * 供 WS 层调用：把当前工作区可用的 MCP 工具清单报给平台，让模型直接看到这些工具。
+ * 失败/未配置都返回空数组（MCP 是可选能力，不该拖垮 Agent 上线）。
+ */
+async function listMcpTools(root, logger) {
+    if ((0, mcp_1.mcpDisabled)())
+        return [];
+    try {
+        const key = (0, path_utils_1.canonicalize)(root);
+        let m = mcpManagers.get(key);
+        if (!m) {
+            m = new mcp_1.McpManager(key, (msg) => logger?.info(msg));
+            mcpManagers.set(key, m);
+        }
+        return await m.listTools();
+    }
+    catch {
+        return [];
+    }
+}
+/** 配置了但启动失败的 MCP server（用于向平台如实说明，而不是让工具静默消失） */
+function mcpFailuresFor(root) {
+    try {
+        return mcpManagers.get((0, path_utils_1.canonicalize)(root))?.failures() || [];
+    }
+    catch {
+        return [];
+    }
+}
+/** 进程退出时收尾：把所有 MCP 子进程杀掉，避免留下孤儿进程 */
+function shutdownMcp() {
+    for (const [, m] of mcpManagers) {
+        try {
+            m.shutdown();
+        }
+        catch { /* 忽略 */ }
+    }
+    mcpManagers.clear();
+}
+/**
+ * mcp_list：列出当前工作区配置的 MCP server 与它们暴露的工具。
+ * 平台会把工具清单合并进模型工具表（正常情况下模型不需要调这个）；
+ * 这里保留是为了「平台没同步到」或模型想确认参数时有个兜底。
+ */
+const mcpList = async (ctx) => {
+    if ((0, mcp_1.mcpDisabled)()) {
+        return { ok: true, result: { enabled: false, count: 0, tools: [], note: 'MCP 已通过环境变量 YSAGC_MCP=0 关闭' } };
+    }
+    const root = (0, path_utils_1.canonicalize)(ctx.root);
+    const m = mcpManagerFor(ctx);
+    const tools = await m.listTools();
+    const failures = m.failures();
+    return {
+        ok: true,
+        result: {
+            enabled: true,
+            config_path: (0, mcp_1.mcpConfigPath)(root),
+            count: tools.length,
+            tools: tools.map((t) => ({ name: t.name, description: t.description })),
+            failures,
+            note: tools.length
+                ? '调用方式：直接用上面列出的工具名（mcp__server__tool）调用即可，参数按各工具的 inputSchema 传。'
+                : `当前工作区没有可用的 MCP 工具。如需接入，编辑 ${(0, mcp_1.mcpConfigPath)(root)} 后重新调用本工具。`,
+        },
+    };
+};
 const TOOLS = {
     list_dir: listDir,
     fs_drives: fsDrives,
@@ -1689,6 +1998,10 @@ const TOOLS = {
     write_binary: writeBinary,
     open_app: openApp,
     install_app: installApp,
+    screenshot: screenshot_1.screenshotTool,
+    browser: browser_1.browserTool,
+    remember: memory_1.rememberTool,
+    mcp_list: mcpList,
 };
 /** Build a tool registry bound to a single execution context. */
 function createToolRegistry(ctx) {
@@ -1697,12 +2010,16 @@ function createToolRegistry(ctx) {
         ctx,
         tools: names,
         has(name) {
-            return Object.prototype.hasOwnProperty.call(TOOLS, name);
+            // MCP 工具名是动态的，静态表里查不到；按前缀放行，真正的可用性由 Manager 判断。
+            return Object.prototype.hasOwnProperty.call(TOOLS, name) || (0, mcp_1.parseMcpToolName)(name) !== null;
         },
-        async dispatch(name, args, signal, rootOverride, preApproved) {
+        async dispatch(name, args, signal, rootOverride, preApproved, onProgress, readRootsOverride) {
             const started = Date.now();
             const executor = TOOLS[name];
-            if (!executor) {
+            // mcp__<server>__<tool>：MCP 工具是动态的（由工作区配置决定），没法写进静态 TOOLS 表，
+            // 所以在这里按名字前缀分流。走的是同一套权限闸门 / hook / 密钥脱敏。
+            const mcpTarget = (0, mcp_1.parseMcpToolName)(name);
+            if (!executor && !mcpTarget) {
                 return { ok: false, error: `Unknown tool: ${name}`, durationMs: 0 };
             }
             // 平台可把“用户所选工作区”作为本次调用的授权根：工作区是用户的明确选择，允许任意绝对路径（不限于启动时的 --root）；仍拦截系统/凭证敏感路径，执行边界就是该工作区（safeResolve/assertNotSensitive 保证）。
@@ -1721,6 +2038,21 @@ function createToolRegistry(ctx) {
                     /* 无效的 override：沿用原授权根 */
                 }
             }
+            // 只读参考根：逐个规范化，无效/敏感的直接丢弃（宁可少一个参考目录，也不要放开边界）
+            if (readRootsOverride && readRootsOverride.length) {
+                const cleaned = [];
+                for (const r of readRootsOverride.slice(0, 10)) {
+                    try {
+                        const rc = (0, path_utils_1.canonicalize)(r);
+                        if (!(0, security_1.isSensitivePath)(rc))
+                            cleaned.push(rc);
+                    }
+                    catch {
+                        /* 忽略无效参考根 */
+                    }
+                }
+                effCtx = { ...effCtx, readRoots: cleaned };
+            }
             try {
                 // Guarded gate: pre-execution check (permission preset, danger
                 // commands, canonicalise + sensitive-path). A platform-preApproved
@@ -1741,13 +2073,73 @@ function createToolRegistry(ctx) {
                 }
                 // A cancel message may arrive while pre-checking; honour it.
                 abortIfRequested(signal);
-                const outcome = await executor(effCtx, args ?? {}, signal, { preApproved: preApproved === true });
+                // ===== 前置 hook（工作区 .ysagc/hooks.json 里配的）=====
+                // 放在权限检查之后：被安全策略拦下的调用不该触发用户的 hook（否则 hook 会对着
+                // 一次根本没发生的操作跑）。hook 失败**不阻断**本次工具调用 —— 它是辅助动作，
+                // 不能因为 prettier 没装就让「写文件」这件事失败；失败信息会带回给模型。
+                let preHookNote = null;
+                try {
+                    const ph = await (0, hooks_1.runPreHooks)(effCtx, name, (args ?? {}));
+                    if (ph)
+                        preHookNote = ph.ok
+                            ? `前置 hook \`${ph.command}\` 执行成功${ph.output ? `：${ph.output}` : ''}`
+                            : `前置 hook \`${ph.command}\` 执行失败${ph.output ? `：${ph.output}` : ''}`;
+                }
+                catch { /* hook 机制自身出错不影响工具 */ }
+                const outcome = mcpTarget
+                    ? await (async () => {
+                        try {
+                            // 用 effCtx（平台下发的当前工作区；没有 override 时就是 Agent 授权根）：
+                            // MCP 配置跟着**工作区**走 —— `.ysagc/mcp.json` 就放在工作区根目录，
+                            // mcp_list 与平台侧工具表也都按工作区算。
+                            // 这里以前写的是 ctx（Agent 授权根），于是「探测到的工具」和「实际能调到的 server」
+                            // 读的不是同一份配置，实测表现是：工具表里有 mcp__testbox__add，
+                            // 一调用却回「MCP server "testbox" 未配置或未启动」。
+                            const raw = await mcpManagerFor(effCtx).callByName(name, (args ?? {}));
+                            const r = (0, mcp_1.renderMcpResult)(raw);
+                            return r.ok
+                                ? { ok: true, result: { mcp: name, content: r.text } }
+                                : { ok: false, error: `MCP 工具 ${name} 返回错误：${r.text}` };
+                        }
+                        catch (err) {
+                            return { ok: false, error: err?.message || String(err) };
+                        }
+                    })()
+                    : await executor(effCtx, args ?? {}, signal, {
+                        preApproved: preApproved === true,
+                        ...(onProgress ? { onOutput: onProgress } : {}),
+                    });
+                // ===== 后置 hook：只在工具**成功**后跑 =====
+                // 工具失败说明工作区可能停在半成品状态，这时再跑格式化只会对着残缺内容动手，
+                // 还可能把失败原因搅乱。所以失败的工具不触发后置 hook。
+                let hookNote = preHookNote;
+                if (outcome.ok) {
+                    try {
+                        const po = await (0, hooks_1.runPostHooks)(effCtx, name, (args ?? {}));
+                        if (po) {
+                            const note = po.ok
+                                ? `后置 hook \`${po.command}\` 执行成功${po.output ? `：${po.output}` : ''}`
+                                : `后置 hook \`${po.command}\` 执行失败${po.output ? `：${po.output}` : ''}`;
+                            hookNote = hookNote ? `${hookNote}\n${note}` : note;
+                        }
+                    }
+                    catch { /* 同上 */ }
+                }
+                // 把 hook 结果并进 result：模型和用户都能看到「自动跑了什么、成没成」
+                const withHook = hookNote
+                    ? {
+                        ...outcome,
+                        result: (outcome.result && typeof outcome.result === 'object')
+                            ? { ...outcome.result, hook: hookNote }
+                            : { hook: hookNote },
+                    }
+                    : outcome;
                 const result = {
-                    ok: outcome.ok,
-                    result: outcome.result,
-                    error: outcome.error,
+                    ok: withHook.ok,
+                    result: withHook.result,
+                    error: withHook.error,
                     durationMs: Date.now() - started,
-                    ...(outcome.needsApproval ? { needsApproval: true } : {}),
+                    ...(withHook.needsApproval ? { needsApproval: true } : {}),
                 };
                 // Guarded gate: post-execution check (mask secrets + record reason).
                 const post = postExecute(ctx, name, result);