sundynix/sundynix-agentix

Fork 0

Files

T

Blizzard dfa1e163bf docs: 项目总体分析

2026-06-22 23:39:21 +08:00

16 KiB

Raw Blame History

sundynix-agentix · 项目深度分析

一、项目定位

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

二、架构概览

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

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：按 DSL 的真实拓扑执行（非线性拍平），支持拓扑排序 → 逐节点激活 → 分支剪枝
黑板模式（board）在节点间传递状态：画像/历史/检索结果/工具产出/成稿
无图/空图时退化为「无图单轮对话」

5.3 ReAct 自主 Agent

react_agent.go：模型在 ReAct 循环中自主决定调哪些 MCP 工具
适配了 Eino 的 react.NewAgent，自定义 streamHasToolCall 解决 DeepSeek 先吐文本再给 tool call 的兼容问题
最大 8 步限制控成本
模型不支持函数调用时优雅降级回普通对话

5.4 RAG 混合检索

rag.go：三路混合检索
- 向量路：Embedding → Milvus ANN 检索
- 全文路：Bleve 全文索引
- 图谱路：Neo4j 知识图谱三元组匹配
RRF 融合（Reciprocal Rank Fusion）合并三路结果
可选 Rerank 精排
入库流水线：切块 → 分批向量化 → Milvus + Bleve + LLM 实体抽取 → Neo4j

5.5 长期记忆（Generative Agents 式）

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：专用多步编排
1. LLM 规划 3-5 章大纲
2. 各章有界并发（max 4）：RAG 检索参考资料 → LLM 撰写
3. 流式呈现 Markdown 进度
4. 存源 → 按需导出 Word/PDF/Markdown
每次 LLM 调用套 60s 超时防挂死

5.7 安全体系（纵深防御）

层级	机制
输入护栏	拦截提示词注入 + 超大体（guardrail）
输出护栏	逐片脱敏 sk-/AKIA/JWT/Bearer 疑似密钥（output.go）
代码沙箱	AST 静态守卫 → Docker 隔离执行（禁网/非root/限资源/一次性）（sandbox.py）
鉴权	JWT 注册/登录/校验 + RequireAuth + RequireAdmin 白名单
熔断	三态状态机 Closed/Open/HalfOpen（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() 当前仅按行切、超 2000 字符强截——生产环境这是 RAG 质量的瓶颈。

// 当前：朴素切块
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 + 返回空值的降级模式，虽然保证了可用性，但 调试定位困难：

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 自动化。

16 KiB Raw Blame History Unescape Escape