@kernel4632/agent-core 0.24.18 → 0.26.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 CHANGED
@@ -641,18 +641,47 @@ import Agent from '@kernel4632/agent-core'
641
641
  | `mediaFallback` | `'error'` | 媒体能力关闭时的处理方式;改成 `'strip'` 后保留文字并丢掉不支持的媒体 |
642
642
  | `provider` | `{}` | AI SDK 的生成参数,整份交给 AI SDK;不设时用模型自己的默认值 |
643
643
  | `maxToolOutput` | `undefined` | 默认不截断工具输出;主动设置后超出部分从中间截断并告知模型 |
644
- | `maxTokens` | `128000` | 上下文预算,**默认开启自动压缩**:估算的上下文超过预算的 `compactThreshold` 比例时就压缩一次。设 `Infinity` 关闭。注意区别于 `provider.maxOutputTokens`(那是单次生成上限) |
644
+ | `maxContextTokens` | `128000` | 上下文预算,**默认开启自动压缩**:估算的上下文超过预算的 `compactThreshold` 比例时就压缩一次。设 `Infinity` 关闭 |
645
+ | `maxTokens` | `undefined` | 单次生成的最大输出 token,映射到请求体的 `maxOutputTokens`;不设=不限。`provider.maxOutputTokens` 显式设置时优先于它 |
645
646
  | `compactThreshold` | `0.8` | 压缩触发比例,0.8 表示到达 80% 时压缩 |
646
647
  | `compact` | `undefined` | 压缩单独用一套模型时写在这里,例如 `{ model: '便宜的小模型' }`;不写就和主模型共用 |
647
648
  | `output` | `undefined` | 结构化输出格式,例如 `Agent.output.object({ schema })`;不写就返回普通文字 |
648
649
  | `maxSteps` | `undefined` | 默认不限制模型轮数;主动设置正整数后,到上限先保存这一轮的工具结果,再返回 `step-limit` |
649
650
  | `maxToolConcurrency` | `undefined` | 默认不限制**文件工具**的并发;主动设置后超出的排队。内存工具(`Agent.tool.adopt` / MCP)在主进程直接跑,不受这个上限约束 |
650
- | `retryMaxDelay` | `undefined` | 默认不限制单次退避时间;主动设置后限制毫秒数 |
651
- | `retryMaxElapsed` | `undefined` | 默认不限制重试总时长;主动设置后到点把错误交给上层(毫秒) |
651
+ | `retryBaseDelay` | `5000` | 第一次退避的基数(毫秒),之后每次 ×2:5s、10s、20s…(照抄 Roo Code) |
652
+ | `retryMaxDelay` | `600000` | 单次退避上限(毫秒),到顶就按这个值等待、不再增长(默认 10 分钟,照抄 Roo Code) |
653
+ | `retryMaxElapsed` | `undefined` | 默认不限重试总时长;主动设置毫秒数后,到点把错误交给上层 |
654
+ | `retry` | `undefined` | 调用方过滤不想重试的错误,见下方「重试规则」。不设=默认全重试 |
652
655
  | `requestTimeout` | `undefined` | 默认不限制单笔请求时长;主动设置毫秒数后,卡住的一笔会被中断 |
653
656
  | `noToolPrompt` | 一条"请继续使用工具"的提醒 | 有工具但模型连续不调时,在结束前一轮临时发给模型;只挂在那一次请求上,不写进 `history`。设成 `''` 就不提醒 |
654
657
  | `noToolRounds` | `3` | 有工具时,连续多少轮不调工具就结束一次 `send`;设成 `1` 就是模型不调工具即结束,设成 `Infinity` 就永不因不调工具结束。没注册工具时一轮就结束,不受它影响 |
655
658
 
