@zhin.js/agent 0.0.17 → 0.0.19

package/src/builtin-tools.ts

@@ -1,118 +1,140 @@
 /**
  * AI 内置系统工具
  *
- * 借鉴 OpenClaw/MicroClaw 的实用工具设计，为 ZhinAgent 提供：
- *
  * 文件工具:  read_file, write_file, edit_file, list_dir, glob, grep
  * Shell:     bash
  * 网络:      web_search, web_fetch
  * 计划:      todo_read, todo_write
  * 记忆:      read_memory, write_memory (AGENTS.md)
  * 技能:      activate_skill, install_skill
- * 会话:      session_status, compact_session
- * 技能发现:  工作区 skills/ 目录自动扫描
- * 引导文件:  SOUL.md, TOOLS.md, AGENTS.md 自动加载
+ * 交互:      ask_user（基于 Prompt 类的用户确认/提问工具）
+ *
+ * 发现逻辑已拆分到 discover-skills.ts / discover-agents.ts / discover-tools.ts
  */
 
 import * as fs from 'fs';
-import * as os from 'os';
 import * as path from 'path';
 import { exec } from 'child_process';
 import { promisify } from 'util';
-import { Logger, type PropertySchema, type Plugin } from '@zhin.js/core';
+import { Logger, Prompt, type Plugin, type PropertySchema } from '@zhin.js/core';
 import { ZhinTool } from '@zhin.js/core';
-import { assertFileAccess, checkBashCommandSafety, shellEscape } from './file-policy.js';
-
-// 从新模块中 re-export 向后兼容的函数
-export { loadSoulPersona, loadToolsGuide, loadAgentsMemory } from './bootstrap.js';
+import {
+  assertFileAccess, checkBashCommandSafety, shellEscape,
+  isBlockedDevicePath, MAX_READ_FILE_SIZE, MAX_EDIT_FILE_SIZE,
+  classifyBashCommand, getFileMtime, isFileStale,
+} from './file-policy.js';
+import {
+  errMsg, expandHome, getDataDir, mergeSkillDirsWithResolver, nodeErrToFileMessage,
+} from './discovery-utils.js';
+import { checkSkillDeps, extractSkillInstructions } from './discover-skills.js';
 
 const execAsync = promisify(exec);
 const logger = new Logger(null, 'builtin-tools');
 
-function errMsg(e: unknown): string {
-  return e instanceof Error ? e.message : String(e);
-}
+// ── 引号归一化 + 模糊匹配（参考 Claude Code FileEditTool/utils.ts） ──
 
