# sundynix-agentix 项目全面分析

## 一、项目定位

分层式 AI Agent 平台，采用 **Monolith First → Microservices (Morph B)** 演进策略。  
目标是构建一个集 **Agent 可视化编排、知识库 RAG、报告生成、用户记忆** 于一体的企业级 AI 工作站。

---

## 二、技术栈总览

| 层级 | 模块 | 语言/框架 | 核心依赖 |
|---|---|---|---|
| **1. 客户端** | `sundynix-desktop` | Wails + React 19 + TypeScript | @xyflow/react (React Flow), 自建 UI 原语(`src/ui`，非 shadcn), 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, 自建零依赖 OOXML(.docx，刻意不用商业授权的 UniOffice), 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 渲染**：自建零依赖 OOXML 渲染 .docx 文档（不引第三方 Office 库），一键下载
- **流式进度**：规划/撰写进度实时流回客户端
- **报告源持久化**：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 订阅轨迹，逐节点展示执行状态
- **Token 流可回放 + 断点续传**：网关把 Token 流落 Redis Stream，SSE 带 `Last-Event-ID`，连晚/刷新/网络抖动重连均不丢 token（Redis 降级时回退 live NATS）

### 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 全局命令面板（键盘优先工作站）
- **GitHub Releases 分发 + 自动检查更新**：打 `vX.Y.Z` 标签经 release workflow 自动构建 mac/win 安装包发布到 Releases；桌面端启动查 `releases/latest`，有新版弹横幅引导下载

---

## 四、核心数据流

```
客户端 → 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()` + `CORS_ALLOW_ORIGIN`（缺省 `*` 仅供开发） | 生产环境把 `CORS_ALLOW_ORIGIN` 设为具体源 |
| **Rate Limiting** | 已实现：Redis 滑动窗口、按客户端 IP 每分钟限流（`middleware.RateLimit` + `store.Allow`） | 可对登录/任务提交等关键 API 单独配更严阈值 |
| **依赖安全审计** | 无 dependabot / 漏洞扫描 | 启用 GitHub Dependabot + `go vet` / `govulncheck` CI |

### 6.5 运维与部署

| 问题 | 现状 | 建议 |
|---|---|---|
| **CI/CD（部分完成）** | ✅ 已加 `ci.yml`（go build+vet+test / 前端 tsc / mcp-py 守卫）+ `release.yml`（tag 触发构建发布到 GitHub Releases） | 后续补：自动部署、govulncheck/Dependabot 安全扫描 |
| **无 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 合理；代码沙箱已可用，但 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/PaddleOCR 多模态解析仍为桩（代码执行沙箱已实现可用，run_code 已接入自主 agent）
4. 链路追踪、集中配置、k8s 部署、API Key 加密等生产级工程化设施待补（CI/CD 已具备）

**项目成熟度**：处于 **高完成度 MVP** 阶段，核心数据流和关键功能闭环已通，具备向生产环境演进的基础。