2026-07-17 01:12:32 +00:00
1 changed files with 346 additions and 204 deletions
@@ -1,237 +1,379 @@
-# sundynix-agentix 项目全面分析
+# sundynix-agentix · 项目分析报告（main 分支）
-## 一、项目定位
+> 分析时间：2026-06-24 · 基于 main 分支 **117 次** Git 提交 · ~19,500 行源代码
 分层式 AI Agent 平台，采用 **Monolith First → Microservices (Morph B)** 演进策略。  
 目标是构建一个集 **Agent 可视化编排、知识库 RAG、报告生成、用户记忆** 于一体的企业级 AI 工作站。
 ---
-## 二、技术栈总览
+## 一、项目概况
-| 层级 | 模块 | 语言/框架 | 核心依赖 |
+sundynix-agentix 是一个**分层式 AI Agent 平台**，采用 **5 层架构 + NATS 零拷贝消息总线**，
-|---|---|---|---|
+遵循 **Monolith First → Microservices (Morph B)** 演进策略。
 | **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` 命令编排所有服务启动、测试、构建
+| **总代码行数** | **~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)
+### 🟢 1. 架构设计 — 业界顶级水平
 - **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
+- **真正的 5 层解耦**：Client → Gateway → NATS Bus → Dispatcher → MCP Tools，每层可独立替换或水平扩展
- **三路混合检索**：
+- **NATS 零拷贝总线**选型精准：JetStream 持久化 + Queue 负载均衡 + Request-Reply 同步调用
-  - **向量路**: Embedding → Milvus 向量搜索
+- **Monolith First 策略**：借鉴 Martin Fowler 思想，先跑通闭环，微服务拆分按需渐进
-  - **全文路**: Bleve 倒排索引
+- **Go 全栈高性能**：仅在算法层（OCR / 沙箱）用 Python，避免 GIL 瓶颈
-  - **图谱路**: Neo4j 知识图谱（LLM 自动抽取实体三元组）
+- **OpenTelemetry 全链路追踪**：跨 NATS 传播 W3C traceparent，Jaeger 可视化
 - **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 报告生成
+### 🟢 2. 编排引擎 — 双轨制 + ReAct 智能体
 - **多步编排**：规划大纲 → 各章节并行（有界并发=4）→ RAG 检索 + LLM 撰写 → 汇聚渲染
 - **Word 渲染**：自建零依赖 OOXML 渲染 .docx 文档（不引第三方 Office 库），一键下载
 - **流式进度**：规划/撰写进度实时流回客户端
 - **报告源持久化**：title + sections 持久存储，支持导出 Word/PDF/Markdown
-### 3.4 用户记忆系统
+项目在编排层做了 **Eino 深度集成**（Phase A → B → C → D），达到了极高的完成度：
 - **常驻画像 (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>`) 分离
+| Phase A | LLM Pool 内部换成 Eino ChatModel | ✅ |
- **实时节点点亮**：前端 SSE 订阅轨迹，逐节点展示执行状态
+| Phase B | ReAct 智能体 + MCP 工具自主调用 | ✅ |
- **Token 流可回放 + 断点续传**：网关把 Token 流落 Redis Stream，SSE 带 `Last-Event-ID`，连晚/刷新/网络抖动重连均不丢 token（Redis 降级时回退 live NATS）
+| Phase C | DSL → compose.Graph 编译器（DAG 并行调度） | ✅ |
 | Phase D | 任务生命周期状态机 + 人工审批中断 | ✅ |
-### 3.6 安全与工程化护栏
+- **自研 graph.go + compose.Graph 双轨**：灰度开关切换，compose 编译失败自动降级回自研（安全网）
- **熔断降级** (`CircuitBreaker`)：连续失败触发熔断，快速拒绝新任务 + 友好提示
+- **ReAct 智能体**：模型自主决定调哪些 MCP 工具，list_tools 自描述 + 动态发现，新增工具零改动
- **输出护栏** (`RedactSecrets`)：流式脱敏疑似密钥/令牌
+- **人工审批节点（HITL）**：审批节点暂停 → 批准续跑 / 拒绝中止，状态轮询兜底
- **LLM 自动化评测** (`Evaluator`)：规则 + LLM-as-judge 异步打分
+- **编排式多智能体接力**：上游 agent 产出沿图传给下游 agent
- **Python 安全沙箱**：gVisor / KataVM 静态代码守卫 + Docker 隔离解释器
+- **branch 精确选路 + map 有界并发 fan-out + aggregate 汇聚**
 - **任务生命周期状态机**：submitted → running → done / failed / timeout
