@notic/agent-engine 1.1.0 → 1.2.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 (95) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +409 -726
  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 +38 -0
  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 +74 -1
  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 +17 -0
  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 +45 -16
  27. package/dist/agent/Agent.d.ts.map +1 -1
  28. package/dist/agent/Agent.js +250 -52
  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 +8 -3
  43. package/dist/index.d.ts.map +1 -1
  44. package/dist/index.js +29 -3
  45. package/dist/index.js.map +1 -1
  46. package/dist/message/Message.d.ts.map +1 -1
  47. package/dist/message/Message.js +20 -0
  48. package/dist/message/Message.js.map +1 -1
  49. package/dist/message/MessagePart.d.ts +2 -0
  50. package/dist/message/MessagePart.d.ts.map +1 -1
  51. package/dist/provider/Provider.d.ts +48 -0
  52. package/dist/provider/Provider.d.ts.map +1 -0
  53. package/dist/provider/Provider.js +73 -0
  54. package/dist/provider/Provider.js.map +1 -0
  55. package/dist/provider/index.d.ts +2 -0
  56. package/dist/provider/index.d.ts.map +1 -0
  57. package/dist/provider/index.js +10 -0
  58. package/dist/provider/index.js.map +1 -0
  59. package/dist/session/Session.d.ts +0 -3
  60. package/dist/session/Session.d.ts.map +1 -1
  61. package/dist/session/Session.js +0 -13
  62. package/dist/session/Session.js.map +1 -1
  63. package/dist/stream/AnthropicStreamParser.d.ts +26 -0
  64. package/dist/stream/AnthropicStreamParser.d.ts.map +1 -0
  65. package/dist/stream/AnthropicStreamParser.js +176 -0
  66. package/dist/stream/AnthropicStreamParser.js.map +1 -0
  67. package/dist/stream/GeminiStreamParser.d.ts +21 -0
  68. package/dist/stream/GeminiStreamParser.d.ts.map +1 -0
  69. package/dist/stream/GeminiStreamParser.js +144 -0
  70. package/dist/stream/GeminiStreamParser.js.map +1 -0
  71. package/dist/stream/MessageStreamParser.d.ts +13 -0
  72. package/dist/stream/MessageStreamParser.d.ts.map +1 -0
  73. package/dist/stream/MessageStreamParser.js +3 -0
  74. package/dist/stream/MessageStreamParser.js.map +1 -0
  75. package/dist/stream/OpenAIResponsesStreamParser.d.ts +30 -0
  76. package/dist/stream/OpenAIResponsesStreamParser.d.ts.map +1 -0
  77. package/dist/stream/OpenAIResponsesStreamParser.js +273 -0
  78. package/dist/stream/OpenAIResponsesStreamParser.js.map +1 -0
  79. package/dist/stream/StreamParser.d.ts +2 -1
  80. package/dist/stream/StreamParser.d.ts.map +1 -1
  81. package/dist/stream/StreamParser.js.map +1 -1
  82. package/dist/stream/index.d.ts +4 -0
  83. package/dist/stream/index.d.ts.map +1 -1
  84. package/dist/stream/index.js +7 -1
  85. package/dist/stream/index.js.map +1 -1
  86. package/dist/tool/ToolKit.d.ts +4 -0
  87. package/dist/tool/ToolKit.d.ts.map +1 -1
  88. package/dist/tool/ToolKit.js +50 -14
  89. package/dist/tool/ToolKit.js.map +1 -1
  90. package/dist/tool/index.d.ts +1 -1
  91. package/dist/tool/index.d.ts.map +1 -1
  92. package/dist/tool/index.js +2 -1
  93. package/dist/tool/index.js.map +1 -1
  94. package/docs/API.md +1642 -0
  95. package/package.json +32 -12