-/**
- * 获取数据目录路径
- */
-function getDataDir(): string {
-  const dir = path.join(process.cwd(), 'data');
-  fs.mkdirSync(dir, { recursive: true });
-  return dir;
+/** 将弯引号归一化为直引号 */
+function normalizeQuotes(str: string): string {
+  return str
+    .replace(/\u2018/g, "'")  // '
+    .replace(/\u2019/g, "'")  // '
+    .replace(/\u201C/g, '"')  // "
+    .replace(/\u201D/g, '"'); // "
 }
 
-/** Workspace / ~/.zhin / data 下 skills 根目录（与 activate_skill 扫描顺序一致的前缀） */
-function buildStandardSkillDirs(): string[] {
-  return [
-    path.join(process.cwd(), 'skills'),
-    path.join(os.homedir(), '.zhin', 'skills'),
-    path.join(getDataDir(), 'skills'),
-  ];
+interface FuzzyMatchResult {
+  /** 文件中实际匹配到的字符串 */
+  actual: string;
+  /** 匹配次数 */
+  count: number;
+  /** 是否通过引号归一化匹配 */
+  wasNormalized: boolean;
 }
 
 /**
- * 从根插件树收集：根插件与**直接子插件**包目录下的 `skills/`（其下为 `<name>/SKILL.md`）
+ * 在文件内容中查找字符串，支持精确匹配和引号归一化模糊匹配。
+ * 参考 Claude Code `findActualString`。
  */
-export function collectPluginSkillSearchRoots(root: Plugin | null | undefined): string[] {
-  if (!root) return [];
-  const dirs: string[] = [];
-  const push = (d: string) => {
-    if (d && !dirs.includes(d)) dirs.push(d);
-  };
-  const fromPlugin = (p: Plugin) => {
-    if (!p?.filePath) return;
-    const dir = path.dirname(p.filePath);
-    push(path.join(dir, 'skills'));
-    // Also check package root when filePath is under src/ or lib/
-    const dirName = path.basename(dir);
-    if (dirName === 'src' || dirName === 'lib') {
-      push(path.join(path.dirname(dir), 'skills'));
-    }
-  };
-  fromPlugin(root);
-  for (const child of root.children || []) {
-    fromPlugin(child);
+function findActualStringInFile(fileContent: string, searchString: string): FuzzyMatchResult | null {
+  // 精确匹配
+  const exactCount = fileContent.split(searchString).length - 1;
+  if (exactCount > 0) {
+    return { actual: searchString, count: exactCount, wasNormalized: false };
+  }
+
+  // 引号归一化匹配
+  const normalizedSearch = normalizeQuotes(searchString);
+  const normalizedFile = normalizeQuotes(fileContent);
+  const idx = normalizedFile.indexOf(normalizedSearch);
+  if (idx !== -1) {
+    // 提取文件中实际的字符串（保留原始弯引号）
+    const actual = fileContent.substring(idx, idx + searchString.length);
+    const normalizedCount = normalizedFile.split(normalizedSearch).length - 1;
+    return { actual, count: normalizedCount, wasNormalized: true };
   }
-  return dirs;
+
+  return null;
 }
 
 /**
- * 技能发现与 activate_skill 查找共用：标准目录 + 已加载插件包 skills/
+ * 将 new_string 中的直引号替换为文件中原始的弯引号风格。
+ * 参考 Claude Code `preserveQuoteStyle`。
  */
-export function getSkillSearchDirectories(root?: Plugin | null): string[] {
-  const list = [...buildStandardSkillDirs()];
-  for (const d of collectPluginSkillSearchRoots(root ?? undefined)) {
-    if (!list.includes(d)) list.push(d);
+function preserveQuoteStyleInEdit(oldString: string, actualOldString: string, newString: string): string {
+  if (oldString === actualOldString) return newString;
+
+  const hasDouble = actualOldString.includes('\u201C') || actualOldString.includes('\u201D');
+  const hasSingle = actualOldString.includes('\u2018') || actualOldString.includes('\u2019');
+  if (!hasDouble && !hasSingle) return newString;
+
+  let result = newString;
+  if (hasDouble) {
+    // 简单启发式：前面是空白/行首时用左引号，否则右引号
+    const chars = [...result];
+    const out: string[] = [];
+    for (let i = 0; i < chars.length; i++) {
+      if (chars[i] === '"') {
+        const prev = i > 0 ? chars[i - 1] : ' ';
+        const isOpening = /[\s(\[{]/.test(prev) || i === 0;
+        out.push(isOpening ? '\u201C' : '\u201D');
+      } else {
+        out.push(chars[i]);
+      }
+    }
+    result = out.join('');
   }
-  return list;
-}
-
-function mergeSkillDirsWithResolver(resolver?: () => string[]): string[] {
-  const list = [...buildStandardSkillDirs()];
-  for (const d of resolver?.() ?? []) {
-    if (d && !list.includes(d)) list.push(d);
+  if (hasSingle) {
+    const chars = [...result];
+    const out: string[] = [];
+    for (let i = 0; i < chars.length; i++) {
+      if (chars[i] === "'") {
+        const prev = i > 0 ? chars[i - 1] : ' ';
+        const next = i < chars.length - 1 ? chars[i + 1] : ' ';
+        // 两个字母之间是缩写，用右引号
+        if (/\p{L}/u.test(prev) && /\p{L}/u.test(next)) {
+          out.push('\u2019');
+        } else {
+          const isOpening = /[\s(\[{]/.test(prev) || i === 0;
+          out.push(isOpening ? '\u2018' : '\u2019');
+        }
+      } else {
+        out.push(chars[i]);
+      }
+    }
+    result = out.join('');
   }
-  return list;
+  return result;
 }
 
-/** 展开路径中的 ~ 为实际 home 目录 */
-function expandHome(p: string): string {
-  if (p === '~') return os.homedir();
-  if (p.startsWith('~/') || p.startsWith('~\\')) return path.join(os.homedir(), p.slice(2));
-  return p;
-}
+// ── 图片格式检测（参考 Claude Code FileReadTool imageResizer） ──
 
-/** 将 Node 文件错误转为 miniclawd 风格的结构化短句，便于模型区分并重试 */
-function nodeErrToFileMessage(err: unknown, filePath: string, kind: 'read' | 'write' | 'edit' | 'list'): string {
-  const e = err as NodeJS.ErrnoException;
-  if (e?.code === 'ENOENT') {
-    if (kind === 'list') return `Error: Directory not found: ${filePath}`;
-    return `Error: File not found: ${filePath}`;
-  }
-  if (e?.code === 'EACCES') return `Error: Permission denied: ${filePath}`;
-  const action = kind === 'read' ? 'reading file' : kind === 'write' ? 'writing file' : kind === 'edit' ? 'editing file' : 'listing directory';
-  return `Error ${action}: ${e?.message ?? String(err)}`;
+/** 支持的图片扩展名 */
+const IMAGE_EXTENSIONS: ReadonlySet<string> = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.svg', '.ico',
+]);
+
+function isImageFile(filePath: string): boolean {
+  return IMAGE_EXTENSIONS.has(path.extname(filePath).toLowerCase());
 }
 
 // ============================================================================
@@ -120,6 +142,8 @@ function nodeErrToFileMessage(err: unknown, filePath: string, kind: 'read' | 'wr
 // ============================================================================
 
 export interface BuiltinToolsOptions {
+  /** 插件实例，用于 ask_user 工具创建 Prompt 交互 */
+  plugin?: Plugin;
   /** Max chars for skill instruction extraction (model-size-aware) */
   skillInstructionMaxChars?: number;
   /**
@@ -141,13 +165,14 @@ export function createBuiltinTools(options?: BuiltinToolsOptions): ZhinTool[] {
   const skillMaxChars = options?.skillInstructionMaxChars ?? 4000;
   const skillDirList = () => mergeSkillDirsWithResolver(options?.pluginSkillRootsResolver);
   const skillFileLookup = options?.skillFileLookup;
+  const pluginRef = options?.plugin;
 
   const tools: ZhinTool[] = [];
 
-  // ── read_file（清晰描述 + 强关键词） ──
+  // ── read_file（清晰描述 + 强关键词 + 图片检测 + 安全防护） ──
   tools.push(
     new ZhinTool('read_file')
-      .desc('读取指定路径的文件内容。用于查看、打开或读取任意文本文件。')
+      .desc('读取指定路径的文件内容。用于查看、打开或读取任意文本文件。图片文件返回 Base64 数据。')
       .keyword('读文件', '读取文件', '查看文件', '打开文件', '文件内容', 'read file', 'read', 'cat', '查看', '打开')
       .tag('file', 'read')
       .kind('file')
@@ -157,8 +182,27 @@ export function createBuiltinTools(options?: BuiltinToolsOptions): ZhinTool[] {
       .execute(async (args) => {
         try {
           const fp = expandHome(args.file_path);
+          // 设备路径拦截（参考 Claude Code BLOCKED_DEVICE_PATHS）
+          if (isBlockedDevicePath(fp)) {
+            return `Error: 禁止读取设备文件 ${fp}（会导致进程挂起或注入攻击）`;
+          }
           assertFileAccess(fp);
           const stat = await fs.promises.stat(fp);
+          // 文件大小限制（参考 Claude Code MAX_EDIT_FILE_SIZE）
+          if (stat.size > MAX_READ_FILE_SIZE) {
+            return `Error: 文件过大 (${(stat.size / 1024 / 1024).toFixed(1)} MiB)，超过 ${MAX_READ_FILE_SIZE / 1024 / 1024} MiB 限制。请使用 offset/limit 分段读取。`;
+          }
+
+          // 图片文件检测（参考 Claude Code FileReadTool 的图片处理）
+          if (isImageFile(fp)) {
+            const buffer = await fs.promises.readFile(fp);
+            const ext = path.extname(fp).toLowerCase().replace('.', '');
+            const mimeType = ext === 'jpg' ? 'jpeg' : ext === 'svg' ? 'svg+xml' : ext;
+            const b64 = buffer.toString('base64');
+            const sizeKb = (buffer.length / 1024).toFixed(1);
+            return `[Image: ${path.basename(fp)}, ${sizeKb} KB, type: image/${mimeType}]\ndata:image/${mimeType};base64,${b64.slice(0, 200)}...(total ${b64.length} chars)`;
+          }
+
           const content = await fs.promises.readFile(fp, 'utf-8');
           const lines = content.split('\n');
           const offset = args.offset ?? 0;
@@ -194,10 +238,10 @@ export function createBuiltinTools(options?: BuiltinToolsOptions): ZhinTool[] {
       }),
   );
 
-  // ── edit_file（old_text 必须精确匹配） ──
+  // ── edit_file（支持精确匹配 + 引号归一化模糊匹配）──
   tools.push(
     new ZhinTool('edit_file')
-      .desc('在文件中查找并替换一段文本。old_string 必须在文件中精确存在且唯一；建议包含完整行或足够上下文以避免重复匹配。')
+      .desc('在文件中查找并替换一段文本。old_string 必须在文件中精确存在且唯一；建议包含完整行或足够上下文以避免重复匹配。支持弯引号/直引号自动归一化。')
       .keyword('编辑文件', '修改文件', '替换内容', '查找替换', 'edit file', 'edit', '修改', '替换')
       .tag('file', 'edit')
       .kind('file')
@@ -208,11 +252,32 @@ export function createBuiltinTools(options?: BuiltinToolsOptions): ZhinTool[] {
         try {
           const fp = expandHome(args.file_path);
           assertFileAccess(fp);
+          // 文件大小限制
+          const stat = await fs.promises.stat(fp);
+          if (stat.size > MAX_EDIT_FILE_SIZE) {
+            return `Error: 文件过大 (${(stat.size / 1024 / 1024).toFixed(1)} MiB)，超过 ${MAX_EDIT_FILE_SIZE / 1024 / 1024} MiB 限制。`;
+          }
+          // 记录 mtime 用于防并发覆写
+          const mtimeBefore = stat.mtimeMs;
           const content = await fs.promises.readFile(fp, 'utf-8');
-          const count = content.split(args.old_string).length - 1;
-          if (count === 0) return `Error: old_string not found in file. Make sure it matches exactly.`;
-          if (count > 1) return `Warning: old_string appears ${count} times. Please provide more context to make it unique.`;
-          const newContent = content.replace(args.old_string, args.new_string);
+
+          // 精确匹配 → 引号归一化模糊匹配
+          const matchResult = findActualStringInFile(content, args.old_string);
+          if (!matchResult) return `Error: old_string not found in file. Make sure it matches exactly (also tried quote normalization).`;
+          if (matchResult.count > 1) return `Warning: old_string appears ${matchResult.count} times. Please provide more context to make it unique.`;
+
+          // 如果通过引号归一化匹配，保持文件的引号风格
+          const effectiveNew = matchResult.wasNormalized
+            ? preserveQuoteStyleInEdit(args.old_string, matchResult.actual, args.new_string)
+            : args.new_string;
+
+          const newContent = content.replace(matchResult.actual, effectiveNew);
+
+          // 写入前再检查 mtime 防止并发修改
+          const currentStat = await fs.promises.stat(fp);
+          if (isFileStale(mtimeBefore, currentStat.mtimeMs)) {
+            return `Error: 文件 ${fp} 在读取后被外部修改。请重新读取文件后再编辑，避免覆盖他人的修改。`;
+          }
           await fs.promises.writeFile(fp, newContent, 'utf-8');
 
           const oldLines = args.old_string.split('\n');
@@ -284,29 +349,68 @@ export function createBuiltinTools(options?: BuiltinToolsOptions): ZhinTool[] {
       }),
   );
 
-  // ── grep ──
+  // ── grep（支持上下文行、大小写、多行、ripgrep 自动检测） ──
   tools.push(
     new ZhinTool('grep')
-      .desc('按正则搜索文件内容，返回匹配行和行号')
-      .keyword('搜索', '查找内容', 'grep', '正则')
+      .desc('按正则搜索文件内容，返回匹配行和行号。优先使用 ripgrep (rg)，回退到 grep。')
+      .keyword('搜索', '查找内容', 'grep', '正则', 'rg', 'ripgrep')
       .tag('search', 'regex')
       .kind('file')
       .param('pattern', { type: 'string', description: '正则表达式' }, true)
       .param('path', { type: 'string', description: '搜索路径（默认 .）' })
       .param('include', { type: 'string', description: '文件类型过滤（如 *.ts）' })
+      .param('context', { type: 'number', description: '匹配行上下文行数（-C 参数）' })
+      .param('before', { type: 'number', description: '匹配行之前显示行数（-B 参数）' })
+      .param('after', { type: 'number', description: '匹配行之后显示行数（-A 参数）' })
+      .param('ignore_case', { type: 'boolean', description: '大小写不敏感搜索（-i 参数）' } as any)
+      .param('multiline', { type: 'boolean', description: '多行模式，. 匹配换行（仅 ripgrep 支持）' } as any)
+      .param('limit', { type: 'number', description: '最多返回结果行数（默认 50）' })
       .execute(async (args) => {
         try {
           const searchPath = args.path || '.';
           assertFileAccess(path.resolve(process.cwd(), searchPath));
-          // 安全转义 pattern 和 include 参数防止命令注入
           const safePattern = shellEscape(args.pattern);
           const safePath = shellEscape(searchPath);
-          const includeFlag = args.include ? `--include=${shellEscape(args.include)}` : '';
-          const { stdout } = await execAsync(
-            `grep -rn ${includeFlag} ${safePattern} ${safePath} 2>/dev/null | head -50`,
-            { cwd: process.cwd() },
-          );
-          return stdout.trim() || `No matches for '${args.pattern}'`;
+          const limit = args.limit ?? 50;
+
+          // 检测 ripgrep 是否可用
+          let useRipgrep = false;
+          try {
+            await execAsync('rg --version', { timeout: 3000 });
+            useRipgrep = true;
+          } catch { /* ripgrep 不可用，回退到 grep */ }
+
+          let cmd: string;
+          if (useRipgrep) {
+            // ripgrep 命令构建
+            const rgFlags: string[] = ['-n']; // 行号
+            if (args.ignore_case) rgFlags.push('-i');
+            if (args.multiline) rgFlags.push('-U', '--multiline-dotall');
+            if (args.context) rgFlags.push(`-C${args.context}`);
+            else {
+              if (args.before) rgFlags.push(`-B${args.before}`);
+              if (args.after) rgFlags.push(`-A${args.after}`);
+            }
+            if (args.include) rgFlags.push(`--glob=${shellEscape(args.include)}`);
+            cmd = `rg ${rgFlags.join(' ')} ${safePattern} ${safePath} 2>/dev/null | head -${limit}`;
+          } else {
+            // 传统 grep 回退
+            const grepFlags: string[] = ['-rn'];
+            if (args.ignore_case) grepFlags.push('-i');
+            if (args.context) grepFlags.push(`-C${args.context}`);
+            else {
+              if (args.before) grepFlags.push(`-B${args.before}`);
+              if (args.after) grepFlags.push(`-A${args.after}`);
+            }
+            const includeFlag = args.include ? `--include=${shellEscape(args.include)}` : '';
+            cmd = `grep ${grepFlags.join(' ')} ${includeFlag} ${safePattern} ${safePath} 2>/dev/null | head -${limit}`;
+          }
+
+          const { stdout } = await execAsync(cmd, { cwd: process.cwd() });
+          const engine = useRipgrep ? '(ripgrep)' : '(grep)';
+          return stdout.trim()
+            ? `${engine}\n${stdout.trim()}`
+            : `No matches for '${args.pattern}' ${engine}`;
         } catch (e: unknown) {
           const err = e as { code?: number; message?: string };
           if (err.code === 1) return `No matches for '${args.pattern}'`;
@@ -315,10 +419,10 @@ export function createBuiltinTools(options?: BuiltinToolsOptions): ZhinTool[] {
       }),
   );
 
-  // ── bash ──
+  // ── bash（安全检查 + 命令读写分类） ──
   tools.push(
     new ZhinTool('bash')
-      .desc('执行 Shell 命令（带超时保护）')
+      .desc('执行 Shell 命令（带超时保护和命令分类）。返回结果中会标注命令类型（只读/搜索/写入）。')
       .keyword('执行', '运行', '命令', '终端', 'shell', 'bash')
       .tag('shell', 'exec')
       .kind('shell')
@@ -332,15 +436,20 @@ export function createBuiltinTools(options?: BuiltinToolsOptions): ZhinTool[] {
           // 检查命令是否可能泄漏敏感信息
           const safety = checkBashCommandSafety(cmd);
           if (!safety.safe) return `Error: ${safety.reason}`;
+          // 命令读写分类
+          const classification = classifyBashCommand(cmd);
           const { stdout, stderr } = await execAsync(cmd, {
             cwd: args.cwd || process.cwd(),
             timeout,
             maxBuffer: 1024 * 1024,
           });
           let result = '';
+          const tag = classification.isReadOnly
+            ? (classification.isSearch ? '[搜索]' : classification.isList ? '[列出]' : '[只读]')
+            : '[执行]';
           if (stdout.trim()) result += `STDOUT:\n${stdout.trim()}`;
           if (stderr.trim()) result += `${result ? '\n' : ''}STDERR:\n${stderr.trim()}`;
-          return result || '(no output)';
+          return `${tag} ${result || '(no output)'}`;
         } catch (e: unknown) {
           const err = e as { code?: number; message?: string; stdout?: string; stderr?: string };
           return `Error (exit ${err.code || '?'}): ${errMsg(e)}\nSTDOUT:\n${err.stdout || ''}\nSTDERR:\n${err.stderr || ''}`;
@@ -348,17 +457,27 @@ export function createBuiltinTools(options?: BuiltinToolsOptions): ZhinTool[] {
       }),
   );
 
-  // ── web_search（搜索网页，返回标题、URL、摘要） ──
+  // ── web_search（搜索网页，返回标题、URL、摘要 + 域名过滤 + 次数限制） ──
+  let searchCount = 0;
+  const MAX_SEARCH_COUNT = 20; // 单次会话搜索次数上限
   tools.push(
     new ZhinTool('web_search')
-      .desc('在互联网上搜索，返回匹配的标题、URL 和摘要片段。用于查资料、找网页。')
+      .desc('在互联网上搜索，返回匹配的标题、URL 和摘要片段。用于查资料、找网页。支持域名过滤。')
       .keyword('搜索', '网上搜', '网页搜索', '搜索引擎', 'search', 'google', '百度', '查询', '搜一下')
       .tag('web', 'search')
       .kind('web')
       .param('query', { type: 'string', description: '搜索关键词或完整查询语句' }, true)
       .param('limit', { type: 'number', description: '返回结果数量（默认 5，建议 1–10）' })
+      .param('allowed_domains', { type: 'array', description: '仅保留这些域名的结果（可选，如 ["github.com", "stackoverflow.com"]）' } as any)
+      .param('blocked_domains', { type: 'array', description: '排除这些域名的结果（可选）' } as any)
       .execute(async (args) => {
         try {
+          // 搜索次数限制
+          searchCount++;
+          if (searchCount > MAX_SEARCH_COUNT) {
+            return `Error: 搜索次数已达上限 (${MAX_SEARCH_COUNT})。请使用已获取的信息回答。`;
+          }
+
           const limit = args.limit ?? 5;
           const url = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(args.query)}`;
           const res = await fetch(url, {
@@ -401,8 +520,23 @@ export function createBuiltinTools(options?: BuiltinToolsOptions): ZhinTool[] {
             }
           }
 
-          if (results.length === 0) return 'No results found.';
-          return results.map((r, i) =>
+          // 域名过滤
+          let filtered = results;
+          if (args.allowed_domains?.length) {
+            const allowed = new Set((args.allowed_domains as string[]).map(d => d.toLowerCase()));
+            filtered = filtered.filter(r => {
+              try { return allowed.has(new URL(r.url).hostname.toLowerCase()); } catch { return false; }
+            });
+          }
+          if (args.blocked_domains?.length) {
+            const blocked = new Set((args.blocked_domains as string[]).map(d => d.toLowerCase()));
+            filtered = filtered.filter(r => {
+              try { return !blocked.has(new URL(r.url).hostname.toLowerCase()); } catch { return true; }
+            });
+          }
+
+          if (filtered.length === 0) return 'No results found.';
+          return `(${searchCount}/${MAX_SEARCH_COUNT} searches)\n` + filtered.map((r, i) =>
             `${i + 1}. ${r.title}\n   URL: ${r.url}\n   ${r.snippet}`,
           ).join('\n\n');
         } catch (e: unknown) {
@@ -411,29 +545,67 @@ export function createBuiltinTools(options?: BuiltinToolsOptions): ZhinTool[] {
       }),
   );
 
-  // ── web_fetch（抓取 URL 并提取正文） ──
+  // ── web_fetch（抓取 URL 并提取正文 + SSRF 防护 + 改进的内容提取） ──
   tools.push(
     new ZhinTool('web_fetch')
-      .desc('抓取指定 URL 的网页内容并提取正文（去除广告等），返回可读文本。用于读文章、获取网页内容。')
+      .desc('抓取指定 URL 的网页内容并提取正文（去除广告、脚本等），返回可读文本。仅支持 http/https 协议。')
       .keyword('抓取网页', '打开链接', '获取网页', '读网页', 'fetch', 'url', '链接内容', '网页内容')
       .tag('web', 'fetch')
       .kind('web')
       .param('url', { type: 'string', description: '要抓取的完整 URL（需 http 或 https）' }, true)
+      .param('max_length', { type: 'number', description: '最大返回字符数（默认 20480）' })
       .execute(async (args) => {
         try {
+          // SSRF 防护：仅允许 http/https 协议
+          let parsedUrl: URL;
+          try {
+            parsedUrl = new URL(args.url);
+          } catch {
+            return `Error: 无效的 URL 格式`;
+          }
+          if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+            return `Error: 仅支持 http/https 协议，拒绝 ${parsedUrl.protocol}`;
+          }
+          // 阻止内网地址（SSRF 关键防护）
+          const hostname = parsedUrl.hostname.toLowerCase();
+          if (
+            hostname === 'localhost' ||
+            hostname === '127.0.0.1' ||
+            hostname === '::1' ||
+            hostname === '0.0.0.0' ||
+            hostname.endsWith('.local') ||
+            hostname.startsWith('10.') ||
+            hostname.startsWith('192.168.') ||
+            /^172\.(1[6-9]|2\d|3[01])\./.test(hostname)
+          ) {
+            return `Error: 禁止访问内网地址 ${hostname}（SSRF 防护）`;
+          }
+
           const response = await fetch(args.url, {
             headers: { 'User-Agent': 'Mozilla/5.0 (compatible; ZhinBot/1.0)' },
             signal: AbortSignal.timeout(15000),
+            redirect: 'follow',
           });
           if (!response.ok) return `HTTP ${response.status}: ${response.statusText}`;
           const html = await response.text();
+          // 改进的内容提取：去除脚本、样式、导航、页脚、表单等
           const text = html
             .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '')
             .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '')
+            .replace(/<nav[^>]*>[\s\S]*?<\/nav>/gi, '')
+            .replace(/<footer[^>]*>[\s\S]*?<\/footer>/gi, '')
+            .replace(/<header[^>]*>[\s\S]*?<\/header>/gi, ' ')
+            .replace(/<form[^>]*>[\s\S]*?<\/form>/gi, '')
+            .replace(/<!--[\s\S]*?-->/g, '')
             .replace(/<[^>]+>/g, ' ')
+            .replace(/&nbsp;/gi, ' ')
+            .replace(/&amp;/g, '&')
+            .replace(/&lt;/g, '<')
+            .replace(/&gt;/g, '>')
+            .replace(/&quot;/g, '"')
             .replace(/\s+/g, ' ')
             .trim();
-          const maxLen = 20 * 1024;
+          const maxLen = args.max_length ?? 20 * 1024;
           return text.length > maxLen ? text.slice(0, maxLen) + '\n...(truncated)' : text;
         } catch (e: unknown) {
           return `Error: ${errMsg(e)}`;
@@ -555,7 +727,6 @@ export function createBuiltinTools(options?: BuiltinToolsOptions): ZhinTool[] {
             const instructions = extractSkillInstructions(args.name, fullContent, skillMaxChars);
             return depWarning ? `${depWarning}\n\n${instructions}` : instructions;
           }
-          // 回退到目录扫描（与 discoverWorkspaceSkills 顺序一致）
           for (const dir of skillDirList()) {
             const skillPath = path.join(dir, args.name, 'SKILL.md');
             if (fs.existsSync(skillPath)) {
@@ -617,738 +788,65 @@ export function createBuiltinTools(options?: BuiltinToolsOptions): ZhinTool[] {
       }),
   );
 
-  return tools;
-}
-
-/**
- * 检查技能声明的依赖是否在环境中可用；若有缺失返回提示文案，否则返回空字符串
- */
-async function checkSkillDeps(content: string): Promise<string> {
-  const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
-  if (!fmMatch) return '';
-  let jsYaml: any;
-  try {
-    jsYaml = await import('js-yaml');
-    if (jsYaml.default) jsYaml = jsYaml.default;
-  } catch {
-    return '';
-  }
-  const metadata = jsYaml.load(fmMatch[1]);
-  if (!metadata) return '';
-  const compat = metadata.compatibility || {};
-  const deps = compat.deps || metadata.deps;
-  if (!deps || !Array.isArray(deps)) return '';
-  const missing: string[] = [];
-  for (const dep of deps) {
-    try {
-      await execAsync(`which ${dep} 2>/dev/null`);
-    } catch {
-      missing.push(dep);
-    }
-  }
-  if (missing.length === 0) return '';
-  return `⚠️ 当前环境缺少以下依赖，请先安装后再使用本技能：${missing.join(', ')}`;
-}
-
-/**
- * 从 SKILL.md 全文中提取精简的执行指令
- * 只保留 frontmatter（工具列表）和执行规则，去掉示例、测试场景等冗余内容
- * 这样可以大幅减少 token 占用，让小模型能有足够空间继续调用工具
- */
-function extractSkillInstructions(name: string, content: string, maxBodyLen: number = 4000): string {
-  const lines: string[] = [];
-  lines.push(`Skill '${name}' activated. 请立即根据以下指导执行工具调用：`);
-  lines.push('');
-
-  const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
-  if (fmMatch) {
-    const fmContent = fmMatch[1];
-    const toolsMatch = fmContent.match(/tools:\s*\n((?:\s+-\s+.+\n?)+)/);
-    if (toolsMatch) {
-      lines.push('## 可用工具');
-      lines.push(toolsMatch[0].trim());
-      lines.push('');
-    }
-  }
-
-  const bodyAfterFm = fmMatch && fmMatch.index !== undefined
-    ? content.slice(fmMatch.index + fmMatch[0].length).replace(/^\s+/, '')
-    : content;
-
-  // Priority: "## 快速操作" / "## Quick Actions" summary for small models
-  const quickActionsMatch = bodyAfterFm.match(/## (?:快速操作|Quick\s*Actions)[\s\S]*?(?=\n## [^\s]|$)/i);
-  if (quickActionsMatch && maxBodyLen <= 2000) {
-    lines.push(quickActionsMatch[0].trim());
-    lines.push('');
-    lines.push('## 立即行动');
-    lines.push('根据上面的指导，立即调用工具完成用户请求。禁止重复调用 activate_skill，禁止用文本描述代替实际工具调用。');
-    return lines.join('\n');
-  }
-
-  const rulesMatch = content.match(/## 执行规则[\s\S]*?(?=\n## [^\s]|$)/);
-  const workflowMatch = content.match(/## (?:Workflow|Instructions|使用说明)[\s\S]*?(?=\n## [^\s]|$)/);
-
-  if (rulesMatch) {
-    lines.push(rulesMatch[0].trim());
-    lines.push('');
-  } else if (workflowMatch) {
-    lines.push(workflowMatch[0].trim());
-    lines.push('');
-  } else if (bodyAfterFm.trim()) {
-    const firstH2 = bodyAfterFm.match(/\n## [^\s]/);
-    const intro = firstH2 ? bodyAfterFm.slice(0, firstH2.index).trim() : bodyAfterFm.trim();
-
-    const quickStartMatch = bodyAfterFm.match(/## (?:快速开始|Quick\s*Start|Getting\s*Started)[\s\S]*?(?=\n## [^\s]|$)/i);
-    const authMatch = bodyAfterFm.match(/## (?:认证|Authentication|Auth)[\s\S]*?(?=\n## [^\s]|$)/i);
-
-    if (quickStartMatch || (intro.length < 200 && bodyAfterFm.length > intro.length)) {
-      lines.push('## 指导');
-      lines.push(intro);
-      lines.push('');
-      const extra: string[] = [];
-      if (quickStartMatch) extra.push(quickStartMatch[0].trim());
-      if (authMatch) extra.push(authMatch[0].trim());
-      if (extra.length > 0) {
-        const joined = extra.join('\n\n');
-        lines.push(joined.length > maxBodyLen ? joined.slice(0, maxBodyLen) + '\n...(truncated)' : joined);
-      } else {
-        const rest = bodyAfterFm.slice(intro.length).trim();
-        lines.push(rest.length > maxBodyLen ? rest.slice(0, maxBodyLen) + '\n...(truncated)' : rest);
-      }
-      lines.push('');
-    } else if (intro) {
-      lines.push('## 指导');
-      lines.push(intro);
-      lines.push('');
-    }
-  }
-
-  lines.push('## 立即行动');
-  lines.push('根据上面的指导，立即调用工具完成用户请求。禁止重复调用 activate_skill，禁止用文本描述代替实际工具调用。');
-
-  return lines.join('\n');
-}
-
-// ============================================================================
-// 技能发现
-// ============================================================================
-
-export interface SkillMeta {
-  name: string;
-  description: string;
-  keywords?: string[];
-  tags?: string[];
-  /** SKILL.md frontmatter 中声明的关联工具名列表 */
-  toolNames?: string[];
-  filePath: string;
-  /** 是否常驻注入 system prompt（frontmatter always: true） */
-  always?: boolean;
-  /** 当前环境是否满足依赖（bins/env） */
-  available?: boolean;
-  /** 缺失的依赖描述（如 "CLI: ffmpeg", "ENV: API_KEY"） */
-  requiresMissing?: string[];
-}
-
-/**
- * 扫描技能目录，发现 SKILL.md 技能文件
- * 加载顺序：Workspace（cwd/skills）> Local（~/.zhin/skills）> data/skills > 已加载插件包 skills/，同名先发现者优先
- * 支持平台/依赖兼容性过滤。内置技能由 create-zhin 在创建项目时写入 skills/summarize 等。
- *
- * @param root 根插件（可选）：用于追加插件包内 `skills/` 扫描，与 `activate_skill` 查找路径一致
- */
-export async function discoverWorkspaceSkills(root?: Plugin | null): Promise<SkillMeta[]> {
-  const skills: SkillMeta[] = [];
-  const seenNames = new Set<string>();
-  const dataDir = getDataDir();
-  const skillDirs = getSkillSearchDirectories(root ?? undefined);
-
-  // 确保 data/skills 目录存在
-  const defaultSkillDir = path.join(dataDir, 'skills');
-  if (!fs.existsSync(defaultSkillDir)) {
-    fs.mkdirSync(defaultSkillDir, { recursive: true });
-    logger.debug(`Created skill directory: ${defaultSkillDir}`);
-  }
-
-  for (const skillsDir of skillDirs) {
-    if (!fs.existsSync(skillsDir)) continue;
-
-    let entries: fs.Dirent[];
-    try {
-      entries = await fs.promises.readdir(skillsDir, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      const skillMdPath = path.join(skillsDir, entry.name, 'SKILL.md');
-      if (!fs.existsSync(skillMdPath)) continue;
-
-      try {
-        const content = await fs.promises.readFile(skillMdPath, 'utf-8');
-        // 改进的 frontmatter 正则：支持多种换行符、可选的尾部空白
-        const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*(?:\n|$)/);
-        if (!match) {
-          logger.debug(`Skill文件 ${skillMdPath} 没有有效的frontmatter格式`);
-          continue;
-        }
+  // ── ask_user（基于 Prompt 类的用户确认/提问工具） ──
+  tools.push(
+    new ZhinTool('ask_user')
+      .desc('向用户发送问题，等待用户在聊天中回复。用于需要用户确认、补充信息或做出选择时。支持文本输入、数字输入、是/否确认、选项选择。')
+      .keyword('询问', '确认', '提问', '用户输入', 'ask', 'confirm', 'prompt', '选择', '请问')
+      .tag('interaction', 'prompt')
+      .kind('interaction')
+      .param('question', { type: 'string', description: '要向用户提出的问题文本' }, true)
+      .param('type', { type: 'string', description: '问题类型: text(文本输入)、number(数字输入)、confirm(是/否确认)、pick(选项选择)。默认 text' })
+      .param('options', { type: 'array', description: '选项列表（type=pick 时必填），每项为字符串，如 ["选项A","选项B","选项C"]' })
+      .param('default_value', { type: 'string', description: '用户超时未回复时使用的默认值' })
+      .param('timeout', { type: 'number', description: '等待用户回复的超时时间（秒），默认 120' })
+      .execute(async (args, context) => {
+        // 无消息上下文时无法使用（如子任务场景）
+        if (!context?.message) {
+          return 'Error: 当前上下文没有消息来源，无法向用户提问。请改为在回复中直接询问。';
+        }
+        if (!pluginRef) {
+          return 'Error: 插件实例不可用，无法创建交互式提问。请改为在回复中直接询问。';
+        }
+
+        const prompt = new Prompt(pluginRef, context.message);
+        const timeoutMs = (args.timeout ?? 120) * 1000;
+        const questionType = args.type || 'text';
 
-        let jsYaml: any;
         try {
-          jsYaml = await import('js-yaml');
-          if (jsYaml.default) jsYaml = jsYaml.default;
-        } catch (e) {
-          logger.warn(`Unable to import js-yaml module: ${e}`);
-          continue;
-        }
-
-        const metadata = jsYaml.load(match[1]);
-        if (!metadata || !metadata.name || !metadata.description) {
-          logger.debug(`Skill文件 ${skillMdPath} 缺少必需的 name/description 字段`);
-          continue;
-        }
-
-        // 平台兼容检查
-        const compat = metadata.compatibility || {};
-        if (compat.os && Array.isArray(compat.os)) {
-          const currentOs = process.platform === 'darwin' ? 'darwin' : process.platform === 'win32' ? 'windows' : 'linux';
-          if (!compat.os.includes(currentOs)) {
-            logger.debug(`Skipping skill '${metadata.name}' (unsupported OS)`);
-            continue;
-          }
-        }
-
-        // 依赖检查：支持 metadata.requires.bins / requires.env 或 compat.deps / metadata.deps
-        const requiresBins: string[] = metadata.requires?.bins || compat.deps || metadata.deps || [];
-        const requiresEnv: string[] = metadata.requires?.env || [];
-        const binsToCheck = Array.isArray(requiresBins) ? requiresBins : [];
-        const envToCheck = Array.isArray(requiresEnv) ? requiresEnv : [];
-        const requiresMissing: string[] = [];
-        for (const bin of binsToCheck) {
-          try {
-            await execAsync(`which ${bin} 2>/dev/null`);
-          } catch {
-            requiresMissing.push(`CLI: ${bin}`);
-          }
-        }
-        for (const envKey of envToCheck) {
-          if (!process.env[envKey]) {
-            requiresMissing.push(`ENV: ${envKey}`);
+          switch (questionType) {
+            case 'number': {
+              const defaultNum = args.default_value != null ? Number(args.default_value) : undefined;
+              const result = await prompt.number(args.question, timeoutMs, defaultNum, '输入超时，已取消');
+              return String(result);
+            }
+            case 'confirm': {
+              const result = await prompt.confirm(args.question, 'yes', timeoutMs, false, '确认超时，已取消');
+              return result ? 'yes' : 'no';
+            }
+            case 'pick': {
+              if (!args.options?.length) {
+                return 'Error: type=pick 时必须提供 options 选项列表';
+              }
+              const pickOptions = (args.options as string[]).map((o: string) => ({ label: o, value: o }));
+              const result = await prompt.pick(args.question, {
+                type: 'text' as const,
+                options: pickOptions,
+                timeout: timeoutMs,
+              }, '选择超时，已取消');
+              return String(result);
+            }
+            case 'text':
+            default: {
+              const result = await prompt.text(args.question, timeoutMs, args.default_value || '', '输入超时，已取消');
+              return result;
+            }
           }
+        } catch (e: unknown) {
+          return `用户未响应或输入错误: ${errMsg(e)}`;
         }
-        const available = requiresMissing.length === 0;
-
-        if (seenNames.has(metadata.name)) {
-          logger.debug(`Skill '${metadata.name}' 已由先序目录加载，跳过: ${skillMdPath}`);
-          continue;
-        }
-        seenNames.add(metadata.name);
-
-        skills.push({
-          name: metadata.name,
-          description: metadata.description,
-          keywords: metadata.keywords || [],
-          tags: [...(metadata.tags || []), 'workspace-skill'],
-          toolNames: Array.isArray(metadata.tools) ? metadata.tools : [],
-          filePath: skillMdPath,
-          always: Boolean(metadata.always),
-          available,
-          requiresMissing: requiresMissing.length > 0 ? requiresMissing : undefined,
-        });
-        logger.debug(`Skill发现成功: ${metadata.name}, tools: ${JSON.stringify(metadata.tools || [])}`);
-      } catch (e) {
-        logger.warn(`Failed to parse SKILL.md in ${skillMdPath}:`, e);
-      }
-    }
-  }
-
-  if (skills.length > 0) {
-    logger.info(`发现 ${skills.length} 个工作区技能: ${skills.map(s => `${s.name}(tools:${(s.toolNames || []).join(',')})`).join(', ')}`);
-  }
-
-  return skills;
-}
-
-/**
- * 获取 frontmatter 中 always: true 的技能名列表（用于常驻注入 system prompt）
- */
-export function getAlwaysSkillNames(skills: SkillMeta[]): string[] {
-  return skills.filter(s => s.always && s.available).map(s => s.name);
-}
-
-/**
- * 去除 frontmatter，返回正文
- */
-function stripFrontmatter(content: string): string {
-  const match = content.match(/^---\s*\n[\s\S]*?\n---\s*(?:\n|$)/);
-  if (match) {
-    return content.slice(match[0].length).trim();
-  }
-  return content.trim();
-}
-
-/**
- * 加载 always 技能的正文内容并拼接为「Active Skills」段
- */
-export async function loadAlwaysSkillsContent(skills: SkillMeta[]): Promise<string> {
-  const always = skills.filter(s => s.always && s.available);
-  if (always.length === 0) return '';
-  const parts: string[] = [];
-  for (const s of always) {
-    try {
-      const content = await fs.promises.readFile(s.filePath, 'utf-8');
-      const body = stripFrontmatter(content);
-      parts.push(`### Skill: ${s.name}\n\n${body}`);
-    } catch (e) {
-      logger.warn(`Failed to load always skill ${s.name}: ${(e as Error).message}`);
-    }
-  }
-  return parts.join('\n\n---\n\n');
-}
-
-/** 转义 XML 特殊字符 */
-function escapeXml(s: string): string {
-  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-}
-
-/**
- * 构建技能列表的 XML 摘要，供 model 区分可用/不可用及缺失依赖
- */
-export function buildSkillsSummaryXML(skills: SkillMeta[]): string {
-  if (skills.length === 0) return '';
-  const lines = ['<skills>'];
-  for (const s of skills) {
-    const available = s.available !== false;
-    lines.push(`  <skill available="${available}">`);
-    lines.push(`    <name>${escapeXml(s.name)}</name>`);
-    lines.push(`    <description>${escapeXml(s.description)}</description>`);
-    lines.push(`    <location>${escapeXml(s.filePath)}</location>`);
-    if (!available && s.requiresMissing && s.requiresMissing.length > 0) {
-      lines.push(`    <requires>${escapeXml(s.requiresMissing.join(', '))}</requires>`);
-    }
-    lines.push('  </skill>');
-  }
-  lines.push('</skills>');
-  return lines.join('\n');
-}
-
-// ============================================================================
-// Agent 预设发现（*.agent.md 文件）
-// ============================================================================
-
-/**
- * Agent 预设元数据（从 *.agent.md frontmatter 解析）
- */
-export interface AgentMeta {
-  name: string;
-  description: string;
-  keywords?: string[];
-  tags?: string[];
-  /** frontmatter 中声明的工具名列表 */
-  toolNames?: string[];
-  /** *.agent.md 文件的绝对路径 */
-  filePath: string;
-  /** 首选模型名 */
-  model?: string;
-  /** 首选 Provider 名 */
-  provider?: string;
-  /** 最大工具调用迭代次数 */
-  maxIterations?: number;
-}
-
-/**
- * 扫描 agents/ 目录，发现 *.agent.md 文件
- * 加载顺序与 skills 一致：Workspace > ~/.zhin > data > 插件包
- * 同名先发现者优先
- */
-export async function discoverWorkspaceAgents(root?: Plugin | null): Promise<AgentMeta[]> {
-  const agents: AgentMeta[] = [];
-  const seenNames = new Set<string>();
-
-  // 构建扫描目录：标准目录的 agents/ + 插件包的 agents/
-  const agentDirs: string[] = [
-    path.join(process.cwd(), 'agents'),
-    path.join(os.homedir(), '.zhin', 'agents'),
-    path.join(getDataDir(), 'agents'),
-  ];
-  if (root) {
-    const addPluginDir = (p: Plugin) => {
-      if (!p?.filePath) return;
-      const dir = path.dirname(p.filePath);
-      const d = path.join(dir, 'agents');
-      if (!agentDirs.includes(d)) agentDirs.push(d);
-      // Also check package root when filePath is under src/ or lib/
-      const dirName = path.basename(dir);
-      if (dirName === 'src' || dirName === 'lib') {
-        const d2 = path.join(path.dirname(dir), 'agents');
-        if (!agentDirs.includes(d2)) agentDirs.push(d2);
-      }
-    };
-    addPluginDir(root);
-    for (const child of root.children || []) {
-      addPluginDir(child);
-    }
-  }
-
-  for (const agentsDir of agentDirs) {
-    if (!fs.existsSync(agentsDir)) continue;
-
-    let entries: fs.Dirent[];
-    try {
-      entries = await fs.promises.readdir(agentsDir, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-
-    for (const entry of entries) {
-      // 支持两种结构：
-      // 1. agents/<name>.agent.md（扁平文件）
-      // 2. agents/<name>/<name>.agent.md（目录结构）
-      let agentMdPath: string | undefined;
-      if (entry.isFile() && entry.name.endsWith('.agent.md')) {
-        agentMdPath = path.join(agentsDir, entry.name);
-      } else if (entry.isDirectory()) {
-        const nested = path.join(agentsDir, entry.name, `${entry.name}.agent.md`);
-        if (fs.existsSync(nested)) {
-          agentMdPath = nested;
-        }
-      }
-      if (!agentMdPath) continue;
-
-      try {
-        const content = await fs.promises.readFile(agentMdPath, 'utf-8');
-        const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*(?:\n|$)/);
-        if (!match) {
-          logger.debug(`Agent文件 ${agentMdPath} 没有有效的frontmatter格式`);
-          continue;
-        }
-
-        let jsYaml: any;
-        try {
-          jsYaml = await import('js-yaml');
-          if (jsYaml.default) jsYaml = jsYaml.default;
-        } catch (e) {
-          logger.warn(`Unable to import js-yaml module: ${e}`);
-          continue;
-        }
-
-        const metadata = jsYaml.load(match[1]);
-        if (!metadata || !metadata.name || !metadata.description) {
-          logger.debug(`Agent文件 ${agentMdPath} 缺少必需的 name/description 字段`);
-          continue;
-        }
-
-        if (seenNames.has(metadata.name)) {
-          logger.debug(`Agent '${metadata.name}' 已由先序目录加载，跳过: ${agentMdPath}`);
-          continue;
-        }
-        seenNames.add(metadata.name);
-
-        agents.push({
-          name: metadata.name,
-          description: metadata.description,
-          keywords: metadata.keywords || [],
-          tags: metadata.tags || [],
-          toolNames: Array.isArray(metadata.tools) ? metadata.tools : [],
-          filePath: agentMdPath,
-          model: metadata.model,
-          provider: metadata.provider,
-          maxIterations: typeof metadata.maxIterations === 'number' ? metadata.maxIterations : undefined,
-        });
-        logger.debug(`Agent发现成功: ${metadata.name}`);
-      } catch (e) {
-        logger.warn(`Failed to parse agent.md in ${agentMdPath}:`, e);
-      }
-    }
-  }
-
-  if (agents.length > 0) {
-    logger.info(`发现 ${agents.length} 个工作区 Agent 预设: ${agents.map(a => a.name).join(', ')}`);
-  }
-
-  return agents;
-}
-
-// ============================================================================
-// Tool 发现（*.tool.md 文件）
-// ============================================================================
-
-/**
- * 简写参数定义（*.tool.md frontmatter 中使用）
- */
-export interface ToolParamShorthand {
-  type: string;
-  description?: string;
-  required?: boolean;
-  enum?: string[];
-  default?: any;
-}
-
-/**
- * Tool 元数据（从 *.tool.md frontmatter 解析）
- */
-export interface ToolMeta {
-  name: string;
-  description: string;
-  /** 简写参数定义（frontmatter 格式） */
-  parameters?: Record<string, ToolParamShorthand>;
-  /** 命令配置 */
-  command?: {
-    pattern?: string;
-    alias?: string[];
-    examples?: string[];
-  };
-  /** 支持的平台列表 */
-  platforms?: string[];
-  /** 支持的场景列表 */
-  scopes?: string[];
-  /** 权限级别 */
-  permissionLevel?: string;
-  /** 标签 */
-  tags?: string[];
-  /** 触发关键词 */
-  keywords?: string[];
-  /** 工具分类 */
-  kind?: string;
-  /** 是否隐藏 */
-  hidden?: boolean;
-  /** handler 文件路径（相对于 .tool.md） */
-  handler?: string;
-  /** *.tool.md 文件的绝对路径 */
-  filePath: string;
-  /** body 内容（无 handler 时作为 prompt 模板） */
-  templateBody?: string;
-}
-
-/**
- * 从根插件树收集：根插件与直接子插件包目录下的 `tools/`
- */
-export function collectPluginToolSearchRoots(root: Plugin | null | undefined): string[] {
-  if (!root) return [];
-  const dirs: string[] = [];
-  const push = (d: string) => {
-    if (d && !dirs.includes(d)) dirs.push(d);
-  };
-  const fromPlugin = (p: Plugin) => {
-    if (!p?.filePath) return;
-    const dir = path.dirname(p.filePath);
-    push(path.join(dir, 'tools'));
-    // Also check package root when filePath is under src/ or lib/
-    const dirName = path.basename(dir);
-    if (dirName === 'src' || dirName === 'lib') {
-      push(path.join(path.dirname(dir), 'tools'));
-    }
-  };
-  fromPlugin(root);
-  for (const child of root.children || []) {
-    fromPlugin(child);
-  }
-  return dirs;
-}
-
-/**
- * 获取所有 tool 搜索目录（标准目录 + 插件包 tools/）
- */
-export function getToolSearchDirectories(root?: Plugin | null): string[] {
-  const list = [
-    path.join(process.cwd(), 'tools'),
-    path.join(os.homedir(), '.zhin', 'tools'),
-    path.join(getDataDir(), 'tools'),
-  ];
-  for (const d of collectPluginToolSearchRoots(root ?? undefined)) {
-    if (!list.includes(d)) list.push(d);
-  }
-  return list;
-}
-
-/**
- * 将简写参数定义转换为 ToolParametersSchema
- */
-function shorthandToSchema(params: Record<string, ToolParamShorthand>): import('@zhin.js/core').ToolParametersSchema {
-  const properties: Record<string, any> = {};
-  const required: string[] = [];
-  for (const [key, param] of Object.entries(params)) {
-    properties[key] = {
-      type: param.type || 'string',
-      description: param.description || key,
-    };
-    if (param.enum) properties[key].enum = param.enum;
-    if (param.default !== undefined) properties[key].default = param.default;
-    if (param.required) required.push(key);
-  }
-  return { type: 'object', properties, required: required.length > 0 ? required : undefined };
-}
-
-/**
- * 加载 handler 文件（动态 import）
- * @returns execute 函数, 或 undefined（加载失败）
- */
-async function loadToolHandler(handlerPath: string, toolMdPath: string): Promise<((args: any, context?: any) => any) | undefined> {
-  const resolved = path.resolve(path.dirname(toolMdPath), handlerPath);
-  if (!fs.existsSync(resolved)) {
-    logger.warn(`Tool handler 文件不存在: ${resolved}`);
-    return undefined;
-  }
-  try {
-    const fileUrl = `file://${resolved}?t=${Date.now()}`;
-    const mod = await import(fileUrl);
-    const fn = mod.default || mod;
-    if (typeof fn !== 'function') {
-      logger.warn(`Tool handler 未导出函数: ${resolved}`);
-      return undefined;
-    }
-    return fn;
-  } catch (e) {
-    logger.warn(`Tool handler 加载失败 (${resolved}): ${errMsg(e)}`);
-    return undefined;
-  }
-}
-
-/**
- * 从 body 构建 prompt 模板执行函数
- */
-function buildTemplateExecute(body: string): (args: Record<string, any>) => string {
-  return (args: Record<string, any>) => body.replace(/\{\{(\w+)\}\}/g, (_, k) => {
-    const val = args[k];
-    return val !== undefined && val !== null ? String(val) : '';
-  });
-}
-
-/**
- * 扫描 tools/ 目录，发现 *.tool.md 文件
- * 加载顺序与 skills/agents 一致：Workspace > ~/.zhin > data > 插件包
- * 同名先发现者优先
- */
-export async function discoverWorkspaceTools(root?: Plugin | null): Promise<ToolMeta[]> {
-  const tools: ToolMeta[] = [];
-  const seenNames = new Set<string>();
-  const toolDirs = getToolSearchDirectories(root);
-
-  for (const toolsDir of toolDirs) {
-    if (!fs.existsSync(toolsDir)) continue;
-
-    let entries: fs.Dirent[];
-    try {
-      entries = await fs.promises.readdir(toolsDir, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-
-    for (const entry of entries) {
-      // 支持两种结构：
-      // 1. tools/<name>.tool.md（扁平文件）
-      // 2. tools/<name>/<name>.tool.md（目录结构，允许放 handler.ts）
-      let toolMdPath: string | undefined;
-      if (entry.isFile() && entry.name.endsWith('.tool.md')) {
-        toolMdPath = path.join(toolsDir, entry.name);
-      } else if (entry.isDirectory()) {
-        const nested = path.join(toolsDir, entry.name, `${entry.name}.tool.md`);
-        if (fs.existsSync(nested)) {
-          toolMdPath = nested;
-        }
-      }
-      if (!toolMdPath) continue;
-
-      try {
-        const content = await fs.promises.readFile(toolMdPath, 'utf-8');
-        const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*(?:\n|$)/);
-        if (!match) {
-          logger.debug(`Tool文件 ${toolMdPath} 没有有效的frontmatter格式`);
-          continue;
-        }
-
-        let jsYaml: any;
-        try {
-          jsYaml = await import('js-yaml');
-          if (jsYaml.default) jsYaml = jsYaml.default;
-        } catch (e) {
-          logger.warn(`Unable to import js-yaml module: ${e}`);
-          continue;
-        }
-
-        const metadata = jsYaml.load(match[1]);
-        if (!metadata || !metadata.name || !metadata.description) {
-          logger.debug(`Tool文件 ${toolMdPath} 缺少必需的 name/description 字段`);
-          continue;
-        }
-
-        if (seenNames.has(metadata.name)) {
-          logger.debug(`Tool '${metadata.name}' 已由先序目录加载，跳过: ${toolMdPath}`);
-          continue;
-        }
-        seenNames.add(metadata.name);
-
-        // 提取 body（frontmatter 之后的内容）
-        const body = content.replace(/^---\s*\n[\s\S]*?\n---\s*(?:\n|$)/, '').trim();
-
-        tools.push({
-          name: metadata.name,
-          description: metadata.description,
-          parameters: metadata.parameters || undefined,
-          command: metadata.command || undefined,
-          platforms: metadata.platforms,
-          scopes: metadata.scopes,
-          permissionLevel: metadata.permissionLevel,
-          tags: metadata.tags || [],
-          keywords: metadata.keywords || [],
-          kind: metadata.kind,
-          hidden: metadata.hidden,
-          handler: metadata.handler,
-          filePath: toolMdPath,
-          templateBody: !metadata.handler && body ? body : undefined,
-        });
-        logger.debug(`Tool发现成功: ${metadata.name}`);
-      } catch (e) {
-        logger.warn(`Failed to parse tool.md in ${toolMdPath}:`, e);
-      }
-    }
-  }
-
-  if (tools.length > 0) {
-    logger.info(`发现 ${tools.length} 个工作区 Tool: ${tools.map(t => t.name).join(', ')}`);
-  }
+      }),
+  );
 
   return tools;
 }
-
-/**
- * 将 ToolMeta 转换为 Tool 对象（包含 execute 函数）
- */
-export async function buildToolFromMeta(meta: ToolMeta): Promise<import('@zhin.js/core').Tool | null> {
-  // 构建 execute 函数
-  let execute: ((args: any, context?: any) => any) | undefined;
-
-  if (meta.handler) {
-    execute = await loadToolHandler(meta.handler, meta.filePath);
-    if (!execute) return null;
-  } else if (meta.templateBody) {
-    execute = buildTemplateExecute(meta.templateBody);
-  } else {
-    logger.warn(`Tool '${meta.name}' 既没有 handler 也没有模板 body，跳过`);
-    return null;
-  }
-
-  // 构建参数 schema
-  const parameters = meta.parameters
-    ? shorthandToSchema(meta.parameters)
-    : { type: 'object' as const, properties: {} };
-
-  return {
-    name: meta.name,
-    description: meta.description,
-    parameters,
-    execute,
-    tags: meta.tags,
-    keywords: meta.keywords,
-    platforms: meta.platforms,
-    scopes: meta.scopes as any,
-    permissionLevel: meta.permissionLevel as any,
-    hidden: meta.hidden,
-    kind: meta.kind,
-    command: meta.command ? {
-      pattern: meta.command.pattern,
-      alias: meta.command.alias,
-      examples: meta.command.examples,
-    } : undefined,
-  };
-}