@kernel4632/agent-core 0.34.0 → 0.35.1

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
@@ -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) |
@@ -822,12 +823,38 @@ console.log(answer.text)
822
823
  | `compactThreshold` | 触发比例 |
823
824
  | `ratio` | 这次用的"每字符多少 token"比例(按模型自校准的那个值) |
824
825
  | `chars` / `media` | `token` 的两个组成部分:文字字符数、媒体块数(`token = ceil(chars × ratio) + media × 1200`) |
825
- | `calibrated` | `ratio` 是不是从真实 usage 学来的。`false` = 还在用默认值 |
826
+ | `calibrated` | `ratio` 是不是从真实 usage 学来的。`false` = 还在用默认值或宿主 seed |
827
+ | `ratioSource` | `'usage'` / `'host'` / `'default'`,直接说明这个比例是谁给的 |
826
828
 
827
829
  判断"是不是估算误判"就看 `token` 和 `budget × compactThreshold` 的关系,以及 `ratio` 是不是明显偏离你的内容(中文 ≈ 1,英文 ≈ 0.25)。注意 `token` 是**这一轮开始时**的估算:上一次真实请求之后又写进来的工具结果也在里面,所以它会比"上一次请求的 input"大。
828
830
 
829
831
  `calibrated: false` 有两个常见原因:一是进程刚起、还没成功跑完过一笔请求;二是上游没在响应里回 `usage`(流式请求需要 `stream_options.include_usage`,个别中转站不支持,可以用 `capabilities.usage: false` 关掉这个字段,但那样估算就只能一直用默认比例)。**校准是每个进程从零开始的**:重启后恢复一份很大的 history 时,第一个 `send` 用的仍是默认比例,可能因此多压一次——把 `token / chars / ratio` 记下来就能确认。想据此折算真实比例:`真实 token ÷ chars`。
830
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
+
831
858
  #### 宿主注入临时提示(`onInject`)
832
859
 
833
860
  想在"下一次模型请求"里临时补一句话,用 `onInject`:每轮请求前调一次,返回的文字作为一条 `user` 消息附在请求末尾,**不写进 `history`**,请求发完就没了。`tokens` 是这一轮压缩之后的估算值。
@@ -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>
@@ -246,6 +252,10 @@ export interface AgentInstance {
246
252
  resume: (options?: Omit<SendOptions, 'input'>) => Promise<Answer> // 不发新消息,用现有历史末尾续跑(历史末尾须是 assistant/tool)
247
253
  stop: () => Promise<{ ok: boolean }>
248
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 }
249
259
  }
250
260
 
251
261
  export interface CreateOptions {