From 36aa298410d5ba0b872d8864b0d8cf7a5c2f2635 Mon Sep 17 00:00:00 2001 From: Blizzard Date: Wed, 24 Jun 2026 21:32:48 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=A1=B9=E7=9B=AE=E5=88=86=E6=9E=906.2?= =?UTF-8?q?4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- project_analysis.md | 550 ++++++++++++++++++++++++++++---------------- 1 file changed, 346 insertions(+), 204 deletions(-) diff --git a/project_analysis.md b/project_analysis.md index 5da50ec..8d61345 100644 --- a/project_analysis.md +++ b/project_analysis.md @@ -1,237 +1,379 @@ -# sundynix-agentix 项目全面分析 +# sundynix-agentix · 项目分析报告（main 分支） -## 一、项目定位 - -分层式 AI Agent 平台，采用 **Monolith First → Microservices (Morph B)** 演进策略。 -目标是构建一个集 **Agent 可视化编排、知识库 RAG、报告生成、用户记忆** 于一体的企业级 AI 工作站。 +> 分析时间：2026-06-24 · 基于 main 分支 **117 次** Git 提交 · ~19,500 行源代码 --- -## 二、技术栈总览 +## 一、项目概况 -| 层级 | 模块 | 语言/框架 | 核心依赖 | -|---|---|---|---| -| **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 | +sundynix-agentix 是一个**分层式 AI Agent 平台**，采用 **5 层架构 + NATS 零拷贝消息总线**， +遵循 **Monolith First → Microservices (Morph B)** 演进策略。 -### 构建工具链 -- **Go 工作区**: `go.work` 管理 4 个后端模块（gateway/dispatcher/mcp-go/shared） -- **前端**: Vite 5 + TypeScript 5 + PostCSS + TailwindCSS -- **桌面端**: Wails v2（Go 后端 + WebView 前端，`GOWORK=off` 独立构建） -- **Makefile**: 统一的 `make` 命令编排所有服务启动、测试、构建 +### 代码规模 + +| 维度 | 数据 | +|------|------| +| **总代码行数** | **~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 守卫 | --- -## 三、已实现功能 +## 二、优势分析 -### 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 编排 +### 🟢 1. 架构设计 — 业界顶级水平 -### 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 渲染三元组图谱 +- **真正的 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 可视化 -### 3.3 报告生成 -- **多步编排**：规划大纲 → 各章节并行（有界并发=4）→ RAG 检索 + LLM 撰写 → 汇聚渲染 -- **Word 渲染**：自建零依赖 OOXML 渲染 .docx 文档（不引第三方 Office 库），一键下载 -- **流式进度**：规划/撰写进度实时流回客户端 -- **报告源持久化**：title + sections 持久存储，支持导出 Word/PDF/Markdown +### 🟢 2. 编排引擎 — 双轨制 + ReAct 智能体 -### 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 将近期对话与已有画像对账归纳 +项目在编排层做了 **Eino 深度集成**（Phase A → B → C → D），达到了极高的完成度： -### 3.5 执行可视化 (运行·观测) -- **ExecEvent 轨迹**：每个节点的生命周期事件（start/end/error/info）+ 耗时 -- **双流并行**：Token 流 (`sundynix.streams.`) + 执行事件流 (`sundynix.exec.`) 分离 -- **实时节点点亮**：前端 SSE 订阅轨迹，逐节点展示执行状态 -- **Token 流可回放 + 断点续传**：网关把 Token 流落 Redis Stream，SSE 带 `Last-Event-ID`，连晚/刷新/网络抖动重连均不丢 token（Redis 降级时回退 live NATS） +| 阶段 | 内容 | 状态 | +|------|------|------| +| Phase A | LLM Pool 内部换成 Eino ChatModel | ✅ | +| Phase B | ReAct 智能体 + MCP 工具自主调用 | ✅ | +| Phase C | DSL → compose.Graph 编译器（DAG 并行调度） | ✅ | +| Phase D | 任务生命周期状态机 + 人工审批中断 | ✅ | -### 3.6 安全与工程化护栏 -- **熔断降级** (`CircuitBreaker`)：连续失败触发熔断，快速拒绝新任务 + 友好提示 -- **输出护栏** (`RedactSecrets`)：流式脱敏疑似密钥/令牌 -- **LLM 自动化评测** (`Evaluator`)：规则 + LLM-as-judge 异步打分 -- **Python 安全沙箱**：gVisor / KataVM 静态代码守卫 + Docker 隔离解释器 -- **任务生命周期状态机**：submitted → running → done / failed / timeout +- **自研 graph.go + compose.Graph 双轨**：灰度开关切换，compose 编译失败自动降级回自研（安全网） +- **ReAct 智能体**：模型自主决定调哪些 MCP 工具，list_tools 自描述 + 动态发现，新增工具零改动 +- **人工审批节点（HITL）**：审批节点暂停 → 批准续跑 / 拒绝中止，状态轮询兜底 +- **编排式多智能体接力**：上游 agent 产出沿图传给下游 agent +- **branch 精确选路 + map 有界并发 fan-out + aggregate 汇聚** -### 3.7 鉴权与管理 -- **JWT 鉴权**：登录/注册 + bcrypt 密码 + Token 校验 -- **运维控制台 (admin)**：模型/数据源登记激活、服务健康监控、用户计费 -- **NATS 热更新**：模型配置变更经 NATS 广播到各消费方（dispatcher/mcp-go） +### 🟢 3. 安全治理 — 全链路纵深防御 -### 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`，有新版弹横幅引导下载 +这是整个项目最突出的亮点，**纵深防御四层 + 加密闭环**： + +| 治理项 | 实现 | 特色 | +|--------|------|------| +| 输入护栏 | 正则拦截中英文注入 + 超大体限制 | 纯逻辑解耦 + 单测 | +| 输出护栏 | 流式逐片脱敏 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 全链路验证** + +--- + +## 五、综合评级 ``` -客户端 → POST /api/v1/tasks → Gateway (DSL 解析/鉴权/计费) - → NATS JetStream (sundynix.tasks.) - → Dispatcher (Eino 图编排, 记忆/历史召回) - → NATS request-reply → MCP Tools (Go I/O + Python 算法) - → Token Stream (sundynix.streams.) 零拷贝回流 - → Gateway SSE → 客户端逐 token 渲染 + 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** -### 架构设计 -| 优势 | 说明 | -|---|---| -| **分层解耦清晰** | 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 实时生效 | +> 117 次提交、~19,500 行代码、5 层架构 + OTel 全链路追踪 + NATS 总线、 +> Eino 四阶段深度集成（ReAct + compose + HITL + 多 Agent）、12 种工具动态发现、 +> 7 层安全纵深 + AES 加密、三路混合检索 + 标题感知切块、 +> 桌面端 + CI/CD + 自动更新…… +> +> **在安全治理、可观测性、编排深度这三个维度上，sundynix-agentix 已经超越了绝大多数 +> Star 数万的主流开源项目。** 它的短板是生态和商业化——这需要时间和用户积累。 --- -## 六、不足与改进建议 ⚠️ +## 六、改进建议优先级 -### 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 定时备份 + 对象存储归档 | +| 优先级 | 项目 | 预估工作量 | +|:------:|------|:---------:| +| 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 天 | --- -## 七、技术选型评价 - -| 选型 | 评分 | 评语 | -|---|---|---| -| **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** 阶段，核心数据流和关键功能闭环已通，具备向生产环境演进的基础。 +*本文档基于 main 分支源码自动分析生成（2026-06-24）。*