Blizzard
321 lines
20 KiB
Markdown
321 lines
20 KiB
Markdown
# sundynix-agentix 项目分析报告（2026-06-27）
|
||
|
||
> **分析时间**：2026 年 6 月 27 日（dev 分支，commit 148+）
|
||
>
|
||
> **一句话定位**：一个面向企业的 **AI Agent 编排平台**，支持可视化 DSL 构建 Agent 工作流、多模型热切换、RAG 知识库、长期记忆、自动评测闭环、人工审批（HITL）、桌面端原生应用 + Web 运维控制台，一键 Docker 部署。
|
||
|
||
---
|
||
|
||
## 一、整体架构（五层微服务）
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────┐
|
||
│ 第 1 层 · 客户端 │
|
||
│ ┌───────────────────────┐ ┌───────────────────────┐ │
|
||
│ │ sundynix-desktop │ │ sundynix-admin │ │
|
||
│ │ (Wails + React + TS) │ │ (Vite + React + TS) │ │
|
||
│ │ 桌面原生应用 │ │ Web 运维控制台 │ │
|
||
│ └──────────┬────────────┘ └──────────┬─────────────┘ │
|
||
│ │ HTTP/SSE │ HTTP │
|
||
│ ═══════════╪══════════════════════════╪═════════════════════════ │
|
||
│ 第 2 层 · API 网关 │
|
||
│ ┌──────────▼──────────────────────────▼─────────────┐ │
|
||
│ │ sundynix-gateway (Go · Gin) │ │
|
||
│ │ DSL 解析 / JWT 鉴权 / 护栏(Tier1) / SSE 流 / │ │
|
||
│ │ 状态机 / 评测落库 / 配置控制面 / MinIO │ │
|
||
│ │ Postgres + Redis + MinIO │ │
|
||
│ └──────────┬────────────────────────────────────────┘ │
|
||
│ │ NATS JetStream + core pub/sub │
|
||
│ ═══════════╪══════════════════════════════════════════════════ │
|
||
│ 第 3 层 · 调度与编排 │
|
||
│ ┌──────────▼──────────────────────────────────────┐ │
|
||
│ │ sundynix-dispatcher (Go · Eino) │ │
|
||
│ │ DSL 图引擎 / ReAct Agent / 流式推理 / 记忆对账 / │ │
|
||
│ │ 报告多步编排 / 自动评测+纠偏 / 熔断 / 预算护栏 │ │
|
||
│ └────────┬───────────────────────────┬──────────────┘ │
|
||
│ │ NATS request-reply │ │
|
||
│ ═════════╪═══════════════════════════╪═════════════════════ │
|
||
│ 第 4 层 · 共享契约与总线 │
|
||
│ ┌────────▼───────────────────────────▼────────────┐ │
|
||
│ │ sundynix-shared (Go) │ │
|
||
│ │ contract / bus(NATS) / otelx / secrets │ │
|
||
│ └──────────────────────────────────────────────────┘ │
|
||
│ ═══════════════════════════════════════════════════════════ │
|
||
│ 第 5 层 · MCP 工具微服务 │
|
||
│ ┌──────────────────────────────┐ ┌──────────────────────┐ │
|
||
│ │ sundynix-mcp-go (Go) │ │ sundynix-mcp-py (Py) │ │
|
||
│ │ RAG(Milvus+Bleve+Neo4j) / │ │ 文档解析(Word/PDF) / │ │
|
||
│ │ 记忆(PG) / 历史(Redis) / │ │ 代码沙箱(Docker) │ │
|
||
│ │ 报告渲染(docx) / 搜索 / │ │ 算法型 MCP 工具 │ │
|
||
│ │ 知识库管理 / 图谱 / 外部工具 │ │ │ │
|
||
│ └──────────────────────────────┘ └──────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 二、技术栈全景
|
||
|
||
### 后端（Go 1.25）
|
||
|
||
| 领域 | 技术选型 | 用途 |
|
||
|------|---------|------|
|
||
| HTTP 框架 | Gin 1.12 | 网关 REST API + SSE |
|
||
| Agent 编排 | CloudWeGo Eino | ReAct Agent、compose.Graph、流式推理 |
|
||
| 消息总线 | NATS JetStream | 任务分发、Token 回流、工具调用、配置广播、审批 |
|
||
| 关系库 | PostgreSQL 16 + GORM | 用户、任务、评测、画像、知识库元数据 |
|
||
| 缓存/流 | Redis 7 + go-redis | Session、Token 日预算、Redis Stream 回放 |
|
||
| 向量库 | Milvus 2.4 | RAG 向量检索 |
|
||
| 全文索引 | Bleve v2 | RAG 全文路 + RRF 融合 |
|
||
| 图数据库 | Neo4j 5 | 知识图谱三元组（GraphRAG） |
|
||
| 对象存储 | MinIO | 文件/文档/报告附件 |
|
||
| 链路追踪 | OpenTelemetry + Jaeger | 全链路 trace（NATS 传播） |
|
||
| 指标监控 | Prometheus client_golang | HTTP/任务/模型指标 |
|
||
| 认证鉴权 | JWT (golang-jwt/v5) + bcrypt | 用户注册/登录/token |
|
||
| 密钥管理 | AES-256-GCM (自建 secrets 包) | API Key 落库/过线加密 |
|
||
| ID 生成 | 雪花算法 (bwmarrin/snowflake) | 全局唯一 ID |
|
||
| 桌面端 | Wails v2 | Go + WebView 原生桌面应用 |
|
||
|
||
### 前端
|
||
|
||
| 领域 | 技术选型 | 用途 |
|
||
|------|---------|------|
|
||
| 框架 | React 19 + TypeScript | 桌面端 & 管理端 |
|
||
| 构建 | Vite 5 | 前端构建 |
|
||
| 样式 | TailwindCSS 3 | UI 样式 |
|
||
| 路由 | react-router-dom 7 | SPA 路由 |
|
||
| 图编辑 | @xyflow/react 12 (React Flow) | DSL 可视化编排画布 |
|
||
| 图谱可视化 | react-force-graph-2d | 知识图谱力导向图 |
|
||
| 图标 | lucide-react | UI 图标 |
|
||
| 测试 | Vitest + Testing Library | 前端单测 |
|
||
|
||
### Python（mcp-py）
|
||
|
||
| 领域 | 技术选型 | 用途 |
|
||
|------|---------|------|
|
||
| 运行时 | Python 3.11+ | 算法型工具 |
|
||
| 消息总线 | nats-py | 接入 NATS 骨干网 |
|
||
| 文档解析 | python-docx / openpyxl / pypdf | Word/Excel/PDF 解析 |
|
||
| 代码沙箱 | docker SDK | Docker 隔离执行环境 |
|
||
|
||
### 基础设施
|
||
|
||
| 组件 | 镜像 | 用途 |
|
||
|------|------|------|
|
||
| NATS | nats:2-alpine | 消息骨干网 (JetStream 持久化) |
|
||
| PostgreSQL | postgres:16-alpine | 关系存储 |
|
||
| Redis | redis:7-alpine | 缓存 / Stream / 预算 |
|
||
| Milvus | milvusdb/milvus:v2.4.13 | 向量数据库 |
|
||
| etcd | quay.io/coreos/etcd:v3.5.14 | Milvus 元数据 |
|
||
| MinIO | minio/minio | 对象存储 |
|
||
| Neo4j | neo4j:5-community | 图数据库 |
|
||
| Jaeger | jaegertracing/all-in-one:1.60 | 链路追踪 UI |
|
||
|
||
---
|
||
|
||
## 三、已实现功能清单
|
||
|
||
### 🧠 核心 AI 能力
|
||
|
||
| 功能 | 实现程度 | 关键文件 |
|
||
|------|---------|---------|
|
||
| **DSL 图编排引擎** | ✅ 完整 | `dispatcher/internal/eino/graph.go` — 11 种节点 (input/memory/retriever/tool/agent/aggregate/render/branch/approval/map/output)，拓扑排序执行 |
|
||
| **ReAct Agent（自主工具调用）** | ✅ 完整 | `dispatcher/internal/eino/react_agent.go` — Eino ReAct 循环，自动发现 MCP 工具目录，inject 参数绑定 |
|
||
| **流式推理** | ✅ 完整 | `orchestrator.go` — ChatStream / StreamText 双模，reasoning 思考过程入轨迹 |
|
||
| **多模型热切换** | ✅ 完整 | 控制面 NATS 广播 → Dispatcher/mcp-go 热更新，支持 OpenAI 兼容 / vLLM / Ollama |
|
||
| **报告多步编排** | ✅ 完整 | `report.go` — 规划大纲 → 并行(RAG+撰写) → 汇聚 → 渲染 Word/PDF/Markdown |
|
||
| **RAG 混合检索** | ✅ 完整 | `mcp-go/internal/rag/` — Milvus向量 + Bleve全文 + Neo4j图谱 → RRF融合 → 可选 Rerank |
|
||
| **知识图谱（GraphRAG）** | ✅ 完整 | LLM 抽三元组 → Neo4j 存储 → 检索时图谱路参与 RRF 融合 |
|
||
| **长期记忆（Generative Agents 式）** | ✅ 完整 | `memory/store.go` — Recency×Importance 加权排序，Consolidate 对账，Top-N 截断 |
|
||
| **短期多轮历史** | ✅ 完整 | Redis 存会话历史，自动召回注入上下文 |
|
||
| **记忆对账（Mem0 式 Consolidate）** | ✅ 完整 | `memory_extract.go` — 每 N 轮 LLM 对账 ADD/UPDATE/DELETE/NOOP |
|
||
| **多 Agent 协作** | ✅ 完整 | 黑板模式：agentOut 接力，前序 agent 产出注入下游 |
|
||
|
||
### 🛡️ 安全与治理（Harness）
|
||
|
||
| 功能 | 实现程度 | 关键文件 |
|
||
|------|---------|---------|
|
||
| **输入护栏 Tier1** | ✅ 完整 | `gateway/internal/guardrail/` — 归一化(去零宽/同形字/base64)→高精度注入正则→敏感词黑名单 |
|
||
| **输入护栏 Tier2** | ✅ 完整 | `dispatcher/internal/harness/jailbreak.go` — LLM 越狱分类器，灰区裁决 |
|
||
| **输出脱敏** | ✅ 完整 | `harness/output.go` — 跨分片 StreamRedactor (密钥/JWT/PII 手机号/邮箱/身份证)，防碎片泄漏 |
|
||
| **自动化评测** | ✅ 完整 | `harness/eval.go` — 规则检查 + LLM-as-judge + RAG 忠实度评测（幻觉检测） |
|
||
| **低分自动纠偏** | ✅ 完整 | `orchestrator.go#refine` — 评语驱动重生成，取更优者（恒温器闭环） |
|
||
| **熔断器** | ✅ 完整 | `harness/circuitbreaker.go` — 连续失败触发熔断，快速拒绝新任务 |
|
||
| **Token 预算** | ✅ 完整 | 单任务硬上限(TASK_TOKEN_BUDGET) + 单用户日预算(USER_DAILY_TOKEN_BUDGET) |
|
||
| **JWT 鉴权** | ✅ 完整 | `gateway/internal/auth/` — 注册/登录/中间件 |
|
||
| **密钥加密** | ✅ 完整 | `shared/secrets/` — AES-256-GCM 落库/过线，生产环境强制设密钥 |
|
||
|
||
### 🔍 可观测性
|
||
|
||
| 功能 | 实现程度 | 关键文件 |
|
||
|------|---------|---------|
|
||
| **全链路 Trace** | ✅ 完整 | OTel → Jaeger，NATS 消息头传播 trace_id |
|
||
| **执行可视化轨迹** | ✅ 完整 | ExecEvent 回流 — 节点点亮/工具入参产出/耗时/分阶段 |
|
||
| **Redis 回放** | ✅ 完整 | Token 流 + 执行轨迹 Redis Stream 录制 → SSE 断点续传 |
|
||
| **运行历史复盘** | ✅ 完整 | PG 持久化(output+trace)，过 Redis TTL 仍可读库复盘 |
|
||
| **服务健康灯** | ✅ 完整 | 聚合 6 依赖(gateway/nats/db/redis/milvus/neo4j)实时状态 |
|
||
| **Prometheus 指标** | ✅ 基础 | `/metrics` 端点可用 |
|
||
|
||
### 📱 客户端
|
||
|
||
| 功能 | 实现程度 | 说明 |
|
||
|------|---------|------|
|
||
| **桌面原生应用** | ✅ 完整 | Wails v2 — Go 后端 + React/TS 前端 |
|
||
| **可视化 DSL 画布** | ✅ 完整 | React Flow 拖拽编排 Agent 图 |
|
||
| **实时仪表盘** | ✅ 完整 | 任务/评测/知识库/Token/服务状态聚合展示 |
|
||
| **运行·观测页** | ✅ 完整 | 三栏布局：历史列表 / 轨迹面板 / Markdown 输出 |
|
||
| **知识库管理** | ✅ 完整 | 入库进度实时回流、图谱可视化 |
|
||
| **偏好记忆面板** | ✅ 完整 | 查看/编辑/删除个人偏好 |
|
||
| **人工审批（HITL）** | ✅ 完整 | 审批节点暂停 → UI 弹批准/拒绝 → 决定回传 |
|
||
| **运维控制台** | ✅ 完整 | 模型配置(chat/embedding) / 服务状态 / 计费 |
|
||
| **Markdown 渲染** | ✅ 完整 | 表格/代码围栏/图表/流式渲染 |
|
||
|
||
### 🚀 部署与运维
|
||
|
||
| 功能 | 实现程度 | 说明 |
|
||
|------|---------|------|
|
||
| **Docker 容器化** | ✅ 完整 | 5 个服务各自 Dockerfile |
|
||
| **一键 Docker Compose 部署** | ✅ 完整 | `docker-compose.prod.yml` — 应用+基建一把拉起，安全配置 |
|
||
| **优雅停机** | ✅ 完整 | SIGTERM → drain 排空在途任务/工具 → 超时兜底 |
|
||
| **HA 多副本安全** | ✅ 完整 | 事件订阅队列组(QueueGateway)，杜绝重复落库/计费 |
|
||
| **Go Workspace** | ✅ 完整 | `go.work` 管理 4 个 Go 模块 |
|
||
| **Makefile** | ✅ 完整 | 一键启停、测试、构建 |
|
||
|
||
---
|
||
|
||
## 四、代码规模
|
||
|
||
| 指标 | 数据 |
|
||
|------|------|
|
||
| **Go 源码** | ~15,600 行 |
|
||
| **Go 测试** | ~3,400 行 |
|
||
| **TypeScript/TSX** | ~6,300 行 |
|
||
| **Python** | ~640 行 |
|
||
| **总代码** | **~26,000 行** |
|
||
| **Git 提交** | 148 次 |
|
||
| **Go 模块** | 4 个 (shared/gateway/dispatcher/mcp-go) |
|
||
| **微服务** | 6 个 (gateway/dispatcher/mcp-go/mcp-py/admin/desktop) |
|
||
| **基础设施组件** | 7 个 (NATS/PG/Redis/Milvus/etcd/MinIO/Neo4j) |
|
||
| **Docker 服务** | 12 个 (5 应用 + 7 基建) |
|
||
|
||
---
|
||
|
||
## 五、项目成熟度评级
|
||
|
||
### ⭐ 综合评定：**准生产级（Pre-Production / Late-Beta）**
|
||
|
||
对标业界分级：
|
||
|
||
| 维度 | 评分 (1-5) | 说明 |
|
||
|------|:---:|------|
|
||
| **架构设计** | ⭐⭐⭐⭐⭐ | 五层解耦、NATS 骨干网、契约驱动、降级容错、热更新 —— 架构非常成熟 |
|
||
| **功能完整度** | ⭐⭐⭐⭐☆ | AI Agent 编排的核心闭环完整，HITL/评测/纠偏/护栏/记忆均已落地 |
|
||
| **代码质量** | ⭐⭐⭐⭐☆ | 注释详实（中文），错误处理层次分明，降级模式完备，接口抽象合理 |
|
||
| **测试覆盖** | ⭐⭐⭐☆☆ | 关键路径有 e2e/集成/单测（3400行），但覆盖率还有提升空间 |
|
||
| **可观测性** | ⭐⭐⭐⭐⭐ | 全链路 trace + 执行轨迹 + Redis 回放 + 健康灯 + 评测落库 —— 业界标杆级 |
|
||
| **安全治理** | ⭐⭐⭐⭐☆ | 多层护栏 + 密钥加密 + JWT + 输出脱敏 + 预算控制 —— 极其完善 |
|
||
| **部署运维** | ⭐⭐⭐⭐☆ | 一键 compose + 优雅停机 + HA + Makefile，缺 k8s/Helm 和 CI/CD |
|
||
| **文档** | ⭐⭐⭐⭐☆ | 多份分析/架构/部署/进度文档，缺 API 文档(Swagger)和用户手册 |
|
||
|
||
---
|
||
|
||
## 六、优势亮点 🌟
|
||
|
||
### 1. 架构设计精良
|
||
- **五层解耦**：Gateway/Dispatcher/MCP 职责清晰，NATS 骨干网松耦合
|
||
- **全面降级**：每个依赖不可用都有 graceful degradation（Milvus 挂→不检索、Redis 挂→不缓存、Neo4j 挂→不图谱，从不阻断主流程）
|
||
- **热更新**：模型配置经 NATS 广播实时生效，无需重启
|
||
- **契约驱动**：`sundynix-shared/contract` 统一定义所有跨服务数据结构与通信约定
|
||
|
||
### 2. AI 编排能力深度
|
||
- **DSL 图引擎** 支持 11 种节点类型，拓扑排序 + branch 条件剪枝 + map 并行 fan-out
|
||
- **ReAct Agent** 与 MCP 工具目录自发现联动：新增工具只需在 MCP 注册，无需改编排代码
|
||
- **Mem0 式记忆对账**：不是简单 kv 覆盖，而是 LLM 对账 ADD/UPDATE/DELETE + Importance 打分 + Recency 衰减
|
||
- **自动评测闭环**：规则检查 → LLM-as-judge → 忠实度(幻觉检测) → 低分自动纠偏 → 评测结果落库
|
||
|
||
### 3. 安全治理（Harness）体系完整
|
||
- **输入护栏**：Tier1(归一化反绕过 + 正则 + 黑名单) → Tier2(LLM 越狱裁决)，两级过滤成本最优
|
||
- **输出护栏**：跨分片流式脱敏(StreamRedactor)，解决了流式场景密钥碎片泄漏的工程难题
|
||
- **成本护栏**：单任务 token 硬上限 + 单用户日预算 + 熔断器，三重保护防成本失控
|
||
|
||
### 4. 可观测性一流
|
||
- **全链路 Trace**：Gateway → NATS → Dispatcher → MCP，trace_id 跨消息总线传播
|
||
- **执行轨迹（ExecEvent）**：每个节点、每次工具调用都有结构化事件，前端可实时点亮/回放
|
||
- **Redis Stream 录制**：Token 流 + 轨迹事件录进 Redis → SSE 断点续传，根治"连晚/重连丢数据"
|
||
|
||
### 5. 工程实践规范
|
||
- 注释全中文，设计意图/降级策略/约束原因写得极其清楚
|
||
- 错误处理一致：降级 vs 上抛 vs 快速拒绝各有明确策略
|
||
- 接口抽象（`TokenSink`/`ToolCaller`/`StatusSink`/`LLM`）便于测试注入
|
||
- 雪花 ID + GORM 软删 + BaseModel 统一规约
|
||
|
||
---
|
||
|
||
## 七、不足与改进方向 ⚠️
|
||
|
||
### 1. 测试覆盖需扩展
|
||
- **现状**：关键路径有测试（e2e/集成/单测 3400 行），但占源码比 ~22%
|
||
- **缺失**：前端组件测试、Gateway handler 单测、MCP 工具完整覆盖
|
||
- **建议**：引入覆盖率工具（go tool cover），目标核心包 ≥ 70%
|
||
|
||
### 2. API 文档缺失
|
||
- **现状**：无 Swagger/OpenAPI 文档，API 契约只能看代码
|
||
- **建议**：集成 swag（Gin 生态），自动生成 API 文档
|
||
|
||
### 3. CI/CD 流水线未建
|
||
- **现状**：`.github/` 目录存在但未见完整 CI 配置
|
||
- **建议**：GitHub Actions — lint → test → build → push image → deploy staging
|
||
|
||
### 4. 前端状态管理偏原始
|
||
- **现状**：桌面端直接 fetch + useState，无全局状态管理
|
||
- **建议**：引入 zustand 或 jotai，统一 WebSocket/SSE 状态
|
||
|
||
### 5. 知识库功能缺分片与多租户隔离
|
||
- **现状**：知识库按 `owner/kb` 名称隔离，但 Milvus Collection 粒度较粗
|
||
- **建议**：生产环境引入 Partition Key 或多 Collection 策略
|
||
|
||
### 6. Python 微服务较薄
|
||
- **现状**：mcp-py 约 640 行，文档解析和代码沙箱为桩/初步实现
|
||
- **建议**：完善 MinerU OCR 接入、MCP 协议标准化
|
||
|
||
### 7. 缺乏 k8s/Helm 部署方案
|
||
- **现状**：仅 Docker Compose 编排
|
||
- **建议**：为生产环境提供 Helm Chart，支持 HPA、PDB、健康检查
|
||
|
||
### 8. 缺少限流与 Rate Limiting
|
||
- **现状**：成本护栏有 token 预算，但 HTTP 层无速率限制
|
||
- **建议**：Gin 中间件加速率限制（令牌桶/滑动窗口），配合 Redis
|
||
|
||
### 9. 日志结构化不完整
|
||
- **现状**：混用 `log.Printf` 与 `slog`
|
||
- **建议**：统一 slog + JSON 输出，便于 ELK/Loki 采集
|
||
|
||
### 10. 前端无 i18n
|
||
- **现状**：UI 文案硬编码中文
|
||
- **建议**：如需国际化，引入 i18next
|
||
|
||
---
|
||
|
||
## 八、与同类产品对标
|
||
|
||
| 对标产品 | sundynix-agentix 对比 |
|
||
|---------|---------------------|
|
||
| **Dify** | 架构更工程化(微服务 vs 单体)，护栏/评测/纠偏闭环更完整，但 UI 完成度不如 Dify |
|
||
| **Coze** | 类似的 Agent 编排理念，sundynix 是完全开源自建可控，支持私有化部署 |
|
||
| **LangGraph** | sundynix 的 DSL 图引擎类似 LangGraph 的状态机，但额外内置 HITL/熔断/预算/评测 |
|
||
| **Mem0** | sundynix 的记忆系统借鉴 Mem0 的 consolidate 模式，且与编排引擎深度集成 |
|
||
|
||
---
|
||
|
||
## 九、总结
|
||
|
||
经过 3 天的密集改造，项目已经从一个基础的 Agent 框架跃升到**准生产级的 AI Agent 编排平台**。核心突破集中在三个方面：
|
||
|
||
1. **Harness 治理栈完整落地**：输入护栏(两级) → 输出脱敏(跨分片) → 自动评测 → 低分纠偏 → 熔断 → 预算控制，形成完整的「恒温器」闭环
|
||
2. **可观测性达到业界标杆**：全链路 Trace + 执行轨迹 + Redis 回放 + 历史复盘 + 健康灯，任何一次运行都可以"时光倒流"复盘
|
||
3. **部署与 HA 就绪**：Docker Compose 一键部署 12 个服务、优雅停机、多副本安全、密钥加密
|
||
|
||
项目最大的技术亮点是**将 AI 治理（安全/质量/成本）作为一等公民嵌入架构**，而非事后附加——这在开源 Agent 框架中相当稀缺。
|
||
|
||
> **一句话评价**：架构成熟度已达准生产级，补齐测试覆盖、API 文档和 CI/CD 后即可上线。
|