@kernel4632/agent-core 0.26.0 → 0.30.2
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 +64 -15
- package/dist/agent-core.d.ts +12 -3
- package/dist/agent-core.js +104 -97
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
|
|
1
|
+
# @kernel4632/agent-core
|
|
2
2
|
|
|
3
3
|
[](https://github.com/kernel4632/agent-core/actions/workflows/ci.yml)
|
|
4
4
|
[](https://github.com/kernel4632/agent-core/releases/latest)
|
|
@@ -64,18 +64,17 @@ flowchart TD
|
|
|
64
64
|
D --> E["结果写回 history"]
|
|
65
65
|
E --> S{"有工具返回<br/>stop:true?"}
|
|
66
66
|
S -->|是| T1["返回 tool-stop"]
|
|
67
|
-
S -->|否|
|
|
68
|
-
T2 -->|是| T3["返回 step-limit"]
|
|
69
|
-
T2 -->|否| A
|
|
67
|
+
S -->|否| A
|
|
70
68
|
|
|
71
69
|
C -->|不要| F{"结束判定"}
|
|
72
70
|
F -->|结构化输出成功<br/>或没注册工具| R1["返回 finished"]
|
|
73
|
-
F -->|步数到 maxSteps| T3
|
|
74
71
|
F -->|连续不调工具<br/>达 noToolRounds| R2["返回 no-tool"]
|
|
75
72
|
F -->|还没到| P["继续下一轮<br/>(末轮前插一句提醒)"]
|
|
76
73
|
P --> A
|
|
77
74
|
```
|
|
78
75
|
|
|
76
|
+
没有"最大轮数"这种上限:**什么时候停由模型的判断和工具的结果决定**,不由一个写死的步数决定。这个包只在你取消、模型报错、或两种正常收尾时结束。
|
|
77
|
+
|
|
79
78
|
**① 模型不调工具,不会立刻结束。** 很多模型在任务没做完时会"礼貌地"给一段总结就停下。直接结束会把没干完的活丢掉。所以有工具时,模型不调工具会先**临时**插一句提醒(`noToolPrompt`)再问一次,连续 `noToolRounds` 轮(默认 3)都不调才结束。这句提醒只挂在那一次请求上,**不写进 `history`**。不想要这个行为,把 `noToolRounds` 设成 `Infinity`。
|
|
80
79
|
|
|
81
80
|
**② `history` 是唯一的权威数据来源,只增不删。** 循环从不修改历史,模型消息、工具结果按发生的顺序追加。连压缩也只追加一条总结。原因:`history` 归你的应用所有(存库、渲染、多会话),核心替它丢弃数据是不可逆的错误——该留多少由持有它的你决定。
|
|
@@ -601,6 +600,14 @@ const agent = Agent.create({
|
|
|
601
600
|
})
|
|
602
601
|
```
|
|
603
602
|
|
|
603
|
+
**人机审批的推荐结构**(实战里每个应用都会撞到的问题):
|
|
604
|
+
|
|
605
|
+
- 等用户点击的实现是"返回一个挂起的 Promise"——包保证取消信号一到就不再等它,但**等多久、谁来唤醒**由你的回调决定。常见做法:按 `toolCallId` 存一张 `Map<id, resolve>`,审批接口收到决定后 `resolve(true/false)`。
|
|
606
|
+
- **等待期间 `send` 仍处于"正在运行"**:想允许用户在审批时发新消息顶掉任务,按 `send` 的既有语义处理(新 send 会先 stop 旧的)。
|
|
607
|
+
- **服务重启会丢掉挂起的审批**:`Map` 在内存里。重启后要么给会话补发一条审批请求(凭 history 里的 assistant 工具调用就能还原 `toolCallId`),要么在启动时把该会话标记为"已中断"。
|
|
608
|
+
- **务必给每条路径都 `return`**:非布尔返回值一律按拒绝处理(0.26 起),漏 return 会让这次调用被静默拒绝。
|
|
609
|
+
- **拒绝/取消/无效调用现在也会触发 `onToolResult`**(0.27 起),`output.type` 分别是 `execution-denied` / `error-text`——界面统一从这一个回调翻状态即可,不用再监听 `onPermission` 补通知。
|
|
610
|
+
|
|
604
611
|
---
|
|
605
612
|
|
|
606
613
|
## API 参考
|
|
@@ -646,7 +653,6 @@ import Agent from '@kernel4632/agent-core'
|
|
|
646
653
|
| `compactThreshold` | `0.8` | 压缩触发比例,0.8 表示到达 80% 时压缩 |
|
|
647
654
|
| `compact` | `undefined` | 压缩单独用一套模型时写在这里,例如 `{ model: '便宜的小模型' }`;不写就和主模型共用 |
|
|
648
655
|
| `output` | `undefined` | 结构化输出格式,例如 `Agent.output.object({ schema })`;不写就返回普通文字 |
|
|
649
|
-
| `maxSteps` | `undefined` | 默认不限制模型轮数;主动设置正整数后,到上限先保存这一轮的工具结果,再返回 `step-limit` |
|
|
650
656
|
| `maxToolConcurrency` | `undefined` | 默认不限制**文件工具**的并发;主动设置后超出的排队。内存工具(`Agent.tool.adopt` / MCP)在主进程直接跑,不受这个上限约束 |
|
|
651
657
|
| `retryBaseDelay` | `5000` | 第一次退避的基数(毫秒),之后每次 ×2:5s、10s、20s…(照抄 Roo Code) |
|
|
652
658
|
| `retryMaxDelay` | `600000` | 单次退避上限(毫秒),到顶就按这个值等待、不再增长(默认 10 分钟,照抄 Roo Code) |
|
|
@@ -717,7 +723,7 @@ const agent = Agent.create({
|
|
|
717
723
|
})
|
|
718
724
|
```
|
|
719
725
|
|
|
720
|
-
在 `agent.send({ input, config: { ... } })` 里传入的配置会**写回 Agent
|
|
726
|
+
在 `agent.send({ input, config: { ... } })` 里传入的配置会**写回 Agent**、之后的每一次模型请求继续生效(包括正在跑的这一轮的下一笔,见下方「每轮现拼」)。合并规则分三种:`provider` 和 `retry` **整份替换**(传了就只用新的,未写的字段不再保留);`capabilities` 和 `compact` **按字段浅合并**(只传其中一项不丢另外的);其余字段直接覆盖。`maxContextTokens` 是上下文预算,`maxTokens` 是单次生成的最大输出(会映射成请求体的 `maxOutputTokens`),两者不是一回事。
|
|
721
727
|
|
|
722
728
|
`cache` 默认开启。四种协议各按自己的方式让服务端复用固定的开头(system、工具描述、历史),命中后那部分不再重新计算,长会话能明显变快、变便宜:
|
|
723
729
|
|
|
@@ -795,10 +801,10 @@ console.log(answer.text)
|
|
|
795
801
|
| `onPermission` | 工具执行前 | `{ toolName, input, sessionId, toolCallId, signal }` → 返回 `true/false` |
|
|
796
802
|
| `onToolCall` | 工具即将执行 | `{ toolCallId, toolName, input }` |
|
|
797
803
|
| `onToolOutput` | 工具有流式输出 | `{ toolName, stream, data, toolCallId, input? }`;`data` 是工具 yield / 打印出来的原值,类型不定 |
|
|
798
|
-
| `onToolResult` |
|
|
799
|
-
| `onStep` | 一轮模型和工具都完成后 | `{ step, result, toolCalls, toolResults }` |
|
|
804
|
+
| `onToolResult` | 工具执行完成(拒绝/取消/无效调用也触发) | `{ toolName, toolCallId, output, ... }` |
|
|
805
|
+
| `onStep` | 一轮模型和工具都完成后 | `{ step, result, toolCalls, toolResults }`;`toolResults` 是完整结果对象(`call` + `output`),和 `onToolResult` 同一种形状 |
|
|
800
806
|
| `onRetry` | 请求失败重试 | `{ attempt, error, delay }`(主请求和压缩请求共用) |
|
|
801
|
-
| `onCompact` | 上下文压缩 | `compact-start` / AI SDK
|
|
807
|
+
| `onCompact` | 上下文压缩 | `compact-start` / AI SDK 事件(统一带 `request: 'compact'` 标记)/ `compact-finish`(带 `usage`,即压缩这一笔的用量) |
|
|
802
808
|
|
|
803
809
|
除了 `onPermission`,所有回调都只是通知:回调自己抛错会被忽略,任务照常进行,工具结果也不会被改写。`onPermission` 的返回值决定放不放行,所以它抛错时这次 `send` 会失败,交给你的 `.catch()`。注意它按"非 `true` 即拒绝"处理:**每个分支都要显式 `return true`**,忘了返回会让那次工具被拒。
|
|
804
810
|
|
|
@@ -811,7 +817,7 @@ await agent.send('继续')
|
|
|
811
817
|
|
|
812
818
|
const result = await agent.send({
|
|
813
819
|
input: '帮我写个函数', // 用户输入(必填)。也可以是内容块数组,见下方"发图片"
|
|
814
|
-
config: { model: '新模型' }, // 可选:覆盖部分配置(会写回 Agent
|
|
820
|
+
config: { model: '新模型' }, // 可选:覆盖部分配置(会写回 Agent,之后的每一次模型请求继续生效)
|
|
815
821
|
history: [], // 可选:整份替换历史(也写回 Agent)
|
|
816
822
|
tools: newTools, // 可选:整份替换工具集(也写回 Agent)
|
|
817
823
|
callbacks: { onLLMEvent: e => {} }, // 可选:合并回调(逐项写回 Agent,最后传的长期生效)
|
|
@@ -824,11 +830,11 @@ const result = await agent.send({
|
|
|
824
830
|
// result.steps → 这次 send 一共请求了模型几轮
|
|
825
831
|
// result.usage → 整次 send 的用量合计:{ inputTokens, outputTokens, totalTokens, cacheReadTokens, cacheWriteTokens }
|
|
826
832
|
// 算钱、看缓存命中直接读这里;cacheReadTokens / inputTokens 就是缓存命中率
|
|
833
|
+
// 自动压缩那一笔的用量也计在合计里(0.27 起)——压缩也是真实的模型请求
|
|
827
834
|
// result.reason:
|
|
828
835
|
// 'finished' → 没注册工具,或结构化输出已校验成功:这就是最终回答
|
|
829
836
|
// 'no-tool' → 有工具,但连续 noToolRounds 轮(默认 3)没调用工具才结束
|
|
830
837
|
// 'tool-stop' → 某个工具返回了 stop: true
|
|
831
|
-
// 'step-limit' → 达到 maxSteps,当前工具结果已保存,下一次 send 可继续
|
|
832
838
|
```
|
|
833
839
|
|
|
834
840
|
`send` 的出错方式只有一种:返回的 Promise 拒绝。空输入、非法配置、取消、模型报错全都从这里出来,所以只需要写 `.catch()`,不用另外包同步的 `try/catch`。取消造成的拒绝带 `error.kind === 'aborted'`;模型报错的 `error.kind` 见下方。
|
|
@@ -858,7 +864,27 @@ await agent.send({
|
|
|
858
864
|
|
|
859
865
|
能不能看懂取决于模型本身。实测 `kimi-k2.6` 可以,`gpt-oss-120b` 没有视觉能力、会直接报 `content must be a string`——是大声失败,不是静默忽略。
|
|
860
866
|
|
|
861
|
-
> 直接 `send`
|
|
867
|
+
> 直接 `send` 的内容块会在入口校验:`text` / `image` / `audio` / `video` / `file` 这些块形状不对(比如媒体缺 `mediaType`、值不是字符串 / URL / 二进制)会当场拒绝,不会写进只增不删的历史。图片块用 `{ type: 'image', image: <data URL 或 base64 或 URL 对象> }`,或 AI SDK 当前的 `{ type: 'file', mediaType, data }`。
|
|
868
|
+
|
|
869
|
+
#### 每轮现拼:运行中改什么,下一笔请求就生效
|
|
870
|
+
|
|
871
|
+
每发一笔模型请求之前,Loop 都会重新从宿主那里取一遍这次请求要用的全部东西——配置、`system`、工具表,再重新拼出这一轮的上下文和请求。具体到代码就一句话:`agent` 是活对象,Loop 每轮重新读一次 `agent.config` 和 `agent.tools`,不是 `send` 开始时留一份副本。所以一次 `send` 还在跑的时候改它们,下一笔请求就用新值:不用停掉当前任务,也不用重建 Agent。
|
|
872
|
+
|
|
873
|
+
```js
|
|
874
|
+
// 在 onStep / onLLMFinish 里改都行:当前这笔请求和它发起的工具已经跑完
|
|
875
|
+
agent.config.model = '新的模型'
|
|
876
|
+
agent.config.provider = { ...agent.config.provider, temperature: 0.2 }
|
|
877
|
+
agent.config.system = '新的系统提示'
|
|
878
|
+
agent.tools = Agent.tool.omit(agent.tools, ['shell']) // 运行中撤掉一个工具,下一笔请求就不带它
|
|
879
|
+
```
|
|
880
|
+
|
|
881
|
+
- **什么时候切换**:只在请求边界。已经发出去的那一笔不会被打断,它发起的工具也照常跑完;下一轮请求模型时才换。流式过程中不会热替换。
|
|
882
|
+
- **每轮都会重新取的**:连接(`baseURL` / `apiKey` / `model` / `protocol`)、`provider` 里的生成参数(温度、思考强度等)、`capabilities` / `mediaFallback`、`cache`、`retry` / `requestTimeout`、`maxTokens`、`maxContextTokens` / `compactThreshold`、`noToolRounds`、`maxToolOutput` / `maxToolConcurrency`、`system`、工具表;压缩用的 `compact` 配置在压缩发生的那一轮取。token 估算也按新模型重新记。
|
|
883
|
+
- **工具表只读一遍,不重新扫描目录**:把 `agent.tools` 换成新的集合(`Agent.tool.from` / `pick` / `omit` 的返回值)就生效;目录里的文件不会在这次运行中被重新扫描——要重新扫描用新的 `send`(`send({ tools })` 会在开始时现扫)。模型看到的那张表和执行时用的 handler 取自同一份集合。
|
|
884
|
+
- **不随轮次换的只有两样**:`history` 是这次运行的权威数据,循环始终往同一个数组追加;回调是运行期的接线,在 `send` 开始时定下。
|
|
885
|
+
- 按次传的 `send({ config })` 语义不变:写回 `agent.config`,这次运行从第一笔请求起就用它。
|
|
886
|
+
|
|
887
|
+
> 会话运行中改模型 / 思考强度 / system / 工具表,直接改 `agent.config` 和 `agent.tools` 就行:历史、流式输出和运行状态都不中断。
|
|
862
888
|
|
|
863
889
|
#### `agent.stop()`
|
|
864
890
|
|
|
@@ -868,6 +894,18 @@ await agent.send({
|
|
|
868
894
|
await agent.stop() // 等待完全停止后返回 { ok: true };Agent 空闲时返回 { ok: false }
|
|
869
895
|
```
|
|
870
896
|
|
|
897
|
+
#### `agent.resume(options?)`
|
|
898
|
+
|
|
899
|
+
不发新消息,用现有历史的末尾接着跑——典型场景是停止后继续被中断的回复。它不往 `history` 里写任何东西:模型看到的末尾就是中断前的最后一条(assistant 或 tool 消息),所以**不会**出现"续跑后历史里多出一条假的用户消息"。
|
|
900
|
+
|
|
901
|
+
```js
|
|
902
|
+
const answer = await agent.resume() // 从上次停下的地方继续,返回值和 send 相同
|
|
903
|
+
const answer = await agent.resume({ config: { model: '新模型' } }) // 也可以像 send 一样按次覆盖 config / callbacks
|
|
904
|
+
```
|
|
905
|
+
|
|
906
|
+
- 历史末尾必须是 `assistant` 或 `tool` 消息(有"没说完的话"可续),否则直接报错;想发新内容用 `send`。
|
|
907
|
+
- `resume` 不接受 `input`;传了会报错,防止把"继续"误写成新指令。
|
|
908
|
+
|
|
871
909
|
#### 流式与网页实时推送
|
|
872
910
|
|
|
873
911
|
`send` 内部默认就是流式(`config.stream` 默认 `true`),`await` 拿到的是和流式一样的结果。想实时拿到每一块,用 `onLLMEvent`:模型每吐一段就调用一次,事件是包内 AI SDK 的原生事件。
|
|
@@ -1004,10 +1042,15 @@ const agent = Agent.create({ config, tools: safe })
|
|
|
1004
1042
|
|------|--------|
|
|
1005
1043
|
| `schema[name].name` | 工具名 |
|
|
1006
1044
|
| `schema[name].description` | 给模型看的工具说明 |
|
|
1045
|
+
| `schema[name].source` | **来源标记**:`'file'`(目录扫描)或 `'memory'`(内存工具,MCP 工具走这里)。应用判断"这个工具从哪来"读它,别靠工具名前缀猜 |
|
|
1007
1046
|
| `schema[name].inputSchema` | **已编译的校验器**(AI SDK 的 `jsonSchema()` 形态);原始 JSON Schema 在 `inputSchema.jsonSchema` 里 |
|
|
1008
1047
|
| `handlers[name]` | 执行器内部形状(文件工具是 `url`,内存工具是 `execute` 等);**不要自己构造**,原样传回 `merge` / `pick` / `omit` 或 `Agent.tool.execute` |
|
|
1009
1048
|
|
|
1010
|
-
工具对象上的额外字段会被 `scan` / `adopt` 原样带进 `schema[name]`:比如工具自己声明 `touchesFiles: ['path']`,应用层就能从 `tools.schema[name].touchesFiles` 读到。注意 `schema` 是发给模型的那一份,别把不想让模型看到的内部标记放进去(`execute`、`toModelOutput`、`timeout` 不会被带进去,它们只留在 `handlers
|
|
1049
|
+
工具对象上的额外字段会被 `scan` / `adopt` 原样带进 `schema[name]`:比如工具自己声明 `touchesFiles: ['path']`,应用层就能从 `tools.schema[name].touchesFiles` 读到。注意 `schema` 是发给模型的那一份,别把不想让模型看到的内部标记放进去(`execute`、`toModelOutput`、`timeout` 不会被带进去,它们只留在 `handlers`)。**想要"只在宿主用、不进 schema"的字段**(比如内部钩子),把工具包一层、从闭包里取,别写在工具对象上:
|
|
1050
|
+
|
|
1051
|
+
```js
|
|
1052
|
+
const wrap = (tool, host) => ({ ...tool, execute: (input, options) => tool.execute(input, { ...options, host }) }) // host 从闭包取,不进 schema
|
|
1053
|
+
```
|
|
1011
1054
|
|
|
1012
1055
|
**MCP 工具直接可用,不需要包装**:`@ai-sdk/mcp` 的 `client.tools()` 自带 `execute` 和 `toModelOutput`,核心按 AI SDK 的签名调用它们,文字、图片都会正确交给模型。完整接入例子见前面的[「接入 MCP 和技能」](#接入-mcp-和技能)。
|
|
1013
1056
|
|
|
@@ -1024,6 +1067,10 @@ const agent = Agent.create({ config, tools: safe })
|
|
|
1024
1067
|
> 从 0.23 升级:内存工具(`Agent.tool.adopt`)现在也支持 `async *execute` 流式输出,和文件工具一致;`Tool.from` 接受一组目录(字符串数组);取消错误统一带 `error.kind === 'aborted'`。
|
|
1025
1068
|
>
|
|
1026
1069
|
> 从 0.25 升级(破坏性改名):上下文预算 `maxTokens` 改名为 **`maxContextTokens`**;`maxTokens` 现在指**单次生成的最大输出** token(映射到请求体的 `maxOutputTokens`)。这是把名字拨回 OpenAI / Anthropic 的习惯(它们的 `max_tokens` 就是输出上限,不是上下文)。另外:`onPermission` 现在要求**严格返回布尔**——非 `true`(含对象、漏 `return`)一律按拒绝处理;新增 `Agent.tool.pick` / `Agent.tool.omit` 用来取工具子集(做只读模式用 `omit` 去掉写工具)。
|
|
1070
|
+
>
|
|
1071
|
+
> 从 0.27 升级:`Compact.run` 的返回值从总结文本变成 `{ content, usage }`(单独用 `Agent.compact` 时注意解构);`onCompact` 的流事件统一带 `request: 'compact'` 标记、`compact-finish` 带 `usage`;工具被拒绝/取消/无效调用也触发 `onToolResult`,`onStep` 的 `toolResults` 是完整结果对象;自动压缩的用量计进 `send().usage`;新增 `agent.resume()` 从历史末尾续跑;工具的 `schema[name]` 带来源标记 `source: 'file' | 'memory'`;文件工具(子进程路径)的 `execute(input, options)` 现在也能拿到 `options.abortSignal`(取消即杀进程不变,信号仅供工具优雅收尾)。
|
|
1072
|
+
>
|
|
1073
|
+
> 从 0.30 升级(破坏性):去掉了 `maxSteps` 和结束原因 `'step-limit'`。这个包**不再限制循环轮数**——什么时候停由模型的判断和工具的结果决定。原来靠 `maxSteps` 兜底的地方,改由应用层控制:给 `send` 传 `signal`、设 `requestTimeout`,或者写一个返回 `stop: true` 的 `finish` 工具。
|
|
1027
1074
|
|
|
1028
1075
|
#### `Agent.tool.execute(options)`
|
|
1029
1076
|
|
|
@@ -1064,7 +1111,7 @@ console.log(output.total)
|
|
|
1064
1111
|
|
|
1065
1112
|
`Agent.output` 是包内 AI SDK 的 Output,`Agent.schema` 是包内 Zod,无需另装一套。数组可用 `Agent.output.array({ element: Agent.schema.string() })`,普通 JSON 可用 `Agent.output.json()`。所选模型服务须支持对应输出格式。
|
|
1066
1113
|
|
|
1067
|
-
|
|
1114
|
+
有工具时先完成工具调用,再读取最终对象。工具轮或 `tool-stop` 不会凭空产生 `output`。最终对象校验成功立即结束;格式错误默认也会重试(重新生成不保证还是坏的),想让它立刻失败可用 `retry` 过滤或收紧 `retryMaxElapsed`。手动及自动压缩只生成文本总结,不继承任务的对象格式。流式和非流式都在最终结果上提供 `output`;流中仍会有生成时的文字片段。
|
|
1068
1115
|
|
|
1069
1116
|
直接使用底层 LLM,绕过 Agent 循环。
|
|
1070
1117
|
|
|
@@ -1166,6 +1213,8 @@ History.turns(agent.history) // 折成回合:[[user], [assistant, tool], [us
|
|
|
1166
1213
|
| `retryMaxElapsed` | 不限制 | 默认重试所有错误且无总上限,等于无限重试。生产建议设毫秒数收口,或用 `retry` 过滤掉不该重试的错误(如 `auth`、`request`)。 |
|
|
1167
1214
|
| `maxContextTokens` | `128000` | 上下文预算,要按你模型的窗口调。比窗口大会撑爆,比需求小会频繁压缩。 |
|
|
1168
1215
|
|
|
1216
|
+
**这个包不限制循环轮数。** 循环停不停只由模型的判断、工具的结果(`stop: true`)、取消和报错决定。生产里要兜住"模型一直调工具停不下来",由应用层做:给 `send` 传 `signal`,用你自己的计时器或业务条件取消;或者写一个 `finish` 工具让模型主动收尾。
|
|
1217
|
+
|
|
1169
1218
|
## 可观测性
|
|
1170
1219
|
|
|
1171
1220
|
每一轮里模型花了多久、工具花了多久、什么时候压缩,用现成的回调就能拼出来。它们只是通知,抛错也不影响任务:
|
package/dist/agent-core.d.ts
CHANGED
|
@@ -58,7 +58,6 @@ export interface Config {
|
|
|
58
58
|
compactThreshold?: number
|
|
59
59
|
compact?: Partial<Config>
|
|
60
60
|
output?: any
|
|
61
|
-
maxSteps?: number
|
|
62
61
|
maxToolConcurrency?: number
|
|
63
62
|
retryBaseDelay?: number
|
|
64
63
|
retryMaxDelay?: number
|
|
@@ -79,7 +78,7 @@ export interface Usage {
|
|
|
79
78
|
cacheWriteTokens: number
|
|
80
79
|
}
|
|
81
80
|
|
|
82
|
-
export type Reason = 'finished' | 'no-tool' | 'tool-stop'
|
|
81
|
+
export type Reason = 'finished' | 'no-tool' | 'tool-stop'
|
|
83
82
|
|
|
84
83
|
export interface Answer {
|
|
85
84
|
reason: Reason
|
|
@@ -110,12 +109,18 @@ export interface ToolSet {
|
|
|
110
109
|
handlers: Record<string, any> // 执行器内部形状,不要自己构造,原样传回 merge/pick/omit
|
|
111
110
|
}
|
|
112
111
|
|
|
112
|
+
// scan / adopt 会在每个工具的 schema 里盖上来源标记:file(目录扫描)/ memory(内存工具)。
|
|
113
|
+
// 应用判断"这个工具从哪来"读它,不要再靠工具名前缀猜(名字是应用拼的,拼法一变判断就失效)。
|
|
114
|
+
export type ToolSourceKind = 'file' | 'memory'
|
|
115
|
+
|
|
113
116
|
// 内存工具对象的形状(AI SDK tool() 产物、MCP client.tools() 的单项都符合这个形状)
|
|
114
117
|
export interface ToolLike {
|
|
115
118
|
name?: string // 数组形式必填;record 形式从键名取;单个对象直接传时也必填
|
|
116
119
|
description?: string
|
|
117
120
|
inputSchema?: any // 裸 JSON Schema / zod / AI SDK jsonSchema() 三种都认
|
|
118
121
|
execute: (input: any, options?: { signal?: AbortSignal; abortSignal?: AbortSignal }) => any | Promise<any>
|
|
122
|
+
// 两条路径的契约一致:内存工具和文件工具(子进程)的 execute 都拿得到第二参 { signal, abortSignal }。
|
|
123
|
+
// 注意:文件工具的"取消即杀进程"仍由包负责,signal 只是让工具能优雅收尾(比如通知孙进程清理)。
|
|
119
124
|
toModelOutput?: (options: { output: any; input?: any; toolCallId?: string }) => any
|
|
120
125
|
timeout?: number
|
|
121
126
|
[key: string]: any
|
|
@@ -179,7 +184,8 @@ export interface ContextModule {
|
|
|
179
184
|
build: (options: { history: Message[]; system?: string; tools?: Record<string, any>; budget?: number; ratio?: number; capabilities?: Capabilities; mediaFallback?: 'error' | 'strip' }) => { messages: any[]; readonly token: number }
|
|
180
185
|
}
|
|
181
186
|
export interface CompactModule {
|
|
182
|
-
|
|
187
|
+
// 返回总结文本和这一笔压缩请求的用量(0.27 起带 usage:压缩也是真实请求,钱要计进合计)。
|
|
188
|
+
run: (options: Record<string, any>) => Promise<{ content: string; usage: Usage }>
|
|
183
189
|
}
|
|
184
190
|
export interface LLMModule {
|
|
185
191
|
chat: (options: Record<string, any>) => Promise<any>
|
|
@@ -213,7 +219,9 @@ export interface SendOptions {
|
|
|
213
219
|
export interface AgentInstance {
|
|
214
220
|
id: string
|
|
215
221
|
history: Message[]
|
|
222
|
+
// 活配置:每轮请求前重新取一次,运行中改它,下一笔模型请求就用新值(含 system)。
|
|
216
223
|
config: Config
|
|
224
|
+
// 同样每轮现取:运行中换成另一份集合(Tool.from / pick / omit 的返回值),下一笔请求就按新表发。
|
|
217
225
|
tools: ToolSet
|
|
218
226
|
callbacks: Callbacks
|
|
219
227
|
running: { controller: AbortController; task: Promise<Answer | string> } | null // send 时是 Answer;compact 时是总结字符串。
|
|
@@ -221,6 +229,7 @@ export interface AgentInstance {
|
|
|
221
229
|
(input: string | any[], options?: Omit<SendOptions, 'input'>): Promise<Answer>
|
|
222
230
|
(options: SendOptions & { input: string | any[] }): Promise<Answer>
|
|
223
231
|
}
|
|
232
|
+
resume: (options?: Omit<SendOptions, 'input'>) => Promise<Answer> // 不发新消息,用现有历史末尾续跑(历史末尾须是 assistant/tool)
|
|
224
233
|
stop: () => Promise<{ ok: boolean }>
|
|
225
234
|
compact: (options?: { onCompact?: Callbacks['onCompact']; onRetry?: Callbacks['onRetry']; signal?: AbortSignal }) => Promise<string>
|
|
226
235
|
}
|