sundynix-agentix/project_analysis.md

# sundynix-agentix · 项目深度分析

## 一、项目定位

**sundynix-agentix** 是一个**分层式 AI Agent 平台**，采用 **Monolith First → Microservices (Morph B)** 的演进策略。核心价值主张是：用可视化画布编排 AI Agent 工作流，通过 NATS 消息总线解耦各层，支持知识库混合检索（RAG）、长期记忆、报告生成、代码解释器等企业级 AI 能力。

---

## 二、架构概览

采用 **5 层 + 1 条 NATS 零拷贝消息总线** 的分层架构：

```mermaid
flowchart LR
  C["1·Client<br/>Wails+React 19"] --> G["2·Gateway<br/>Gin"]
  G --> N["3·NATS<br/>JetStream"]
  N --> D["4·Dispatcher<br/>Eino"]
  N --> T1["5a·MCP-Go<br/>I/O工具"]
  N --> T2["5b·MCP-Py<br/>算法工具"]
  D --> T1
  D --> T2
```

| 层 | 模块 | 职责 |
|---|---|---|
| **1·Client** | `sundynix-desktop` | Wails 桌面端 + 浏览器模式双轨；React Flow 画布可视化编排 Agent → 导出 JSON DSL |
| **2·Gateway** | `sundynix-gateway` | Gin 统一接入、JWT 鉴权、DSL 解析组装、计费计量、输入护栏、模型配置控制面 |
| **3·Bus** | NATS Server | 零拷贝骨干网：JetStream 任务队列 + core NATS Token 流 / 执行轨迹 / 工具调用 |
| **4·Dispatcher** | `sundynix-dispatcher` | Eino 图编排引擎、LLM Pool、ReAct Agent、报告多步编排、熔断降级、LLM 评测 |
| **5a·MCP-Go** | `sundynix-mcp-go` | 混合检索(Bleve+Milvus+Neo4j)、长期记忆(PgSQL)、Word 渲染、外部 API |
| **5b·MCP-Py** | `sundynix-mcp-py` | 安全沙箱(AST 守卫)、Docker 代码解释器、文档解析(docx/pdf/xlsx) |
| **Admin** | `sundynix-admin` | 独立运维控制台（模型/数据源配置、服务状态、计价管理） |

---

## 三、技术栈全景

### 后端（Go 为主 + Python 补充）

| 领域 | 技术选型 |
|---|---|
| **语言** | Go 1.25（主力，4 模块）、Python 3.11+（算法型工具 1 模块） |
| **Web 框架** | Gin（Gateway 层） |
| **AI 编排** | CloudWeGo Eino（图编排 + ChatModel + ReAct Agent） |
| **消息总线** | NATS + JetStream（任务队列、Token 流、工具调用、配置下发） |
| **关系数据库** | PostgreSQL 16（用户/计费/DSL/画像/文库） + GORM |
| **缓存** | Redis 7（Session / Rate Limit） |
| **向量数据库** | Milvus 2.4（向量检索） |
| **搜索引擎** | Bleve（Go 原生全文索引） |
| **知识图谱** | Neo4j 5（三元组存储 + GraphRAG） |
| **对象存储** | MinIO（大文件正文） |
| **ID 生成** | Snowflake 雪花 ID（全库统一规约） |
| **文档处理** | 自建零依赖 OOXML（Word 渲染）、python-docx、openpyxl、pypdf |

### 前端

| 领域 | 技术选型 |
|---|---|
| **框架** | React 19 + TypeScript |
| **桌面端** | Wails v2（TS/Go 强绑定、原生窗口） |
| **构建** | Vite 5 |
| **样式** | Tailwind CSS 3 |
| **Agent 编排** | React Flow（@xyflow/react v12） |
| **可视化** | react-force-graph-2d（知识图谱力导向图） |
| **图标** | Lucide React |

### 基础设施

| 领域 | 技术选型 |
|---|---|
| **容器编排** | Docker Compose（开发环境） |
| **构建工具** | Makefile（一键启动各服务） |
| **Monorepo** | Go workspace（`go.work`） |
| **安全沙箱** | Docker 容器隔离（禁网/非root/丢能力/只读根）+ AST 静态守卫 |

---

## 四、核心代码统计

| 类别 | 文件数 | 代码行数 |
|---|---|---|
| Go 源码（非测试） | 60 | ~8,000 |
| TypeScript/TSX | 49 | ~5,000 |
| Python | 10 | ~620 |
| Go 测试文件 | 18 | ~4,000（估） |
| **合计** | ~137 | **~13,600+** |

---

## 五、已实现功能详析

