@cicctencent/agent-core 0.1.15 → 0.1.17

package/dist/cjs/tool/builtin-tools.js

@@ -0,0 +1,221 @@
+"use strict";
+// ============================================================
+// Builtin Tools — 可选通用工具工厂
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createShellTools = createShellTools;
+exports.createFileSystemTools = createFileSystemTools;
+exports.createToolDocTool = createToolDocTool;
+exports.createSkillLoaderTool = createSkillLoaderTool;
+exports.createBuiltinTools = createBuiltinTools;
+function createShellTools() {
+    return [
+        {
+            definition: {
+                type: 'function',
+                function: {
+                    name: 'execute_command',
+                    description: 'Execute a shell command through the injected ToolContext.shell executor.',
+                    parameters: {
+                        type: 'object',
+                        properties: {
+                            command: { type: 'string', description: 'Shell command to execute' },
+                            timeout: { type: 'number', description: 'Timeout in milliseconds' },
+                        },
+                        required: ['command'],
+                    },
+                },
+            },
+            executor: async (args, ctx) => {
+                const command = String(args.command || '').trim();
+                if (!command)
+                    return 'ERROR: execute_command requires non-empty command.';
+                return ctx.shell.exec(command, Number(args.timeout) || undefined);
+            },
+            category: 'builtin',
+            concurrent: false,
+        },
+        {
+            definition: {
+                type: 'function',
+                function: {
+                    name: 'read_terminal',
+                    description: 'Read recent terminal output from the injected ToolContext.shell executor.',
+                    parameters: {
+                        type: 'object',
+                        properties: { lines: { type: 'number', description: 'Number of lines to read' } },
+                    },
+                },
+            },
+            executor: async (args, ctx) => ctx.shell.read(Number(args.lines) || 50),
+            category: 'builtin',
+            concurrent: true,
+        },
+    ];
+}
+function createFileSystemTools() {
+    return [
+        {
+            definition: {
+                type: 'function',
+                function: {
+                    name: 'read_file',
+                    description: 'Read a text file through the injected ToolContext.fs executor.',
+                    parameters: {
+                        type: 'object',
+                        properties: { path: { type: 'string', description: 'File path to read' } },
+                        required: ['path'],
+                    },
+                },
+            },
+            executor: async (args, ctx) => {
+                if (!ctx.fs)
+                    return 'Error: FileSystem executor not available';
+                const filePath = String(args.path || '').trim();
+                if (!filePath)
+                    return 'Error: path is required.';
+                return ctx.fs.readFile(filePath);
+            },
+            category: 'builtin',
+            concurrent: true,
+        },
+        {
+            definition: {
+                type: 'function',
+                function: {
+                    name: 'write_file',
+                    description: 'Write text content to a file through the injected ToolContext.fs executor.',
+                    parameters: {
+                        type: 'object',
+                        properties: {
+                            path: { type: 'string', description: 'File path to write' },
+                            content: { type: 'string', description: 'Text content' },
+                        },
+                        required: ['path', 'content'],
+                    },
+                },
+            },
+            executor: async (args, ctx) => {
+                if (!ctx.fs)
+                    return 'Error: FileSystem executor not available';
+                const filePath = String(args.path || '').trim();
+                if (!filePath)
+                    return 'Error: path is required.';
+                await ctx.fs.writeFile(filePath, String(args.content ?? ''));
+                return `File written: ${filePath}`;
+            },
+            category: 'builtin',
+            concurrent: false,
+        },
+        {
+            definition: {
+                type: 'function',
+                function: {
+                    name: 'append_file',
+                    description: 'Append text content to a file through the injected ToolContext.fs executor.',
+                    parameters: {
+                        type: 'object',
+                        properties: {
+                            path: { type: 'string', description: 'File path to append' },
+                            content: { type: 'string', description: 'Text content to append' },
+                        },
+                        required: ['path', 'content'],
+                    },
+                },
+            },
+            executor: async (args, ctx) => {
+                if (!ctx.fs)
+                    return 'Error: FileSystem executor not available';
+                const filePath = String(args.path || '').trim();
+                if (!filePath)
+                    return 'Error: path is required.';
+                if (ctx.fs.appendFile)
+                    await ctx.fs.appendFile(filePath, String(args.content ?? ''));
+                else {
+                    let existing = '';
+                    try {
+                        existing = await ctx.fs.readFile(filePath);
+                    }
+                    catch {
+                        existing = '';
+                    }
+                    await ctx.fs.writeFile(filePath, existing + String(args.content ?? ''));
+                }
+                return `Content appended to: ${filePath}`;
+            },
+            category: 'builtin',
+            concurrent: false,
+        },
+    ];
+}
+function createToolDocTool(registry) {
+    return {
+        definition: {
+            type: 'function',
+            function: {
+                name: 'read_tool_doc',
+                description: 'Read full schema/documentation for a registered tool. Use tool_name="list" to list names.',
+                parameters: {
+                    type: 'object',
+                    properties: { tool_name: { type: 'string', description: 'Tool name, or "list"' } },
+                    required: ['tool_name'],
+                },
+            },
+        },
+        executor: async (args, ctx) => {
+            const toolRegistry = ctx.custom?.toolRegistry || registry;
+            if (!toolRegistry)
+                return 'Error: ToolRegistry not available';
+            const name = String(args.tool_name || '').trim();
+            if (name === 'list')
+                return toolRegistry.listNames().join('\n');
+            const tool = toolRegistry.get(name);
+            if (!tool)
+                return `Tool not found: ${name}`;
+            return JSON.stringify(tool.definition.function, null, 2);
+        },
+        category: 'builtin',
+        concurrent: true,
+    };
+}
+function createSkillLoaderTool(skillManager) {
+    return {
+        definition: {
+            type: 'function',
+            function: {
+                name: 'load_skill',
+                description: 'Load full instructions for an available skill by skill_id.',
+                parameters: {
+                    type: 'object',
+                    properties: { skill_id: { type: 'string', description: 'Skill id' } },
+                    required: ['skill_id'],
+                },
+            },
+        },
+        executor: async (args, ctx) => {
+            const manager = ctx.custom?.skillManager || skillManager;
+            if (!manager)
+                return 'Error: SkillManager not available';
+            const id = String(args.skill_id || '').trim();
+            const skill = manager.get(id);
+            if (!skill)
+                return `Skill not found: ${id}`;
+            return skill.content || '';
+        },
+        category: 'builtin',
+        concurrent: true,
+    };
+}
+function createBuiltinTools(options = {}) {
+    const tools = [];
+    if (options.includeShell ?? true)
+        tools.push(...createShellTools());
+    if (options.includeFileSystem ?? true)
+        tools.push(...createFileSystemTools());
+    if (options.includeToolDoc ?? true)
+        tools.push(createToolDocTool(options.toolRegistry));
+    if (options.includeSkillLoader ?? true)
+        tools.push(createSkillLoaderTool(options.skillManager));
+    return tools;
+}
+//# sourceMappingURL=builtin-tools.js.map

