📌 1. 项目概述
1.1 项目背景
当前 OpenClaw 系统已经搭建完成，但缺乏针对不同类型查询的智能路由和后端集成能力。主要需求包括：
- 自然语言查询能力：理解用户意图，查询数据库，使用大模型组织返回结果
- 多技术栈支持：支持 Python、Spring Cloud、Spring AI Alibaba、Golang 等后端服务
- 智能路由：根据查询类型智能路由到不同的 SQLBot 工作空间
- 扩展性：支持对接 RAGFlow（非数据库通用问题）和更多外部系统
- 多业务 Agent 支持：订单、钻针、涨缩模型、仓储管理等微服务
✅ 核心目标
- 意图识别准确率 ≥ 95%
- 查询响应时间 < 3 秒（数据库查询）
- 路由准确率 ≥ 98%
- 支持多技术栈：Python / Spring Cloud / Spring AI Alibaba / Golang
- 可扩展架构：支持后续接入 RAGFlow 等新系统
🏗️ 2. 系统架构设计
2.1 总体架构
OpenClaw 采用六层架构，从消息接入到最终响应，每一层负责特定的职责，确保系统的可扩展性、可维护性和可观测性。
graph TB
subgraph "第 1 层：Gateway 层 - 消息协议转换与统一接入"
User[用户] -->|Feishu| OpenClaw[OpenClaw 平台]
end
subgraph "第 2 层：IRR 层 - 意图识别与路由"
OpenClaw --> GatewayAdapter[网关适配器]
GatewayAdapter --> MessageParser[消息解析器]
MessageParser --> IntentRecognizer[意图识别器]
IntentRecognizer --> IntelligentRouter[智能路由器]
end
subgraph "第 3 层：Agent 层 - 专用处理层"
IntelligentRouter --> GeneralAgent[通用 Agent]
IntelligentRouter --> DatabaseAgent[数据库 Agent]
IntelligentRouter --> OrderAgent[订单微服务 Agent]
IntelligentRouter --> HoleAgent[钻针管理 Agent]
IntelligentRouter --> PricingModelAgent[涨缩模型 Agent]
IntelligentRouter --> WarehouseAgent[仓储管理 Agent]
end
subgraph "第 4 层：后端服务层"
DatabaseAgent -->|HTTP| SQLBot[SQLBot HTTP Skill]
OrderAgent -->|RPC| OrderService[订单微服务]
HoleAgent -->|RPC| HoleService[钻针管理服务]
PricingModelAgent -->|RPC| PricingService[涨缩模型服务]
WarehouseAgent -->|RPC| WarehouseService[仓储服务]
end
subgraph "第 5 层：外部系统"
SQLBot --> DataEaseAPI[DataEase API]
OrderService --> OrderDB[(订单数据库)]
HoleService --> HoleDB[(钻针数据库)]
PricingService --> ModelDB[(模型数据库)]
WarehouseAgent --> ERPSystem[ERP 系统]
end
subgraph "第 0 层：AI 处理层（横向）"
IntentRecognizer --> LLMService[LLM 服务]
LLMService --> ResultOrganizer[结果组织器]
end
subgraph "第 -1 层：决策记录层（横向）"
IntelligentRouter --> DecisionRecorder[架构决策记录器]
DecisionRecorder --> ArchitectureSkill[architecture-decision-records Skill]
end
2.2 架构层次详细说明
第 1 层：Gateway 层
| 组件 | 功能 | 技术实现 |
|---|---|---|
| GatewayAdapter | 适配不同消息协议，转换为统一格式 | 消息框架（Feishu SDK、WebSocket） |
| MessageParser | 解析消息内容，提取用户输入 | 正则表达式 + 结构化解析 |
| 安全认证 | 用户身份验证、权限校验 | JWT / OAuth2 / API Key |
第 2 层：IRR 层（意图识别与路由）
IntentRecognizer 支持的意图类型：
| 意图类型 | 说明 | 路由目标 | 降级策略 |
|---|---|---|---|
database_query |
需要查询数据库（SQL） | Database Agent | 降级到 General Agent |
general_qa |
通用知识问答 | General Agent | RAGFlow 集成 |
rag_query |
需要检索知识库（RAG） | RAGFlow Agent | 降级到 General Agent |
order_query |
订单相关查询 | Order Agent | Database Agent（如有权限） |
hole_query |
钻针管理查询 | HoleAgent | Database Agent（如有权限） |
pricing_query |
涨缩模型查询 | PricingModelAgent | Database Agent（如有权限） |
warehouse_query |
仓储管理查询 | WarehouseAgent | Database Agent（如有权限） |
第 3 层：Agent 层（专用处理层）
DatabaseAgent 技术栈识别与路由
| 后端技术栈 | SQLBot 工作空间 | Agent 内部路由 |
|---|---|---|
| Python | sqlbot-python |
Python Agent |
| Spring Cloud | sqlbot-spring |
Java Agent |
| Spring AI Alibaba | sqlbot-alibaba |
Java Agent (Spring AI) |
| Golang | sqlbot-golang |
Golang Agent |
2.3 消息流转示例
数据库查询流程
sequenceDiagram
participant User as 用户
participant Gateway as Gateway层
participant IRR as IRR层
participant DBAgent as Database Agent
participant SQLBot as SQLBot HTTP
participant LLM as LLM服务
User->>Gateway: 查询最近7天的订单数量
Gateway->>IRR: 消息解析
IRR->>IRR: 意图识别: database_query
IRR->>DBAgent: 路由到 Database Agent
DBAgent->>SQLBot: 执行SQL查询
SQLBot->>SQLBot: 查询数据库
SQLBot-->>DBAgent: 返回结果
DBAgent->>LLM: 组织结果
LLM-->>User: 返回格式化答案
订单查询流程
sequenceDiagram
participant User as 用户
participant Gateway as Gateway层
participant IRR as IRR层
participant OrderAgent as Order Agent
participant OrderSvc as 订单微服务
participant OrderDB as 订单数据库
participant LLM as LLM服务
User->>Gateway: 查询订单SO-2024-001的状态
Gateway->>IRR: 消息解析
IRR->>IRR: 意图识别: order_query
IRR->>OrderAgent: 路由到 Order Agent
OrderAgent->>OrderSvc: RPC调用
OrderSvc->>OrderDB: 查询数据库
OrderDB-->>OrderSvc: 返回订单数据
OrderSvc-->>OrderAgent: 返回状态
OrderAgent->>LLM: 组织结果
LLM-->>User: 返回JSON格式结果
⚙️ 3. 技术实现
3.1 意图识别器实现
混合意图识别策略：
- 第一级：关键词匹配（快速响应，< 50ms）
- 第二级：正则表达式匹配（中等响应，< 100ms）
- 第三级：大模型分类（准确响应，< 500ms）
class HybridIntentRecognizer:
def recognize(self, input_text):
# 第一级：关键词匹配
if self._keyword_match(input_text):
return self._keyword_to_intent()
# 第二级：正则匹配
if self._regex_match(input_text):
return self._regex_to_intent()
# 第三级：大模型分类
llm_intent = self._llm_classify(input_text)
return llm_intent3.2 智能路由器实现
class IntelligentRouter:
def __init__(self):
self.agents = {
'general': GeneralAgent(),
'database': DatabaseAgent(),
'order': OrderAgent(),
'hole': HoleAgent(),
'pricing': PricingModelAgent(),
'warehouse': WarehouseAgent()
}
self.fallback_chain = {
'database': 'general',
'order': 'general',
'hole': 'general',
'pricing': 'general',
'warehouse': 'general',
'rag': 'general'
}3.3 数据脱敏规则
| 字段类型 | 脱敏规则 | 示例 |
|---|---|---|
| 手机号 | 中间4位隐藏 | 138****1234 |
| 身份证号 | 保留前6位和后4位 | 123456************1234 |
| 银行卡号 | 保留前6位和后4位 | 622588************1234 |
| 姓名 | 保留姓，名隐藏 | 张** |
| 邮箱 | 保留前2位和域名 | ab****@example.com |
| IP地址 | 保留前3段 | 192.168.1.*** |
🔌 4. 扩展性设计
4.1 插件化架构
| 插件类型 | 说明 | 扩展点 |
|---|---|---|
| 意图识别器 | 支持多种意图识别算法 | 添加新的 LLM 模型或规则 |
| 路由器 | 支持多种路由策略 | 添加新的路由规则或目标 |
| Agent | 支持多种后端技术栈和业务领域 | 添加新的技术栈 Agent 或业务 Agent |
| 结果组织器 | 支持多种结果处理策略 | 添加新的组织逻辑 |
4.2 新增 Business Agent
| 新 Agent | 功能描述 | 后端服务集成 |
|---|---|---|
| FinanceAgent | 财务查询 Agent | 财务微服务 |
| LogisticsAgent | 物流查询 Agent | 物流微服务 |
| ProductionAgent | 生产查询 Agent | 生产微服务 |
⚡ 5. 性能优化
5.1 缓存策略
| 缓存类型 | 缓存内容 | 有效期 | 清理策略 |
|---|---|---|---|
| 意图识别缓存 | 常见查询的意图识别结果 | 1小时 | LRU 淘汰 |
| 路由结果缓存 | 路由决策结果 | 10分钟 | 基于 TTL |
| 查询结果缓存 | 常用查询的 SQL 结果 | 5分钟 | 基于查询参数 |
5.2 并发处理
- 异步查询多个数据源
- 结果聚合与超时控制
- 熔断机制保护后端服务
5.3 数据库查询优化
| 优化技术 | 说明 | 实施方式 |
|---|---|---|
| 索引优化 | 为常用查询字段创建索引 | 在数据库中创建索引 |
| 查询重写 | 避免使用 SELECT * | 只查询需要的字段 |
| 分页查询 | 大数据集使用分页 | 使用 LIMIT 和 OFFSET |
| 缓存策略 | 缓存常用查询结果 | 使用 Redis 缓存 |
🔒 6. 安全设计
6.1 数据安全
安全措施：
- API 密钥管理：使用环境变量存储 API 密钥，不在代码中硬编码密钥
- SQL 注入防护：参数化 SQL 查询，禁止动态 SQL 拼接
- 访问控制：基于角色的访问控制（RBAC），数据库连接池管理
- 数据脱敏：敏感字段加密存储，日志中不记录完整信息
6.2 通信安全
- HTTPS 传输：所有 API 调用使用 HTTPS，SSL/TLS 证书验证
- 请求签名：API 请求签名验证，时间戳防重放攻击
- 限流与熔断：API 限流保护（每秒请求数），熔断保护后端服务
6.3 审计日志
| 事件类型 | 说明 | 记录内容 |
|---|---|---|
| 用户登录 | 用户登录事件 | 用户 ID、登录时间、IP 地址、登录方式 |
| 权限变更 | 权限变更事件 | 用户 ID、变更前权限、变更后权限、操作人 |
| 数据访问 | 数据访问事件 | 用户 ID、访问的数据类型、访问的数据范围 |
| 敏感操作 | 敏感操作事件 | 用户 ID、操作类型、操作对象、操作时间、操作结果 |
📅 7. 实施计划
7.1 开发阶段
| 阶段 | 工作内容 | 预计周期 | 优先级 |
|---|---|---|---|
| 阶段 1 | Gateway 层开发（消息解析、协议转换） | 1 周 | P0 |
| 阶段 2 | IRR 层开发（意图识别、智能路由、决策记录） | 2 周 | P0 |
| 阶段 3 | Agent 层开发（通用 Agent、数据库 Agent） | 2 周 | P0 |
| 阶段 4 | Agent 层开发（订单、钻针、涨缩模型、仓储 Agent） | 3 周 | P1 |
| 阶段 5 | SQLBot HTTP Skill 集成 | 1 周 | P0 |
| 阶段 6 | LLM 服务集成、结果组织器开发 | 1 周 | P0 |
| 阶段 7 | OpenClaw Agent 工作空间集成 | 1 周 | P0 |
| 阶段 8 | 端到端集成测试 | 1 周 | P1 |
开发阶段总计：12 周
7.2 测试阶段
| 测试类型 | 测试内容 | 预计周期 |
|---|---|---|
| 单元测试 | 各组件的单元测试 | 2 周 |
| 集成测试 | 端到端集成测试 | 2 周 |
| 压力测试 | 并发查询性能测试 | 1 周 |
| 安全测试 | SQL 注入、权限控制测试 | 1 周 |
测试阶段总计：6 周
7.3 部署阶段
| 部署阶段 | 工作内容 | 预计周期 |
|---|---|---|
| 环境准备 | 测试环境搭建、配置管理 | 1 周 |
| 灰度发布 | 部署到测试环境、内部测试 | 1 周 |
| 正式上线 | 生产环境部署 | 1 周 |
部署阶段总计：3 周
📊 8. 运维与监控
8.1 核心监控指标
| 指标类别 | 具体指标 | 目标值 |
|---|---|---|
| 性能指标 | 意图识别时间 < 1 秒 | P95 |
| 性能指标 | 路由时间 < 0.5 秒 | P95 |
| 性能指标 | 数据库查询时间 < 2 秒 | P95 |
| 性能指标 | 总响应时间 < 3 秒 | P95 |
| 可用性指标 | 系统可用性 > 99.9% | 月度 |
| 准确性指标 | 意图识别准确率 > 95% | 月度 |
| 准确性指标 | 路由准确率 > 98% | 月度 |
8.2 告警规则
| 告警类型 | 触发条件 | 通知方式 |
|---|---|---|
| 性能告警 | P95 响应时间 > 3 秒 | Feishu + 邮件 |
| 错误告警 | 错误率 > 5% | Feishu + 邮件 |
| 可用性告警 | 系统可用性 < 99% | Feishu + 邮件 + 短信 |
⚠️ 9. 风险评估与应对
9.1 技术风险
| 风险项 | 风险等级 | 影响 | 应对措施 |
|---|---|---|---|
| 多技术栈集成复杂度 | 高 | 开发周期延长 | 采用分层架构、分阶段实施 |
| 多 Agent 管理复杂度 | 高 | 运维成本增加 | 统一监控平台、自动化告警 |
| SQL 注入风险 | 高 | 数据安全威胁 | 参数化 SQL、输入验证、最小权限原则 |
| LLM API 成本 | 中 | 运营成本增加 | 缓存策略、按量计费优化 |
9.2 实施风险
| 风险项 | 风险等级 | 影响 | 应对措施 |
|---|---|---|---|
| 跨团队协调风险 | 中 | 进度延迟 | 明确分工、定期同步会议、敏捷开发管理 |
| 测试时间不足 | 中 | 质量问题 | 自动化测试、并行测试、优先级排序 |
💡 10. 使用场景扩展
10.1 数据库查询场景
场景示例：
- "查询订单表中的所有待处理订单" → 简单单表查询
- "查询最近 7 天的订单及其对应的客户信息" → 多表关联查询
- "统计每天的销售总额" → 聚合统计查询
10.2 订单管理场景
场景示例：
- "创建订单 SO-2024-002，产品 XYZ，数量 100，单价 50" → 创建订单
- "查询订单 SO-2024-001 的状态" → 订单状态查询
- "将订单 SO-2024-002 的状态改为生产中" → 订单状态变更
10.3 钻针管理场景
场景示例：
- "查询直径 0.8mm 的钻针可用性" → 钻针可用性查询
- "优化接下来的 24 小时的钻针排程" → 钻针排程优化
10.4 涨缩模型场景
场景示例：
- "预测产品 XYZ 下个月的价格" → 价格预测
- "对比当前版本和上个月版本的价格预测准确率" → 模型版本对比
10.5 仓储管理场景
场景示例：
- "显示所有库存低于安全水位的预警" → 库存预警
- "记录产品 XYZ 的出库 50 个，订单号 SO-2024-002" → 出入库操作
🚀 11. 部署架构
11.1 生产环境部署架构
graph TB
subgraph "负载均衡层"
Nginx[Nginx 负载均衡]
HAProxy[HAProxy 高可用]
end
subgraph "网关层"
Gateway1[OpenClaw Gateway 节点 1]
Gateway2[OpenClaw Gateway 层 2]
end
subgraph "应用层"
Worker1[Worker 节点 1]
Worker2[Worker 节点 2]
Worker3[Worker 层 3]
Worker4[Worker 层 4]
end
subgraph "服务层"
PostgreSQL[(PostgreSQL 主从复制)]
Redis[(Redis 集群)]
Milvus[(Milvus 集群)]
end
Nginx --> Gateway1
Nginx --> Gateway2
Gateway1 --> Worker1
Gateway1 --> Worker2
Gateway2 --> Worker3
Gateway2 --> Worker4
Worker1 --> PostgreSQL
Worker2 --> PostgreSQL
Worker3 --> PostgreSQL
Worker4 --> PostgreSQL
Worker1 --> Redis
Worker2 --> Redis
Worker3 --> Redis
Worker4 --> Redis
Worker1 --> Milvus
Worker2 --> Milvus
Worker3 --> Milvus
Worker4 --> Milvus
11.2 容灾方案
数据库容灾策略：
- 主从复制：主数据库处理写操作，从数据库处理读操作
- 同步方式：流复制（Streaming Replication）
- 故障切换：手动或自动切换到从数据库
- 备份策略：每日全量备份 + 实时增量备份
应用层容灾策略：
- 多机房部署：主机房处理 70% 的流量，备机房处理 30% 的流量
- DNS 切换：故障时自动切换 DNS 记录
- 数据同步：通过专线或 VPN 同步数据
📋 12. 项目总结
12.1 项目关键指标
| 类别 | 指标 | 目标值 |
|---|---|---|
| 性能 | P95 响应时间 | < 3 秒 |
| 可用性 | 系统可用性 | ≥ 99.9% |
| 准确性 | 意图识别准确率 | ≥ 95% |
| 安全性 | 漏洞扫描通过率 | 100% |
| 成本 | 月度运营成本 | 预算内 |
12.2 项目里程碑
| 阶段 | 里程碑 | 预期时间 |
|---|---|---|
| 需求分析 | 完成需求文档 | 第 1 周 |
| 架构设计 | 完成架构设计文档 | 第 2 周 |
| 核心开发 | 完成核心功能开发 | 第 10 周 |
| 测试验收 | 完成所有测试 | 第 16 周 |
| 部署上线 | 完成生产部署 | 第 19 周 |
📄 文档版本历史
- v2.1.0（2026-03-12）：详细技术实现、使用场景扩展、容错机制、性能优化、安全措施、监控指标、故障排查、自动化运维、CI/CD 配置、项目总结
- v2.0（2026-03-12）：初始版本