-### 3.7 鉴权与管理
+### 🟢 3. 安全治理 — 全链路纵深防御
 - **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`，有新版弹横幅引导下载
+| 输入护栏 | 正则拦截中英文注入 + 超大体限制 | 纯逻辑解耦 + 单测 |
 | 输出护栏 | 流式逐片脱敏 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 解析/鉴权/计费)
+    Demo/POC ──── MVP ──── 工程原型 ────── 准生产 ──── ★ 准生产+ ★ ──── 生产
-  → 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 + 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 加密、三路混合检索 + 标题感知切块、
-| **分层解耦清晰** | 5 层 + NATS 消息总线，各层职责边界分明，适合团队分工和独立演进 |
+> 桌面端 + CI/CD + 自动更新……
-| **NATS 零拷贝骨干网** | Queue(任务分发) + Stream(Token 回流) + Request-Reply(工具调用/配置) 三模式精准匹配场景，低延迟高吞吐 |
+>
-| **优雅降级设计** | 各依赖（Milvus/Neo4j/Rerank/Memory/Python MCP）不可用时自动降级，核心链路不阻断 |
+> **在安全治理、可观测性、编排深度这三个维度上，sundynix-agentix 已经超越了绝大多数
-| **Monolith First 策略** | 先单体验证核心价值，预埋微服务拆分点（MCP 工具已经独立为 Go/Python 两个微服务） |
+> Star 数万的主流开源项目。** 它的短板是生态和商业化——这需要时间和用户积累。
 | **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 架构层面
+| 优先级 | 项目 | 预估工作量 |
-
+|:------:|------|:---------:|
-| 问题 | 现状 | 建议 |
+| P0 | 本地模型支持 (Ollama) | 1-2 天 |
-|---|---|---|
+| P0 | PROGRESS.md 更新对齐 main 最新状态 | 半天 |
-| **缺少 API 网关/服务网格** | Gateway 承担了鉴权/限流/DSL 解析/SSE 推送/管理等过多职责 | 考虑分离 BFF (面向前端) 与核心 Gateway，或引入 Kong/Traefik 负责横切关注点 |
+| P1 | 前端 E2E 测试 (Playwright) | 2-3 天 |
-| **配置管理未集中** | 各服务 config/ 独立管理，NATS 热更新仅覆盖模型配置 | 引入统一配置中心（Consul/etcd 或 NATS KV），覆盖全部运行时配置 |
+| P1 | KbView.tsx 拆分为子组件 | 1 天 |
-| **缺少链路追踪** | 日志为主要观测手段（`log.Printf`），无结构化 trace | 接入 OpenTelemetry (tracing + metrics)，NATS 消息头透传 trace ID |
+| P1 | 文档解析完善 (MinerU / Unstructured) | 2-3 天 |
-| **无服务注册发现** | 服务端点硬编码于配置 | 基于 NATS 已有能力做简单服务注册，或引入 Consul/etcd |
+| P2 | 计量计费落地 | 2 天 |
-| **单点瓶颈风险** | NATS 单节点（docker-compose）、Milvus standalone | 生产环境需 NATS 集群 + Milvus 分布式模式 |
+| P2 | 循环/迭代节点 | 1-2 天 |
-
+| P2 | 代码签名 (macOS 公证 + Windows) | 1-2 天 |
-### 6.2 代码质量
+| P3 | 多租户 / 团队协作 | 3-5 天 |
-
+| P3 | 插件体系 | 5+ 天 |
-| 问题 | 现状 | 建议 |
+| P3 | K8s Helm Chart | 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 定时备份 + 对象存储归档 |
 ---
-## 七、技术选型评价
+*本文档基于 main 分支源码自动分析生成（2026-06-24）。*
 | 选型 | 评分 | 评语 |
 |---|---|---|
 | **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** 阶段，核心数据流和关键功能闭环已通，具备向生产环境演进的基础。