Files

T

2026-06-27 12:06:29 +08:00

20 KiB

Raw Blame History

sundynix-agentix 项目分析报告（2026-06-27）

分析时间：2026 年 6 月 27 日（dev 分支，commit 148+）

一句话定位：一个面向企业的 AI Agent 编排平台，支持可视化 DSL 构建 Agent 工作流、多模型热切换、RAG 知识库、长期记忆、自动评测闭环、人工审批（HITL）、桌面端原生应用 + Web 运维控制台，一键 Docker 部署。

一、整体架构（五层微服务）

┌─────────────────────────────────────────────────────────────────────┐
│  第 1 层 · 客户端                                                    │
│  ┌───────────────────────┐  ┌───────────────────────┐              │
│  │ sundynix-desktop      │  │ sundynix-admin         │              │
│  │ (Wails + React + TS)  │  │ (Vite + React + TS)    │              │
│  │ 桌面原生应用             │  │ Web 运维控制台           │              │
│  └──────────┬────────────┘  └──────────┬─────────────┘              │
│             │ HTTP/SSE                  │ HTTP                       │
│  ═══════════╪══════════════════════════╪═════════════════════════   │
│  第 2 层 · API 网关                                                   │
│  ┌──────────▼──────────────────────────▼─────────────┐              │
│  │ sundynix-gateway  (Go · Gin)                       │              │
│  │ DSL 解析 / JWT 鉴权 / 护栏(Tier1) / SSE 流 /       │              │
│  │ 状态机 / 评测落库 / 配置控制面 / MinIO              │              │
│  │ Postgres + Redis + MinIO                           │              │
│  └──────────┬────────────────────────────────────────┘              │
│             │ NATS JetStream + core pub/sub                         │
│  ═══════════╪══════════════════════════════════════════════════     │
│  第 3 层 · 调度与编排                                                  │
│  ┌──────────▼──────────────────────────────────────┐                │
│  │ sundynix-dispatcher  (Go · Eino)                  │                │
│  │ DSL 图引擎 / ReAct Agent / 流式推理 / 记忆对账 /   │                │
│  │ 报告多步编排 / 自动评测+纠偏 / 熔断 / 预算护栏      │                │
│  └────────┬───────────────────────────┬──────────────┘              │
│           │ NATS request-reply         │                             │
│  ═════════╪═══════════════════════════╪═════════════════════       │
│  第 4 层 · 共享契约与总线                                               │
│  ┌────────▼───────────────────────────▼────────────┐                │
│  │ sundynix-shared (Go)                              │                │
│  │ contract / bus(NATS) / otelx / secrets            │                │
│  └──────────────────────────────────────────────────┘               │
│  ═══════════════════════════════════════════════════════════       │
│  第 5 层 · MCP 工具微服务                                               │
│  ┌──────────────────────────────┐  ┌──────────────────────┐        │
│  │ sundynix-mcp-go  (Go)        │  │ sundynix-mcp-py (Py) │        │
│  │ RAG(Milvus+Bleve+Neo4j) /    │  │ 文档解析(Word/PDF) / │        │
│  │ 记忆(PG) / 历史(Redis) /      │  │ 代码沙箱(Docker)     │        │
│  │ 报告渲染(docx) / 搜索 /       │  │ 算法型 MCP 工具       │        │
│  │ 知识库管理 / 图谱 / 外部工具   │  │                      │        │
│  └──────────────────────────────┘  └──────────────────────┘        │
└─────────────────────────────────────────────────────────────────────┘

二、技术栈全景

后端（Go 1.25）

