@zhin.js/agent 0.1.14 → 0.1.16

package/lib/builtin/bing-search-html.js

@@ -0,0 +1,116 @@
+/**
+ * Bing 搜索结果 HTML 解析（参考 claude-code-best/claude-code WebSearchTool bingAdapter）
+ * https://github.com/claude-code-best/claude-code/blob/main/packages/builtin-tools/src/tools/WebSearchTool/adapters/bingAdapter.ts
+ */
+import he from 'he';
+import { acceptLanguageForMarket, DEFAULT_WEB_SEARCH_MARKET } from './web-search-locale.js';
+export const decodeHtmlEntities = (s) => he.decode(s);
+/**
+ * 从 Bing 结果页 HTML 提取有机结果。
+ * 结果位于 <ol id="b_results"> 内 <li class="b_algo"> 块中。
+ */
+export function extractBingResults(html) {
+    const results = [];
+    const algoBlockRegex = /<li\s+class="b_algo"[^>]*>([\s\S]*?)<\/li>/gi;
+    let blockMatch;
+    while ((blockMatch = algoBlockRegex.exec(html)) !== null) {
+        const block = blockMatch[1];
+        const h2LinkRegex = /<h2[^>]*>\s*<a[^>]+href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/i;
+        const linkMatch = h2LinkRegex.exec(block);
+        if (!linkMatch)
+            continue;
+        const rawUrl = decodeHtmlEntities(linkMatch[1]);
+        const titleHtml = linkMatch[2];
+        const url = resolveBingUrl(rawUrl);
+        if (!url)
+            continue;
+        const title = decodeHtmlEntities(titleHtml.replace(/<[^>]+>/g, '').trim());
+        const snippet = extractSnippet(block);
+        results.push({ title, url, snippet });
+    }
+    return results;
+}
+function extractSnippet(block) {
+    const lineclampRegex = /<p[^>]*class="b_lineclamp[^"]*"[^>]*>([\s\S]*?)<\/p>/i;
+    let match = lineclampRegex.exec(block);
+    if (match) {
+        return decodeHtmlEntities(match[1].replace(/<[^>]+>/g, '').trim());
+    }
+    const captionPRegex = /<div[^>]*class="b_caption[^"]*"[^>]*>[\s\S]*?<p[^>]*>([\s\S]*?)<\/p>/i;
+    match = captionPRegex.exec(block);
+    if (match) {
+        return decodeHtmlEntities(match[1].replace(/<[^>]+>/g, '').trim());
+    }
+    const fallbackRegex = /<div[^>]*class="b_caption[^"]*"[^>]*>([\s\S]*?)<\/div>/i;
+    const fallbackMatch = fallbackRegex.exec(block);
+    if (fallbackMatch) {
+        const text = fallbackMatch[1].replace(/<[^>]+>/g, '').trim();
+        if (text)
+            return decodeHtmlEntities(text);
+    }
+    return undefined;
+}
+/**
+ * 将 Bing 跳转链接解析为真实 URL（/ck/a?...&u=a1aHR0cHM6Ly9...）
+ */
+export function resolveBingUrl(rawUrl) {
+    if (rawUrl.startsWith('/') || rawUrl.startsWith('#'))
+        return undefined;
+    const uMatch = rawUrl.match(/[?&]u=([a-zA-Z0-9+/_=-]+)/);
+    if (uMatch) {
+        const encoded = uMatch[1];
+        if (encoded.length >= 3) {
+            const b64 = encoded.slice(2);
+            try {
+                const padded = b64.replace(/-/g, '+').replace(/_/g, '/');
+                const decoded = Buffer.from(padded, 'base64').toString('utf-8');
+                if (decoded.startsWith('http'))
+                    return decoded;
+            }
+            catch {
+                /* fall through */
+            }
+        }
+    }
+    if (!rawUrl.includes('bing.com'))
+        return rawUrl;
+    return undefined;
+}
+/** 与 bingAdapter 一致：浏览器风格请求头（不含 Accept-Language，由 {@link bingSearchFetchHeaders} 按市场注入） */
+const BING_SEARCH_BROWSER_HEADERS_BASE = {
+    'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36 Edg/131.0.0.0',
+    Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8',
+    'Accept-Encoding': 'gzip, deflate, br',
+    'Cache-Control': 'no-cache',
+    Pragma: 'no-cache',
+    'Sec-Ch-Ua': '"Microsoft Edge";v="131", "Chromium";v="131", "Not_A Brand";v="24"',
+    'Sec-Ch-Ua-Mobile': '?0',
+    'Sec-Ch-Ua-Platform': '"macOS"',
+    'Sec-Fetch-Dest': 'document',
+    'Sec-Fetch-Mode': 'navigate',
+    'Sec-Fetch-Site': 'none',
+    'Sec-Fetch-User': '?1',
+    'Upgrade-Insecure-Requests': '1',
+};
+/** @deprecated 单测兼容：请用 {@link bingSearchFetchHeaders}；默认语言为 en-US 旧行为已弃用 */
+export const BING_SEARCH_BROWSER_HEADERS = {
+    ...BING_SEARCH_BROWSER_HEADERS_BASE,
+    'Accept-Language': 'en-US,en;q=0.9',
+};
+export function bingSearchFetchHeaders(market) {
+    return {
+        ...BING_SEARCH_BROWSER_HEADERS_BASE,
+        'Accept-Language': acceptLanguageForMarket(market),
+    };
+}
+export const BING_SEARCH_FETCH_TIMEOUT_MS = 30_000;
+export function buildBingSearchUrl(query, market = DEFAULT_WEB_SEARCH_MARKET) {
+    const mkt = encodeURIComponent(market);
+    return `https://www.bing.com/search?q=${encodeURIComponent(query)}&setmkt=${mkt}`;
+}
+export function hostnameMatchesList(hostname, domain) {
+    const h = hostname.toLowerCase();
+    const d = domain.toLowerCase().replace(/^\.+/, '');
+    return h === d || h.endsWith(`.${d}`);
+}
+//# sourceMappingURL=bing-search-html.js.map

