@kernel4632/agent-core 0.30.2 → 0.31.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 +32 -3
- package/dist/agent-core.d.ts +3 -0
- package/dist/agent-core.js +135 -127
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -374,7 +374,7 @@ const agent = Agent.create({ config: { ...config, system: ['你是一个助手
|
|
|
374
374
|
├── notify.js ← 所有回调的统一出口
|
|
375
375
|
├── schema.js ← 工具参数格式归一化(scan 和 adopt 共用)
|
|
376
376
|
├── shape.js ← 工具返回值变成输出块(内存工具用;子进程里有一份副本)
|
|
377
|
-
└── tokens.js ← 上下文 token
|
|
377
|
+
└── tokens.js ← 上下文 token 估算:文字按字符数 × 每字符 token 比(比例由真实 usage 自校准),媒体按块计
|
|
378
378
|
```
|
|
379
379
|
|
|
380
380
|
`tool.js` 和 `tool-process.js` 是同一件事的两半,所以放在一起:前者在主线程里找工具、管工具进程,
|
|
@@ -804,9 +804,36 @@ console.log(answer.text)
|
|
|
804
804
|
| `onToolResult` | 工具执行完成(拒绝/取消/无效调用也触发) | `{ toolName, toolCallId, output, ... }` |
|
|
805
805
|
| `onStep` | 一轮模型和工具都完成后 | `{ step, result, toolCalls, toolResults }`;`toolResults` 是完整结果对象(`call` + `output`),和 `onToolResult` 同一种形状 |
|
|
806
806
|
| `onRetry` | 请求失败重试 | `{ attempt, error, delay }`(主请求和压缩请求共用) |
|
|
807
|
+
| `onInject` | 每轮请求前(压缩之后) | `{ tokens, budget, compactThreshold }` → 返回字符串就临时附在本次请求末尾;返回其它值不注入 |
|
|
807
808
|
| `onCompact` | 上下文压缩 | `compact-start` / AI SDK 事件(统一带 `request: 'compact'` 标记)/ `compact-finish`(带 `usage`,即压缩这一笔的用量) |
|
|
808
809
|
|
|
809
|
-
除了 `onPermission`,所有回调都只是通知:回调自己抛错会被忽略,任务照常进行,工具结果也不会被改写。`onPermission` 的返回值决定放不放行,所以它抛错时这次 `send` 会失败,交给你的 `.catch()`。注意它按"非 `true` 即拒绝"处理:**每个分支都要显式 `return true
|
|
810
|
+
除了 `onPermission` 和 `onInject`,所有回调都只是通知:回调自己抛错会被忽略,任务照常进行,工具结果也不会被改写。`onPermission` 的返回值决定放不放行,所以它抛错时这次 `send` 会失败,交给你的 `.catch()`。注意它按"非 `true` 即拒绝"处理:**每个分支都要显式 `return true`**,忘了返回会让那次工具被拒。`onInject` 抛错只当这一轮不注入,不打断任务。
|
|
811
|
+
|
|
812
|
+
#### 宿主注入临时提示(`onInject`)
|
|
813
|
+
|
|
814
|
+
想在"下一次模型请求"里临时补一句话,用 `onInject`:每轮请求前调一次,返回的文字作为一条 `user` 消息附在请求末尾,**不写进 `history`**,请求发完就没了。`tokens` 是这一轮压缩之后的估算值。
|
|
815
|
+
|
|
816
|
+
典型用法是上下文余量提醒——快到压缩点了,让模型这一轮收口:
|
|
817
|
+
|
|
818
|
+
```js
|
|
819
|
+
let reminded = false // "只提醒一次"是业务策略,由宿主自己记
|
|
820
|
+
|
|
821
|
+
const agent = Agent.create({
|
|
822
|
+
config: { ...config, maxContextTokens: 128000, compactThreshold: 0.8 },
|
|
823
|
+
callbacks: {
|
|
824
|
+
onInject: ({ tokens, budget, compactThreshold }) => {
|
|
825
|
+
const threshold = budget * compactThreshold
|
|
826
|
+
if (reminded || tokens < threshold * 0.95) return undefined
|
|
827
|
+
reminded = true
|
|
828
|
+
return '上下文快满了,这一轮请收口:不要再开新任务,把已有结果整理成答复。'
|
|
829
|
+
},
|
|
830
|
+
},
|
|
831
|
+
})
|
|
832
|
+
```
|
|
833
|
+
|
|
834
|
+
- 压缩当轮:`onInject` 在压缩之后才调,拿到的 `tokens` 已经是压小的值,自然不会再提醒。
|
|
835
|
+
- 每轮都会问,去重由你决定(上面用 `reminded`);核心不替宿主记"提醒过没有"。
|
|
836
|
+
- 和核心自己的 `noToolPrompt` 同时存在时,两段文字会合在一条消息里。
|
|
810
837
|
|
|
811
838
|
#### `agent.send(input)` / `agent.send(options)`
|
|
812
839
|
|
|
@@ -1156,7 +1183,7 @@ const { messages, token } = Agent.context.build({
|
|
|
1156
1183
|
tools: tools.schema,
|
|
1157
1184
|
})
|
|
1158
1185
|
// messages → 可以直接传给 LLM.chat 的消息数组
|
|
1159
|
-
// token → 估算的 token
|
|
1186
|
+
// token → 估算的 token 数(不装分词器:文字按字符数 × 每字符 token 比,比例由 Loop 从真实 usage 自校准;媒体按块计,不看 base64 长度)
|
|
1160
1187
|
```
|
|
1161
1188
|
|
|
1162
1189
|
裁剪的最小单位是**回合**,不是消息。一个回合 = 模型的一次响应 + 它发起的全部工具调用 + 这些调用的结果,
|
|
@@ -1393,6 +1420,8 @@ const agent = Agent.create({ config: { /* ... */ }, tools })
|
|
|
1393
1420
|
|
|
1394
1421
|
**上下文 token 怎么估**:不装分词器,用"字符数 × 每字符多少 token"。这个比例是**会自校准**的——每轮模型都会回 `usage.inputTokens`(这次请求真实的输入 token 数),拿它反推这个模型真实的"每字符 token 比"记下来给下一轮。换模型(`config.compact` 的压缩模型、`send` 时覆盖 `model`、换 provider)就换一条记录,越用越准,也不怕分词器对不上模型。
|
|
1395
1422
|
|
|
1423
|
+
**图片 / 音频 / 视频 / 文件不按 base64 字符数算。** 媒体块在 JSON 里可能有几百万字符,但模型为它付的 token 只取决于尺寸和解码方式,所以每块按固定值(`MEDIA_TOKENS`,1200)估,校准时会先把这部分从真实用量里扣掉。不这么做的话,一张截图就能让估算从 14 万跳到 80 万,上下文还很空就触发压缩(实战踩过:JSON 从 100 万字符涨到 4700 万字符)。
|
|
1424
|
+
|
|
1396
1425
|
**压缩只往 `agent.history` 里追加一条总结,永远不删任何东西。** `history` 是唯一权威数据来源,该保留多少由持有它的你来决定——压缩控制的是"这一轮发给模型的内容有多大",不是"历史能留多少"。
|
|
1397
1426
|
|
|
1398
1427
|
**压缩可以另配一套模型。** 总结不需要主模型那么聪明,用便宜的小模型就够,写在 `config.compact` 里:
|
package/dist/agent-core.d.ts
CHANGED
|
@@ -96,6 +96,9 @@ export interface Callbacks {
|
|
|
96
96
|
onLLMEvent?: (event: any) => void | Promise<void>
|
|
97
97
|
onPermission?: (permission: { sessionId: string; toolCallId: string; toolName: string; input: any; signal: AbortSignal }) => boolean | Promise<boolean>
|
|
98
98
|
onRetry?: (info: { attempt: number; error: Error; delay: number }) => void
|
|
99
|
+
// 每轮请求前调用;返回字符串就临时附在这次请求末尾(role:'user',不写进 history),返回其它值不注入。
|
|
100
|
+
// tokens 是这一轮压缩之后的估算值。去重由宿主负责:核心每轮都会问,"只提醒一次"是业务策略。
|
|
101
|
+
onInject?: (info: { tokens: number; budget: number; compactThreshold: number }) => string | undefined | null | Promise<string | undefined | null>
|
|
99
102
|
onToolCall?: (call: { toolCallId: string; toolName: string; input: any; type?: string; title?: string; providerExecuted?: boolean; providerMetadata?: Record<string, any> }) => void | Promise<void>
|
|
100
103
|
onToolOutput?: (output: { toolName: string; stream: string; data: unknown; toolCallId: string; input?: any }) => void
|
|
101
104
|
onToolResult?: (result: { toolCallId: string; toolName: string; input?: any; output: any; result?: any; error?: string; type?: string; title?: string; providerExecuted?: boolean; providerMetadata?: Record<string, any> }) => void | Promise<void>
|