领域	技术选型	用途
HTTP 框架	Gin 1.12	网关 REST API + SSE
Agent 编排	CloudWeGo Eino	ReAct Agent、compose.Graph、流式推理
消息总线	NATS JetStream	任务分发、Token 回流、工具调用、配置广播、审批
关系库	PostgreSQL 16 + GORM	用户、任务、评测、画像、知识库元数据
缓存/流	Redis 7 + go-redis	Session、Token 日预算、Redis Stream 回放
向量库	Milvus 2.4	RAG 向量检索
全文索引	Bleve v2	RAG 全文路 + RRF 融合
图数据库	Neo4j 5	知识图谱三元组（GraphRAG）
对象存储	MinIO	文件/文档/报告附件
链路追踪	OpenTelemetry + Jaeger	全链路 trace（NATS 传播）
指标监控	Prometheus client_golang	HTTP/任务/模型指标
认证鉴权	JWT (golang-jwt/v5) + bcrypt	用户注册/登录/token
密钥管理	AES-256-GCM (自建 secrets 包)	API Key 落库/过线加密
ID 生成	雪花算法 (bwmarrin/snowflake)	全局唯一 ID
桌面端	Wails v2	Go + WebView 原生桌面应用

前端

领域	技术选型	用途
框架	React 19 + TypeScript	桌面端 & 管理端
构建	Vite 5	前端构建
样式	TailwindCSS 3	UI 样式
路由	react-router-dom 7	SPA 路由
图编辑	@xyflow/react 12 (React Flow)	DSL 可视化编排画布
图谱可视化	react-force-graph-2d	知识图谱力导向图
图标	lucide-react	UI 图标
测试	Vitest + Testing Library	前端单测

Python（mcp-py）

领域	技术选型	用途
运行时	Python 3.11+	算法型工具
消息总线	nats-py	接入 NATS 骨干网
文档解析	python-docx / openpyxl / pypdf	Word/Excel/PDF 解析
代码沙箱	docker SDK	Docker 隔离执行环境

基础设施

组件	镜像	用途
NATS	nats:2-alpine	消息骨干网 (JetStream 持久化)
PostgreSQL	postgres:16-alpine	关系存储
Redis	redis:7-alpine	缓存 / Stream / 预算
Milvus	milvusdb/milvus:v2.4.13	向量数据库
etcd	quay.io/coreos/etcd:v3.5.14	Milvus 元数据
MinIO	minio/minio	对象存储
Neo4j	neo4j:5-community	图数据库
Jaeger	jaegertracing/all-in-one:1.60	链路追踪 UI

三、已实现功能清单

🧠 核心 AI 能力

功能	实现程度	关键文件
DSL 图编排引擎	✅ 完整	`dispatcher/internal/eino/graph.go` — 11 种节点 (input/memory/retriever/tool/agent/aggregate/render/branch/approval/map/output)，拓扑排序执行
ReAct Agent（自主工具调用）	✅ 完整	`dispatcher/internal/eino/react_agent.go` — Eino ReAct 循环，自动发现 MCP 工具目录，inject 参数绑定
流式推理	✅ 完整	`orchestrator.go` — ChatStream / StreamText 双模，reasoning 思考过程入轨迹
多模型热切换	✅ 完整	控制面 NATS 广播 → Dispatcher/mcp-go 热更新，支持 OpenAI 兼容 / vLLM / Ollama
报告多步编排	✅ 完整	`report.go` — 规划大纲 → 并行(RAG+撰写) → 汇聚 → 渲染 Word/PDF/Markdown
RAG 混合检索	✅ 完整	`mcp-go/internal/rag/` — Milvus向量 + Bleve全文 + Neo4j图谱 → RRF融合 → 可选 Rerank
知识图谱（GraphRAG）	✅ 完整	LLM 抽三元组 → Neo4j 存储 → 检索时图谱路参与 RRF 融合
长期记忆（Generative Agents 式）	✅ 完整	`memory/store.go` — Recency×Importance 加权排序，Consolidate 对账，Top-N 截断
短期多轮历史	✅ 完整	Redis 存会话历史，自动召回注入上下文
记忆对账（Mem0 式 Consolidate）	✅ 完整	`memory_extract.go` — 每 N 轮 LLM 对账 ADD/UPDATE/DELETE/NOOP
多 Agent 协作	✅ 完整	黑板模式：agentOut 接力，前序 agent 产出注入下游

🛡️ 安全与治理（Harness）

