sundynix-agentix/project_analysis.md

# sundynix-agentix · 项目分析报告（main 分支）

> 分析时间：2026-06-24 · 基于 main 分支 **117 次** Git 提交 · ~19,500 行源代码

---

## 一、项目概况

sundynix-agentix 是一个**分层式 AI Agent 平台**，采用 **5 层架构 + NATS 零拷贝消息总线**，
遵循 **Monolith First → Microservices (Morph B)** 演进策略。

### 代码规模

| 维度 | 数据 |
|------|------|
| **总代码行数** | **~19,453 行** (不含依赖 / 生成文件) |
| Go 后端 | 12,916 行（含 2,397 行测试） |
| TypeScript/TSX 前端 | 5,834 行（桌面端 4,628 + 运维台 1,181） |
| Python MCP 工具 | 641 行 |
| Git 提交数 | **117 次** |
| 源文件数 | ~160 个 |
| Go 模块 | 5 个（gateway / dispatcher / mcp-go / shared / desktop） |
| 前端应用 | 2 个（桌面端 + 运维控制台） |
| 测试文件 | **32 个**（Go 22 + TS/TSX 5 + Python 1 + setup 1 + CI 3） |
| 测试代码 | **~2,776 行** |
| CI/CD | **2 条 GitHub Actions**（CI + Release） |

### 各模块代码分布

| 模块 | 行数 | 职责 |
|------|------|------|
| sundynix-dispatcher | 4,222 | Eino 图编排 + compose 编译器 + ReAct 智能体 + 熔断 + 评测 |
| sundynix-mcp-go | 3,872 | MCP 工具网关 · 混合检索 · 语义切块 · Agent 工具集 · Word 渲染 |
| sundynix-gateway | 3,121 | Gin 接入层 · DSL · 鉴权 · 护栏 · 可观测 · SSE 断点续传 |
| sundynix-shared | 1,561 | 任务契约 · NATS bus · OTel 链路 · AES 加密 · slog trace |
| desktop frontend | 4,628 | React 19 + React Flow 编排 · 知识库 · 图表 · 更新检查 |
| sundynix-admin | 1,181 | 运维控制台 · 模型 / 数据源 / 计价 / 服务状态 |
| sundynix-mcp-py | 641 | 代码解释器 · Docker 沙箱 · AST 守卫 |

---

## 二、优势分析

### 🟢 1. 架构设计 — 业界顶级水平

- **真正的 5 层解耦**：Client → Gateway → NATS Bus → Dispatcher → MCP Tools，每层可独立替换或水平扩展
- **NATS 零拷贝总线**选型精准：JetStream 持久化 + Queue 负载均衡 + Request-Reply 同步调用
- **Monolith First 策略**：借鉴 Martin Fowler 思想，先跑通闭环，微服务拆分按需渐进
- **Go 全栈高性能**：仅在算法层（OCR / 沙箱）用 Python，避免 GIL 瓶颈
- **OpenTelemetry 全链路追踪**：跨 NATS 传播 W3C traceparent，Jaeger 可视化

### 🟢 2. 编排引擎 — 双轨制 + ReAct 智能体

项目在编排层做了 **Eino 深度集成**（Phase A → B → C → D），达到了极高的完成度：

| 阶段 | 内容 | 状态 |
|------|------|------|
| Phase A | LLM Pool 内部换成 Eino ChatModel | ✅ |
| Phase B | ReAct 智能体 + MCP 工具自主调用 | ✅ |
| Phase C | DSL → compose.Graph 编译器（DAG 并行调度） | ✅ |
| Phase D | 任务生命周期状态机 + 人工审批中断 | ✅ |

- **自研 graph.go + compose.Graph 双轨**：灰度开关切换，compose 编译失败自动降级回自研（安全网）
- **ReAct 智能体**：模型自主决定调哪些 MCP 工具，list_tools 自描述 + 动态发现，新增工具零改动
- **人工审批节点（HITL）**：审批节点暂停 → 批准续跑 / 拒绝中止，状态轮询兜底
- **编排式多智能体接力**：上游 agent 产出沿图传给下游 agent
- **branch 精确选路 + map 有界并发 fan-out + aggregate 汇聚**

