入门05：工具系统与 LLM 集成

工具系统就是"给 AI 配的 API 工具箱"——就像你给前端项目配的工具函数库，但这里 AI 模型可以自己决定调用哪个工具。

---

1. 工具系统长啥样？

让 AI 能"干活"——执行命令、读写文件、搜网页。架构分三层：

---

2. ToolRuntime（工具运行时）

相当于 Vue 的全局组件注册中心 app.component() + 渲染函数。

代码位置：packages/core/tools/src/index.ts

注册工具

class ToolRuntime extends Service {
  // 注册工具，就像 Vue 的 app.component('tool-name', definition)
  define(name: string, definition: ToolDefinition): void

  // 同名工具重复注册会报错（就像组件名不能重复）
}

工具定义（ToolDefinition）

就像定义组件的 props——描述工具叫什么、有什么用、需要什么参数。

interface ToolDefinition {
  name: string        // 工具名（AI 调用时用的名字）
  description: string // 描述（AI 根据这个决定要不要用）
  parameters: {       // 参数定义（JSON Schema 格式，就像 props 类型定义）
    type: 'object',
    properties: { ... },
    required: ['...']
  }
  execute: (args, context) => Promise<result>  // 执行函数
}

执行管线

就像 Express 中间件——每个阶段都能拦截，跟 webpack loader 的 pitch 类似。

创建执行 → pre-execute（waterfall） → guard（守卫检查） → execute（waterfall） → post-execute（waterfall） → 返回结果

每个阶段都可以"插一脚"：

// 在工具执行前加日志
ctx.waterfall('tools/pre-execute', (execution) => {
  console.log(`AI 要调用: ${execution.name}`)
  return execution
})

// 限制子 Agent 能用的工具
toolRuntime.restrict(scopeKey, ['read', 'bash', 'web_search'])

// 设置不可逆的守卫（比如禁止写文件）
toolRuntime.guard((toolName) => {
  return !toolName.startsWith('write_')
})

---

3. 内置了哪些工具？

文件系统（就像 Node.js 的 fs 模块）

工具名	干啥的
read	读文件
read_image	读图片
write	写文件
edit	编辑文件
str_replace_editor	字符串替换编辑器
glob	搜索文件
grep	搜索文件内容

Shell（就像你在终端里敲命令）

工具名	干啥的
bash	执行 bash 命令
pwsh	执行 PowerShell 命令

Web（就像浏览器里搜东西）

工具名	干啥的
web_search	搜索网页
web_fetch	抓取网页内容

终端（就像持久化的命令行窗口）

工具名	干啥的
terminal_open	打开终端会话
terminal_send	发命令
terminal_read	读输出
terminal_close	关闭

子 Agent（就像开子线程）

工具名	干啥的
subagent	创建子 Agent 干活
send_message	给子 Agent 发消息
interrupt_agent	中断子 Agent

其他

工具名	干啥的
todo_write	管理任务列表
workflow	执行工作流
ask_user_question	向用户提问
schedule_create	创建定时任务
job_kill	杀掉后台任务

---

4. LLM 适配器机制

就像 axios 的 adapter——不管你用 fetch 还是 XMLHttpRequest，axios 的调用方式都一样。换后端只需换个 adapter。

代码位置：packages/llm/llm/src/index.ts

abstract class LlmAdapter {
  abstract name: string           // 适配器名字
  abstract models: string[]       // 支持的模型列表

  // 流式调用（就像 fetch 的 stream）
  abstract stream(options: GenerateOptions): AsyncIterable<StreamChunk>
}

内置适配器

适配器	包位置	支持模型
DeepSeek	packages/llm/llm-deepseek/	deepseek-chat, deepseek-reasoner
Pi.ai	packages/llm/llm-pi-ai/	pi-model

---

5. 自定义工具（写一个自己的工具）

就像写一个 Vue 组件——定义名字、props、执行逻辑。

// 写一个问候工具
const myTool = defineTool({
  name: 'my_greeting',
  description: '向用户问好',
  parameters: {
    type: 'object',
    properties: {
      name: { type: 'string', description: '用户名称' },
    },
    required: ['name'],
  },
  async execute(args: { name: string }) {
    return {
      success: true,
      data: `你好, ${args.name}!`,
    }
  },
})

// 注册到工具系统
ctx.tools.define('my_greeting', myTool)

---

6. 工具与 AI 的完整交互流程

---

要点总结

• 工具系统 = 给 AI 配的 API 工具箱，注册、执行、拦截一应俱全
• ToolRuntime = 工具注册中心，像 Vue 的 app.component()
• 执行管线 = 像 Express 中间件，每个阶段都能拦截
• 内置 30+ 工具：文件、Shell、Web、终端、子 Agent 等
• LLM 适配器 = 像 axios adapter，换模型只需换配置
• 自定义工具 = 写个 defineTool 注册就行

进阶阅读

• 工具源码：packages/core/tools/src/
• LLM 源码：packages/llm/llm/src/
• DeepSeek 适配器：packages/llm/llm-deepseek/src/
• 名词速查：附录-AI 概念名词速查手册
• 下一步：06-会话持久化与状态管理