功能	实现程度	关键文件
输入护栏 Tier1	✅ 完整	`gateway/internal/guardrail/` — 归一化(去零宽/同形字/base64)→高精度注入正则→敏感词黑名单
输入护栏 Tier2	✅ 完整	`dispatcher/internal/harness/jailbreak.go` — LLM 越狱分类器，灰区裁决
输出脱敏	✅ 完整	`harness/output.go` — 跨分片 StreamRedactor (密钥/JWT/PII 手机号/邮箱/身份证)，防碎片泄漏
自动化评测	✅ 完整	`harness/eval.go` — 规则检查 + LLM-as-judge + RAG 忠实度评测（幻觉检测）
低分自动纠偏	✅ 完整	`orchestrator.go#refine` — 评语驱动重生成，取更优者（恒温器闭环）
熔断器	✅ 完整	`harness/circuitbreaker.go` — 连续失败触发熔断，快速拒绝新任务
Token 预算	✅ 完整	单任务硬上限(TASK_TOKEN_BUDGET) + 单用户日预算(USER_DAILY_TOKEN_BUDGET)
JWT 鉴权	✅ 完整	`gateway/internal/auth/` — 注册/登录/中间件
密钥加密	✅ 完整	`shared/secrets/` — AES-256-GCM 落库/过线，生产环境强制设密钥

🔍 可观测性

功能	实现程度	关键文件
全链路 Trace	✅ 完整	OTel → Jaeger，NATS 消息头传播 trace_id
执行可视化轨迹	✅ 完整	ExecEvent 回流 — 节点点亮/工具入参产出/耗时/分阶段
Redis 回放	✅ 完整	Token 流 + 执行轨迹 Redis Stream 录制 → SSE 断点续传
运行历史复盘	✅ 完整	PG 持久化(output+trace)，过 Redis TTL 仍可读库复盘
服务健康灯	✅ 完整	聚合 6 依赖(gateway/nats/db/redis/milvus/neo4j)实时状态
Prometheus 指标	✅ 基础	`/metrics` 端点可用

📱 客户端

功能	实现程度	说明
桌面原生应用	✅ 完整	Wails v2 — Go 后端 + React/TS 前端
可视化 DSL 画布	✅ 完整	React Flow 拖拽编排 Agent 图
实时仪表盘	✅ 完整	任务/评测/知识库/Token/服务状态聚合展示
运行·观测页	✅ 完整	三栏布局：历史列表 / 轨迹面板 / Markdown 输出
知识库管理	✅ 完整	入库进度实时回流、图谱可视化
偏好记忆面板	✅ 完整	查看/编辑/删除个人偏好
人工审批（HITL）	✅ 完整	审批节点暂停 → UI 弹批准/拒绝 → 决定回传
运维控制台	✅ 完整	模型配置(chat/embedding) / 服务状态 / 计费
Markdown 渲染	✅ 完整	表格/代码围栏/图表/流式渲染

🚀 部署与运维

功能	实现程度	说明
Docker 容器化	✅ 完整	5 个服务各自 Dockerfile
一键 Docker Compose 部署	✅ 完整	`docker-compose.prod.yml` — 应用+基建一把拉起，安全配置
优雅停机	✅ 完整	SIGTERM → drain 排空在途任务/工具 → 超时兜底
HA 多副本安全	✅ 完整	事件订阅队列组(QueueGateway)，杜绝重复落库/计费
Go Workspace	✅ 完整	`go.work` 管理 4 个 Go 模块
Makefile	✅ 完整	一键启停、测试、构建

四、代码规模

指标	数据
Go 源码	~15,600 行
Go 测试	~3,400 行
TypeScript/TSX	~6,300 行
Python	~640 行
总代码	~26,000 行
Git 提交	148 次
Go 模块	4 个 (shared/gateway/dispatcher/mcp-go)
微服务	6 个 (gateway/dispatcher/mcp-go/mcp-py/admin/desktop)
基础设施组件	7 个 (NATS/PG/Redis/Milvus/etcd/MinIO/Neo4j)
Docker 服务	12 个 (5 应用 + 7 基建)

五、项目成熟度评级