### 🟢 3. 安全治理 — 全链路纵深防御

这是整个项目最突出的亮点，**纵深防御四层 + 加密闭环**：

| 治理项 | 实现 | 特色 |
|--------|------|------|
| 输入护栏 | 正则拦截中英文注入 + 超大体限制 | 纯逻辑解耦 + 单测 |
| 输出护栏 | 流式逐片脱敏 sk-/AKIA/JWT/Bearer | 流式 token 不可回收，故逐片处理 |
| 熔断降级 | 真三态 Closed/Open/HalfOpen 状态机 | `-race` 并发安全 + 熔断时不静默丢弃 |
| LLM 评测 | 规则检查 + LLM-as-judge | 异步 off 热路径评分 |
| 代码沙箱 | Docker 隔离 + AST 静态守卫 | 禁网 / 非root / 丢能力 / 只读根 / tmpfs / 限资源 / 超时kill |
| SSRF 防护 | 主机白名单 + 超时 / 限重定向 / 限体 | 覆盖 external_api + web_fetch |
| **API Key 端到端加密** | **AES-256-GCM，磁盘 + NATS 线缆均密文** | SHA-256 派生密钥，`enc:1:` 版本前缀，历史明文平滑迁移 |
| JWT 鉴权 | 注册 / 登录 / 校验 / RequireAuth + Admin 白名单 | 生产密钥 fail-fast |
| SQL 查询安全 | 只读事务 + SELECT/WITH 静态校验 + 行数限制 | 三重防护 |

> 同类开源项目（Dify / FastGPT / Langflow / Flowise）**均不具备**如此完整的安全治理栈。

### 🟢 4. 知识库 — 三路混合检索 + 语义切块

- **Milvus 向量 + Bleve 全文 + Neo4j 图谱 → RRF 融合 → 可选 Rerank**
- **语义切块已升级**：Markdown 标题感知（块带章节面包屑、不跨章节、跳过代码围栏）
  + 递归句界切块 + 块间 overlap（80 rune）+ 碎块合并 + rune 安全（杜绝 UTF-8 切碎）
- 入库可视化：切块 → 向量化 → 三元组抽取 → 实时进度回流
- Obsidian 式文库：`[[双链]]` + 反链 + 力导向关系图

### 🟢 5. Agent 工具集 — 动态化 + 丰富

MCP 工具经 NATS list_tools 自描述，新增工具零改动（无硬编码）：

| 工具 | 类型 | 说明 |
|------|------|------|
| kb_search / kb_ingest / kb_graph | Go | 知识库检索 / 入库 / 图谱查询 |
| memory_get / memory_upsert / memory_list / memory_delete | Go | 长期记忆 CRUD |
| history_get / history_append | Go | 会话历史 |
| report_render / report_store / report_export | Go | 报告生成全链路 |
| external_api | Go | 通用出站 HTTP（SSRF 防护） |
| **web_search** | Go | **联网搜索**（Tavily + DuckDuckGo 兜底） |
| **web_fetch** | Go | **网页抓取 + 正文提取** |
| **calculator** | Go | **安全表达式求值**（调度场算法 → RPN） |
| **current_datetime** | Go | **当前日期时间**（LLM 不知道"现在"） |
| **sql_query** | Go | **只读 SQL 查询**（三重防护） |
| **chart** | Go | **图表工具**（JSON spec → 前端 SVG 渲染） |
| code_interpreter | Python | Docker 隔离执行 |

### 🟢 6. 可观测性 — 生产级

- **OpenTelemetry 全链路追踪**：OTLP → Jaeger，跨 NATS 总线 W3C traceparent 传播
- **slog 日志带 trace_id**：日志与链路双向互跳
- Prometheus `/metrics`（请求数 / 耗时 / 在途，路由模板低基数标签）
- 结构化 JSON 访问日志 + `X-Request-ID`
- `/healthz` + `/readyz` K8s 标准探针
- SSE Token 流可回放 + 断点续传（Redis Stream）
- 前端健康五盏灯 + 节点级实时执行轨迹

### 🟢 7. CI/CD + 发版体系

