@zooique/memora 0.1.0

package/dist/agent/builtinToolHandlers.js

@@ -0,0 +1,388 @@
+/**
+ * 内置工具处理器（从 ToolExecutor 提取的内置工具实现层）
+ *
+ * 职责：
+ *   1. 路径安全解析（resolveSafePath + guardPathOrThrow）—— 内置 + 自定义工具共享
+ *   2. 内置工具实现（read_file / write_file / list_dir / search_memories）
+ *   3. 文件写入内容计算（computeWriteContent）
+ *   4. 目录递归遍历（walkDir + shouldIgnore）
+ *
+ * 设计理由（QC-R2-10）：ToolExecutor 802 行超阈值，内置工具实现（~440 行）
+ * 是独立职责——实际文件系统/记忆索引操作，与 ToolExecutor 的注册/分发/校验职责分离。
+ *
+ * 自然生长原则：BuiltinToolHandlers 不持有 customTools 注册表（避免与 ToolExecutor 状态耦合），
+ * 所有方法接收参数，是无状态的纯计算 + I/O 操作。
+ */
+import { readFile, writeFile, mkdir, readdir, stat, access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { resolve, isAbsolute, join, relative, dirname, basename } from 'node:path';
+import { toolError, MemoraError, ToolErrorCode, toError } from '../utils/errors.js';
+import { logger } from '../logging/logger.js';
+import { segmentText } from '../utils/segmenter.js';
+/**
+ * 内置工具处理器
+ *
+ * 管理 4 个内置工具的实际实现 + 路径安全校验。
+ * 从 ToolExecutor 提取，保持无状态设计（不持有 customTools 注册表）。
+ */
+export class BuiltinToolHandlers {
+    projectPath;
+    security;
+    memoryIndex;
+    workProjection;
+    /** list_dir 默认忽略的目录/文件名 */
+    static IGNORED_DIR_NAMES = [
+        '.git',
+        'node_modules',
+        '.memora',
+        'dist',
+        'coverage',
+        '.next',
+    ];
+    /**
+     * @param projectPath 项目根路径（用于相对路径解析）
+     * @param security 安全守卫（路径白名单 + 写入确认）
+     * @param memoryIndex 记忆索引（用于 search_memories 工具）
+     * @param workProjection 作品投影管理器（可选，读取文件时自动生成投影）
+     */
+    constructor(projectPath, security, memoryIndex, workProjection) {
+        this.projectPath = projectPath;
+        this.security = security;
+        this.memoryIndex = memoryIndex;
+        this.workProjection = workProjection;
+    }
+    // ─── 路径安全（内置 + 自定义工具共享） ──────────────────────────
+    /**
+     * 解析相对路径为绝对路径
+     *
+     * 绝对路径直接使用（安全校验由下游 guardPathOrThrow → SecurityGuard.assertPathAllowed 完成）；
+     * 相对路径基于 projectPath 解析。防御纵深：resolveSafePath 只负责路径解析，
+     * 白名单拦截由 assertPathAllowed 独立执行。
+     */
+    resolveSafePath(relativePath) {
+        return isAbsolute(relativePath) ? relativePath : resolve(this.projectPath, relativePath);
+    }
+    /**
+     * 路径白名单校验（捕获后包装为 toolError）
+     * @param source S-02: 调用链来源标记
+     */
+    guardPathOrThrow(absolutePath, tool, source = 'builtin') {
+        try {
+            this.security.assertPathAllowed(absolutePath, tool, source);
+        }
+        catch (err) {
+            const e = toError(err);
+            throw toolError('路径不在白名单内', e.message, [
+                '确认路径在白名单内（项目目录/数据目录/显式 allowedPaths）',
+                '查看审计日志：~/.memora/logs/memora.log',
+            ], e, ToolErrorCode.PATH_NOT_ALLOWED);
+        }
+    }
+    // ─── 内置工具实现 ──────────────────────────────────────
+    /**
+     * 读取文件（带路径白名单校验）
+     */
+    async readFile(relativePath) {
+        if (!relativePath) {
+            throw toolError('read_file 工具调用缺少 path 参数', 'LLM 未传 path', ['检查 personality.md 是否明确了 read_file 用法', '检查 LLM 输出'], undefined, ToolErrorCode.ARGUMENT_ERROR);
+        }
+        const absolutePath = this.resolveSafePath(relativePath);
+        this.guardPathOrThrow(absolutePath, 'read_file');
+        try {
+            const content = await readFile(absolutePath, 'utf-8');
+            // 读取文件时自动触发生成/更新作品投影（fire-and-forget，不阻塞读取）
+            if (this.workProjection) {
+                this.workProjection.ensureProjection(absolutePath, content, relativePath).catch((err) => {
+                    logger.warn({ err, path: absolutePath }, '作品投影生成失败');
+                });
+            }
+            return content;
+        }
+        catch (err) {
+            const e = toError(err);
+            // 区分 ENOENT（文件不存在）和其他 IO 错误
+            if (e instanceof MemoraError)
+                throw e;
+            if (err !== null &&
+                typeof err === 'object' &&
+                'code' in err &&
+                err.code === 'ENOENT') {
+                throw toolError('read_file 文件不存在', `${absolutePath}：文件不存在`, ['确认路径正确', '使用 list_dir 查看目录结构'], e, ToolErrorCode.FILE_NOT_FOUND);
+            }
+            throw toolError('read_file 读取失败', `${absolutePath}：${e.message}`, ['确认文件权限', '确认路径正确'], e, ToolErrorCode.UNKNOWN);
+        }
+    }
+    /**
+     * 写入文件（支持 overwrite / append / insert 三种模式）
+     *
+     * 安全策略：
+     *   - 路径必须在白名单内
+     *   - 写入前需用户确认（WriteExtensions.onBeforeWrite 或 SecurityGuard.requestWriteConfirmation）
+     *   - 自动创建不存在的父目录
+     *
+     * @param relativePath 相对项目根的文件路径
+     * @param content 要写入的内容
+     * @param extensions 写入扩展（可选，用于 diff 确认等）
+     * @param mode 写入模式："overwrite" | "append" | "insert"，默认 "overwrite"
+     * @param insertLine insert 模式下的目标行号（从 1 开始），省略则插入到末尾
+     */
+    async writeFile(relativePath, content, extensions, mode = 'overwrite', insertLine) {
+        if (!relativePath) {
+            throw toolError('write_file 工具调用缺少 path 参数', 'LLM 未传 path', ['检查 personality.md 是否明确了 write_file 用法'], undefined, ToolErrorCode.ARGUMENT_ERROR);
+        }
+        if (typeof content !== 'string') {
+            throw toolError('write_file 工具调用缺少 content 参数', 'LLM 未传 content', ['确认 content 是字符串'], undefined, ToolErrorCode.ARGUMENT_ERROR);
+        }
+        // 校验 mode 参数合法性
+        const validModes = ['overwrite', 'append', 'insert'];
+        if (!validModes.includes(mode)) {
+            throw toolError('write_file 参数错误', `mode 必须是 ${validModes.join('/')} 之一，收到：${mode}`, ['检查 LLM 输出的 mode 参数'], undefined, ToolErrorCode.ARGUMENT_ERROR);
+        }
+        // insert 模式必须提供 insert_line
+        if (mode === 'insert' && !insertLine) {
+            throw toolError('write_file 参数错误', 'insert 模式必须提供 insert_line 参数', ['insert_line 指定插入位置的行号（从 1 开始）'], undefined, ToolErrorCode.ARGUMENT_ERROR);
+        }
+        const absolutePath = this.resolveSafePath(relativePath);
+        this.guardPathOrThrow(absolutePath, 'write_file');
+        // 读取文件旧内容（如果存在）
+        let beforeContent = null;
+        try {
+            await access(absolutePath, constants.F_OK);
+            beforeContent = await readFile(absolutePath, 'utf-8');
+        }
+        catch {
+            // 文件不存在 → 新文件，beforeContent 保持 null
+        }
+        // 根据 mode 计算最终写入内容
+        const finalContent = this.computeWriteContent(mode, content, beforeContent, insertLine);
+        // 写入确认：优先使用 WriteExtensions.onBeforeWrite（diff 确认），
+        // 否则回退到 SecurityGuard.requestWriteConfirmation（安全确认）
+        if (extensions?.onBeforeWrite) {
+            let ok;
+            try {
+                ok = await extensions.onBeforeWrite(relativePath, beforeContent, finalContent);
+            }
+            catch (err) {
+                const e = toError(err);
+                throw toolError('写入确认失败', `写入确认回调异常：${e.message}`, ['重试写入操作', '检查扩展实现是否有 bug'], e, ToolErrorCode.UNKNOWN);
+            }
+            if (!ok) {
+                throw toolError('用户拒绝写入', `用户取消了 write_file 操作：${absolutePath}`, ['如需写入，请重新发起请求并确认'], undefined, ToolErrorCode.WRITE_REJECTED);
+            }
+        }
+        else {
+            // 回退到原有安全确认流程
+            const description = `写入 ${finalContent.length} 字符到 ${basename(absolutePath)}（模式：${mode}）`;
+            let confirmed;
+            try {
+                confirmed = await this.security.requestWriteConfirmation(absolutePath, 'write_file', description);
+            }
+            catch (err) {
+                const e = toError(err);
+                throw toolError('写入确认失败', `安全确认异常：${e.message}`, ['重试写入操作'], e, ToolErrorCode.UNKNOWN);
+            }
+            if (!confirmed) {
+                throw toolError('用户拒绝写入', `用户取消了 write_file 操作：${absolutePath}`, ['如需写入，请重新发起请求并确认'], undefined, ToolErrorCode.WRITE_REJECTED);
+            }
+        }
+        // 自动创建父目录（mkdir recursive）
+        const parentDir = dirname(absolutePath);
+        try {
+            await mkdir(parentDir, { recursive: true });
+        }
+        catch (err) {
+            const e = toError(err);
+            throw toolError('创建目录失败', `无法创建父目录 ${parentDir}：${e.message}`, ['确认父目录路径可写', '检查磁盘权限'], e, ToolErrorCode.PERMISSION_DENIED);
+        }
+        try {
+            await writeFile(absolutePath, finalContent, 'utf-8');
+            // 返回结果包含写入模式、行数变化等信息
+            const newLines = finalContent.split('\n').length;
+            const oldLines = beforeContent !== null ? beforeContent.split('\n').length : 0;
+            const modeLabel = mode === 'overwrite' ? '覆盖' : mode === 'append' ? '追加' : `插入到第${insertLine}行`;
+            return (`✅ 已写入（${modeLabel}）：${absolutePath}（${finalContent.length} 字符，${newLines} 行）` +
+                (beforeContent !== null ? ` [旧文件: ${oldLines} 行]` : ' [新文件]'));
+        }
+        catch (err) {
+            const e = toError(err);
+            throw toolError('文件写入失败', `${absolutePath}：${e.message}`, ['确认父目录可写', '确认磁盘空间充足'], e, ToolErrorCode.PERMISSION_DENIED);
+        }
+    }
+    /**
+     * 根据写入模式计算最终文件内容
+     *
+     * @param mode 写入模式
+     * @param content LLM 提供的写入内容
+     * @param beforeContent 文件旧内容（null 表示新文件）
+     * @param insertLine insert 模式下的行号
+     * @returns 最终要写入文件的完整内容
+     */
+    computeWriteContent(mode, content, beforeContent, insertLine) {
+        switch (mode) {
+            case 'overwrite':
+                // 全量覆盖：直接使用 content
+                return content;
+            case 'append':
+                // 追加模式：旧内容 + 新内容
+                if (beforeContent === null) {
+                    // 新文件等同于 overwrite
+                    return content;
+                }
+                return beforeContent + content;
+            case 'insert': {
+                // 插入模式：在指定行号前插入
+                if (beforeContent === null) {
+                    // 新文件等同于 overwrite
+                    return content;
+                }
+                const lineNum = Number.parseInt(insertLine ?? '1', 10);
+                if (Number.isNaN(lineNum) || lineNum < 1) {
+                    throw toolError('write_file 参数错误', `insert_line 必须是正整数，收到：${insertLine}`, ['insert_line 从 1 开始计数'], undefined, ToolErrorCode.ARGUMENT_ERROR);
+                }
+                const lines = beforeContent.split('\n');
+                // 行号超出范围时追加到末尾
+                const insertIdx = Math.min(lineNum - 1, lines.length);
+                lines.splice(insertIdx, 0, content);
+                return lines.join('\n');
+            }
+            default:
+                // 理论上不会到达（writeFile 已校验 mode），防御性兜底
+                return content;
+        }
+    }
+    /**
+     * 列出目录内容
+     *
+     * 安全策略：
+     *   - 路径必须在白名单内
+     *   - 递归深度 ≤ 3（maxDepth 入参强校验）
+     *   - 自动忽略：.git / node_modules / .memora / dist / coverage
+     */
+    async listDir(relativePath, recursiveStr, maxDepthStr) {
+        const absolutePath = this.resolveSafePath(relativePath);
+        this.guardPathOrThrow(absolutePath, 'list_dir');
+        const recursive = recursiveStr === 'true' || recursiveStr === '1';
+        let maxDepth = Number.parseInt(maxDepthStr, 10);
+        if (Number.isNaN(maxDepth) || maxDepth < 1) {
+            maxDepth = 2;
+        }
+        if (maxDepth > 3) {
+            maxDepth = 3;
+        }
+        let stats;
+        try {
+            stats = await stat(absolutePath);
+        }
+        catch (err) {
+            // stat 调用失败：区分 ENOENT（不存在）和其他 IO 错误
+            if (err !== null &&
+                typeof err === 'object' &&
+                'code' in err &&
+                err.code === 'ENOENT') {
+                const e = toError(err);
+                throw toolError('list_dir 路径不存在', `${absolutePath}：目录不存在`, ['确认路径存在', '使用 list_dir(".") 列出项目根'], e, ToolErrorCode.DIR_NOT_FOUND);
+            }
+            // 其他 IO 错误（如权限问题），包装为统一的 TOOL_ERROR
+            const e = toError(err);
+            throw toolError('list_dir 访问失败', `${absolutePath}：${e.message}`, ['确认目录权限', '尝试其他路径'], e, ToolErrorCode.UNKNOWN);
+        }
+        // stat 成功，检查是否为目录
+        if (!stats.isDirectory()) {
+            throw toolError('list_dir 路径不是目录', `${absolutePath} 是文件，不是目录`, ['path 参数必须指向目录'], undefined, ToolErrorCode.DIR_NOT_FOUND);
+        }
+        const entries = [];
+        await this.walkDir(absolutePath, absolutePath, entries, 0, maxDepth, recursive);
+        if (entries.length === 0) {
+            return `（目录为空或所有条目都被忽略）${absolutePath}`;
+        }
+        return `目录 ${absolutePath} 共有 ${entries.length} 个条目：\n${entries.map((e) => `  ${e}`).join('\n')}`;
+    }
+    /**
+     * 递归遍历目录（深度受限 + 忽略特定目录）
+     */
+    async walkDir(root, current, out, depth, maxDepth, recursive) {
+        if (depth > maxDepth)
+            return;
+        let names;
+        try {
+            names = await readdir(current);
+        }
+        catch (err) {
+            logger.debug({ err, dir: current }, 'readdir 失败，跳过');
+            return;
+        }
+        names.sort();
+        for (const name of names) {
+            // 忽略：.git / node_modules / .memora / dist / coverage
+            if (this.shouldIgnore(name))
+                continue;
+            const childAbs = join(current, name);
+            const childRel = relative(root, childAbs);
+            try {
+                const childStat = await stat(childAbs);
+                if (childStat.isDirectory()) {
+                    out.push(`📁 ${childRel}/`);
+                    // 递归条件：未达到 maxDepth（depth+1 < maxDepth）
+                    // maxDepth=1 → 0+1<1=false 不递归；maxDepth=2 → 0+1<2=true 递归 1 层
+                    if (recursive && depth + 1 < maxDepth) {
+                        await this.walkDir(root, childAbs, out, depth + 1, maxDepth, recursive);
+                    }
+                }
+                else {
+                    out.push(`📄 ${childRel}`);
+                }
+            }
+            catch (err) {
+                // 跳过无法访问的条目（符号链接断开、权限不足等）
+                out.push(`❓ ${childRel}（无法访问：${toError(err).message}）`);
+            }
+        }
+    }
+    /**
+     * 判断目录/文件名是否应被忽略
+     */
+    shouldIgnore(name) {
+        return BuiltinToolHandlers.IGNORED_DIR_NAMES.includes(name);
+    }
+    /**
+     * 在记忆索引中搜索
+     *
+     * @param query 搜索关键词
+     * @param limitStr 返回数量上限
+     * @param modeStr 搜索模式："match"（任一命中，默认）或 "near"（全部命中）
+     */
+    async searchMemories(query, limitStr, modeStr) {
+        if (!query) {
+            throw toolError('search_memories 工具调用缺少 query 参数', 'LLM 未传 query', ['query 不能为空'], undefined, ToolErrorCode.ARGUMENT_ERROR);
+        }
+        let limit = Number.parseInt(limitStr, 10);
+        if (Number.isNaN(limit) || limit < 1) {
+            limit = 10;
+        }
+        if (limit > 50) {
+            limit = 50;
+        }
+        const mode = modeStr === 'near' ? 'near' : 'match';
+        let results = this.memoryIndex.search(query, limit);
+        // near 模式：过滤只保留所有关键词都命中的结果
+        if (mode === 'near' && results.length > 0) {
+            // 复用 segmentText 分词，与 inMemoryStorage 搜索保持一致
+            const keywords = segmentText(query).map((t) => t.toLowerCase());
+            if (keywords.length > 1) {
+                results = results.filter((m) => {
+                    const text = `${m.content} ${m.name}`.toLowerCase();
+                    return keywords.every((kw) => text.includes(kw));
+                });
+            }
+        }
+        if (results.length === 0) {
+            return `（未找到匹配 "${query}" 的记忆${mode === 'near' ? '（near 模式：所有关键词必须命中）' : ''}）`;
+        }
+        const lines = results.map((m, i) => {
+            const preview = m.content.length > 80 ? `${m.content.slice(0, 80)}…` : m.content;
+            return `${i + 1}. [${m.source}:${m.name}] (score=${m.score})\n   ${preview.replace(/\n/g, ' ')}`;
+        });
+        return `搜索 "${query}" 找到 ${results.length} 条（${mode} 模式）：\n${lines.join('\n')}`;
+    }
+}
+//# sourceMappingURL=builtinToolHandlers.js.map

package/dist/agent/builtinToolHandlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtinToolHandlers.js","sourceRoot":"","sources":["../../src/agent/builtinToolHandlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEnF,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACnF,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AASnD;;;;;GAKG;AACH,MAAM,OAAO,mBAAmB;IAkBX;IACA;IACA;IACA;IApBnB,2BAA2B;IAC3B,MAAM,CAAU,iBAAiB,GAAsB;QACrD,MAAM;QACN,cAAc;QACd,SAAS;QACT,MAAM;QACN,UAAU;QACV,OAAO;KACR,CAAC;IAEF;;;;;OAKG;IACH,YACmB,WAAmB,EACnB,QAAuB,EACvB,WAA2B,EAC3B,cAAsC;QAHtC,gBAAW,GAAX,WAAW,CAAQ;QACnB,aAAQ,GAAR,QAAQ,CAAe;QACvB,gBAAW,GAAX,WAAW,CAAgB;QAC3B,mBAAc,GAAd,cAAc,CAAwB;IACtD,CAAC;IAEJ,oDAAoD;IAEpD;;;;;;OAMG;IACH,eAAe,CAAC,YAAoB;QAClC,OAAO,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IAC3F,CAAC;IAED;;;OAGG;IACH,gBAAgB,CACd,YAAoB,EACpB,IAAY,EACZ,SAA0C,SAAS;QAEnD,IAAI,CAAC;YACH,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC,YAAY,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QAC9D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;YACvB,MAAM,SAAS,CACb,UAAU,EACV,CAAC,CAAC,OAAO,EACT;gBACE,sCAAsC;gBACtC,kCAAkC;aACnC,EACD,CAAC,EACD,aAAa,CAAC,gBAAgB,CAC/B,CAAC;QACJ,CAAC;IACH,CAAC;IAED,oDAAoD;IAEpD;;OAEG;IACH,KAAK,CAAC,QAAQ,CAAC,YAAoB;QACjC,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,MAAM,SAAS,CACb,0BAA0B,EAC1B,aAAa,EACb,CAAC,sCAAsC,EAAE,WAAW,CAAC,EACrD,SAAS,EACT,aAAa,CAAC,cAAc,CAC7B,CAAC;QACJ,CAAC;QAED,MAAM,YAAY,GAAG,IAAI,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;QACxD,IAAI,CAAC,gBAAgB,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;QAEjD,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;YACtD,4CAA4C;YAC5C,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;gBACxB,IAAI,CAAC,cAAc,CAAC,gBAAgB,CAAC,YAAY,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;oBACtF,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,UAAU,CAAC,CAAC;gBACvD,CAAC,CAAC,CAAC;YACL,CAAC;YACD,OAAO,OAAO,CAAC;QACjB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;YACvB,4BAA4B;YAC5B,IAAI,CAAC,YAAY,WAAW;gBAAE,MAAM,CAAC,CAAC;YACtC,IACE,GAAG,KAAK,IAAI;gBACZ,OAAO,GAAG,KAAK,QAAQ;gBACvB,MAAM,IAAI,GAAG;gBACZ,GAAyB,CAAC,IAAI,KAAK,QAAQ,EAC5C,CAAC;gBACD,MAAM,SAAS,CACb,iBAAiB,EACjB,GAAG,YAAY,QAAQ,EACvB,CAAC,QAAQ,EAAE,oBAAoB,CAAC,EAChC,CAAC,EACD,aAAa,CAAC,cAAc,CAC7B,CAAC;YACJ,CAAC;YACD,MAAM,SAAS,CACb,gBAAgB,EAChB,GAAG,YAAY,IAAI,CAAC,CAAC,OAAO,EAAE,EAC9B,CAAC,QAAQ,EAAE,QAAQ,CAAC,EACpB,CAAC,EACD,aAAa,CAAC,OAAO,CACtB,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,SAAS,CACb,YAAoB,EACpB,OAAe,EACf,UAA4B,EAC5B,OAAe,WAAW,EAC1B,UAAmB;QAEnB,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,MAAM,SAAS,CACb,2BAA2B,EAC3B,aAAa,EACb,CAAC,uCAAuC,CAAC,EACzC,SAAS,EACT,aAAa,CAAC,cAAc,CAC7B,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAChC,MAAM,SAAS,CACb,8BAA8B,EAC9B,gBAAgB,EAChB,CAAC,iBAAiB,CAAC,EACnB,SAAS,EACT,aAAa,CAAC,cAAc,CAC7B,CAAC;QACJ,CAAC;QAED,gBAAgB;QAChB,MAAM,UAAU,GAAG,CAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;QACrD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/B,MAAM,SAAS,CACb,iBAAiB,EACjB,YAAY,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,IAAI,EAAE,EAChD,CAAC,oBAAoB,CAAC,EACtB,SAAS,EACT,aAAa,CAAC,cAAc,CAC7B,CAAC;QACJ,CAAC;QAED,4BAA4B;QAC5B,IAAI,IAAI,KAAK,QAAQ,IAAI,CAAC,UAAU,EAAE,CAAC;YACrC,MAAM,SAAS,CACb,iBAAiB,EACjB,8BAA8B,EAC9B,CAAC,+BAA+B,CAAC,EACjC,SAAS,EACT,aAAa,CAAC,cAAc,CAC7B,CAAC;QACJ,CAAC;QAED,MAAM,YAAY,GAAG,IAAI,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;QACxD,IAAI,CAAC,gBAAgB,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;QAElD,gBAAgB;QAChB,IAAI,aAAa,GAAkB,IAAI,CAAC;QACxC,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,YAAY,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;YAC3C,aAAa,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACxD,CAAC;QAAC,MAAM,CAAC;YACP,oCAAoC;QACtC,CAAC;QAED,mBAAmB;QACnB,MAAM,YAAY,GAAG,IAAI,CAAC,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,aAAa,EAAE,UAAU,CAAC,CAAC;QAExF,oDAAoD;QACpD,qDAAqD;QACrD,IAAI,UAAU,EAAE,aAAa,EAAE,CAAC;YAC9B,IAAI,EAAW,CAAC;YAChB,IAAI,CAAC;gBACH,EAAE,GAAG,MAAM,UAAU,CAAC,aAAa,CAAC,YAAY,EAAE,aAAa,EAAE,YAAY,CAAC,CAAC;YACjF,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;gBACvB,MAAM,SAAS,CACb,QAAQ,EACR,YAAY,CAAC,CAAC,OAAO,EAAE,EACvB,CAAC,QAAQ,EAAE,eAAe,CAAC,EAC3B,CAAC,EACD,aAAa,CAAC,OAAO,CACtB,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,EAAE,EAAE,CAAC;gBACR,MAAM,SAAS,CACb,QAAQ,EACR,uBAAuB,YAAY,EAAE,EACrC,CAAC,iBAAiB,CAAC,EACnB,SAAS,EACT,aAAa,CAAC,cAAc,CAC7B,CAAC;YACJ,CAAC;QACH,CAAC;aAAM,CAAC;YACN,cAAc;YACd,MAAM,WAAW,GAAG,MAAM,YAAY,CAAC,MAAM,QAAQ,QAAQ,CAAC,YAAY,CAAC,OAAO,IAAI,GAAG,CAAC;YAC1F,IAAI,SAAkB,CAAC;YACvB,IAAI,CAAC;gBACH,SAAS,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,wBAAwB,CACtD,YAAY,EACZ,YAAY,EACZ,WAAW,CACZ,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;gBACvB,MAAM,SAAS,CACb,QAAQ,EACR,UAAU,CAAC,CAAC,OAAO,EAAE,EACrB,CAAC,QAAQ,CAAC,EACV,CAAC,EACD,aAAa,CAAC,OAAO,CACtB,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,MAAM,SAAS,CACb,QAAQ,EACR,uBAAuB,YAAY,EAAE,EACrC,CAAC,iBAAiB,CAAC,EACnB,SAAS,EACT,aAAa,CAAC,cAAc,CAC7B,CAAC;YACJ,CAAC;QACH,CAAC;QAED,2BAA2B;QAC3B,MAAM,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;QACxC,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;YACvB,MAAM,SAAS,CACb,QAAQ,EACR,WAAW,SAAS,IAAI,CAAC,CAAC,OAAO,EAAE,EACnC,CAAC,WAAW,EAAE,QAAQ,CAAC,EACvB,CAAC,EACD,aAAa,CAAC,iBAAiB,CAChC,CAAC;QACJ,CAAC;QAED,IAAI,CAAC;YACH,MAAM,SAAS,CAAC,YAAY,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;YACrD,qBAAqB;YACrB,MAAM,QAAQ,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;YACjD,MAAM,QAAQ,GAAG,aAAa,KAAK,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;YAC/E,MAAM,SAAS,GACb,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,UAAU,GAAG,CAAC;YAChF,OAAO,CACL,SAAS,SAAS,KAAK,YAAY,IAAI,YAAY,CAAC,MAAM,OAAO,QAAQ,KAAK;gBAC9E,CAAC,aAAa,KAAK,IAAI,CAAC,CAAC,CAAC,UAAU,QAAQ,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,CAC9D,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;YACvB,MAAM,SAAS,CACb,QAAQ,EACR,GAAG,YAAY,IAAI,CAAC,CAAC,OAAO,EAAE,EAC9B,CAAC,SAAS,EAAE,UAAU,CAAC,EACvB,CAAC,EACD,aAAa,CAAC,iBAAiB,CAChC,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACK,mBAAmB,CACzB,IAAY,EACZ,OAAe,EACf,aAA4B,EAC5B,UAA8B;QAE9B,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,WAAW;gBACd,oBAAoB;gBACpB,OAAO,OAAO,CAAC;YAEjB,KAAK,QAAQ;gBACX,iBAAiB;gBACjB,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;oBAC3B,mBAAmB;oBACnB,OAAO,OAAO,CAAC;gBACjB,CAAC;gBACD,OAAO,aAAa,GAAG,OAAO,CAAC;YAEjC,KAAK,QAAQ,CAAC,CAAC,CAAC;gBACd,gBAAgB;gBAChB,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;oBAC3B,mBAAmB;oBACnB,OAAO,OAAO,CAAC;gBACjB,CAAC;gBACD,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,UAAU,IAAI,GAAG,EAAE,EAAE,CAAC,CAAC;gBACvD,IAAI,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;oBACzC,MAAM,SAAS,CACb,iBAAiB,EACjB,yBAAyB,UAAU,EAAE,EACrC,CAAC,sBAAsB,CAAC,EACxB,SAAS,EACT,aAAa,CAAC,cAAc,CAC7B,CAAC;gBACJ,CAAC;gBACD,MAAM,KAAK,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBACxC,eAAe;gBACf,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;gBACtD,KAAK,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;gBACpC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC1B,CAAC;YAED;gBACE,oCAAoC;gBACpC,OAAO,OAAO,CAAC;QACnB,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,CACX,YAAoB,EACpB,YAAoB,EACpB,WAAmB;QAEnB,MAAM,YAAY,GAAG,IAAI,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;QACxD,IAAI,CAAC,gBAAgB,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;QAEhD,MAAM,SAAS,GAAG,YAAY,KAAK,MAAM,IAAI,YAAY,KAAK,GAAG,CAAC;QAClE,IAAI,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;QAChD,IAAI,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;YAC3C,QAAQ,GAAG,CAAC,CAAC;QACf,CAAC;QACD,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;YACjB,QAAQ,GAAG,CAAC,CAAC;QACf,CAAC;QAED,IAAI,KAAK,CAAC;QACV,IAAI,CAAC;YACH,KAAK,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,CAAC;QACnC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,oCAAoC;YACpC,IACE,GAAG,KAAK,IAAI;gBACZ,OAAO,GAAG,KAAK,QAAQ;gBACvB,MAAM,IAAI,GAAG;gBACZ,GAAyB,CAAC,IAAI,KAAK,QAAQ,EAC5C,CAAC;gBACD,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;gBACvB,MAAM,SAAS,CACb,gBAAgB,EAChB,GAAG,YAAY,QAAQ,EACvB,CAAC,QAAQ,EAAE,wBAAwB,CAAC,EACpC,CAAC,EACD,aAAa,CAAC,aAAa,CAC5B,CAAC;YACJ,CAAC;YACD,oCAAoC;YACpC,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;YACvB,MAAM,SAAS,CACb,eAAe,EACf,GAAG,YAAY,IAAI,CAAC,CAAC,OAAO,EAAE,EAC9B,CAAC,QAAQ,EAAE,QAAQ,CAAC,EACpB,CAAC,EACD,aAAa,CAAC,OAAO,CACtB,CAAC;QACJ,CAAC;QAED,kBAAkB;QAClB,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YACzB,MAAM,SAAS,CACb,iBAAiB,EACjB,GAAG,YAAY,WAAW,EAC1B,CAAC,eAAe,CAAC,EACjB,SAAS,EACT,aAAa,CAAC,aAAa,CAC5B,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,MAAM,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;QAEhF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,kBAAkB,YAAY,EAAE,CAAC;QAC1C,CAAC;QACD,OAAO,MAAM,YAAY,OAAO,OAAO,CAAC,MAAM,UAAU,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IACpG,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,OAAO,CACnB,IAAY,EACZ,OAAe,EACf,GAAa,EACb,KAAa,EACb,QAAgB,EAChB,SAAkB;QAElB,IAAI,KAAK,GAAG,QAAQ;YAAE,OAAO;QAE7B,IAAI,KAAe,CAAC;QACpB,IAAI,CAAC;YACH,KAAK,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;QACjC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,eAAe,CAAC,CAAC;YACrD,OAAO;QACT,CAAC;QAED,KAAK,CAAC,IAAI,EAAE,CAAC;QAEb,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,qDAAqD;YACrD,IAAI,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC;gBAAE,SAAS;YAEtC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YACrC,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YAE1C,IAAI,CAAC;gBACH,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACvC,IAAI,SAAS,CAAC,WAAW,EAAE,EAAE,CAAC;oBAC5B,GAAG,CAAC,IAAI,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC;oBAC5B,wCAAwC;oBACxC,8DAA8D;oBAC9D,IAAI,SAAS,IAAI,KAAK,GAAG,CAAC,GAAG,QAAQ,EAAE,CAAC;wBACtC,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;oBAC1E,CAAC;gBACH,CAAC;qBAAM,CAAC;oBACN,GAAG,CAAC,IAAI,CAAC,MAAM,QAAQ,EAAE,CAAC,CAAC;gBAC7B,CAAC;YACH,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,0BAA0B;gBAC1B,GAAG,CAAC,IAAI,CAAC,KAAK,QAAQ,SAAS,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC;YAC1D,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACK,YAAY,CAAC,IAAY;QAC/B,OAAO,mBAAmB,CAAC,iBAAiB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC9D,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,cAAc,CAClB,KAAa,EACb,QAAgB,EAChB,OAAe;QAEf,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,SAAS,CACb,iCAAiC,EACjC,cAAc,EACd,CAAC,YAAY,CAAC,EACd,SAAS,EACT,aAAa,CAAC,cAAc,CAC7B,CAAC;QACJ,CAAC;QAED,IAAI,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAC1C,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACrC,KAAK,GAAG,EAAE,CAAC;QACb,CAAC;QACD,IAAI,KAAK,GAAG,EAAE,EAAE,CAAC;YACf,KAAK,GAAG,EAAE,CAAC;QACb,CAAC;QAED,MAAM,IAAI,GAAG,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;QACnD,IAAI,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QAEpD,2BAA2B;QAC3B,IAAI,IAAI,KAAK,MAAM,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1C,6CAA6C;YAC7C,MAAM,QAAQ,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;YAChE,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACxB,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;oBAC7B,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;oBACpD,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;gBACnD,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,WAAW,KAAK,QAAQ,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC;QACjF,CAAC;QAED,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YACjC,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;YACjF,OAAO,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,YAAY,CAAC,CAAC,KAAK,SAAS,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC;QACnG,CAAC,CAAC,CAAC;QACH,OAAO,OAAO,KAAK,QAAQ,OAAO,CAAC,MAAM,MAAM,IAAI,UAAU,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IAClF,CAAC"}

package/dist/agent/builtinTools.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 内置工具定义
+ *
+ * 工具定义（schema/参数描述）与工具执行逻辑分离：
+ * - 本文件只包含工具的"声明"（名称、描述、参数 schema）
+ * - 工具的"执行"逻辑留在 toolExecutor.ts
+ */
+/**
+ * 工具定义接口
+ *
+ * 描述一个工具的名称、用途和参数 schema，
+ * 用于构建 LLM 请求的 tools 参数。
+ */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, {
+            type: string;
+            description: string;
+        }>;
+        required: string[];
+    };
+}
+/**
+ * 工具注册表
+ * 阶段二（M-204）：4 个工具
+ * - read_file：读取文件
+ * - write_file：写入/创建文件（受写入二次确认保护）
+ * - list_dir：列出目录内容
+ * - search_memories：在记忆索引中搜索关键词
+ */
+export declare const BUILTIN_TOOLS: ToolDefinition[];
+//# sourceMappingURL=builtinTools.d.ts.map