package/README.md CHANGED
@@ -1,726 +1,409 @@
1
- # ⚡ AgentEngine
2
-
3
- 一个轻量、优雅、功能完整的 TypeScript AI Agent 框架。
4
-
5
- > **简单的事情简单做,复杂的事情也能做。**
6
-
7
- ```typescript
8
- const agent = new Agent({ client, model: "gpt-4o", session: Session.create("你是AI助手") });
9
- agent.on(StreamEventType.TEXT_DELTA, (e) => process.stdout.write(e.delta));
10
- await agent.run("你好");
11
- ```
12
-
13
- ---
14
-
15
- ## ✨ 核心特性
16
-
17
- - 🌳 **树结构会话管理** — 天然支持对话分支、回退、分页导航
18
- - 🔧 **工具生命周期钩子** — ON_CREATE → ON_VALIDATE → BEFORE_EXECUTE → AFTER_EXECUTE → ON_SERIALIZE / ON_ERROR
19
- - 🌊 **流式解析器** — 无状态纯函数设计,结构化事件驱动
20
- - 📝 **提示词构建器** — 声明式注入规则 + 数组操作管线 + 生命周期 + 概率触发
21
- - ⚙️ **请求参数配置器** — 预设模式 + 链式构建 + 三层优先级合并
22
- - 🔌 **MCP 原生集成** — 一行代码接入,与手动工具完全同构
23
- - 🎨 **多模态支持** — 图片 / 音频 / 文件,媒体资源懒加载
24
- - 💭 **思考内容提取** — 兼容 DeepSeek / Qwen / Claude / Gemini 的推理过程
25
- - 🔄 **多平台适配器** — OpenAI / Anthropic / Gemini,统一消息模型,一个接口换平台
26
- - 🛡️ **工具审批机制** — 自动 / 手动 / 自定义审批,支持超时策略
27
- - ⏸️ **中断与恢复** — 支持中断当前运行并从断点恢复
28
-
29
- ---
30
-
31
- ## 📦 架构总览
32
-
33
- ```
34
- AgentEngine
35
- ├── 📨 Message 统一消息模型(多模态 + 树结构)
36
- ├── 🔌 Adapter 消息序列化适配器(OpenAI / Anthropic / Gemini)
37
- ├── 🖼️ Media 媒体资源懒加载解析器
38
- ├── 💬 Session 会话管理(树结构 + 分支 + 分页)
39
- ├── 🔧 Tool 工具系统(Builder + 生命周期钩子 + MCP)
40
- ├── 🌊 Stream 流式解析器(纯函数 + 结构化事件)
41
- ├── 📝 Prompt 提示词构建器(声明式注入 + 数组操作管线)
42
- ├── ⚙️ Config 请求参数配置器(预设 + 链式构建)
43
- └── 🤖 Agent 智能体编排层(串联一切 + 自动循环 + 审批 + 中断恢复)
44
- ```
45
-
46
- ---
47
-
48
- ## 🚀 快速开始
49
-
50
- ### 安装
51
-
52
- ```bash
53
- npm install @notic/agent-engine
54
- ```
55
-
56
- #### Peer Dependencies
57
-
58
- 根据你使用的平台,安装对应的客户端 SDK:
59
-
60
- ```bash
61
- # OpenAI / DeepSeek / Qwen 等 OpenAI 兼容平台
62
- npm install openai
63
-
64
- # MCP 集成(可选)
65
- npm install @modelcontextprotocol/sdk
66
- ```
67
-
68
- ### 最简示例
69
-
70
- ```typescript
71
- import { Agent, Session, StreamEventType } from "@notic/agent-engine";
72
- import { OpenAI } from "openai";
73
-
74
- const client = new OpenAI({ apiKey: "sk-...", baseURL: "..." });
75
-
76
- const agent = new Agent({
77
- client,
78
- model: "gpt-4o",
79
- session: Session.create("你是一个友好的AI助手"),
80
- });
81
-
82
- agent.on(StreamEventType.TEXT_DELTA, (e) => process.stdout.write(e.delta));
83
-
84
- const reply = await agent.run("你好!");
85
- console.log(reply.text);
86
- ```
87
-
88
- ---
89
-
90
- ## 📖 模块详解
91
-
92
- ### 📨 Message — 统一消息模型
93
-
94
- 树结构消息模型,支持多模态内容,天然支持对话分支。
95
-
96
- ```typescript
97
- // 创建消息
98
- const msg = Message.user("你好");
99
- const msg = Message.system("你是AI助手");
100
- const msg = Message.assistant("你好!");
101
-
102
- // 多模态
103
- const msg = Message.user("看看这张图")
104
- .addImage("https://example.com/photo.jpg")
105
- .addFile("./data.csv")
106
- .tag("multimodal")
107
- .setMeta("priority", "high");
108
-
109
- // 便捷 Getter
110
- msg.text; // 文本内容
111
- msg.thinking; // 思考/推理内容
112
- msg.toolCalls; // 工具调用列表
113
- msg.hasMedia; // 是否含媒体
114
- msg.hasThinking; // 是否含思考
115
-
116
- // 树结构
117
- msg.parent; // 父节点
118
- msg.children; // 子节点列表
119
- msg.getHistory(); // 从根到当前的路径
120
- msg.depth; // 在树中的深度
121
- msg.isRoot; // 是否根节点
122
- msg.isLeaf; // 是否叶子节点
123
-
124
- // 序列化与反序列化
125
- const json = msg.toJSON();
126
- const restored = Message.fromJSON(json);
127
- ```
128
-
129
- #### 消息内容类型 (MessagePart)
130
-
131
- | 类型 | 说明 |
132
- | ---------------- | ------------------------- |
133
- | `TextPart` | 文本内容 |
134
- | `ImagePart` | 图片(URL / data URI / 本地路径) |
135
- | `AudioPart` | 音频 |
136
- | `FilePart` | 文件附件 |
137
- | `ToolCallPart` | LLM 发起的工具调用 |
138
- | `ToolResultPart` | 工具执行结果 |
139
- | `ThinkingPart` | 模型推理/思考过程 |
140
-
141
- ### 💬 Session — 会话管理
142
-
143
- 基于树结构的会话管理器,通过光标(cursor)追踪当前对话位置。
144
-
145
- ```typescript
146
- const session = Session.create("你是AI助手");
147
-
148
- // 基本对话
149
- session.addUser("你好");
150
- session.addAssistant(reply);
151
- const history = session.history(); // [System, User, Assistant]
152
-
153
- // 分支对话 — 回退并分叉
154
- const branchPoint = session.cursor.parent;
155
- session.rewind(branchPoint);
156
- session.addUser("换个话题"); // 自动产生新分支
157
-
158
- // 分支导航
159
- session.allLeaves; // 所有分支末端
160
- session.branches; // 所有分支路径
161
-
162
- // 分页器 — 在分支间切换
163
- const pag = session.paginators[0];
164
- pag.next(); // 下一个分支
165
- pag.prev(); // 上一个分支
166
- pag.goTo(2); // 跳转到第3个分支
167
- pag.total; // 总分支数
168
-
169
- // 系统提示词
170
- session.systemPrompt = "新的系统提示";
171
-
172
- // Token 统计
173
- session.totalUsage; // 全树累计 Usage(带缓存)
174
-
175
- // 序列化
176
- const json = session.toJSON();
177
- const restored = Session.fromJSON(json);
178
- ```
179
-
180
- #### Inserter — 命令式插入器
181
-
182
- 游标式插入器,通过移动光标定位插入点,支持事务提交。执行后自动报废。
183
-
184
- ```typescript
185
- const inserter = session.inserter;
186
-
187
- inserter
188
- .top() // 光标移到顶部
189
- .insertAssistantAfter("注入内容") // 在光标后插入
190
- .execute(); // 事务提交
191
-
192
- // 按标签定位
193
- inserter
194
- .moveByTags(["context"])
195
- .insertUserBefore("补充信息")
196
- .execute();
197
-
198
- // 按内容定位
199
- inserter
200
- .moveByContent(["关键词"])
201
- .insertAfter(Message.system("补充上下文"))
202
- .execute();
203
- ```
204
-
205
- #### Query — 查询系统
206
-
207
- ```typescript
208
- const query = session.query;
209
-
210
- // 在当前分支 / 全树中查找
211
- query.findByContent(["天气"], { scope: "branch" });
212
- query.findByTags(["important"], { scope: "tree" });
213
- query.findByRole(Role.User);
214
- query.findFirst({ content: ["关键词"] });
215
- query.findLast({ tags: ["context"] });
216
-
217
- // 自定义规则
218
- query.findBy((msg) => msg.hasThinking, "tree");
219
- ```
220
-
221
- ### 🔧 Tool — 工具系统
222
-
223
- Builder 模式定义工具,完整的生命周期钩子。
224
-
225
- ```typescript
226
- const weatherTool = Tool.create(async (args, ctx) => {
227
- ctx.throwIfAborted(); // 支持中断检查
228
- const city = args.city as string;
229
- return await fetchWeather(city);
230
- })
231
- .name("get_weather")
232
- .description("获取指定城市的天气")
233
- .params(
234
- Param.string("city").desc("城市名称").required(),
235
- Param.string("unit").desc("温度单位").enum(["celsius", "fahrenheit"]),
236
- )
237
- // 生命周期钩子
238
- .on(Hook.BEFORE_EXECUTE, (ctx) => {
239
- console.log(`即将查询: ${ctx.arguments.city}`);
240
- // ctx.cancel("理由") 可取消执行
241
- })
242
- .on(Hook.AFTER_EXECUTE, (ctx) => {
243
- // 可改写结果
244
- ctx.result = { ...ctx.result, cached: true };
245
- })
246
- .on(Hook.ON_ERROR, (ctx) => {
247
- // 错误降级
248
- ctx.result = "天气服务暂不可用";
249
- })
250
- .on(Hook.ON_SERIALIZE, (ctx) => {
251
- // 自定义返回给 LLM 的内容
252
- })
253
- .build();
254
- ```
255
-
256
- #### 参数定义
257
-
258
- 支持嵌套对象与数组:
259
-
260
- ```typescript
261
- // 嵌套对象
262
- Param.object("address", [
263
- Param.string("city").desc("城市").required(),
264
- Param.object("geo", [
265
- Param.number("lat").desc("纬度").required(),
266
- Param.number("lng").desc("经度").required(),
267
- ]),
268
- ]);
269
-
270
- // 对象数组
271
- Param.array("items", [
272
- Param.string("name").desc("名称").required(),
273
- Param.number("count").desc("数量"),
274
- ]);
275
- ```
276
-
277
- #### 生命周期
278
-
279
- ```
280
- ON_CREATE → ON_VALIDATE → BEFORE_EXECUTE → execute → AFTER_EXECUTE → ON_SERIALIZE
281
- ↓
282
- ON_ERROR
283
- ```
284
-
285
- > **注意**:`ON_CREATE` 和 `ON_VALIDATE` 中的异常也会触发 `ON_ERROR`。整个生命周期共享同一个 `Context` 实例。
286
-
287
- #### ToolKit — 工具包管理
288
-
289
- ```typescript
290
- const toolkit = new ToolKit()
291
- .add(weatherTool, searchTool);
292
-
293
- // MCP 一行接入
294
- await toolkit.addMCP(mcpClient);
295
-
296
- // 传给 LLM
297
- const tools = toolkit.schemas;
298
-
299
- // 执行
300
- const result = await toolkit.execute(toolCallPart);
301
- const results = await toolkit.executeAll(toolCallParts);
302
-
303
- // 执行选项
304
- const result = await toolkit.execute(toolCallPart, {
305
- signal: abortController.signal,
306
- errorPolicy: "return_to_model", // 或 "throw"
307
- });
308
- ```
309
-
310
- #### MCP 集成
311
-
312
- ```typescript
313
- import { Client } from "@modelcontextprotocol/sdk/client/index.js";
314
- import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
315
-
316
- const transport = new StdioClientTransport({
317
- command: "npx",
318
- args: ["-y", "@modelcontextprotocol/server-filesystem", "./"],
319
- });
320
-
321
- const mcpClient = new Client({ name: "my-app", version: "1.0.0" });
322
- await mcpClient.connect(transport);
323
-
324
- const toolkit = new ToolKit();
325
- await toolkit.addMCP(mcpClient); // 自动发现所有工具,与手动工具完全同构
326
- ```
327
-
328
- ### 🌊 Stream — 流式解析器
329
-
330
- 无状态纯函数设计,将 OpenAI 流式 chunk 解析为结构化事件。
331
-
332
- ```typescript
333
- const parser = new StreamParser();
334
-
335
- for await (const chunk of stream) {
336
- const events = parser.feed(chunk);
337
- for (const event of events) {
338
- switch (event.type) {
339
- case StreamEventType.THINKING_DELTA:
340
- process.stdout.write(event.delta); // 思考过程
341
- break;
342
- case StreamEventType.TEXT_DELTA:
343
- process.stdout.write(event.delta); // 文本增量
344
- break;
345
- case StreamEventType.TOOL_CALL_START:
346
- console.log(`工具: ${event.name}`);
347
- break;
348
- }
349
- }
350
- }
351
-
352
- const finalEvents = parser.finish(); // TEXT_DONE, THINKING_DONE, MESSAGE_DONE
353
-
354
- // 已组装的消息快照
355
- parser.snapshot; // 当前 Message
356
- parser.finishReason; // "stop" | "tool_calls" | ...
357
- parser.usage; // 流返回的 Token 用量(如有 enable_usage)
358
- ```
359
-
360
- #### 事件类型
361
-
362
- | 事件 | 说明 |
363
- | ------------------------ | ------- |
364
- | `THINKING_DELTA` | 思考/推理增量 |
365
- | `THINKING_DONE` | 思考完成 |
366
- | `TEXT_DELTA` | 文本增量 |
367
- | `TEXT_DONE` | 文本完成 |
368
- | `TOOL_CALL_START` | 工具调用开始 |
369
- | `TOOL_CALL_DELTA` | 工具参数增量 |
370
- | `TOOL_CALL_DONE` | 工具调用完成 |
371
- | `TOOL_APPROVAL_REQUIRED` | 工具需要审批 |
372
- | `TOOL_APPROVAL_ACCEPTED` | 审批通过 |
373
- | `TOOL_APPROVAL_REJECTED` | 审批拒绝 |
374
- | `TOOL_EXECUTE_START` | 工具执行开始 |
375
- | `TOOL_EXECUTE_DONE` | 工具执行完成 |
376
- | `TOOL_EXECUTE_ERROR` | 工具执行失败 |
377
- | `MESSAGE_DONE` | 消息组装完成 |
378
- | `TURN_START` | 新一轮循环开始 |
379
- | `TURN_END` | 一轮循环结束 |
380
- | `ERROR` | 错误 |
381
-
382
- ### 📝 PromptBuilder — 提示词构建器
383
-
384
- 声明式注入规则,在不修改原始 Session 的情况下向上下文注入临时消息。
385
-
386
- ```typescript
387
- const builder = new PromptBuilder();
388
-
389
- // 注入时间感知(永久)
390
- builder.injectSystem(Rule.top().after(), "当前时间:2025年7月16日");
391
-
392
- // 注入临时约束(只生效3轮)
393
- builder.injectSystem(
394
- Rule.byRole(Role.User).last().before(),
395
- "请用英文回复",
396
- 3 // life = 3
397
- );
398
-
399
- // 概率触发(50%概率注入)
400
- builder.injectSystem(
401
- Rule.bottom().before(),
402
- "添加一个有趣的彩蛋",
403
- { life: -1, probability: 0.5 }
404
- );
405
-
406
- // 带优先级的注入
407
- builder.injectSystem(
408
- Rule.top().after(),
409
- "高优先级内容",
410
- { life: -1, priority: 0 } // 越小越先执行
411
- );
412
-
413
- // 构建最终上下文
414
- const context = builder.build(session.history());
415
- // 原始 session 不受影响
416
- ```
417
-
418
- #### 数组操作管线
419
-
420
- 除了声明式注入,还支持对消息数组进行管线操作:
421
-
422
- ```typescript
423
- // 过滤、截取、自由变换
424
- builder
425
- .filter((msg) => msg.role !== Role.Tool, "remove-tool") // 按条件过滤
426
- .slice(-10, undefined, "keep-recent") // 只保留最近10条
427
- .removeWhere((msg) => msg.hasTag("temp"), "clean-temp") // 移除临时消息
428
- .map((msg) => { /* 变换 */ return msg; }, "transform") // 映射变换
429
- .transform((msgs) => { /* 自由变换 */ return msgs; }); // 完全自定义
430
-
431
- // 按标签管理操作
432
- builder.removeOperation("remove-tool"); // 移除指定操作
433
- builder.clearOperations(); // 清空所有操作
434
- ```
435
-
436
- #### 构建策略
437
-
438
- ```typescript
439
- // batch(默认):所有 Injection 基于原始 history 定位
440
- builder.build(history, { strategy: "batch" });
441
-
442
- // immediate:后续 Injection 可看到前序 Injection 的插入结果
443
- builder.build(history, { strategy: "immediate" });
444
- ```
445
-
446
- #### Rule — 声明式定位规则
447
-
448
- ```typescript
449
- // 位置定位
450
- Rule.top().after() // 第一条之后
451
- Rule.bottom().before() // 最后一条之前
452
- Rule.index(2).after() // 第3条之后
453
- Rule.index(-1).before() // 倒数第1条之前
454
-
455
- // 角色定位
456
- Rule.byRole(Role.User).last().before() // 最后一条 User 之前
457
- Rule.byRole(Role.User).first().after() // 第一条 User 之后
458
- Rule.byRole(Role.User).all().before() // 每条 User 之前
459
-
460
- // 内容/标签定位
461
- Rule.byContent(["天气"]).after()
462
- Rule.byTags(["context"]).before()
463
- Rule.by((msg, idx) => msg.hasTag("inject-point")).after()
464
-
465
- // 扫描深度 + 方向
466
- Rule.byContent(["关键词"]).scanDepth(5).scanReverse().after() // 只扫描最近5条
467
- Rule.byContent(["关键词"]).scanDepth(10).scanForward().after() // 只扫描前10条
468
-
469
- // 排序(同位置多条注入)
470
- Rule.top().after().order(1) // 排在前面
471
- Rule.top().after().order(2) // 排在后面
472
-
473
- // 偏移
474
- Rule.byRole(Role.System).first().offset(1).after()
475
- ```
476
-
477
- #### 生命周期 & 概率
478
-
479
- ```typescript
480
- // life = -1 → 永久
481
- // life = N → 剩余N次,每次 build 后递减
482
- // life = 0 → 已过期,跳过
483
-
484
- const inj = builder.inject(rule, message, { life: 5, probability: 0.8 });
485
-
486
- inj.enabled; // 手动开关
487
- inj.life; // 剩余次数
488
- inj.isActive; // 存活且启用
489
- inj.probability; // 触发概率
490
-
491
- builder.disable(inj); // 暂停(不消耗 life)
492
- builder.enable(inj); // 恢复
493
- builder.prune(); // 清理过期注入
494
-
495
- // 查询
496
- builder.aliveCount; // 存活注入数
497
- builder.activeCount; // 活跃注入数
498
- builder.expiredCount; // 过期注入数
499
- ```
500
-
501
- ### ⚙️ RequestConfig — 请求参数配置器
502
-
503
- ```typescript
504
- // 预设模式
505
- const config = RequestConfig.precise(); // 低温度、低随机
506
- const config = RequestConfig.balanced(); // 适中
507
- const config = RequestConfig.creative(); // 高温度、高创意
508
-
509
- // 链式配置
510
- const config = RequestConfig.create()
511
- .temperature(0.8)
512
- .topP(0.95)
513
- .topK(40)
514
- .maxTokens(2048)
515
- .frequencyPenalty(0.1)
516
- .presencePenalty(0.2)
517
- .stop("n", "END")
518
- .seed(42)
519
- .responseFormat("json_object")
520
- .set("custom_key", value); // 自定义参数
521
-
522
- // 操作
523
- const cloned = config.clone();
524
- const merged = base.merge(override); // override 优先
525
- const params = config.build(); // → Record<string, unknown>
526
- ```
527
-
528
- #### 参数优先级
529
-
530
- ```
531
- RequestConfig(最低) → requestOptions → run()的 options(最高)
532
- ```
533
-
534
- ### 🤖 Agent — 智能体
535
-
536
- 串联所有组件,实现完整的 Agent 循环。
537
-
538
- ```typescript
539
- const agent = new Agent({
540
- client, // OpenAI 兼容客户端
541
- model: "gpt-4o", // 模型名
542
- session: Session.create("..."), // 会话
543
- toolkit, // 工具包(可选)
544
- promptBuilder, // 提示词构建器(可选)
545
- config: RequestConfig.balanced(), // 请求配置(可选)
546
- adapter: new OpenAIAdapter(), // 适配器(可选,默认 OpenAI)
547
- maxTurns: 10, // 最大循环轮次(可选)
548
- toolApproval: async (req) => { // 工具审批(可选)
549
- return confirm(`允许执行 ${req.name}?`);
550
- },
551
- toolErrorPolicy: "return_to_model", // 工具错误策略(可选)
552
- });
553
-
554
- // 事件监听(类型安全)
555
- agent
556
- .on(StreamEventType.THINKING_DELTA, (e) => { /* 思考增量 */ })
557
- .on(StreamEventType.TEXT_DELTA, (e) => { /* 文本增量 */ })
558
- .on(StreamEventType.TOOL_CALL_START, (e) => { /* 工具调用 */ })
559
- .on(StreamEventType.TOOL_EXECUTE_DONE, (e) => { /* 工具结果 */ })
560
- .on(StreamEventType.TOOL_APPROVAL_REQUIRED, (e) => { /* 等待审批 */ });
561
-
562
- // 运行
563
- const reply = await agent.run("你好");
564
- reply.text; // 回复文本
565
- reply.thinking; // 思考内容
566
- reply.usage; // Token 用量
567
- reply.toolCalls; // 工具调用
568
- ```
569
-
570
- #### 多种运行方式
571
-
572
- ```typescript
573
- // 标准运行
574
- const reply = await agent.run("你好");
575
-
576
- // 传入任意消息运行
577
- const reply = await agent.runWith(Message.user("你好").addImage("photo.jpg"));
578
-
579
- // 直接传入消息列表运行(不走 Session)
580
- const reply = await agent.runRaw(messages);
581
-
582
- // 运行选项
583
- const reply = await agent.run("你好", {
584
- signal: abortController.signal, // 中断信号
585
- timeoutMs: 30000, // 超时时间
586
- });
587
- ```
588
-
589
- #### 中断与恢复
590
-
591
- ```typescript
592
- // 中断
593
- agent.abort("用户取消");
594
-
595
- // 恢复运行
596
- if (agent.canResume) {
597
- const reply = await agent.resume();
598
- }
599
-
600
- // 继续对话(自动判断恢复或继续)
601
- const reply = await agent.continue({ prompt: "继续" });
602
- ```
603
-
604
- #### 工具审批
605
-
606
- ```typescript
607
- // 方式一:自动审批(handler 函数)
608
- agent.setToolApproval(async (req) => {
609
- if (req.name === "dangerous_tool") return false;
610
- return true;
611
- });
612
-
613
- // 方式二:手动审批模式
614
- agent.setToolApprovalMode("manual");
615
- agent.on(StreamEventType.TOOL_APPROVAL_REQUIRED, (e) => {
616
- // 外部 UI 展示审批请求
617
- showApprovalDialog(e.approvalId, e.name);
618
- });
619
- // 用户操作后
620
- agent.approve(approvalId);
621
- agent.reject(approvalId, "不允许");
622
- ```
623
-
624
- #### 自动循环
625
-
626
- `agent.run()` 自动完成:
627
-
628
- ```
629
- 用户输入 → Session.addUser
630
- → PromptBuilder.build(注入)
631
- → Adapter.serialize(序列化)
632
- → LLM 流式调用
633
- → StreamParser 解析
634
- → 有 tool_calls?
635
- → 工具审批(auto / manual / handler)
636
- → ToolKit.execute → 结果回传 → 再次调用 LLM
637
- → 无 tool_calls → Session.addAssistant → 返回结果
638
- ```
639
-
640
- ---
641
-
642
- ## 🔌 Adapter — 适配器
643
-
644
- 通过实现 `MessageAdapter` 接口适配不同 API 平台:
645
-
646
- ```typescript
647
- interface MessageAdapter {
648
- readonly capabilities?: AdapterCapabilities;
649
- serialize(messages: Message[], options?: SerializeOptions): Promise<SerializedResult>;
650
- deserialize(raw: unknown): Message;
651
- }
652
- ```
653
-
654
- ### 内置适配器
655
-
656
- | 平台 | 适配器 | 说明 |
657
- | ---------------- | ------------------ | ------------------- |
658
- | OpenAI | `OpenAIAdapter` | 支持所有 OpenAI 兼容 API |
659
- | DeepSeek | `OpenAIAdapter` | OpenAI 兼容 |
660
- | 通义千问 (Qwen) | `OpenAIAdapter` | OpenAI 兼容 |
661
- | Kimi (Moonshot) | `OpenAIAdapter` | OpenAI 兼容 |
662
- | GLM (智谱) | `OpenAIAdapter` | OpenAI 兼容 |
663
- | MiniMax | `OpenAIAdapter` | OpenAI 兼容 |
664
- | Anthropic Claude | `AnthropicAdapter` | 原生 Claude API 适配 |
665
- | Google Gemini | `GeminiAdapter` | 原生 Gemini API 适配 |
666
-
667
- ### 思考内容序列化
668
-
669
- 通过 `SerializeOptions.thinking` 控制思考内容的回传方式:
670
-
671
- ```typescript
672
- await agent.run("你好", {
673
- serializeOptions: {
674
- thinking: {
675
- mode: "auto", // "none" | "native" | "message" | "auto"
676
- scope: "last", // "none" | "last" | "tool_call" | "all"
677
- }
678
- }
679
- });
680
- ```
681
-
682
- 各模型思考字段兼容:
683
-
684
- | 模型 | 字段名 | 支持 |
685
- | ----------------- | ------------------- |:---:|
686
- | DeepSeek Reasoner | `reasoning_content` | ✅ |
687
- | Qwen (思考模式) | `reasoning_content` | ✅ |
688
- | Claude (thinking) | `thinking` block | ✅ |
689
- | Gemini (thinking) | `thought: true` | ✅ |
690
-
691
- ---
692
-
693
- ## 📂 模块结构
694
-
695
- ```
696
- @notic/agent-engine
697
- ├── message/ 统一消息模型(树结构 + 多模态 + 序列化)
698
- ├── adapter/ 消息序列化适配器(OpenAI / Anthropic / Gemini)
699
- ├── media/ 媒体资源懒加载解析器
700
- ├── session/ 会话管理(树结构 + 分支 + 分页 + 插入器 + 查询)
701
- ├── tool/ 工具系统(Builder + 生命周期钩子 + MCP + 审批)
702
- ├── stream/ 流式解析器(纯函数 + 结构化事件)
703
- ├── prompt/ 提示词构建器(声明式注入 + 数组操作管线)
704
- ├── config/ 请求参数配置器(预设 + 链式构建)
705
- ├── agent/ 智能体编排层(串联一切 + 自动循环 + 中断恢复)
706
- └── utils/ 工具函数
707
- ```
708
-
709
- ---
710
-
711
- ## 📖 API 文档
712
-
713
- 完整的 API 参考文档请查看 [docs/API.md](./docs/API.md)。
714
-
715
- ---
716
-
717
- ## 🌍 环境要求
718
-
719
- - Node.js >= 18.0.0
720
- - TypeScript >= 5.5(推荐)
721
-
722
- ---
723
-
724
- ## 📄 License
725
-
726
- [Apache-2.0](./LICENSE)
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
+ ## 适合做什么
42
+
43
+ - 构建带工具调用的 AI Agent
44
+ - 管理多轮对话、分支会话和可恢复上下文
45
+ - 把 OpenAI-compatible、Anthropic、Gemini 等平台统一到同一套消息模型
46
+ - 解析模型 stream,并把文本、思考内容、工具调用转换成结构化事件
47
+ - 用声明式规则动态注入提示词和运行时上下文
48
+ - 为 Agent 各模块编写可控的单元测试和 fake client 测试
49
+
50
+ ## 核心特性
51
+
52
+ - **模块化架构**:`Message`、`Session`、`Tool`、`Stream`、`Prompt`、`Config`、`Adapter`、`Agent` 都可以单独使用。
53
+ - **统一消息模型**:支持文本、图片、音频、文件、工具调用、工具结果和 thinking 内容。
54
+ - **树形会话管理**:天然支持对话分支、回退、分页、查询和插入。
55
+ - **工具系统**:Builder 风格定义工具,自动生成 JSON Schema,支持生命周期 Hook、MCP 和错误策略。
56
+ - **流式事件**:把模型 stream 解析成 `TEXT_DELTA`、`TOOL_CALL_*`、`MESSAGE_DONE` 等事件。
57
+ - **提示词构建器**:用 `Rule` 定位消息,再注入临时上下文;也支持数组操作管线。
58
+ - **请求配置器**:链式构建 temperature、top_p、max_tokens、response_format 等参数。
59
+ - **低耦合 Provider**:Client、Adapter、Parser 三层可独立替换,内置 OpenAI Compatible、OpenAI Responses、Anthropic 和 Gemini 预设。
60
+ - **流式与非流式**:同一套 Agent、Session 和工具循环同时支持增量 stream 与完整响应。
61
+ - **中断与恢复**:支持 abort、timeout、partial message、continue 和 resume。
62
+ - **工具审批**:支持自动审批、自定义审批、手动审批和审批超时策略。
63
+
64
+ ## 安装
65
+
66
+ ```bash
67
+ npm install @notic/agent-engine
68
+ ```
69
+
70
+ 根据你使用的平台安装对应 SDK:
71
+
72
+ ```bash
73
+ # OpenAI / DeepSeek / Qwen / Kimi 等 OpenAI-compatible 平台
74
+ npm install openai
75
+
76
+ # Anthropic 原生 Messages API
77
+ npm install @anthropic-ai/sdk
78
+
79
+ # Gemini 原生 API
80
+ npm install @google/genai
81
+
82
+ # MCP 集成,可选
83
+ npm install @modelcontextprotocol/sdk
84
+ ```
85
+
86
+ 环境要求:
87
+
88
+ - Node.js >= 18
89
+ - TypeScript 项目推荐开启 `strict`
90
+
91
+ ## 快速开始
92
+
93
+ ### 1. 创建 Agent
94
+
95
+ ```ts
96
+ import OpenAI from "openai";
97
+ import { Agent, RequestConfig, Session } from "@notic/agent-engine";
98
+
99
+ const client = new OpenAI({
100
+ apiKey: process.env.OPENAI_API_KEY,
101
+ baseURL: "https://api.openai.com/v1",
102
+ });
103
+
104
+ const agent = new Agent({
105
+ client,
106
+ model: "gpt-4o-mini",
107
+ session: Session.create("你是一个友好的中文助手。"),
108
+ config: RequestConfig.create().temperature(0.3).maxTokens(1024),
109
+ });
110
+ ```
111
+
112
+ OpenAI-compatible 平台只需要替换 `baseURL` 和 `model`:
113
+
114
+ ```ts
115
+ const client = new OpenAI({
116
+ apiKey: process.env.DEEPSEEK_API_KEY,
117
+ baseURL: "https://api.deepseek.com",
118
+ });
119
+ ```
120
+
121
+ ### 2. 监听流式输出
122
+
123
+ ```ts
124
+ import { StreamEventType } from "@notic/agent-engine";
125
+
126
+ agent.on(StreamEventType.TEXT_DELTA, (event) => {
127
+ process.stdout.write(event.delta);
128
+ });
129
+
130
+ agent.on(StreamEventType.TOOL_EXECUTE_START, (event) => {
131
+ console.log("tool:", event.name);
132
+ });
133
+ ```
134
+
135
+ ### 3. 运行一轮对话
136
+
137
+ ```ts
138
+ const reply = await agent.run("帮我写一个 npm 包介绍。");
139
+ console.log(reply.text);
140
+ ```
141
+
142
+ `Agent` 会自动把用户消息和助手回复写入 `Session`。
143
+
144
+ ## Provider
145
+
146
+ Provider 只负责组合三块可替换能力:
147
+
148
+ - `ModelClient`:发送平台请求,返回流或完整响应。
149
+ - `MessageAdapter`:在统一 `Message` 与平台 JSON 之间转换。
150
+ - `MessageStreamParser`:把平台流事件转换成统一事件和 `Message`。
151
+
152
+ Agent 不需要知道当前使用哪一家模型平台。
153
+
154
+ ### OpenAI Compatible
155
+
156
+ 适用于 OpenAI Chat Completions,以及 DeepSeek、Qwen、Kimi、GLM 等兼容平台:
157
+
158
+ ```ts
159
+ import OpenAI from "openai";
160
+ import {
161
+ Agent,
162
+ OpenAICompatibleProvider,
163
+ Session,
164
+ } from "@notic/agent-engine";
165
+
166
+ const client = new OpenAI({
167
+ apiKey: process.env.DEEPSEEK_API_KEY,
168
+ baseURL: "https://api.deepseek.com",
169
+ });
170
+
171
+ const agent = new Agent({
172
+ provider: new OpenAICompatibleProvider(client),
173
+ model: "deepseek-chat",
174
+ session: Session.create(),
175
+ });
176
+ ```
177
+
178
+ ### OpenAI Responses API
179
+
180
+ ```ts
181
+ import OpenAI from "openai";
182
+ import { Agent, OpenAIResponsesProvider, Session } from "@notic/agent-engine";
183
+
184
+ const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
185
+ const agent = new Agent({
186
+ provider: new OpenAIResponsesProvider(client),
187
+ model: "your-openai-model",
188
+ session: Session.create(),
189
+ });
190
+ ```
191
+
192
+ Responses Provider 会保留 reasoning item、加密推理状态和 function call item,供下一轮工具调用继续使用。
193
+
194
+ ### Anthropic
195
+
196
+ ```ts
197
+ import Anthropic from "@anthropic-ai/sdk";
198
+ import { Agent, AnthropicProvider, Session } from "@notic/agent-engine";
199
+
200
+ const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
201
+ const agent = new Agent({
202
+ provider: new AnthropicProvider(client),
203
+ model: "your-claude-model",
204
+ session: Session.create(),
205
+ });
206
+ ```
207
+
208
+ ### Gemini
209
+
210
+ ```ts
211
+ import { GoogleGenAI } from "@google/genai";
212
+ import { Agent, GeminiProvider, Session } from "@notic/agent-engine";
213
+
214
+ const client = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
215
+ const agent = new Agent({
216
+ provider: new GeminiProvider(client),
217
+ model: "your-gemini-model",
218
+ session: Session.create(),
219
+ });
220
+ ```
221
+
222
+ 所有内置 Provider 都支持:
223
+
224
+ ```ts
225
+ await agent.run("增量输出");
226
+ await agent.run("完整响应", { stream: false });
227
+ ```
228
+
229
+ ## 工具调用示例
230
+
231
+ ```ts
232
+ import { Agent, Param, Session, Tool, ToolKit } from "@notic/agent-engine";
233
+
234
+ const getWeather = Tool.create(async (args) => {
235
+ return {
236
+ city: args.city,
237
+ temperature: 21,
238
+ unit: "celsius",
239
+ };
240
+ })
241
+ .name("get_weather")
242
+ .description("查询城市天气")
243
+ .params(
244
+ Param.string("city").desc("城市名称").required()
245
+ )
246
+ .build();
247
+
248
+ const toolkit = new ToolKit().add(getWeather);
249
+
250
+ const agent = new Agent({
251
+ client,
252
+ model: "your-model",
253
+ session: Session.create("需要外部信息时可以调用工具。"),
254
+ toolkit,
255
+ });
256
+
257
+ const reply = await agent.run("北京今天适合跑步吗?");
258
+ console.log(reply.text);
259
+ ```
260
+
261
+ 当模型发起工具调用时,AgentEngine 会自动执行工具、把结果写回会话,并再次请求模型生成最终答案。
262
+
263
+ ## 模块地图
264
+
265
+ ```text
266
+ AgentEngine
267
+ ├─ Message 统一消息模型:文本、多模态、工具调用、树节点
268
+ ├─ Session 会话树:历史、分支、查询、插入、分页
269
+ ├─ Tool 工具系统:Param、Tool、ToolKit、Hook、MCP
270
+ ├─ Stream 流式解析:chunk -> 结构化事件 -> Message
271
+ ├─ Prompt 提示词构建:Rule、Injection、数组操作管线
272
+ ├─ Config 请求参数:预设、链式配置、三层优先级
273
+ ├─ Client 传输边界:流式请求、完整响应、中断信号
274
+ ├─ Adapter 消息转换:OpenAI、Responses、Anthropic、Gemini
275
+ ├─ Provider Client + Adapter + Parser 的低耦合组合
276
+ ├─ Media 媒体解析:data URI、HTTP、本地文件
277
+ └─ Agent 编排层:自动循环、审批、中断、恢复
278
+ ```
279
+
280
+ ### Message
281
+
282
+ 统一消息对象,支持:
283
+
284
+ - `Message.user()` / `Message.assistant()` / `Message.system()`
285
+ - 文本、图片、音频、文件
286
+ - 工具调用和工具结果
287
+ - thinking 内容
288
+ - 标签、元数据和树结构
289
+
290
+ ### Session
291
+
292
+ 会话管理器,负责:
293
+
294
+ - root -> cursor 的当前历史路径
295
+ - 对话分支和回退
296
+ - 查询当前分支或全树
297
+ - 在历史中插入消息
298
+ - 在兄弟分支间分页切换
299
+
300
+ ### Tool
301
+
302
+ 工具系统,负责:
303
+
304
+ - 用 `Param` 定义参数 schema
305
+ - 用 `Tool` 包装 TypeScript 函数
306
+ - 用 `ToolKit` 注册并执行多个工具
307
+ - 用 Hook 处理校验、取消、结果改写和错误降级
308
+
309
+ ### Stream
310
+
311
+ 流式解析器,负责:
312
+
313
+ - 文本增量
314
+ - thinking / reasoning 增量
315
+ - 工具调用增量
316
+ - usage
317
+ - 最终 `Message` 组装
318
+
319
+ ### Prompt
320
+
321
+ 提示词构建器,负责:
322
+
323
+ - 按角色、标签、内容或自定义规则定位消息
324
+ - 动态注入 system/user/assistant 消息
325
+ - 控制注入生命周期、概率和优先级
326
+ - 在发送模型前过滤、裁剪或转换上下文
327
+
328
+ ### Config
329
+
330
+ 请求参数配置器,负责:
331
+
332
+ - temperature / top_p / top_k
333
+ - max_tokens
334
+ - stop
335
+ - seed
336
+ - response_format
337
+ - 自定义平台参数
338
+
339
+ ### Adapter
340
+
341
+ 平台适配器,负责:
342
+
343
+ - 把 AgentEngine 的 `Message[]` 序列化成平台请求格式
344
+ - 处理多模态内容
345
+ - 处理工具调用和工具结果
346
+ - 控制 thinking 内容如何回传
347
+
348
+ ### Provider
349
+
350
+ Provider 提供平台预设,但不接管 Agent 执行流程:
351
+
352
+ - `OpenAICompatibleProvider`
353
+ - `OpenAIResponsesProvider`
354
+ - `AnthropicProvider`
355
+ - `GeminiProvider`
356
+ - `Provider.create()` 自定义组合
357
+
358
+ 通过 `provider.supportsComplete` 可以检查是否支持非流式完整响应。
359
+
360
+ ### Agent
361
+
362
+ 智能体编排层,负责:
363
+
364
+ - 管理 `Session`
365
+ - 调用模型 stream
366
+ - 派发事件
367
+ - 执行工具循环
368
+ - 处理工具审批
369
+ - 中断、超时、恢复和继续
370
+
371
+ ## 文档
372
+
373
+ 完整教程式 API 文档见:
374
+
375
+ - [docs/API.md](./docs/API.md)
376
+ - [CHANGELOG.md](./CHANGELOG.md)
377
+
378
+ 建议阅读顺序:
379
+
380
+ 1. 安装与最小示例
381
+ 2. Agent:智能体编排
382
+ 3. Tool:工具系统
383
+ 4. Prompt:提示词构建
384
+ 5. Session:会话树
385
+ 6. Adapter / Media:平台与多模态适配
386
+
387
+ ## 测试
388
+
389
+ 项目使用 Node.js 内置测试运行器。
390
+
391
+ ```bash
392
+ npm test
393
+ ```
394
+
395
+ 真实 API 测试需要显式开启,避免普通测试误触发外部请求:
396
+
397
+ ```bash
398
+ RUN_REAL_DEEPSEEK_TESTS=1 DEEPSEEK_API_KEY=sk-... npm run test:real:deepseek
399
+ ```
400
+
401
+ ## 构建
402
+
403
+ ```bash
404
+ npm run build
405
+ ```
406
+
407
+ ## License
408
+
409
+ Apache-2.0