sundynix/sundynix-agentix
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
36aa298410d5ba0b872d8864b0d8cf7a5c2f2635
sundynix-agentix/project_analysis.md
T
Blizzard 36aa298410 docs: 项目分析6.24
2026-06-24 21:32:48 +08:00

19 KiB
Raw Blame History

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 发版清单（版本号对齐 + 验证 + 回滚）
  • 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）。

Reference in New Issue View Git Blame Copy Permalink