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

2026-06-23 20:52:41 +08:00
parent fc1494b634
commit 9f2a059ce2
2 changed files with 881 additions and 328 deletions
@@ -0,0 +1,664 @@
 # sundynix-agentix · 工业生产级演进蓝图
 > 基于对当前代码库的深度审计（6 个服务模块 + 共享层 + 基础设施），从 8 个维度系统梳理"从高完成度 MVP 到工业生产级"还需引入的能力。
 ---
 ## 当前基线评估
 在分析差距之前，先盘点**已有的生产级基因**（这些是优势，不需要从零开始）：
 | ✅ 已有能力 | 现状 |
 |---|---|
 | Prometheus 指标 | Gateway 已埋 `sundynix_http_requests_total` / `duration` / `in_flight` 三个核心指标 ([observability.go](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-gateway/internal/middleware/observability.go)) |
 | 结构化访问日志 | Gateway 已用 `slog.JSONHandler` 输出包含 request_id/method/route/status/latency 的 JSON 日志 |
 | Request ID 透传 | `X-Request-ID` 生成 + 上下文注入已实现 |
 | 熔断降级 | Dispatcher 有完整的三态熔断器（Closed → Open → HalfOpen）([circuitbreaker.go](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-dispatcher/internal/harness/circuitbreaker.go)) |
 | 输入护栏 | 正则检测提示词注入 + 超大请求体拦截 ([guardrail.go](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-gateway/internal/guardrail/guardrail.go)) |
 | 输出护栏 | 流式脱敏疑似密钥/令牌 ([output.go](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-dispatcher/internal/harness/output.go)) |
 | LLM 自动评测 | 规则 + LLM-as-judge 双路评分 ([eval.go](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-dispatcher/internal/harness/eval.go)) |
 | CI/CD 基础 | GitHub Actions CI（Go build+vet+test / 前端 tsc / Python sandbox test）+ Release（Wails 跨平台构建）|
 | 限流 | Redis 会话级 IP 限流 120/min ([middleware/guardrail.go](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-gateway/internal/middleware/guardrail.go#L39-L51)) |
 | 安全沙箱 | Python Code Interpreter 有 Docker 隔离（禁网/non-root/丢 cap/限内存 CPU PID/只读根/tmpfs）+ AST 静态守卫 |
 | 管理员权限 | RequireAdmin 中间件 + 生产模式强制显式配置 `ADMIN_USER_IDS` |
 ---
 ## 一、可观测性 (Observability)
 > **目标**：任何线上问题在 5 分钟内能定位到根因节点。
 ### 1.1 分布式链路追踪 (Tracing) — ⚠️ 缺失
 **现状**：仅有 `X-Request-ID` 透传和 `log.Printf` 散落日志，无法追踪一次请求跨 Gateway → NATS → Dispatcher → MCP 工具的完整调用链。
 **需引入**：
 ```
 ┌─────────────────────────────────────────────────────────────────┐
 │                    OpenTelemetry Tracing                        │
 │                                                                 │
 │  Gateway        NATS 消息头       Dispatcher       MCP Tools    │
 │  ┌────────┐    ┌──────────┐     ┌────────────┐   ┌──────────┐  │
 │  │ Span A │───▶│ W3C Ctx  │────▶│  Span B    │──▶│ Span C   │  │
 │  │(HTTP)  │    │(Header)  │     │(图编排)    │   │(工具调用)│  │
 │  └────────┘    └──────────┘     └────────────┘   └──────────┘  │
 │                                                                 │
 │  → 导出到 Jaeger / Tempo                                       │
 └─────────────────────────────────────────────────────────────────┘
 ```
 | 组件 | 方案 | 说明 |
 |---|---|---|
 | **SDK** | `go.opentelemetry.io/otel` | Go 标准 OTel SDK |
 | **Gin 自动埋点** | `otelgin` 中间件 | 替代/补充现有 Observe()，每个 HTTP 请求自动创建 span |
 | **NATS 跨进程透传** | 在 NATS 消息 Header 中注入 `traceparent` (W3C TraceContext) | bus.PublishTask / ConsumeTasks 双端抽 inject/extract |
 | **Eino 图节点埋点** | 每个节点 (agent/retriever/tool/branch) 创建 child span | 与现有 ExecEvent 对齐，自动关联 |
 | **后端** | Jaeger (开发) / Grafana Tempo (生产) | Tempo 对接 Grafana 可视化 |
 **关键收益**：一条 trace 覆盖 HTTP 入口 → DSL 解析 → NATS 发布 → Dispatcher 消费 → 记忆召回 → 图节点 1→2→3 → 工具调用 → Token 回流 → SSE 推送，任何环节慢/错一眼可见。
 ### 1.2 指标体系完善 (Metrics) — ⚠️ 部分
 **现状**：Gateway 有 3 个 HTTP 指标，Dispatcher/MCP 无指标。
 **需补充**：
 | 新增指标 | 归属 | 说明 |
 |---|---|---|
 | `sundynix_tasks_total{status}` | Dispatcher | 任务处理计数（submitted/done/failed/timeout）|
 | `sundynix_task_duration_seconds` | Dispatcher | 任务端到端耗时直方图 |
 | `sundynix_llm_requests_total{model,status}` | Dispatcher | LLM 调用计数 |
 | `sundynix_llm_tokens_total{model,direction}` | Dispatcher | Token 用量（input/output）— **计费核心** |
 | `sundynix_llm_latency_seconds{model}` | Dispatcher | LLM 响应延迟 (TTFT / 总耗时) |
 | `sundynix_tool_calls_total{tool,status}` | MCP-Go/Py | 工具调用计数 |
 | `sundynix_rag_search_duration_seconds{path}` | MCP-Go | 检索延迟（向量/全文/图谱/融合）|
 | `sundynix_circuitbreaker_state` | Dispatcher | 熔断器当前状态 (gauge) |
 | `sundynix_nats_msgs_total{subject}` | Shared | NATS 消息流量 |
 **推荐栈**：Prometheus + Grafana (已有 prometheus client)，补 Grafana 仪表盘。
 ### 1.3 日志标准化 — ⚠️ 部分
 **现状**：Gateway 用 `slog` ✅，但 Dispatcher / MCP-Go / MCP-Py 仍用 `log.Printf` / `fmt.Printf`。
 **需引入**：
 | 变更 | 说明 |
 |---|---|
 | 全局切换到 `log/slog` (Go 1.21+) | 统一 JSON 格式，所有日志携带 `request_id` / `task_id` / `service` 字段 |
 | 日志级别控制 | 生产 INFO，调试 DEBUG，按环境变量切换 |
 | 关联 trace_id | 日志注入 `trace_id` + `span_id`，Grafana Loki 可跳到对应 trace |
 | Python 端 structlog | MCP-Py 引入 structlog，输出 JSON 格式，对齐 Go 端 |
 | 日志采集 | Grafana Loki / ELK (Fluentd → Elasticsearch → Kibana) |
 ### 1.4 全栈观测仪表盘
 ```
 Grafana Dashboard 体系：
 ├── Overview:    服务健康 / 请求量 / 错误率 / P99 延迟
 ├── LLM:         Token 用量 / 模型延迟 / 成功率 / 成本估算
 ├── RAG:         入库速率 / 检索延迟 / 命中率 / 图谱规模
 ├── Tasks:       任务状态分布 / 排队深度 / 处理耗时
 ├── NATS:        消息吞吐 / 消费者延迟 / 积压深度
 └── Alerts:      错误率>5% / P99>3s / 熔断打开 / 任务超时率>10%
 ```
 ---
 ## 二、安全加固 (Security Hardening)
 ### 2.1 密钥管理 — 🔴 高优先
 **现状**：
 - `ModelConfig.APIKey` 明文存 PostgreSQL、经 NATS 明文广播到各消费方
 - JWT 签名密钥硬编码或环境变量
 - 配置文件中明文 DSN（含密码）
 **需引入**：
 | 方案 | 说明 | 推荐 |
 |---|---|---|
 | **Vault / SOPS** | API Key 加密存储，运行时经 Vault API 获取 | HashiCorp Vault（生产首选）或 Mozilla SOPS（轻量） |
 | **K8s Secrets + CSI** | 集群内密钥挂载 | Secrets Store CSI Driver + Vault Provider |
 | **NATS TLS** | NATS 客户端↔服务端全链路 TLS，消息传输加密 | 配置 nats-server TLS + 客户端证书 |
 | **PG SSL** | 数据库连接启用 `sslmode=require` | 当前 DSN 为 `sslmode=disable` |
 | **环境变量注入** | 敏感配置一律不入代码/配置文件 | `.env.production` + Docker secrets |
 ### 2.2 认证与授权深化 — ⚠️ 部分
 **现状**：JWT 鉴权 ✅ + RequireAdmin 白名单 ✅，但：
 - 无 Token 刷新机制（过期即登出）
 - 无 RBAC 角色体系
 - SSE/EventSource 无法带 Authorization 头（当前按 task_id 寻址，无鉴权）
 **需引入**：
 | 能力 | 方案 |
 |---|---|
 | **Refresh Token** | JWT access_token (15min) + refresh_token (7d)，静默续期 |
 | **RBAC** | 角色模型：`admin / operator / user / viewer`，PG 存角色表 |
 | **SSE 鉴权** | 连接时带 `?token=xxx` query param → 验证后升级为 SSE（或 WebSocket 时握手带 token）|
 | **OAuth2 / SSO** | 企业客户需要 OIDC（接 KeyCloak / Auth0 / Azure AD）|
 | **API Key 鉴权** | 对外开放 API 时，支持 `X-API-Key` 鉴权（与 JWT 并行）|
 ### 2.3 网络安全 — ⚠️ 缺失
 | 能力 | 当前 | 需引入 |
 |---|---|---|
 | **CORS** | 未见显式配置 | Gin CORS 中间件，生产严格限制 Origin |
 | **HTTPS** | 无 TLS 终端 | 前置 Nginx/Caddy/Traefik 做 TLS 终端 + HTTP→HTTPS 重定向 |
 | **mTLS** | 无 | NATS 集群间 + 服务间 mTLS（零信任网络）|
 | **WAF** | 无 | 前置 Cloudflare / ModSecurity 或 Nginx WAF 规则 |
 | **网络隔离** | docker-compose 共享网络 | K8s NetworkPolicy：前端→Gateway→NATS→后端 严格分网段 |
 ### 2.4 审计日志 — 🔴 缺失
 **需引入**：
 ```go
 // 关键操作审计（写 PG sundynix_audit_log）：
 // - 用户登录/登出
 // - 模型配置变更
 // - 知识库创建/删除/入库
 // - 任务提交/执行
 // - 管理员操作（改角色/改限额）
 type AuditLog struct {
    ID        string    `gorm:"primaryKey;size:24"`
    UserID    string    // 操作者
    Action    string    // login / config_update / kb_ingest / task_submit / ...
    Resource  string    // 操作对象
    Detail    string    // JSON 详情
    IP        string
    CreatedAt time.Time
 }
 ```
 ---
 ## 三、高可用与容灾 (HA & Disaster Recovery)
 ### 3.1 NATS 集群 — 🔴 必须
 **现状**：单节点 NATS（docker-compose），是**全局单点故障**。
 **需引入**：
 ```yaml
 # NATS 3 节点集群 + JetStream Raft
 nats-1:
  image: nats:2-alpine
  command: ["-c", "/etc/nats/cluster.conf", "--name", "nats-1"]
 nats-2:
  image: nats:2-alpine
  command: ["-c", "/etc/nats/cluster.conf", "--name", "nats-2"]
 nats-3:
  image: nats:2-alpine
  command: ["-c", "/etc/nats/cluster.conf", "--name", "nats-3"]
 ```
 - JetStream 自带 Raft 共识，3 节点即可容忍 1 节点故障
 - 客户端连接串改为 `nats://nats-1:4222,nats-2:4222,nats-3:4222`
 - `bus.ConnectWithRetry` 已支持重连 ✅
 ### 3.2 数据库高可用
 | 组件 | 当前 | 生产方案 |
 |---|---|---|
 | **PostgreSQL** | 单节点 | Patroni + etcd 主从自动切换；或云 RDS (高可用版) |
 | **Redis** | 单节点 | Redis Sentinel (3 节点) 或 Redis Cluster |
 | **Milvus** | Standalone | Milvus Cluster 模式（需独立 Pulsar/Kafka + 多 QueryNode）|
 | **Neo4j** | 单节点 Community | Neo4j Enterprise Causal Cluster（3 Core + Read Replicas）|
 | **MinIO** | 随 Milvus | 独立 MinIO Distributed (4+ 节点 erasure coding) |
 ### 3.3 服务多副本与负载均衡
 | 服务 | 扩容方式 | 注意事项 |
 |---|---|---|
 | **Gateway** | N 副本 + Nginx/Traefik 负载均衡 | SSE 连接需要 sticky session 或用 NATS 做中转 |
 | **Dispatcher** | N 副本 | NATS 队列组（`ConsumerDurable`）已天然支持负载均衡 ✅ |
 | **MCP-Go** | N 副本 | NATS `QueueSubscribe` 队列组已天然支持 ✅ |
 | **MCP-Py** | N 副本 | 同上 ✅ |
 > 项目架构上 Dispatcher/MCP 已经是无状态 + NATS 队列组，天然支持水平扩展，这是很大的优势。
 ### 3.4 Kubernetes 部署 — 🔴 必须
 **现状**：仅 docker-compose（开发环境）。
 **需引入**：
 ```
 deploy/k8s/
 ├── charts/
 │   └── sundynix/
 │       ├── Chart.yaml
 │       ├── values.yaml           # 统一配置（副本数/资源限制/密钥引用）
 │       ├── values.prod.yaml      # 生产覆盖
 │       └── templates/
 │           ├── gateway-deploy.yaml
 │           ├── gateway-svc.yaml
 │           ├── dispatcher-deploy.yaml
 │           ├── mcp-go-deploy.yaml
 │           ├── mcp-py-deploy.yaml
 │           ├── ingress.yaml
 │           ├── hpa.yaml          # 水平自动扩缩
 │           ├── pdb.yaml          # Pod 中断预算
 │           └── networkpolicy.yaml
 ├── kustomize/                    # 或 Kustomize base + overlays
 └── Dockerfile.*                  # 各服务容器镜像
 ```
 **必须包含**：
 | K8s 资源 | 说明 |
 |---|---|
 | **Deployment** | 每个服务 ≥2 副本，滚动更新 |
 | **HPA** | Gateway 按 CPU/请求量自动扩缩；Dispatcher 按 NATS 消费者延迟 |
 | **PDB** | `minAvailable: 1`，升级时不中断 |
 | **Resource Limits** | 每个 Pod 明确 requests/limits（CPU/内存）|
 | **Liveness / Readiness** | Gateway: HTTP /health; Dispatcher: NATS ping; MCP: NATS health |
 | **NetworkPolicy** | 前端 → Gateway (8080)；Gateway → NATS (4222) / PG / Redis; NATS → Dispatcher / MCP |
 | **Ingress** | Nginx Ingress / Traefik + TLS 证书（cert-manager + Let's Encrypt）|
 | **ConfigMap / Secret** | 配置与密钥分离，Secret 经 Vault CSI 注入 |
 ### 3.5 备份与恢复
 | 数据 | 策略 | RPO / RTO |
 |---|---|---|
 | **PostgreSQL** | pg_dump 每日全量 + WAL 归档增量 → S3/MinIO | RPO < 1h, RTO < 30min |
 | **Milvus** | Milvus backup 工具 → S3 | RPO < 24h |
 | **Neo4j** | neo4j-admin dump → S3 | RPO < 24h |
 | **NATS JetStream** | 3 副本 Raft 自带持久化 | 天然容灾 |
 | **配置** | Git 版本管理 + Vault 快照 | 即时恢复 |
 ---
 ## 四、CI/CD 与发布工程 (Release Engineering)
 ### 4.1 当前 CI 评估
 **已有**：
 - [ci.yml](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/.github/workflows/ci.yml)：Go build+vet+test / 前端 tsc / Python sandbox test ✅
 - [release.yml](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/.github/workflows/release.yml)：Wails 跨平台构建 + GitHub Release ✅
 **缺失**：
 ### 4.2 需补充的 CI 流水线
 ```yaml
 # 完整 CI 流水线：
 jobs:
  lint:           # ← 新增
    - golangci-lint run    # 代码质量门
    - eslint + prettier    # 前端 lint
    - ruff check           # Python lint
  security:       # ← 新增
    - govulncheck ./...    # Go 依赖漏洞扫描
    - npm audit            # 前端依赖漏洞
    - trivy image scan     # 容器镜像漏洞扫描
    - gitleaks detect      # 代码中泄露的密钥检测
  test:           # 增强
    - go test -race -coverprofile  # 竞态检测 + 覆盖率
    - vitest run           # 前端单元测试（需先引入）
    - pytest --cov         # Python 覆盖率
  build:          # ← 新增：后端容器镜像
    - docker build -t sundynix-gateway:$SHA
    - docker build -t sundynix-dispatcher:$SHA
    - docker build -t sundynix-mcp-go:$SHA
    - docker build -t sundynix-mcp-py:$SHA
    - push to container registry
  e2e:            # ← 新增：端到端
    - docker-compose up → make e2e → 全链路验证
  deploy-staging: # ← 新增
    - helm upgrade --install -n staging
    - 冒烟测试
  deploy-prod:    # ← 新增
    - 人工审批 gate
    - helm upgrade --install -n production
    - 金丝雀验证
 ```
 ### 4.3 容器化 — 🔴 必须
 需为每个服务创建 Dockerfile：
 ```dockerfile
 # 示例：sundynix-gateway
 FROM golang:1.25-alpine AS builder
 WORKDIR /src
 COPY go.work go.work.sum ./
 COPY sundynix-shared/ sundynix-shared/
 COPY sundynix-gateway/ sundynix-gateway/
 RUN cd sundynix-gateway && CGO_ENABLED=0 go build -o /app ./cmd/server
 FROM gcr.io/distroless/static-debian12
 COPY --from=builder /app /app
 EXPOSE 8080
 ENTRYPOINT ["/app"]
 ```
 - 多阶段构建，最终镜像用 distroless（最小攻击面）
 - 镜像推到 GitHub Container Registry (ghcr.io) 或私有 Harbor
 ### 4.4 发布策略
 | 策略 | 说明 |
 |---|---|
 | **语义化版本** | `vMAJOR.MINOR.PATCH`，MAJOR 含 breaking change |
 | **金丝雀发布** | 新版先切 10% 流量，观测 30min 无异常再全量 |
 | **蓝绿部署** | 数据库 schema 变更时用蓝绿（需 schema 向后兼容）|
 | **Feature Flags** | 引入 unleash / flagsmith，功能灰度发布 |
 | **回滚机制** | `helm rollback` + NATS JetStream 消费者 replay |
 ---
 ## 五、数据治理与合规 (Data Governance)
 ### 5.1 多租户 — ⚠️ 待实现
 **现状**：知识库按 `user_id/kb_name` 做 owner 作用域，但无正式租户模型。
 **需引入**：
 | 层次 | 方案 |
 |---|---|
 | **数据隔离** | 租户 ID → PG Schema / 行级策略 (RLS)；Milvus 按租户 partition；Neo4j 按租户 label |
 | **资源配额** | 每租户 LLM Token 配额 / 存储配额 / 并发任务上限 |
 | **计费** | 按 Token 用量 / 存储用量 / API 调用量 阶梯计费 |
 ### 5.2 数据生命周期
 | 能力 | 说明 |
 |---|---|
 | **数据保留策略** | 会话历史 90 天过期；审计日志 1 年；JetStream 7 天滚动 |
 | **个人数据删除** | GDPR / 个保法 合规：用户注销 → 级联清除 PG + Milvus + Neo4j + Redis 所有个人数据 |
 | **数据脱敏** | 生产日志中 PII 字段（用户输入/模型输出）自动脱敏 |
 | **数据分类分级** | API Key = L4 机密；用户输入 = L3 敏感；模型输出 = L2 内部 |
 ### 5.3 合规
 | 要求 | 措施 |
 |---|---|
 | **等保 2.0 三级** | 审计日志 + 访问控制 + 加密存储 + 入侵检测 |
 | **GDPR** | 个人数据删除权 + 数据可携权 + 处理记录 |
 | **AI 生成标识** | 输出标注"AI 生成"水印或元信息 |
 | **内容审查** | 模型输出过滤（敏感内容/政治/暴力/色情）— 需接第三方审查 API 或部署自有模型 |
 ---
 ## 六、AI 特有的生产治理
 ### 6.1 Token 计量与成本控制 — 🔴 必须
 **现状**：LLM Pool 无 Token 计数。
 **需引入**：
 ```go
 // Token 计量中间件（包装 Pool.ChatStream / Chat）：
 type TokenMeter struct {
    pool    *Pool
    counter prometheus.Counter    // sundynix_llm_tokens_total
    store   TokenUsageStore       // 写 PG sundynix_token_usage
 }
 // 每次 LLM 调用记录：
 type TokenUsage struct {
    TaskID       string
    UserID       string
    Model        string
    InputTokens  int
    OutputTokens int
    LatencyMS    int64
    Cost         float64   // 按 model pricing 计算
    CreatedAt    time.Time
 }
 ```
 - 大部分 OpenAI 兼容 API 在响应中返回 `usage.prompt_tokens` / `usage.completion_tokens`
 - Eino `ChatModel.Generate` 的响应 `ChatModelOutput` 包含 `TokenUsage`
 ### 6.2 模型路由与 Fallback — ⚠️ 缺失
 **现状**：单一模型配置，无 fallback。
 **需引入**：
 ```
 模型路由策略：
 ├── 主模型: deepseek-chat (成本低/速度快)
 ├── Fallback 1: gpt-4o-mini (主模型超时/500 时切)
 ├── Fallback 2: 本地 Ollama (外网不可用时切)
 └── 规则路由:
    ├── 报告生成 → 强模型 (需要长输出+结构化)
    ├── 普通对话 → 快模型 (低延迟优先)
    └── 知识抽取 → 便宜模型 (批量场景控成本)
 ```
 ### 6.3 Prompt 版本管理 — ⚠️ 缺失
 **现状**：Prompt 硬编码在 Go 代码中。
 **需引入**：
 | 方案 | 说明 |
 |---|---|
 | **Prompt 模板表** | PG 存 prompt 模板，支持版本控制 + A/B 测试 |
 | **变量插值引擎** | `{{.profile}}` / `{{.history}}` / `{{.refs}}` 模板变量 |
 | **A/B 测试** | 同一任务按百分比路由到不同 prompt 版本，对比评分 |
 | **Prompt 审计** | 记录每次推理的完整 prompt（脱敏后），便于复盘优化 |
 ### 6.4 模型输出缓存 — ⚠️ 缺失
 | 层次 | 方案 |
 |---|---|
 | **Semantic Cache** | 相似 query 的 RAG 检索结果缓存（Redis / Milvus 相似度匹配）|
 | **Exact Cache** | 完全相同的 prompt 直接返回缓存结果（省 LLM 调用） |
 | **KB 搜索缓存** | 高频 query 的检索结果缓存（TTL 5min）|
 ### 6.5 安全 AI 特有治理
 | 能力 | 说明 |
 |---|---|
 | **Prompt 注入防御增强** | 当前正则检测 ✅；建议补 LLM-based 注入检测（二段判决：先用小模型判定是否为注入）|
 | **幻觉检测** | RAG 场景：比对模型输出与检索到的参考资料，标注无出处的断言 |
 | **输出内容审查** | 接第三方内容审核 API 或部署开源模型（如 Llama Guard）做输出过滤 |
 | **PII 检测** | 输入/输出流经 PII 检测器（身份证号/手机号/银行卡号），日志自动脱敏 |
 ---
 ## 七、前端工程化
 ### 7.1 状态管理 — ⚠️ 改进
 **现状**：纯 `useState` + props drilling，无全局状态。
 ```typescript
 // 推荐引入 Zustand（轻量 + React 生态友好）：
 import { create } from 'zustand';
 interface AppStore {
  user: AuthUser | null;
  identity: Identity;
  currentRun: RunState;
  // actions
  setUser: (u: AuthUser | null) => void;
  submitTask: (dsl: TaskDsl) => Promise<void>;
 }
 ```
 ### 7.2 路由 — ⚠️ 缺失
 **现状**：`view` state + 条件渲染，无 URL 路由。
 ```typescript
 // 引入 React Router v7（Admin 端已用）：
 // → 支持 URL 直达、浏览器前进后退、深链接分享
 <Route path="/" element={<Home />} />
 <Route path="/studio" element={<StudioView />} />
 <Route path="/kb" element={<KbView />} />
 <Route path="/report" element={<ReportView />} />
 <Route path="/runs/:taskId?" element={<RunsView />} />
 ```
 ### 7.3 测试 — 🔴 缺失
 | 层次 | 工具 | 覆盖 |
 |---|---|---|
 | **单元测试** | Vitest + React Testing Library | 核心组件（StudioView / KbView / 状态逻辑）|
 | **E2E 测试** | Playwright | 关键用户流（登录 → 编排 → 运行 → 查看结果）|
 | **Visual Regression** | Chromatic / Percy | UI 回归检测 |
 ### 7.4 性能优化
 | 方案 | 说明 |
 |---|---|
 | **代码分割** | React.lazy + Suspense，按视图/路由懒加载 |
 | **虚拟列表** | 知识库文档列表 / 运行历史 → 用 `react-virtual` |
 | **SSE 重连** | EventSource 断连自动重连 + 指数退避 |
 | **离线缓存** | Service Worker 缓存静态资源 |
 ### 7.5 大文件拆分
 | 文件 | 大小 | 建议 |
 |---|---|---|
 | [KbView.tsx](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-desktop/frontend/src/views/KbView.tsx) | 31,944 bytes | 拆为 `KbSearchPanel` / `KbDocList` / `KbGraphPanel` / `KbIngestPanel` |
 | [StudioView.tsx](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-desktop/frontend/src/studio/StudioView.tsx) | 11,966 bytes | 拆为 `Canvas` / `Toolbar` / `PropertiesPanel` |
 | [App.tsx](file:///Users/zhangjianmin/sourceCode/GolandProjects/src/sundynix-agentix/sundynix-desktop/frontend/src/App.tsx) | 8,942 bytes | 路由抽离后天然减小 |
 ---
 ## 八、运维自动化 (Platform Engineering)
 ### 8.1 集中配置管理 — ⚠️ 缺失
 **现状**：各服务独立 `config.yaml`，NATS 热更新仅覆盖模型配置。
 **需引入**：
 | 方案 | 说明 |
 |---|---|
 | **NATS KV** | NATS 2.8+ 内建 KV Store，已接 NATS 生态，零额外运维 |
 | **Consul** | 功能更全（服务发现 + 配置 + 健康检查），但多一个组件 |
 | 推荐 NATS KV（现有生态内扩展，无新增依赖）：配置变更 → Watch → 各服务热加载 |
 ### 8.2 优雅停机 — ⚠️ 部分
 **需确保**：
 - 收到 SIGTERM → 停止接收新请求 → 等待在途请求完成 → 关闭 NATS / PG / Redis → 退出
 - NATS ConsumeTasks 的 `stop` 函数已有 ✅，需在信号处理中调用
 - K8s `preStop` hook + `terminationGracePeriodSeconds: 30`
 ### 8.3 数据库 Schema 迁移 — ⚠️ 改进
 **现状**：GORM `AutoMigrate`（开发方便但生产风险高：字段删除不生效、大表加列会锁表）。
 **需引入**：
 | 工具 | 说明 |
 |---|---|
 | **golang-migrate** 或 **Atlas** | 版本化 SQL 迁移文件（up/down），CI 自动校验；生产用 `gh-ost` 做无锁 schema 变更 |
 | 保留 AutoMigrate 仅用于开发模式 | `if env == "dev" { db.AutoMigrate(...) }` |
 ### 8.4 健康检查统一 — ⚠️ 不一致
 **现状**：Gateway 有 HTTP 端点，Dispatcher 走 NATS ping，MCP-Go 走 NATS 队列组。
 **需引入**：
 ```go
 // 每个服务暴露统一的 /healthz (liveness) 和 /readyz (readiness)：
 // - liveness: 进程存活（总是 200）
 // - readiness: 所有依赖就绪
 //   Gateway:  PG connected + Redis connected + NATS connected
 //   Dispatcher: NATS connected + LLM pool ready
 //   MCP-Go:  NATS connected + Milvus ready + Bleve ready
 //   MCP-Py:  NATS connected + Docker available
 ```
 ### 8.5 告警与 On-Call
 | 能力 | 方案 |
 |---|---|
 | **告警规则** | Prometheus Alertmanager + PagerDuty / 飞书 / 钉钉 webhook |
 | **关键告警** | 错误率>5% / P99>5s / 熔断打开 / 磁盘>80% / 队列积压>1000 / LLM 成功率<90% |
 | **On-Call 轮值** | PagerDuty / OpsGenie 自动轮值 + 升级 |
 | **Runbook** | 每个告警对应标准处置流程文档 |
 ---
 ## 优先级排序（路线图）
 > 按风险/收益排序，分三阶段实施：
 ### 🔴 Phase 1：安全底线 + 部署能力 (4-6 周)
 | # | 事项 | 理由 |
 |---|---|---|
 | 1 | **密钥加密存储** (Vault/SOPS) | API Key 明文是最大安全风险 |
 | 2 | **Dockerfile 容器化** (4 个 Go 服务 + 1 Python) | 生产部署的前提 |
 | 3 | **Kubernetes Helm Chart** | 取代 docker-compose 部署 |
 | 4 | **NATS 3 节点集群** | 消除全局单点故障 |
 | 5 | **PG SSL + NATS TLS** | 传输层加密 |
 | 6 | **统一健康检查** (/healthz + /readyz) | K8s 探针就绪 |
 | 7 | **优雅停机信号处理** | 滚动更新不丢请求 |
 | 8 | **Token 计量基础** | 成本可控的前提 |
 ### 🟡 Phase 2：可观测性 + 治理能力 (4-6 周)
 | # | 事项 | 理由 |
 |---|---|---|
 | 9 | **OpenTelemetry Tracing** | 分布式链路追踪 |
 | 10 | **指标体系补全** | LLM/RAG/Task 指标 |
 | 11 | **Grafana 仪表盘** | 统一观测面板 |
 | 12 | **日志标准化** (全局 slog + Loki) | 结构化日志 + 集中采集 |
 | 13 | **审计日志** | 合规要求 |
 | 14 | **模型路由 + Fallback** | 提升可用性 |
 | 15 | **PG 主从 + 备份策略** | 数据安全 |
 | 16 | **CI 增强** (lint + security scan + coverage) | 代码质量门 |
 | 17 | **Schema 迁移工具** (golang-migrate) | 安全 DDL |
 ### 🟢 Phase 3：规模化 + 精细化 (6-8 周)
 | # | 事项 | 理由 |
 |---|---|---|
 | 18 | **多租户** | 商业化必需 |
 | 19 | **RBAC 角色体系** | 企业客户需求 |
 | 20 | **前端 React Router + Zustand** | 用户体验 + 可维护性 |
 | 21 | **前端测试** (Vitest + Playwright) | 质量保障 |
 | 22 | **Prompt 版本管理 + A/B 测试** | AI 质量持续优化 |
 | 23 | **Semantic Cache** | 降低 LLM 调用成本 |
 | 24 | **内容审查 (Llama Guard)** | 合规 |
 | 25 | **金丝雀发布 + Feature Flags** | 安全发布 |
 | 26 | **Milvus Cluster + Neo4j Cluster** | 数据层高可用 |
 | 27 | **告警体系 + Runbook** | 运维成熟度 |
 | 28 | **GDPR / 个保法合规** | 数据合规 |
 ---
 ## 技术选型速查表
 | 维度 | 推荐工具/组件 | 替代方案 |
 |---|---|---|
 | 链路追踪 | OpenTelemetry + Grafana Tempo | Jaeger / SkyWalking |
 | 指标 | Prometheus + Grafana | VictoriaMetrics |
 | 日志 | slog + Grafana Loki | ELK (Elasticsearch + Logstash + Kibana) |
 | 密钥管理 | HashiCorp Vault | AWS Secrets Manager / SOPS |
 | 容器编排 | Kubernetes + Helm | Docker Swarm (小规模) |
 | CI/CD | GitHub Actions + ArgoCD | GitLab CI / Jenkins |
 | 镜像仓库 | ghcr.io / Harbor | Docker Hub Private |
 | API 网关 | Traefik / Nginx Ingress | Kong / APISIX |
 | 配置中心 | NATS KV | Consul / etcd / Apollo |
 | Schema 迁移 | golang-migrate / Atlas | goose / Flyway |
 | Feature Flags | Unleash | LaunchDarkly / Flagsmith |
 | 内容审查 | Llama Guard (自部署) | 阿里绿网 / 腾讯天御 |
 | 前端状态 | Zustand | Jotai / Redux Toolkit |
 | 前端测试 | Vitest + Playwright | Jest + Cypress |
 | 告警 | Alertmanager + 飞书/钉钉 | PagerDuty / OpsGenie |
@@ -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
+- **Go 工作区**: `go.work` 管理 4 个后端模块（gateway/dispatcher/mcp-go/shared）
-  C["1·Client<br/>Wails+React 19"] --> G["2·Gateway<br/>Gin"]
+- **前端**: Vite 5 + TypeScript 5 + PostCSS + TailwindCSS
-  G --> N["3·NATS<br/>JetStream"]
+- **桌面端**: Wails v2（Go 后端 + WebView 前端，`GOWORK=off` 独立构建）
-  N --> D["4·Dispatcher<br/>Eino"]
+- **Makefile**: 统一的 `make` 命令编排所有服务启动、测试、构建
-  N --> T1["5a·MCP-Go<br/>I/O工具"]
+
-  N --> T2["5b·MCP-Py<br/>算法工具"]
+---
-  D --> T1
+
-  D --> T2
+## 三、已实现功能
 ### 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 |
+| **缺少 API 网关/服务网格** | Gateway 承担了鉴权/限流/DSL 解析/SSE 推送/管理等过多职责 | 考虑分离 BFF (面向前端) 与核心 Gateway，或引入 Kong/Traefik 负责横切关注点 |
-| **2·Gateway** | `sundynix-gateway` | Gin 统一接入、JWT 鉴权、DSL 解析组装、计费计量、输入护栏、模型配置控制面 |
+| **配置管理未集中** | 各服务 config/ 独立管理，NATS 热更新仅覆盖模型配置 | 引入统一配置中心（Consul/etcd 或 NATS KV），覆盖全部运行时配置 |
-| **3·Bus** | NATS Server | 零拷贝骨干网：JetStream 任务队列 + core NATS Token 流 / 执行轨迹 / 工具调用 |
+| **缺少链路追踪** | 日志为主要观测手段（`log.Printf`），无结构化 trace | 接入 OpenTelemetry (tracing + metrics)，NATS 消息头透传 trace ID |
-| **4·Dispatcher** | `sundynix-dispatcher` | Eino 图编排引擎、LLM Pool、ReAct Agent、报告多步编排、熔断降级、LLM 评测 |
+| **无服务注册发现** | 服务端点硬编码于配置 | 基于 NATS 已有能力做简单服务注册，或引入 Consul/etcd |
-| **5a·MCP-Go** | `sundynix-mcp-go` | 混合检索(Bleve+Milvus+Neo4j)、长期记忆(PgSQL)、Word 渲染、外部 API |
+| **单点瓶颈风险** | NATS 单节点（docker-compose）、Milvus standalone | 生产环境需 NATS 集群 + Milvus 分布式模式 |
 | **5b·MCP-Py** | `sundynix-mcp-py` | 安全沙箱(AST 守卫)、Docker 代码解释器、文档解析(docx/pdf/xlsx) |
 | **Admin** | `sundynix-admin` | 独立运维控制台（模型/数据源配置、服务状态、计价管理） |
---
+### 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 |
+| **Dispatcher graph.go 过大** | 单文件 492 行，混合了图执行、各节点实现、条件求值 | 拆分为 `node_agent.go` / `node_retriever.go` / `node_branch.go` 等，每类节点独立文件 |
-| TypeScript/TSX | 49 | ~5,000 |
+| **日志标准化不足** | 使用标准 `log.Printf`，无结构化字段和级别控制 | 引入 slog（Go 1.21 标准库）或 zap，统一 JSON 格式 + 日志级别 |
-| Python | 10 | ~620 |
+| **错误处理不够严谨** | 多处 `_ = msg.Respond(data)` / `_ = m.Respond(data)` 忽略错误 | 关键路径的响应失败应记录日志 |
-| Go 测试文件 | 18 | ~4,000（估） |
+| **魔法字符串** | 节点 Kind (`"agent"`, `"retriever"`) 为裸字符串 | 定义 `const` 枚举或使用 `iota`，消除散落的字符串匹配 |
-| **合计** | ~137 | **~13,600+** |
+| **部分 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 解耦，成熟度极高 |
+| **状态管理原始** | 纯 `useState` + props drilling，无全局状态管理 | 随功能增长，考虑引入 Zustand 或 Jotai 管理全局状态（当前/会话/运行态） |
-| **功能完整度** | ⭐⭐⭐⭐ | Agent 编排/RAG/记忆/报告/安全均已落地，计费/MCP-Py 有缺 |
+| **路由为自研视图切换** | `view` state + 条件渲染，无 URL 路由 | 引入 React Router，支持 URL 直达、浏览器前进后退 |
-| **代码质量** | ⭐⭐⭐⭐ | 注释充分、职责清晰、降级设计优秀；配置硬编码/日志结构化可改进 |
+| **类型安全不完整** | 部分 API 响应缺 TypeScript 类型定义 | 考虑 API 契约生成（OpenAPI → TypeScript types），前后端类型一致 |
-| **测试覆盖** | ⭐⭐⭐ | 后端 18 个测试文件含 e2e/集成/race；**前端零测试**拉低分 |
+| **KbView.tsx 过大** | 单文件 31944 字节 | 拆分为子组件（搜索面板 / 文档列表 / 图谱面板 / 入库面板） |
-| **工程化** | ⭐⭐⭐⭐ | Monorepo/Makefile/Docker Compose/统一规约；缺 CI/CD |
+| **无单元测试** | 前端零测试覆盖 | 引入 Vitest + React Testing Library，优先覆盖核心交互 |
 | **可扩展性** | ⭐⭐⭐⭐⭐ | NATS 消息总线天然支持水平扩展和微服务化 |
 | **安全性** | ⭐⭐⭐⭐ | 纵深防御（输入/输出/沙箱/鉴权/熔断）；JWT 密钥管理可强化 |
 | **开发体验** | ⭐⭐⭐⭐⭐ | `make demo` 零配置跑通全链路，热更新模型，文档详尽 |
-> [!TIP]
+### 6.4 安全
-> **综合评价**：这是一个架构功力深厚、功能覆盖广泛的 AI Agent 平台原型。其分层设计、消息总线解耦、全链路降级哲学和 Generative Agents 式记忆机制都体现了高水平的工程设计。当前阶段最值得投入的改进方向是：**前端测试覆盖**、**RAG 切块质量**、**CI/CD 自动化**。
+
 | 问题 | 现状 | 建议 |
 |---|---|---|
 | **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** 阶段，核心数据流和关键功能闭环已通，具备向生产环境演进的基础。