659
+ ### 重试规则
660
+
661
+ 失败的重试由底层统一处理,默认行为照抄 Roo Code:**除"取消"和"上下文超长"外,任何错误都会重试**(401、400、格式错误都算),次数不限,也不设总时长上限;退避按 `retryBaseDelay × 2` 增长,单次最长到 `retryMaxDelay` 封顶。上下文超长不走重试,而是先压缩上下文再重发这笔请求,最多 3 次。取消(`agent.stop()` 或传 `signal`)永远不重试。
662
+
663
+ 想收口或过滤,用三个配置:
664
+
665
+ ```js
666
+ const agent = Agent.create({
667
+ config: {
668
+ retryBaseDelay: 5000, // 第一次等待 5s,之后 10s、20s…(默认)
669
+ retryMaxDelay: 600000, // 单次等待最多 10 分钟(默认)
670
+ retryMaxElapsed: 120000, // 一直失败最多再试 2 分钟,到点把错误交给上层(默认不限)
671
+ // 只对"不想重试的错误"下手,命中即不重试:
672
+ retry: {
673
+ skipCodes: [400, 401], // 按状态码
674
+ skipKinds: ['auth'], // 按 error.kind:aborted/auth/limit/timeout/server/network/request/unknown
675
+ skipText: /invalid api key/i, // 按报错文字(字符串或正则)
676
+ shouldRetry: error => error.statusCode !== 422, // 自定义判断,返回 false=不重试
677
+ },
678
+ // retry 也可以直接传一个函数:(error) => boolean,返回 false=不重试
679
+ },
680
+ })
681
+ ```
682
+
683
+ `retry` 属于 **整份替换**(和 `provider` 一样,本次传了就用本次的整份,不与上次合并)。
684
+
656
685
  陌生中转站建议先使用默认能力。遇到只支持文字、但接口声称兼容 OpenAI 的模型,可以按能力关闭:
657
686
 
658
687
  ```js
@@ -688,7 +717,7 @@ const agent = Agent.create({
688
717
  })
689
718
  ```
690
719
 
691
- 在 `agent.send({ input, config: { ... } })` 里传入的配置会**写回 Agent**、之后的 send 继续生效。合并规则分三种:`provider` **整份替换**(传了就只用新的,未写的字段不再保留);`capabilities` 和 `compact` **按字段浅合并**(只传其中一项不丢另外的);其余字段直接覆盖。`maxTokens` 是上下文预算,和 `provider.maxOutputTokens`(单次生成量)不是一回事。
720
+ 在 `agent.send({ input, config: { ... } })` 里传入的配置会**写回 Agent**、之后的 send 继续生效。合并规则分三种:`provider` 和 `retry` **整份替换**(传了就只用新的,未写的字段不再保留);`capabilities` 和 `compact` **按字段浅合并**(只传其中一项不丢另外的);其余字段直接覆盖。`maxContextTokens` 是上下文预算,`maxTokens` 是单次生成的最大输出(会映射成请求体的 `maxOutputTokens`),两者不是一回事。
692
721
 
693
722
  `cache` 默认开启。四种协议各按自己的方式让服务端复用固定的开头(system、工具描述、历史),命中后那部分不再重新计算,长会话能明显变快、变便宜:
694
723
 
