@kernel4632/agent-core 0.36.0 → 0.38.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
@@ -660,6 +660,7 @@ import Agent from '@kernel4632/agent-core'
660
660
  | `retryBaseDelay` | `5000` | 第一次退避的基数(毫秒),之后每次 ×2:5s、10s、20s…(照抄 Roo Code) |
661
661
  | `retryMaxDelay` | `600000` | 单次退避上限(毫秒),到顶就按这个值等待、不再增长(默认 10 分钟,照抄 Roo Code) |
662
662
  | `retryMaxElapsed` | `undefined` | 默认不限重试总时长;主动设置毫秒数后,到点把错误交给上层 |
663
+ | `retryMaxTries` | `undefined` | 默认不限重试次数;设 `0` 是一次都不重试,设正整数是最多再重试几次。和 `retryMaxElapsed` 同时设时,谁先到谁停 |
663
664
  | `retry` | `undefined` | 调用方过滤不想重试的错误,见下方「重试规则」。不设=默认全重试 |
664
665
  | `requestTimeout` | `undefined` | 默认不限制单笔请求时长;主动设置毫秒数后,卡住的一笔会被中断 |
665
666
  | `noToolPrompt` | 一条"请继续使用工具"的提醒 | 有工具但模型连续不调时,在结束前一轮临时发给模型;只挂在那一次请求上,不写进 `history`。设成 `''` 就不提醒 |
@@ -670,7 +671,7 @@ import Agent from '@kernel4632/agent-core'
670
671
 
671
672
  失败的重试由底层统一处理,默认行为照抄 Roo Code:**除"取消"和"上下文超长"外,任何错误都会重试**(401、400、格式错误都算),次数不限,也不设总时长上限;退避按 `retryBaseDelay × 2` 增长,单次最长到 `retryMaxDelay` 封顶。上下文超长不走重试,而是先压缩上下文再重发这笔请求,最多 3 次。取消(`agent.stop()` 或传 `signal`)永远不重试。
672
673
 
673
- 想收口或过滤,用三个配置:
674
+ 想收口或过滤,用这几个配置:
674
675
 
675
676
  ```js
676
677
  const agent = Agent.create({
@@ -678,6 +679,7 @@ const agent = Agent.create({
678
679
  retryBaseDelay: 5000, // 第一次等待 5s,之后 10s、20s…(默认)
679
680
  retryMaxDelay: 600000, // 单次等待最多 10 分钟(默认)
680
681
  retryMaxElapsed: 120000, // 一直失败最多再试 2 分钟,到点把错误交给上层(默认不限)
682
+ retryMaxTries: 5, // 最多再重试 5 次(默认不限);0=不重试;和上面那条谁先到谁停
681
683
  // 只对"不想重试的错误"下手,命中即不重试:
682
684
  retry: {
683
685
  skipCodes: [400, 401], // 按状态码
@@ -690,7 +692,7 @@ const agent = Agent.create({
690
692
  })
691
693
  ```
692
694
 
693
- `retry` 属于 **整份替换**(和 `provider` 一样,本次传了就用本次的整份,不与上次合并)。
695
+ `retry` 属于 **整份替换**(和 `provider` 一样,本次传了就用本次的整份,不与上次合并)。`onRetry` 会收到 `{ attempt, maxTries, error, delay }`,宿主可以直接显示"第几 / 最多几次"。
694
696
 
695
697
  陌生中转站建议先使用默认能力。遇到只支持文字、但接口声称兼容 OpenAI 的模型,可以按能力关闭:
696
698
 
@@ -727,7 +729,7 @@ const agent = Agent.create({
727
729
  })
