Blizzard
236 lines
14 KiB
Markdown
236 lines
14 KiB
Markdown
# sundynix-agentix 项目全面分析
|
||
|
||
## 一、项目定位
|
||
|
||
分层式 AI Agent 平台，采用 **Monolith First → Microservices (Morph B)** 演进策略。
|
||
目标是构建一个集 **Agent 可视化编排、知识库 RAG、报告生成、用户记忆** 于一体的企业级 AI 工作站。
|
||
|
||
---
|
||
|
||
## 二、技术栈总览
|
||
|
||
| 层级 | 模块 | 语言/框架 | 核心依赖 |
|
||
|---|---|---|---|
|
||
| **1. 客户端** | `sundynix-desktop` | Wails + React 19 + TypeScript | @xyflow/react (React Flow), shadcn/ui, TailwindCSS 3, lucide-react, react-force-graph-2d, Vite 5 |
|
||
| **1b. 运维控制台** | `sundynix-admin` | React 19 + TS + Vite | react-router-dom 7, TailwindCSS |
|
||
| **2. 网关** | `sundynix-gateway` | Go · Gin | GORM + PostgreSQL 16, Redis 7, NATS JetStream, 雪花 ID, bcrypt 鉴权 |
|
||
| **3. 消息总线** | NATS Server | Go | NATS 2 (Alpine), JetStream 持久化 |
|
||
| **4. 调度器** | `sundynix-dispatcher` | Go · CloudWeGo Eino | eino (图编排/ReAct Agent), nats.go, 熔断器, LLM 自动化评测 |
|
||
| **5a. MCP 工具 (I/O)** | `sundynix-mcp-go` | Go | Milvus SDK, Bleve, Neo4j Driver, UniOffice (.docx), Snowflake ID, GORM |
|
||
| **5b. MCP 工具 (算法)** | `sundynix-mcp-py` | Python ≥3.11 | nats-py, python-docx, openpyxl, pypdf, docker (沙箱) |
|
||
| **共享层** | `sundynix-shared` | Go | nats.go, JetStream, 内嵌 NATS (devnats) |
|
||
| **基础设施** | Docker Compose | - | NATS, PostgreSQL 16, Redis 7, Milvus 2.4, Neo4j 5, MinIO |
|
||
|
||
### 构建工具链
|
||
- **Go 工作区**: `go.work` 管理 4 个后端模块（gateway/dispatcher/mcp-go/shared）
|
||
- **前端**: Vite 5 + TypeScript 5 + PostCSS + TailwindCSS
|
||
- **桌面端**: Wails v2（Go 后端 + WebView 前端，`GOWORK=off` 独立构建）
|
||
- **Makefile**: 统一的 `make` 命令编排所有服务启动、测试、构建
|
||
|
||
---
|
||
|
||
## 三、已实现功能
|
||
|
||
### 3.1 Agent 可视化编排 (Studio)
|
||
- **React Flow 画布**：拖拽式节点编排，支持 10+ 节点类型：
|
||
- `input` / `output` / `memory` / `retriever` / `tool` / `agent` / `aggregate` / `render` / `branch` / `map`
|
||
- **DSL 导出**：画布编排导出 JSON DSL，经网关发布到 NATS 任务队列
|
||
- **图执行引擎**：按拓扑序遍历节点、沿连线传播活性、branch 条件剪枝
|
||
- **多 Agent 协作**：agent 节点产出通过黑板(board)接力传递给下游 agent
|
||
- **ReAct 自主 Agent**：基于 CloudWeGo Eino 的 ReAct 循环，模型自主选工具（最多 8 步）
|
||
- **Eino Compose Graph** (可选)：环境变量 `EINO_COMPOSE=1` 可切换到 Eino 原生 compose.Graph 编排
|
||
|
||
### 3.2 知识库 RAG
|
||
- **三路混合检索**：
|
||
- **向量路**: Embedding → Milvus 向量搜索
|
||
- **全文路**: Bleve 倒排索引
|
||
- **图谱路**: Neo4j 知识图谱（LLM 自动抽取实体三元组）
|
||
- **RRF 融合 + 可选 Rerank**：三路结果经 Reciprocal Rank Fusion 融合，可接 Rerank 模型精排
|
||
- **入库流水线**：文档解析 → 语义切块（递归+句界+重叠+rune 安全）→ 分批向量化 → 写 Milvus/Bleve → LLM 抽三元组 → 写 Neo4j
|
||
- **实时入库监控**：`IngestEvent` 逐阶段回流进度给 UI（切块/向量化/写库/抽实体）
|
||
- **文档格式支持**：.docx (python-docx) / .xlsx (openpyxl) / .pdf (pypdf)
|
||
- **知识图谱可视化**：react-force-graph-2d 渲染三元组图谱
|
||
|
||
### 3.3 报告生成
|
||
- **多步编排**：规划大纲 → 各章节并行（有界并发=4）→ RAG 检索 + LLM 撰写 → 汇聚渲染
|
||
- **Word 渲染**：UniOffice 渲染 .docx 文档，一键下载
|
||
- **流式进度**：规划/撰写进度实时流回客户端
|
||
- **报告源持久化**：title + sections 持久存储，支持导出 Word/PDF/Markdown
|
||
|
||
### 3.4 用户记忆系统
|
||
- **常驻画像 (Always-on Memory)**：
|
||
- Postgres 存储 key-value 偏好，GORM 软删 + 雪花 ID
|
||
- **Generative Agents 打分**：`Score = 0.4·Recency + 0.6·Importance`
|
||
- 指数衰减 Recency（每天衰减 0.98）+ LLM 评分 Importance (1-10)
|
||
- 读取时 Top-30 截断控 context + 自然遗忘
|
||
- **短期多轮历史**：经 MCP history_get/history_append 工具存取
|
||
- **记忆对账 (Consolidate)**：每 3 轮攒批一次，LLM 将近期对话与已有画像对账归纳
|
||
|
||
### 3.5 执行可视化 (运行·观测)
|
||
- **ExecEvent 轨迹**：每个节点的生命周期事件（start/end/error/info）+ 耗时
|
||
- **双流并行**：Token 流 (`sundynix.streams.<id>`) + 执行事件流 (`sundynix.exec.<id>`) 分离
|
||
- **实时节点点亮**：前端 SSE 订阅轨迹，逐节点展示执行状态
|
||
|
||
### 3.6 安全与工程化护栏
|
||
- **熔断降级** (`CircuitBreaker`)：连续失败触发熔断，快速拒绝新任务 + 友好提示
|
||
- **输出护栏** (`RedactSecrets`)：流式脱敏疑似密钥/令牌
|
||
- **LLM 自动化评测** (`Evaluator`)：规则 + LLM-as-judge 异步打分
|
||
- **Python 安全沙箱**：gVisor / KataVM 静态代码守卫 + Docker 隔离解释器
|
||
- **任务生命周期状态机**：submitted → running → done / failed / timeout
|
||
|
||
### 3.7 鉴权与管理
|
||
- **JWT 鉴权**：登录/注册 + bcrypt 密码 + Token 校验
|
||
- **运维控制台 (admin)**：模型/数据源登记激活、服务健康监控、用户计费
|
||
- **NATS 热更新**：模型配置变更经 NATS 广播到各消费方（dispatcher/mcp-go）
|
||
|
||
### 3.8 桌面端
|
||
- **Wails 原生应用**：macOS/Windows/Linux 跨平台桌面端
|
||
- **Go/TS 强绑定**：前端调用 Go 后端（本地文件 I/O 等）
|
||
- **命令面板**：⌘K / Ctrl+K 全局命令面板（键盘优先工作站）
|
||
|
||
---
|
||
|
||
## 四、核心数据流
|
||
|
||
```
|
||
客户端 → POST /api/v1/tasks → Gateway (DSL 解析/鉴权/计费)
|
||
→ NATS JetStream (sundynix.tasks.<id>)
|
||
→ Dispatcher (Eino 图编排, 记忆/历史召回)
|
||
→ NATS request-reply → MCP Tools (Go I/O + Python 算法)
|
||
→ Token Stream (sundynix.streams.<id>) 零拷贝回流
|
||
→ Gateway SSE → 客户端逐 token 渲染
|
||
```
|
||
|
||
---
|
||
|
||
## 五、优势与亮点 ✅
|
||
|
||
### 架构设计
|
||
| 优势 | 说明 |
|
||
|---|---|
|
||
| **分层解耦清晰** | 5 层 + NATS 消息总线，各层职责边界分明，适合团队分工和独立演进 |
|
||
| **NATS 零拷贝骨干网** | Queue(任务分发) + Stream(Token 回流) + Request-Reply(工具调用/配置) 三模式精准匹配场景，低延迟高吞吐 |
|
||
| **优雅降级设计** | 各依赖（Milvus/Neo4j/Rerank/Memory/Python MCP）不可用时自动降级，核心链路不阻断 |
|
||
| **Monolith First 策略** | 先单体验证核心价值，预埋微服务拆分点（MCP 工具已经独立为 Go/Python 两个微服务） |
|
||
| **Eino 生态** | 基于 CloudWeGo Eino 的 ReAct Agent + Compose Graph，复用字节生态的模型抽象和工具适配 |
|
||
|
||
### 功能实现
|
||
| 优势 | 说明 |
|
||
|---|---|
|
||
| **三路混合 RAG** | 向量 + 全文 + 知识图谱 RRF 融合 → 召回质量显著优于纯向量检索 |
|
||
| **Generative Agents 记忆** | Recency + Importance 双维打分 + 自然遗忘，远超简单的"全量注入"记忆方案 |
|
||
| **可视化 Agent 编排** | React Flow 画布低代码拖拽，支持 branch/map/aggregate 等复杂流控，降低使用门槛 |
|
||
| **执行可视化** | Token 流与执行轨迹分流，运行时逐节点点亮，工具调用入参/产出透明可观测 |
|
||
| **动态工具发现** | ReAct agent 通过 `list_tools` 自描述发现可用工具，新增工具只需在 MCP 注册，无需改 dispatcher |
|
||
| **报告并行生成** | 大纲规划 → 多章有界并发撰写 → 真实 Word 渲染，端到端闭环 |
|
||
|
||
### 工程化
|
||
| 优势 | 说明 |
|
||
|---|---|
|
||
| **Monorepo 统一管理** | go.work + Makefile 一键启动，`make demo` 零 Docker 即可验证全链路 |
|
||
| **内嵌 NATS (devnats)** | 开发/测试无需外部 NATS，降低环境搭建成本 |
|
||
| **完善的 E2E 测试** | 任务流/工具调用/Token 流 三场景端到端覆盖 |
|
||
| **雪花 ID 规约** | 全局统一的字符串雪花 ID 主键 + GORM 软删，数据规约一致 |
|
||
| **零配置启动** | docker-compose 对齐默认配置，clone 后只需填 API key |
|
||
| **NATS 配置热更新** | 模型配置变更无需重启服务，broadcast + subscribe 实时生效 |
|
||
|
||
---
|
||
|
||
## 六、不足与改进建议 ⚠️
|
||
|
||
### 6.1 架构层面
|
||
|
||
| 问题 | 现状 | 建议 |
|
||
|---|---|---|
|
||
| **缺少 API 网关/服务网格** | Gateway 承担了鉴权/限流/DSL 解析/SSE 推送/管理等过多职责 | 考虑分离 BFF (面向前端) 与核心 Gateway，或引入 Kong/Traefik 负责横切关注点 |
|
||
| **配置管理未集中** | 各服务 config/ 独立管理，NATS 热更新仅覆盖模型配置 | 引入统一配置中心（Consul/etcd 或 NATS KV），覆盖全部运行时配置 |
|
||
| **缺少链路追踪** | 日志为主要观测手段（`log.Printf`），无结构化 trace | 接入 OpenTelemetry (tracing + metrics)，NATS 消息头透传 trace ID |
|
||
| **无服务注册发现** | 服务端点硬编码于配置 | 基于 NATS 已有能力做简单服务注册，或引入 Consul/etcd |
|
||
| **单点瓶颈风险** | NATS 单节点（docker-compose）、Milvus standalone | 生产环境需 NATS 集群 + Milvus 分布式模式 |
|
||
|
||
### 6.2 代码质量
|
||
|
||
| 问题 | 现状 | 建议 |
|
||
|---|---|---|
|
||
| **Dispatcher graph.go 过大** | 单文件 492 行，混合了图执行、各节点实现、条件求值 | 拆分为 `node_agent.go` / `node_retriever.go` / `node_branch.go` 等，每类节点独立文件 |
|
||
| **日志标准化不足** | 使用标准 `log.Printf`，无结构化字段和级别控制 | 引入 slog（Go 1.21 标准库）或 zap，统一 JSON 格式 + 日志级别 |
|
||
| **错误处理不够严谨** | 多处 `_ = msg.Respond(data)` / `_ = m.Respond(data)` 忽略错误 | 关键路径的响应失败应记录日志 |
|
||
| **魔法字符串** | 节点 Kind (`"agent"`, `"retriever"`) 为裸字符串 | 定义 `const` 枚举或使用 `iota`，消除散落的字符串匹配 |
|
||
| **部分 Python 代码为桩** | MinerU (PaddleOCR)、MCP 协议真实实现标注为 TODO | 核心功能保持占位可接受，但应有明确的迭代计划和 issue 跟踪 |
|
||
|
||
### 6.3 前端
|
||
|
||
| 问题 | 现状 | 建议 |
|
||
|---|---|---|
|
||
| **状态管理原始** | 纯 `useState` + props drilling，无全局状态管理 | 随功能增长，考虑引入 Zustand 或 Jotai 管理全局状态（当前/会话/运行态） |
|
||
| **路由为自研视图切换** | `view` state + 条件渲染，无 URL 路由 | 引入 React Router，支持 URL 直达、浏览器前进后退 |
|
||
| **类型安全不完整** | 部分 API 响应缺 TypeScript 类型定义 | 考虑 API 契约生成（OpenAPI → TypeScript types），前后端类型一致 |
|
||
| **KbView.tsx 过大** | 单文件 31944 字节 | 拆分为子组件（搜索面板 / 文档列表 / 图谱面板 / 入库面板） |
|
||
| **无单元测试** | 前端零测试覆盖 | 引入 Vitest + React Testing Library，优先覆盖核心交互 |
|
||
|
||
### 6.4 安全
|
||
|
||
| 问题 | 现状 | 建议 |
|
||
|---|---|---|
|
||
| **API Key 明文传输/存储** | ModelConfig 中 `api_key` 明文存 PG、经 NATS 广播 | API Key 加密存储（AES-256），NATS 传输走 TLS |
|
||
| **CORS 配置** | 未见显式 CORS 配置 | 生产环境需严格限制允许源 |
|
||
| **Rate Limiting** | Redis 存 session/rate limit 但实现程度不明 | 确保关键 API（登录/任务提交）有完善的速率限制 |
|
||
| **依赖安全审计** | 无 dependabot / 漏洞扫描 | 启用 GitHub Dependabot + `go vet` / `govulncheck` CI |
|
||
|
||
### 6.5 运维与部署
|
||
|
||
| 问题 | 现状 | 建议 |
|
||
|---|---|---|
|
||
| **无 CI/CD 流水线** | `.github/` 目录存在但未见完整 workflow | 配置 GitHub Actions：lint → test → build → deploy |
|
||
| **无 Kubernetes 部署** | 仅 docker-compose（开发环境） | 补充 Helm Chart 或 Kustomize，面向生产集群 |
|
||
| **健康检查不统一** | dispatcher 走 NATS ping，其它走 HTTP | 统一为 Kubernetes 标准的 liveness/readiness probe |
|
||
| **无数据备份策略** | PG/Milvus/Neo4j 数据卷无备份配置 | 配置 pg_dump 定时备份 + 对象存储归档 |
|
||
|
||
---
|
||
|
||
## 七、技术选型评价
|
||
|
||
| 选型 | 评分 | 评语 |
|
||
|---|---|---|
|
||
| **Go + NATS** | ⭐⭐⭐⭐⭐ | 高性能、低延迟、零拷贝，完美适配 AI 推理 Token 流场景 |
|
||
| **Eino (CloudWeGo)** | ⭐⭐⭐⭐ | 字节生态，ReAct/Compose Graph 成熟；但社区生态不如 LangChain/LlamaIndex |
|
||
| **Wails** | ⭐⭐⭐⭐ | Go+WebView 跨平台桌面端，避免 Electron 臃肿；但 WebView 兼容性不如 Electron |
|
||
| **Milvus + Bleve + Neo4j** | ⭐⭐⭐⭐ | 三路 RAG 架构领先；但三套存储的运维复杂度高 |
|
||
| **React Flow** | ⭐⭐⭐⭐⭐ | 低代码编排标配，生态成熟，@xyflow/react v12 性能好 |
|
||
| **Python MCP 层** | ⭐⭐⭐ | 算法型工具用 Python 合理；但 MCP/MinerU 仍为桩，实际价值待兑现 |
|
||
|
||
---
|
||
|
||
## 八、代码量统计（估算）
|
||
|
||
| 模块 | Go 代码 | TS/TSX 代码 | Python 代码 | 说明 |
|
||
|---|---|---|---|---|
|
||
| `sundynix-shared` | ~1,500 行 | - | - | 契约 + NATS 总线 |
|
||
| `sundynix-gateway` | ~6,000 行 | - | - | 鉴权/DSL/存储/路由/SSE |
|
||
| `sundynix-dispatcher` | ~8,000 行 | - | - | Eino 编排/ReAct/报告/评测/熔断 |
|
||
| `sundynix-mcp-go` | ~5,000 行 | - | - | RAG 三路/记忆/Office/MCP |
|
||
| `sundynix-mcp-py` | - | - | ~1,500 行 | 沙箱/解析/解释器/MCP |
|
||
| `sundynix-desktop` | ~300 行(Go) | ~8,000 行 | - | Wails 绑定 + React 全套 |
|
||
| `sundynix-admin` | - | ~3,000 行 | - | 运维控制台 |
|
||
| **合计** | **~21,000 行** | **~11,000 行** | **~1,500 行** | **~33,500 行** |
|
||
|
||
---
|
||
|
||
## 九、总体评价
|
||
|
||
> **sundynix-agentix 是一个架构设计水准较高、功能相当完整的 AI Agent 平台原型。**
|
||
|
||
**核心竞争力**在于：
|
||
1. **NATS 零拷贝骨干网** — 贯穿全栈的消息总线设计，比 HTTP 微服务更适合 AI 场景
|
||
2. **三路混合 RAG** — 向量+全文+图谱的 RRF 融合，业界领先
|
||
3. **可视化编排 + ReAct** — 低代码画布 + 自主 Agent 双模式，兼顾不同用户群
|
||
4. **Generative Agents 记忆** — 带打分的自然遗忘记忆系统，超越大部分同类项目
|
||
|
||
**主要风险**在于：
|
||
1. 基础设施复杂度高（6 个存储组件），运维压力大
|
||
2. 前端缺少测试和路由，随功能增长技术债务会快速累积
|
||
3. Python MCP 层实现深度不足，核心差异化功能（MinerU OCR、安全沙箱）仍为桩
|
||
4. 缺少 CI/CD、链路追踪、集中配置等生产级工程化基础设施
|
||
|
||
**项目成熟度**：处于 **高完成度 MVP** 阶段，核心数据流和关键功能闭环已通，具备向生产环境演进的基础。
|