- **GitHub Actions CI**：Go build + vet + test（4 模块）/ 前端 tsc / mcp-py 沙箱测试
- **GitHub Actions Release**：打 `vX.Y.Z` 标签 → macOS universal + Windows amd64 桌面端安装包 → 自动发布到 GitHub Releases
- **桌面端自动更新检查**：App 启动查 releases/latest，新版弹横幅提示下载
- 完整的 [RELEASE.md](RELEASE.md) 发版清单（版本号对齐 + 验证 + 回滚）
- CI 并发组（同分支新 push 自动取消上次未完成运行，省 CI 时间）

### 🟢 8. 长期记忆 — Generative Agents 级

- P1：异步攒批 Consolidate（每 3 轮 1 次 LLM 对账 → ADD/UPDATE/DELETE/NOOP）+ 软删 + importance/last_seen
- P2：读路径 Score(Recency + Importance) 排序 + 衰减 + 截断 top30
- 桌面端记忆面板：可看 / 改 / 删（软删）
- memory_list / memory_delete 工具 + 端点

### 🟢 9. 工程化 — 开发者体验一流

- `make demo` 无 Docker 一键跑全链路（内嵌 NATS）
- docker-compose 7 服务（NATS / PG / Redis / Milvus + etcd + MinIO / Neo4j），clone 后零配置直跑
- 模型配置经 NATS 控制面热更新，运行时无需重启
- 配置拉取后台重试，根治启动竞态
- DB 连接池上限 + LLM 失败暴露为 failed（生产级并发收尾）
- 空答复不落历史 + 发送前过滤空消息（根治会话毒化）
- 工具服务单实例并发（协程化）+ 任务并发消费
- 前端测试（Vitest + RTL，5 测试文件）

---

## 三、劣势 / 待改进项

### 🔴 1. 前端测试仍薄

- 已有 5 个前端测试文件（UpdateBanner / dsl / run / version / chartspec），比之前的零测试进步很大
- 但 KbView.tsx (~32K) 等核心业务视图仍无测试
- 缺 E2E 测试（Playwright / Cypress）

### 🔴 2. MinerU / PaddleOCR 多模态仍为骨架

- `mineru.py` 仅 435 字节，PDF / 图片多模态解析未真实落地
- 对比 Dify 已支持 Unstructured / Jina Reader 等多种解析器

### 🔴 3. 本地模型支持缺失

- LLM Pool 仅对接 OpenAI 兼容在线 API，架构图设计的 vLLM / Ollama 未实现
- 缺模型路由（按延迟 / 成本 / 能力自动选型）、无多模型 fallback

### 🔴 4. 计量计费未闭环

- 计价配置已完成（按模型 · 分输入/输出单价 + 币种），但计量×单价折算 + 配额未落地

### 🔴 5. 缺多租户 / 团队协作

- 当前按 `owner` 做基础数据隔离，无团队 / 组织概念
- 无 Agent 编排共享、知识库权限分级

### 🔴 6. 前端大文件需拆分

- KbView.tsx ~32K / ~900 行，杂糅入库、文库、检索、图谱等多个子功能

### 🟡 7. 其他小项

| 项 | 状态 |
|----|------|
| PDF 导出 Wails 真机未验证 | 浏览器 OK，桌面端待验 |
| 代码签名（macOS 公证 / Windows） | 未做，RELEASE.md 已标注 |
| K8s Helm Chart | 未做（有 Docker Compose） |
| PROGRESS.md 更新日期 | 仍停在 6-19，部分新功能未勾选 |
| i18n 国际化 | 仅中文 |

---

## 四、与主流开源项目对比

### 对比项目简介

| 项目 | Stars | 技术栈 | 定位 |
|------|-------|--------|------|
| **Dify** | ~60K+ | Python + React | LLM 应用开发平台，workflow + chatbot + agent |
| **FastGPT** | ~20K+ | Node.js (Next.js) | 知识库问答系统，workflow 编排 |
| **Langflow** | ~45K+ | Python (FastAPI) + React | DataStax 支持的可视化 AI 应用构建 |
| **Flowise** | ~35K+ | Node.js + React | 拖拽式 LLM 流程构建器 |
| **AutoGen (AG2)** | ~40K+ | Python | 微软多 Agent 对话框架 |
| **sundynix-agentix** | 个人项目 | Go + React + Python | 分层式 AI Agent 平台 |