package/dist/cjs/tool/builtin-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-tools.js","sourceRoot":"","sources":["../../../src/tool/builtin-tools.ts"],"names":[],"mappings":";AAAA,+DAA+D;AAC/D,2BAA2B;AAC3B,+DAA+D;;AAqB/D,4CA2CC;AAED,sDAkFC;AAED,8CA0BC;AAED,sDAyBC;AAED,gDAOC;AA/LD,SAAgB,gBAAgB;IAC9B,OAAO;QACL;YACE,UAAU,EAAE;gBACV,IAAI,EAAE,UAAU;gBAChB,QAAQ,EAAE;oBACR,IAAI,EAAE,iBAAiB;oBACvB,WAAW,EAAE,0EAA0E;oBACvF,UAAU,EAAE;wBACV,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE;4BACV,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,0BAA0B,EAAE;4BACpE,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,yBAAyB,EAAE;yBACpE;wBACD,QAAQ,EAAE,CAAC,SAAS,CAAC;qBACtB;iBACF;aACF;YACD,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;gBAC5B,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;gBAClD,IAAI,CAAC,OAAO;oBAAE,OAAO,oDAAoD,CAAC;gBAC1E,OAAO,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,SAAS,CAAC,CAAC;YACpE,CAAC;YACD,QAAQ,EAAE,SAAS;YACnB,UAAU,EAAE,KAAK;SAClB;QACD;YACE,UAAU,EAAE;gBACV,IAAI,EAAE,UAAU;gBAChB,QAAQ,EAAE;oBACR,IAAI,EAAE,eAAe;oBACrB,WAAW,EAAE,2EAA2E;oBACxF,UAAU,EAAE;wBACV,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,yBAAyB,EAAE,EAAE;qBAClF;iBACF;aACF;YACD,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YACvE,QAAQ,EAAE,SAAS;YACnB,UAAU,EAAE,IAAI;SACjB;KACF,CAAC;AACJ,CAAC;AAED,SAAgB,qBAAqB;IACnC,OAAO;QACL;YACE,UAAU,EAAE;gBACV,IAAI,EAAE,UAAU;gBAChB,QAAQ,EAAE;oBACR,IAAI,EAAE,WAAW;oBACjB,WAAW,EAAE,gEAAgE;oBAC7E,UAAU,EAAE;wBACV,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,mBAAmB,EAAE,EAAE;wBAC1E,QAAQ,EAAE,CAAC,MAAM,CAAC;qBACnB;iBACF;aACF;YACD,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;gBAC5B,IAAI,CAAC,GAAG,CAAC,EAAE;oBAAE,OAAO,0CAA0C,CAAC;gBAC/D,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;gBAChD,IAAI,CAAC,QAAQ;oBAAE,OAAO,0BAA0B,CAAC;gBACjD,OAAO,GAAG,CAAC,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YACnC,CAAC;YACD,QAAQ,EAAE,SAAS;YACnB,UAAU,EAAE,IAAI;SACjB;QACD;YACE,UAAU,EAAE;gBACV,IAAI,EAAE,UAAU;gBAChB,QAAQ,EAAE;oBACR,IAAI,EAAE,YAAY;oBAClB,WAAW,EAAE,4EAA4E;oBACzF,UAAU,EAAE;wBACV,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE;4BACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,oBAAoB,EAAE;4BAC3D,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE;yBACzD;wBACD,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC;qBAC9B;iBACF;aACF;YACD,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;gBAC5B,IAAI,CAAC,GAAG,CAAC,EAAE;oBAAE,OAAO,0CAA0C,CAAC;gBAC/D,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;gBAChD,IAAI,CAAC,QAAQ;oBAAE,OAAO,0BAA0B,CAAC;gBACjD,MAAM,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC;gBAC7D,OAAO,iBAAiB,QAAQ,EAAE,CAAC;YACrC,CAAC;YACD,QAAQ,EAAE,SAAS;YACnB,UAAU,EAAE,KAAK;SAClB;QACD;YACE,UAAU,EAAE;gBACV,IAAI,EAAE,UAAU;gBAChB,QAAQ,EAAE;oBACR,IAAI,EAAE,aAAa;oBACnB,WAAW,EAAE,6EAA6E;oBAC1F,UAAU,EAAE;wBACV,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE;4BACV,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,qBAAqB,EAAE;4BAC5D,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,wBAAwB,EAAE;yBACnE;wBACD,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,CAAC;qBAC9B;iBACF;aACF;YACD,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;gBAC5B,IAAI,CAAC,GAAG,CAAC,EAAE;oBAAE,OAAO,0CAA0C,CAAC;gBAC/D,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;gBAChD,IAAI,CAAC,QAAQ;oBAAE,OAAO,0BAA0B,CAAC;gBACjD,IAAI,GAAG,CAAC,EAAE,CAAC,UAAU;oBAAE,MAAM,GAAG,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC;qBAChF,CAAC;oBACJ,IAAI,QAAQ,GAAG,EAAE,CAAC;oBAClB,IAAI,CAAC;wBAAC,QAAQ,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;oBAAC,CAAC;oBAAC,MAAM,CAAC;wBAAC,QAAQ,GAAG,EAAE,CAAC;oBAAC,CAAC;oBAC5E,MAAM,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC;gBAC1E,CAAC;gBACD,OAAO,wBAAwB,QAAQ,EAAE,CAAC;YAC5C,CAAC;YACD,QAAQ,EAAE,SAAS;YACnB,UAAU,EAAE,KAAK;SAClB;KACF,CAAC;AACJ,CAAC;AAED,SAAgB,iBAAiB,CAAC,QAAuB;IACvD,OAAO;QACL,UAAU,EAAE;YACV,IAAI,EAAE,UAAU;YAChB,QAAQ,EAAE;gBACR,IAAI,EAAE,eAAe;gBACrB,WAAW,EAAE,2FAA2F;gBACxG,UAAU,EAAE;oBACV,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE,EAAE,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sBAAsB,EAAE,EAAE;oBAClF,QAAQ,EAAE,CAAC,WAAW,CAAC;iBACxB;aACF;SACF;QACD,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;YAC5B,MAAM,YAAY,GAAI,GAAG,CAAC,MAAM,EAAE,YAAyC,IAAI,QAAQ,CAAC;YACxF,IAAI,CAAC,YAAY;gBAAE,OAAO,mCAAmC,CAAC;YAC9D,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;YACjD,IAAI,IAAI,KAAK,MAAM;gBAAE,OAAO,YAAY,CAAC,SAAS,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAChE,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACpC,IAAI,CAAC,IAAI;gBAAE,OAAO,mBAAmB,IAAI,EAAE,CAAC;YAC5C,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;QAC3D,CAAC;QACD,QAAQ,EAAE,SAAS;QACnB,UAAU,EAAE,IAAI;KACjB,CAAC;AACJ,CAAC;AAED,SAAgB,qBAAqB,CAAC,YAA2B;IAC/D,OAAO;QACL,UAAU,EAAE;YACV,IAAI,EAAE,UAAU;YAChB,QAAQ,EAAE;gBACR,IAAI,EAAE,YAAY;gBAClB,WAAW,EAAE,4DAA4D;gBACzE,UAAU,EAAE;oBACV,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,EAAE;oBACrE,QAAQ,EAAE,CAAC,UAAU,CAAC;iBACvB;aACF;SACF;QACD,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;YAC5B,MAAM,OAAO,GAAI,GAAG,CAAC,MAAM,EAAE,YAAyC,IAAI,YAAY,CAAC;YACvF,IAAI,CAAC,OAAO;gBAAE,OAAO,mCAAmC,CAAC;YACzD,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;YAC9C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC9B,IAAI,CAAC,KAAK;gBAAE,OAAO,oBAAoB,EAAE,EAAE,CAAC;YAC5C,OAAO,KAAK,CAAC,OAAO,IAAI,EAAE,CAAC;QAC7B,CAAC;QACD,QAAQ,EAAE,SAAS;QACnB,UAAU,EAAE,IAAI;KACjB,CAAC;AACJ,CAAC;AAED,SAAgB,kBAAkB,CAAC,UAA8B,EAAE;IACjE,MAAM,KAAK,GAAqB,EAAE,CAAC;IACnC,IAAI,OAAO,CAAC,YAAY,IAAI,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,gBAAgB,EAAE,CAAC,CAAC;IACpE,IAAI,OAAO,CAAC,iBAAiB,IAAI,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,qBAAqB,EAAE,CAAC,CAAC;IAC9E,IAAI,OAAO,CAAC,cAAc,IAAI,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;IACxF,IAAI,OAAO,CAAC,kBAAkB,IAAI,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;IAChG,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/cjs/tool/registry.d.ts