@@ -885,7 +914,7 @@ app.get('/chat', async request => {
885
914
 
886
915
  要取消某次运行,给 `send` 传 `signal`(如 `request.signal`)或调用 `agent.stop()`,两者都能终止。
887
916
 
888
- 模型请求失败时抛出的错误带一个稳定的 `kind`:`aborted`(用户取消)、`auth`(密钥或权限,401/403)、`limit`(限流,429)、`timeout`(单笔超时或 408)、`server`(5xx)、`network`(没连上)、`request`(其余 4xx)、`unknown`(服务返回成功状态码,但回答格式对不上,常见于不完全兼容的中转站)。上层靠它决定该换模型、该等一下还是该直接报错,不用去认 AI SDK 的内部错误形状。`kind` 只补充信息,能不能重试仍然只由错误自己的 `isRetryable` 决定。
917
+ 模型请求失败时抛出的错误带一个稳定的 `kind`:`aborted`(用户取消)、`auth`(密钥或权限,401/403)、`limit`(限流,429)、`timeout`(单笔超时或 408)、`server`(5xx)、`network`(没连上)、`request`(其余 4xx)、`unknown`(服务返回成功状态码,但回答格式对不上,常见于不完全兼容的中转站)。上层靠它决定该换模型、该等一下还是该直接报错,不用去认 AI SDK 的内部错误形状。`kind` 只补充信息;能不能重试由 Retry 的规则统一决定(见上方「重试规则」),默认除取消和上下文超长外都重试,调用方可用 `retry` 过滤。
889
918
 
890
919
  #### `agent.compact(options?)`
891
920
 
@@ -957,7 +986,28 @@ Agent.tool.adopt(await mcpClient.tools())
957
986
 
958
987
  `inputSchema` 可以是裸 JSON Schema、zod,或 AI SDK 的 `jsonSchema()`。`execute(input, { abortSignal })` 会收到取消信号(也接受别名 `signal`)。
959
988
 
960
- 文件工具和内存工具可以合并:`Agent.tool.merge(await Agent.tool.scan('./tools'), Agent.tool.adopt(mcpTools))`,或者直接用 `Agent.tool.from('./tools', mcpTools)`(见上)。
989
+ 文件工具和内存工具可以合并:`Agent.tool.merge(await Agent.tool.scan('./tools'), Agent.tool.adopt(mcpTools))`,或者直接用 `Agent.tool.from('./tools', mcpTools)`(见上)。想从集合里取子集,用 `pick` / `omit`:
990
+
991
+ ```js
992
+ const readonly = Agent.tool.pick(tools, ['read', 'glob']) // 只留这两个工具
993
+ const safe = Agent.tool.omit(tools, ['shell', 'write']) // 去掉这些,其余全留
994
+ const agent = Agent.create({ config, tools: safe })
995
+ ```
996
+
997
+ `pick` / `omit` 的 `names` 是字符串数组,`schema` 和 `handlers` 会**一起筛**,不会出现"模型看不见、却还能被执行"的隐蔽状态。返回的是新集合,可以直接交给 `create` / `send` / `merge`,也可以继续 `pick` / `omit`。空集合或 `undefined` 集合也安全(返回空集合)。
998
+
999
+ #### 工具集合里有什么
1000
+
1001
+ `scan` / `adopt` / `merge` / `pick` / `omit` 都返回同一种 `{ schema, handlers }`,里面的东西:
1002
+
1003
+ | 位置 | 是什么 |
1004
+ |------|--------|
1005
+ | `schema[name].name` | 工具名 |
1006
+ | `schema[name].description` | 给模型看的工具说明 |
1007
+ | `schema[name].inputSchema` | **已编译的校验器**(AI SDK 的 `jsonSchema()` 形态);原始 JSON Schema 在 `inputSchema.jsonSchema` 里 |
1008
+ | `handlers[name]` | 执行器内部形状(文件工具是 `url`,内存工具是 `execute` 等);**不要自己构造**,原样传回 `merge` / `pick` / `omit` 或 `Agent.tool.execute` |
1009
+
1010
+ 工具对象上的额外字段会被 `scan` / `adopt` 原样带进 `schema[name]`:比如工具自己声明 `touchesFiles: ['path']`,应用层就能从 `tools.schema[name].touchesFiles` 读到。注意 `schema` 是发给模型的那一份,别把不想让模型看到的内部标记放进去(`execute`、`toModelOutput`、`timeout` 不会被带进去,它们只留在 `handlers`)。
961
1011
 
962
1012
  **MCP 工具直接可用,不需要包装**:`@ai-sdk/mcp` 的 `client.tools()` 自带 `execute` 和 `toModelOutput`,核心按 AI SDK 的签名调用它们,文字、图片都会正确交给模型。完整接入例子见前面的[「接入 MCP 和技能」](#接入-mcp-和技能)。
963
1013
 
@@ -967,11 +1017,13 @@ Agent.tool.adopt(await mcpClient.tools())
967
1017
  >
968
1018
  > 从 0.19 升级:`onPermission` 的 `arguments` 字段改名为 `input`;结束原因多了一个 `'finished'`(没注册工具、或结构化输出已校验成功,原先是 `'no-tool'`)。工具对象的 `execute(input, { abortSignal })`、`toModelOutput({ output, input })` 现在按 AI SDK 签名调用。
969
1019
  >
970
- > 从 0.21 升级:去掉了 `gpt-tokenizer`,上下文 token 改用**自校准估算**(字符数 × 每字符 token 比,比例由真实 `usage` 学到,跟着模型走);`maxTokens` 默认变为 `128000`,**自动压缩默认开启**(想关掉设 `maxTokens: Infinity`)。产物从 ~3.9 MB 降到 ~1.3 MB。
1020
+ > 从 0.21 升级:去掉了 `gpt-tokenizer`,上下文 token 改用**自校准估算**(字符数 × 每字符 token 比,比例由真实 `usage` 学到,跟着模型走);`maxContextTokens` 默认变为 `128000`,**自动压缩默认开启**(想关掉设 `maxContextTokens: Infinity`)。产物从 ~3.9 MB 降到 ~1.3 MB。
971
1021
  >
972
- > 从 0.22 升级:内存工具声明的 `timeout` 现在真的生效;新增 `capabilities.usage`(关掉流式请求里的 `include_usage`);`compactThreshold`、字符串型 `maxTokens` 等非法配置现在会在 `send` 入口报错。
1022
+ > 从 0.22 升级:内存工具声明的 `timeout` 现在真的生效;新增 `capabilities.usage`(关掉流式请求里的 `include_usage`);`compactThreshold`、字符串型 `maxContextTokens` 等非法配置现在会在 `send` 入口报错。
973
1023
  >
974
1024
  > 从 0.23 升级:内存工具(`Agent.tool.adopt`)现在也支持 `async *execute` 流式输出,和文件工具一致;`Tool.from` 接受一组目录(字符串数组);取消错误统一带 `error.kind === 'aborted'`。
1025
+ >
1026
+ > 从 0.25 升级(破坏性改名):上下文预算 `maxTokens` 改名为 **`maxContextTokens`**;`maxTokens` 现在指**单次生成的最大输出** token(映射到请求体的 `maxOutputTokens`)。这是把名字拨回 OpenAI / Anthropic 的习惯(它们的 `max_tokens` 就是输出上限,不是上下文)。另外:`onPermission` 现在要求**严格返回布尔**——非 `true`(含对象、漏 `return`)一律按拒绝处理;新增 `Agent.tool.pick` / `Agent.tool.omit` 用来取工具子集(做只读模式用 `omit` 去掉写工具)。
975
1027
 
976
1028
  #### `Agent.tool.execute(options)`
977
1029
 
@@ -1012,7 +1064,7 @@ console.log(output.total)
1012
1064
 
1013
1065
  `Agent.output` 是包内 AI SDK 的 Output,`Agent.schema` 是包内 Zod,无需另装一套。数组可用 `Agent.output.array({ element: Agent.schema.string() })`,普通 JSON 可用 `Agent.output.json()`。所选模型服务须支持对应输出格式。
1014
1066
 
1015
- 有工具时先完成工具调用,再读取最终对象。工具轮、`tool-stop` 或轮数用尽不会凭空产生 `output`。最终对象校验成功立即结束;格式错误直接抛出,不当成网络故障无限重试。手动及自动压缩只生成文本总结,不继承任务的对象格式。流式和非流式都在最终结果上提供 `output`;流中仍会有生成时的文字片段。
1067
+ 有工具时先完成工具调用,再读取最终对象。工具轮、`tool-stop` 或轮数用尽不会凭空产生 `output`。最终对象校验成功立即结束;格式错误默认也会重试(重新生成不保证还是坏的),想让它立刻失败可用 `retry` 过滤或收紧 `retryMaxElapsed`。手动及自动压缩只生成文本总结,不继承任务的对象格式。流式和非流式都在最终结果上提供 `output`;流中仍会有生成时的文字片段。
1016
1068
 
1017
1069
  直接使用底层 LLM,绕过 Agent 循环。
1018
1070
 
@@ -1111,8 +1163,8 @@ History.turns(agent.history) // 折成回合:[[user], [assistant, tool], [us
1111
1163
  | `maxToolOutput` | 不截断 | 工具输出不截断有 31 万 token 风险:一个 1MB 的文本(`cat` 一个日志文件)就够,超过多数模型的整个窗口,还会永久留在历史里,压缩也救不回来。设个字符数,比如 `32000`。 |
1112
1164
  | `maxToolConcurrency` | 不限制 | 默认不限文件工具并发:模型偶尔一轮返回几十个工具调用,会瞬间起几十个进程。设个上限,比如 `8`。 |
1113
1165
  | `requestTimeout` | 不限制 | 默认不限单笔时长:卡住的请求会一直等下去。设毫秒数,到点中断这一笔。 |
1114
- | `retryMaxElapsed` | 不限制 | 默认不限重试总时长,等于无限重试。设毫秒数,到点把错误交给上层。 |
1115
- | `maxTokens` | `128000` | 上下文预算,要按你模型的窗口调。比窗口大会撑爆,比需求小会频繁压缩。 |
1166
+ | `retryMaxElapsed` | 不限制 | 默认重试所有错误且无总上限,等于无限重试。生产建议设毫秒数收口,或用 `retry` 过滤掉不该重试的错误(如 `auth`、`request`)。 |
1167
+ | `maxContextTokens` | `128000` | 上下文预算,要按你模型的窗口调。比窗口大会撑爆,比需求小会频繁压缩。 |
1116
1168
 
1117
1169
  ## 可观测性
1118
1170
 
@@ -1216,7 +1268,7 @@ const agent = Agent.create({ config: { /* ... */ }, tools })
1216
1268
  |---|---|
1217
1269
  | `Agent.version` | 包版本,排查问题时报得出来 |
1218
1270
  | `Agent.create(...)` | 创建 Agent 实例 |
1219
- | `Agent.tool` | `.from()` / `.scan()` / `.adopt()` / `.execute()` / `.merge()` |
1271
+ | `Agent.tool` | `.from()` / `.scan()` / `.adopt()` / `.execute()` / `.merge()` / `.pick()` / `.omit()` |
1220
1272
  | `Agent.history` | `.user()` / `.assistant()` / `.tool()` / `.compact()` 造消息块;`.turns()` / `.render()` 读历史 |
1221
1273
  | `Agent.context` | `.build()` |
1222
1274
  | `Agent.compact` | `.run()` |
@@ -1288,7 +1340,7 @@ const agent = Agent.create({ config: { /* ... */ }, tools })
1288
1340
 
1289
1341
  **Q:上下文太长会怎样?**
1290
1342
 
1291
- 上下文超过 `config.maxTokens` 的 `compactThreshold`(默认 0.8,即 80%)时,Loop 会自动调用 Compact 把历史压缩成一段总结,然后继续运行。**默认就开着**:`maxTokens` 默认 `128000`,不配置也会在接近上限时自动压缩,避免把上下文撑爆。你的模型窗口比这小就把它调小;想彻底关掉设 `maxTokens: Infinity`。
1343
+ 上下文超过 `config.maxContextTokens` 的 `compactThreshold`(默认 0.8,即 80%)时,Loop 会自动调用 Compact 把历史压缩成一段总结,然后继续运行。**默认就开着**:`maxContextTokens` 默认 `128000`,不配置也会在接近上限时自动压缩,避免把上下文撑爆。你的模型窗口比这小就把它调小;想彻底关掉设 `maxContextTokens: Infinity`。
1292
1344
 
1293
1345
  **上下文 token 怎么估**:不装分词器,用"字符数 × 每字符多少 token"。这个比例是**会自校准**的——每轮模型都会回 `usage.inputTokens`(这次请求真实的输入 token 数),拿它反推这个模型真实的"每字符 token 比"记下来给下一轮。换模型(`config.compact` 的压缩模型、`send` 时覆盖 `model`、换 provider)就换一条记录,越用越准,也不怕分词器对不上模型。
1294
1346
 
@@ -1305,7 +1357,7 @@ config: {
1305
1357
 
1306
1358
  不写 `compact` 就和主模型共用。自动压缩和手动 `agent.compact()` 用的都是这一套。
1307
1359
 
1308
- > 用更小的小模型做压缩时注意:那笔压缩请求的**大小是由主模型的 `maxTokens` 决定的**,跟压缩模型自己的窗口无关。如果压缩模型的窗口比主模型预算小,压缩请求会先在小模型这边撑爆。让压缩模型的窗口 ≥ 主模型预算,或把 `maxTokens` 调小。
1360
+ > 用更小的小模型做压缩时注意:那笔压缩请求的**大小是由主模型的 `maxContextTokens` 决定的**,跟压缩模型自己的窗口无关。如果压缩模型的窗口比主模型预算小,压缩请求会先在小模型这边撑爆。让压缩模型的窗口 ≥ 主模型预算,或把 `maxContextTokens` 调小。
1309
1361
 
1310
1362
  **最新的那条总结会折进 `system`,而不是当成一条用户消息塞进对话里**,并且带一句"这是你自己之前做过的工作,数据已由工具确认"。裸的 `role:'user'` 总结会被模型读成"用户塞给我一张表",于是它从头重做整个任务——真实端点实测 `gpt-oss-120b` 改之前 1/6 能正确续跑,改之后 6/6。
1311
1363
 
@@ -29,6 +29,17 @@ export interface Capabilities {
29
29
 
30
30
  export type CacheOption = boolean | { key?: string; retention?: string; body?: Record<string, unknown> }
31
31
 
32
+ // 重试过滤:函数直接对错误下判断(返回 false=不重试);
33
+ // 对象命中任一 skip 维度、或 shouldRetry 返回 false 时不重试。
34
+ export type RetryFilter =
35
+ | ((error: any) => boolean)
36
+ | {
37
+ skipCodes?: number[]
38
+ skipText?: string | RegExp
39
+ skipKinds?: string[]
40
+ shouldRetry?: (error: any) => boolean
41
+ }
42
+
32
43
  export interface Config {
33
44
  baseURL?: string
34
45
  apiKey?: string
@@ -42,14 +53,17 @@ export interface Config {
42
53
  mediaFallback?: 'error' | 'strip'
43
54
  provider?: Record<string, any>
44
55
  maxToolOutput?: number
45
- maxTokens?: number
56
+ maxTokens?: number // 单次生成的最大输出 token,映射到请求体的 maxOutputTokens;不设=不限。provider.maxOutputTokens 显式设置时优先。
57
+ maxContextTokens?: number // 上下文预算;估算的上下文达到它的 compactThreshold 比例时自动压缩。默认 128000,设 Infinity 关闭自动压缩。
46
58
  compactThreshold?: number
47
59
  compact?: Partial<Config>
48
60
  output?: any
49
61
  maxSteps?: number
50
62
  maxToolConcurrency?: number
63
+ retryBaseDelay?: number
51
64
  retryMaxDelay?: number
52
65
  retryMaxElapsed?: number
66
+ retry?: RetryFilter
53
67
  requestTimeout?: number
54
68
  noToolPrompt?: string
55
69
  noToolRounds?: number
@@ -90,10 +104,10 @@ export interface Callbacks {
90
104
  onCompact?: (event: any) => void | Promise<void>
91
105
  }
92
106
 
93
- // --- 工具集合:scan / adopt / merge 都返回这个形状 ---
107
+ // --- 工具集合:scan / adopt / merge / pick / omit 都返回这个形状 ---
94
108
  export interface ToolSet {
95
- schema: Record<string, any>
96
- handlers: Record<string, any>
109
+ schema: Record<string, { name?: string; description?: string; inputSchema?: any; [key: string]: any }>
110
+ handlers: Record<string, any> // 执行器内部形状,不要自己构造,原样传回 merge/pick/omit
97
111
  }
98
112
 
99
113
  // 内存工具对象的形状(AI SDK tool() 产物、MCP client.tools() 的单项都符合这个形状)
@@ -133,6 +147,8 @@ export interface ToolModule {
133
147
  concurrency?: number
134
148
  }) => Promise<{ output: any; stop?: boolean; error?: string; interrupted?: boolean }>
135
149
  merge: (...sets: ToolSet[]) => ToolSet
150
+ pick: (set: ToolSet, names: string[]) => ToolSet
151
+ omit: (set: ToolSet, names: string[]) => ToolSet
136
152
  }
137
153
 
138
154
  // --- 历史块 ---