### 5.1 Agent 可视化编排

- React Flow 画布拖拽编排 Agent 工作流
- 支持 **11 种节点类型**：input / memory / retriever / tool / agent / aggregate / render / branch / map / output + 自定义
- **Branch 分支**：条件表达式求值，支持 true/false 边标签精确选路（向后兼容无标签旧图）
- **Map 并行 fan-out**：LLM 拆分子项 → 有界并发撰写 → 汇聚
- DSL 导出为 JSON，经 Gateway 解析后通过 NATS 投递

### 5.2 图编排执行引擎

- [graph.go](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-dispatcher/internal/eino/graph.go)：按 DSL 的真实拓扑执行（非线性拍平），支持拓扑排序 → 逐节点激活 → 分支剪枝
- 黑板模式（`board`）在节点间传递状态：画像/历史/检索结果/工具产出/成稿
- 无图/空图时退化为「无图单轮对话」

### 5.3 ReAct 自主 Agent

- [react_agent.go](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-dispatcher/internal/eino/react_agent.go)：模型在 ReAct 循环中自主决定调哪些 MCP 工具
- 适配了 Eino 的 `react.NewAgent`，自定义 `streamHasToolCall` 解决 DeepSeek 先吐文本再给 tool call 的兼容问题
- 最大 8 步限制控成本
- 模型不支持函数调用时优雅降级回普通对话

### 5.4 RAG 混合检索

- [rag.go](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-mcp-go/internal/rag/rag.go)：三路混合检索
  - **向量路**：Embedding → Milvus ANN 检索
  - **全文路**：Bleve 全文索引
  - **图谱路**：Neo4j 知识图谱三元组匹配
- **RRF 融合**（Reciprocal Rank Fusion）合并三路结果
- 可选 **Rerank** 精排
- 入库流水线：切块 → 分批向量化 → Milvus + Bleve + LLM 实体抽取 → Neo4j

### 5.5 长期记忆（Generative Agents 式）

- [store.go](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-mcp-go/internal/memory/store.go)：基于 PgSQL 的用户画像存储
- **读路径**：Score = 0.4·Recency(指数衰减) + 0.6·Importance(1-10) → 降序排序 → top-30 截断
- **写路径**：Upsert (user_id, key) 冲突覆盖 + last_seen 印证
- **Consolidate**：每 3 轮异步攒批，LLM 对账产出 ADD/UPDATE/DELETE/NOOP
- 桌面端记忆面板支持查看/编辑/软删

### 5.6 报告生成

- [report.go](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-dispatcher/internal/eino/report.go)：专用多步编排
  1. LLM 规划 3-5 章大纲
  2. 各章有界并发（max 4）：RAG 检索参考资料 → LLM 撰写
  3. 流式呈现 Markdown 进度
  4. 存源 → 按需导出 Word/PDF/Markdown
- 每次 LLM 调用套 60s 超时防挂死

### 5.7 安全体系（纵深防御）

| 层级 | 机制 |
|---|---|
| 输入护栏 | 拦截提示词注入 + 超大体（[guardrail](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-gateway/internal/guardrail)） |
| 输出护栏 | 逐片脱敏 sk-/AKIA/JWT/Bearer 疑似密钥（[output.go](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-dispatcher/internal/harness/output.go)） |
| 代码沙箱 | AST 静态守卫 → Docker 隔离执行（禁网/非root/限资源/一次性）（[sandbox.py](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-mcp-py/src/sundynix_mcp_py/sandbox.py)） |
| 鉴权 | JWT 注册/登录/校验 + RequireAuth + RequireAdmin 白名单 |
| 熔断 | 三态状态机 Closed/Open/HalfOpen（[circuitbreaker.go](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-dispatcher/internal/harness/circuitbreaker.go)） |

### 5.8 可观测性

- Prometheus `/metrics`（请求数/耗时/在途）
- 结构化 JSON 访问日志 + X-Request-ID
- `/healthz`(存活) + `/readyz`(就绪) 探针
- 执行轨迹流（`sundynix.exec.<id>`）：节点级实时观测（点亮、工具入参/产出、耗时）
- 运维控制台健康五盏灯

### 5.9 知识库

- 文件入库（docx/xlsx/pdf）+ 入库进度实时可视化（解析→切块→向量化→抽实体时间线）
- Obsidian 式文库（Markdown 阅读 + `[[双链]]` + 反链 + 笔记关系图）
- 检索调试台 + 知识图谱力导向图可视化
- 批量文件/文件夹入库

---

## 六、优势分析

### ✅ 1. 架构设计成熟度高

