@kernel4632/agent-core 0.38.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +243 -1463
- package/dist/agent-core.js +151 -343
- package/dist/types/index.d.ts +2 -0
- package/dist/types/src/agent.d.ts +20 -0
- package/dist/types/src/context/build.d.ts +26 -0
- package/dist/types/src/history.d.ts +10 -0
- package/dist/types/src/loop/compact.d.ts +6 -0
- package/dist/types/src/loop/decide.d.ts +10 -0
- package/dist/types/src/loop/run.d.ts +3 -0
- package/dist/types/src/model/ask.d.ts +2 -0
- package/dist/types/src/model/configure.d.ts +5 -0
- package/dist/types/src/model/text-tools/describe.d.ts +11 -0
- package/dist/types/src/model/text-tools/parse.d.ts +6 -0
- package/dist/types/src/tools/child.d.ts +13 -0
- package/dist/types/src/tools/load.d.ts +6 -0
- package/dist/types/src/tools/mcp.d.ts +5 -0
- package/dist/types/src/tools/run.d.ts +16 -0
- package/dist/types/src/tools/shape.d.ts +16 -0
- package/dist/types/src/tools/spawn.d.ts +19 -0
- package/dist/types/src/types.d.ts +324 -0
- package/dist/types/src/utils/errors.d.ts +9 -0
- package/dist/types/src/utils/retry.d.ts +17 -0
- package/dist/types/src/utils/tokens.d.ts +13 -0
- package/package.json +19 -17
- package/dist/agent-core.d.ts +0 -288
package/README.md
CHANGED
|
@@ -3,1589 +3,369 @@
|
|
|
3
3
|
[](https://github.com/kernel4632/agent-core/actions/workflows/ci.yml)
|
|
4
4
|
[](https://github.com/kernel4632/agent-core/releases/latest)
|
|
5
5
|
|
|
6
|
-
一个轻量的 AI Agent
|
|
6
|
+
一个轻量的 AI Agent 核心包(TypeScript,运行在 Bun 上)。给它一个模型和一组工具文件路径(也可以接 MCP 服务),
|
|
7
|
+
它就自动循环"问模型 → 执行工具 → 再问模型",直到任务完成。
|
|
7
8
|
|
|
8
9
|
---
|
|
9
10
|
|
|
10
11
|
## 目录
|
|
11
12
|
|
|
12
13
|
- [这个包是干什么的](#这个包是干什么的)
|
|
13
|
-
- [
|
|
14
|
+
- [核心设计](#核心设计)
|
|
14
15
|
- [安装](#安装)
|
|
15
16
|
- [5 分钟快速上手](#5-分钟快速上手)
|
|
16
|
-
- [
|
|
17
|
-
- [
|
|
18
|
-
- [项目架构](#项目架构)
|
|
19
|
-
- [自定义工具:从零到完整](#自定义工具从零到完整)
|
|
17
|
+
- [工具文件](#工具文件)
|
|
18
|
+
- [接 MCP](#接-mcp)
|
|
20
19
|
- [API 参考](#api-参考)
|
|
20
|
+
- [上下文与压缩](#上下文与压缩)
|
|
21
21
|
- [上生产前](#上生产前)
|
|
22
|
-
- [
|
|
23
|
-
- [
|
|
24
|
-
- [长跑压测](#长跑压测)
|
|
25
|
-
- [运行测试](#运行测试)
|
|
26
|
-
- [打包成单文件](#打包成单文件)
|
|
22
|
+
- [项目架构](#项目架构)
|
|
23
|
+
- [开发与发布](#开发与发布)
|
|
27
24
|
- [这个包不做什么](#这个包不做什么)
|
|
28
|
-
- [常见问题](#常见问题)
|
|
29
25
|
|
|
30
26
|
---
|
|
31
27
|
|
|
32
28
|
## 这个包是干什么的
|
|
33
29
|
|
|
34
|
-
你可以把它理解成一个"AI 大脑驱动引擎":
|
|
35
|
-
|
|
36
30
|
```mermaid
|
|
37
31
|
flowchart TD
|
|
38
|
-
app["你的程序"] --> create["Agent.create()
|
|
39
|
-
create --> send["agent.send()
|
|
40
|
-
send --> loop["
|
|
41
|
-
loop --> llm["
|
|
42
|
-
loop --> tool["
|
|
32
|
+
app["你的程序"] --> create["Agent.create()"]
|
|
33
|
+
create --> send["agent.send()"]
|
|
34
|
+
send --> loop["loop:自动循环"]
|
|
35
|
+
loop --> llm["model:问模型"]
|
|
36
|
+
loop --> tool["tools:子进程执行工具"]
|
|
43
37
|
tool --> loop
|
|
44
38
|
```
|
|
45
39
|
|
|
46
|
-
模型每次回复要么"调用某个工具",要么"我做完了"
|
|
40
|
+
模型每次回复要么"调用某个工具",要么"我做完了"。这个包负责把循环跑起来;你只需要写工具文件,把路径交给它。
|
|
47
41
|
|
|
48
42
|
---
|
|
49
43
|
|
|
50
|
-
##
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
44
|
+
## 核心设计
|
|
45
|
+
|
|
46
|
+
**① Agent 是唯一的状态持有者。** 宿主能改的东西都是实例上的公开字段:`config`、`history`、`tools`、`MCP.list`、
|
|
47
|
+
`contextRatio`、`ratios`(以及 `id`)。直接改,下一轮请求就生效,不需要调任何"通知"方法。
|
|
48
|
+
内部状态(子进程、工具缓存、MCP 连接、取消器)是私有字段,模块里没有任何全局可变状态,多个实例完全隔离。
|
|
49
|
+
|
|
50
|
+
**② 工具只认文件路径。** `tools` 是路径数组,目录是"其中全部工具文件"的简写。每一轮请求前现读:
|
|
51
|
+
文件改了(修改时间变了)自动重读,路径删了下一轮就没有这个工具。插件、技能、开关这些概念属于宿主——
|
|
52
|
+
宿主按插件增删路径即可,核心不知道"插件"是什么。
|
|
53
|
+
|
|
54
|
+
**③ 每个工具调用独占一个子进程。** 用 `process.execPath`(当前 Bun)启动,经 IPC 通信。工具死循环、崩溃都不会拖垮 Agent;
|
|
55
|
+
`agent.stop()` 直接杀掉本实例的全部子进程,不给工具任何反应时间。
|
|
56
|
+
|
|
57
|
+
**④ history 只增不删,只有 loop 写它。** 模型消息、工具结果按发生顺序追加;压缩也只追加一条 `role: 'compact'` 的总结。
|
|
58
|
+
每个出口都补一条模型能读的结果(工具失败、调用无效、被取消都会写一条结果),绝不留下"有调用、没结果"的残缺记录。
|
|
59
|
+
问模型出错(每次重试前、最终失败、上下文超长,压缩请求也一样)追加一条 `role: 'error'`:`content` 是给人看的错误描述(分类、状态码、服务端原话;厂商格式解析不了就取原始响应体里的 message),
|
|
60
|
+
`request` 存 `{ kind, statusCode, model, protocol, attempt | final, compact? }`;和上一条是同一个错误(内容相同)就不重复记,用户 `stop()` 不记。
|
|
61
|
+
模型回复写进 history 前去掉 AI SDK 的 `custom` 元数据块(发请求用不上),思考块、签名和各块的 `providerOptions` 原样保留。
|
|
62
|
+
一次模型请求产出一条 `assistant`(纯调工具也是),上面挂着这次请求的记录;压缩请求的记录挂在它写的 `compact` 上,形状相同:
|
|
63
|
+
|
|
64
|
+
```ts
|
|
65
|
+
request: {
|
|
66
|
+
model: string, // 模型名(核心只有模型,没有供应商)
|
|
67
|
+
start: number, // 请求发出的毫秒时间戳
|
|
68
|
+
first?: number, // 首字耗时(毫秒):start 到第一个正文 / 思考 / 工具调用片段;只有流式有
|
|
69
|
+
duration: number, // 完整耗时(毫秒)
|
|
70
|
+
usage?: { input?, output?, cacheRead?, cacheWrite? } // 只放供应商真报了的;一个都没报就没有 usage,不补 0
|
|
71
|
+
}
|
|
74
72
|
```
|
|
75
73
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
**① 模型不调工具,不会立刻结束。** 很多模型在任务没做完时会"礼貌地"给一段总结就停下。直接结束会把没干完的活丢掉。所以有工具时,模型不调工具会先**临时**插一句提醒(`noToolPrompt`)再问一次,连续 `noToolRounds` 轮(默认 3)都不调才结束。这句提醒只挂在那一次请求上,**不写进 `history`**。不想要这个行为,把 `noToolRounds` 设成 `Infinity`。
|
|
79
|
-
|
|
80
|
-
**② `history` 是唯一的权威数据来源,只增不删。** 循环从不修改历史,模型消息、工具结果按发生的顺序追加。连压缩也只追加一条总结。原因:`history` 归你的应用所有(存库、渲染、多会话),核心替它丢弃数据是不可逆的错误——该留多少由持有它的你决定。
|
|
81
|
-
|
|
82
|
-
**③ 一轮里的工具并行执行。** 模型经常一次要求调好几个工具;串行会让任务慢好几倍。所以同一轮的工具同时开跑,结果按原顺序收齐再写回历史。每个工具独占一个子进程,所以死循环的工具能被一刀杀掉,崩溃的工具不会拖垮 Agent。
|
|
83
|
-
|
|
84
|
-
**④ 每次 `send` 只跑一个任务,"最新指令优先"。** 新的 `send` 会先停掉上一个(同一次 tick 里发出的请求,后者一定看得见前者并把它停掉)。原因:一台 Agent 只有一份 `history`,两个任务同时写会乱序。
|
|
85
|
-
|
|
86
|
-
**⑤ 每个出口都补一条模型能读的结果。** 取消 → 一条"已中断"结果;工具失败 → 一条错误结果;模型点了不存在的工具 → 一条"调用无效"结果。**绝不留下"有调用、没结果"的残缺记录**。原因:这种残缺序列会被 OpenAI / Anthropic 直接 400,而 `history` 只增不删,一次残缺就永久毒死这个会话,重启装回历史也一样。
|
|
87
|
-
|
|
88
|
-
### 二、独特的上下文压缩保留方案
|
|
74
|
+
计时只算成功的那次尝试(失败的尝试各记一条 `error`)。这些字段只存在 history 里,发给模型时和 `id` 一起去掉。
|
|
89
75
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
`history` 里原文一条不少;每次发请求时,只从里面**现挑**该带哪些回合:
|
|
93
|
-
|
|
94
|
-
| history 里的位置 | 内容 | 这一次发给模型吗 |
|
|
95
|
-
|------------------|------|------------------|
|
|
96
|
-
| 最初 | 用户最初的目标 | 保留:最多 3 个用户回合、≤20% 预算 |
|
|
97
|
-
| 中段 | 更早的回合 | 已被总结覆盖,不再单独发 |
|
|
98
|
-
| 总结 | 最新一条 `compact` 总结 | 折进 `system`(不是当消息) |
|
|
99
|
-
| 总结前 | 最近的现场回合 | 保留:默认最多 3 个回合、≤30% 预算 |
|
|
100
|
-
| 总结后 | 之后的全部新回合 | 全部保留(当前正在推进的) |
|
|
101
|
-
|
|
102
|
-
这几个数(3 / 3 / 20% / 30%)是**默认值**,宿主可以用 `config.contextKeep` 覆盖;传 `{ firstTurns: 0 }` 就是压缩后连最初那几轮原文也不带,只信总结 + 最近现场(见下方「上下文压缩保留方案」)。
|
|
103
|
-
|
|
104
|
-
几个关键取舍,以及为什么:
|
|
105
|
-
|
|
106
|
-
- **裁剪的最小单位是「回合」,不是「消息」。** 一个回合 = 用户一次发言,或模型的一次响应连同它发起的全部工具调用和结果。工具结果按 `toolCallId` 回到发起它的回合,**同进同出**。所以裁剪结果永远不会切断"调用 / 结果"的配对——那种残缺会被供应商 400。
|
|
107
|
-
- **最新那条总结折进 system,而不是当成一条消息塞进对话。** 裸的 `role:'user'` 总结会被模型读成"用户塞给我一张表",于是从头重做整个任务。实测 `gpt-oss-120b` 折进 system 前只有 1/6 能正确接着做,之后 6/6。
|
|
108
|
-
- **总结里保留最初目标。** 挑内容时,最初那几轮用户发言(说不出的话)单独钉住,默认最多 3 个回合、占 20% 预算。就算预算装不下,总结本身也被要求保留"用户最初的目标",而总结在 `system` 里永远不会被裁掉。这几个数可以用 `contextKeep` 调小甚至设成 0——原始措辞和总结里的目标同时出现时,模型有时会把旧话当成当前指令。
|
|
109
|
-
- **二次压缩不会忘掉上一次的总结。** 压缩请求会把上一版总结作为"背景"并进提示词,新总结必须保留其中仍然有效的事实。直接丢掉旧总结,会越压越忘。
|
|
110
|
-
- **按预算保留,不按条数。** 用户第一条消息就粘一大段日志时,只按条数留会让压缩永远收敛不了(实测 120/120 轮压完仍超阈值)。所以旧内容按预算分:目标 20%、最近现场 30%。
|
|
111
|
-
- **每轮最多压一次。** 不为"压到达标"而连续调用模型——那样一轮能烧掉上千次请求(实测)。压完还超限就照常发出去,由服务端判断;下一轮还超自然会再压一次。
|
|
112
|
-
|
|
113
|
-
> 一句话:**history 永不删、总结折进 system、裁剪按回合。** 这三条一起保证——发给模型的永远是合法上下文,模型永远能"接着做"而不是"重做",而你的完整历史一条都没丢。
|
|
76
|
+
**⑤ 停不停由模型和工具决定,没有"最大轮数"。** 模型不调工具时,先临时挂一句提醒再问(不进 history),
|
|
77
|
+
连续 `noToolRounds` 轮(默认 3)都不调才结束;工具返回 `stop: true` 立即结束。
|
|
114
78
|
|
|
115
79
|
---
|
|
116
80
|
|
|
117
81
|
## 安装
|
|
118
82
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
从 npm 安装:
|
|
83
|
+
需要 [Bun](https://bun.sh) ≥ 1.4.4(不支持 Node.js)。
|
|
122
84
|
|
|
123
85
|
```bash
|
|
124
86
|
bun add @kernel4632/agent-core
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
想锁死某个版本(比如 `0.24.18`),在包名后写版本号:
|
|
128
|
-
|
|
129
|
-
```bash
|
|
130
|
-
bun add @kernel4632/agent-core@0.24.18
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
也可以从 GitHub Release 安装,永远拿到最新版:
|
|
134
|
-
|
|
135
|
-
```bash
|
|
87
|
+
# 或从 GitHub Release 安装最新版
|
|
136
88
|
bun add https://github.com/kernel4632/agent-core/releases/latest/download/agent-core.tgz
|
|
137
89
|
```
|
|
138
90
|
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
```bash
|
|
142
|
-
bun add https://github.com/kernel4632/agent-core/releases/download/v0.24.18/agent-core.tgz
|
|
143
|
-
```
|
|
144
|
-
|
|
145
|
-
以后升级到最新版,再运行一次安装命令就行。
|
|
91
|
+
发布包是单文件 `dist/agent-core.js`(依赖全部打进去,工具子进程入口也内联在里面)加 `dist/types/` 类型声明。
|
|
146
92
|
|
|
147
93
|
---
|
|
148
94
|
|
|
149
95
|
## 5 分钟快速上手
|
|
150
96
|
|
|
151
|
-
|
|
97
|
+
第一步,写一个工具文件 `tools/say-hello.ts`。它是零依赖的纯对象,不需要 import 任何东西:
|
|
152
98
|
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
```js
|
|
99
|
+
```ts
|
|
156
100
|
export default {
|
|
157
|
-
name: 'say_hello',
|
|
158
|
-
description: '
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
name: { type: 'string', description: '要打招呼的人的名字' },
|
|
163
|
-
},
|
|
164
|
-
required: ['name'],
|
|
165
|
-
},
|
|
166
|
-
async execute(input) { // 真正执行的函数,input 就是模型传来的参数
|
|
167
|
-
return `你好,${input.name}!` // 返回值会原样告诉模型
|
|
101
|
+
name: 'say_hello',
|
|
102
|
+
description: '向指定的人打个招呼',
|
|
103
|
+
parameters: { type: 'object', properties: { who: { type: 'string' } }, required: ['who'] },
|
|
104
|
+
run({ who }: { who: string }) {
|
|
105
|
+
return `你好,${who}!`
|
|
168
106
|
},
|
|
169
107
|
}
|
|
170
108
|
```
|
|
171
109
|
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
新建 `main.js`:
|
|
175
|
-
|
|
176
|
-
```js
|
|
177
|
-
import Agent from '@kernel4632/agent-core'
|
|
110
|
+
第二步,创建 Agent 并发送指令:
|
|
178
111
|
|
|
179
|
-
|
|
180
|
-
|
|
112
|
+
```ts
|
|
113
|
+
import { Agent } from '@kernel4632/agent-core'
|
|
181
114
|
|
|
182
|
-
// 创建一个 Agent 实例
|
|
183
115
|
const agent = Agent.create({
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
},
|
|
190
|
-
tools, // 把扫描好的工具传进来
|
|
191
|
-
callbacks: {
|
|
192
|
-
onToolResult: result => { // 工具执行完时的回调
|
|
193
|
-
console.log('工具执行完了:', result.toolName, result.output)
|
|
194
|
-
},
|
|
195
|
-
},
|
|
116
|
+
baseURL: 'https://api.openai.com/v1',
|
|
117
|
+
apiKey: process.env.OPENAI_API_KEY,
|
|
118
|
+
model: 'gpt-4o',
|
|
119
|
+
system: '你是一个助手。',
|
|
120
|
+
tools: ['/abs/path/to/tools'], // 文件或目录的路径
|
|
196
121
|
})
|
|
197
122
|
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
console.log('Agent 结束,原因:', result.reason) // 有工具时通常是 'no-tool':模型停手后还会被追问最多 noToolRounds 轮(默认 3)才结束
|
|
201
|
-
```
|
|
202
|
-
|
|
203
|
-
> 上面这个例子里注册了工具,所以模型就算一次就把话说完了,`send` 也不会立刻返回——它会连续几轮确认模型真的不再用工具(这是这个包循环的特点,避免模型过早收手)。想一停手就结束,设 `noToolRounds: 1`;想明确收尾,写一个返回 `stop: true` 的 `finish` 工具。
|
|
204
|
-
|
|
205
|
-
运行:
|
|
206
|
-
|
|
207
|
-
```bash
|
|
208
|
-
bun main.js
|
|
209
|
-
```
|
|
210
|
-
|
|
211
|
-
---
|
|
212
|
-
|
|
213
|
-
## 三种用法:从纯聊天到接 MCP 和技能
|
|
214
|
-
|
|
215
|
-
先看清自己属于哪一种,再往下读:
|
|
216
|
-
|
|
217
|
-
| 你想做什么 | 怎么写 | 去哪看 |
|
|
218
|
-
|------------|--------|--------|
|
|
219
|
-
| 只聊天,不用工具 | `Agent.create({ config })` 然后 `agent.send('...')` | 上面的快速上手 |
|
|
220
|
-
| 用普通工具(自己写的文件) | `tools = await Agent.tool.from('./tools')`,传给 `create` | 「自定义工具」「`Agent.tool`」 |
|
|
221
|
-
| 用 MCP 工具、用技能(skills) | 应用自己连 MCP、读技能,再用 `Agent.tool.from(...)` 汇进来 | 下一节「接入 MCP 和技能」 |
|
|
222
|
-
|
|
223
|
-
一句话记住:**这个包只负责"循环 + 执行工具"**。MCP 的连接、技能的读取都不是它的事——你把它们变成普通工具对象交进来就行。
|
|
224
|
-
|
|
225
|
-
---
|
|
226
|
-
|
|
227
|
-
## 接入 MCP 和技能
|
|
228
|
-
|
|
229
|
-
MCP 和技能(skills)都由**你的应用**负责,核心只接收通用工具对象。两者的做法一样:先拿到"工具对象",再交给 `Agent.tool.from`。
|
|
230
|
-
|
|
231
|
-
```mermaid
|
|
232
|
-
flowchart TD
|
|
233
|
-
f["文件工具<br/>./tools"] --> from["Agent.tool.from(...)"]
|
|
234
|
-
m["MCP 工具<br/>mcp.tools()"] --> from
|
|
235
|
-
s["技能工具<br/>skills.readTool()"] --> from
|
|
236
|
-
from --> agent["Agent.create(...)"]
|
|
237
|
-
```
|
|
238
|
-
|
|
239
|
-
### 接 MCP
|
|
240
|
-
|
|
241
|
-
MCP 是"模型调用外部服务"的标准协议。用官方客户端 `@ai-sdk/mcp` 连上服务后,它给出的工具对象**直接就能用**,不需要任何包装:
|
|
242
|
-
|
|
243
|
-
```js
|
|
244
|
-
import { createMCPClient } from '@ai-sdk/mcp'
|
|
245
|
-
import { Experimental_StdioMCPTransport as Stdio } from '@ai-sdk/mcp/mcp-stdio' // stdio 传输要从子路径导入
|
|
246
|
-
|
|
247
|
-
// 连接由你的应用管理:什么时候连、连哪个、什么时候关
|
|
248
|
-
const mcp = await createMCPClient({
|
|
249
|
-
transport: new Stdio({ command: 'bun', args: ['./mcp-server.js'] }),
|
|
123
|
+
const { reason, text, usage } = await agent.send('请向世界打个招呼', {
|
|
124
|
+
onChunk: chunk => { if (chunk.type === 'text') process.stdout.write(chunk.text) },
|
|
250
125
|
})
|
|
251
|
-
|
|
252
|
-
const tools = await Agent.tool.from('./tools', mcp.tools()) // 就这一句
|
|
253
|
-
const agent = Agent.create({ config, tools })
|
|
254
|
-
|
|
255
|
-
// ... 用完后
|
|
256
|
-
await mcp.close()
|
|
257
|
-
```
|
|
258
|
-
|
|
259
|
-
> MCP 工具的返回值(文字、图片)会自动转成模型能读的块。想自己改写,见「`Agent.tool.adopt`」。
|
|
260
|
-
|
|
261
|
-
### 接技能(skills)
|
|
262
|
-
|
|
263
|
-
技能是"现成的操作步骤":一个文件夹放一份 `SKILL.md`,开头写名字和说明,下面是正文。约定见 [agentskills.io](https://agentskills.io)。
|
|
264
|
-
|
|
265
|
-
```
|
|
266
|
-
skills/
|
|
267
|
-
└── review-pr/
|
|
268
|
-
└── SKILL.md # 开头是 name 和 description,下面是步骤正文
|
|
269
|
-
```
|
|
270
|
-
|
|
271
|
-
社区有现成的库负责**读取和校验**这些文件,比如 `agent-skills-ts-sdk`。它给你两样东西:一段"技能清单"(放进 `system` 让模型知道有哪些技能)和一个"按需读正文"的工具。扫描、组装仍由你写,就是下面这几行:
|
|
272
|
-
|
|
273
|
-
```js
|
|
274
|
-
import { createSkillRegistry, skillSourceFromEntries } from 'agent-skills-ts-sdk'
|
|
275
|
-
|
|
276
|
-
const sources = []
|
|
277
|
-
for await (const file of new Bun.Glob('skills/*/SKILL.md').scan()) {
|
|
278
|
-
sources.push(skillSourceFromEntries(
|
|
279
|
-
[{ name: 'SKILL.md', content: await Bun.file(file).text() }],
|
|
280
|
-
{ id: file, location: file },
|
|
281
|
-
))
|
|
282
|
-
}
|
|
283
|
-
const skills = await createSkillRegistry(sources)
|
|
284
|
-
const decl = skills.readTool() // 技能清单 + 一个"读正文"的工具声明
|
|
285
|
-
|
|
286
|
-
const skillTool = {
|
|
287
|
-
description: decl.description,
|
|
288
|
-
inputSchema: decl.parametersJsonSchema,
|
|
289
|
-
execute: async args => {
|
|
290
|
-
const r = await skills.read(args)
|
|
291
|
-
return r.ok ? r.content : { output: { type: 'error-text', value: r.error } }
|
|
292
|
-
},
|
|
293
|
-
}
|
|
294
|
-
|
|
295
|
-
// 清单进 system,正文等模型需要时用 skill 工具读
|
|
296
|
-
const system = ['你是一个编程助手。', skills.systemPrompt()].filter(Boolean).join('\n\n')
|
|
297
|
-
const tools = await Agent.tool.from({ [decl.name]: skillTool })
|
|
298
|
-
const agent = Agent.create({ config: { ...config, system }, tools })
|
|
299
|
-
|
|
300
|
-
await agent.send('按 review-pr 技能审查这个改动')
|
|
301
|
-
```
|
|
302
|
-
|
|
303
|
-
### MCP 和技能一起用
|
|
304
|
-
|
|
305
|
-
一次性汇进去就行:
|
|
306
|
-
|
|
307
|
-
```js
|
|
308
|
-
const tools = await Agent.tool.from(
|
|
309
|
-
'./tools', // 文件工具
|
|
310
|
-
mcp.tools(), // MCP 工具
|
|
311
|
-
{ [decl.name]: skillTool }, // 技能加载工具
|
|
312
|
-
)
|
|
313
|
-
```
|
|
314
|
-
|
|
315
|
-
<details>
|
|
316
|
-
<summary>不想引库?自己读 SKILL.md 也就十几行</summary>
|
|
317
|
-
|
|
318
|
-
`SKILL.md` 的开头是一小段用 `---` 包起来的说明(`name` 和 `description`),下面是正文。自己切开即可:
|
|
319
|
-
|
|
320
|
-
```js
|
|
321
|
-
const skills = {}
|
|
322
|
-
for await (const path of new Bun.Glob('skills/*/SKILL.md').scan()) {
|
|
323
|
-
const text = await Bun.file(path).text()
|
|
324
|
-
const name = text.match(/name:\s*(.+)/)?.[1]?.trim()
|
|
325
|
-
const description = text.match(/description:\s*(.+)/)?.[1]?.trim()
|
|
326
|
-
const body = text.replace(/^---[\s\S]*?---/, '').trim() // 去掉说明段,只留正文
|
|
327
|
-
if (name) skills[name] = { description, body }
|
|
328
|
-
}
|
|
329
|
-
|
|
330
|
-
const names = Object.keys(skills)
|
|
331
|
-
const system = names.length
|
|
332
|
-
? '可用技能(需要时用 skill 工具读正文):\n' + names.map(n => `- ${n}:${skills[n].description}`).join('\n')
|
|
333
|
-
: ''
|
|
334
|
-
|
|
335
|
-
const skillTool = {
|
|
336
|
-
skill: {
|
|
337
|
-
description: '按名字读取一个技能的完整步骤',
|
|
338
|
-
inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
|
|
339
|
-
execute: async ({ name }) => {
|
|
340
|
-
if (!Object.hasOwn(skills, name)) throw new Error(`没有技能 ${name}`)
|
|
341
|
-
return skills[name].body
|
|
342
|
-
},
|
|
343
|
-
},
|
|
344
|
-
}
|
|
345
|
-
|
|
346
|
-
// 拼装:提示词进 system,读正文的工具进 tools
|
|
347
|
-
const tools = await Agent.tool.from('./tools', skillTool)
|
|
348
|
-
const agent = Agent.create({ config: { ...config, system: ['你是一个助手。', system].filter(Boolean).join('\n\n') }, tools })
|
|
349
126
|
```
|
|
350
127
|
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
</details>
|
|
354
|
-
|
|
355
|
-
---
|
|
356
|
-
|
|
357
|
-
## 项目架构
|
|
358
|
-
|
|
359
|
-
```
|
|
360
|
-
@kernel4632/agent-core
|
|
361
|
-
│
|
|
362
|
-
├── index.js ← 唯一入口:create / send / stop / compact,把下面的功能组合起来
|
|
363
|
-
│
|
|
364
|
-
├── features/ ← 功能:由入口或主循环组合起来用,每个文件一个主体
|
|
365
|
-
│ ├── loop.js ← 主循环:Context → TextTools → LLM → 工具 → ...
|
|
366
|
-
│ ├── llm.js ← 只负责和模型说话:四种协议、缓存、超时、错误分类
|
|
367
|
-
│ ├── text-tools.js ← 文字工具协议:让纯对话模型也能调用工具
|
|
368
|
-
│ ├── history.js ← 对话记录:造消息块、拆回合、渲染
|
|
369
|
-
│ ├── context.js ← 把历史消息裁剪成这一轮发给模型的上下文
|
|
370
|
-
│ ├── compact.js ← 上下文太长时写总结
|
|
371
|
-
│ ├── tool.js ← 工具:扫描文件工具、接纳内存工具、执行、合并(主线程这一半)
|
|
372
|
-
│ └── tool-process.js ← 文件工具真正跑起来的地方(子进程那一半)
|
|
373
|
-
│
|
|
374
|
-
└── utils/ ← 工具:被功能调用,不反过来依赖功能
|
|
375
|
-
├── retry.js ← 失败自动重试(指数退避)
|
|
376
|
-
├── notify.js ← 所有回调的统一出口
|
|
377
|
-
├── schema.js ← 工具参数格式归一化(scan 和 adopt 共用)
|
|
378
|
-
├── shape.js ← 工具返回值变成输出块(内存工具用;子进程里有一份副本)
|
|
379
|
-
└── tokens.js ← 上下文 token 估算:文字按字符数 × 每字符 token 比(比例由真实 usage 自校准),媒体按块计
|
|
380
|
-
```
|
|
381
|
-
|
|
382
|
-
`tool.js` 和 `tool-process.js` 是同一件事的两半,所以放在一起:前者在主线程里找工具、管工具进程,
|
|
383
|
-
后者被前者当成文本内联、在独立的 bun 子进程里加载并执行工具。分成两个文件是平台限制,不是分层。
|
|
384
|
-
|
|
385
|
-
**工具进程隔离的是生命周期,不是环境。** 工具在里面拥有和 Agent 完全相同的权限:读写任意文件、执行任意命令、联网、读到父进程的全部环境变量。这是有意的——电脑任务 agent 的工具本来就得能干这些。它真正隔离的是四样:**失控**(死循环工具能被一刀杀掉,实测 0ms)、**崩溃**(工具死了 Agent 继续跑)、**内存**(独立堆)、**Agent 状态**(工具碰不到 `history`、`config`、`running`)。
|
|
386
|
-
|
|
387
|
-
**为什么用子进程而不是 Worker 线程**:Worker 被 `terminate()` 之后 Bun 不归还它占的约 22MB,
|
|
388
|
-
而且杀线程带不走它 `Bun.spawn` 出来的孙进程。常驻 agent 天天要杀工具进程(工具崩溃、超时、用户打断),
|
|
389
|
-
两笔账会一直累积。换成子进程之后实测 200 次「起→用→杀」主进程只涨 2MB(Worker 版是 4.4GB),
|
|
390
|
-
孙进程一起带走,主进程退出时工具进程也全部跟着死。复用时单次调用 0.08ms,比 Worker 还快。
|
|
391
|
-
|
|
392
|
-
### 数据流
|
|
393
|
-
|
|
394
|
-
```mermaid
|
|
395
|
-
flowchart TD
|
|
396
|
-
send["agent.send(input)"] --> hu["History.user()"]
|
|
397
|
-
hu --> ctx["Context.build()<br/>裁剪上下文"]
|
|
398
|
-
ctx --> llm["LLM.chat()<br/>请求模型"]
|
|
399
|
-
llm --> q{"模型要调工具?"}
|
|
400
|
-
q -->|要| te["Tool.execute()<br/>并行执行"]
|
|
401
|
-
te --> wr["结果写入 history"]
|
|
402
|
-
wr --> ctx
|
|
403
|
-
q -->|不要| done["结束判定<br/>(分支见「核心设计」)"]
|
|
404
|
-
```
|
|
128
|
+
离线可跑的完整示例见 [`examples/minimal`](examples/minimal/):`bun examples/minimal/main.ts`。
|
|
405
129
|
|
|
406
130
|
---
|
|
407
131
|
|
|
408
|
-
##
|
|
132
|
+
## 工具文件
|
|
409
133
|
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
```js
|
|
413
|
-
// tools/add.js
|
|
134
|
+
```ts
|
|
414
135
|
export default {
|
|
415
|
-
name:
|
|
416
|
-
description:
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
b: { type: 'number' },
|
|
422
|
-
},
|
|
423
|
-
required: ['a', 'b'],
|
|
424
|
-
},
|
|
425
|
-
async execute(input) {
|
|
426
|
-
return input.a + input.b // 直接返回结果
|
|
427
|
-
},
|
|
136
|
+
name: string, // 工具名(同一个 Agent 内重名的,后读到的被跳过并警告)
|
|
137
|
+
description: string,
|
|
138
|
+
parameters: JSONSchema, // 只收 JSON Schema,顶层必须是 type: 'object'
|
|
139
|
+
run(args) { ... }, // 只有 args;可以是 async,也可以是 async generator
|
|
140
|
+
toModelOutput?({ output, input, toolCallId }) { ... }, // 可选:把结果改写成给模型看的输出块(与 AI SDK 同签名)
|
|
141
|
+
timeout?: number, // 可选:单次执行超时(毫秒)
|
|
428
142
|
}
|
|
429
143
|
```
|
|
430
144
|
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
145
|
+
- **一个文件一个工具。** 目录展开时收 `.ts` / `.js` / `.mjs`(不含 `.d.ts`),按文件名排序。
|
|
146
|
+
- **返回值:** 字符串或可 JSON 化的值都行;`{ stop: true, ... }` 让循环结束(reason 为 `tool-stop`)。
|
|
147
|
+
generator 的每次 yield 实时转给 `onToolOutput`,全部片段一起作为结果。默认不截断;设了 `maxToolOutput` 时,
|
|
148
|
+
超长的文字(含 `content` 里的文字块)保留开头 70%、结尾 30%,中间注明省略了多少字符并提示模型缩小范围重新获取。
|
|
149
|
+
返回成形块(`{ type: 'text' | 'json' | 'content' | ... }`)但形状不对时,模型收到一条说明哪里不对的错误结果。
|
|
150
|
+
- **出错就是结果:** `run` 抛错、超时、子进程崩溃,都会变成一条错误文字结果交给模型,循环继续。
|
|
151
|
+
超时和崩溃的错误里带上工具已经输出的部分(头尾各保留一段);被系统 SIGKILL(常见于内存不足)和被 `stop()` 取消分开说明。
|
|
152
|
+
- **调用本身无效**(参数解析失败、工具不存在):不问 `onPermission`、不执行,直接写一条"工具调用无效:原因"结果让模型自己改。
|
|
153
|
+
- **坏文件不会拖垮循环:** 读不出来(语法错、导出不合法、加载超过 3 秒)的文件被跳过,通过 `onWarning` 提醒一次;
|
|
154
|
+
按修改时间记住,文件没改之前不会每轮重试。
|
|
155
|
+
- 工具的 stdout / stderr 通过 `onToolOutput` 实时转给宿主,不会污染和子进程之间的协议。
|
|
156
|
+
- 工具子进程和 Agent 权限相同(文件、网络、环境变量)。危险操作请在宿主的 `onPermission` 里拦。
|
|
434
157
|
|
|
435
|
-
|
|
436
|
-
// tools/count.js
|
|
437
|
-
export default {
|
|
438
|
-
name: 'count',
|
|
439
|
-
description: '从 1 数到 n,逐步输出',
|
|
440
|
-
inputSchema: {
|
|
441
|
-
type: 'object',
|
|
442
|
-
properties: { n: { type: 'number' } },
|
|
443
|
-
required: ['n'],
|
|
444
|
-
},
|
|
445
|
-
async *execute(input) { // 注意:async * 是异步生成器
|
|
446
|
-
for (let i = 1; i <= input.n; i++) {
|
|
447
|
-
yield `数到了 ${i}` // 每次 yield 都会立刻发给上层的 onOutput 回调
|
|
448
|
-
await new Promise(r => setTimeout(r, 100))
|
|
449
|
-
}
|
|
450
|
-
},
|
|
451
|
-
}
|
|
452
|
-
```
|
|
453
|
-
|
|
454
|
-
文件工具和内存工具都支持 `async *execute`(`Agent.tool.adopt` 接纳的内存工具也一样)。接收流式输出:
|
|
455
|
-
|
|
456
|
-
```js
|
|
457
|
-
const agent = Agent.create({
|
|
458
|
-
// ...
|
|
459
|
-
callbacks: {
|
|
460
|
-
onToolOutput: output => {
|
|
461
|
-
console.log('实时输出:', output.data) // 每次 yield 触发一次
|
|
462
|
-
},
|
|
463
|
-
},
|
|
464
|
-
})
|
|
465
|
-
```
|
|
466
|
-
|
|
467
|
-
### 调用子进程的工具
|
|
468
|
-
|
|
469
|
-
工具在独立子进程里运行,`Bun.spawn` 的 stdout/stderr 会自动转发给 `onToolOutput`,不需要额外处理:
|
|
470
|
-
|
|
471
|
-
```js
|
|
472
|
-
// tools/run-script.js
|
|
473
|
-
export default {
|
|
474
|
-
name: 'run_script',
|
|
475
|
-
description: '运行一个 shell 脚本',
|
|
476
|
-
inputSchema: {
|
|
477
|
-
type: 'object',
|
|
478
|
-
properties: { command: { type: 'string' } },
|
|
479
|
-
required: ['command'],
|
|
480
|
-
},
|
|
481
|
-
async execute(input) {
|
|
482
|
-
const proc = Bun.spawn(['bash', '-c', input.command], {
|
|
483
|
-
stdout: 'pipe',
|
|
484
|
-
stderr: 'pipe',
|
|
485
|
-
})
|
|
486
|
-
await proc.exited
|
|
487
|
-
return { exitCode: proc.exitCode } // stdout/stderr 已经自动转发了
|
|
488
|
-
},
|
|
489
|
-
}
|
|
490
|
-
```
|
|
491
|
-
|
|
492
|
-
### 一个文件导出多个工具
|
|
493
|
-
|
|
494
|
-
```js
|
|
495
|
-
// tools/math.js
|
|
496
|
-
const add = {
|
|
497
|
-
name: 'add',
|
|
498
|
-
description: '加法',
|
|
499
|
-
inputSchema: { type: 'object', properties: { a: { type: 'number' }, b: { type: 'number' } }, required: ['a', 'b'] },
|
|
500
|
-
async execute(input) { return input.a + input.b },
|
|
501
|
-
}
|
|
502
|
-
|
|
503
|
-
const multiply = {
|
|
504
|
-
name: 'multiply',
|
|
505
|
-
description: '乘法',
|
|
506
|
-
inputSchema: { type: 'object', properties: { a: { type: 'number' }, b: { type: 'number' } }, required: ['a', 'b'] },
|
|
507
|
-
async execute(input) { return input.a * input.b },
|
|
508
|
-
}
|
|
509
|
-
|
|
510
|
-
export default [add, multiply] // 导出数组
|
|
511
|
-
```
|
|
512
|
-
|
|
513
|
-
工具是按**名字**找到的,不是按它在数组里排第几。所以往文件里插入新工具、调换顺序都不会让模型调错工具。
|
|
514
|
-
|
|
515
|
-
### 工具目录里可以放共享代码
|
|
516
|
-
|
|
517
|
-
扫描时只把"形状对得上"(有 `name`、有 `execute`)的东西注册成工具,其余文件直接跳过。
|
|
518
|
-
所以下面这些都可以和工具放在同一个目录里,不会影响扫描:
|
|
519
|
-
|
|
520
|
-
```
|
|
521
|
-
tools/
|
|
522
|
-
├── read.js ← 工具
|
|
523
|
-
├── write.js ← 工具
|
|
524
|
-
├── shared.js ← 共享辅助函数,没有默认导出,自动跳过
|
|
525
|
-
└── read.test.js ← 测试文件,自动跳过
|
|
526
|
-
```
|
|
527
|
-
|
|
528
|
-
跳过的前提是这些文件**能被加载**。目录里任何一个 `.js` 有语法错误、或者 import 了装不上的依赖,
|
|
529
|
-
`scan` 会当场抛出来——这是有意的:工具目录是你自己的代码,坏了就该立刻知道,
|
|
530
|
-
静默跳过只会变成"某个工具莫名其妙不见了"。
|
|
531
|
-
|
|
532
|
-
### 主动停止 Agent 的工具
|
|
533
|
-
|
|
534
|
-
如果某个工具代表"任务完成",可以让它返回 `stop: true`,Agent 循环会立刻停止:
|
|
535
|
-
|
|
536
|
-
```js
|
|
537
|
-
// tools/finish.js
|
|
538
|
-
export default {
|
|
539
|
-
name: 'finish',
|
|
540
|
-
description: '任务完成时调用这个工具',
|
|
541
|
-
inputSchema: {
|
|
542
|
-
type: 'object',
|
|
543
|
-
properties: { summary: { type: 'string', description: '完成情况总结' } },
|
|
544
|
-
required: ['summary'],
|
|
545
|
-
},
|
|
546
|
-
async execute(input) {
|
|
547
|
-
return {
|
|
548
|
-
stop: true, // 告诉 Loop 停止循环
|
|
549
|
-
output: { type: 'text', value: input.summary },
|
|
550
|
-
}
|
|
551
|
-
},
|
|
552
|
-
}
|
|
553
|
-
```
|
|
554
|
-
|
|
555
|
-
### 返回图片的工具
|
|
158
|
+
---
|
|
556
159
|
|
|
557
|
-
|
|
160
|
+
## 接 MCP
|
|
558
161
|
|
|
559
|
-
```
|
|
560
|
-
//
|
|
561
|
-
|
|
562
|
-
name: '
|
|
563
|
-
|
|
564
|
-
inputSchema: { type: 'object', properties: {} },
|
|
565
|
-
async execute() {
|
|
566
|
-
const png = await grabScreen() // 你自己的截图实现,拿到 base64
|
|
567
|
-
return {
|
|
568
|
-
output: {
|
|
569
|
-
type: 'content', // 多模态输出块
|
|
570
|
-
value: [
|
|
571
|
-
{ type: 'text', text: '当前屏幕:' },
|
|
572
|
-
{ type: 'file', mediaType: 'image/png', data: { type: 'data', data: png } },
|
|
573
|
-
],
|
|
574
|
-
},
|
|
575
|
-
}
|
|
576
|
-
},
|
|
577
|
-
}
|
|
162
|
+
```ts
|
|
163
|
+
agent.MCP.list = [ // 也可以 Agent.create({ MCP: [...] }),或者原地 push / splice
|
|
164
|
+
{ name: 'github', url: 'https://example.com/mcp', headers: { Authorization: 'Bearer ...' } },
|
|
165
|
+
{ name: 'legacy', url: 'https://old.example.com/sse', transport: 'sse' },
|
|
166
|
+
]
|
|
578
167
|
```
|
|
579
168
|
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
`
|
|
169
|
+
核心负责连接(默认 Streamable HTTP,老服务器用 `sse`),工具名统一加 `${name}_` 前缀。
|
|
170
|
+
**连接完全异步,从不阻塞**:请求、`send`、`stop()` 都不会等任何 MCP 连接。连接尽早开始(`Agent.create` 时、`MCP.open` 时、
|
|
171
|
+
每轮开头发现 `list` 里有新元素时),在后台连上的那一刻起,下一次构建请求就带上它的工具——一次 `send` 中途连上的,下一轮请求就能用。
|
|
172
|
+
还没连上的这一轮就是没有它的工具。连接按配置缓存,配置变了自动重建,从数组里删掉的连接会被关闭。
|
|
173
|
+
连不上(含握手超过 15 秒)就是没有它的工具,对话照常进行:**不发任何警告**(不占用 `send` 的 `onWarning`),**也不自动重连**。
|
|
174
|
+
要用它的是用户:`await agent.MCP.open(name)` 会重新连接并等这一条的结果,成功与否和失败原因直接作为返回值给你看;
|
|
175
|
+
想重试就再 `open` 一次。只有 `open` 的调用方在等,请求和 `send` 照样不等。
|
|
583
176
|
|
|
584
|
-
|
|
177
|
+
**临时关闭某一条:** 元素上的 `enabled` 每轮现读——`false` 断开连接、下一轮起它的工具消失;改回 `true`(或删掉这个字段)下一轮开头重新开连。
|
|
178
|
+
也可以用方法,效果相同:
|
|
585
179
|
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
// ...
|
|
591
|
-
callbacks: {
|
|
592
|
-
onPermission: async ({ toolName, input: args }) => {
|
|
593
|
-
// 只有 delete_file 工具需要确认
|
|
594
|
-
if (toolName === 'delete_file') {
|
|
595
|
-
console.log(`即将删除文件: ${args.path}`)
|
|
596
|
-
// 实际项目里这里可以弹窗或读取用户输入
|
|
597
|
-
return true // 返回 true 允许,false 拒绝
|
|
598
|
-
}
|
|
599
|
-
return true // 其他工具直接放行
|
|
600
|
-
},
|
|
601
|
-
},
|
|
602
|
-
})
|
|
180
|
+
```ts
|
|
181
|
+
await agent.MCP.close('github') // → { name: 'github', found: true, enabled: false, closed: true },立即断开
|
|
182
|
+
await agent.MCP.open('github') // → { name: 'github', found: true, enabled: true, connected: true }
|
|
183
|
+
// 连不上 → { ..., connected: false, error: '原因' };没有这个名字 → { found: false, enabled: false, connected: false }
|
|
603
184
|
```
|
|
604
185
|
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
- **等待期间 `send` 仍处于"正在运行"**:想允许用户在审批时发新消息顶掉任务,按 `send` 的既有语义处理(新 send 会先 stop 旧的)。
|
|
609
|
-
- **服务重启会丢掉挂起的审批**:`Map` 在内存里。重启后要么给会话补发一条审批请求(凭 history 里的 assistant 工具调用就能还原 `toolCallId`),要么在启动时把该会话标记为"已中断"。
|
|
610
|
-
- **务必给每条路径都 `return`**:非布尔返回值一律按拒绝处理(0.26 起),漏 return 会让这次调用被静默拒绝。
|
|
611
|
-
- **拒绝/取消/无效调用现在也会触发 `onToolResult`**(0.27 起),`output.type` 分别是 `execution-denied` / `error-text`——界面统一从这一个回调翻状态即可,不用再监听 `onPermission` 补通知。
|
|
186
|
+
`MCP.open` 把同名元素原地换成 `enabled: true` 的新对象并立刻开连:已连上的立刻返回,正在连的等它出结果,上次失败的重新连。
|
|
187
|
+
`MCP.close` 把 `MCP.list` 里同名元素原地换成 `enabled: false` 的新对象并立即断开连接(`closed` 表示是否真的断开了一条已连上的连接,连接中 / 连接失败的记录只是被移出,
|
|
188
|
+
`found: false` 表示没有这个名字、什么也没改);正在执行的该服务器工具调用会以错误结果结束。
|
|
612
189
|
|
|
613
190
|
---
|
|
614
191
|
|
|
615
192
|
## API 参考
|
|
616
193
|
|
|
617
|
-
### `Agent`
|
|
618
|
-
|
|
619
|
-
从包里导入的唯一入口:
|
|
620
|
-
|
|
621
|
-
```js
|
|
622
|
-
import Agent from '@kernel4632/agent-core'
|
|
623
|
-
```
|
|
624
|
-
|
|
625
|
-
#### `Agent.create(options?)`
|
|
194
|
+
### `Agent.create(options)`
|
|
626
195
|
|
|
627
|
-
|
|
196
|
+
配置平铺在顶层,另带 `id`、`history`、`tools`、`MCP`(MCP 连接数组,成为 `agent.MCP.list`)、`contextRatio`、`ratios`。同步返回实例;唯一的 I/O 是让 `MCP` 里启用的连接在后台开始(不等)。
|
|
628
197
|
|
|
629
|
-
|
|
|
198
|
+
| 字段 | 默认 | 说明 |
|
|
630
199
|
|------|------|------|
|
|
631
|
-
| `
|
|
632
|
-
| `
|
|
633
|
-
| `
|
|
634
|
-
| `
|
|
635
|
-
| `
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
|
640
|
-
|
|
641
|
-
| `
|
|
642
|
-
| `
|
|
643
|
-
| `
|
|
644
|
-
| `
|
|
645
|
-
| `
|
|
646
|
-
| `
|
|
647
|
-
| `
|
|
648
|
-
| `
|
|
649
|
-
| `
|
|
650
|
-
| `
|
|
651
|
-
| `
|
|
652
|
-
| `
|
|
653
|
-
| `
|
|
654
|
-
| `
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
失败的重试由底层统一处理,默认行为照抄 Roo Code:**除"取消"和"上下文超长"外,任何错误都会重试**(401、400、格式错误都算),次数不限,也不设总时长上限;退避按 `retryBaseDelay × 2` 增长,单次最长到 `retryMaxDelay` 封顶。上下文超长不走重试,而是先压缩上下文再重发这笔请求,最多 3 次。取消(`agent.stop()` 或传 `signal`)永远不重试。
|
|
673
|
-
|
|
674
|
-
想收口或过滤,用这几个配置:
|
|
675
|
-
|
|
676
|
-
```js
|
|
677
|
-
const agent = Agent.create({
|
|
678
|
-
config: {
|
|
679
|
-
retryBaseDelay: 5000, // 第一次等待 5s,之后 10s、20s…(默认)
|
|
680
|
-
retryMaxDelay: 600000, // 单次等待最多 10 分钟(默认)
|
|
681
|
-
retryMaxElapsed: 120000, // 一直失败最多再试 2 分钟,到点把错误交给上层(默认不限)
|
|
682
|
-
retryMaxTries: 5, // 最多再重试 5 次(默认不限);0=不重试;和上面那条谁先到谁停
|
|
683
|
-
// 只对"不想重试的错误"下手,命中即不重试:
|
|
684
|
-
retry: {
|
|
685
|
-
skipCodes: [400, 401], // 按状态码
|
|
686
|
-
skipKinds: ['auth'], // 按 error.kind:aborted/auth/limit/timeout/server/network/request/unknown
|
|
687
|
-
skipText: /invalid api key/i, // 按报错文字(字符串或正则)
|
|
688
|
-
shouldRetry: error => error.statusCode !== 422, // 自定义判断,返回 false=不重试
|
|
689
|
-
},
|
|
690
|
-
// retry 也可以直接传一个函数:(error) => boolean,返回 false=不重试
|
|
691
|
-
},
|
|
692
|
-
})
|
|
693
|
-
```
|
|
694
|
-
|
|
695
|
-
`retry` 属于 **整份替换**(和 `provider` 一样,本次传了就用本次的整份,不与上次合并)。`onRetry` 会收到 `{ attempt, maxTries, error, delay }`,宿主可以直接显示"第几 / 最多几次"。
|
|
696
|
-
|
|
697
|
-
陌生中转站建议先使用默认能力。遇到只支持文字、但接口声称兼容 OpenAI 的模型,可以按能力关闭:
|
|
698
|
-
|
|
699
|
-
```js
|
|
700
|
-
const agent = Agent.create({
|
|
701
|
-
config: {
|
|
702
|
-
baseURL: 'https://api.example.com/v1', model: 'model-name',
|
|
703
|
-
capabilities: {
|
|
704
|
-
image: false, audio: false, video: false, file: false,
|
|
705
|
-
tools: false, structuredOutput: false, toolChoice: false,
|
|
706
|
-
reasoning: false,
|
|
707
|
-
},
|
|
708
|
-
mediaFallback: 'strip',
|
|
709
|
-
},
|
|
710
|
-
})
|
|
711
|
-
```
|
|
712
|
-
|
|
713
|
-
`image`、`audio`、`video` 和 `file` 控制内容块;`tools` 控制是否发送工具描述;`structuredOutput` 控制是否发送 `response_format`;`toolChoice:false` 让请求省略 `tool_choice`(只对字符串模型 + `chat`/`responses`/`anthropic` 完整生效;`gemini` 按自身默认、不强制;传模型实例时会报错,因为它需要改写请求体);`reasoning:true` 才会把历史里的思考块发给模型;`usage:false` 关掉流式请求里的 `stream_options.include_usage`(个别不认这个字段的中转站会 400,关掉即可,代价是 token 估算拿不到真实数据、只能靠粗估)。旧式 `image`、`audio`、`video` 内容块会在真正请求模型时转换成 AI SDK 当前使用的 `file`,历史数组仍保留原始形状。
|
|
714
|
-
|
|
715
|
-
`provider` 直接放 AI SDK 的生成参数,例如:
|
|
716
|
-
|
|
717
|
-
```js
|
|
718
|
-
const agent = Agent.create({
|
|
719
|
-
config: {
|
|
720
|
-
baseURL: 'https://api.example.com/v1', apiKey: 'sk-xxx', model: 'model-name',
|
|
721
|
-
provider: {
|
|
722
|
-
temperature: 0.3, topP: 0.9, maxOutputTokens: 4096,
|
|
723
|
-
toolChoice: 'auto', // 默认 auto;不传时由底层使用 auto
|
|
724
|
-
providerOptions: { openai: {} }, // 厂商专用设置直接交给 AI SDK
|
|
725
|
-
headers: { 'X-App': 'example' }, // 额外请求头
|
|
726
|
-
body: { custom_field: true }, // 额外请求体字段
|
|
727
|
-
},
|
|
728
|
-
},
|
|
729
|
-
})
|
|
730
|
-
```
|
|
731
|
-
|
|
732
|
-
在 `agent.send({ input, config: { ... } })` 里传入的配置会**写回 Agent**、之后的每一笔模型请求继续生效(包括正在跑的这一轮的下一笔和它的每次重试,见下方「每笔请求现拼」)。合并规则分三种:`provider` 和 `retry` **整份替换**(传了就只用新的,未写的字段不再保留);`capabilities`、`compact` 和 `contextKeep` **按字段浅合并**(只传其中一项不丢另外的);其余字段直接覆盖。`maxContextTokens` 是上下文预算,`maxTokens` 是单次生成的最大输出(会映射成请求体的 `maxOutputTokens`),两者不是一回事。
|
|
733
|
-
|
|
734
|
-
`cache` 默认开启。四种协议各按自己的方式让服务端复用固定的开头(system、工具描述、历史),命中后那部分不再重新计算,长会话能明显变快、变便宜:
|
|
735
|
-
|
|
736
|
-
| 协议 | 发的字段 |
|
|
737
|
-
|------|----------|
|
|
738
|
-
| `chat` / `responses` | `prompt_cache_key`,服务端按这个键把同一台 Agent 的连续请求路由到同一处缓存 |
|
|
739
|
-
| `anthropic` | 在 system 和最后一条消息上打 `cache_control` 断点;Anthropic 不会自动缓存,不打就是 0% |
|
|
740
|
-
| `gemini` | 隐式缓存由服务端自己决定,请求里没有可发的字段 |
|
|
741
|
-
|
|
742
|
-
实测(同一会话的多步工具循环,默认配置):`chat` 从第二步起命中约 99%,整个任务约 80%;`anthropic` 从第三步起每步命中整段开头,整个任务约 60%。键默认由 `baseURL + model + system` 推出,同一台 Agent 的连续请求自然落在同一个键上。也可以传对象自定义:
|
|
743
|
-
|
|
744
|
-
```js
|
|
745
|
-
cache: {
|
|
746
|
-
key: 'project:conversation-1',
|
|
747
|
-
retention: '1h',
|
|
748
|
-
body: { cache_namespace: 'agent' },
|
|
749
|
-
}
|
|
750
|
-
```
|
|
751
|
-
|
|
752
|
-
个别中转站不认这组字段、直接返回 400,那时设 `cache: false` 关掉,或把供应商自己的字段放进 `provider.body`。
|
|
753
|
-
|
|
754
|
-
#### 让没有原生工具的模型也能用工具
|
|
755
|
-
|
|
756
|
-
有的中转站模型只会对话:请求里一带 `tools` 字段就报错。也有的模型接口支持工具,模型自己却不会用,把调用当成一段文字写了出来。这两种情况各有一个兼容开关,**默认都关着**:
|
|
757
|
-
|
|
758
|
-
| `toolMode` | 行为 | 会不会改 system |
|
|
759
|
-
|------------|------|----------------|
|
|
760
|
-
| `'native'`(默认) | 只用原生工具字段,文字里的调用一律当成普通回答 | 不会,你写的 system 原样发出 |
|
|
761
|
-
| `'text'` | 模拟工具:不发 `tools` 字段,把工具说明写进 system,从模型的文字里读回调用 | 会,追加一段工具说明 |
|
|
762
|
-
| `'auto'` | 兼容降级:先用原生工具;接口拒收工具字段时,改用文字协议重发,并记住这个模型;模型没走原生调用、却在文字里写了调用时,也读出来执行 | 只在被拒收、改用文字协议之后才会 |
|
|
763
|
-
|
|
764
|
-
这个包的原则是**默认零注入**:不打开开关,发给模型的 system 就是你写的那段,一个字都不多。接特殊 API 时缺什么就打开什么。
|
|
765
|
-
|
|
766
|
-
文字协议的格式(参考 Roo Code / Cline 的文本工具调用):
|
|
767
|
-
|
|
768
|
-
```
|
|
769
|
-
<tool_call>
|
|
770
|
-
{"name": "add", "arguments": {"a": 1, "b": 2}}
|
|
771
|
-
</tool_call>
|
|
772
|
-
```
|
|
773
|
-
|
|
774
|
-
工具结果用 `<tool_result name="add">…</tool_result>` 作为一条 user 消息送回模型。读取时尽量宽容:一次回复里写多个调用、`arguments` 写成字符串、外面套一层 `{"type":"function","function":{…}}`、参数平铺在同一层、带 Markdown 代码围栏、多一个尾逗号、最后一块没闭合,都能读出来。Roo Code 风格的 XML 写法(`<read_file><path>a.js</path></read_file>`)也认,会按工具的 schema 把 `"7"` 还原成数字 `7`。JSON 坏到读不出来时,会生成一条无效调用告诉模型重写,不会悄悄当成普通回答。模型自己编了 `<tool_result>` 时,从那里往后的内容全部丢掉,免得假结果混进历史。
|
|
775
|
-
|
|
776
|
-
**历史始终是标准形状。** 文字协议只在发请求和读响应的时候转换,`agent.history` 里存的永远是标准的 `tool-call` 块和 `tool` 消息。同一台 Agent 中途从纯对话模型换成原生工具模型(或反过来),历史直接接着用。
|
|
777
|
-
|
|
778
|
-
流式输出时,文字协议的 `<tool_call>` 原文也会出现在 `onLLMEvent` 的 `text-delta` 里,前端想隐藏可以按这个标签过滤。`result.text` 和历史里的文字已经去掉了调用部分。
|
|
779
|
-
|
|
780
|
-
需要包内没有预设的 Provider 或模型中间件时,直接传 AI SDK 模型实例;实例由调用方创建,`baseURL`、`apiKey`、`protocol` 就不必重复写。下面的进阶用法需要调用方安装对应的 Provider 包:
|
|
781
|
-
|
|
782
|
-
```js
|
|
783
|
-
import { createOpenAICompatible } from '@ai-sdk/openai-compatible'
|
|
784
|
-
import Agent from '@kernel4632/agent-core'
|
|
785
|
-
|
|
786
|
-
const model = createOpenAICompatible({
|
|
787
|
-
name: 'custom', baseURL: 'https://api.example.com/v1', apiKey: 'sk-xxx',
|
|
788
|
-
}).chatModel('model-name')
|
|
789
|
-
const agent = Agent.create({ config: { model, provider: { temperature: 0.3 } } })
|
|
790
|
-
const answer = await agent.send('你好')
|
|
791
|
-
console.log(answer.text)
|
|
792
|
-
```
|
|
793
|
-
|
|
794
|
-
模型实例的额外请求头仍可写在 `provider.headers`;`provider.body`、自定义的 `cache` 对象、以及 `capabilities.toolChoice: false`(它要改写请求体才能生效)都需要本包创建连接,不能用于已创建的模型实例,设置时会明确报错。默认的 `cache: true` 对模型实例会安静跳过——实例的缓存设置由创建它的人负责。
|
|
795
|
-
|
|
796
|
-
> `provider.toolChoice` 保持 `auto` 时,模型才能在任务做完后正常收尾,`{ reason: 'no-tool' }` 这个结束方式也才有意义。
|
|
797
|
-
> 改成 `required` 会强制模型每轮都调工具,而且部分服务(实测 gpt-oss-120b)在模型不想调工具时会直接返回 `tool_use_failed`。
|
|
798
|
-
|
|
799
|
-
**`callbacks` 回调:**
|
|
800
|
-
|
|
801
|
-
| 回调 | 触发时机 | 参数 |
|
|
802
|
-
|------|----------|------|
|
|
803
|
-
| `onStart` | 循环开始 | 无 |
|
|
804
|
-
| `onLLMStart` | 每次请求模型前 | `{ messages, tools }` |
|
|
805
|
-
| `onLLMFinish` | 模型请求完成 | LLM 返回的完整结果 |
|
|
806
|
-
| `onLLMEvent` | 流式事件(每个 token) | AI SDK 原生事件 |
|
|
807
|
-
| `onPermission` | 工具执行前 | `{ toolName, input, sessionId, toolCallId, signal }` → 返回 `true/false` |
|
|
808
|
-
| `onToolCall` | 工具即将执行 | `{ toolCallId, toolName, input }` |
|
|
809
|
-
| `onToolOutput` | 工具有流式输出 | `{ toolName, stream, data, toolCallId, input? }`;`data` 是工具 yield / 打印出来的原值,类型不定 |
|
|
810
|
-
| `onToolResult` | 工具执行完成(拒绝/取消/无效调用也触发) | `{ toolName, toolCallId, output, ... }` |
|
|
811
|
-
| `onStep` | 一轮模型和工具都完成后 | `{ step, result, toolCalls, toolResults }`;`toolResults` 是完整结果对象(`call` + `output`),和 `onToolResult` 同一种形状 |
|
|
812
|
-
| `onRetry` | 请求失败重试 | `{ attempt, maxTries, error, delay }`(主请求和压缩请求共用) |
|
|
813
|
-
| `onInject` | 每轮请求前(压缩之后) | `{ tokens, budget, compactThreshold }` → 返回字符串就临时附在本次请求末尾;返回其它值不注入 |
|
|
814
|
-
| `onCompact` | 上下文压缩 | `compact-start`(`messages` + `reason` / `token` / `budget` / `compactThreshold` / `ratio` / `chars` / `media` / `calibrated`)/ AI SDK 事件(统一带 `request: 'compact'` 标记)/ `compact-finish`(带 `usage`,即压缩这一笔的用量) |
|
|
815
|
-
|
|
816
|
-
除了 `onPermission` 和 `onInject`,所有回调都只是通知:回调自己抛错会被忽略,任务照常进行,工具结果也不会被改写。`onPermission` 的返回值决定放不放行,所以它抛错时这次 `send` 会失败,交给你的 `.catch()`。注意它按"非 `true` 即拒绝"处理:**每个分支都要显式 `return true`**,忘了返回会让那次工具被拒。`onInject` 抛错只当这一轮不注入,不打断任务。
|
|
817
|
-
|
|
818
|
-
**为什么压?** `compact-start` 把判断依据一起带出来:
|
|
819
|
-
|
|
820
|
-
| 字段 | 含义 |
|
|
200
|
+
| `model` | 必填 | 模型名(配 `baseURL` / `apiKey`),或 AI SDK 模型实例 |
|
|
201
|
+
| `baseURL` / `apiKey` | — | 服务地址与密钥 |
|
|
202
|
+
| `protocol` | `'chat'` | `'chat'` / `'responses'` / `'anthropic'` / `'gemini'` |
|
|
203
|
+
| `system` | — | 系统提示词 |
|
|
204
|
+
| `stream` | `true` | 是否流式 |
|
|
205
|
+
| `cache` | 开启 | 提示词缓存:`true` / `false` / `{ key, retention, body }` |
|
|
206
|
+
| `textTools` | `false` | 用文字协议模拟工具调用(给不支持原生工具的模型) |
|
|
207
|
+
| `media` | 全部 `false` | `{ image, audio, video, file }` 逐项开关。没开的类型(用户消息和工具结果里的都算)发送时换成一句占位文字,history 原样保留,换成支持的模型后原件照常发出 |
|
|
208
|
+
| `reasoning` | `'strip'` | 历史里的思考块发不发回模型:`'strip'` 发送前摘掉(与旧版默认一致),`'send'` 原样发回(供应商要求回传时用)。history 里始终保留。`responses` 协议下 `'send'` 会设 `store: false` 并请求 `reasoning.encrypted_content`,思考发全文而不是 `item_reference`(`providerOptions.openai` 里显式写的优先) |
|
|
209
|
+
| `provider` | — | 原样透传给 AI SDK 的生成参数 |
|
|
210
|
+
| `maxTokens` | — | 单次最大输出 token |
|
|
211
|
+
| `maxToolOutput` | 不截断 | 单个工具结果最多保留多少字符(保留头 70%、尾 30%) |
|
|
212
|
+
| `includeUsage` | `true` | `chat` 协议流式时请求 usage(token 校准靠它);不认 `stream_options` 的中转站设 `false` |
|
|
213
|
+
| `maxContextTokens` | `128000` | 上下文预算;`Infinity` 关闭自动压缩 |
|
|
214
|
+
| `compactThreshold` | `0.8` | 估算达到预算的这个比例就压缩 |
|
|
215
|
+
| `compact` | — | 压缩请求单独用的配置(比如更便宜的模型)。压缩不传 `maxTokens`(用模型自己的上限,总结长度靠提示词约束) |
|
|
216
|
+
| `context` | `{ head: 0, beforeSummary: 10, budget: 0.3 }` | 压缩后的保留规则,见下文 |
|
|
217
|
+
| `output` | — | 结构化输出格式(AI SDK `Output`) |
|
|
218
|
+
| `noToolRounds` | `3` | 连续几轮不调工具就结束 |
|
|
219
|
+
| `noToolPrompt` | 内置 | 不调工具时临时挂上的提醒 |
|
|
220
|
+
| `retryMaxTries` / `retryMaxElapsed` | 不限 | 重试次数 / 总时长上限 |
|
|
221
|
+
| `retryBaseDelay` / `retryMaxDelay` | `5000` / `600000` | 指数退避基数 / 单次上限(毫秒) |
|
|
222
|
+
| `requestTimeout` | 不限 | 单次请求超时(毫秒) |
|
|
223
|
+
| `retry` | — | 不重试规则:函数(返回 `false` 不重试),或 `{ shouldRetry, skipCodes, skipText, skipKinds }` |
|
|
224
|
+
|
|
225
|
+
默认值在读取时才套用,所以整份替换 `agent.config` 不会丢默认值。被取消和上下文溢出(`kind: 'overflow'`)永远不重试;
|
|
226
|
+
溢出时 loop 会先压缩再重发,最多 3 次。`provider.toolChoice` 只在这一笔真的带原生工具时发送(文字工具模式、压缩请求不带)。
|
|
227
|
+
|
|
228
|
+
### `agent.send(input?, callbacks?)`
|
|
229
|
+
|
|
230
|
+
`input` 是一句话或内容块数组;省略就是"从当前历史继续"。返回 `{ reason, text, steps, usage, output? }`(`steps` 是这次问了模型几轮),
|
|
231
|
+
`reason` 为 `'finished'`(模型正常收尾 / 没有工具)、`'no-tool'`(连续不调工具)或 `'tool-stop'`(工具要求停止)。
|
|
232
|
+
|
|
233
|
+
同一实例一次只跑一件事:新的 `send` / `compact` 会先停掉上一次并等它收尾。模型错误会抛出,带 `error.kind`
|
|
234
|
+
(`aborted` / `auth` / `limit` / `timeout` / `server` / `network` / `request` / `overflow` / `unknown`),
|
|
235
|
+
同时(连同每次重试前的错误)以 `role: 'error'` 记进 history,见上文 ④。重试默认不限次数。
|
|
236
|
+
|
|
237
|
+
回调按次传入,全部可选,抛错或返回被拒绝的 Promise 都不影响循环;`onToolCall` 和 `onStep` 会被等待(返回 Promise 时等它完成再继续):
|
|
238
|
+
|
|
239
|
+
| 回调 | 时机 |
|
|
821
240
|
|------|------|
|
|
822
|
-
| `
|
|
823
|
-
| `
|
|
824
|
-
| `budget` | `
|
|
825
|
-
| `
|
|
826
|
-
| `
|
|
827
|
-
| `
|
|
828
|
-
| `
|
|
829
|
-
| `
|
|
830
|
-
|
|
831
|
-
判断"是不是估算误判"就看 `token` 和 `budget × compactThreshold` 的关系,以及 `ratio` 是不是明显偏离你的内容(中文 ≈ 1,英文 ≈ 0.25)。注意 `token` 是**这一轮开始时**的估算:上一次真实请求之后又写进来的工具结果也在里面,所以它会比"上一次请求的 input"大。
|
|
832
|
-
|
|
833
|
-
`calibrated: false` 有两个常见原因:一是进程刚起、还没成功跑完过一笔请求;二是上游没在响应里回 `usage`(流式请求需要 `stream_options.include_usage`,个别中转站不支持,可以用 `capabilities.usage: false` 关掉这个字段,但那样估算就只能一直用默认比例)。**校准是每个进程从零开始的**:重启后恢复一份很大的 history 时,第一个 `send` 用的仍是默认比例,可能因此多压一次——把 `token / chars / ratio` 记下来就能确认。想据此折算真实比例:`真实 token ÷ chars`。
|
|
834
|
-
|
|
835
|
-
#### 冷启动的估算倍率(`contextRatio`)
|
|
836
|
-
|
|
837
|
-
上面那个"重启后第一个 send 多压一次"可以直接消掉:宿主把上次学到的倍率存起来,恢复会话时传回去,第一次估算就用它。
|
|
838
|
-
|
|
839
|
-
```js
|
|
840
|
-
// 进程 A:跑过之后把倍率存起来(宿主自己存,core 不碰磁盘)
|
|
841
|
-
const { ratio, source } = agent.getContextRatio()
|
|
842
|
-
if (source === 'usage') await save(`${provider}:${model}`, ratio)
|
|
843
|
-
|
|
844
|
-
// 进程 B:恢复会话时先传回去,第一个 send 就用它估,而不是默认 0.6
|
|
845
|
-
const agent = Agent.create({
|
|
846
|
-
history,
|
|
847
|
-
config: { contextRatio: await load(`${provider}:${model}`) },
|
|
848
|
-
})
|
|
849
|
-
|
|
850
|
-
// 也可以运行中改:立刻生效,之后真实 usage 到达仍会覆盖它
|
|
851
|
-
agent.setContextRatio(0.297)
|
|
852
|
-
```
|
|
853
|
-
|
|
854
|
-
- 优先级:**真实 usage 学到的 > `contextRatio`(宿主 seed)> 默认 0.6**。
|
|
855
|
-
- `getContextRatio()` 返回 `{ ratio, calibrated, source }`,`source` 是 `'usage'` / `'host'` / `'default'`。
|
|
856
|
-
- `onCompact` 的 `compact-start.ratioSource`、`onInject` 的参数里也能看到当前来源。
|
|
857
|
-
- 上游不返回 usage 时,宿主 seed 会一直有效(不会被打回默认值);`setContextRatio` 之后的第一笔真实 usage 仍会重新校准。
|
|
858
|
-
- 按 `provider + model` 存:换模型后比例本来就不一样,这台 Agent 的估算器也是按模型分开记的。
|
|
859
|
-
|
|
860
|
-
#### 宿主注入临时提示(`onInject`)
|
|
861
|
-
|
|
862
|
-
想在"下一次模型请求"里临时补一句话,用 `onInject`:每轮请求前调一次,返回的文字作为一条 `user` 消息附在请求末尾,**不写进 `history`**,请求发完就没了。`tokens` 是这一轮压缩之后的估算值。
|
|
863
|
-
|
|
864
|
-
典型用法是上下文余量提醒——快到压缩点了,让模型这一轮收口:
|
|
865
|
-
|
|
866
|
-
```js
|
|
867
|
-
let reminded = false // "只提醒一次"是业务策略,由宿主自己记
|
|
868
|
-
|
|
869
|
-
const agent = Agent.create({
|
|
870
|
-
config: { ...config, maxContextTokens: 128000, compactThreshold: 0.8 },
|
|
871
|
-
callbacks: {
|
|
872
|
-
onInject: ({ tokens, budget, compactThreshold }) => {
|
|
873
|
-
const threshold = budget * compactThreshold
|
|
874
|
-
if (reminded || tokens < threshold * 0.95) return undefined
|
|
875
|
-
reminded = true
|
|
876
|
-
return '上下文快满了,这一轮请收口:不要再开新任务,把已有结果整理成答复。'
|
|
877
|
-
},
|
|
878
|
-
},
|
|
879
|
-
})
|
|
880
|
-
```
|
|
881
|
-
|
|
882
|
-
- 压缩当轮:`onInject` 在压缩之后才调,拿到的 `tokens` 已经是压小的值,自然不会再提醒。
|
|
883
|
-
- 每轮都会问,去重由你决定(上面用 `reminded`);核心不替宿主记"提醒过没有"。
|
|
884
|
-
- 和核心自己的 `noToolPrompt` 同时存在时,两段文字会合在一条消息里。
|
|
241
|
+
| `onChunk(chunk)` | 流式片段:`text` / `reasoning` / `tool-call` / `tool-result` / `finish`;压缩期间见下方 |
|
|
242
|
+
| `onPermission(call)` | 工具执行前;严格返回 `true` 才放行,其余(含非布尔值,会警告一次)都拒绝,模型收到"被拒绝"结果。`call.path` 是来源文件;无效调用不会来问 |
|
|
243
|
+
| `onInject({ tokens, budget, compactThreshold, ratio, ratioSource })` | 每次请求前;返回的文字临时挂在这次请求上,不进 history。`ratioSource`:`'usage'` 学到的 / `'host'` 宿主给的 / `'default'` 默认值 |
|
|
244
|
+
| `onToolCall(call)` / `onToolResult(result)` | 工具开始 / 结束;`path` 用来映射回宿主的插件 |
|
|
245
|
+
| `onToolOutput({ toolCallId, stream, data })` | 工具子进程的 stdout / stderr |
|
|
246
|
+
| `onStep({ step, reply, results })` | 每轮结束(适合落盘 history) |
|
|
247
|
+
| `onCompact({ reason, summary, before, after, budget, compactThreshold, ratio, ratioSource, chars, media, usage })` | 压缩完成;`reason` 为 `'auto'`(估算到阈值)/ `'overflow'`(模型报超长)/ `'manual'`;其余是压缩前的估算诊断 |
|
|
248
|
+
| `onRetry({ attempt, maxTries, error, delay })` | 模型请求重试前(这次的错误已先记进 history) |
|
|
249
|
+
| `onWarning({ path?, message })` | 坏工具文件、工具重名、history 里有发不出去的消息(system / 未知 role / 没有 content)等 |
|
|
885
250
|
|
|
886
|
-
|
|
251
|
+
文字工具模式(`textTools`)下流式照常:调用块之外的正文边收边推,只有可能是调用块的那一段先扣住,确认不是调用再推出。
|
|
887
252
|
|
|
888
|
-
|
|
253
|
+
**压缩也是流式的。** 压缩开始时先来一条 `{ type: 'compact-start', reason: 'auto' | 'overflow' | 'manual', compact: true }`,
|
|
254
|
+
之后压缩模型的 `reasoning` / `text` / `finish` 片段都带 `compact: true`,宿主可以实时展示"正在压缩:模型在想什么、总结正文是什么",
|
|
255
|
+
又不会和正式回答混在一起。压缩结束后 `onCompact` 照常给出完整信息(含总结正文)。
|
|
256
|
+
压缩请求的流式跟随 `compact.stream ?? stream`(默认流式);设为非流式时只有 `compact-start`。
|
|
889
257
|
|
|
890
|
-
|
|
891
|
-
await agent.send('继续')
|
|
258
|
+
### `agent.stop()`
|
|
892
259
|
|
|
893
|
-
|
|
894
|
-
|
|
895
|
-
|
|
896
|
-
history: [], // 可选:整份替换历史(也写回 Agent)
|
|
897
|
-
tools: newTools, // 可选:整份替换工具集(也写回 Agent)
|
|
898
|
-
callbacks: { onLLMEvent: e => {} }, // 可选:合并回调(逐项写回 Agent,最后传的长期生效)
|
|
899
|
-
})
|
|
900
|
-
|
|
901
|
-
// 注意:这四项覆盖都写进 Agent 状态,本次 send 之后一直有效,不是"只作用这一次"。
|
|
902
|
-
// 想只影响一次,就在这次 send 里传对值,或之后再传一次恢复。
|
|
903
|
-
|
|
904
|
-
// result.text → 最后一轮模型生成的文字
|
|
905
|
-
// result.steps → 这次 send 一共请求了模型几轮
|
|
906
|
-
// result.usage → 整次 send 的用量合计:{ inputTokens, outputTokens, totalTokens, cacheReadTokens, cacheWriteTokens }
|
|
907
|
-
// 算钱、看缓存命中直接读这里;cacheReadTokens / inputTokens 就是缓存命中率
|
|
908
|
-
// 自动压缩那一笔的用量也计在合计里(0.27 起)——压缩也是真实的模型请求
|
|
909
|
-
// result.reason:
|
|
910
|
-
// 'finished' → 没注册工具,或结构化输出已校验成功:这就是最终回答
|
|
911
|
-
// 'no-tool' → 有工具,但连续 noToolRounds 轮(默认 3)没调用工具才结束
|
|
912
|
-
// 'tool-stop' → 某个工具返回了 stop: true
|
|
913
|
-
```
|
|
914
|
-
|
|
915
|
-
`send` 的出错方式只有一种:返回的 Promise 拒绝。空输入、非法配置、取消、模型报错全都从这里出来,所以只需要写 `.catch()`,不用另外包同步的 `try/catch`。取消造成的拒绝带 `error.kind === 'aborted'`;模型报错的 `error.kind` 见下方。
|
|
916
|
-
|
|
917
|
-
> 输入是在发请求**之前**就写进 `history` 的,所以一次 `send` 失败后,这条输入已经留在历史里(历史只增不删)。重试前记得先决定要不要把它去掉,否则会叠成连续两条同样的输入。
|
|
918
|
-
|
|
919
|
-
连续发送时,建议保存并处理旧任务的 Promise,避免出现未处理的中止错误:
|
|
920
|
-
|
|
921
|
-
```js
|
|
922
|
-
const oldTask = agent.send({ input: '执行旧任务' })
|
|
923
|
-
const newTask = agent.send({ input: '改执行新任务' }) // 自动停止旧任务
|
|
924
|
-
|
|
925
|
-
await oldTask.catch(() => {}) // 旧任务可能以 AbortError 结束
|
|
926
|
-
const result = await newTask
|
|
927
|
-
```
|
|
928
|
-
|
|
929
|
-
**发图片:** `input` 除了字符串,也可以是 AI SDK 风格的内容块数组。截图、用户在 IM 里发来的图都走这条路。
|
|
930
|
-
|
|
931
|
-
```js
|
|
932
|
-
await agent.send({
|
|
933
|
-
input: [
|
|
934
|
-
{ type: 'text', text: '这张截图里哪个按钮是提交?' },
|
|
935
|
-
{ type: 'image', image: 'data:image/png;base64,' + png }, // 也可以传 URL 或 Uint8Array
|
|
936
|
-
],
|
|
937
|
-
})
|
|
938
|
-
```
|
|
939
|
-
|
|
940
|
-
能不能看懂取决于模型本身。实测 `kimi-k2.6` 可以,`gpt-oss-120b` 没有视觉能力、会直接报 `content must be a string`——是大声失败,不是静默忽略。
|
|
260
|
+
立即停止:中断模型请求,杀掉本实例的工具子进程,给没结果的调用补上"已取消"。返回
|
|
261
|
+
`Promise<{ stopped: true, wasRunning: boolean, killed: number }>`,**只在子进程全部确认退出、循环已经退出之后才兑现**——
|
|
262
|
+
拿到返回值就说明已经停干净了。`wasRunning` 表示调用时是否有运行,`killed` 是被杀掉的子进程数。正在跑的 `send` 会以 `kind: 'aborted'` 拒绝。
|
|
941
263
|
|
|
942
|
-
|
|
264
|
+
### `agent.compact(callbacks?)`
|
|
943
265
|
|
|
944
|
-
|
|
266
|
+
强制压缩一次,返回总结文字(片段同样通过 `onChunk` 流式推送)。
|
|
945
267
|
|
|
946
|
-
|
|
947
|
-
|
|
948
|
-
```js
|
|
949
|
-
// 在 onStep / onLLMFinish 里改都行:当前这笔请求和它发起的工具已经跑完
|
|
950
|
-
agent.config.model = '新的模型'
|
|
951
|
-
agent.config.provider = { ...agent.config.provider, temperature: 0.2 }
|
|
952
|
-
agent.config.system = '新的系统提示'
|
|
953
|
-
agent.tools = Agent.tool.omit(agent.tools, ['shell']) // 运行中撤掉一个工具,下一笔请求就不带它
|
|
954
|
-
```
|
|
268
|
+
### `agent.MCP.close(name)` / `agent.MCP.open(name)`
|
|
955
269
|
|
|
956
|
-
|
|
957
|
-
- **每笔都会重新取的**:连接(`baseURL` / `apiKey` / `model` / `protocol`)、`provider` 里的生成参数(温度、思考强度等)、`capabilities` / `mediaFallback`、`cache`、`requestTimeout`、`maxTokens`、`maxContextTokens`、`system`、工具表、以及从 `history` 现推的 messages。token 估算也按新模型重新记。
|
|
958
|
-
- **每轮才取的**:压缩判定(`compactThreshold` / 压缩用的 `compact` 配置)、`noToolRounds` 计数、轮次上限、`onInject` 的"这一轮要不要插一句"。这些是有副作用的决策(压缩会真的发一次请求、往 `history` 追加总结),不能放进重试里;新模型装不下时走"上下文超长 → 压缩后重发"那条兜底。
|
|
959
|
-
- **工具表只读一遍,不重新扫描目录**:把 `agent.tools` 换成新的集合(`Agent.tool.from` / `pick` / `omit` 的返回值)就生效;目录里的文件不会在这次运行中被重新扫描——要重新扫描用新的 `send`(`send({ tools })` 会在开始时现扫)。模型看到的那张表和执行时用的 handler 取自同一份集合。
|
|
960
|
-
- **不随请求换的只有两样**:`history` 是这次运行的权威数据,循环始终往同一个数组追加;回调是运行期的接线,在 `send` 开始时定下。
|
|
961
|
-
- 按次传的 `send({ config })` 语义不变:写回 `agent.config`,这次运行从第一笔请求起就用它。
|
|
962
|
-
|
|
963
|
-
> 会话运行中改模型 / 思考强度 / system / 工具表,直接改 `agent.config` 和 `agent.tools` 就行:历史、流式输出和运行状态都不中断,正在重试的那笔请求也会立刻用上新配置。
|
|
964
|
-
|
|
965
|
-
#### `agent.stop()`
|
|
966
|
-
|
|
967
|
-
停止正在运行的 Agent。
|
|
968
|
-
|
|
969
|
-
```js
|
|
970
|
-
await agent.stop() // 等待完全停止后返回 { ok: true };Agent 空闲时返回 { ok: false }
|
|
971
|
-
```
|
|
972
|
-
|
|
973
|
-
#### `agent.resume(options?)`
|
|
974
|
-
|
|
975
|
-
不发新消息,用现有历史的末尾接着跑——典型场景是停止后继续被中断的回复。它不往 `history` 里写任何东西:模型看到的末尾就是中断前的最后一条(assistant 或 tool 消息),所以**不会**出现"续跑后历史里多出一条假的用户消息"。
|
|
976
|
-
|
|
977
|
-
```js
|
|
978
|
-
const answer = await agent.resume() // 从上次停下的地方继续,返回值和 send 相同
|
|
979
|
-
const answer = await agent.resume({ config: { model: '新模型' } }) // 也可以像 send 一样按次覆盖 config / callbacks
|
|
980
|
-
```
|
|
981
|
-
|
|
982
|
-
- 历史末尾必须是 `assistant` 或 `tool` 消息(有"没说完的话"可续),否则直接报错;想发新内容用 `send`。
|
|
983
|
-
- `resume` 不接受 `input`;传了会报错,防止把"继续"误写成新指令。
|
|
984
|
-
|
|
985
|
-
#### 流式与网页实时推送
|
|
986
|
-
|
|
987
|
-
`send` 内部默认就是流式(`config.stream` 默认 `true`),`await` 拿到的是和流式一样的结果。想实时拿到每一块,用 `onLLMEvent`:模型每吐一段就调用一次,事件是包内 AI SDK 的原生事件。
|
|
988
|
-
|
|
989
|
-
```js
|
|
990
|
-
await agent.send({
|
|
991
|
-
input: '帮我查一下',
|
|
992
|
-
callbacks: {
|
|
993
|
-
onLLMEvent: event => {
|
|
994
|
-
if (event.type === 'text-delta') show(event.text) // 模型新吐的一段文字
|
|
995
|
-
},
|
|
996
|
-
onToolOutput: output => show(output.data), // 工具产生的实时输出
|
|
997
|
-
},
|
|
998
|
-
})
|
|
999
|
-
```
|
|
1000
|
-
|
|
1001
|
-
网页要边生成边推给浏览器时,用同样的回调,把内容写进一个标准 `Response` 流:
|
|
1002
|
-
|
|
1003
|
-
```js
|
|
1004
|
-
// Bun.serve 的 fetch 里。开始请求,立刻把响应返回给浏览器,内容随后一块块写上。
|
|
1005
|
-
app.get('/chat', async request => {
|
|
1006
|
-
const encoder = new TextEncoder()
|
|
1007
|
-
const stream = new ReadableStream({
|
|
1008
|
-
async start(controller) {
|
|
1009
|
-
const send = data => controller.enqueue(encoder.encode(`data: ${JSON.stringify(data)}\n\n`))
|
|
1010
|
-
try {
|
|
1011
|
-
// send 里的 onLLMEvent 在流式过程中被反复调用,每段文字都及时写出去。
|
|
1012
|
-
const result = await agent.send({
|
|
1013
|
-
input: await request.text(),
|
|
1014
|
-
callbacks: {
|
|
1015
|
-
onLLMEvent: event => { if (event.type === 'text-delta') send({ text: event.text }) },
|
|
1016
|
-
onStep: () => send({ status: 'step-done' }),
|
|
1017
|
-
},
|
|
1018
|
-
})
|
|
1019
|
-
send({ done: true, reason: result.reason })
|
|
1020
|
-
} catch (error) {
|
|
1021
|
-
send({ error: error.message, kind: error.kind }) // 可传输的错误描述和分类。
|
|
1022
|
-
} finally { controller.close() }
|
|
1023
|
-
},
|
|
1024
|
-
})
|
|
1025
|
-
return new Response(stream, { headers: { 'Content-Type': 'text/event-stream; charset=utf-8', 'Cache-Control': 'no-cache' } })
|
|
1026
|
-
})
|
|
1027
|
-
```
|
|
1028
|
-
|
|
1029
|
-
要取消某次运行,给 `send` 传 `signal`(如 `request.signal`)或调用 `agent.stop()`,两者都能终止。
|
|
1030
|
-
|
|
1031
|
-
模型请求失败时抛出的错误带一个稳定的 `kind`:`aborted`(用户取消)、`auth`(密钥或权限,401/403)、`limit`(限流,429)、`timeout`(单笔超时或 408)、`server`(5xx)、`network`(没连上)、`request`(其余 4xx)、`unknown`(服务返回成功状态码,但回答格式对不上,常见于不完全兼容的中转站)。上层靠它决定该换模型、该等一下还是该直接报错,不用去认 AI SDK 的内部错误形状。`kind` 只补充信息;能不能重试由 Retry 的规则统一决定(见上方「重试规则」),默认除取消和上下文超长外都重试,调用方可用 `retry` 过滤。
|
|
1032
|
-
|
|
1033
|
-
#### `agent.compact(options?)`
|
|
1034
|
-
|
|
1035
|
-
手动压缩当前历史(会先停止正在进行的任务)。默认使用 `Agent.create` 中配置的 `onCompact`、`onRetry`;在本次调用中传入同名回调可以覆盖默认值。
|
|
1036
|
-
|
|
1037
|
-
```js
|
|
1038
|
-
const summary = await agent.compact({
|
|
1039
|
-
onCompact: event => console.log(event),
|
|
1040
|
-
})
|
|
1041
|
-
// summary 是压缩后的文本,同时会自动追加到 agent.history
|
|
1042
|
-
```
|
|
1043
|
-
|
|
1044
|
-
#### `agent.history`
|
|
1045
|
-
|
|
1046
|
-
Agent 当前的完整历史消息数组,可直接读写。
|
|
1047
|
-
|
|
1048
|
-
#### `agent.running`
|
|
1049
|
-
|
|
1050
|
-
`null` 表示空闲;运行中时是 `{ controller, task }` 对象。
|
|
1051
|
-
|
|
1052
|
-
---
|
|
1053
|
-
|
|
1054
|
-
### `Agent.tool`
|
|
1055
|
-
|
|
1056
|
-
#### `Agent.tool.from(...sources)`
|
|
1057
|
-
|
|
1058
|
-
一行拼装工具集合。每个参数可以是目录、内存工具对象、数组、record、已经装好的集合,或它们的 Promise;同名时后面的覆盖前面的。
|
|
1059
|
-
|
|
1060
|
-
```js
|
|
1061
|
-
const tools = await Agent.tool.from(
|
|
1062
|
-
'./tools', // 目录:文件工具跑在子进程里
|
|
1063
|
-
mcpClient.tools(), // 内存工具:MCP / AI SDK 给的工具对象,主进程直接调
|
|
1064
|
-
{ skill: skillTool }, // record(一个对象,键是工具名):自定义函数;也可以传数组 [{ name, ... }, ...]
|
|
1065
|
-
)
|
|
1066
|
-
const agent = Agent.create({ config, tools })
|
|
1067
|
-
```
|
|
1068
|
-
|
|
1069
|
-
`create` 收已经装好的工具(同步,不扫目录);`send` 收任意形状,目录会在发送的那一刻现扫。只有一个来源时也可以直接用下面的 `scan` / `adopt`。
|
|
1070
|
-
|
|
1071
|
-
#### `Agent.tool.scan(directory)`
|
|
1072
|
-
|
|
1073
|
-
扫描目录(含子目录)里所有 `.js` / `.mjs` / `.ts` / `.mts` 文件,把其中形状对得上的注册成工具,其余文件跳过。Bun 直接执行 TypeScript,所以工具可以直接写成 `.ts`;只有类型、没有代码的 `.d.ts` 会被跳过。
|
|
1074
|
-
|
|
1075
|
-
```js
|
|
1076
|
-
Agent.tool.scan('./tools') // 路径字符串(相对宿主进程的当前目录)
|
|
1077
|
-
Agent.tool.scan(new URL('./tools', import.meta.url)) // URL——嵌进别人项目时用这个
|
|
1078
|
-
Agent.tool.scan(builtinDir, userDir) // 多个目录,后面的覆盖前面的同名工具
|
|
1079
|
-
```
|
|
1080
|
-
|
|
1081
|
-
多目录那条顺带给了你一个免费的覆盖机制:内置工具目录在前、用户工具目录在后,用户放一个同名工具就能替换掉内置的,不需要任何注册逻辑。
|
|
1082
|
-
|
|
1083
|
-
```js
|
|
1084
|
-
const tools = await Agent.tool.scan('./tools')
|
|
1085
|
-
// tools.schema → 给模型看的工具描述,传给 create/send 的 tools(或 Loop.run 的 tools)
|
|
1086
|
-
// tools.handlers → 执行器用的处理表,Tool.execute 需要它
|
|
1087
|
-
```
|
|
270
|
+
临时关闭 / 重新打开一条 MCP 连接,见[接 MCP](#接-mcp)。
|
|
1088
271
|
|
|
1089
|
-
|
|
272
|
+
### `Agent.LLM.ask(request, onChunk?)`
|
|
1090
273
|
|
|
1091
|
-
|
|
274
|
+
不建实例直接问模型:传完整的 `{ model, baseURL, apiKey, protocol, system, messages, tools, textTools, reasoning, stream, includeUsage, cache, provider, maxTokens, output, retry, signal, onRetry }`,
|
|
275
|
+
返回 `{ text, reasoning, toolCalls, usage, request, output?, messages }`,流式与非流式形状一致。`usage` 五个字段缺的补 0 方便累加;`request` 是上文 ④ 的请求记录(loop 把它挂到写进 history 的消息上)。
|
|
276
|
+
`reasoning` 是这次回复的思考全文(没有思考就是空串),`text` 是正文全文:流式时宿主可以拿它们核对 `onChunk` 推送过的片段有没有漏。`tools` 只要 `{ description, parameters }`,不会执行。
|
|
1092
277
|
|
|
1093
|
-
|
|
278
|
+
### 公开字段
|
|
1094
279
|
|
|
1095
|
-
|
|
1096
|
-
|
|
1097
|
-
|
|
1098
|
-
|
|
1099
|
-
|
|
1100
|
-
|
|
1101
|
-
`
|
|
1102
|
-
|
|
1103
|
-
文件工具和内存工具可以合并:`Agent.tool.merge(await Agent.tool.scan('./tools'), Agent.tool.adopt(mcpTools))`,或者直接用 `Agent.tool.from('./tools', mcpTools)`(见上)。想从集合里取子集,用 `pick` / `omit`:
|
|
1104
|
-
|
|
1105
|
-
```js
|
|
1106
|
-
const readonly = Agent.tool.pick(tools, ['read', 'glob']) // 只留这两个工具
|
|
1107
|
-
const safe = Agent.tool.omit(tools, ['shell', 'write']) // 去掉这些,其余全留
|
|
1108
|
-
const agent = Agent.create({ config, tools: safe })
|
|
1109
|
-
```
|
|
1110
|
-
|
|
1111
|
-
`pick` / `omit` 的 `names` 是字符串数组,`schema` 和 `handlers` 会**一起筛**,不会出现"模型看不见、却还能被执行"的隐蔽状态。返回的是新集合,可以直接交给 `create` / `send` / `merge`,也可以继续 `pick` / `omit`。空集合或 `undefined` 集合也安全(返回空集合)。
|
|
1112
|
-
|
|
1113
|
-
#### 工具集合里有什么
|
|
1114
|
-
|
|
1115
|
-
`scan` / `adopt` / `merge` / `pick` / `omit` 都返回同一种 `{ schema, handlers }`,里面的东西:
|
|
1116
|
-
|
|
1117
|
-
| 位置 | 是什么 |
|
|
1118
|
-
|------|--------|
|
|
1119
|
-
| `schema[name].name` | 工具名 |
|
|
1120
|
-
| `schema[name].description` | 给模型看的工具说明 |
|
|
1121
|
-
| `schema[name].source` | **来源标记**:`'file'`(目录扫描)或 `'memory'`(内存工具,MCP 工具走这里)。应用判断"这个工具从哪来"读它,别靠工具名前缀猜 |
|
|
1122
|
-
| `schema[name].inputSchema` | **已编译的校验器**(AI SDK 的 `jsonSchema()` 形态);原始 JSON Schema 在 `inputSchema.jsonSchema` 里 |
|
|
1123
|
-
| `handlers[name]` | 执行器内部形状(文件工具是 `url`,内存工具是 `execute` 等);**不要自己构造**,原样传回 `merge` / `pick` / `omit` 或 `Agent.tool.execute` |
|
|
1124
|
-
|
|
1125
|
-
工具对象上的额外字段会被 `scan` / `adopt` 原样带进 `schema[name]`:比如工具自己声明 `touchesFiles: ['path']`,应用层就能从 `tools.schema[name].touchesFiles` 读到。注意 `schema` 是发给模型的那一份,别把不想让模型看到的内部标记放进去(`execute`、`toModelOutput`、`timeout` 不会被带进去,它们只留在 `handlers`)。**想要"只在宿主用、不进 schema"的字段**(比如内部钩子),把工具包一层、从闭包里取,别写在工具对象上:
|
|
1126
|
-
|
|
1127
|
-
```js
|
|
1128
|
-
const wrap = (tool, host) => ({ ...tool, execute: (input, options) => tool.execute(input, { ...options, host }) }) // host 从闭包取,不进 schema
|
|
1129
|
-
```
|
|
1130
|
-
|
|
1131
|
-
**MCP 工具直接可用,不需要包装**:`@ai-sdk/mcp` 的 `client.tools()` 自带 `execute` 和 `toModelOutput`,核心按 AI SDK 的签名调用它们,文字、图片都会正确交给模型。完整接入例子见前面的[「接入 MCP 和技能」](#接入-mcp-和技能)。
|
|
1132
|
-
|
|
1133
|
-
想自己改写某个工具的返回结果时,给它加一个 `toModelOutput`,签名和 AI SDK 一致(拿到的是 `{ output, input }`):`toModelOutput: ({ output }) => ({ type: 'content', value: output.content })`。
|
|
1134
|
-
|
|
1135
|
-
> 从 0.16 升级:`Agent.create({ mcp })`、`agent.mcp`、`Agent.skill` 和 `create({ skills })` 已删除。MCP 改为自己用 `@ai-sdk/mcp` 连接,再把工具传进 `tools`;技能的提示词自己拼进 `config.system`。
|
|
1136
|
-
>
|
|
1137
|
-
> 从 0.19 升级:`onPermission` 的 `arguments` 字段改名为 `input`;结束原因多了一个 `'finished'`(没注册工具、或结构化输出已校验成功,原先是 `'no-tool'`)。工具对象的 `execute(input, { abortSignal })`、`toModelOutput({ output, input })` 现在按 AI SDK 签名调用。
|
|
1138
|
-
>
|
|
1139
|
-
> 从 0.21 升级:去掉了 `gpt-tokenizer`,上下文 token 改用**自校准估算**(字符数 × 每字符 token 比,比例由真实 `usage` 学到,跟着模型走);`maxContextTokens` 默认变为 `128000`,**自动压缩默认开启**(想关掉设 `maxContextTokens: Infinity`)。产物从 ~3.9 MB 降到 ~1.3 MB。
|
|
1140
|
-
>
|
|
1141
|
-
> 从 0.22 升级:内存工具声明的 `timeout` 现在真的生效;新增 `capabilities.usage`(关掉流式请求里的 `include_usage`);`compactThreshold`、字符串型 `maxContextTokens` 等非法配置现在会在 `send` 入口报错。
|
|
1142
|
-
>
|
|
1143
|
-
> 从 0.23 升级:内存工具(`Agent.tool.adopt`)现在也支持 `async *execute` 流式输出,和文件工具一致;`Tool.from` 接受一组目录(字符串数组);取消错误统一带 `error.kind === 'aborted'`。
|
|
1144
|
-
>
|
|
1145
|
-
> 从 0.25 升级(破坏性改名):上下文预算 `maxTokens` 改名为 **`maxContextTokens`**;`maxTokens` 现在指**单次生成的最大输出** token(映射到请求体的 `maxOutputTokens`)。这是把名字拨回 OpenAI / Anthropic 的习惯(它们的 `max_tokens` 就是输出上限,不是上下文)。另外:`onPermission` 现在要求**严格返回布尔**——非 `true`(含对象、漏 `return`)一律按拒绝处理;新增 `Agent.tool.pick` / `Agent.tool.omit` 用来取工具子集(做只读模式用 `omit` 去掉写工具)。
|
|
1146
|
-
>
|
|
1147
|
-
> 从 0.27 升级:`Compact.run` 的返回值从总结文本变成 `{ content, usage }`(单独用 `Agent.compact` 时注意解构);`onCompact` 的流事件统一带 `request: 'compact'` 标记、`compact-finish` 带 `usage`;工具被拒绝/取消/无效调用也触发 `onToolResult`,`onStep` 的 `toolResults` 是完整结果对象;自动压缩的用量计进 `send().usage`;新增 `agent.resume()` 从历史末尾续跑;工具的 `schema[name]` 带来源标记 `source: 'file' | 'memory'`;文件工具(子进程路径)的 `execute(input, options)` 现在也能拿到 `options.abortSignal`(取消即杀进程不变,信号仅供工具优雅收尾)。
|
|
1148
|
-
>
|
|
1149
|
-
> 从 0.30 升级(破坏性):去掉了 `maxSteps` 和结束原因 `'step-limit'`。这个包**不再限制循环轮数**——什么时候停由模型的判断和工具的结果决定。原来靠 `maxSteps` 兜底的地方,改由应用层控制:给 `send` 传 `signal`、设 `requestTimeout`,或者写一个返回 `stop: true` 的 `finish` 工具。
|
|
1150
|
-
|
|
1151
|
-
#### `Agent.tool.execute(options)`
|
|
1152
|
-
|
|
1153
|
-
直接执行一个工具(通常不需要手动调用,Agent 内部会调用)。
|
|
1154
|
-
|
|
1155
|
-
```js
|
|
1156
|
-
const result = await Agent.tool.execute({
|
|
1157
|
-
name: 'add',
|
|
1158
|
-
input: { a: 1, b: 2 },
|
|
1159
|
-
handlers: tools.handlers,
|
|
1160
|
-
signal: abortController.signal, // 可选:取消信号
|
|
1161
|
-
onOutput: output => {}, // 可选:接收工具流式输出(文件工具的 stdout/生成器 yield,内存工具的生成器 yield)
|
|
1162
|
-
limit: 32000, // 可选:输出字符上限,超出从中间截断;不传则不截断
|
|
1163
|
-
concurrency: 8, // 可选:同一批(同一个 signal)最多同时跑几个文件工具,超出的排队
|
|
1164
|
-
})
|
|
1165
|
-
// result.output → 工具输出块,type 是 'text' | 'json' | 'content' | 'error-text' | 'error-json' | 'execution-denied'
|
|
1166
|
-
// result 还带:stop:true(工具要求结束循环)/ error(工具失败)/ interrupted:true(被取消)
|
|
1167
|
-
```
|
|
1168
|
-
|
|
1169
|
-
---
|
|
1170
|
-
|
|
1171
|
-
### `Agent.llm`
|
|
1172
|
-
|
|
1173
|
-
#### 结构化结果
|
|
1174
|
-
|
|
1175
|
-
```js
|
|
1176
|
-
const agent = Agent.create({
|
|
1177
|
-
config: {
|
|
1178
|
-
baseURL, apiKey, model,
|
|
1179
|
-
output: Agent.output.object({ // 要什么形状的结果,写在配置顶层
|
|
1180
|
-
schema: Agent.schema.object({ total: Agent.schema.number() }),
|
|
1181
|
-
}),
|
|
1182
|
-
},
|
|
1183
|
-
})
|
|
1184
|
-
const { output } = await agent.send('计算订单总数')
|
|
1185
|
-
console.log(output.total)
|
|
1186
|
-
```
|
|
1187
|
-
|
|
1188
|
-
`Agent.output` 是包内 AI SDK 的 Output,`Agent.schema` 是包内 Zod,无需另装一套。数组可用 `Agent.output.array({ element: Agent.schema.string() })`,普通 JSON 可用 `Agent.output.json()`。所选模型服务须支持对应输出格式。
|
|
1189
|
-
|
|
1190
|
-
有工具时先完成工具调用,再读取最终对象。工具轮或 `tool-stop` 不会凭空产生 `output`。最终对象校验成功立即结束;格式错误默认也会重试(重新生成不保证还是坏的),想让它立刻失败可用 `retry` 过滤或收紧 `retryMaxElapsed`。手动及自动压缩只生成文本总结,不继承任务的对象格式。流式和非流式都在最终结果上提供 `output`;流中仍会有生成时的文字片段。
|
|
1191
|
-
|
|
1192
|
-
直接使用底层 LLM,绕过 Agent 循环。这里的参数是**一次性**的:`Agent.llm.chat` 不认识 `agent.config`,运行中改配置再重发是 Agent 层(`send` / 重试)的事——见「每笔请求现拼」。
|
|
1193
|
-
|
|
1194
|
-
#### `Agent.llm.chat(options)`
|
|
1195
|
-
|
|
1196
|
-
```js
|
|
1197
|
-
const result = await Agent.llm.chat({
|
|
1198
|
-
baseURL: 'https://api.example.com/v1',
|
|
1199
|
-
apiKey: 'sk-xxx',
|
|
1200
|
-
model: 'gpt-4o',
|
|
1201
|
-
messages: [{ role: 'user', content: '你好' }],
|
|
1202
|
-
provider: { temperature: 0.3 }, // 生成参数原样转给 AI SDK
|
|
1203
|
-
stream: true, // 默认 true
|
|
1204
|
-
onLLMEvent: event => console.log(event), // 流式事件回调
|
|
1205
|
-
})
|
|
1206
|
-
// result.text → 模型回复的文字
|
|
1207
|
-
// result.toolCalls → 工具调用列表
|
|
1208
|
-
// result.usage → token 用量
|
|
1209
|
-
// result.finishReason → 停止原因
|
|
1210
|
-
```
|
|
1211
|
-
|
|
1212
|
-
`Agent.llm.chat` 只负责和模型说话,不处理文字工具协议(`toolMode` 是 Agent 的配置,由主循环负责)。直接调它、又要让纯对话模型用工具时,自己在请求前后各调一次:
|
|
1213
|
-
|
|
1214
|
-
```js
|
|
1215
|
-
const spec = await Agent.textTools.prepare(tools.schema) // 把工具表写成说明书
|
|
1216
|
-
const reply = await Agent.llm.chat({ ...connection, messages: Agent.textTools.wrap(messages, spec) }) // 不带 tools 字段
|
|
1217
|
-
const result = Agent.textTools.read(reply, spec, { loose: true }) // result.toolCalls 就是读回来的调用
|
|
1218
|
-
```
|
|
1219
|
-
|
|
1220
|
-
---
|
|
1221
|
-
|
|
1222
|
-
### `Agent.context`
|
|
1223
|
-
|
|
1224
|
-
#### `Agent.context.build(options)`
|
|
1225
|
-
|
|
1226
|
-
把历史消息裁剪成模型能用的上下文,并估算 token 数。
|
|
1227
|
-
|
|
1228
|
-
```js
|
|
1229
|
-
const { messages, token } = Agent.context.build({
|
|
1230
|
-
history: agent.history,
|
|
1231
|
-
system: '你是助手',
|
|
1232
|
-
tools: tools.schema,
|
|
1233
|
-
keep: { firstTurns: 0 }, // 可选:压缩后保留多少旧内容,语义同 config.contextKeep
|
|
1234
|
-
})
|
|
1235
|
-
// messages → 可以直接传给 LLM.chat 的消息数组
|
|
1236
|
-
// token → 估算的 token 数(不装分词器:文字按字符数 × 每字符 token 比,比例由 Loop 从真实 usage 自校准;媒体按块计,不看 base64 长度)
|
|
1237
|
-
```
|
|
1238
|
-
|
|
1239
|
-
裁剪的最小单位是**回合**,不是消息。一个回合 = 模型的一次响应 + 它发起的全部工具调用 + 这些调用的结果,
|
|
1240
|
-
永远同进同出。所以裁剪结果里不会出现"有调用没结果"或"有结果没调用"的残缺配对——那种序列会被
|
|
1241
|
-
OpenAI 和 Anthropic 直接 400。
|
|
1242
|
-
|
|
1243
|
-
压缩时默认保留:用户最初的 3 个回合(保留原始目标)+ 最新总结 + 总结前最近 3 个回合 + 总结后所有回合。数量可用 `keep`(对应 `config.contextKeep`)覆盖,`0` 表示不留。
|
|
1244
|
-
|
|
1245
|
-
模型的思考内容(`reasoning`)会留在 `history` 里供上层 UI 渲染,但不会回传给模型:
|
|
1246
|
-
它是某一次响应的厂商产物,不是持久对话状态,回传还会被一些服务拒绝。
|
|
280
|
+
| 字段 | 说明 |
|
|
281
|
+
|------|------|
|
|
282
|
+
| `history` | 消息数组(AI SDK 标准消息 + `id`,`assistant` / `compact` 另带请求记录 `request`,外加 `compact` 总结和 `error` 记录——模型请求出错时 loop 写的,或宿主自己写的)。宿主可直接读写;`error` 永远不发给模型,`request` 发送时去掉 |
|
|
283
|
+
| `tools` / `MCP.list` | 工具路径 / MCP 连接配置,增删或整份替换下一轮生效 |
|
|
284
|
+
| `config` | 活配置,下一轮生效 |
|
|
285
|
+
| `contextRatio` | 冷启动的"每字符 token"估算比例;学到真实值之前用它 |
|
|
286
|
+
| `ratios` | 按模型名学到的比例 `{ 模型名: 比例 }`,宿主可持久化后下次传回 |
|
|
1247
287
|
|
|
1248
288
|
---
|
|
1249
289
|
|
|
1250
|
-
|
|
1251
|
-
|
|
1252
|
-
```js
|
|
1253
|
-
const History = Agent.history // 从唯一入口拿,打包成单文件之后也一样
|
|
1254
|
-
|
|
1255
|
-
// 创建各种类型的历史块
|
|
1256
|
-
History.user({ content: '你好' })
|
|
1257
|
-
History.user({ content: [{ type: 'text', text: '这是什么' }, { type: 'image', image: dataUrl }] }) // 带图片
|
|
1258
|
-
History.assistant({ content: '你好', toolCalls: [{ id: 'call-1', name: 'add', arguments: { a: 1, b: 2 } }] })
|
|
1259
|
-
History.tool({ toolCallId: 'call-1', toolName: 'add', content: '3' })
|
|
1260
|
-
History.compact({ content: '之前的对话总结...' })
|
|
290
|
+
## 上下文与压缩
|
|
1261
291
|
|
|
1262
|
-
|
|
1263
|
-
History.error({ content: '请求失败:500', request: { model: 'claude', ms: 1234, error: 'boom' } })
|
|
1264
|
-
```
|
|
1265
|
-
|
|
1266
|
-
**失败记录(`role:'error'`)**:它不参与回合、不参与工具配对、不参与压缩,`Context.build()` 会整条丢掉;`render()` 仍然把正文渲染出来,`request` 原样保存在这条消息上,宿主可以放自己的审计信息(模型、耗时、错误原因)。只有 `user` / `assistant` / `tool` 会发给模型——history 里出现别的 role,会跳过并 `console.warn` 一次(`error` 除外,那是预期用法)。
|
|
292
|
+
history 里原文一条不少;每次请求只从里面**现挑**发给模型的内容:
|
|
1267
293
|
|
|
1268
|
-
|
|
294
|
+
1. 开场的 `head` 个用户回合;
|
|
295
|
+
2. 最新一条总结——**折进 system**,不当成消息(当消息发,模型会以为用户塞给它一张表,从头重做);
|
|
296
|
+
3. 总结之前最近的 `beforeSummary` 个用户回合;
|
|
297
|
+
4. 总结之后的全部原文。
|
|
1269
298
|
|
|
1270
|
-
|
|
1271
|
-
|
|
1272
|
-
|
|
1273
|
-
|
|
1274
|
-
|
|
1275
|
-
|
|
1276
|
-
|
|
1277
|
-
History.turns(agent.history) // 折成回合:[[user], [assistant, tool], [user]]
|
|
1278
|
-
```
|
|
1279
|
-
|
|
1280
|
-
`turns()` 的规则比看上去微妙——**工具结果认的是发起它的 `toolCallId`,不是它在数组里排在谁后面**。从数据库按 id 恢复会话时结果可能排在调用前面,自己推一遍很容易算错。`Context.build()` 裁剪上下文用的就是这同一份实现,所以"什么是一个回合"在整个包里只有一处定义。
|
|
1281
|
-
|
|
1282
|
-
想自己排版的,用 `turns()` 拿到回合,再按内容块类型(`text` / `reasoning` / `tool-call` / `tool-result` / `image` / `file`)自己拼。
|
|
299
|
+
`budget × maxContextTokens` 约束第 1、3 段,超出先丢最早的一轮。**进行中的那一轮不会整轮丢掉**:
|
|
300
|
+
一次 send 里压缩后它落在总结之前,整轮放不下(或 `beforeSummary` 为 0)时,用户那句话始终保留,
|
|
301
|
+
再按"步"(一次模型回复连同它的工具结果)从后往前补回预算装得下的最近几步——模型既看得到"正在做的事",
|
|
302
|
+
也看得到刚刚那一步的现场(刚读到的内容、刚报的错),不用从头再来;`budget: 0` 时只留那句话。
|
|
303
|
+
裁剪按回合 / 步进行,工具结果按 `toolCallId` 跟在它的调用后面,落单的调用 / 结果丢掉;
|
|
304
|
+
history 里发不出去的消息(`system`、未知 role、没有 content)跳过并 `onWarning` 一次,保证发出去的永远是合法上下文。估算超过 `compactThreshold` 就自动压缩一次(每轮最多一次);
|
|
305
|
+
二次压缩会把上一版总结并进提示词,越压不会越忘。token 估算比例在每次拿到真实 usage 后按模型名校准。
|
|
1283
306
|
|
|
1284
307
|
---
|
|
1285
308
|
|
|
1286
309
|
## 上生产前
|
|
1287
310
|
|
|
1288
|
-
|
|
1289
|
-
|
|
1290
|
-
|
|
|
1291
|
-
|
|
1292
|
-
| `
|
|
1293
|
-
| `
|
|
1294
|
-
| `requestTimeout` | 不限制 | 默认不限单笔时长:卡住的请求会一直等下去。设毫秒数,到点中断这一笔。 |
|
|
1295
|
-
| `retryMaxElapsed` | 不限制 | 默认重试所有错误且无总上限,等于无限重试。生产建议设毫秒数收口,或用 `retry` 过滤掉不该重试的错误(如 `auth`、`request`)。 |
|
|
1296
|
-
| `maxContextTokens` | `128000` | 上下文预算,要按你模型的窗口调。比窗口大会撑爆,比需求小会频繁压缩。 |
|
|
1297
|
-
|
|
1298
|
-
**这个包不限制循环轮数。** 循环停不停只由模型的判断、工具的结果(`stop: true`)、取消和报错决定。生产里要兜住"模型一直调工具停不下来",由应用层做:给 `send` 传 `signal`,用你自己的计时器或业务条件取消;或者写一个 `finish` 工具让模型主动收尾。
|
|
311
|
+
| 旋钮 | 为什么要设 |
|
|
312
|
+
|------|------------|
|
|
313
|
+
| `requestTimeout` | 默认不限单笔时长,卡住的请求会一直等 |
|
|
314
|
+
| `retryMaxElapsed` / `retry` | 默认重试所有可重试错误且无总上限;建议收口,或跳过 `auth`、`request` |
|
|
315
|
+
| `maxContextTokens` | 按你模型的窗口调 |
|
|
316
|
+
| `maxToolOutput` | 按模型窗口和工具特性设置(默认不截断) |
|
|
1299
317
|
|
|
1300
|
-
|
|
318
|
+
这个包不限制循环轮数。要兜住"一直调工具停不下来",由宿主用计时器调 `agent.stop()`,或提供一个返回 `stop: true` 的收尾工具。
|
|
1301
319
|
|
|
1302
|
-
|
|
1303
|
-
|
|
1304
|
-
```js
|
|
1305
|
-
const startedAt = new Map() // toolCallId → 开始时间
|
|
1306
|
-
|
|
1307
|
-
const agent = Agent.create({
|
|
1308
|
-
config,
|
|
1309
|
-
callbacks: {
|
|
1310
|
-
// 一次模型请求的耗时和用量
|
|
1311
|
-
onLLMStart: () => { startedAt.set('llm', performance.now()) },
|
|
1312
|
-
onLLMFinish: result => {
|
|
1313
|
-
console.log('模型耗时', (performance.now() - startedAt.get('llm')).toFixed(0), 'ms', result.usage)
|
|
1314
|
-
},
|
|
1315
|
-
// 每个工具的耗时和结果
|
|
1316
|
-
onToolCall: ({ toolCallId, toolName, input }) => {
|
|
1317
|
-
startedAt.set(toolCallId, performance.now())
|
|
1318
|
-
console.log('工具开始', toolName, input)
|
|
1319
|
-
},
|
|
1320
|
-
onToolResult: ({ toolCallId, toolName, output }) => {
|
|
1321
|
-
console.log('工具结束', toolName, (performance.now() - startedAt.get(toolCallId)).toFixed(0), 'ms', output)
|
|
1322
|
-
},
|
|
1323
|
-
// 一轮(模型 + 全部工具)结束
|
|
1324
|
-
onStep: ({ step, toolCalls }) => {
|
|
1325
|
-
console.log('第', step, '轮结束', toolCalls.length, '个工具')
|
|
1326
|
-
},
|
|
1327
|
-
// 压缩开始 / 完成
|
|
1328
|
-
onCompact: event => console.log('压缩', event.type, event),
|
|
1329
|
-
},
|
|
1330
|
-
})
|
|
1331
|
-
```
|
|
1332
|
-
|
|
1333
|
-
把这些按 `step` 或 `toolCallId` 串起来写进日志或时序库,就是每一轮的完整观测数据。
|
|
1334
|
-
|
|
1335
|
-
想直接接 AI SDK 的 OpenTelemetry,把 `experimental_telemetry` 放进 `config.provider` 即可——本包把 `provider` 整份转给模型调用,不截留字段:
|
|
1336
|
-
|
|
1337
|
-
```js
|
|
1338
|
-
config: {
|
|
1339
|
-
// ...
|
|
1340
|
-
provider: {
|
|
1341
|
-
experimental_telemetry: { isEnabled: true, functionId: 'my-agent' },
|
|
1342
|
-
},
|
|
1343
|
-
}
|
|
1344
|
-
```
|
|
1345
|
-
|
|
1346
|
-
## 示例
|
|
1347
|
-
|
|
1348
|
-
[`examples/minimal/`](examples/minimal/) 是一个能直接跑起来的最小项目:用本地假模型,不需要任何密钥,注册一个工具跑完一圈,适合拿来当起点。
|
|
1349
|
-
|
|
1350
|
-
```bash
|
|
1351
|
-
bun examples/minimal/main.js
|
|
1352
|
-
```
|
|
1353
|
-
|
|
1354
|
-
[`examples/app/`](examples/app/) 是一个更完整的 chat 服务示例:同样的本地假模型,演示会话管理 / 持久化 / 流式 / 权限 / 观测 / 取消 / 生产设置,适合要写真实应用的人参考。
|
|
1355
|
-
|
|
1356
|
-
```bash
|
|
1357
|
-
bun examples/app/server.js
|
|
1358
|
-
```
|
|
1359
|
-
|
|
1360
|
-
## 长跑压测
|
|
1361
|
-
|
|
1362
|
-
`bun scripts/stress.js` 会跑多会话 × 多轮,打印完成情况和内存增量。生产长期运行前,先在你自己的负载上压一遍。
|
|
1363
|
-
|
|
1364
|
-
## 运行测试
|
|
1365
|
-
|
|
1366
|
-
```bash
|
|
1367
|
-
bun test
|
|
1368
|
-
```
|
|
1369
|
-
|
|
1370
|
-
测试在 [`tests/`](tests/) 里按 Agent、模型、上下文、工具等模块分文件;模型测试使用本地模拟服务。
|
|
320
|
+
---
|
|
1371
321
|
|
|
1372
|
-
|
|
322
|
+
## 项目架构
|
|
1373
323
|
|
|
1374
|
-
```bash
|
|
1375
|
-
bun test --coverage
|
|
1376
324
|
```
|
|
325
|
+
index.ts 包入口:导出 Agent 和类型
|
|
326
|
+
src/
|
|
327
|
+
agent.ts 唯一的状态持有者:create / send / stop / compact、Agent.LLM
|
|
328
|
+
loop/run.ts 一次 send 的完整循环(loop 是 history 唯一的写入者)
|
|
329
|
+
loop/compact.ts 压缩:拼总结请求、问模型、写 role:compact、发 onCompact
|
|
330
|
+
loop/decide.ts 每轮结束后的继续 / 提醒 / 结束判定
|
|
331
|
+
context/build.ts 从 history 现挑这一次要发的上下文
|
|
332
|
+
model/ask.ts 问一次模型(流式 / 非流式 / 文字工具),重试
|
|
333
|
+
model/configure.ts 按协议建 provider、提示词缓存
|
|
334
|
+
model/text-tools/ 文字协议工具:describe 描述、parse 解析
|
|
335
|
+
tools/load.ts 展开路径、子进程读元数据、mtime 缓存
|
|
336
|
+
tools/run.ts 并行执行一轮的工具调用
|
|
337
|
+
tools/spawn.ts 启动工具子进程(process.execPath + IPC)
|
|
338
|
+
tools/child.ts 子进程入口
|
|
339
|
+
tools/shape.ts 结果整形与截断
|
|
340
|
+
tools/mcp.ts MCP 连接
|
|
341
|
+
history.ts 追加、按回合切分、未答复的调用
|
|
342
|
+
utils/ errors(错误分类)、retry(重试)、tokens(估算与校准)
|
|
343
|
+
types.ts 全部共享类型
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
导入只能往下指:`agent > loop > {context, model, tools} > history > utils > types`,同层能力模块互不导入,
|
|
347
|
+
`bun run check` 会检查(`scripts/check-imports.ts`)。
|
|
1377
348
|
|
|
1378
349
|
---
|
|
1379
350
|
|
|
1380
|
-
##
|
|
351
|
+
## 开发与发布
|
|
1381
352
|
|
|
1382
353
|
```bash
|
|
1383
|
-
bun
|
|
1384
|
-
|
|
1385
|
-
|
|
1386
|
-
只生成 `dist/agent-core.js`:Bun 运行时使用的依赖全部内联并压缩。同时把手写的类型声明 `index.d.ts` 复制成 `dist/agent-core.d.ts`,TypeScript 用户导入时有参数补全和类型检查。构建脚本在没有 `node_modules` 的临时目录中导入产物,实际运行一次工具和模型模拟请求,成功后才替换 `dist/agent-core.js`。发布包只包含 `dist/agent-core.js`、`dist/agent-core.d.ts`、`README.md`、`LICENSE` 和 `package.json`;`npm pack` / `npm publish` 前会自动构建。产物顶部写有版本号和提交号,压缩不是加密。
|
|
1387
|
-
|
|
1388
|
-
```js
|
|
1389
|
-
import Agent from './agent-core.js'
|
|
1390
|
-
|
|
1391
|
-
// 工具目录用 URL 指,永远相对你自己这份代码,不受宿主进程当前目录影响
|
|
1392
|
-
const tools = await Agent.tool.scan(new URL('./tools', import.meta.url))
|
|
1393
|
-
const agent = Agent.create({ config: { /* ... */ }, tools })
|
|
354
|
+
bun test # 全部测试(用 ai/test 的 mock 模型,不联网)
|
|
355
|
+
bun run check # tsc 类型检查 + 导入方向检查
|
|
356
|
+
bun run build # 打包 dist/agent-core.js + dist/types,并在临时目录自检
|
|
1394
357
|
```
|
|
1395
358
|
|
|
1396
|
-
`
|
|
1397
|
-
|
|
1398
|
-
| | |
|
|
1399
|
-
|---|---|
|
|
1400
|
-
| `Agent.version` | 包版本,排查问题时报得出来 |
|
|
1401
|
-
| `Agent.create(...)` | 创建 Agent 实例 |
|
|
1402
|
-
| `Agent.tool` | `.from()` / `.scan()` / `.adopt()` / `.execute()` / `.merge()` / `.pick()` / `.omit()` |
|
|
1403
|
-
| `Agent.history` | `.user()` / `.assistant()` / `.tool()` / `.compact()` / `.error()` 造消息块;`.turns()` / `.render()` 读历史 |
|
|
1404
|
-
| `Agent.context` | `.build()` |
|
|
1405
|
-
| `Agent.compact` | `.run()` |
|
|
1406
|
-
| `Agent.llm` | `.chat()` |
|
|
1407
|
-
| `Agent.textTools` | 文字工具协议:`.prepare()` / `.wrap()` / `.read()`,直接调 `llm.chat` 时用 |
|
|
1408
|
-
| `Agent.output` / `Agent.schema` | 结构化输出的 Output 与 Zod,包内同一份,无需另装 |
|
|
1409
|
-
|
|
1410
|
-
`Agent.history` 和 `Agent.textTools` 还导出一些底层方法(`stored` / `model` / `parts` / `answeredCalls`,以及文字协议的 `parse` / `downgrade` / `refused` / `remember` / `remembered`),完整列表见 `index.d.ts`。
|
|
1411
|
-
|
|
1412
|
-
`Agent.history` 是嵌入时最常用的那个:把 IM 消息转成 user 块、往历史里塞一条系统通知、从数据库恢复会话,都要靠它造出格式正确的消息。
|
|
1413
|
-
|
|
1414
|
-
**工具进程需要一个 bun 运行时。** 普通 `bun run` 时用的就是宿主自己(`process.execPath`,不依赖 PATH);宿主被 `bun build --compile` 成单可执行文件时,会退回 PATH 上的 `bun`——这种分发方式需要目标机器装了 bun。
|
|
1415
|
-
|
|
1416
|
-
工具目录不会被打包——它本来就该是运行时扫描的,放文件即加功能这件事在打包后照样成立。
|
|
1417
|
-
|
|
1418
|
-
工具进程那一半(`features/tool-process.js`)在打包时会被当成文本内联进单文件,运行时通过 `bun -` 从 stdin 喂给一个新的子进程,
|
|
1419
|
-
所以产物挪到任何目录都能正常执行工具,也不会往磁盘上写临时文件。
|
|
1420
|
-
这也是 `tool-process.js` 里不能出现任何 `import` 的原因:它以匿名程序的身份运行,相对路径和裸包名会按进程当前目录解析,必然出错。
|
|
1421
|
-
(用 stdin 而不是 `bun -e`:后者在 8KB 到 32KB 之间就会 `ENAMETOOLONG`,而工具进程源码已经接近这个量级。)
|
|
359
|
+
开发时工具子进程直接从 `src/tools/child.ts` 启动;打包时 `scripts/build.ts` 把子进程入口打成文本内联进产物,
|
|
360
|
+
产物里以 `bun -` 从 stdin 启动,不依赖任何包内文件路径。版本与发布流程见 [AGENTS.md](AGENTS.md)。
|
|
1422
361
|
|
|
1423
362
|
---
|
|
1424
363
|
|
|
1425
364
|
## 这个包不做什么
|
|
1426
365
|
|
|
1427
|
-
|
|
1428
|
-
|
|
1429
|
-
|
|
1430
|
-
|
|
1431
|
-
|
|
1432
|
-
|
|
1433
|
-
**不做用户和权限系统。** 它只有一个 `onPermission` 回调,在工具执行前问一句"放不放行"。谁是用户、谁登录了、谁能用哪个工具,由你的应用判断后通过这个回调告诉它。
|
|
1434
|
-
|
|
1435
|
-
**不隔离多租户。** 一台 Agent 是一个独立对象,`history`、`config`、`running` 都在自己的实例里,实例之间互不影响。但"张三的对话不能跑到李四那里"要靠你给每个用户各自创建 Agent、各自保管 history 来实现,核心包不提供账号、鉴权、数据隔离。
|
|
1436
|
-
|
|
1437
|
-
**不管并发排队和限流。** 同一台 Agent 上后一次 `send` 会停掉前一次(这是有意设计的"最新指令优先")。要让多个用户同时用,就为每个会话建一台 Agent;要限制总并发、总费用,由你的应用做。核心包没有全局任务队列。
|
|
1438
|
-
|
|
1439
|
-
**不管 MCP 连接和技能。** 核心只接收通用工具对象。MCP 服务的连接、开关和关闭由你的应用管理,再用 `Agent.tool.adopt` 把工具交进来;技能提示词自己拼进 `system`。
|
|
1440
|
-
|
|
1441
|
-
**不做工具的安全检查。** 工具子进程和 Agent 拥有完全相同的权限:读写任意文件、执行任意命令、联网、读到父进程的全部环境变量。这是有意的——电脑任务 agent 的工具本来就得能干这些。**沙箱、白名单、危险命令拦截属于你的应用层**,核心包只提供 `onPermission` 这一个挂钩点。
|
|
1442
|
-
|
|
1443
|
-
**不保证所有模型/中转站的兼容性。** 它针对四种协议做了适配,也在真实网关上验证过,但中转站千奇百怪:有的返回的状态码和实际结果不符,有的字段缺失。遇到不兼容时,`error.kind` 会告诉你大概是哪一类问题,但没法替那个服务端修好它。
|
|
1444
|
-
|
|
1445
|
-
**不保证长跑和多会话并发下的表现。** 这两项只在小规模下验证过。要在生产环境长期运行,请先按你自己的负载压测。
|
|
1446
|
-
|
|
1447
|
-
**没有 GUI、没有服务端、没有命令行工具。** 它只是一个库,被别的程序 `import` 使用。开箱即用的聊天应用不在它的范围内。
|
|
1448
|
-
|
|
1449
|
-
---
|
|
1450
|
-
|
|
1451
|
-
## 常见问题
|
|
1452
|
-
|
|
1453
|
-
**Q:支持 Node.js 吗?**
|
|
1454
|
-
|
|
1455
|
-
不支持,而且这是刻意的。工具进程用 [`Bun.spawn` + IPC](features/tool-process.js),扫描用 [`Bun.Glob`](features/tool.js),打包靠 `import ... with { type: 'text' }`,都只有 Bun 有。
|
|
1456
|
-
|
|
1457
|
-
---
|
|
1458
|
-
|
|
1459
|
-
**Q:支持哪些模型提供商?**
|
|
1460
|
-
|
|
1461
|
-
通过 `config.protocol` 控制:
|
|
1462
|
-
|
|
1463
|
-
| protocol 值 | 适用场景 |
|
|
1464
|
-
|-------------|----------|
|
|
1465
|
-
| `chat`(默认) | OpenAI 以及任何兼容 OpenAI Chat 接口的中转站 |
|
|
1466
|
-
| `responses` | OpenAI Responses API |
|
|
1467
|
-
| `anthropic` | Anthropic 官方接口 |
|
|
1468
|
-
| `gemini` | Google Gemini 接口 |
|
|
1469
|
-
|
|
1470
|
-
---
|
|
1471
|
-
|
|
1472
|
-
**Q:上下文太长会怎样?**
|
|
1473
|
-
|
|
1474
|
-
上下文超过 `config.maxContextTokens` 的 `compactThreshold`(默认 0.8,即 80%)时,Loop 会自动调用 Compact 把历史压缩成一段总结,然后继续运行。**默认就开着**:`maxContextTokens` 默认 `128000`,不配置也会在接近上限时自动压缩,避免把上下文撑爆。你的模型窗口比这小就把它调小;想彻底关掉设 `maxContextTokens: Infinity`。
|
|
1475
|
-
|
|
1476
|
-
**上下文 token 怎么估**:不装分词器,用"字符数 × 每字符多少 token"。这个比例是**会自校准**的——每轮模型都会回 `usage.inputTokens`(这次请求真实的输入 token 数),拿它反推这个模型真实的"每字符 token 比"记下来给下一轮。换模型(`config.compact` 的压缩模型、`send` 时覆盖 `model`、换 provider)就换一条记录,越用越准,也不怕分词器对不上模型。
|
|
1477
|
-
|
|
1478
|
-
**图片 / 音频 / 视频 / 文件不按 base64 字符数算。** 媒体块在 JSON 里可能有几百万字符,但模型为它付的 token 只取决于尺寸和解码方式,所以每块按固定值(`MEDIA_TOKENS`,1200)估,校准时会先把这部分从真实用量里扣掉。不这么做的话,一张截图就能让估算从 14 万跳到 80 万,上下文还很空就触发压缩(实战踩过:JSON 从 100 万字符涨到 4700 万字符)。
|
|
1479
|
-
|
|
1480
|
-
**压缩只往 `agent.history` 里追加一条总结,永远不删任何东西。** `history` 是唯一权威数据来源,该保留多少由持有它的你来决定——压缩控制的是"这一轮发给模型的内容有多大",不是"历史能留多少"。
|
|
1481
|
-
|
|
1482
|
-
**压缩可以另配一套模型。** 总结不需要主模型那么聪明,用便宜的小模型就够,写在 `config.compact` 里:
|
|
1483
|
-
|
|
1484
|
-
```js
|
|
1485
|
-
config: {
|
|
1486
|
-
baseURL: 'https://api.example.com/v1', apiKey: 'sk-xxx', model: '主模型',
|
|
1487
|
-
compact: { model: '便宜的小模型' }, // 也能一起换 baseURL / apiKey / provider
|
|
1488
|
-
}
|
|
1489
|
-
```
|
|
1490
|
-
|
|
1491
|
-
不写 `compact` 就和主模型共用。自动压缩和手动 `agent.compact()` 用的都是这一套。
|
|
1492
|
-
|
|
1493
|
-
> 用更小的小模型做压缩时注意:那笔压缩请求的**大小是由主模型的 `maxContextTokens` 决定的**,跟压缩模型自己的窗口无关。如果压缩模型的窗口比主模型预算小,压缩请求会先在小模型这边撑爆。让压缩模型的窗口 ≥ 主模型预算,或把 `maxContextTokens` 调小。
|
|
1494
|
-
|
|
1495
|
-
**最新的那条总结会折进 `system`,而不是当成一条用户消息塞进对话里**,并且带一句"这是你自己之前做过的工作,数据已由工具确认"。裸的 `role:'user'` 总结会被模型读成"用户塞给我一张表",于是它从头重做整个任务——真实端点实测 `gpt-oss-120b` 改之前 1/6 能正确续跑,改之后 6/6。
|
|
1496
|
-
|
|
1497
|
-
保留多少旧内容是**按预算**算的,不是按条数:默认最初目标最多占 20%、总结前的现场最多占 30%,总结之后的新回合不受限。只按条数留的话,用户第一条消息粘一大段日志就能让压缩永远收敛不了(实测 120/120 轮压完仍超阈值)。放不下的最初目标不会丢——总结本身就被要求保留用户的原始目标,而总结在 `system` 里,永远不会被裁掉。
|
|
1498
|
-
|
|
1499
|
-
这几个默认值可以用 `config.contextKeep` 覆盖:
|
|
1500
|
-
|
|
1501
|
-
```js
|
|
1502
|
-
config: {
|
|
1503
|
-
// ...
|
|
1504
|
-
contextKeep: {
|
|
1505
|
-
firstTurns: 0, // 压缩后不带总结之前的开场原文,只信总结 + 最近现场
|
|
1506
|
-
// recentTurns: 3, // 总结前保留几个回合
|
|
1507
|
-
// firstShare: 0.2, // 开场最多占多少预算 [0,1]
|
|
1508
|
-
// recentShare: 0.3,// 总结前现场最多占多少预算 [0,1]
|
|
1509
|
-
},
|
|
1510
|
-
}
|
|
1511
|
-
```
|
|
1512
|
-
|
|
1513
|
-
- `0` 是合法值,表示这一段一点都不留(实现里用 `??` 取默认值,不是 `||`)。
|
|
1514
|
-
- 无论怎么配,**本次 send 的用户输入永远保留**——它是当前任务,剪掉模型就只能瞎猜。
|
|
1515
|
-
- 手动 `agent.compact()` 和自动压缩用的是同一份 `contextKeep`,不用配两遍。
|
|
1516
|
-
|
|
1517
|
-
每轮最多压一次。压完还超限就照常发出去,由模型服务判断收不收;下一轮还超自然会再压。**不会**为了压到达标而连续调用模型——那样一轮能烧掉上千次请求。
|
|
1518
|
-
|
|
1519
|
-
---
|
|
1520
|
-
|
|
1521
|
-
**Q:工具返回一个巨大的结果会怎样?**
|
|
1522
|
-
|
|
1523
|
-
默认不截断(`maxToolOutput` 默认 `undefined`)。设置 `config.maxToolOutput`(字符数)后,超出的部分会从中间截断,头尾都保留,并插入一段明确的提示告诉模型"输出过长、请缩小范围或分页重新获取"。
|
|
1524
|
-
|
|
1525
|
-
截断**只作用于文字**。多模态输出块里的图片、文件一个字节都不动——截一刀就彻底废了,截图工具的返回值本来就大。
|
|
1526
|
-
|
|
1527
|
-
建议主动设置它(比如 `maxToolOutput: 32000`):实测一个返回 1MB 文本的工具(`cat` 一个日志文件就够了)= **31 万 token**,超过大多数模型的整个上下文窗口,而且它会永久留在历史里——连压缩都救不回来,因为压缩本身要把这坨东西发给模型去总结。
|
|
1528
|
-
|
|
1529
|
-
---
|
|
1530
|
-
|
|
1531
|
-
**Q:工具卡住不返回会怎样?**
|
|
1532
|
-
|
|
1533
|
-
默认会一直等——因为**阻塞型工具是被支持的正常用法**:等 IM 消息、盯文件变化、守着一个长任务,这些工具就是要长期不返回。有全局超时反而会把它们全废掉。
|
|
1534
|
-
|
|
1535
|
-
需要超时保护的工具自己在工具文件里声明:
|
|
1536
|
-
|
|
1537
|
-
```js
|
|
1538
|
-
export default {
|
|
1539
|
-
name: 'fetch_page',
|
|
1540
|
-
description: '抓一个网页',
|
|
1541
|
-
timeout: 30000, // 毫秒。超时后工具进程被直接杀掉,模型收到一条超时结果
|
|
1542
|
-
inputSchema: { /* ... */ },
|
|
1543
|
-
async execute(input) { /* ... */ },
|
|
1544
|
-
}
|
|
1545
|
-
```
|
|
1546
|
-
|
|
1547
|
-
`agent.stop()` 任何时候都能立刻掐断,不管工具声没声明超时。
|
|
1548
|
-
|
|
1549
|
-
---
|
|
1550
|
-
|
|
1551
|
-
**Q:工具执行失败会让 Agent 崩溃吗?**
|
|
1552
|
-
|
|
1553
|
-
不会。工具失败会被捕获,错误信息会作为工具结果告诉模型,模型可以自行决定是否重试或换一种方式。
|
|
1554
|
-
|
|
1555
|
-
这条覆盖得相当彻底:工具自己抛错、工具文件语法错误、工具返回了没法序列化的值(循环引用、函数、类实例)、
|
|
1556
|
-
`toModelOutput` 自己抛错、甚至工具调 `process.exit` 把整个工具进程干掉——
|
|
1557
|
-
全都会变成一条模型能读的工具结果,而不是让这次调用永远挂着。
|
|
1558
|
-
|
|
1559
|
-
---
|
|
1560
|
-
|
|
1561
|
-
**Q:多个工具是串行还是并行执行的?**
|
|
1562
|
-
|
|
1563
|
-
并行。模型在一轮里要求调用多个工具时,所有工具同时开跑,结果按原顺序收集后一起写回历史。
|
|
1564
|
-
|
|
1565
|
-
同一个 Agent 内,**文件工具**同时最多跑 `config.maxToolConcurrency` 个(默认不限制,一个工具独占一个工具进程),超出的排队。模型偶尔会一轮返回几十个工具调用,建议设一个上限(比如 8)避免瞬间起几十个进程。不同 Agent 各自计算,互不影响。**内存工具(`Agent.tool.adopt` / MCP)在主进程直接跑,不受这个上限约束**——要限它们得在自己的 `execute` 里做。
|
|
1566
|
-
|
|
1567
|
-
注意阻塞型工具会**长期占着名额**:上限设成 8、又有 8 个会话各挂一个 `wait_for_message`,第 9 个会话的任何工具都排不进来。多会话的 bot 要按会话数把这个值调大。
|
|
1568
|
-
|
|
1569
|
-
---
|
|
1570
|
-
|
|
1571
|
-
**Q:怎么让 Agent 在任务完成时自动停止?**
|
|
1572
|
-
|
|
1573
|
-
有两种方式:
|
|
1574
|
-
|
|
1575
|
-
1. 写一个 `finish` 工具,让它 `return { stop: true }`,并在系统提示词里告诉模型"完成任务时调用 finish 工具"。
|
|
1576
|
-
2. 不写 finish 工具,依赖默认行为:有工具时模型连续 `noToolRounds` 轮(默认 3,最后一轮请求前会插一次提醒)不调用任何工具,Loop 自动返回 `{ reason: 'no-tool' }`。想让模型一不调工具就结束,设 `noToolRounds: 1`。
|
|
1577
|
-
|
|
1578
|
-
---
|
|
1579
|
-
|
|
1580
|
-
**Q:怎么中途停止 Agent?**
|
|
1581
|
-
|
|
1582
|
-
```js
|
|
1583
|
-
const runPromise = agent.send({ input: '...' })
|
|
1584
|
-
|
|
1585
|
-
// 3 秒后强制停止
|
|
1586
|
-
setTimeout(() => agent.stop(), 3000)
|
|
1587
|
-
|
|
1588
|
-
await runPromise.catch(() => {}) // stop() 会让 send() 以 AbortError 结束
|
|
1589
|
-
```
|
|
1590
|
-
|
|
1591
|
-
或者在 `onPermission` 回调里返回 `false` 拒绝某次工具调用,但不会停止整个循环。
|
|
366
|
+
- **不保存对话。** `history` 就是内存里的数组,存库、按用户隔离由宿主做(`onStep` 是落盘的好时机)。
|
|
367
|
+
- **不管插件和技能。** 插件 → 路径的映射、开关、渲染都在宿主;核心只看路径,结果里带 `path` 方便宿主分发。
|
|
368
|
+
- **不算钱。** `usage` 是原始 token 数。
|
|
369
|
+
- **不做用户、权限和沙箱。** 只有 `onPermission` 一个挂钩点。
|
|
370
|
+
- **不管并发排队和限流。** 一个实例就是一段对话;要多段对话就建多个实例。
|
|
371
|
+
- **不支持 Node.js。** 子进程、IPC、打包都依赖 Bun。
|