### 功能矩阵

| 功能维度 | sundynix | Dify | FastGPT | Langflow | Flowise |
|----------|:--------:|:----:|:-------:|:--------:|:-------:|
| **编排** | | | | | |
| 可视化画布编排 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 图执行引擎 | ✅ 双轨 (自研+compose) | ✅ DAG | ✅ DAG | ✅ DAG | ✅ DAG |
| 分支/条件节点 | ✅ 条件表达式求值 | ✅ | ✅ | ✅ | ✅ |
| 并行 (map/fan-out) | ✅ 有界并发 | ✅ | ❌ | ✅ | ❌ |
| **ReAct 智能体** | **✅ MCP 动态发现** | ✅ | ✅ | ✅ | ❌ |
| 多智能体接力 | **✅** | ❌ | ❌ | ✅ | ❌ |
| 人工审批 (HITL) | **✅** | ✅ | ❌ | ❌ | ❌ |
| 循环/迭代 | ❌ | ✅ | ✅ | ✅ | ❌ |
| **知识库 / RAG** | | | | | |
| 向量检索 | ✅ Milvus | ✅ 多选 | ✅ PgVector | ✅ 多选 | ✅ 多选 |
| 全文检索 | ✅ Bleve | ✅ | ✅ | ❌ | ❌ |
| **知识图谱检索** | **✅ Neo4j GraphRAG** | ❌ | ❌ | ❌ | ❌ |
| 三路 RRF 融合 | **✅** | ❌ (双路) | ❌ (双路) | ❌ | ❌ |
| Rerank | ✅ | ✅ | ✅ | ❌ | ❌ |
| **语义切块 (标题感知)** | **✅ Markdown 章节面包屑** | ✅ 多策略 | ✅ 多策略 | ✅ | ✅ |
| Obsidian 式双链文库 | **✅ 独有** | ❌ | ❌ | ❌ | ❌ |
| 入库可视化进度 | **✅** | ❌ | ❌ | ❌ | ❌ |
| **Agent 工具** | | | | | |
| 联网搜索 | ✅ Tavily + DDG | ✅ SerpAPI | ✅ | ✅ | ✅ |
| 网页抓取 | ✅ | ✅ Jina | ❌ | ✅ | ✅ |
| 计算器 | ✅ 调度场算法 | ✅ | ❌ | ✅ | ❌ |
| SQL 查询 | **✅ 三重防护** | ❌ | ❌ | ✅ | ❌ |
| **图表工具** | **✅ JSON spec + 前端 SVG** | ❌ | ❌ | ❌ | ❌ |
| 代码解释器 | ✅ Docker 沙箱 | ✅ Docker | ❌ | ❌ | ❌ |
| **工具动态发现** | **✅ list_tools 自描述** | ❌ 硬编码 | ❌ | ❌ | ❌ |
| **安全与治理** | | | | | |
| 输入护栏 | ✅ | 🟡 基础 | ❌ | ❌ | ❌ |
| 输出护栏 (流式脱敏) | **✅** | ❌ | ❌ | ❌ | ❌ |
| 熔断降级 | **✅ 三态状态机** | ❌ | ❌ | ❌ | ❌ |
| LLM 自动化评测 | **✅** | ❌ | ❌ | ❌ | ❌ |
| **API Key 加密存储** | **✅ AES-256-GCM** | ❌ 明文/环境变量 | ❌ | ❌ | ❌ |
| 代码沙箱 | ✅ Docker + AST | ✅ Docker | ❌ | ❌ | ❌ |
| SSRF 防护 | ✅ | ✅ | ❌ | ❌ | ❌ |
| SQL 注入防护 | **✅ 只读事务 + 静态校验** | N/A | N/A | N/A | N/A |
| **可观测性** | | | | | |
| **OpenTelemetry 链路追踪** | **✅ Jaeger + 跨 NATS** | ✅ | ❌ | ❌ | ❌ |
| slog + trace_id | **✅** | ❌ | ❌ | ❌ | ❌ |
| Prometheus 指标 | ✅ | ✅ | ❌ | ❌ | ❌ |
| SSE 断点续传 | **✅ Redis Stream** | ❌ | ❌ | ❌ | ❌ |
| 健康探针 | ✅ | ✅ | ❌ | ❌ | ❌ |
| **工程 / 部署** | | | | | |
| 消息总线 | **✅ NATS JetStream** | ❌ 直调 | ❌ 直调 | ❌ 直调 | ❌ 直调 |
| **桌面原生客户端** | **✅ Wails** | ❌ 纯 Web | ❌ 纯 Web | ❌ 纯 Web | ❌ 纯 Web |
| **自动更新检查** | **✅ GitHub Release** | N/A | N/A | N/A | N/A |
| CI/CD | **✅ GitHub Actions** | ✅ | ✅ | ✅ | ✅ |
| **Release 自动构建** | **✅ macOS + Windows** | N/A | N/A | N/A | N/A |
| 无 Docker 验证 | **✅ `make demo`** | ❌ | ❌ | ❌ | ❌ |
| 模型热更新 | **✅ NATS 控制面** | ❌ 需重启 | ❌ | ❌ | ❌ |
| **商业化** | | | | | |
| 计费/配额 | 🟡 计价已有 | ✅ 完整 | ✅ | ❌ | ❌ |
| 多租户/团队 | ❌ | ✅ | ✅ | 🟡 | 🟡 |
| 插件市场 | ❌ | ✅ | ✅ | ✅ | ✅ |