728
730
  ```
729
731
 
730
- 在 `agent.send({ input, config: { ... } })` 里传入的配置会**写回 Agent**、之后的每一次模型请求继续生效(包括正在跑的这一轮的下一笔,见下方「每轮现拼」)。合并规则分三种:`provider` 和 `retry` **整份替换**(传了就只用新的,未写的字段不再保留);`capabilities`、`compact` 和 `contextKeep` **按字段浅合并**(只传其中一项不丢另外的);其余字段直接覆盖。`maxContextTokens` 是上下文预算,`maxTokens` 是单次生成的最大输出(会映射成请求体的 `maxOutputTokens`),两者不是一回事。
732
+ 在 `agent.send({ input, config: { ... } })` 里传入的配置会**写回 Agent**、之后的每一笔模型请求继续生效(包括正在跑的这一轮的下一笔和它的每次重试,见下方「每笔请求现拼」)。合并规则分三种:`provider` 和 `retry` **整份替换**(传了就只用新的,未写的字段不再保留);`capabilities`、`compact` 和 `contextKeep` **按字段浅合并**(只传其中一项不丢另外的);其余字段直接覆盖。`maxContextTokens` 是上下文预算,`maxTokens` 是单次生成的最大输出(会映射成请求体的 `maxOutputTokens`),两者不是一回事。
731
733
 
732
734
  `cache` 默认开启。四种协议各按自己的方式让服务端复用固定的开头(system、工具描述、历史),命中后那部分不再重新计算,长会话能明显变快、变便宜:
733
735
 
@@ -807,7 +809,7 @@ console.log(answer.text)
807
809
  | `onToolOutput` | 工具有流式输出 | `{ toolName, stream, data, toolCallId, input? }`;`data` 是工具 yield / 打印出来的原值,类型不定 |
808
810
  | `onToolResult` | 工具执行完成(拒绝/取消/无效调用也触发) | `{ toolName, toolCallId, output, ... }` |
809
811
  | `onStep` | 一轮模型和工具都完成后 | `{ step, result, toolCalls, toolResults }`;`toolResults` 是完整结果对象(`call` + `output`),和 `onToolResult` 同一种形状 |
810
- | `onRetry` | 请求失败重试 | `{ attempt, error, delay }`(主请求和压缩请求共用) |
812
+ | `onRetry` | 请求失败重试 | `{ attempt, maxTries, error, delay }`(主请求和压缩请求共用) |
811
813
  | `onInject` | 每轮请求前(压缩之后) | `{ tokens, budget, compactThreshold }` → 返回字符串就临时附在本次请求末尾;返回其它值不注入 |
812
814
  | `onCompact` | 上下文压缩 | `compact-start`(`messages` + `reason` / `token` / `budget` / `compactThreshold` / `ratio` / `chars` / `media` / `calibrated`)/ AI SDK 事件(统一带 `request: 'compact'` 标记)/ `compact-finish`(带 `usage`,即压缩这一笔的用量) |
813
815
 
@@ -939,9 +941,9 @@ await agent.send({
939
941
 
940
942
  > 直接 `send` 的内容块会在入口校验:`text` / `image` / `audio` / `video` / `file` 这些块形状不对(比如媒体缺 `mediaType`、值不是字符串 / URL / 二进制)会当场拒绝,不会写进只增不删的历史。图片块用 `{ type: 'image', image: <data URL 或 base64 或 URL 对象> }`,或 AI SDK 当前的 `{ type: 'file', mediaType, data }`。
941
943
 
942
- #### 每轮现拼:运行中改什么,下一笔请求就生效
944
+ #### 每笔请求现拼:运行中改什么,下一笔请求就生效
943
945
 
944
- 每发一笔模型请求之前,Loop 都会重新从宿主那里取一遍这次请求要用的全部东西——配置、`system`、工具表,再重新拼出这一轮的上下文和请求。具体到代码就一句话:`agent` 是活对象,Loop 每轮重新读一次 `agent.config` 和 `agent.tools`,不是 `send` 开始时留一份副本。所以一次 `send` 还在跑的时候改它们,下一笔请求就用新值:不用停掉当前任务,也不用重建 Agent。
946
+ **每一笔真正发给模型的请求**之前,Loop 都会重新从宿主那里取一遍要用的全部东西——配置、`system`、工具表,再从 `history` 现推 messages。这里说的"每一笔"是字面意思:每轮的首次请求,**以及它的每一次重试**。`agent` 是活对象,不是 `send` 开始时留的一份副本。
945
947
 
946
948
  ```js
947
949
  // 在 onStep / onLLMFinish 里改都行:当前这笔请求和它发起的工具已经跑完
@@ -951,13 +953,14 @@ agent.config.system = '新的系统提示'
951
953
  agent.tools = Agent.tool.omit(agent.tools, ['shell']) // 运行中撤掉一个工具,下一笔请求就不带它
