# 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 后即可上线。