@notic/agent-engine 1.1.1 → 2.0.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.
Files changed (112) hide show
  1. package/CHANGELOG.md +46 -0
  2. package/README.md +434 -292
  3. package/dist/adapter/AnthropicAdapter.d.ts +3 -1
  4. package/dist/adapter/AnthropicAdapter.d.ts.map +1 -1
  5. package/dist/adapter/AnthropicAdapter.js +40 -2
  6. package/dist/adapter/AnthropicAdapter.js.map +1 -1
  7. package/dist/adapter/GeminiAdapter.d.ts +3 -1
  8. package/dist/adapter/GeminiAdapter.d.ts.map +1 -1
  9. package/dist/adapter/GeminiAdapter.js +76 -3
  10. package/dist/adapter/GeminiAdapter.js.map +1 -1
  11. package/dist/adapter/MessageAdapter.d.ts +17 -0
  12. package/dist/adapter/MessageAdapter.d.ts.map +1 -1
  13. package/dist/adapter/MessageAdapter.js.map +1 -1
  14. package/dist/adapter/OpenAIAdapter.d.ts +3 -1
  15. package/dist/adapter/OpenAIAdapter.d.ts.map +1 -1
  16. package/dist/adapter/OpenAIAdapter.js +19 -2
  17. package/dist/adapter/OpenAIAdapter.js.map +1 -1
  18. package/dist/adapter/OpenAIResponsesAdapter.d.ts +23 -0
  19. package/dist/adapter/OpenAIResponsesAdapter.d.ts.map +1 -0
  20. package/dist/adapter/OpenAIResponsesAdapter.js +231 -0
  21. package/dist/adapter/OpenAIResponsesAdapter.js.map +1 -0
  22. package/dist/adapter/index.d.ts +2 -1
  23. package/dist/adapter/index.d.ts.map +1 -1
  24. package/dist/adapter/index.js +3 -1
  25. package/dist/adapter/index.js.map +1 -1
  26. package/dist/agent/Agent.d.ts +57 -16
  27. package/dist/agent/Agent.d.ts.map +1 -1
  28. package/dist/agent/Agent.js +292 -54
  29. package/dist/agent/Agent.js.map +1 -1
  30. package/dist/agent/index.d.ts +1 -1
  31. package/dist/agent/index.d.ts.map +1 -1
  32. package/dist/agent/index.js +4 -1
  33. package/dist/agent/index.js.map +1 -1
  34. package/dist/client/ModelClient.d.ts +74 -0
  35. package/dist/client/ModelClient.d.ts.map +1 -0
  36. package/dist/client/ModelClient.js +85 -0
  37. package/dist/client/ModelClient.js.map +1 -0
  38. package/dist/client/index.d.ts +2 -0
  39. package/dist/client/index.d.ts.map +1 -0
  40. package/dist/client/index.js +11 -0
  41. package/dist/client/index.js.map +1 -0
  42. package/dist/index.d.ts +11 -6
  43. package/dist/index.d.ts.map +1 -1
  44. package/dist/index.js +31 -5
  45. package/dist/index.js.map +1 -1
  46. package/dist/media/BrowserMediaResolver.d.ts +14 -0
  47. package/dist/media/BrowserMediaResolver.d.ts.map +1 -0
  48. package/dist/media/BrowserMediaResolver.js +52 -0
  49. package/dist/media/BrowserMediaResolver.js.map +1 -0
  50. package/dist/media/index.d.ts +1 -0
  51. package/dist/media/index.d.ts.map +1 -1
  52. package/dist/media/index.js +3 -1
  53. package/dist/media/index.js.map +1 -1
  54. package/dist/message/Message.d.ts +7 -0
  55. package/dist/message/Message.d.ts.map +1 -1
  56. package/dist/message/Message.js +52 -0
  57. package/dist/message/Message.js.map +1 -1
  58. package/dist/message/MessagePart.d.ts +2 -0
  59. package/dist/message/MessagePart.d.ts.map +1 -1
  60. package/dist/node.d.ts +3 -0
  61. package/dist/node.d.ts.map +1 -0
  62. package/dist/node.js +6 -0
  63. package/dist/node.js.map +1 -0
  64. package/dist/provider/Provider.d.ts +48 -0
  65. package/dist/provider/Provider.d.ts.map +1 -0
  66. package/dist/provider/Provider.js +73 -0
  67. package/dist/provider/Provider.js.map +1 -0
  68. package/dist/provider/index.d.ts +2 -0
  69. package/dist/provider/index.d.ts.map +1 -0
  70. package/dist/provider/index.js +10 -0
  71. package/dist/provider/index.js.map +1 -0
  72. package/dist/session/Session.d.ts +0 -3
  73. package/dist/session/Session.d.ts.map +1 -1
  74. package/dist/session/Session.js +0 -13
  75. package/dist/session/Session.js.map +1 -1
  76. package/dist/stream/AnthropicStreamParser.d.ts +26 -0
  77. package/dist/stream/AnthropicStreamParser.d.ts.map +1 -0
  78. package/dist/stream/AnthropicStreamParser.js +176 -0
  79. package/dist/stream/AnthropicStreamParser.js.map +1 -0
  80. package/dist/stream/GeminiStreamParser.d.ts +21 -0
  81. package/dist/stream/GeminiStreamParser.d.ts.map +1 -0
  82. package/dist/stream/GeminiStreamParser.js +144 -0
  83. package/dist/stream/GeminiStreamParser.js.map +1 -0
  84. package/dist/stream/MessageStreamParser.d.ts +13 -0
  85. package/dist/stream/MessageStreamParser.d.ts.map +1 -0
  86. package/dist/stream/MessageStreamParser.js +3 -0
  87. package/dist/stream/MessageStreamParser.js.map +1 -0
  88. package/dist/stream/OpenAIResponsesStreamParser.d.ts +30 -0
  89. package/dist/stream/OpenAIResponsesStreamParser.d.ts.map +1 -0
  90. package/dist/stream/OpenAIResponsesStreamParser.js +273 -0
  91. package/dist/stream/OpenAIResponsesStreamParser.js.map +1 -0
  92. package/dist/stream/StreamEvent.d.ts +13 -1
  93. package/dist/stream/StreamEvent.d.ts.map +1 -1
  94. package/dist/stream/StreamEvent.js +2 -0
  95. package/dist/stream/StreamEvent.js.map +1 -1
  96. package/dist/stream/StreamParser.d.ts +2 -1
  97. package/dist/stream/StreamParser.d.ts.map +1 -1
  98. package/dist/stream/StreamParser.js.map +1 -1
  99. package/dist/stream/index.d.ts +5 -1
  100. package/dist/stream/index.d.ts.map +1 -1
  101. package/dist/stream/index.js +7 -1
  102. package/dist/stream/index.js.map +1 -1
  103. package/dist/tool/ToolKit.d.ts +4 -0
  104. package/dist/tool/ToolKit.d.ts.map +1 -1
  105. package/dist/tool/ToolKit.js +50 -14
  106. package/dist/tool/ToolKit.js.map +1 -1
  107. package/dist/tool/index.d.ts +1 -1
  108. package/dist/tool/index.d.ts.map +1 -1
  109. package/dist/tool/index.js +2 -1
  110. package/dist/tool/index.js.map +1 -1
  111. package/docs/API.md +1676 -1455
  112. package/package.json +33 -9