---

### vs Dify（最接近的竞品）

| 维度 | sundynix 优势 | Dify 优势 |
|------|--------------|-----------|
| 架构 | NATS 消息总线解耦 · OTel 全链路追踪 | 单体简单直接 |
| 编排 | 双轨引擎 + ReAct + HITL + 多 Agent 接力 | 更多节点类型 + 循环 |
| 检索 | **三路混合 + 图谱 + 标题感知切块** | 双路 + 更多策略 |
| 安全 | **7 层纵深防御 + AES 加密** | 基础安全 |
| 工具 | **SQL 查询 + 图表 + 动态发现** | 数十家内置工具 |
| 客户端 | **原生桌面端 + 自动更新** | 纯 Web |
| 模型 | 热更新 | **数十家提供商 + 本地模型** |
| 生态 | 个人项目 | **60K+ Stars + 大社区** |
| 商业化 | 计价配置 | **完整计费 + 多租户 + API** |

### vs FastGPT

| 维度 | sundynix 优势 | FastGPT 优势 |
|------|--------------|-------------|
| 检索 | **三路混合 + Neo4j 图谱** | 成熟向量+全文 + 多切块策略 |
| 文库 | **双链 + 力导向图** | 传统文件管理 |
| 编排 | ReAct 智能体 + HITL + 多 Agent | 更多模板 |
| 安全 | 7 层纵深 + AES | 较弱 |
| 桌面 | ✅ Wails | ❌ 纯 Web |
| 可观测 | OTel + Prometheus + slog | 基础 |
| 商业化 | 未完成 | **完整计费 + 分享 + 嵌入** |

### vs Langflow / Flowise

| 维度 | sundynix 优势 | 竞品优势 |
|------|--------------|----------|
| 性能 | Go 后端 · NATS 零拷贝 | — |
| 安全 | 7 层纵深 | 几乎无 |
| 可观测 | OTel + Prometheus | 基础日志 |
| 生态 | 自研节点 | **LangChain/LlamaIndex 数百种组件** |

---

### 独有特色功能（竞品不具备）

以下功能在上述对比项目中**均未见到**或**实现远不完整**：

