design-agent
以下是整理后的《AgentHub 设计文件》，涵盖了项目定位、微内核架构、DDD 领域模型、各组件详细设计、测试策略、部署方案以及实施里程碑。您可以直接将此文件用于学习、展示或作为开发蓝图。
AgentHub 设计文件
1. 项目概述
- 项目名称：AgentHub
- 定位：企业级 Agent SDK 与服务平台
- 核心价值
- 微内核架构：稳定内核（core-sdk）+ 插件化扩展（web/chat/stream）
- 生产级特性：限流、成本控制、实时统计、RAG 知识库增量更新
- 全平台展示：Web 产品介绍页、Flutter App、Tauri 桌面应用、WebAssembly 在线试用
2. 微内核架构
graph TD
subgraph 插件层
A[web-sdk TS] --> C
B[chat-sdk TS] --> C
D[markdown-stream-render.rs] --> C
end
subgraph 内核层
C["core-sdk (Agent) TS"] --> E
end
subgraph 适配层
E[openapi rust server]
F[网关 & 限流]
G[Kafka + 流计算]
H[RAG 知识库]
end
subgraph 基础设施
I[K8s/云函数]
J[Redis]
K[PostgreSQL]
end
3. DDD 领域模型
3.1 核心聚合与实体
classDiagram
class Agent {
+AgentId id
+string name
+list~Tool~ tools
+execute(input): AsyncIterator~Chunk~
}
class Tool {
+string name
+schema JSON
+invoke(params): Promise
}
class Conversation {
+list~Message~ history
+append(message)
+cost(): TokenCost
}
class TokenCost {
+int inputTokens
+int outputTokens
+string provider
+float price
}
class Quota {
+UserId userId
+int dailyLimit
+int remaining
+checkAndConsume(): bool
}
class CallEvent {
+timestamp
+userId
+apiType
+latencyMs
+success
}
Agent --> Tool
Agent --> Conversation
Conversation --> TokenCost
Quota --> CallEvent : 聚合计算
3.2 限流与统计上下文
- 限流聚合根：
Quota，由滑动窗口事件实时更新。 - 统计事件：
CallEvent作为领域事件发布到 Kafka，用于流计算。
4. 组件详细设计
4.1 SDK 组件（内核 + 插件）
| 组件 | 技术栈 | 职责 | 白盒测试策略 |
|---|---|---|---|
core-sdk (TS) | TypeScript + 依赖注入 | Agent 执行器、工具注册、钩子系统 | Jest 单元测试，模拟 LLM 返回，验证执行链与工具调用 |
web-sdk (TS) | TypeScript | 包装 core-sdk，提供 HTTP/WebSocket 适配 | 集成测试，连接 mock server 验证网络序列化 |
chat-sdk (TS) | TypeScript | 会话管理、多轮记忆 | 状态机测试，验证 Conversation 行为 |
markdown-stream-render.rs | Rust + wasm-bindgen | 流式 markdown 分片渲染（按段落/代码块切割） | Rust 单元测试，断言切片边界正确性 |
4.2 后端服务
| 组件 | 技术栈 | 职责 | 黑盒测试策略 |
|---|---|---|---|
| openapi rust | Rust + axum + tower | 暴露 REST API，转发请求到云函数 | API 测试（Postman / cucumber），验证鉴权、限流响应头 |
| 网关 gateway | Envoy 或 Rust 自研 | 动态限流、熔断、路由 | 压测（wrk），触发限流返回 429 |
| 云函数 | AWS Lambda / K8s Job | 无状态执行 agent 推理 | mock 下游 LLM 的单元测试 |
| 限流调度 | Redis + 滑动窗口 | 单用户日配额、整体成本阈值 | 高并发测试，验证超限后拒绝 |
| Kafka + rdkafka | Rust + rdkafka + tokio | 消费 CallEvent，5min 滑动窗口聚合 | 集成测试，注入模拟事件并断言聚合结果 |
| RAG 知识库 | qdrant + sentence-transformers | 增量更新检索，结合历史调用 | 黑盒测试：添加文档后查询，验证实时性 |
滑动窗口聚合逻辑（伪代码）
// 每5分钟滑动窗口，每1分钟触发一次
window(5m).every(1m).group_by(user_id, provider).aggregate(
sum(latency_ms) as total_latency,
count_if(success=false) as failure_count,
sum(token_count) as tokens,
count_if(api_type="chat") as chat_ratio
).to(redis, postgres)
4.3 客户端与展示端
| 组件 | 技术栈 | 职责 |
|---|---|---|
| Flutter App | Dart + Riverpod | 移动端调用 agent，支持语音输入 |
| Web WASM | markdown-stream-render.rs + React | 浏览器内直接运行 agent 推理 |
| Tauri 桌面 | Rust + Next.js | 本地 agent 服务 + 系统工具 |
| 产品介绍页 | Next.js + Tailwind | 功能展示、在线试用（调用公开 API） |
4.4 实时大屏
- 技术：Rust + actix-web + WebSocket + ECharts
- 展示指标（5分钟滑动窗口）
- API 耗时 p50/p95
- 失败率（按服务商）
- token 消耗及各模型占比
- 实时调用成本（美元/分钟）
- 告警：单用户成本超过预算 80% 时，动态更新配置库，网关立即限流。
5. 开发与测试全流程
5.1 设计阶段产出物
- DDD 领域模型图（Mermaid）
- 微内核接口定义：
core-sdk/src/agent.ts中AgentExecutor抽象类 - OpenAPI 3.0 契约
- 滑动窗口算法设计文档
5.2 白盒测试（开发前编写）
- 核心内核：Jest 模拟 LLM，测试工具调用重试、循环检测
- markdown-stream-render：Rust
#[cfg(test)]单元测试 - 限流模块：
TokenBucket状态机测试
5.3 开发（TDD 模式）
- 使用
cargo workspaces（Rust）和npm workspaces（TS） - CI（GitHub Actions）：并行执行 Rust/TS 测试，构建 Docker 镜像
5.4 黑盒测试（集成后）
| 场景 | 验证点 |
|---|---|
| 用户通过 Web SDK 聊天 | 触发工具调用、限流生效、Kafka 事件记录 |
| RAG 知识库更新 | 新增文档后实时命中检索 |
| 大屏统计 | 失败率上升时网关自动降级 |
- 工具：pytest（端到端）、locust（负载测试）
6. 部署架构与弹性
graph LR
Client --> Gateway[Envoy Gateway]
Gateway -->|限流| Function[云函数/ K8s Pod]
Function --> Core[core-sdk 容器]
Core --> LLM[外部 LLM API]
Core --> Kafka[(Kafka)]
Kafka --> Stream[流计算 Job]
Stream --> Redis[(Redis)]
Gateway -.->|读取配置| Redis
- 弹性：云函数根据请求量自动扩缩容
- 安全处理：网关实现 JWT 鉴权、请求体加密、防重放攻击
7. 实施里程碑（7 周可演示）
| 周次 | 任务 | 可展示成果 |
|---|---|---|
| 1 | DDD 建模 + 微内核接口定义 + Mermaid 图 | 设计文档 |
| 2 | 实现 core-sdk + 白盒测试 + markdown-stream-render | 单元测试覆盖率 >85% |
| 3 | openapi rust 网关 + 限流调度 + Kafka 模拟 | Postman 调用限流效果 |
| 4 | Flutter 最小 Demo + Tauri 桌面应用 | 跨平台运行截图 |
| 5 | 5min 滑动窗口大屏（Rust + WebSocket + ECharts） | 实时统计图表 |
| 6 | RAG 增量更新 + Web 产品介绍页 | 在线试用功能 |
| 7 | 黑盒测试报告 + 压测报告 | 1000 QPS 下的系统表现 |
8. 领域事件流示例（Mermaid）
sequenceDiagram
participant User
participant WebSDK
participant Gateway
participant AgentCore
participant LLM
participant Kafka
participant StreamJob
participant Redis
User->>WebSDK: 发送消息
WebSDK->>Gateway: HTTP /agent/execute
Gateway->>Redis: 检查 quota
Redis-->>Gateway: remaining=5
Gateway->>AgentCore: 转发请求
AgentCore->>LLM: 调用 API
LLM-->>AgentCore: 返回 token 流
AgentCore->>Kafka: 发送 CallEvent
AgentCore-->>WebSDK: 流式返回
WebSDK-->>User: 展示 markdown
Kafka->>StreamJob: 每5min滑动窗口计算
StreamJob->>Redis: 更新聚合指标
StreamJob->>Gateway: 动态调整限流阈值
设计文件结束。您可以直接按此文档执行开发与展示，每个章节均可作为独立的学习模块。如需具体代码模板或测试用例示例，可进一步提出。