package/dist/agent/builtinTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtinTools.d.ts","sourceRoot":"","sources":["../../src/agent/builtinTools.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE;QACV,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAClE,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;CACH;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,EAAE,cAAc,EA8DzC,CAAC"}

package/dist/agent/builtinTools.js

@@ -0,0 +1,75 @@
+/**
+ * 内置工具定义
+ *
+ * 工具定义（schema/参数描述）与工具执行逻辑分离：
+ * - 本文件只包含工具的"声明"（名称、描述、参数 schema）
+ * - 工具的"执行"逻辑留在 toolExecutor.ts
+ */
+/**
+ * 工具注册表
+ * 阶段二（M-204）：4 个工具
+ * - read_file：读取文件
+ * - write_file：写入/创建文件（受写入二次确认保护）
+ * - list_dir：列出目录内容
+ * - search_memories：在记忆索引中搜索关键词
+ */
+export const BUILTIN_TOOLS = [
+    {
+        name: 'read_file',
+        description: '读取项目内文件内容。路径必须相对项目根目录。',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: '相对项目根目录的文件路径' },
+            },
+            required: ['path'],
+        },
+    },
+    {
+        name: 'write_file',
+        description: '写入或创建文件。owner 模式默认自动批准；guest 模式会要求用户确认。受路径白名单保护。支持三种写入模式：overwrite（默认，全量覆盖）、append（追加到末尾）、insert（在指定行号前插入）。',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: '相对项目根目录的文件路径' },
+                content: { type: 'string', description: '要写入的内容' },
+                mode: {
+                    type: 'string',
+                    description: '写入模式："overwrite"（默认，全量覆盖）、"append"（追加到末尾）、"insert"（在 insert_line 行号前插入）',
+                },
+                insert_line: {
+                    type: 'string',
+                    description: 'insert 模式下插入位置的行号（从 1 开始），省略则插入到文件末尾',
+                },
+            },
+            required: ['path', 'content'],
+        },
+    },
+    {
+        name: 'list_dir',
+        description: '列出目录内容。默认相对项目根目录。受路径白名单保护。递归深度 ≤ 3，自动忽略 .git / node_modules。',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: '相对项目根目录的目录路径，默认为 "."（项目根）' },
+                recursive: { type: 'string', description: '是否递归（"true" / "false"），默认 "false"' },
+                maxDepth: { type: 'string', description: '递归最大深度（1-3），默认 "2"' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'search_memories',
+        description: '在记忆索引中搜索关键词。支持 match（任一命中，默认）和 near（全部命中）两种模式。',
+        parameters: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: '搜索关键词' },
+                limit: { type: 'string', description: '返回结果数量上限，默认 "10"' },
+                mode: { type: 'string', description: '"match"（默认，任一）或 "near"（必须全部）' },
+            },
+            required: ['query'],
+        },
+    },
+];
+//# sourceMappingURL=builtinTools.js.map