package/README.md CHANGED
@@ -1,292 +1,434 @@
1
- # AgentEngine
2
-
3
- AgentEngine 是一个轻量、模块化、可测试的 TypeScript AI Agent 框架。
4
-
5
- 它的目标不是把所有能力塞进一个黑盒,而是把 Agent 拆成清晰的模块:消息、会话、工具、流式解析、提示词构建、请求配置、平台适配和自动循环。你可以直接使用完整的 `Agent`,也可以单独拿其中某个模块来构建自己的系统。
6
-
7
- > 简单的事情简单做,复杂的事情也能拆开做。
8
-
9
- ```ts
10
- import OpenAI from "openai";
11
- import { Agent, Session, StreamEventType } from "@notic/agent-engine";
12
-
13
- const client = new OpenAI({
14
- apiKey: process.env.OPENAI_API_KEY,
15
- });
16
-
17
- const agent = new Agent({
18
- client,
19
- model: "gpt-4o-mini",
20
- session: Session.create("你是一个简洁可靠的助手。"),
21
- });
22
-
23
- agent.on(StreamEventType.TEXT_DELTA, (event) => {
24
- process.stdout.write(event.delta);
25
- });
26
-
27
- const reply = await agent.run("用一句话介绍 AgentEngine。");
28
- console.log(reply.text);
29
- ```
30
-
31
- ## 适合做什么
32
-
33
- - 构建带工具调用的 AI Agent
34
- - 管理多轮对话、分支会话和可恢复上下文
35
- - 把 OpenAI-compatible、Anthropic、Gemini 等平台统一到同一套消息模型
36
- - 解析模型 stream,并把文本、思考内容、工具调用转换成结构化事件
37
- - 用声明式规则动态注入提示词和运行时上下文
38
- - 为 Agent 各模块编写可控的单元测试和 fake client 测试
39
-
40
- ## 核心特性
41
-
42
- - **模块化架构**:`Message`、`Session`、`Tool`、`Stream`、`Prompt`、`Config`、`Adapter`、`Agent` 都可以单独使用。
43
- - **统一消息模型**:支持文本、图片、音频、文件、工具调用、工具结果和 thinking 内容。
44
- - **树形会话管理**:天然支持对话分支、回退、分页、查询和插入。
45
- - **工具系统**:Builder 风格定义工具,自动生成 JSON Schema,支持生命周期 Hook、MCP 和错误策略。
46
- - **流式事件**:把模型 stream 解析成 `TEXT_DELTA`、`TOOL_CALL_*`、`MESSAGE_DONE` 等事件。
47
- - **提示词构建器**:用 `Rule` 定位消息,再注入临时上下文;也支持数组操作管线。
48
- - **请求配置器**:链式构建 temperature、top_p、max_tokens、response_format 等参数。
49
- - **多平台适配**:内置 OpenAI、Anthropic、Gemini 适配器;OpenAI Adapter 可用于 DeepSeek、Qwen、Kimi、GLM 等兼容平台。
50
- - **中断与恢复**:支持 abort、timeout、partial message、continue 和 resume。
51
- - **工具审批**:支持自动审批、自定义审批、手动审批和审批超时策略。
52
-
53
- ## 安装
54
-
55
- ```bash
56
- npm install @notic/agent-engine
57
- ```
58
-
59
- 根据你使用的平台安装对应 SDK:
60
-
61
- ```bash
62
- # OpenAI / DeepSeek / Qwen / Kimi 等 OpenAI-compatible 平台
63
- npm install openai
64
-
65
- # MCP 集成,可选
66
- npm install @modelcontextprotocol/sdk
67
- ```
68
-
69
- 环境要求:
70
-
71
- - Node.js >= 18
72
- - TypeScript 项目推荐开启 `strict`
73
-
74
- ## 快速开始
75
-
76
- ### 1. 创建 Agent
77
-
78
- ```ts
79
- import OpenAI from "openai";
80
- import { Agent, RequestConfig, Session } from "@notic/agent-engine";
81
-
82
- const client = new OpenAI({
83
- apiKey: process.env.OPENAI_API_KEY,
84
- baseURL: "https://api.openai.com/v1",
85
- });
86
-
87
- const agent = new Agent({
88
- client,
89
- model: "gpt-4o-mini",
90
- session: Session.create("你是一个友好的中文助手。"),
91
- config: RequestConfig.create().temperature(0.3).maxTokens(1024),
92
- });
93
- ```
94
-
95
- OpenAI-compatible 平台只需要替换 `baseURL` 和 `model`:
96
-
97
- ```ts
98
- const client = new OpenAI({
99
- apiKey: process.env.DEEPSEEK_API_KEY,
100
- baseURL: "https://api.deepseek.com",
101
- });
102
- ```
103
-
104
- ### 2. 监听流式输出
105
-
106
- ```ts
107
- import { StreamEventType } from "@notic/agent-engine";
108
-
109
- agent.on(StreamEventType.TEXT_DELTA, (event) => {
110
- process.stdout.write(event.delta);
111
- });
112
-
113
- agent.on(StreamEventType.TOOL_EXECUTE_START, (event) => {
114
- console.log("tool:", event.name);
115
- });
116
- ```
117
-
118
- ### 3. 运行一轮对话
119
-
120
- ```ts
121
- const reply = await agent.run("帮我写一个 npm 包介绍。");
122
- console.log(reply.text);
123
- ```
124
-
125
- `Agent` 会自动把用户消息和助手回复写入 `Session`。
126
-
127
- ## 工具调用示例
128
-
129
- ```ts
130
- import { Agent, Param, Session, Tool, ToolKit } from "@notic/agent-engine";
131
-
132
- const getWeather = Tool.create(async (args) => {
133
- return {
134
- city: args.city,
135
- temperature: 21,
136
- unit: "celsius",
137
- };
138
- })
139
- .name("get_weather")
140
- .description("查询城市天气")
141
- .params(
142
- Param.string("city").desc("城市名称").required()
143
- )
144
- .build();
145
-
146
- const toolkit = new ToolKit().add(getWeather);
147
-
148
- const agent = new Agent({
149
- client,
150
- model: "your-model",
151
- session: Session.create("需要外部信息时可以调用工具。"),
152
- toolkit,
153
- });
154
-
155
- const reply = await agent.run("北京今天适合跑步吗?");
156
- console.log(reply.text);
157
- ```
158
-
159
- 当模型发起工具调用时,AgentEngine 会自动执行工具、把结果写回会话,并再次请求模型生成最终答案。
160
-
161
- ## 模块地图
162
-
163
- ```text
164
- AgentEngine
165
- ├─ Message 统一消息模型:文本、多模态、工具调用、树节点
166
- ├─ Session 会话树:历史、分支、查询、插入、分页
167
- ├─ Tool 工具系统:Param、Tool、ToolKit、Hook、MCP
168
- ├─ Stream 流式解析:chunk -> 结构化事件 -> Message
169
- ├─ Prompt 提示词构建:Rule、Injection、数组操作管线
170
- ├─ Config 请求参数:预设、链式配置、三层优先级
171
- ├─ Adapter 平台适配:OpenAI、Anthropic、Gemini
172
- ├─ Media 媒体解析:data URI、HTTP、本地文件
173
- └─ Agent 编排层:自动循环、审批、中断、恢复
174
- ```
175
-
176
- ### Message
177
-
178
- 统一消息对象,支持:
179
-
180
- - `Message.user()` / `Message.assistant()` / `Message.system()`
181
- - 文本、图片、音频、文件
182
- - 工具调用和工具结果
183
- - thinking 内容
184
- - 标签、元数据和树结构
185
-
186
- ### Session
187
-
188
- 会话管理器,负责:
189
-
190
- - root -> cursor 的当前历史路径
191
- - 对话分支和回退
192
- - 查询当前分支或全树
193
- - 在历史中插入消息
194
- - 在兄弟分支间分页切换
195
-
196
- ### Tool
197
-
198
- 工具系统,负责:
199
-
200
- - 用 `Param` 定义参数 schema
201
- - 用 `Tool` 包装 TypeScript 函数
202
- - 用 `ToolKit` 注册并执行多个工具
203
- - 用 Hook 处理校验、取消、结果改写和错误降级
204
-
205
- ### Stream
206
-
207
- 流式解析器,负责:
208
-
209
- - 文本增量
210
- - thinking / reasoning 增量
211
- - 工具调用增量
212
- - usage
213
- - 最终 `Message` 组装
214
-
215
- ### Prompt
216
-
217
- 提示词构建器,负责:
218
-
219
- - 按角色、标签、内容或自定义规则定位消息
220
- - 动态注入 system/user/assistant 消息
221
- - 控制注入生命周期、概率和优先级
222
- - 在发送模型前过滤、裁剪或转换上下文
223
-
224
- ### Config
225
-
226
- 请求参数配置器,负责:
227
-
228
- - temperature / top_p / top_k
229
- - max_tokens
230
- - stop
231
- - seed
232
- - response_format
233
- - 自定义平台参数
234
-
235
- ### Adapter
236
-
237
- 平台适配器,负责:
238
-
239
- - 把 AgentEngine 的 `Message[]` 序列化成平台请求格式
240
- - 处理多模态内容
241
- - 处理工具调用和工具结果
242
- - 控制 thinking 内容如何回传
243
-
244
- ### Agent
245
-
246
- 智能体编排层,负责:
247
-
248
- - 管理 `Session`
249
- - 调用模型 stream
250
- - 派发事件
251
- - 执行工具循环
252
- - 处理工具审批
253
- - 中断、超时、恢复和继续
254
-
255
- ## 文档
256
-
257
- 完整教程式 API 文档见:
258
-
259
- - [docs/API.md](./docs/API.md)
260
-
261
- 建议阅读顺序:
262
-
263
- 1. 安装与最小示例
264
- 2. Agent:智能体编排
265
- 3. Tool:工具系统
266
- 4. Prompt:提示词构建
267
- 5. Session:会话树
268
- 6. Adapter / Media:平台与多模态适配
269
-
270
- ## 测试
271
-
272
- 项目使用 Node.js 内置测试运行器。
273
-
274
- ```bash
275
- npm test
276
- ```
277
-
278
- 真实 API 测试需要显式开启,避免普通测试误触发外部请求:
279
-
280
- ```bash
281
- RUN_REAL_DEEPSEEK_TESTS=1 DEEPSEEK_API_KEY=sk-... npm run test:real:deepseek
282
- ```
283
-
284
- ## 构建
285
-
286
- ```bash
287
- npm run build
288
- ```
289
-
290
- ## License
291
-
292
- Apache-2.0
1
+ # AgentEngine
2
+
3
+ AgentEngine 是一个轻量、模块化、可测试的 TypeScript AI Agent 框架。
4
+
5
+ 它的目标不是把所有能力塞进一个黑盒,而是把 Agent 拆成清晰的模块:消息、会话、工具、流式解析、提示词构建、请求配置、平台适配和自动循环。你可以直接使用完整的 `Agent`,也可以单独拿其中某个模块来构建自己的系统。
6
+
7
+ > 简单的事情简单做,复杂的事情也能拆开做。
8
+
9
+ ```ts
10
+ import OpenAI from "openai";
11
+ import { Agent, Session, StreamEventType } from "@notic/agent-engine";
12
+
13
+ const client = new OpenAI({
14
+ apiKey: process.env.OPENAI_API_KEY,
15
+ });
16
+
17
+ const agent = new Agent({
18
+ client,
19
+ model: "gpt-4o-mini",
20
+ session: Session.create("你是一个简洁可靠的助手。"),
21
+ });
22
+
23
+ agent.on(StreamEventType.TEXT_DELTA, (event) => {
24
+ process.stdout.write(event.delta);
25
+ });
26
+
27
+ const reply = await agent.run("用一句话介绍 AgentEngine。");
28
+ console.log(reply.text);
29
+ ```
30
+
31
+ 需要一次性取得完整响应时:
32
+
33
+ ```ts
34
+ const reply = await agent.run("用一句话介绍 AgentEngine。", {
35
+ stream: false,
36
+ });
37
+ ```
38
+
39
+ 流式与非流式模式使用同一套 `Message`、Session 和工具调用循环。
40
+
41
+ 如果上下文已经写入当前 `Session`,可以直接生成 Assistant:
42
+
43
+ ```ts
44
+ session.addUser("已经准备好的上下文");
45
+ const reply = await agent.generate();
46
+ ```
47
+
48
+ 在 Assistant 写入 Session 前执行可等待转换:
49
+
50
+ ```ts
51
+ agent.on(StreamEventType.BEFORE_ASSISTANT_COMMIT, async (event) => {
52
+ const transformed = await transformText(event.message.text);
53
+ event.message.setText(transformed);
54
+ });
55
+ ```
56
+
57
+ ## 适合做什么
58
+
59
+ - 构建带工具调用的 AI Agent
60
+ - 管理多轮对话、分支会话和可恢复上下文
61
+ - 把 OpenAI-compatible、Anthropic、Gemini 等平台统一到同一套消息模型
62
+ - 解析模型 stream,并把文本、思考内容、工具调用转换成结构化事件
63
+ - 用声明式规则动态注入提示词和运行时上下文
64
+ - 为 Agent 各模块编写可控的单元测试和 fake client 测试
65
+
66
+ ## 核心特性
67
+
68
+ - **模块化架构**:`Message`、`Session`、`Tool`、`Stream`、`Prompt`、`Config`、`Adapter`、`Agent` 都可以单独使用。
69
+ - **统一消息模型**:支持文本、图片、音频、文件、工具调用、工具结果和 thinking 内容。
70
+ - **树形会话管理**:天然支持对话分支、回退、分页、查询和插入。
71
+ - **工具系统**:Builder 风格定义工具,自动生成 JSON Schema,支持生命周期 Hook、MCP 和错误策略。
72
+ - **流式事件**:把模型 stream 解析成 `TEXT_DELTA`、`TOOL_CALL_*`、`MESSAGE_DONE` 等事件。
73
+ - **提示词构建器**:用 `Rule` 定位消息,再注入临时上下文;也支持数组操作管线。
74
+ - **请求配置器**:链式构建 temperature、top_p、max_tokens、response_format 等参数。
75
+ - **低耦合 Provider**:Client、Adapter、Parser 三层可独立替换,内置 OpenAI Compatible、OpenAI Responses、Anthropic 和 Gemini 预设。
76
+ - **流式与非流式**:同一套 Agent、Session 和工具循环同时支持增量 stream 与完整响应。
77
+ - **浏览器安全入口**:根入口不包含 Node.js builtin,本地文件解析通过显式 `./node` 子入口使用。
78
+ - **中断与恢复**:支持 abort、timeout、partial message、continue 和 resume。
79
+ - **工具审批**:支持自动审批、自定义审批、手动审批和审批超时策略。
80
+
81
+ ## 安装
82
+
83
+ ```bash
84
+ npm install @notic/agent-engine
85
+ ```
86
+
87
+ 根据你使用的平台安装对应 SDK:
88
+
89
+ ```bash
90
+ # OpenAI / DeepSeek / Qwen / Kimi 等 OpenAI-compatible 平台
91
+ npm install openai
92
+
93
+ # Anthropic 原生 Messages API
94
+ npm install @anthropic-ai/sdk
95
+
96
+ # Gemini 原生 API
97
+ npm install @google/genai
98
+
99
+ # MCP 集成,可选
100
+ npm install @modelcontextprotocol/sdk
101
+ ```
102
+
103
+ 环境要求:
104
+
105
+ - Node.js >= 18
106
+ - TypeScript 项目推荐开启 `strict`
107
+
108
+ 根入口可直接用于浏览器和 WebView。Node.js 中需要读取本地媒体文件时:
109
+
110
+ ```ts
111
+ import { DefaultMediaResolver } from "@notic/agent-engine/node";
112
+ ```
113
+
114
+ ## 快速开始
115
+
116
+ ### 1. 创建 Agent
117
+
118
+ ```ts
119
+ import OpenAI from "openai";
120
+ import { Agent, RequestConfig, Session } from "@notic/agent-engine";
121
+
122
+ const client = new OpenAI({
123
+ apiKey: process.env.OPENAI_API_KEY,
124
+ baseURL: "https://api.openai.com/v1",
125
+ });
126
+
127
+ const agent = new Agent({
128
+ client,
129
+ model: "gpt-4o-mini",
130
+ session: Session.create("你是一个友好的中文助手。"),
131
+ config: RequestConfig.create().temperature(0.3).maxTokens(1024),
132
+ });
133
+ ```
134
+
135
+ OpenAI-compatible 平台只需要替换 `baseURL` 和 `model`:
136
+
137
+ ```ts
138
+ const client = new OpenAI({
139
+ apiKey: process.env.DEEPSEEK_API_KEY,
140
+ baseURL: "https://api.deepseek.com",
141
+ });
142
+ ```
143
+
144
+ ### 2. 监听流式输出
145
+
146
+ ```ts
147
+ import { StreamEventType } from "@notic/agent-engine";
148
+
149
+ agent.on(StreamEventType.TEXT_DELTA, (event) => {
150
+ process.stdout.write(event.delta);
151
+ });
152
+
153
+ agent.on(StreamEventType.TOOL_EXECUTE_START, (event) => {
154
+ console.log("tool:", event.name);
155
+ });
156
+ ```
157
+
158
+ ### 3. 运行一轮对话
159
+
160
+ ```ts
161
+ const reply = await agent.run("帮我写一个 npm 包介绍。");
162
+ console.log(reply.text);
163
+ ```
164
+
165
+ `Agent` 会自动把用户消息和助手回复写入 `Session`。
166
+
167
+ ## Provider
168
+
169
+ Provider 只负责组合三块可替换能力:
170
+
171
+ - `ModelClient`:发送平台请求,返回流或完整响应。
172
+ - `MessageAdapter`:在统一 `Message` 与平台 JSON 之间转换。
173
+ - `MessageStreamParser`:把平台流事件转换成统一事件和 `Message`。
174
+
175
+ Agent 不需要知道当前使用哪一家模型平台。
176
+
177
+ ### OpenAI Compatible
178
+
179
+ 适用于 OpenAI Chat Completions,以及 DeepSeek、Qwen、Kimi、GLM 等兼容平台:
180
+
181
+ ```ts
182
+ import OpenAI from "openai";
183
+ import {
184
+ Agent,
185
+ OpenAICompatibleProvider,
186
+ Session,
187
+ } from "@notic/agent-engine";
188
+
189
+ const client = new OpenAI({
190
+ apiKey: process.env.DEEPSEEK_API_KEY,
191
+ baseURL: "https://api.deepseek.com",
192
+ });
193
+
194
+ const agent = new Agent({
195
+ provider: new OpenAICompatibleProvider(client),
196
+ model: "deepseek-chat",
197
+ session: Session.create(),
198
+ });
199
+ ```
200
+
201
+ ### OpenAI Responses API
202
+
203
+ ```ts
204
+ import OpenAI from "openai";
205
+ import { Agent, OpenAIResponsesProvider, Session } from "@notic/agent-engine";
206
+
207
+ const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
208
+ const agent = new Agent({
209
+ provider: new OpenAIResponsesProvider(client),
210
+ model: "your-openai-model",
211
+ session: Session.create(),
212
+ });
213
+ ```
214
+
215
+ Responses Provider 会保留 reasoning item、加密推理状态和 function call item,供下一轮工具调用继续使用。
216
+
217
+ ### Anthropic
218
+
219
+ ```ts
220
+ import Anthropic from "@anthropic-ai/sdk";
221
+ import { Agent, AnthropicProvider, Session } from "@notic/agent-engine";
222
+
223
+ const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
224
+ const agent = new Agent({
225
+ provider: new AnthropicProvider(client),
226
+ model: "your-claude-model",
227
+ session: Session.create(),
228
+ });
229
+ ```
230
+
231
+ ### Gemini
232
+
233
+ ```ts
234
+ import { GoogleGenAI } from "@google/genai";
235
+ import { Agent, GeminiProvider, Session } from "@notic/agent-engine";
236
+
237
+ const client = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
238
+ const agent = new Agent({
239
+ provider: new GeminiProvider(client),
240
+ model: "your-gemini-model",
241
+ session: Session.create(),
242
+ });
243
+ ```
244
+
245
+ 所有内置 Provider 都支持:
246
+
247
+ ```ts
248
+ await agent.run("增量输出");
249
+ await agent.run("完整响应", { stream: false });
250
+ ```
251
+
252
+ ## 工具调用示例
253
+
254
+ ```ts
255
+ import { Agent, Param, Session, Tool, ToolKit } from "@notic/agent-engine";
256
+
257
+ const getWeather = Tool.create(async (args) => {
258
+ return {
259
+ city: args.city,
260
+ temperature: 21,
261
+ unit: "celsius",
262
+ };
263
+ })
264
+ .name("get_weather")
265
+ .description("查询城市天气")
266
+ .params(
267
+ Param.string("city").desc("城市名称").required()
268
+ )
269
+ .build();
270
+
271
+ const toolkit = new ToolKit().add(getWeather);
272
+
273
+ const agent = new Agent({
274
+ client,
275
+ model: "your-model",
276
+ session: Session.create("需要外部信息时可以调用工具。"),
277
+ toolkit,
278
+ });
279
+
280
+ const reply = await agent.run("北京今天适合跑步吗?");
281
+ console.log(reply.text);
282
+ ```
283
+
284
+ 当模型发起工具调用时,AgentEngine 会自动执行工具、把结果写回会话,并再次请求模型生成最终答案。
285
+
286
+ ## 模块地图
287
+
288
+ ```text
289
+ AgentEngine
290
+ ├─ Message 统一消息模型:文本、多模态、工具调用、树节点
291
+ ├─ Session 会话树:历史、分支、查询、插入、分页
292
+ ├─ Tool 工具系统:Param、Tool、ToolKit、Hook、MCP
293
+ ├─ Stream 流式解析:chunk -> 结构化事件 -> Message
294
+ ├─ Prompt 提示词构建:Rule、Injection、数组操作管线
295
+ ├─ Config 请求参数:预设、链式配置、三层优先级
296
+ ├─ Client 传输边界:流式请求、完整响应、中断信号
297
+ ├─ Adapter 消息转换:OpenAI、Responses、Anthropic、Gemini
298
+ ├─ Provider Client + Adapter + Parser 的低耦合组合
299
+ ├─ Media 媒体解析:浏览器默认实现 + Node 本地文件子入口
300
+ └─ Agent 编排层:自动循环、审批、中断、恢复
301
+ ```
302
+
303
+ ### Message
304
+
305
+ 统一消息对象,支持:
306
+
307
+ - `Message.user()` / `Message.assistant()` / `Message.system()`
308
+ - 文本、图片、音频、文件
309
+ - 工具调用和工具结果
310
+ - thinking 内容
311
+ - 标签、元数据和树结构
312
+ - `setText()` / `setParts()` 安全替换内容并自动失效缓存
313
+
314
+ ### Session
315
+
316
+ 会话管理器,负责:
317
+
318
+ - root -> cursor 的当前历史路径
319
+ - 对话分支和回退
320
+ - 查询当前分支或全树
321
+ - 在历史中插入消息
322
+ - 在兄弟分支间分页切换
323
+
324
+ ### Tool
325
+
326
+ 工具系统,负责:
327
+
328
+ - 用 `Param` 定义参数 schema
329
+ - 用 `Tool` 包装 TypeScript 函数
330
+ - 用 `ToolKit` 注册并执行多个工具
331
+ - 用 Hook 处理校验、取消、结果改写和错误降级
332
+
333
+ ### Stream
334
+
335
+ 流式解析器,负责:
336
+
337
+ - 文本增量
338
+ - thinking / reasoning 增量
339
+ - 工具调用增量
340
+ - usage
341
+ - 最终 `Message` 组装
342
+
343
+ ### Prompt
344
+
345
+ 提示词构建器,负责:
346
+
347
+ - 按角色、标签、内容或自定义规则定位消息
348
+ - 动态注入 system/user/assistant 消息
349
+ - 控制注入生命周期、概率和优先级
350
+ - 在发送模型前过滤、裁剪或转换上下文
351
+
352
+ ### Config
353
+
354
+ 请求参数配置器,负责:
355
+
356
+ - temperature / top_p / top_k
357
+ - max_tokens
358
+ - stop
359
+ - seed
360
+ - response_format
361
+ - 自定义平台参数
362
+
363
+ ### Adapter
364
+
365
+ 平台适配器,负责:
366
+
367
+ - 把 AgentEngine 的 `Message[]` 序列化成平台请求格式
368
+ - 处理多模态内容
369
+ - 处理工具调用和工具结果
370
+ - 控制 thinking 内容如何回传
371
+
372
+ ### Provider
373
+
374
+ Provider 提供平台预设,但不接管 Agent 执行流程:
375
+
376
+ - `OpenAICompatibleProvider`
377
+ - `OpenAIResponsesProvider`
378
+ - `AnthropicProvider`
379
+ - `GeminiProvider`
380
+ - `Provider.create()` 自定义组合
381
+
382
+ 通过 `provider.supportsComplete` 可以检查是否支持非流式完整响应。
383
+
384
+ ### Agent
385
+
386
+ 智能体编排层,负责:
387
+
388
+ - 管理 `Session`
389
+ - 调用模型 stream
390
+ - 派发事件
391
+ - 在 Assistant 提交 Session 前等待生命周期转换
392
+ - 执行工具循环
393
+ - 处理工具审批
394
+ - 中断、超时、恢复和继续
395
+
396
+ ## 文档
397
+
398
+ 完整教程式 API 文档见:
399
+
400
+ - [docs/API.md](./docs/API.md)
401
+ - [CHANGELOG.md](./CHANGELOG.md)
402
+
403
+ 建议阅读顺序:
404
+
405
+ 1. 安装与最小示例
406
+ 2. Agent:智能体编排
407
+ 3. Tool:工具系统
408
+ 4. Prompt:提示词构建
409
+ 5. Session:会话树
410
+ 6. Adapter / Media:平台与多模态适配
411
+
412
+ ## 测试
413
+
414
+ 项目使用 Node.js 内置测试运行器。
415
+
416
+ ```bash
417
+ npm test
418
+ ```
419
+
420
+ 真实 API 测试需要显式开启,避免普通测试误触发外部请求:
421
+
422
+ ```bash
423
+ RUN_REAL_DEEPSEEK_TESTS=1 DEEPSEEK_API_KEY=sk-... npm run test:real:deepseek
424
+ ```
425
+
426
+ ## 构建
427
+
428
+ ```bash
429
+ npm run build
430
+ ```
431
+
432
+ ## License
433
+
434
+ Apache-2.0