**5 层分层 + NATS 消息总线解耦**是该项目最突出的架构亮点。每一层职责清晰、边界明确：
- Client 只负责交互和 DSL 导出
- Gateway 做接入/鉴权/护栏
- NATS 解耦上下游（异步任务队列 + 同步工具调用 + 流式回流）
- Dispatcher 专注编排
- MCP 工具层按能力拆分（Go I/O / Python 算法）

这种架构天然支持后续的微服务化拆分（Morph B），当前 Monolith First 的策略也是务实的。

### ✅ 2. 全链路降级设计（"不 fatal，降级"哲学）

项目贯彻了一个非常好的设计原则——**任何依赖不可用时都能降级运行**：
- Milvus 不在 → 向量检索降级（只走全文）
- Neo4j 不在 → 图谱降级
- Redis 不在 → 限流降级
- Postgres 不在 → 记忆降级（空回）
- LLM 不在 → 桩文本流式输出
- MCP 工具超时 → 降级跳过，不阻断推理

这使得开发调试极其友好（`make demo` 无需 Docker 即可跑通核心链路）。

### ✅ 3. 消息总线使用高水平

NATS 的使用非常规范和深入：
- **JetStream** 做持久化任务队列（at-least-once，失败 NakWithDelay 重投）
- **Core NATS** 做零拷贝 Token 流（低延迟、不持久化）
- **Request-Reply** 做同步工具调用（队列组负载均衡）
- **Pub-Sub** 做配置热更新广播
- 内嵌 NATS 支持无 Docker 联调（`devnats`）

### ✅ 4. 图编排引擎实力扎实

Eino 图编排引擎的实现非常完整：
- 拓扑排序执行（非线性拍平），支持 DAG 任意结构
- Branch 真/假边精确选路 + 条件表达式求值
- Map 并行 fan-out + 有界并发 + Aggregate 汇聚
- ReAct Agent（模型自主工具选择）
- 黑板模式传递中间状态

### ✅ 5. RAG 实现达到产品级

三路混合检索（向量 + 全文 + 图谱）→ RRF 融合 → 可选 Rerank 的 RAG 方案在开源项目中属于高水平。入库流水线的实时进度回流、知识图谱实体抽取、批量向量化等功能齐全。

### ✅ 6. 长期记忆设计有学术功底

参考 Generative Agents 论文的 Recency + Importance 打分机制，实现了攒批 Consolidate、指数衰减、重要度排序、自然遗忘等机制，超越了大多数 Agent 平台的简单 key-value 存储。

### ✅ 7. 安全纵深防御

从输入护栏 → 输出脱敏 → AST 守卫 → Docker 隔离形成了多层安全防线，且标注了 gVisor/Kata 生产加固路径。

### ✅ 8. 工程规范统一

- 全库统一雪花 ID + 软删规约
- Go workspace 统一后端模块
- Makefile 一键操作
- 配置零散（clone 后零配置可跑）
- 合理的测试覆盖（18 个测试文件，含 e2e、集成测试、-race）

### ✅ 9. 桌面端双轨设计

Wails 原生桌面 + 浏览器模式优雅降级，前端代码复用，开发体验好。

### ✅ 10. 开发体验友好

- `make demo` 一键验证全链路（内嵌 NATS，无需 Docker）
- `make e2e` 端到端测试
- 配置控制面热更新（改模型无需重启）
- 详尽的 README 和 PROGRESS 跟踪

### ✅ 11. 可观测性到位

Prometheus metrics、结构化日志、健康探针、执行轨迹实时流——生产级可观测四要素基本齐全。

### ✅ 12. 测试策略合理

用 LLM 接口抽象（`type LLM interface`）实现了对 Dispatcher 核心逻辑的假替身测试，包括分支/工具/map/脱敏等场景，含 `-race` 并发安全检测。

---

## 七、不足与改进建议

### ⚠️ 1. 切块策略过于朴素