⭐ 综合评定：准生产级（Pre-Production / Late-Beta）

对标业界分级：

维度	评分 (1-5)	说明
架构设计	⭐⭐⭐⭐⭐	五层解耦、NATS 骨干网、契约驱动、降级容错、热更新 —— 架构非常成熟
功能完整度	⭐⭐⭐⭐☆	AI Agent 编排的核心闭环完整，HITL/评测/纠偏/护栏/记忆均已落地
代码质量	⭐⭐⭐⭐☆	注释详实（中文），错误处理层次分明，降级模式完备，接口抽象合理
测试覆盖	⭐⭐⭐☆☆	关键路径有 e2e/集成/单测（3400行），但覆盖率还有提升空间
可观测性	⭐⭐⭐⭐⭐	全链路 trace + 执行轨迹 + Redis 回放 + 健康灯 + 评测落库 —— 业界标杆级
安全治理	⭐⭐⭐⭐☆	多层护栏 + 密钥加密 + JWT + 输出脱敏 + 预算控制 —— 极其完善
部署运维	⭐⭐⭐⭐☆	一键 compose + 优雅停机 + HA + Makefile，缺 k8s/Helm 和 CI/CD
文档	⭐⭐⭐⭐☆	多份分析/架构/部署/进度文档，缺 API 文档(Swagger)和用户手册

六、优势亮点 🌟

1. 架构设计精良

五层解耦：Gateway/Dispatcher/MCP 职责清晰，NATS 骨干网松耦合
全面降级：每个依赖不可用都有 graceful degradation（Milvus 挂→不检索、Redis 挂→不缓存、Neo4j 挂→不图谱，从不阻断主流程）
热更新：模型配置经 NATS 广播实时生效，无需重启
契约驱动：sundynix-shared/contract 统一定义所有跨服务数据结构与通信约定

2. AI 编排能力深度

DSL 图引擎 支持 11 种节点类型，拓扑排序 + branch 条件剪枝 + map 并行 fan-out
ReAct Agent 与 MCP 工具目录自发现联动：新增工具只需在 MCP 注册，无需改编排代码
Mem0 式记忆对账：不是简单 kv 覆盖，而是 LLM 对账 ADD/UPDATE/DELETE + Importance 打分 + Recency 衰减
自动评测闭环：规则检查 → LLM-as-judge → 忠实度(幻觉检测) → 低分自动纠偏 → 评测结果落库

3. 安全治理（Harness）体系完整

输入护栏：Tier1(归一化反绕过 + 正则 + 黑名单) → Tier2(LLM 越狱裁决)，两级过滤成本最优
输出护栏：跨分片流式脱敏(StreamRedactor)，解决了流式场景密钥碎片泄漏的工程难题
成本护栏：单任务 token 硬上限 + 单用户日预算 + 熔断器，三重保护防成本失控

4. 可观测性一流

全链路 Trace：Gateway → NATS → Dispatcher → MCP，trace_id 跨消息总线传播
执行轨迹（ExecEvent）：每个节点、每次工具调用都有结构化事件，前端可实时点亮/回放
Redis Stream 录制：Token 流 + 轨迹事件录进 Redis → SSE 断点续传，根治"连晚/重连丢数据"

5. 工程实践规范

注释全中文，设计意图/降级策略/约束原因写得极其清楚
错误处理一致：降级 vs 上抛 vs 快速拒绝各有明确策略
接口抽象（TokenSink/ToolCaller/StatusSink/LLM）便于测试注入
雪花 ID + GORM 软删 + BaseModel 统一规约

七、不足与改进方向 ⚠️

1. 测试覆盖需扩展

现状：关键路径有测试（e2e/集成/单测 3400 行），但占源码比 ~22%
缺失：前端组件测试、Gateway handler 单测、MCP 工具完整覆盖
建议：引入覆盖率工具（go tool cover），目标核心包 ≥ 70%

2. API 文档缺失

现状：无 Swagger/OpenAPI 文档，API 契约只能看代码
建议：集成 swag（Gin 生态），自动生成 API 文档

3. CI/CD 流水线未建