@@ -1,5 +1,5 @@
 import type { ToolDefinition, ToolExecutor, ToolContext, RegisteredTool, ToolCategory } from './types.js';
-/** defineTool 简化参数 */
+/** defineTool 简化参数（OpenAI Function Calling 格式） */
 export interface DefineToolOptions {
     name: string;
     description: string;
@@ -7,6 +7,44 @@ export interface DefineToolOptions {
     executor: ToolExecutor;
     category?: ToolCategory;
     concurrent?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * defineFlatTool 简化参数（扁平格式，兼容 BI 项目风格）
+ *
+ * 扁平格式更直观：直接声明 id / name / description / parameters / execute，
+ * 内部自动转换为 OpenAI Function Calling 格式。
+ *
+ * @example
+ * registry.defineFlatTool({
+ *   id: 'web_search',
+ *   name: '网络搜索',
+ *   description: 'Search the web for information',
+ *   parameters: {
+ *     type: 'object',
+ *     properties: { query: { type: 'string', description: '...' } },
+ *     required: ['query'],
+ *   },
+ *   execute: async (input, ctx) => { ... },
+ * });
+ */
+export interface FlatToolOptions {
+    /** 工具唯一标识（将作为 OpenAI function name） */
+    id: string;
+    /** 工具显示名（仅用于展示，不影响 LLM 调用） */
+    name?: string;
+    /** 工具描述（给 LLM 理解用途） */
+    description: string;
+    /** 参数 Schema（JSON Schema 子集） */
+    parameters: ToolDefinition['function']['parameters'];
+    /** 执行函数 */
+    execute: ToolExecutor;
+    /** 工具分类 */
+    category?: ToolCategory;
+    /** 是否支持并行执行 */
+    concurrent?: boolean;
+    /** 扩展元数据 */
+    metadata?: Record<string, unknown>;
 }
 export declare class ToolRegistry {
     private tools;
@@ -28,10 +66,47 @@ export declare class ToolRegistry {
      * });
      */
     defineTool(options: DefineToolOptions): void;
+    /**
+     * 扁平格式注册（兼容 BI 项目风格，内部自动转换为 OpenAI Function Calling 格式）
+     *
+     * @example
+     * registry.defineFlatTool({
+     *   id: 'search_data_sources',
+     *   description: '搜索候选数据源',
+     *   parameters: { type: 'object', properties: { query: { type: 'string', description: '...' } } },
+     *   execute: async (args, ctx) => { ... },
+     * });
+     */
+    defineFlatTool(options: FlatToolOptions): void;
     /** 批量注册 */
     registerAll(tools: RegisteredTool[]): void;
     /** 注销工具 */
     unregister(name: string): void;
+    /** 克隆当前注册表（浅拷贝工具定义与 executor 引用） */
+    clone(filter?: {
+        category?: ToolCategory;
+        names?: string[];
+        predicate?: (tool: RegisteredTool) => boolean;
+    }): ToolRegistry;
+    /** 按分类生成新注册表 */
+    filterByCategory(category: ToolCategory): ToolRegistry;
+    /** 按 metadata 条件生成新注册表 */
+    filterByMetadata(predicate: (metadata: Record<string, unknown>, tool: RegisteredTool) => boolean): ToolRegistry;
+    /** 导出扁平工具定义（用于使用方适配旧 API 或 UI 展示） */
+    toFlatTools(): Array<Omit<FlatToolOptions, 'execute'> & {
+        execute: ToolExecutor;
+    }>;
+    /** 转为 OpenAI function calling tools 格式 */
+    toOpenAITools(filter?: {
+        category?: ToolCategory;
+        names?: string[];
+    }): ToolDefinition[];
+    /** 生成工具摘要，适合注入 prompt 或 UI 列表 */
+    summary(options?: {
+        maxDescriptionLength?: number;
+        category?: ToolCategory;
+        names?: string[];
+    }): string;
     /** 获取指定工具 */
     get(name: string): RegisteredTool | undefined;
     /** 获取所有工具定义（传给 LLM） */

package/dist/cjs/tool/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/tool/registry.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1G,sBAAsB;AACtB,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC,YAAY,CAAC,CAAC;IACrD,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAqC;IAElD,WAAW;IACX,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IAKpC;;;;;;;;;;;;;;OAcG;IACH,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI;IAgB5C,WAAW;IACX,WAAW,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,IAAI;IAM1C,WAAW;IACX,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B,aAAa;IACb,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI7C,uBAAuB;IACvB,cAAc,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,YAAY,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,cAAc,EAAE;IAcxF,gCAAgC;IAC1B,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAM7F,kBAAkB;IAClB,SAAS,IAAI,MAAM,EAAE;IAIrB,eAAe;IACf,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAG3B"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/tool/registry.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1G,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC,YAAY,CAAC,CAAC;IACrD,QAAQ,EAAE,YAAY,CAAC;IACvB,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uBAAuB;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,UAAU,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC,YAAY,CAAC,CAAC;IACrD,WAAW;IACX,OAAO,EAAE,YAAY,CAAC;IACtB,WAAW;IACX,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,eAAe;IACf,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAqC;IAElD,WAAW;IACX,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IAKpC;;;;;;;;;;;;;;OAcG;IACH,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI;IAiB5C;;;;;;;;;;OAUG;IACH,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAiB9C,WAAW;IACX,WAAW,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,IAAI;IAM1C,WAAW;IACX,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B,oCAAoC;IACpC,KAAK,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,YAAY,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAAA;KAAE,GAAG,YAAY;IAa1H,gBAAgB;IAChB,gBAAgB,CAAC,QAAQ,EAAE,YAAY,GAAG,YAAY;IAItD,0BAA0B;IAC1B,gBAAgB,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,cAAc,KAAK,OAAO,GAAG,YAAY;IAI/G,qCAAqC;IACrC,WAAW,IAAI,KAAK,CAAC,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC,GAAG;QAAE,OAAO,EAAE,YAAY,CAAA;KAAE,CAAC;IAalF,0CAA0C;IAC1C,aAAa,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,YAAY,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,cAAc,EAAE;IAIvF,iCAAiC;IACjC,OAAO,CAAC,OAAO,GAAE;QAAE,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAO,GAAG,MAAM;IAW3G,aAAa;IACb,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI7C,uBAAuB;IACvB,cAAc,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,YAAY,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,cAAc,EAAE;IAcxF,gCAAgC;IAC1B,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAM7F,kBAAkB;IAClB,SAAS,IAAI,MAAM,EAAE;IAIrB,eAAe;IACf,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAG3B"}

package/dist/cjs/tool/registry.js

@@ -39,6 +39,34 @@ class ToolRegistry {
             executor: options.executor,
             category: options.category ?? 'custom',
             concurrent: options.concurrent,
+            metadata: options.metadata,
+        });
+    }
+    /**
+     * 扁平格式注册（兼容 BI 项目风格，内部自动转换为 OpenAI Function Calling 格式）
+     *
+     * @example
+     * registry.defineFlatTool({
+     *   id: 'search_data_sources',
+     *   description: '搜索候选数据源',
+     *   parameters: { type: 'object', properties: { query: { type: 'string', description: '...' } } },
+     *   execute: async (args, ctx) => { ... },
+     * });
+     */
+    defineFlatTool(options) {
+        this.register({
+            definition: {
+                type: 'function',
+                function: {
+                    name: options.id,
+                    description: options.description,
+                    parameters: options.parameters,
+                },
+            },
+            executor: options.execute,
+            category: options.category ?? 'custom',
+            concurrent: options.concurrent,
+            metadata: { ...options.metadata, ...(options.name ? { displayName: options.name } : {}) },
         });
     }
     /** 批量注册 */
