@kernel4632/agent-core 0.35.1 → 0.37.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 +11 -4
- package/dist/agent-core.d.ts +7 -2
- package/dist/agent-core.js +87 -87
- package/package.json +1 -1
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
|
|
|
@@ -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
|
|
|
@@ -1255,8 +1257,13 @@ History.user({ content: [{ type: 'text', text: '这是什么' }, { type: 'image'
|
|
|
1255
1257
|
History.assistant({ content: '你好', toolCalls: [{ id: 'call-1', name: 'add', arguments: { a: 1, b: 2 } }] })
|
|
1256
1258
|
History.tool({ toolCallId: 'call-1', toolName: 'add', content: '3' })
|
|
1257
1259
|
History.compact({ content: '之前的对话总结...' })
|
|
1260
|
+
|
|
1261
|
+
// 只给宿主看的失败记录:存进 history、刷新后还能渲染,但模型永远收不到,也不占上下文预算。
|
|
1262
|
+
History.error({ content: '请求失败:500', request: { model: 'claude', ms: 1234, error: 'boom' } })
|
|
1258
1263
|
```
|
|
1259
1264
|
|
|
1265
|
+
**失败记录(`role:'error'`)**:它不参与回合、不参与工具配对、不参与压缩,`Context.build()` 会整条丢掉;`render()` 仍然把正文渲染出来,`request` 原样保存在这条消息上,宿主可以放自己的审计信息(模型、耗时、错误原因)。只有 `user` / `assistant` / `tool` 会发给模型——history 里出现别的 role,会跳过并 `console.warn` 一次(`error` 除外,那是预期用法)。
|
|
1266
|
+
|
|
1260
1267
|
**读历史**——渲染给用户看、数聊了几轮,这两件事的知识本来就在核心里,不用你照着内部结构重写:
|
|
1261
1268
|
|
|
1262
1269
|
```js
|
|
@@ -1392,7 +1399,7 @@ const agent = Agent.create({ config: { /* ... */ }, tools })
|
|
|
1392
1399
|
| `Agent.version` | 包版本,排查问题时报得出来 |
|
|
1393
1400
|
| `Agent.create(...)` | 创建 Agent 实例 |
|
|
1394
1401
|
| `Agent.tool` | `.from()` / `.scan()` / `.adopt()` / `.execute()` / `.merge()` / `.pick()` / `.omit()` |
|
|
1395
|
-
| `Agent.history` | `.user()` / `.assistant()` / `.tool()` / `.compact()` 造消息块;`.turns()` / `.render()` 读历史 |
|
|
1402
|
+
| `Agent.history` | `.user()` / `.assistant()` / `.tool()` / `.compact()` / `.error()` 造消息块;`.turns()` / `.render()` 读历史 |
|
|
1396
1403
|
| `Agent.context` | `.build()` |
|
|
1397
1404
|
| `Agent.compact` | `.run()` |
|
|
1398
1405
|
| `Agent.llm` | `.chat()` |
|
package/dist/agent-core.d.ts
CHANGED
|
@@ -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>
|
|
@@ -176,12 +177,14 @@ export interface ToolModule {
|
|
|
176
177
|
}
|
|
177
178
|
|
|
178
179
|
// --- 历史块 ---
|
|
179
|
-
|
|
180
|
+
// 前三种是模型能读的对话;'error' 是宿主自己的失败记录(History.error),模型永远看不到。
|
|
181
|
+
export type Role = 'user' | 'assistant' | 'tool' | 'error'
|
|
180
182
|
export interface Message {
|
|
181
183
|
id: string
|
|
182
184
|
role: Role
|
|
183
185
|
content: string | any[] | null
|
|
184
186
|
compact?: boolean
|
|
187
|
+
request?: any // 只有 role:'error' 会带:宿主自己的审计信息(model / 耗时 / 错误原因等),原样保存。
|
|
185
188
|
}
|
|
186
189
|
|
|
187
190
|
export interface HistoryModule {
|
|
@@ -189,6 +192,8 @@ export interface HistoryModule {
|
|
|
189
192
|
assistant: (options: { id?: string; content?: string | any[] | null; toolCalls?: Array<{ id: string; name: string; arguments?: any; input?: any }> }) => Message
|
|
190
193
|
tool: (options: { id?: string; toolCallId: string; toolName: string; content: any }) => Message
|
|
191
194
|
compact: (options: { id?: string; content: string }) => Message
|
|
195
|
+
// 只给宿主看的失败记录:存进 history、能渲染、刷新后还在,但不发给模型、不占上下文预算。
|
|
196
|
+
error: (options: { id?: string; content: string; request?: any }) => Message
|
|
192
197
|
stored: (message: any) => Message
|
|
193
198
|
turns: (history: Message[]) => Message[][]
|
|
194
199
|
render: (history: Message[]) => string
|