[rag.go chunk()](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-mcp-go/internal/rag/rag.go#L256-L270) 当前仅按行切、超 2000 字符强截——**生产环境这是 RAG 质量的瓶颈**。

```go
// 当前：朴素切块
func chunk(text string) []string {
    for _, line := range strings.Split(text, "\n") { ... }
}
```

> **建议**：引入语义切块（Recursive Character Splitter / Sentence Window / Agentic Chunking），按段落/标题层级自然断句，并支持 overlap（上下文重叠）以减少边界信息丢失。

### ⚠️ 2. 前端测试完全缺失

> [!WARNING]
> PROGRESS.md 明确标注："前端测试仍无"。49 个 TSX/TS 文件、~5000 行代码没有任何测试覆盖，是当前最大的工程风险之一。

> **建议**：至少对核心组件（StudioView/KbView/ReportView）补 Vitest + React Testing Library 单测；对关键流程（编排→运行→观测）补 Playwright E2E。

### ⚠️ 3. 错误处理不够结构化

多处使用 `log.Printf` + 返回空值的降级模式，虽然保证了可用性，但 **调试定位困难**：

```go
if err != nil {
    log.Printf("[rag] Milvus 不可用，向量检索降级: %v", err)
} // 没有 metrics 计数降级事件
```

> **建议**：
> - 引入结构化 error wrapping（`fmt.Errorf("...: %w", err)`）
> - 对降级事件增加 Prometheus 计数器（`degradation_total{component="milvus"}`）
> - 考虑引入 `slog`（Go 1.21+标准库）替换 `log.Printf`

### ⚠️ 4. 配置管理方式偏硬编码

常量散落在各包中（`defaultThreshold = 5`、`reactMaxStep = 8`、`memTopN = 30` 等），缺少统一的配置层：

> **建议**：引入环境变量 / 配置文件 / Viper 统一管理可调参数，尤其是：
> - 熔断阈值/冷却时间
> - ReAct 步数上限
> - 记忆 top-N / 衰减因子
> - 报告并发数/超时

### ⚠️ 5. 计费模块未完成

计价配置（单价/币种）已落库，但 **真实的用量计量 × 单价 = 费用 的闭环尚未实现**。当前 `Token 流` 经 NATS 回流但未做计量统计。

> **建议**：在 Token 流的 `PublishToken` 处增加计量 Hook（原子计数器），按 session/user 聚合后写入计费表。

### ⚠️ 6. MCP-Py 模块功能较薄

Python 端仅实现了：
- 静态代码守卫（sandbox.py）
- Docker 代码解释器（interpreter.py）
- 文档解析桩（parsers.py）

相比 Go 端的 7 个子包，Python 端功能密度低。**MinerU/PaddleOCR 多模态解析仍为骨架**，MCP 协议网关依赖包已注释。

### ⚠️ 7. 数据库连接池/事务管理缺失

GORM 使用默认连接池配置，无自定义 `MaxOpenConns`、`MaxIdleConns`、`ConnMaxLifetime` 等调优。多处查询/写入未使用事务保护一致性（如 Ingest 的 Milvus+Bleve+Neo4j 三写）。

> **建议**：
> - 在 `Open()` 中配置合理的连接池参数
> - 对多步写入引入事务或补偿机制

### ⚠️ 8. 缺少 CI/CD 自动化

未发现 `.github/workflows`、`.gitlab-ci.yml` 或其他 CI 配置。当前依赖 `make test` 手动触发。

> **建议**：配置 GitHub Actions / GitLab CI，至少覆盖：
> - 每次 push：`make test`（Go + TS 类型检查 + Python）
> - PR 合并：`make e2e`
> - 自动构建 Docker 镜像

---

## 八、总结评价

| 维度 | 评分 | 说明 |
|---|---|---|
| **架构设计** | ⭐⭐⭐⭐⭐ | 5 层分层 + NATS 解耦，成熟度极高 |
| **功能完整度** | ⭐⭐⭐⭐ | Agent 编排/RAG/记忆/报告/安全均已落地，计费/MCP-Py 有缺 |
| **代码质量** | ⭐⭐⭐⭐ | 注释充分、职责清晰、降级设计优秀；配置硬编码/日志结构化可改进 |
| **测试覆盖** | ⭐⭐⭐ | 后端 18 个测试文件含 e2e/集成/race；**前端零测试**拉低分 |
| **工程化** | ⭐⭐⭐⭐ | Monorepo/Makefile/Docker Compose/统一规约；缺 CI/CD |
| **可扩展性** | ⭐⭐⭐⭐⭐ | NATS 消息总线天然支持水平扩展和微服务化 |
| **安全性** | ⭐⭐⭐⭐ | 纵深防御（输入/输出/沙箱/鉴权/熔断）；JWT 密钥管理可强化 |
| **开发体验** | ⭐⭐⭐⭐⭐ | `make demo` 零配置跑通全链路，热更新模型，文档详尽 |

> [!TIP]
> **综合评价**：这是一个架构功力深厚、功能覆盖广泛的 AI Agent 平台原型。其分层设计、消息总线解耦、全链路降级哲学和 Generative Agents 式记忆机制都体现了高水平的工程设计。当前阶段最值得投入的改进方向是：**前端测试覆盖**、**RAG 切块质量**、**CI/CD 自动化**。