docs: 项目分析与生产演进蓝图

project_analysis.md

@@ -1,346 +1,235 @@
-# sundynix-agentix · 项目深度分析
+# sundynix-agentix 项目全面分析
 
 ## 一、项目定位
 
-**sundynix-agentix** 是一个**分层式 AI Agent 平台**，采用 **Monolith First → Microservices (Morph B)** 的演进策略。核心价值主张是：用可视化画布编排 AI Agent 工作流，通过 NATS 消息总线解耦各层，支持知识库混合检索（RAG）、长期记忆、报告生成、代码解释器等企业级 AI 能力。
+分层式 AI Agent 平台，采用 **Monolith First → Microservices (Morph B)** 演进策略。  
+目标是构建一个集 **Agent 可视化编排、知识库 RAG、报告生成、用户记忆** 于一体的企业级 AI 工作站。
 
 ---
 
-## 二、架构概览
+## 二、技术栈总览
 
-采用 **5 层 + 1 条 NATS 零拷贝消息总线** 的分层架构：
+| 层级 | 模块 | 语言/框架 | 核心依赖 |
+|---|---|---|---|
+| **1. 客户端** | `sundynix-desktop` | Wails + React 19 + TypeScript | @xyflow/react (React Flow), shadcn/ui, 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, UniOffice (.docx), 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 |
 
-```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
+### 构建工具链
+- **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 渲染**：UniOffice 渲染 .docx 文档，一键下载
+- **流式进度**：规划/撰写进度实时流回客户端
+- **报告源持久化**：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 订阅轨迹，逐节点展示执行状态
+
+### 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 全局命令面板（键盘优先工作站）
+
+---
+
+## 四、核心数据流
+
+```
+客户端 → 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 架构层面
+
+| 问题 | 现状 | 建议 |
 |---|---|---|
-| **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` | 独立运维控制台（模型/数据源配置、服务状态、计价管理） |
+| **缺少 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 代码质量
 
-## 三、技术栈全景
-
-### 后端（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+** |
+| **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 前端
 
-## 五、已实现功能详析
-
-### 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` 零配置跑通全链路，热更新模型，文档详尽 |
+| **状态管理原始** | 纯 `useState` + props drilling，无全局状态管理 | 随功能增长，考虑引入 Zustand 或 Jotai 管理全局状态（当前/会话/运行态） |
+| **路由为自研视图切换** | `view` state + 条件渲染，无 URL 路由 | 引入 React Router，支持 URL 直达、浏览器前进后退 |
+| **类型安全不完整** | 部分 API 响应缺 TypeScript 类型定义 | 考虑 API 契约生成（OpenAPI → TypeScript types），前后端类型一致 |
+| **KbView.tsx 过大** | 单文件 31944 字节 | 拆分为子组件（搜索面板 / 文档列表 / 图谱面板 / 入库面板） |
+| **无单元测试** | 前端零测试覆盖 | 引入 Vitest + React Testing Library，优先覆盖核心交互 |
 
-> [!TIP]
-> **综合评价**：这是一个架构功力深厚、功能覆盖广泛的 AI Agent 平台原型。其分层设计、消息总线解耦、全链路降级哲学和 Generative Agents 式记忆机制都体现了高水平的工程设计。当前阶段最值得投入的改进方向是：**前端测试覆盖**、**RAG 切块质量**、**CI/CD 自动化**。
+### 6.4 安全
+
+| 问题 | 现状 | 建议 |
+|---|---|---|
+| **API Key 明文传输/存储** | ModelConfig 中 `api_key` 明文存 PG、经 NATS 广播 | API Key 加密存储（AES-256），NATS 传输走 TLS |
+| **CORS 配置** | 未见显式 CORS 配置 | 生产环境需严格限制允许源 |
+| **Rate Limiting** | Redis 存 session/rate limit 但实现程度不明 | 确保关键 API（登录/任务提交）有完善的速率限制 |
+| **依赖安全审计** | 无 dependabot / 漏洞扫描 | 启用 GitHub Dependabot + `go vet` / `govulncheck` CI |
+
+### 6.5 运维与部署
+
+| 问题 | 现状 | 建议 |
+|---|---|---|
+| **无 CI/CD 流水线** | `.github/` 目录存在但未见完整 workflow | 配置 GitHub Actions：lint → test → build → deploy |
+| **无 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 合理；但 MCP/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 OCR、安全沙箱）仍为桩
+4. 缺少 CI/CD、链路追踪、集中配置等生产级工程化基础设施
+
+**项目成熟度**：处于 **高完成度 MVP** 阶段，核心数据流和关键功能闭环已通，具备向生产环境演进的基础。