From dfa1e163bfae034983a3d2ee412737658211810d Mon Sep 17 00:00:00 2001
From: Blizzard <blizzardzhang@icloud.com>
Date: Mon, 22 Jun 2026 23:39:21 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E9=A1=B9=E7=9B=AE=E6=80=BB=E4=BD=93?=
 =?UTF-8?q?=E5=88=86=E6=9E=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 project_analysis.md | 346 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 346 insertions(+)
 create mode 100644 project_analysis.md

diff --git a/project_analysis.md b/project_analysis.md
new file mode 100644
index 0000000..c8ccbc0
--- /dev/null
+++ b/project_analysis.md
@@ -0,0 +1,346 @@
+# sundynix-agentix · 项目深度分析
+
+## 一、项目定位
+
+**sundynix-agentix** 是一个**分层式 AI Agent 平台**，采用 **Monolith First → Microservices (Morph B)** 的演进策略。核心价值主张是：用可视化画布编排 AI Agent 工作流，通过 NATS 消息总线解耦各层，支持知识库混合检索（RAG）、长期记忆、报告生成、代码解释器等企业级 AI 能力。
+
+---
+
+## 二、架构概览
+
+采用 **5 层 + 1 条 NATS 零拷贝消息总线** 的分层架构：
+
+```mermaid
+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](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-dispatcher/internal/eino/graph.go)：按 DSL 的真实拓扑执行（非线性拍平），支持拓扑排序 → 逐节点激活 → 分支剪枝
+- 黑板模式（`board`）在节点间传递状态：画像/历史/检索结果/工具产出/成稿
+- 无图/空图时退化为「无图单轮对话」
+
+### 5.3 ReAct 自主 Agent
+
+- [react_agent.go](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-dispatcher/internal/eino/react_agent.go)：模型在 ReAct 循环中自主决定调哪些 MCP 工具
+- 适配了 Eino 的 `react.NewAgent`，自定义 `streamHasToolCall` 解决 DeepSeek 先吐文本再给 tool call 的兼容问题
+- 最大 8 步限制控成本
+- 模型不支持函数调用时优雅降级回普通对话
+
+### 5.4 RAG 混合检索
+
+- [rag.go](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-mcp-go/internal/rag/rag.go)：三路混合检索
+  - **向量路**：Embedding → Milvus ANN 检索
+  - **全文路**：Bleve 全文索引
+  - **图谱路**：Neo4j 知识图谱三元组匹配
+- **RRF 融合**（Reciprocal Rank Fusion）合并三路结果
+- 可选 **Rerank** 精排
+- 入库流水线：切块 → 分批向量化 → Milvus + Bleve + LLM 实体抽取 → Neo4j
+
+### 5.5 长期记忆（Generative Agents 式）
+
+- [store.go](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-mcp-go/internal/memory/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](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-dispatcher/internal/eino/report.go)：专用多步编排
+  1. LLM 规划 3-5 章大纲
+  2. 各章有界并发（max 4）：RAG 检索参考资料 → LLM 撰写
+  3. 流式呈现 Markdown 进度
+  4. 存源 → 按需导出 Word/PDF/Markdown
+- 每次 LLM 调用套 60s 超时防挂死
+
+### 5.7 安全体系（纵深防御）
+
+| 层级 | 机制 |
+|---|---|
+| 输入护栏 | 拦截提示词注入 + 超大体（[guardrail](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-gateway/internal/guardrail)） |
+| 输出护栏 | 逐片脱敏 sk-/AKIA/JWT/Bearer 疑似密钥（[output.go](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-dispatcher/internal/harness/output.go)） |
+| 代码沙箱 | AST 静态守卫 → Docker 隔离执行（禁网/非root/限资源/一次性）（[sandbox.py](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-mcp-py/src/sundynix_mcp_py/sandbox.py)） |
+| 鉴权 | JWT 注册/登录/校验 + RequireAuth + RequireAdmin 白名单 |
+| 熔断 | 三态状态机 Closed/Open/HalfOpen（[circuitbreaker.go](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-dispatcher/internal/harness/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()](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-mcp-go/internal/rag/rag.go#L256-L270) 当前仅按行切、超 2000 字符强截——**生产环境这是 RAG 质量的瓶颈**。
+
+```go
+// 当前：朴素切块
+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` + 返回空值的降级模式，虽然保证了可用性，但 **调试定位困难**：
+
+```go
+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 自动化**。