952
954
  ```
953
955
 
954
- - **什么时候切换**:只在请求边界。已经发出去的那一笔不会被打断,它发起的工具也照常跑完;下一轮请求模型时才换。流式过程中不会热替换。
955
- - **每轮都会重新取的**:连接(`baseURL` / `apiKey` / `model` / `protocol`)、`provider` 里的生成参数(温度、思考强度等)、`capabilities` / `mediaFallback`、`cache`、`retry` / `requestTimeout`、`maxTokens`、`maxContextTokens` / `compactThreshold`、`noToolRounds`、`maxToolOutput` / `maxToolConcurrency`、`system`、工具表;压缩用的 `compact` 配置在压缩发生的那一轮取。token 估算也按新模型重新记。
956
+ - **什么时候切换**:只在请求边界。已经发出去、正在流式返回的那一笔不会被打断(也不会热替换);下一笔请求——**包括同一轮的重试**——就用新值。最常见的情况:模型 A 失败、退避期间你把 `agent.config.model` 换成 B,下一次重试直接发给 B,不会一直卡在 A 上。
957
+ - **每笔都会重新取的**:连接(`baseURL` / `apiKey` / `model` / `protocol`)、`provider` 里的生成参数(温度、思考强度等)、`capabilities` / `mediaFallback`、`cache`、`requestTimeout`、`maxTokens`、`maxContextTokens`、`system`、工具表、以及从 `history` 现推的 messages。token 估算也按新模型重新记。
958
+ - **每轮才取的**:压缩判定(`compactThreshold` / 压缩用的 `compact` 配置)、`noToolRounds` 计数、轮次上限、`onInject` 的"这一轮要不要插一句"。这些是有副作用的决策(压缩会真的发一次请求、往 `history` 追加总结),不能放进重试里;新模型装不下时走"上下文超长 → 压缩后重发"那条兜底。
956
959
  - **工具表只读一遍,不重新扫描目录**:把 `agent.tools` 换成新的集合(`Agent.tool.from` / `pick` / `omit` 的返回值)就生效;目录里的文件不会在这次运行中被重新扫描——要重新扫描用新的 `send`(`send({ tools })` 会在开始时现扫)。模型看到的那张表和执行时用的 handler 取自同一份集合。
957
- - **不随轮次换的只有两样**:`history` 是这次运行的权威数据,循环始终往同一个数组追加;回调是运行期的接线,在 `send` 开始时定下。
960
+ - **不随请求换的只有两样**:`history` 是这次运行的权威数据,循环始终往同一个数组追加;回调是运行期的接线,在 `send` 开始时定下。
958
961
  - 按次传的 `send({ config })` 语义不变:写回 `agent.config`,这次运行从第一笔请求起就用它。
959
962
 
960
- > 会话运行中改模型 / 思考强度 / system / 工具表,直接改 `agent.config` 和 `agent.tools` 就行:历史、流式输出和运行状态都不中断。
963
+ > 会话运行中改模型 / 思考强度 / system / 工具表,直接改 `agent.config` 和 `agent.tools` 就行:历史、流式输出和运行状态都不中断,正在重试的那笔请求也会立刻用上新配置。
961
964
 
962
965
  #### `agent.stop()`
963
966
 
@@ -1186,7 +1189,7 @@ console.log(output.total)
1186
1189
 
1187
1190
  有工具时先完成工具调用,再读取最终对象。工具轮或 `tool-stop` 不会凭空产生 `output`。最终对象校验成功立即结束;格式错误默认也会重试(重新生成不保证还是坏的),想让它立刻失败可用 `retry` 过滤或收紧 `retryMaxElapsed`。手动及自动压缩只生成文本总结,不继承任务的对象格式。流式和非流式都在最终结果上提供 `output`;流中仍会有生成时的文字片段。
1188
1191
 
1189
- 直接使用底层 LLM,绕过 Agent 循环。
1192
+ 直接使用底层 LLM,绕过 Agent 循环。这里的参数是**一次性**的:`Agent.llm.chat` 不认识 `agent.config`,运行中改配置再重发是 Agent 层(`send` / 重试)的事——见「每笔请求现拼」。
1190
1193
 
1191
1194
  #### `Agent.llm.chat(options)`
1192
1195
 
@@ -66,6 +66,7 @@ export interface Config {
66
66
  retryBaseDelay?: number
67
67
  retryMaxDelay?: number
68
68
  retryMaxElapsed?: number
69
+ retryMaxTries?: number // 最多再重试几次;不设=不限,0=不重试。和 retryMaxElapsed 谁先到谁停。
69
70
  retry?: RetryFilter
70
71
  requestTimeout?: number
71
72
  noToolPrompt?: string
@@ -111,7 +112,7 @@ export interface Callbacks {
111
112
  onLLMFinish?: (result: any) => void | Promise<void>
112
113
  onLLMEvent?: (event: any) => void | Promise<void>
113
114
  onPermission?: (permission: { sessionId: string; toolCallId: string; toolName: string; input: any; signal: AbortSignal }) => boolean | Promise<boolean>
114
- onRetry?: (info: { attempt: number; error: Error; delay: number }) => void
115
+ onRetry?: (info: { attempt: number; maxTries: number; error: Error; delay: number }) => void
115
116
  // 每轮请求前调用;返回字符串就临时附在这次请求末尾(role:'user',不写进 history),返回其它值不注入。
116
117
  // tokens 是这一轮压缩之后的估算值。去重由宿主负责:核心每轮都会问,"只提醒一次"是业务策略。
117
118
  onInject?: (info: { tokens: number; budget: number; compactThreshold: number; ratio: number; ratioSource: RatioSource }) => string | undefined | null | Promise<string | undefined | null>