package/dist/agent/builtinTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtinTools.js","sourceRoot":"","sources":["../../src/agent/builtinTools.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAkBH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAqB;IAC7C;QACE,IAAI,EAAE,WAAW;QACjB,WAAW,EAAE,wBAAwB;QACrC,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE;aACtD;YACD,QAAQ,EAAE,CAAC,MAAM,CAAC;SACnB;KACF;IACD;QACE,IAAI,EAAE,YAAY;QAClB,WAAW,EACT,6GAA6G;QAC/G,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE;gBACrD,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE;gBAClD,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EACT,yEAAyE;iBAC5E;gBACD,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,sCAAsC;iBACpD;aACF;YACD,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC;SAC9B;KACF;IACD;QACE,IAAI,EAAE,UAAU;QAChB,WAAW,EACT,8DAA8D;QAChE,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,2BAA2B,EAAE;gBAClE,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,mCAAmC,EAAE;gBAC/E,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,oBAAoB,EAAE;aAChE;YACD,QAAQ,EAAE,EAAE;SACb;KACF;IACD;QACE,IAAI,EAAE,iBAAiB;QACvB,WAAW,EACT,gDAAgD;QAClD,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE;gBAC/C,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,kBAAkB,EAAE;gBAC1D,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,8BAA8B,EAAE;aACtE;YACD,QAAQ,EAAE,CAAC,OAAO,CAAC;SACpB;KACF;CACF,CAAC"}