package/lib/builtin/bing-search-html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bing-search-html.js","sourceRoot":"","sources":["../../src/builtin/bing-search-html.ts"],"names":[],"mappings":"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"}

package/lib/builtin/builtin-base-tool.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 内置系统工具基类 — 产出与 {@link ToolFeature} / {@link normalizeTool} 兼容的 {@link Tool}，
+ * 便于将核心逻辑写在可单测的 `run` 中（见 PRD #389 / issue #390）。
+ */
+import type { Tool, ToolContext, ToolParametersSchema, ToolResult } from '@zhin.js/core';
+export declare abstract class BuiltinBaseTool {
+    abstract readonly name: string;
+    abstract readonly description: string;
+    abstract readonly parameters: ToolParametersSchema;
+    /** 与 ZhinTool 链式 API 对齐 */
+    readonly tags: string[];
+    readonly keywords: string[];
+    readonly kind?: string;
+    /** 仅当为 true 时写入 Tool */
+    readonly preExecutable?: boolean;
+    /**
+     * 核心执行逻辑（单测优先覆盖此处）。
+     */
+    abstract run(args: Record<string, unknown>, context?: ToolContext): Promise<ToolResult>;
+    /**
+     * 注册到 ToolFeature；带 `source` 以便 `normalizeTool` 识别为 IM 工具形态并绑定 context。
+     */
+    toTool(): Tool;
+}
+//# sourceMappingURL=builtin-base-tool.d.ts.map

package/lib/builtin/builtin-base-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-base-tool.d.ts","sourceRoot":"","sources":["../../src/builtin/builtin-base-tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEzF,8BAAsB,eAAe;IACnC,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;IAEnD,2BAA2B;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAM;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAM;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,wBAAwB;IACxB,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAEvF;;OAEG;IACH,MAAM,IAAI,IAAI;CAcf"}

package/lib/builtin/builtin-base-tool.js