1. **NATS 零拷贝消息总线 + OTel 跨总线链路传播**
2. **API Key 端到端 AES-256-GCM 加密**（磁盘 + 线缆均密文）
3. **Harness 输出护栏（流式逐 token 脱敏）**
4. **Neo4j 知识图谱检索 + 三路 RRF 融合**
5. **Markdown 标题感知切块**（章节面包屑 + 不跨章节 + 跳过代码围栏）
6. **Obsidian 式双链文库**（`[[双链]]` + 反链 + 力导向图）
7. **原生桌面端 (Wails) + GitHub Release 自动更新**
8. **模型配置 NATS 热更新**（运行时切换无需重启）
9. **MCP 工具动态发现**（list_tools 自描述，新增工具零改动）
10. **SSE Token 流断点续传**（Redis Stream 可回放）
11. **SQL 查询三重防护**（静态校验 + 只读事务 + 行数/超时限制）
12. **图表工具**（工具产出 JSON spec，前端 SVG 渲染，职责分离）
13. **`make demo` 无 Docker 全链路验证**

---

## 五、综合评级

```
    Demo/POC ──── MVP ──── 工程原型 ────── 准生产 ──── ★ 准生产+ ★ ──── 生产
                                                            ▲
                                                            │
                                                       你在这里
```

| 维度 | 评分 | 说明 |
|------|:----:|------|
| 架构设计 | ⭐⭐⭐⭐⭐ | 5 层 + NATS + OTel，在同类项目中属于顶级 |
| 编排引擎 | ⭐⭐⭐⭐⭐ | 双轨 + ReAct + HITL + 多 Agent，完成度极高 |
| 安全治理 | ⭐⭐⭐⭐⭐ | 7 层纵深 + AES 加密，**开源 Agent 平台最强** |
| 知识库 / RAG | ⭐⭐⭐⭐⭐ | 三路检索 + 标题感知切块 + 图谱 + 双链文库 |
| Agent 工具集 | ⭐⭐⭐⭐⭐ | 12 种工具 + 动态发现 + SQL / 图表独有 |
| 可观测性 | ⭐⭐⭐⭐⭐ | OTel + Prometheus + slog trace + 断点续传 |
| 代码质量 | ⭐⭐⭐⭐ | 注释充足、降级完善；KbView 大文件需拆 |
| 测试覆盖 | ⭐⭐⭐⭐ | 32 测试文件 / 2,776 行（含前端）；E2E 待补 |
| CI/CD | ⭐⭐⭐⭐⭐ | CI + Release 自动构建 + 更新检查 |
| 工程化 | ⭐⭐⭐⭐⭐ | Makefile + Docker Compose + 零配置 + 热更新 + 启动竞态修复 |
| 生态 / 社区 | ⭐⭐ | 个人项目 |
| 商业化就绪 | ⭐⭐⭐ | 计价已有，计量 / 配额 / 多租户待做 |

### **综合：4.5 / 5.0**

> 117 次提交、~19,500 行代码、5 层架构 + OTel 全链路追踪 + NATS 总线、
> Eino 四阶段深度集成（ReAct + compose + HITL + 多 Agent）、12 种工具动态发现、
> 7 层安全纵深 + AES 加密、三路混合检索 + 标题感知切块、
> 桌面端 + CI/CD + 自动更新……
>
> **在安全治理、可观测性、编排深度这三个维度上，sundynix-agentix 已经超越了绝大多数
> Star 数万的主流开源项目。** 它的短板是生态和商业化——这需要时间和用户积累。

---

## 六、改进建议优先级

| 优先级 | 项目 | 预估工作量 |
|:------:|------|:---------:|
| P0 | 本地模型支持 (Ollama) | 1-2 天 |
| P0 | PROGRESS.md 更新对齐 main 最新状态 | 半天 |
| P1 | 前端 E2E 测试 (Playwright) | 2-3 天 |
| P1 | KbView.tsx 拆分为子组件 | 1 天 |
| P1 | 文档解析完善 (MinerU / Unstructured) | 2-3 天 |
| P2 | 计量计费落地 | 2 天 |
| P2 | 循环/迭代节点 | 1-2 天 |
| P2 | 代码签名 (macOS 公证 + Windows) | 1-2 天 |
| P3 | 多租户 / 团队协作 | 3-5 天 |
| P3 | 插件体系 | 5+ 天 |
| P3 | K8s Helm Chart | 2 天 |

---

*本文档基于 main 分支源码自动分析生成（2026-06-24）。*