package/dist/agent/constants.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Agent 模块常量集合
+ *
+ * 集中管理 agent.ts 与 loop.ts 中的 magic numbers，便于统一调整与审查。
+ * 按模块分两个命名空间，不创建全局 constants（避免垃圾桶反模式）。
+ *
+ * 触发提取的决策记录：A-006（原"暂缓"判断已失效——10 个 magic number 分布在 2 文件，已达提取阈值）。
+ */
+/**
+ * Agent 门面层常量
+ *
+ * 用于 agent.ts 中的并发锁、输入限制、记忆衰减周期等。
+ */
+export declare const AGENT_CONSTANTS: {
+    /**
+     * chat() 并发锁超时（毫秒）。超时后中断 generator 并释放锁。
+     *
+     * BUG-STREAM-05 修复：原值 300_000（5 分钟）与超时体系不匹配：
+     * - chunk 级读超时 30s（openaiCompatible parseSseStream）
+     * - LLM 请求超时 120s（LLM_TIMEOUT_MS）
+     * - 宿主层无进展兜底 60s（chatHandlers STREAM_NO_PROGRESS_TIMEOUT_MS）
+     * 现调整为 180s（LLM 120s + 60s 缓冲），作为所有超时失败后的最后兜底。
+     */
+    readonly CHAT_LOCK_TIMEOUT_MS: 180000;
+    /** chat() 输入最大长度（字节）。128KB。 */
+    readonly CHAT_INPUT_MAX_LENGTH: number;
+    /** 记忆衰减执行间隔（毫秒）。1 小时。 */
+    readonly DECAY_INTERVAL_MS: 3600000;
+    /** AgentConfig.maxContextTokens 默认值。120K tokens。 */
+    readonly DEFAULT_MAX_CONTEXT_TOKENS: 120000;
+    /** recallExcludeSources 默认值——永久记忆不参与增量召回。 */
+    readonly DEFAULT_RECALL_EXCLUDE_SOURCES: readonly ["persona", "rule", "skill"];
+};
+/**
+ * AgentLoop 引擎层常量
+ *
+ * 用于 loop.ts 中的 token 估算、召回上下文长度、LLM 重试、循环限制等。
+ *
+ * 注意：AgentLoop 构造选项中的默认值（maxIterations ?? 20 等）保留在 loop.ts 原地，
+ * 因为它们是 API 契约的一部分——调用方期望"未传入时使用默认值"。
+ * 这里只提取与 UI/重试/估算相关的纯常量。
+ */
+export declare const LOOP_CONSTANTS: {
+    /** 粗略 token 估算：每 token 约 3 字符（非精确 tokenizer）。 */
+    readonly CHARS_PER_TOKEN: 3;
+    /** 召回记忆注入到上下文的最大字符数。超出会截断。 */
+    readonly RECALL_CONTEXT_MAX_CHARS: 2000;
+    /** LLM 调用最大重试次数（不含首次调用）。 */
+    readonly MAX_LLM_RETRIES: 2;
+    /** LLM 重试基础延迟（毫秒），指数退避 base。 */
+    readonly RETRY_BASE_DELAY_MS: 1000;
+    /** 单次 LLM 请求超时（毫秒）。120 秒。超时后可重试。 */
+    readonly LLM_TIMEOUT_MS: 120000;
+    /** 上下文截断时给 LLM 响应预留的缓冲比例。0.9 = 留 10% 给响应。 */
+    readonly CONTEXT_TOKENS_BUFFER_RATIO: 0.9;
+    /** 摘要缓存 TTL：消息数增长超过此值时缓存过期，需重新生成摘要。 */
+    readonly SUMMARY_CACHE_TTL_MSGS: 10;
+    /** 召回记忆内容注入上下文时的截断长度（字符）。 */
+    readonly RECALL_CONTENT_SLICE: 200;
+    /** 上下文摘要：参与摘要的最近消息条数。 */
+    readonly SUMMARY_MSG_COUNT: 6;
+    /** 上下文摘要：单条消息内容截断长度（字符）。 */
+    readonly SUMMARY_CONTENT_SLICE: 200;
+    /** 上下文摘要：LLM 调用 maxTokens 参数。 */
+    readonly SUMMARY_MAX_TOKENS: 150;
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/agent/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/agent/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;GAIG;AACH,eAAO,MAAM,eAAe;IAC1B;;;;;;;;OAQG;;IAGH,+BAA+B;;IAG/B,yBAAyB;;IAGzB,oDAAoD;;IAGpD,6CAA6C;;CAErC,CAAC;AAEX;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;IACzB,iDAAiD;;IAGjD,8BAA8B;;IAG9B,4BAA4B;;IAG5B,gCAAgC;;IAGhC,oCAAoC;;IAGpC,6CAA6C;;IAG7C,uCAAuC;;IAGvC,6BAA6B;;IAG7B,yBAAyB;;IAGzB,4BAA4B;;IAG5B,iCAAiC;;CAEzB,CAAC"}