@@ -0,0 +1,30 @@
+export class BuiltinBaseTool {
+    /** 与 ZhinTool 链式 API 对齐 */
+    tags = [];
+    keywords = [];
+    kind;
+    /** 仅当为 true 时写入 Tool */
+    preExecutable;
+    /**
+     * 注册到 ToolFeature；带 `source` 以便 `normalizeTool` 识别为 IM 工具形态并绑定 context。
+     */
+    toTool() {
+        const tool = {
+            name: this.name,
+            description: this.description,
+            parameters: this.parameters,
+            source: 'builtin:agent',
+            execute: async (args, ctx) => this.run(args, ctx),
+        };
+        if (this.tags.length)
+            tool.tags = [...this.tags];
+        if (this.keywords.length)
+            tool.keywords = [...this.keywords];
+        if (this.kind)
+            tool.kind = this.kind;
+        if (this.preExecutable)
+            tool.preExecutable = true;
+        return tool;
+    }
+}
+//# sourceMappingURL=builtin-base-tool.js.map

package/lib/builtin/builtin-base-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-base-tool.js","sourceRoot":"","sources":["../../src/builtin/builtin-base-tool.ts"],"names":[],"mappings":"AAMA,MAAM,OAAgB,eAAe;IAKnC,2BAA2B;IAClB,IAAI,GAAa,EAAE,CAAC;IACpB,QAAQ,GAAa,EAAE,CAAC;IACxB,IAAI,CAAU;IACvB,wBAAwB;IACf,aAAa,CAAW;IAOjC;;OAEG;IACH,MAAM;QACJ,MAAM,IAAI,GAAS;YACjB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,MAAM,EAAE,eAAe;YACvB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAA+B,EAAE,GAAG,CAAC;SAC7E,CAAC;QACF,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,IAAI,CAAC,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM;YAAE,IAAI,CAAC,QAAQ,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC7D,IAAI,IAAI,CAAC,IAAI;YAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACrC,IAAI,IAAI,CAAC,aAAa;YAAE,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;QAClD,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/lib/builtin/edit-file-tool.d.ts

@@ -0,0 +1,13 @@
+import type { Tool, ToolContext, ToolParametersSchema, ToolResult } from '@zhin.js/core';
+import { BuiltinBaseTool } from './builtin-base-tool.js';
+export declare const EDIT_FILE_PARAMETERS: ToolParametersSchema;
+export declare class EditFileBuiltinTool extends BuiltinBaseTool {
+    readonly name = "edit_file";
+    readonly description = "\u5728\u6587\u4EF6\u4E2D\u67E5\u627E\u5E76\u66FF\u6362\u4E00\u6BB5\u6587\u672C\u3002old_string \u5FC5\u987B\u5728\u6587\u4EF6\u4E2D\u7CBE\u786E\u5B58\u5728\u4E14\u552F\u4E00\uFF1B\u5EFA\u8BAE\u5305\u542B\u5B8C\u6574\u884C\u6216\u8DB3\u591F\u4E0A\u4E0B\u6587\u4EE5\u907F\u514D\u91CD\u590D\u5339\u914D\u3002\u652F\u6301\u5F2F\u5F15\u53F7/\u76F4\u5F15\u53F7\u81EA\u52A8\u5F52\u4E00\u5316\u3002";
+    readonly parameters: ToolParametersSchema<Record<string, any>>;
+    readonly kind = "file";
+    constructor();
+    run(args: Record<string, unknown>, _context?: ToolContext): Promise<ToolResult>;
+}
+export declare function createEditFileTool(): Tool;
+//# sourceMappingURL=edit-file-tool.d.ts.map

package/lib/builtin/edit-file-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit-file-tool.d.ts","sourceRoot":"","sources":["../../src/builtin/edit-file-tool.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAOzF,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAMzD,eAAO,MAAM,oBAAoB,EAAE,oBAWlC,CAAC;AAEF,qBAAa,mBAAoB,SAAQ,eAAe;IACtD,QAAQ,CAAC,IAAI,eAAe;IAC5B,QAAQ,CAAC,WAAW,4YAC4D;IAChF,QAAQ,CAAC,UAAU,4CAAwB;IAC3C,QAAQ,CAAC,IAAI,UAAU;;IAiBjB,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;CAkDtF;AAED,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/lib/builtin/edit-file-tool.js

