@kernel4632/agent-core 0.33.0 → 0.35.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 -1
- package/dist/agent-core.d.ts +13 -2
- package/dist/agent-core.js +60 -60
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -654,6 +654,7 @@ import Agent from '@kernel4632/agent-core'
|
|
|
654
654
|
| `maxTokens` | `undefined` | 单次生成的最大输出 token,映射到请求体的 `maxOutputTokens`;不设=不限。`provider.maxOutputTokens` 显式设置时优先于它 |
|
|
655
655
|
| `compactThreshold` | `0.8` | 压缩触发比例,0.8 表示到达 80% 时压缩 |
|
|
656
656
|
| `compact` | `undefined` | 压缩单独用一套模型时写在这里,例如 `{ model: '便宜的小模型' }`;不写就和主模型共用 |
|
|
657
|
+
| `contextRatio` | `undefined` | 冷启动的估算倍率(每字符多少 token)。进程重启后第一个 `send` 用它估算,不用默认 0.6;真实 usage 到达后仍会覆盖它 |
|
|
657
658
|
| `output` | `undefined` | 结构化输出格式,例如 `Agent.output.object({ schema })`;不写就返回普通文字 |
|
|
658
659
|
| `maxToolConcurrency` | `undefined` | 默认不限制**文件工具**的并发;主动设置后超出的排队。内存工具(`Agent.tool.adopt` / MCP)在主进程直接跑,不受这个上限约束 |
|
|
659
660
|
| `retryBaseDelay` | `5000` | 第一次退避的基数(毫秒),之后每次 ×2:5s、10s、20s…(照抄 Roo Code) |
|
|
@@ -808,7 +809,7 @@ console.log(answer.text)
|
|
|
808
809
|
| `onStep` | 一轮模型和工具都完成后 | `{ step, result, toolCalls, toolResults }`;`toolResults` 是完整结果对象(`call` + `output`),和 `onToolResult` 同一种形状 |
|
|
809
810
|
| `onRetry` | 请求失败重试 | `{ attempt, error, delay }`(主请求和压缩请求共用) |
|
|
810
811
|
| `onInject` | 每轮请求前(压缩之后) | `{ tokens, budget, compactThreshold }` → 返回字符串就临时附在本次请求末尾;返回其它值不注入 |
|
|
811
|
-
| `onCompact` | 上下文压缩 | `compact-start`(`messages` + `reason` / `token` / `budget` / `compactThreshold` / `ratio`)/ AI SDK 事件(统一带 `request: 'compact'` 标记)/ `compact-finish`(带 `usage`,即压缩这一笔的用量) |
|
|
812
|
+
| `onCompact` | 上下文压缩 | `compact-start`(`messages` + `reason` / `token` / `budget` / `compactThreshold` / `ratio` / `chars` / `media` / `calibrated`)/ AI SDK 事件(统一带 `request: 'compact'` 标记)/ `compact-finish`(带 `usage`,即压缩这一笔的用量) |
|
|
812
813
|
|
|
813
814
|
除了 `onPermission` 和 `onInject`,所有回调都只是通知:回调自己抛错会被忽略,任务照常进行,工具结果也不会被改写。`onPermission` 的返回值决定放不放行,所以它抛错时这次 `send` 会失败,交给你的 `.catch()`。注意它按"非 `true` 即拒绝"处理:**每个分支都要显式 `return true`**,忘了返回会让那次工具被拒。`onInject` 抛错只当这一轮不注入,不打断任务。
|
|
814
815
|
|
|
@@ -821,9 +822,39 @@ console.log(answer.text)
|
|
|
821
822
|
| `budget` | `config.maxContextTokens`(上下文预算,不是模型窗口) |
|
|
822
823
|
| `compactThreshold` | 触发比例 |
|
|
823
824
|
| `ratio` | 这次用的"每字符多少 token"比例(按模型自校准的那个值) |
|
|
825
|
+
| `chars` / `media` | `token` 的两个组成部分:文字字符数、媒体块数(`token = ceil(chars × ratio) + media × 1200`) |
|
|
826
|
+
| `calibrated` | `ratio` 是不是从真实 usage 学来的。`false` = 还在用默认值或宿主 seed |
|
|
827
|
+
| `ratioSource` | `'usage'` / `'host'` / `'default'`,直接说明这个比例是谁给的 |
|
|
824
828
|
|
|
825
829
|
判断"是不是估算误判"就看 `token` 和 `budget × compactThreshold` 的关系,以及 `ratio` 是不是明显偏离你的内容(中文 ≈ 1,英文 ≈ 0.25)。注意 `token` 是**这一轮开始时**的估算:上一次真实请求之后又写进来的工具结果也在里面,所以它会比"上一次请求的 input"大。
|
|
826
830
|
|
|
831
|
+
`calibrated: false` 有两个常见原因:一是进程刚起、还没成功跑完过一笔请求;二是上游没在响应里回 `usage`(流式请求需要 `stream_options.include_usage`,个别中转站不支持,可以用 `capabilities.usage: false` 关掉这个字段,但那样估算就只能一直用默认比例)。**校准是每个进程从零开始的**:重启后恢复一份很大的 history 时,第一个 `send` 用的仍是默认比例,可能因此多压一次——把 `token / chars / ratio` 记下来就能确认。想据此折算真实比例:`真实 token ÷ chars`。
|
|
832
|
+
|
|
833
|
+
#### 冷启动的估算倍率(`contextRatio`)
|
|
834
|
+
|
|
835
|
+
上面那个"重启后第一个 send 多压一次"可以直接消掉:宿主把上次学到的倍率存起来,恢复会话时传回去,第一次估算就用它。
|
|
836
|
+
|
|
837
|
+
```js
|
|
838
|
+
// 进程 A:跑过之后把倍率存起来(宿主自己存,core 不碰磁盘)
|
|
839
|
+
const { ratio, source } = agent.getContextRatio()
|
|
840
|
+
if (source === 'usage') await save(`${provider}:${model}`, ratio)
|
|
841
|
+
|
|
842
|
+
// 进程 B:恢复会话时先传回去,第一个 send 就用它估,而不是默认 0.6
|
|
843
|
+
const agent = Agent.create({
|
|
844
|
+
history,
|
|
845
|
+
config: { contextRatio: await load(`${provider}:${model}`) },
|
|
846
|
+
})
|
|
847
|
+
|
|
848
|
+
// 也可以运行中改:立刻生效,之后真实 usage 到达仍会覆盖它
|
|
849
|
+
agent.setContextRatio(0.297)
|
|
850
|
+
```
|
|
851
|
+
|
|
852
|
+
- 优先级:**真实 usage 学到的 > `contextRatio`(宿主 seed)> 默认 0.6**。
|
|
853
|
+
- `getContextRatio()` 返回 `{ ratio, calibrated, source }`,`source` 是 `'usage'` / `'host'` / `'default'`。
|
|
854
|
+
- `onCompact` 的 `compact-start.ratioSource`、`onInject` 的参数里也能看到当前来源。
|
|
855
|
+
- 上游不返回 usage 时,宿主 seed 会一直有效(不会被打回默认值);`setContextRatio` 之后的第一笔真实 usage 仍会重新校准。
|
|
856
|
+
- 按 `provider + model` 存:换模型后比例本来就不一样,这台 Agent 的估算器也是按模型分开记的。
|
|
857
|
+
|
|
827
858
|
#### 宿主注入临时提示(`onInject`)
|
|
828
859
|
|
|
829
860
|
想在"下一次模型请求"里临时补一句话,用 `onInject`:每轮请求前调一次,返回的文字作为一条 `user` 消息附在请求末尾,**不写进 `history`**,请求发完就没了。`tokens` 是这一轮压缩之后的估算值。
|
package/dist/agent-core.d.ts
CHANGED
|
@@ -57,6 +57,9 @@ export interface Config {
|
|
|
57
57
|
maxContextTokens?: number // 上下文预算;估算的上下文达到它的 compactThreshold 比例时自动压缩。默认 128000,设 Infinity 关闭自动压缩。
|
|
58
58
|
compactThreshold?: number
|
|
59
59
|
compact?: Partial<Config>
|
|
60
|
+
// 冷启动的估算倍率(每字符多少 token)。进程重启、恢复大 history 时,第一次估算就用它,
|
|
61
|
+
// 不用默认 0.6;之后真实 usage 到达仍会覆盖它。宿主按 provider + model 自己持久化。
|
|
62
|
+
contextRatio?: number
|
|
60
63
|
contextKeep?: ContextKeep
|
|
61
64
|
output?: any
|
|
62
65
|
maxToolConcurrency?: number
|
|
@@ -79,6 +82,9 @@ export interface ContextKeep {
|
|
|
79
82
|
recentShare?: number // 总结前现场最多占多少预算,[0,1];默认 0.3
|
|
80
83
|
}
|
|
81
84
|
|
|
85
|
+
// 估算倍率现在是谁给的:真实 usage 校准出来的 / 宿主传的冷启动值 / 默认值。
|
|
86
|
+
export type RatioSource = 'usage' | 'host' | 'default'
|
|
87
|
+
|
|
82
88
|
// --- 用量与返回值 ---
|
|
83
89
|
export interface Usage {
|
|
84
90
|
inputTokens: number
|
|
@@ -108,7 +114,7 @@ export interface Callbacks {
|
|
|
108
114
|
onRetry?: (info: { attempt: number; error: Error; delay: number }) => void
|
|
109
115
|
// 每轮请求前调用;返回字符串就临时附在这次请求末尾(role:'user',不写进 history),返回其它值不注入。
|
|
110
116
|
// tokens 是这一轮压缩之后的估算值。去重由宿主负责:核心每轮都会问,"只提醒一次"是业务策略。
|
|
111
|
-
onInject?: (info: { tokens: number; budget: number; compactThreshold: number }) => string | undefined | null | Promise<string | undefined | null>
|
|
117
|
+
onInject?: (info: { tokens: number; budget: number; compactThreshold: number; ratio: number; ratioSource: RatioSource }) => string | undefined | null | Promise<string | undefined | null>
|
|
112
118
|
onToolCall?: (call: { toolCallId: string; toolName: string; input: any; type?: string; title?: string; providerExecuted?: boolean; providerMetadata?: Record<string, any> }) => void | Promise<void>
|
|
113
119
|
onToolOutput?: (output: { toolName: string; stream: string; data: unknown; toolCallId: string; input?: any }) => void
|
|
114
120
|
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>
|
|
@@ -194,7 +200,8 @@ export interface HistoryModule {
|
|
|
194
200
|
|
|
195
201
|
// --- 上下文、压缩、底层 LLM ---
|
|
196
202
|
export interface ContextModule {
|
|
197
|
-
build: (options: { history: Message[]; system?: string; tools?: Record<string, any>; budget?: number; ratio?: number; capabilities?: Capabilities; mediaFallback?: 'error' | 'strip'; keep?: ContextKeep }) =>
|
|
203
|
+
build: (options: { history: Message[]; system?: string; tools?: Record<string, any>; budget?: number; ratio?: number; capabilities?: Capabilities; mediaFallback?: 'error' | 'strip'; keep?: ContextKeep }) =>
|
|
204
|
+
{ messages: any[]; readonly token: number; readonly chars: number; readonly media: number } // chars / media 是 token 的两个组成部分,诊断估算时用。
|
|
198
205
|
}
|
|
199
206
|
export interface CompactModule {
|
|
200
207
|
// 返回总结文本和这一笔压缩请求的用量(0.27 起带 usage:压缩也是真实请求,钱要计进合计)。
|
|
@@ -245,6 +252,10 @@ export interface AgentInstance {
|
|
|
245
252
|
resume: (options?: Omit<SendOptions, 'input'>) => Promise<Answer> // 不发新消息,用现有历史末尾续跑(历史末尾须是 assistant/tool)
|
|
246
253
|
stop: () => Promise<{ ok: boolean }>
|
|
247
254
|
compact: (options?: { onCompact?: Callbacks['onCompact']; onRetry?: Callbacks['onRetry']; signal?: AbortSignal }) => Promise<string>
|
|
255
|
+
// 当前模型用的估算倍率,宿主可以持久化;calibrated=false 表示还是 seed 或默认值。
|
|
256
|
+
getContextRatio: () => { ratio: number; calibrated: boolean; source: RatioSource }
|
|
257
|
+
// 设一个冷启动倍率:立刻生效(忘掉之前学到的值),之后真实 usage 仍会覆盖它。
|
|
258
|
+
setContextRatio: (ratio: number) => { ratio: number; calibrated: boolean; source: RatioSource }
|
|
248
259
|
}
|
|
249
260
|
|
|
250
261
|
export interface CreateOptions {
|