sundynix-agentix/project_analysis.md

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 阶段，核心数据流和关键功能闭环已通，具备向生产环境演进的基础。