@kernel4632/agent-core 0.27.0 → 0.30.4
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 +36 -13
- package/dist/agent-core.d.ts +5 -3
- package/dist/agent-core.js +86 -86
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
|
|
1
|
+
# @kernel4632/agent-core
|
|
2
2
|
|
|
3
3
|
[](https://github.com/kernel4632/agent-core/actions/workflows/ci.yml)
|
|
4
4
|
[](https://github.com/kernel4632/agent-core/releases/latest)
|
|
@@ -64,18 +64,17 @@ flowchart TD
|
|
|
64
64
|
D --> E["结果写回 history"]
|
|
65
65
|
E --> S{"有工具返回<br/>stop:true?"}
|
|
66
66
|
S -->|是| T1["返回 tool-stop"]
|
|
67
|
-
S -->|否|
|
|
68
|
-
T2 -->|是| T3["返回 step-limit"]
|
|
69
|
-
T2 -->|否| A
|
|
67
|
+
S -->|否| A
|
|
70
68
|
|
|
71
69
|
C -->|不要| F{"结束判定"}
|
|
72
70
|
F -->|结构化输出成功<br/>或没注册工具| R1["返回 finished"]
|
|
73
|
-
F -->|步数到 maxSteps| T3
|
|
74
71
|
F -->|连续不调工具<br/>达 noToolRounds| R2["返回 no-tool"]
|
|
75
72
|
F -->|还没到| P["继续下一轮<br/>(末轮前插一句提醒)"]
|
|
76
73
|
P --> A
|
|
77
74
|
```
|
|
78
75
|
|
|
76
|
+
没有"最大轮数"这种上限:**什么时候停由模型的判断和工具的结果决定**,不由一个写死的步数决定。这个包只在你取消、模型报错、或两种正常收尾时结束。
|
|
77
|
+
|
|
79
78
|
**① 模型不调工具,不会立刻结束。** 很多模型在任务没做完时会"礼貌地"给一段总结就停下。直接结束会把没干完的活丢掉。所以有工具时,模型不调工具会先**临时**插一句提醒(`noToolPrompt`)再问一次,连续 `noToolRounds` 轮(默认 3)都不调才结束。这句提醒只挂在那一次请求上,**不写进 `history`**。不想要这个行为,把 `noToolRounds` 设成 `Infinity`。
|
|
80
79
|
|
|
81
80
|
**② `history` 是唯一的权威数据来源,只增不删。** 循环从不修改历史,模型消息、工具结果按发生的顺序追加。连压缩也只追加一条总结。原因:`history` 归你的应用所有(存库、渲染、多会话),核心替它丢弃数据是不可逆的错误——该留多少由持有它的你决定。
|
|
@@ -375,7 +374,7 @@ const agent = Agent.create({ config: { ...config, system: ['你是一个助手
|
|
|
375
374
|
├── notify.js ← 所有回调的统一出口
|
|
376
375
|
├── schema.js ← 工具参数格式归一化(scan 和 adopt 共用)
|
|
377
376
|
├── shape.js ← 工具返回值变成输出块(内存工具用;子进程里有一份副本)
|
|
378
|
-
└── tokens.js ← 上下文 token
|
|
377
|
+
└── tokens.js ← 上下文 token 估算:文字按字符数 × 每字符 token 比(比例由真实 usage 自校准),媒体按块计
|
|
379
378
|
```
|
|
380
379
|
|
|
381
380
|
`tool.js` 和 `tool-process.js` 是同一件事的两半,所以放在一起:前者在主线程里找工具、管工具进程,
|
|
@@ -654,7 +653,6 @@ import Agent from '@kernel4632/agent-core'
|
|
|
654
653
|
| `compactThreshold` | `0.8` | 压缩触发比例,0.8 表示到达 80% 时压缩 |
|
|
655
654
|
| `compact` | `undefined` | 压缩单独用一套模型时写在这里,例如 `{ model: '便宜的小模型' }`;不写就和主模型共用 |
|
|
656
655
|
| `output` | `undefined` | 结构化输出格式,例如 `Agent.output.object({ schema })`;不写就返回普通文字 |
|
|
657
|
-
| `maxSteps` | `undefined` | 默认不限制模型轮数;主动设置正整数后,到上限先保存这一轮的工具结果,再返回 `step-limit` |
|
|
658
656
|
| `maxToolConcurrency` | `undefined` | 默认不限制**文件工具**的并发;主动设置后超出的排队。内存工具(`Agent.tool.adopt` / MCP)在主进程直接跑,不受这个上限约束 |
|
|
659
657
|
| `retryBaseDelay` | `5000` | 第一次退避的基数(毫秒),之后每次 ×2:5s、10s、20s…(照抄 Roo Code) |
|
|
660
658
|
| `retryMaxDelay` | `600000` | 单次退避上限(毫秒),到顶就按这个值等待、不再增长(默认 10 分钟,照抄 Roo Code) |
|
|
@@ -725,7 +723,7 @@ const agent = Agent.create({
|
|
|
725
723
|
})
|
|
726
724
|
```
|
|
727
725
|
|
|
728
|
-
在 `agent.send({ input, config: { ... } })` 里传入的配置会**写回 Agent
|
|
726
|
+
在 `agent.send({ input, config: { ... } })` 里传入的配置会**写回 Agent**、之后的每一次模型请求继续生效(包括正在跑的这一轮的下一笔,见下方「每轮现拼」)。合并规则分三种:`provider` 和 `retry` **整份替换**(传了就只用新的,未写的字段不再保留);`capabilities` 和 `compact` **按字段浅合并**(只传其中一项不丢另外的);其余字段直接覆盖。`maxContextTokens` 是上下文预算,`maxTokens` 是单次生成的最大输出(会映射成请求体的 `maxOutputTokens`),两者不是一回事。
|
|
729
727
|
|
|
730
728
|
`cache` 默认开启。四种协议各按自己的方式让服务端复用固定的开头(system、工具描述、历史),命中后那部分不再重新计算,长会话能明显变快、变便宜:
|
|
731
729
|
|
|
@@ -819,7 +817,7 @@ await agent.send('继续')
|
|
|
819
817
|
|
|
820
818
|
const result = await agent.send({
|
|
821
819
|
input: '帮我写个函数', // 用户输入(必填)。也可以是内容块数组,见下方"发图片"
|
|
822
|
-
config: { model: '新模型' }, // 可选:覆盖部分配置(会写回 Agent
|
|
820
|
+
config: { model: '新模型' }, // 可选:覆盖部分配置(会写回 Agent,之后的每一次模型请求继续生效)
|
|
823
821
|
history: [], // 可选:整份替换历史(也写回 Agent)
|
|
824
822
|
tools: newTools, // 可选:整份替换工具集(也写回 Agent)
|
|
825
823
|
callbacks: { onLLMEvent: e => {} }, // 可选:合并回调(逐项写回 Agent,最后传的长期生效)
|
|
@@ -837,7 +835,6 @@ const result = await agent.send({
|
|
|
837
835
|
// 'finished' → 没注册工具,或结构化输出已校验成功:这就是最终回答
|
|
838
836
|
// 'no-tool' → 有工具,但连续 noToolRounds 轮(默认 3)没调用工具才结束
|
|
839
837
|
// 'tool-stop' → 某个工具返回了 stop: true
|
|
840
|
-
// 'step-limit' → 达到 maxSteps,当前工具结果已保存,下一次 send 可继续
|
|
841
838
|
```
|
|
842
839
|
|
|
843
840
|
`send` 的出错方式只有一种:返回的 Promise 拒绝。空输入、非法配置、取消、模型报错全都从这里出来,所以只需要写 `.catch()`,不用另外包同步的 `try/catch`。取消造成的拒绝带 `error.kind === 'aborted'`;模型报错的 `error.kind` 见下方。
|
|
@@ -867,7 +864,27 @@ await agent.send({
|
|
|
867
864
|
|
|
868
865
|
能不能看懂取决于模型本身。实测 `kimi-k2.6` 可以,`gpt-oss-120b` 没有视觉能力、会直接报 `content must be a string`——是大声失败,不是静默忽略。
|
|
869
866
|
|
|
870
|
-
> 直接 `send`
|
|
867
|
+
> 直接 `send` 的内容块会在入口校验:`text` / `image` / `audio` / `video` / `file` 这些块形状不对(比如媒体缺 `mediaType`、值不是字符串 / URL / 二进制)会当场拒绝,不会写进只增不删的历史。图片块用 `{ type: 'image', image: <data URL 或 base64 或 URL 对象> }`,或 AI SDK 当前的 `{ type: 'file', mediaType, data }`。
|
|
868
|
+
|
|
869
|
+
#### 每轮现拼:运行中改什么,下一笔请求就生效
|
|
870
|
+
|
|
871
|
+
每发一笔模型请求之前,Loop 都会重新从宿主那里取一遍这次请求要用的全部东西——配置、`system`、工具表,再重新拼出这一轮的上下文和请求。具体到代码就一句话:`agent` 是活对象,Loop 每轮重新读一次 `agent.config` 和 `agent.tools`,不是 `send` 开始时留一份副本。所以一次 `send` 还在跑的时候改它们,下一笔请求就用新值:不用停掉当前任务,也不用重建 Agent。
|
|
872
|
+
|
|
873
|
+
```js
|
|
874
|
+
// 在 onStep / onLLMFinish 里改都行:当前这笔请求和它发起的工具已经跑完
|
|
875
|
+
agent.config.model = '新的模型'
|
|
876
|
+
agent.config.provider = { ...agent.config.provider, temperature: 0.2 }
|
|
877
|
+
agent.config.system = '新的系统提示'
|
|
878
|
+
agent.tools = Agent.tool.omit(agent.tools, ['shell']) // 运行中撤掉一个工具,下一笔请求就不带它
|
|
879
|
+
```
|
|
880
|
+
|
|
881
|
+
- **什么时候切换**:只在请求边界。已经发出去的那一笔不会被打断,它发起的工具也照常跑完;下一轮请求模型时才换。流式过程中不会热替换。
|
|
882
|
+
- **每轮都会重新取的**:连接(`baseURL` / `apiKey` / `model` / `protocol`)、`provider` 里的生成参数(温度、思考强度等)、`capabilities` / `mediaFallback`、`cache`、`retry` / `requestTimeout`、`maxTokens`、`maxContextTokens` / `compactThreshold`、`noToolRounds`、`maxToolOutput` / `maxToolConcurrency`、`system`、工具表;压缩用的 `compact` 配置在压缩发生的那一轮取。token 估算也按新模型重新记。
|
|
883
|
+
- **工具表只读一遍,不重新扫描目录**:把 `agent.tools` 换成新的集合(`Agent.tool.from` / `pick` / `omit` 的返回值)就生效;目录里的文件不会在这次运行中被重新扫描——要重新扫描用新的 `send`(`send({ tools })` 会在开始时现扫)。模型看到的那张表和执行时用的 handler 取自同一份集合。
|
|
884
|
+
- **不随轮次换的只有两样**:`history` 是这次运行的权威数据,循环始终往同一个数组追加;回调是运行期的接线,在 `send` 开始时定下。
|
|
885
|
+
- 按次传的 `send({ config })` 语义不变:写回 `agent.config`,这次运行从第一笔请求起就用它。
|
|
886
|
+
|
|
887
|
+
> 会话运行中改模型 / 思考强度 / system / 工具表,直接改 `agent.config` 和 `agent.tools` 就行:历史、流式输出和运行状态都不中断。
|
|
871
888
|
|
|
872
889
|
#### `agent.stop()`
|
|
873
890
|
|
|
@@ -1052,6 +1069,8 @@ const wrap = (tool, host) => ({ ...tool, execute: (input, options) => tool.execu
|
|
|
1052
1069
|
> 从 0.25 升级(破坏性改名):上下文预算 `maxTokens` 改名为 **`maxContextTokens`**;`maxTokens` 现在指**单次生成的最大输出** token(映射到请求体的 `maxOutputTokens`)。这是把名字拨回 OpenAI / Anthropic 的习惯(它们的 `max_tokens` 就是输出上限,不是上下文)。另外:`onPermission` 现在要求**严格返回布尔**——非 `true`(含对象、漏 `return`)一律按拒绝处理;新增 `Agent.tool.pick` / `Agent.tool.omit` 用来取工具子集(做只读模式用 `omit` 去掉写工具)。
|
|
1053
1070
|
>
|
|
1054
1071
|
> 从 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`(取消即杀进程不变,信号仅供工具优雅收尾)。
|
|
1072
|
+
>
|
|
1073
|
+
> 从 0.30 升级(破坏性):去掉了 `maxSteps` 和结束原因 `'step-limit'`。这个包**不再限制循环轮数**——什么时候停由模型的判断和工具的结果决定。原来靠 `maxSteps` 兜底的地方,改由应用层控制:给 `send` 传 `signal`、设 `requestTimeout`,或者写一个返回 `stop: true` 的 `finish` 工具。
|
|
1055
1074
|
|
|
1056
1075
|
#### `Agent.tool.execute(options)`
|
|
1057
1076
|
|
|
@@ -1092,7 +1111,7 @@ console.log(output.total)
|
|
|
1092
1111
|
|
|
1093
1112
|
`Agent.output` 是包内 AI SDK 的 Output,`Agent.schema` 是包内 Zod,无需另装一套。数组可用 `Agent.output.array({ element: Agent.schema.string() })`,普通 JSON 可用 `Agent.output.json()`。所选模型服务须支持对应输出格式。
|
|
1094
1113
|
|
|
1095
|
-
|
|
1114
|
+
有工具时先完成工具调用,再读取最终对象。工具轮或 `tool-stop` 不会凭空产生 `output`。最终对象校验成功立即结束;格式错误默认也会重试(重新生成不保证还是坏的),想让它立刻失败可用 `retry` 过滤或收紧 `retryMaxElapsed`。手动及自动压缩只生成文本总结,不继承任务的对象格式。流式和非流式都在最终结果上提供 `output`;流中仍会有生成时的文字片段。
|
|
1096
1115
|
|
|
1097
1116
|
直接使用底层 LLM,绕过 Agent 循环。
|
|
1098
1117
|
|
|
@@ -1137,7 +1156,7 @@ const { messages, token } = Agent.context.build({
|
|
|
1137
1156
|
tools: tools.schema,
|
|
1138
1157
|
})
|
|
1139
1158
|
// messages → 可以直接传给 LLM.chat 的消息数组
|
|
1140
|
-
// token → 估算的 token
|
|
1159
|
+
// token → 估算的 token 数(不装分词器:文字按字符数 × 每字符 token 比,比例由 Loop 从真实 usage 自校准;媒体按块计,不看 base64 长度)
|
|
1141
1160
|
```
|
|
1142
1161
|
|
|
1143
1162
|
裁剪的最小单位是**回合**,不是消息。一个回合 = 模型的一次响应 + 它发起的全部工具调用 + 这些调用的结果,
|
|
@@ -1194,6 +1213,8 @@ History.turns(agent.history) // 折成回合:[[user], [assistant, tool], [us
|
|
|
1194
1213
|
| `retryMaxElapsed` | 不限制 | 默认重试所有错误且无总上限,等于无限重试。生产建议设毫秒数收口,或用 `retry` 过滤掉不该重试的错误(如 `auth`、`request`)。 |
|
|
1195
1214
|
| `maxContextTokens` | `128000` | 上下文预算,要按你模型的窗口调。比窗口大会撑爆,比需求小会频繁压缩。 |
|
|
1196
1215
|
|
|
1216
|
+
**这个包不限制循环轮数。** 循环停不停只由模型的判断、工具的结果(`stop: true`)、取消和报错决定。生产里要兜住"模型一直调工具停不下来",由应用层做:给 `send` 传 `signal`,用你自己的计时器或业务条件取消;或者写一个 `finish` 工具让模型主动收尾。
|
|
1217
|
+
|
|
1197
1218
|
## 可观测性
|
|
1198
1219
|
|
|
1199
1220
|
每一轮里模型花了多久、工具花了多久、什么时候压缩,用现成的回调就能拼出来。它们只是通知,抛错也不影响任务:
|
|
@@ -1372,6 +1393,8 @@ const agent = Agent.create({ config: { /* ... */ }, tools })
|
|
|
1372
1393
|
|
|
1373
1394
|
**上下文 token 怎么估**:不装分词器,用"字符数 × 每字符多少 token"。这个比例是**会自校准**的——每轮模型都会回 `usage.inputTokens`(这次请求真实的输入 token 数),拿它反推这个模型真实的"每字符 token 比"记下来给下一轮。换模型(`config.compact` 的压缩模型、`send` 时覆盖 `model`、换 provider)就换一条记录,越用越准,也不怕分词器对不上模型。
|
|
1374
1395
|
|
|
1396
|
+
**图片 / 音频 / 视频 / 文件不按 base64 字符数算。** 媒体块在 JSON 里可能有几百万字符,但模型为它付的 token 只取决于尺寸和解码方式,所以每块按固定值(`MEDIA_TOKENS`,1200)估,校准时会先把这部分从真实用量里扣掉。不这么做的话,一张截图就能让估算从 14 万跳到 80 万,上下文还很空就触发压缩(实战踩过:JSON 从 100 万字符涨到 4700 万字符)。
|
|
1397
|
+
|
|
1375
1398
|
**压缩只往 `agent.history` 里追加一条总结,永远不删任何东西。** `history` 是唯一权威数据来源,该保留多少由持有它的你来决定——压缩控制的是"这一轮发给模型的内容有多大",不是"历史能留多少"。
|
|
1376
1399
|
|
|
1377
1400
|
**压缩可以另配一套模型。** 总结不需要主模型那么聪明,用便宜的小模型就够,写在 `config.compact` 里:
|
package/dist/agent-core.d.ts
CHANGED
|
@@ -58,7 +58,6 @@ export interface Config {
|
|
|
58
58
|
compactThreshold?: number
|
|
59
59
|
compact?: Partial<Config>
|
|
60
60
|
output?: any
|
|
61
|
-
maxSteps?: number
|
|
62
61
|
maxToolConcurrency?: number
|
|
63
62
|
retryBaseDelay?: number
|
|
64
63
|
retryMaxDelay?: number
|
|
@@ -79,7 +78,7 @@ export interface Usage {
|
|
|
79
78
|
cacheWriteTokens: number
|
|
80
79
|
}
|
|
81
80
|
|
|
82
|
-
export type Reason = 'finished' | 'no-tool' | 'tool-stop'
|
|
81
|
+
export type Reason = 'finished' | 'no-tool' | 'tool-stop'
|
|
83
82
|
|
|
84
83
|
export interface Answer {
|
|
85
84
|
reason: Reason
|
|
@@ -185,7 +184,8 @@ export interface ContextModule {
|
|
|
185
184
|
build: (options: { history: Message[]; system?: string; tools?: Record<string, any>; budget?: number; ratio?: number; capabilities?: Capabilities; mediaFallback?: 'error' | 'strip' }) => { messages: any[]; readonly token: number }
|
|
186
185
|
}
|
|
187
186
|
export interface CompactModule {
|
|
188
|
-
|
|
187
|
+
// 返回总结文本和这一笔压缩请求的用量(0.27 起带 usage:压缩也是真实请求,钱要计进合计)。
|
|
188
|
+
run: (options: Record<string, any>) => Promise<{ content: string; usage: Usage }>
|
|
189
189
|
}
|
|
190
190
|
export interface LLMModule {
|
|
191
191
|
chat: (options: Record<string, any>) => Promise<any>
|
|
@@ -219,7 +219,9 @@ export interface SendOptions {
|
|
|
219
219
|
export interface AgentInstance {
|
|
220
220
|
id: string
|
|
221
221
|
history: Message[]
|
|
222
|
+
// 活配置:每轮请求前重新取一次,运行中改它,下一笔模型请求就用新值(含 system)。
|
|
222
223
|
config: Config
|
|
224
|
+
// 同样每轮现取:运行中换成另一份集合(Tool.from / pick / omit 的返回值),下一笔请求就按新表发。
|
|
223
225
|
tools: ToolSet
|
|
224
226
|
callbacks: Callbacks
|
|
225
227
|
running: { controller: AbortController; task: Promise<Answer | string> } | null // send 时是 Answer;compact 时是总结字符串。
|