feat: admin端UI

2026-06-27 12:06:29 +08:00
parent d2662a1f37
commit 2d9695e940
9 changed files with 2117 additions and 85 deletions
@@ -0,0 +1,320 @@
+# 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 编排平台**。核心突破集中在三个方面：
+
+1. **Harness 治理栈完整落地**：输入护栏(两级) → 输出脱敏(跨分片) → 自动评测 → 低分纠偏 → 熔断 → 预算控制，形成完整的「恒温器」闭环
+2. **可观测性达到业界标杆**：全链路 Trace + 执行轨迹 + Redis 回放 + 历史复盘 + 健康灯，任何一次运行都可以"时光倒流"复盘
+3. **部署与 HA 就绪**：Docker Compose 一键部署 12 个服务、优雅停机、多副本安全、密钥加密
+
+项目最大的技术亮点是**将 AI 治理（安全/质量/成本）作为一等公民嵌入架构**，而非事后附加——这在开源 Agent 框架中相当稀缺。
+
+> **一句话评价**：架构成熟度已达准生产级，补齐测试覆盖、API 文档和 CI/CD 后即可上线。