@@ -0,0 +1,81 @@
+/**
+ * edit_file — 内置查找替换编辑
+ */
+import * as fs from 'node:fs/promises';
+import { assertFileAccess, MAX_EDIT_FILE_SIZE, isFileStale, } from '../security/file-policy.js';
+import { expandHome, nodeErrToFileMessage } from '../discovery/utils.js';
+import { BuiltinBaseTool } from './builtin-base-tool.js';
+import { findActualStringInFile, preserveQuoteStyleInEdit, } from './file-edit-quote-utils.js';
+export const EDIT_FILE_PARAMETERS = {
+    type: 'object',
+    properties: {
+        file_path: { type: 'string', description: '要编辑的文件路径' },
+        old_string: {
+            type: 'string',
+            description: '文件中要替换的原文（必须与文件内容完全一致）',
+        },
+        new_string: { type: 'string', description: '替换后的新文本' },
+    },
+    required: ['file_path', 'old_string', 'new_string'],
+};
+export class EditFileBuiltinTool extends BuiltinBaseTool {
+    name = 'edit_file';
+    description = '在文件中查找并替换一段文本。old_string 必须在文件中精确存在且唯一；建议包含完整行或足够上下文以避免重复匹配。支持弯引号/直引号自动归一化。';
+    parameters = EDIT_FILE_PARAMETERS;
+    kind = 'file';
+    constructor() {
+        super();
+        this.tags.push('file', 'edit');
+        this.keywords.push('编辑文件', '修改文件', '替换内容', '查找替换', 'edit file', 'edit', '修改', '替换');
+    }
+    async run(args, _context) {
+        const filePathArg = args.file_path;
+        const oldStringArg = args.old_string;
+        const newStringArg = args.new_string;
+        if (typeof filePathArg !== 'string' || !filePathArg.trim()) {
+            return 'Error: file_path is required';
+        }
+        if (typeof oldStringArg !== 'string') {
+            return 'Error: old_string is required';
+        }
+        if (typeof newStringArg !== 'string') {
+            return 'Error: new_string is required';
+        }
+        try {
+            const fp = expandHome(filePathArg);
+            assertFileAccess(fp);
+            const stat = await fs.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 限制。`;
+            }
+            const mtimeBefore = stat.mtimeMs;
+            const content = await fs.readFile(fp, 'utf-8');
+            const matchResult = findActualStringInFile(content, oldStringArg);
+            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(oldStringArg, matchResult.actual, newStringArg)
+                : newStringArg;
+            const newContent = content.replace(matchResult.actual, effectiveNew);
+            const currentStat = await fs.stat(fp);
+            if (isFileStale(mtimeBefore, currentStat.mtimeMs)) {
+                return `Error: 文件 ${fp} 在读取后被外部修改。请重新读取文件后再编辑，避免覆盖他人的修改。`;
+            }
+            await fs.writeFile(fp, newContent, 'utf-8');
+            const oldLines = oldStringArg.split('\n');
+            const newLines = newStringArg.split('\n');
+            return `✅ Edited ${fp}\n--- before ---\n${oldLines.slice(0, 5).join('\n')}${oldLines.length > 5 ? '\n...' : ''}\n--- after ---\n${newLines.slice(0, 5).join('\n')}${newLines.length > 5 ? '\n...' : ''}`;
+        }
+        catch (e) {
+            return nodeErrToFileMessage(e, String(filePathArg), 'edit');
+        }
+    }
+}
+export function createEditFileTool() {
+    return new EditFileBuiltinTool().toTool();
+}
+//# sourceMappingURL=edit-file-tool.js.map

package/lib/builtin/edit-file-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit-file-tool.js","sourceRoot":"","sources":["../../src/builtin/edit-file-tool.ts"],"names":[],"mappings":"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"}

package/lib/builtin/file-edit-quote-utils.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 引号归一化 + 模糊匹配（参考 Claude Code FileEditTool/utils.ts），供 edit_file 使用。
+ */
+/** 将弯引号归一化为直引号 */
+export declare function normalizeQuotes(str: string): string;
+export interface FuzzyMatchResult {
+    /** 文件中实际匹配到的字符串 */
+    actual: string;
+    /** 匹配次数 */
+    count: number;
+    /** 是否通过引号归一化匹配 */
+    wasNormalized: boolean;
+}
+/**
+ * 在文件内容中查找字符串，支持精确匹配和引号归一化模糊匹配。
+ * 参考 Claude Code `findActualString`。
+ */
+export declare function findActualStringInFile(fileContent: string, searchString: string): FuzzyMatchResult | null;
+/**
+ * 将 new_string 中的直引号替换为文件中原始的弯引号风格。
+ * 参考 Claude Code `preserveQuoteStyle`。
+ */
+export declare function preserveQuoteStyleInEdit(oldString: string, actualOldString: string, newString: string): string;
+//# sourceMappingURL=file-edit-quote-utils.d.ts.map

package/lib/builtin/file-edit-quote-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-edit-quote-utils.d.ts","sourceRoot":"","sources":["../../src/builtin/file-edit-quote-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,kBAAkB;AAClB,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMnD;AAED,MAAM,WAAW,gBAAgB;IAC/B,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW;IACX,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAgBzG;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CA0C9G"}

package/lib/builtin/file-edit-quote-utils.js

@@ -0,0 +1,81 @@
+/**
+ * 引号归一化 + 模糊匹配（参考 Claude Code FileEditTool/utils.ts），供 edit_file 使用。
+ */
+/** 将弯引号归一化为直引号 */
+export function normalizeQuotes(str) {
+    return str
+        .replace(/\u2018/g, "'") // '
+        .replace(/\u2019/g, "'") // '
+        .replace(/\u201C/g, '"') // "
+        .replace(/\u201D/g, '"'); // "
+}
+/**
+ * 在文件内容中查找字符串，支持精确匹配和引号归一化模糊匹配。
+ * 参考 Claude Code `findActualString`。
+ */
+export function findActualStringInFile(fileContent, searchString) {
+    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 null;
+}
+/**
+ * 将 new_string 中的直引号替换为文件中原始的弯引号风格。
+ * 参考 Claude Code `preserveQuoteStyle`。
+ */
+export function preserveQuoteStyleInEdit(oldString, actualOldString, newString) {
+    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 = [];
+        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('');
+    }
+    if (hasSingle) {
+        const chars = [...result];
+        const out = [];
+        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 result;
+}
+//# sourceMappingURL=file-edit-quote-utils.js.map

package/lib/builtin/file-edit-quote-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-edit-quote-utils.js","sourceRoot":"","sources":["../../src/builtin/file-edit-quote-utils.ts"],"names":[],"mappings":"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"}

package/lib/builtin/glob-tool.d.ts

@@ -0,0 +1,23 @@
+/**
+ * glob — 按 glob 模式查找文件
+ */
+import { type ExecOptions } from 'node:child_process';
+import type { Tool, ToolContext, ToolParametersSchema, ToolResult } from '@zhin.js/core';
+import { BuiltinBaseTool } from './builtin-base-tool.js';
+/** 可注入以便单测（默认 `promisify(exec)`） */
+export type GlobExecAsync = (command: string, options?: ExecOptions) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare const GLOB_PARAMETERS: ToolParametersSchema;
+export declare class GlobBuiltinTool extends BuiltinBaseTool {
+    private readonly execAsync;
+    readonly name = "glob";
+    readonly description = "\u6309 glob \u6A21\u5F0F\u67E5\u627E\u5339\u914D\u7684\u6587\u4EF6\u8DEF\u5F84\uFF08\u5982 **/*.ts\uFF09\u3002\u7528\u4E8E\u6309\u6A21\u5F0F\u627E\u6587\u4EF6\uFF0C\u800C\u975E\u5217\u51FA\u76EE\u5F55\u3002";
+    readonly parameters: ToolParametersSchema<Record<string, any>>;
+    readonly kind = "file";
+    constructor(execAsync?: GlobExecAsync);
+    run(args: Record<string, unknown>, _context?: ToolContext): Promise<ToolResult>;
+}
+export declare function createGlobTool(): Tool;
+//# sourceMappingURL=glob-tool.d.ts.map

package/lib/builtin/glob-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob-tool.d.ts","sourceRoot":"","sources":["../../src/builtin/glob-tool.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAQ,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAE5D,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGzF,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAIzD,oCAAoC;AACpC,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,WAAW,KAClB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEjD,eAAO,MAAM,eAAe,EAAE,oBAO7B,CAAC;AAEF,qBAAa,eAAgB,SAAQ,eAAe;IAOtC,OAAO,CAAC,QAAQ,CAAC,SAAS;IANtC,QAAQ,CAAC,IAAI,UAAU;IACvB,QAAQ,CAAC,WAAW,oNAC+B;IACnD,QAAQ,CAAC,UAAU,4CAAmB;IACtC,QAAQ,CAAC,IAAI,UAAU;gBAEM,SAAS,GAAE,aAAgC;IAMlE,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;CAsBtF;AAED,wBAAgB,cAAc,IAAI,IAAI,CAErC"}

package/lib/builtin/glob-tool.js

@@ -0,0 +1,54 @@
+/**
+ * glob — 按 glob 模式查找文件
+ */
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import { assertFileAccess, shellEscape } from '../security/file-policy.js';
+import { errMsg } from '../discovery/utils.js';
+import { BuiltinBaseTool } from './builtin-base-tool.js';
+const defaultExecAsync = promisify(exec);
+export const GLOB_PARAMETERS = {
+    type: 'object',
+    properties: {
+        pattern: { type: 'string', description: 'Glob 模式（如 **/*.ts）' },
+        cwd: { type: 'string', description: '工作目录（默认项目根目录）' },
+    },
+    required: ['pattern'],
+};
+export class GlobBuiltinTool extends BuiltinBaseTool {
+    execAsync;
+    name = 'glob';
+    description = '按 glob 模式查找匹配的文件路径（如 **/*.ts）。用于按模式找文件，而非列出目录。';
+    parameters = GLOB_PARAMETERS;
+    kind = 'file';
+    constructor(execAsync = defaultExecAsync) {
+        super();
+        this.execAsync = execAsync;
+        this.tags.push('file', 'search');
+        this.keywords.push('glob', '查找文件', '按模式找文件', 'find', '匹配文件');
+    }
+    async run(args, _context) {
+        const patternArg = args.pattern;
+        if (typeof patternArg !== 'string' || !patternArg.trim()) {
+            return 'Error: pattern is required';
+        }
+        try {
+            const cwdRaw = args.cwd;
+            const cwd = typeof cwdRaw === 'string' && cwdRaw.trim() ? cwdRaw : process.cwd();
+            assertFileAccess(cwd);
+            const safePattern = shellEscape(patternArg);
+            const { stdout } = await this.execAsync(`find . -path ./${safePattern} -type f 2>/dev/null | head -100`, { cwd });
+            const files = stdout.trim().split('\n').filter(Boolean);
+            return files.length === 0
+                ? `No files matching '${patternArg}'`
+                : `Found ${files.length} files:\n${files.join('\n')}`;
+        }
+        catch (e) {
+            return `Error: ${errMsg(e)}`;
+        }
+    }
+}
+export function createGlobTool() {
+    return new GlobBuiltinTool().toTool();
+}
+//# sourceMappingURL=glob-tool.js.map

package/lib/builtin/glob-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob-tool.js","sourceRoot":"","sources":["../../src/builtin/glob-tool.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,IAAI,EAAoB,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC3E,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAEzD,MAAM,gBAAgB,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;AAQzC,MAAM,CAAC,MAAM,eAAe,GAAyB;IACnD,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,oBAAoB,EAAE;QAC9D,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,eAAe,EAAE;KACtD;IACD,QAAQ,EAAE,CAAC,SAAS,CAAC;CACtB,CAAC;AAEF,MAAM,OAAO,eAAgB,SAAQ,eAAe;IAOrB;IANpB,IAAI,GAAG,MAAM,CAAC;IACd,WAAW,GAClB,gDAAgD,CAAC;IAC1C,UAAU,GAAG,eAAe,CAAC;IAC7B,IAAI,GAAG,MAAM,CAAC;IAEvB,YAA6B,YAA2B,gBAAgB;QACtE,KAAK,EAAE,CAAC;QADmB,cAAS,GAAT,SAAS,CAAkC;QAEtE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACjC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/D,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,IAA6B,EAAE,QAAsB;QAC7D,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC;QAChC,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,CAAC;YACzD,OAAO,4BAA4B,CAAC;QACtC,CAAC;QACD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC;YACxB,MAAM,GAAG,GAAG,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;YACjF,gBAAgB,CAAC,GAAG,CAAC,CAAC;YACtB,MAAM,WAAW,GAAG,WAAW,CAAC,UAAU,CAAC,CAAC;YAC5C,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,SAAS,CACrC,kBAAkB,WAAW,kCAAkC,EAC/D,EAAE,GAAG,EAAE,CACR,CAAC;YACF,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YACxD,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;gBACvB,CAAC,CAAC,sBAAsB,UAAU,GAAG;gBACrC,CAAC,CAAC,SAAS,KAAK,CAAC,MAAM,YAAY,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1D,CAAC;QAAC,OAAO,CAAU,EAAE,CAAC;YACpB,OAAO,UAAU,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/B,CAAC;IACH,CAAC;CACF;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO,IAAI,eAAe,EAAE,CAAC,MAAM,EAAE,CAAC;AACxC,CAAC"}

package/lib/builtin/grep-tool.d.ts

@@ -0,0 +1,23 @@
+/**
+ * grep — 按正则搜索文件内容（ripgrep 优先，grep 回退）
+ */
+import { type ExecOptions } from 'node:child_process';
+import type { Tool, ToolContext, ToolParametersSchema, ToolResult } from '@zhin.js/core';
+import { BuiltinBaseTool } from './builtin-base-tool.js';
+/** 可注入以便单测（默认 `promisify(exec)`） */
+export type GrepExecAsync = (command: string, options?: ExecOptions) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare const GREP_PARAMETERS: ToolParametersSchema;
+export declare class GrepBuiltinTool extends BuiltinBaseTool {
+    private readonly execAsync;
+    readonly name = "grep";
+    readonly description = "\u6309\u6B63\u5219\u641C\u7D22\u6587\u4EF6\u5185\u5BB9\uFF0C\u8FD4\u56DE\u5339\u914D\u884C\u548C\u884C\u53F7\u3002\u4F18\u5148\u4F7F\u7528 ripgrep (rg)\uFF0C\u56DE\u9000\u5230 grep\u3002";
+    readonly parameters: ToolParametersSchema<Record<string, any>>;
+    readonly kind = "file";
+    constructor(execAsync?: GrepExecAsync);
+    run(args: Record<string, unknown>, _context?: ToolContext): Promise<ToolResult>;
+}
+export declare function createGrepTool(): Tool;
+//# sourceMappingURL=grep-tool.d.ts.map

package/lib/builtin/grep-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grep-tool.d.ts","sourceRoot":"","sources":["../../src/builtin/grep-tool.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAQ,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAG5D,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGzF,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAIzD,oCAAoC;AACpC,MAAM,MAAM,aAAa,GAAG,CAC1B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,WAAW,KAClB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEjD,eAAO,MAAM,eAAe,EAAE,oBAc7B,CAAC;AAEF,qBAAa,eAAgB,SAAQ,eAAe;IAOtC,OAAO,CAAC,QAAQ,CAAC,SAAS;IANtC,QAAQ,CAAC,IAAI,UAAU;IACvB,QAAQ,CAAC,WAAW,gMAC+B;IACnD,QAAQ,CAAC,UAAU,4CAAmB;IACtC,QAAQ,CAAC,IAAI,UAAU;gBAEM,SAAS,GAAE,aAAgC;IAMlE,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;CAuEtF;AAED,wBAAgB,cAAc,IAAI,IAAI,CAErC"}