@@ -51,6 +79,59 @@ class ToolRegistry {
     unregister(name) {
         this.tools.delete(name);
     }
+    /** 克隆当前注册表（浅拷贝工具定义与 executor 引用） */
+    clone(filter) {
+        const registry = new ToolRegistry();
+        const names = filter?.names ? new Set(filter.names) : undefined;
+        for (const tool of this.tools.values()) {
+            const name = tool.definition.function.name;
+            if (filter?.category && tool.category !== filter.category)
+                continue;
+            if (names && !names.has(name))
+                continue;
+            if (filter?.predicate && !filter.predicate(tool))
+                continue;
+            registry.register(tool);
+        }
+        return registry;
+    }
+    /** 按分类生成新注册表 */
+    filterByCategory(category) {
+        return this.clone({ category });
+    }
+    /** 按 metadata 条件生成新注册表 */
+    filterByMetadata(predicate) {
+        return this.clone({ predicate: tool => predicate(tool.metadata || {}, tool) });
+    }
+    /** 导出扁平工具定义（用于使用方适配旧 API 或 UI 展示） */
+    toFlatTools() {
+        return [...this.tools.values()].map(tool => ({
+            id: tool.definition.function.name,
+            name: tool.metadata?.displayName,
+            description: tool.definition.function.description,
+            parameters: tool.definition.function.parameters,
+            execute: tool.executor,
+            category: tool.category,
+            concurrent: tool.concurrent,
+            metadata: tool.metadata,
+        }));
+    }
+    /** 转为 OpenAI function calling tools 格式 */
+    toOpenAITools(filter) {
+        return this.getDefinitions(filter);
+    }
+    /** 生成工具摘要，适合注入 prompt 或 UI 列表 */
+    summary(options = {}) {
+        const max = options.maxDescriptionLength ?? 120;
+        const defs = this.getDefinitions({ category: options.category, names: options.names });
+        if (defs.length === 0)
+            return 'No tools available.';
+        return defs.map(def => {
+            const desc = def.function.description || '';
+            const shortDesc = desc.length > max ? `${desc.slice(0, max)}...` : desc;
+            return `- ${def.function.name}: ${shortDesc}`;
+        }).join('\n');
+    }
     /** 获取指定工具 */
     get(name) {
         return this.tools.get(name);

package/dist/cjs/tool/registry.js.map

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

package/dist/cjs/utils/event-adapter.d.ts

@@ -0,0 +1,25 @@
+import type { AgentEvent, TokenUsage } from '../types.js';
+import type { ToolRegistry } from '../tool/registry.js';
+export interface MappedAgentEvent {
+    event: string;
+    data: unknown;
+}
+export type AgentEventPreset = 'core' | 'sse' | 'bi' | 'codebuddy-like';
+export interface AgentEventAdapterOptions {
+    preset?: AgentEventPreset;
+    toolRegistry?: ToolRegistry;
+    resolveToolDisplayName?: (toolName: string, args: Record<string, unknown>, registry?: ToolRegistry) => string;
+    includeTimestamps?: boolean;
+}
+export interface AgentEventCollectorState {
+    fullContent: string;
+    reasoningText: string;
+    toolCallCount: number;
+    stepCount: number;
+    usage?: TokenUsage;
+}
+export declare function createAgentEventCollectorState(): AgentEventCollectorState;
+export declare function defaultResolveToolDisplayName(toolName: string, _args: Record<string, unknown>, registry?: ToolRegistry): string;
+export declare function mapAgentEvent(event: AgentEvent, state?: AgentEventCollectorState, options?: AgentEventAdapterOptions): MappedAgentEvent | null;
+export declare function mapAgentEventStream(events: AsyncIterable<AgentEvent>, options?: AgentEventAdapterOptions): AsyncGenerator<MappedAgentEvent>;
+//# sourceMappingURL=event-adapter.d.ts.map

package/dist/cjs/utils/event-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-adapter.d.ts","sourceRoot":"","sources":["../../../src/utils/event-adapter.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,KAAK,GAAG,IAAI,GAAG,gBAAgB,CAAC;AAExE,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,sBAAsB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,YAAY,KAAK,MAAM,CAAC;IAC9G,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED,wBAAgB,8BAA8B,IAAI,wBAAwB,CAEzE;AAED,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,MAAM,CAG/H;AAED,wBAAgB,aAAa,CAC3B,KAAK,EAAE,UAAU,EACjB,KAAK,GAAE,wBAA2D,EAClE,OAAO,GAAE,wBAA6B,GACrC,gBAAgB,GAAG,IAAI,CAoEzB;AAED,wBAAuB,mBAAmB,CACxC,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,EACjC,OAAO,GAAE,wBAA6B,GACrC,cAAc,CAAC,gBAAgB,CAAC,CAMlC"}

package/dist/cjs/utils/event-adapter.js

@@ -0,0 +1,93 @@
+"use strict";
+// ============================================================
+// AgentEventAdapter — AgentEvent 到通用 UI/SSE 事件的映射
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAgentEventCollectorState = createAgentEventCollectorState;
+exports.defaultResolveToolDisplayName = defaultResolveToolDisplayName;
+exports.mapAgentEvent = mapAgentEvent;
+exports.mapAgentEventStream = mapAgentEventStream;
+function createAgentEventCollectorState() {
+    return { fullContent: '', reasoningText: '', toolCallCount: 0, stepCount: 0 };
+}
+function defaultResolveToolDisplayName(toolName, _args, registry) {
+    const tool = registry?.get(toolName);
+    return tool?.metadata?.displayName || toolName;
+}
+function mapAgentEvent(event, state = createAgentEventCollectorState(), options = {}) {
+    const preset = options.preset ?? 'sse';
+    const resolveName = options.resolveToolDisplayName ?? defaultResolveToolDisplayName;
+    const withMeta = (data) => options.includeTimestamps ? { ...data, timestamp: event.timestamp, sessionId: event.sessionId } : data;
+    if (preset === 'core')
+        return { event: event.type, data: event };
+    switch (event.type) {
+        case 'thinking': {
+            const content = event.content || '';
+            state.reasoningText += content;
+            return { event: preset === 'bi' ? 'reasoning' : 'reasoning', data: options.includeTimestamps ? withMeta({ content }) : content };
+        }
+        case 'message': {
+            const content = event.content || '';
+            state.fullContent += content;
+            return { event: preset === 'bi' ? 'content' : 'content', data: options.includeTimestamps ? withMeta({ content }) : content };
+        }
+        case 'tool_call': {
+            state.toolCallCount++;
+            return {
+                event: preset === 'bi' ? 'tool-call' : 'tool-call',
+                data: withMeta({
+                    toolCallId: event.callId,
+                    toolName: event.tool,
+                    displayName: resolveName(event.tool, event.args || {}, options.toolRegistry),
+                    input: event.args || {},
+                    startedAt: Date.now(),
+                }),
+            };
+        }
+        case 'tool_result': {
+            return {
+                event: preset === 'bi' ? 'tool-result' : 'tool-result',
+                data: withMeta({
+                    toolCallId: event.callId,
+                    toolName: event.tool,
+                    input: {},
+                    output: event.result,
+                    duration: event.duration,
+                    error: event.isError ? event.result : undefined,
+                    completedAt: Date.now(),
+                }),
+            };
+        }
+        case 'done': {
+            state.stepCount = event.iterations || state.stepCount;
+            state.usage = event.usage;
+            return {
+                event: 'done',
+                data: withMeta({
+                    text: state.fullContent || event.content || '',
+                    steps: state.stepCount,
+                    toolCalls: state.toolCallCount,
+                    reasoning: state.reasoningText || undefined,
+                    usage: event.usage,
+                }),
+            };
+        }
+        case 'error':
+            return { event: 'error', data: withMeta({ error: event.error || 'Unknown error', recoverable: event.recoverable }) };
+        case 'steering':
+            return { event: 'steering', data: withMeta({ messages: event.messages, count: event.count }) };
+        case 'retry':
+            return { event: 'retry', data: withMeta({ attempt: event.attempt, maxRetries: event.maxRetries, delay: event.delay, error: event.error, provider: event.provider }) };
+        default:
+            return null;
+    }
+}
+async function* mapAgentEventStream(events, options = {}) {
+    const state = createAgentEventCollectorState();
+    for await (const event of events) {
+        const mapped = mapAgentEvent(event, state, options);
+        if (mapped)
+            yield mapped;
+    }
+}
+//# sourceMappingURL=event-adapter.js.map

package/dist/cjs/utils/event-adapter.js.map

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

package/dist/esm/a2a/client.d.ts

@@ -1,12 +1,33 @@
 import type { A2AAgentCard, A2ASendTaskParams, A2ATask, A2ATaskEvent } from './types.js';
+/**
+ * 认证配置（统一 bearer / basic / apiKey / custom 四种方式）
+ *
+ * value 支持 `${env.VAR_NAME}` 模板，运行时从环境变量读取敏感凭证。
+ */
+export interface AuthConfig {
+    /** 认证方式 */
+    type: 'bearer' | 'basic' | 'apiKey' | 'custom';
+    /** 认证凭证值（支持 `${env.VAR_NAME}` 模板语法） */
+    value: string;
+    /** apiKey/custom 模式下的 header 名称（如 X-API-Key） */
+    name?: string;
+}
+/** 将 AuthConfig 转为 HTTP 请求头 */
+export declare function buildAuthHeaders(auth?: AuthConfig | null): Record<string, string>;
 /** A2A 客户端配置 */
 export interface A2AClientOptions {
     /** 请求超时（毫秒），默认 300000（5分钟） */
     timeout?: number;
+    /** SSE 连接超时（毫秒），默认 30000（30秒） */
+    connectTimeout?: number;
+    /** SSE 逐 chunk 读取超时（毫秒），默认 60000（60秒无数据视为流中断） */
+    chunkTimeout?: number;
     /** 自定义 fetch 实现（默认使用 globalThis.fetch） */
     fetch?: typeof fetch;
     /** 自定义请求头（如认证 token） */
     headers?: Record<string, string>;
+    /** 认证配置（自动转为 headers，与 headers 合并） */
+    auth?: AuthConfig;
 }
 /**
  * 轻量 A2A 协议客户端
@@ -18,6 +39,8 @@ export interface A2AClientOptions {
  */
 export declare class A2AClient {
     private timeout;
+    private connectTimeout;
+    private chunkTimeout;
     private fetchFn;
     private headers;
     constructor(options?: A2AClientOptions);
@@ -31,6 +54,13 @@ export declare class A2AClient {
     /**
      * 流式发送任务（tasks/sendSubscribe），通过回调逐步接收事件
      * 返回最后一个 status-update 事件（通常为 final 事件），用于提取最终结果
+     *
+     * 增强特性：
+     * - connectTimeout: SSE 连接超时（默认 30s）
+     * - chunkTimeout: 逐 chunk 读取超时（默认 60s 无数据视为流中断）
+     * - 外部 AbortSignal 联动（前端断开时中止连接和读取）
+     * - 流异常时保留已接收事件（优雅降级）
+     *
      * @param abortSignal 外部中止信号（前端断开时中止 SSE 读取）
      */
     sendTaskStreaming(agentUrl: string, params: A2ASendTaskParams, onEvent?: (event: A2ATaskEvent) => void, abortSignal?: AbortSignal): Promise<A2ATaskEvent | null>;
@@ -42,8 +72,8 @@ export declare class A2AClient {
     private resolveAgentCardUrl;
     /** 发送 JSON-RPC 请求 */
     private jsonRpcCall;
-    /** 带超时的 reader.read()（每次读取单独计时，收到数据即重置） */
-    private readWithTimeout;
+    /** 带 chunkTimeout 的 reader.read()（每次读取单独计时，收到数据即重置） */
+    private readChunkWithTimeout;
     /** 带超时的 fetch */
     private fetchWithTimeout;
 }