docs: 添加 ag-ui 和 crewai 项目 skills 及更新文档

2026-03-02 17:02:09 +08:00
parent 6fdbc34526
commit ca1ce3d84a
43 changed files with 56074 additions and 3 deletions
@@ -0,0 +1,163 @@
+# AG-UI 示例脚本
+
+本目录包含 AG-UI 协议的实现示例，帮助开发者快速上手。
+
+## 前置要求
+
+```bash
+# 安装依赖
+npm install @ag-ui/client rxjs
+
+# 或
+pnpm add @ag-ui/client rxjs
+```
+
+## 示例列表
+
+### 1. minimal_agent.ts - 最小 Agent 实现
+
+展示如何创建一个最基本的 AG-UI Agent，实现事件流。
+
+**核心概念**:
+- 继承 `AbstractAgent` 类
+- 实现 `run()` 方法返回 Observable 事件流
+- 发送生命周期事件 (RUN_STARTED/RUN_FINISHED)
+- 发送文本消息事件 (TEXT_MESSAGE_START/CONTENT/END)
+
+**运行**:
+```bash
+# 使用 ts-node
+npx ts-node scripts/minimal_agent.ts
+
+# 或编译后运行
+npx tsc scripts/minimal_agent.ts --esModuleInterop
+node scripts/minimal_agent.js
+```
+
+**参考文档**: [modules/agents.md](../modules/agents.md) 行 132-197
+
+---
+
+### 2. tool_call_example.ts - 工具调用流程
+
+展示 Agent 如何调用工具并流式传输参数和结果。
+
+**核心概念**:
+- 定义工具 (Tool)
+- 工具调用事件流: ToolCallStart → ToolCallArgs → ToolCallEnd → ToolCallResult
+- 流式传输工具参数（分块发送）
+- 基于工具结果生成响应
+
+**事件流**:
+```
+ToolCallStart (工具名称)
+  ↓
+ToolCallArgs (参数片段 1)
+ToolCallArgs (参数片段 2)
+ToolCallArgs (参数片段 3)
+  ↓
+ToolCallEnd (参数传输完成)
+  ↓
+ToolCallResult (工具执行结果)
+```
+
+**运行**:
+```bash
+npx ts-node scripts/tool_call_example.ts
+```
+
+**参考文档**: [modules/events.md](../modules/events.md) 行 938-1066
+
+---
+
+### 3. state_sync_example.ts - 状态同步
+
+展示 Agent 与前端的 Snapshot-Delta 状态同步模式。
+
+**核心概念**:
+- StateSnapshot - 完整状态快照
+- StateDelta - 增量更新 (JSON Patch RFC 6902)
+- MessagesSnapshot - 消息历史快照
+- 前端状态管理器实现
+
+**状态同步模式**:
+```
+初始同步:
+  StateSnapshot (完整状态)
+  MessagesSnapshot (消息历史)
+    ↓
+增量更新:
+  StateDelta (JSON Patch 操作)
+  StateDelta (另一个更新)
+    ↓
+周期性刷新:
+  StateSnapshot (确保一致性)
+```
+
+**JSON Patch 操作类型**:
+- `replace` - 替换值
+- `add` - 添加字段
+- `remove` - 删除字段
+
+**运行**:
+```bash
+npx ts-node scripts/state_sync_example.ts
+```
+
+**参考文档**: [modules/events.md](../modules/events.md) 行 1067-1155
+
+---
+
+## 常见问题
+
+### Q: 这些示例可以直接用于生产环境吗？
+
+A: 这些示例仅用于教学目的。生产环境应考虑：
+- 错误处理和重试机制
+- 认证和授权
+- 日志和监控
+- 性能优化（如事件节流）
+
+### Q: 如何处理工具调用的并发？
+
+A: 每个工具调用有唯一的 `toolCallId`，可以并发执行多个工具：
+```typescript
+// 工具调用 1
+ToolCallStart(toolCallId: "tool_1")
+ToolCallArgs(toolCallId: "tool_1", delta: "...")
+ToolCallEnd(toolCallId: "tool_1")
+
+// 工具调用 2（并发）
+ToolCallStart(toolCallId: "tool_2")
+ToolCallArgs(toolCallId: "tool_2", delta: "...")
+ToolCallEnd(toolCallId: "tool_2")
+```
+
+### Q: StateDelta 的 JSON Patch 格式如何工作？
+
+A: JSON Patch (RFC 6902) 是标准的增量更新格式：
+```json
+[
+  { "op": "replace", "path": "/session/currentPage", "value": 2 },
+  { "op": "add", "path": "/formData", "value": {...} },
+  { "op": "remove", "path": "/tempField" }
+]
+```
+
+推荐使用 [fast-json-patch](https://github.com/Starcounter-Jack/Fast-JSON-Patch) 库处理。
+
+---
+
+## 进阶示例
+
+需要更复杂的示例？查看官方仓库：
+- [AG-UI GitHub](https://github.com/ag-ui/ag-ui)
+- [CopilotKit Examples](https://github.com/CopilotKit/CopilotKit/tree/main/examples)
+
+---
+
+## 相关资源
+
+- [AG-UI 协议文档](../llms-full.txt) - 完整协议规范
+- [模块索引](../SKILL.md#模块索引) - 按功能查找文档
+- [常见事件速查](../SKILL.md#常见事件速查) - 高频事件流程