@kernel4632/agent-core 0.31.0 → 0.32.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 +27 -5
- package/dist/agent-core.d.ts +11 -1
- package/dist/agent-core.js +106 -106
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -96,14 +96,16 @@ flowchart TD
|
|
|
96
96
|
| 最初 | 用户最初的目标 | 保留:最多 3 个用户回合、≤20% 预算 |
|
|
97
97
|
| 中段 | 更早的回合 | 已被总结覆盖,不再单独发 |
|
|
98
98
|
| 总结 | 最新一条 `compact` 总结 | 折进 `system`(不是当消息) |
|
|
99
|
-
| 总结前 | 最近的现场回合 |
|
|
99
|
+
| 总结前 | 最近的现场回合 | 保留:默认最多 3 个回合、≤30% 预算 |
|
|
100
100
|
| 总结后 | 之后的全部新回合 | 全部保留(当前正在推进的) |
|
|
101
101
|
|
|
102
|
+
这几个数(3 / 3 / 20% / 30%)是**默认值**,宿主可以用 `config.contextKeep` 覆盖;传 `{ firstTurns: 0 }` 就是压缩后连最初那几轮原文也不带,只信总结 + 最近现场(见下方「上下文压缩保留方案」)。
|
|
103
|
+
|
|
102
104
|
几个关键取舍,以及为什么:
|
|
103
105
|
|
|
104
106
|
- **裁剪的最小单位是「回合」,不是「消息」。** 一个回合 = 用户一次发言,或模型的一次响应连同它发起的全部工具调用和结果。工具结果按 `toolCallId` 回到发起它的回合,**同进同出**。所以裁剪结果永远不会切断"调用 / 结果"的配对——那种残缺会被供应商 400。
|
|
105
107
|
- **最新那条总结折进 system,而不是当成一条消息塞进对话。** 裸的 `role:'user'` 总结会被模型读成"用户塞给我一张表",于是从头重做整个任务。实测 `gpt-oss-120b` 折进 system 前只有 1/6 能正确接着做,之后 6/6。
|
|
106
|
-
- **总结里保留最初目标。**
|
|
108
|
+
- **总结里保留最初目标。** 挑内容时,最初那几轮用户发言(说不出的话)单独钉住,默认最多 3 个回合、占 20% 预算。就算预算装不下,总结本身也被要求保留"用户最初的目标",而总结在 `system` 里永远不会被裁掉。这几个数可以用 `contextKeep` 调小甚至设成 0——原始措辞和总结里的目标同时出现时,模型有时会把旧话当成当前指令。
|
|
107
109
|
- **二次压缩不会忘掉上一次的总结。** 压缩请求会把上一版总结作为"背景"并进提示词,新总结必须保留其中仍然有效的事实。直接丢掉旧总结,会越压越忘。
|
|
108
110
|
- **按预算保留,不按条数。** 用户第一条消息就粘一大段日志时,只按条数留会让压缩永远收敛不了(实测 120/120 轮压完仍超阈值)。所以旧内容按预算分:目标 20%、最近现场 30%。
|
|
109
111
|
- **每轮最多压一次。** 不为"压到达标"而连续调用模型——那样一轮能烧掉上千次请求(实测)。压完还超限就照常发出去,由服务端判断;下一轮还超自然会再压一次。
|
|
@@ -661,6 +663,7 @@ import Agent from '@kernel4632/agent-core'
|
|
|
661
663
|
| `requestTimeout` | `undefined` | 默认不限制单笔请求时长;主动设置毫秒数后,卡住的一笔会被中断 |
|
|
662
664
|
| `noToolPrompt` | 一条"请继续使用工具"的提醒 | 有工具但模型连续不调时,在结束前一轮临时发给模型;只挂在那一次请求上,不写进 `history`。设成 `''` 就不提醒 |
|
|
663
665
|
| `noToolRounds` | `3` | 有工具时,连续多少轮不调工具就结束一次 `send`;设成 `1` 就是模型不调工具即结束,设成 `Infinity` 就永不因不调工具结束。没注册工具时一轮就结束,不受它影响 |
|
|
666
|
+
| `contextKeep` | `{ firstTurns: 3, recentTurns: 3, firstShare: 0.2, recentShare: 0.3 }` | 压缩后保留多少总结之前的原文:`firstTurns` 开场最多几个用户回合,`recentTurns` 总结前最多几个回合,两个 `*Share` 是各自最多占多少预算。`0` 表示这一段不留(比如 `{ firstTurns: 0 }` 只信总结 + 最近现场);本次 send 的用户输入永远保留 |
|
|
664
667
|
|
|
665
668
|
### 重试规则
|
|
666
669
|
|
|
@@ -723,7 +726,7 @@ const agent = Agent.create({
|
|
|
723
726
|
})
|
|
724
727
|
```
|
|
725
728
|
|
|
726
|
-
在 `agent.send({ input, config: { ... } })` 里传入的配置会**写回 Agent**、之后的每一次模型请求继续生效(包括正在跑的这一轮的下一笔,见下方「每轮现拼」)。合并规则分三种:`provider` 和 `retry` **整份替换**(传了就只用新的,未写的字段不再保留);`capabilities` 和 `
|
|
729
|
+
在 `agent.send({ input, config: { ... } })` 里传入的配置会**写回 Agent**、之后的每一次模型请求继续生效(包括正在跑的这一轮的下一笔,见下方「每轮现拼」)。合并规则分三种:`provider` 和 `retry` **整份替换**(传了就只用新的,未写的字段不再保留);`capabilities`、`compact` 和 `contextKeep` **按字段浅合并**(只传其中一项不丢另外的);其余字段直接覆盖。`maxContextTokens` 是上下文预算,`maxTokens` 是单次生成的最大输出(会映射成请求体的 `maxOutputTokens`),两者不是一回事。
|
|
727
730
|
|
|
728
731
|
`cache` 默认开启。四种协议各按自己的方式让服务端复用固定的开头(system、工具描述、历史),命中后那部分不再重新计算,长会话能明显变快、变便宜:
|
|
729
732
|
|
|
@@ -1181,6 +1184,7 @@ const { messages, token } = Agent.context.build({
|
|
|
1181
1184
|
history: agent.history,
|
|
1182
1185
|
system: '你是助手',
|
|
1183
1186
|
tools: tools.schema,
|
|
1187
|
+
keep: { firstTurns: 0 }, // 可选:压缩后保留多少旧内容,语义同 config.contextKeep
|
|
1184
1188
|
})
|
|
1185
1189
|
// messages → 可以直接传给 LLM.chat 的消息数组
|
|
1186
1190
|
// token → 估算的 token 数(不装分词器:文字按字符数 × 每字符 token 比,比例由 Loop 从真实 usage 自校准;媒体按块计,不看 base64 长度)
|
|
@@ -1190,7 +1194,7 @@ const { messages, token } = Agent.context.build({
|
|
|
1190
1194
|
永远同进同出。所以裁剪结果里不会出现"有调用没结果"或"有结果没调用"的残缺配对——那种序列会被
|
|
1191
1195
|
OpenAI 和 Anthropic 直接 400。
|
|
1192
1196
|
|
|
1193
|
-
|
|
1197
|
+
压缩时默认保留:用户最初的 3 个回合(保留原始目标)+ 最新总结 + 总结前最近 3 个回合 + 总结后所有回合。数量可用 `keep`(对应 `config.contextKeep`)覆盖,`0` 表示不留。
|
|
1194
1198
|
|
|
1195
1199
|
模型的思考内容(`reasoning`)会留在 `history` 里供上层 UI 渲染,但不会回传给模型:
|
|
1196
1200
|
它是某一次响应的厂商产物,不是持久对话状态,回传还会被一些服务拒绝。
|
|
@@ -1439,7 +1443,25 @@ config: {
|
|
|
1439
1443
|
|
|
1440
1444
|
**最新的那条总结会折进 `system`,而不是当成一条用户消息塞进对话里**,并且带一句"这是你自己之前做过的工作,数据已由工具确认"。裸的 `role:'user'` 总结会被模型读成"用户塞给我一张表",于是它从头重做整个任务——真实端点实测 `gpt-oss-120b` 改之前 1/6 能正确续跑,改之后 6/6。
|
|
1441
1445
|
|
|
1442
|
-
|
|
1446
|
+
保留多少旧内容是**按预算**算的,不是按条数:默认最初目标最多占 20%、总结前的现场最多占 30%,总结之后的新回合不受限。只按条数留的话,用户第一条消息粘一大段日志就能让压缩永远收敛不了(实测 120/120 轮压完仍超阈值)。放不下的最初目标不会丢——总结本身就被要求保留用户的原始目标,而总结在 `system` 里,永远不会被裁掉。
|
|
1447
|
+
|
|
1448
|
+
这几个默认值可以用 `config.contextKeep` 覆盖:
|
|
1449
|
+
|
|
1450
|
+
```js
|
|
1451
|
+
config: {
|
|
1452
|
+
// ...
|
|
1453
|
+
contextKeep: {
|
|
1454
|
+
firstTurns: 0, // 压缩后不带总结之前的开场原文,只信总结 + 最近现场
|
|
1455
|
+
// recentTurns: 3, // 总结前保留几个回合
|
|
1456
|
+
// firstShare: 0.2, // 开场最多占多少预算 [0,1]
|
|
1457
|
+
// recentShare: 0.3,// 总结前现场最多占多少预算 [0,1]
|
|
1458
|
+
},
|
|
1459
|
+
}
|
|
1460
|
+
```
|
|
1461
|
+
|
|
1462
|
+
- `0` 是合法值,表示这一段一点都不留(实现里用 `??` 取默认值,不是 `||`)。
|
|
1463
|
+
- 无论怎么配,**本次 send 的用户输入永远保留**——它是当前任务,剪掉模型就只能瞎猜。
|
|
1464
|
+
- 手动 `agent.compact()` 和自动压缩用的是同一份 `contextKeep`,不用配两遍。
|
|
1443
1465
|
|
|
1444
1466
|
每轮最多压一次。压完还超限就照常发出去,由模型服务判断收不收;下一轮还超自然会再压。**不会**为了压到达标而连续调用模型——那样一轮能烧掉上千次请求。
|
|
1445
1467
|
|
package/dist/agent-core.d.ts
CHANGED
|
@@ -57,6 +57,7 @@ export interface Config {
|
|
|
57
57
|
maxContextTokens?: number // 上下文预算;估算的上下文达到它的 compactThreshold 比例时自动压缩。默认 128000,设 Infinity 关闭自动压缩。
|
|
58
58
|
compactThreshold?: number
|
|
59
59
|
compact?: Partial<Config>
|
|
60
|
+
contextKeep?: ContextKeep
|
|
60
61
|
output?: any
|
|
61
62
|
maxToolConcurrency?: number
|
|
62
63
|
retryBaseDelay?: number
|
|
@@ -69,6 +70,15 @@ export interface Config {
|
|
|
69
70
|
[key: string]: any
|
|
70
71
|
}
|
|
71
72
|
|
|
73
|
+
// 压缩后保留多少总结之前的原文。不写就用默认值(3 轮 / 3 轮 / 20% / 30%);
|
|
74
|
+
// 轮数是上限,还要受占比和预算约束。0 是合法值:表示这一段一段都不留。
|
|
75
|
+
export interface ContextKeep {
|
|
76
|
+
firstTurns?: number // 开场最多保留几个用户回合(最初目标);默认 3
|
|
77
|
+
recentTurns?: number // 总结前最多保留几个回合(最近现场);默认 3
|
|
78
|
+
firstShare?: number // 开场最多占多少预算,[0,1];默认 0.2
|
|
79
|
+
recentShare?: number // 总结前现场最多占多少预算,[0,1];默认 0.3
|
|
80
|
+
}
|
|
81
|
+
|
|
72
82
|
// --- 用量与返回值 ---
|
|
73
83
|
export interface Usage {
|
|
74
84
|
inputTokens: number
|
|
@@ -184,7 +194,7 @@ export interface HistoryModule {
|
|
|
184
194
|
|
|
185
195
|
// --- 上下文、压缩、底层 LLM ---
|
|
186
196
|
export interface ContextModule {
|
|
187
|
-
build: (options: { history: Message[]; system?: string; tools?: Record<string, any>; budget?: number; ratio?: number; capabilities?: Capabilities; mediaFallback?: 'error' | 'strip' }) => { messages: any[]; readonly token: number }
|
|
197
|
+
build: (options: { history: Message[]; system?: string; tools?: Record<string, any>; budget?: number; ratio?: number; capabilities?: Capabilities; mediaFallback?: 'error' | 'strip'; keep?: ContextKeep }) => { messages: any[]; readonly token: number }
|
|
188
198
|
}
|
|
189
199
|
export interface CompactModule {
|
|
190
200
|
// 返回总结文本和这一笔压缩请求的用量(0.27 起带 usage:压缩也是真实请求,钱要计进合计)。
|