现状：.github/ 目录存在但未见完整 CI 配置
建议：GitHub Actions — lint → test → build → push image → deploy staging

4. 前端状态管理偏原始

现状：桌面端直接 fetch + useState，无全局状态管理
建议：引入 zustand 或 jotai，统一 WebSocket/SSE 状态

5. 知识库功能缺分片与多租户隔离

现状：知识库按 owner/kb 名称隔离，但 Milvus Collection 粒度较粗
建议：生产环境引入 Partition Key 或多 Collection 策略

6. Python 微服务较薄

现状：mcp-py 约 640 行，文档解析和代码沙箱为桩/初步实现
建议：完善 MinerU OCR 接入、MCP 协议标准化

7. 缺乏 k8s/Helm 部署方案

现状：仅 Docker Compose 编排
建议：为生产环境提供 Helm Chart，支持 HPA、PDB、健康检查

8. 缺少限流与 Rate Limiting

现状：成本护栏有 token 预算，但 HTTP 层无速率限制
建议：Gin 中间件加速率限制（令牌桶/滑动窗口），配合 Redis

9. 日志结构化不完整

现状：混用 log.Printf 与 slog
建议：统一 slog + JSON 输出，便于 ELK/Loki 采集

10. 前端无 i18n

现状：UI 文案硬编码中文
建议：如需国际化，引入 i18next

八、与同类产品对标

对标产品	sundynix-agentix 对比
Dify	架构更工程化(微服务 vs 单体)，护栏/评测/纠偏闭环更完整，但 UI 完成度不如 Dify
Coze	类似的 Agent 编排理念，sundynix 是完全开源自建可控，支持私有化部署
LangGraph	sundynix 的 DSL 图引擎类似 LangGraph 的状态机，但额外内置 HITL/熔断/预算/评测
Mem0	sundynix 的记忆系统借鉴 Mem0 的 consolidate 模式，且与编排引擎深度集成

九、总结

经过 3 天的密集改造，项目已经从一个基础的 Agent 框架跃升到准生产级的 AI Agent 编排平台。核心突破集中在三个方面：

Harness 治理栈完整落地：输入护栏(两级) → 输出脱敏(跨分片) → 自动评测 → 低分纠偏 → 熔断 → 预算控制，形成完整的「恒温器」闭环
可观测性达到业界标杆：全链路 Trace + 执行轨迹 + Redis 回放 + 历史复盘 + 健康灯，任何一次运行都可以"时光倒流"复盘
部署与 HA 就绪：Docker Compose 一键部署 12 个服务、优雅停机、多副本安全、密钥加密

项目最大的技术亮点是将 AI 治理（安全/质量/成本）作为一等公民嵌入架构，而非事后附加——这在开源 Agent 框架中相当稀缺。

一句话评价：架构成熟度已达准生产级，补齐测试覆盖、API 文档和 CI/CD 后即可上线。

20 KiB Raw Blame History Unescape Escape

sundynix-agentix 项目分析报告（2026-06-27）

一、整体架构（五层微服务）

二、技术栈全景

后端（Go 1.25）

前端

Python（mcp-py）

基础设施

三、已实现功能清单

🧠 核心 AI 能力

🛡️ 安全与治理（Harness）

🔍 可观测性

📱 客户端

🚀 部署与运维

四、代码规模

五、项目成熟度评级

⭐ 综合评定：准生产级（Pre-Production / Late-Beta）

六、优势亮点 🌟

1. 架构设计精良

2. AI 编排能力深度

3. 安全治理（Harness）体系完整

4. 可观测性一流

5. 工程实践规范

七、不足与改进方向 ⚠️

1. 测试覆盖需扩展

2. API 文档缺失

3. CI/CD 流水线未建

4. 前端状态管理偏原始

5. 知识库功能缺分片与多租户隔离

6. Python 微服务较薄

7. 缺乏 k8s/Helm 部署方案

8. 缺少限流与 Rate Limiting

9. 日志结构化不完整

10. 前端无 i18n

八、与同类产品对标

九、总结

20 KiB

Raw Blame History