diff --git a/production_readiness.md b/production_readiness.md new file mode 100644 index 0000000..085a690 --- /dev/null +++ b/production_readiness.md @@ -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; +} +``` + +### 7.2 路由 — ⚠️ 缺失 + +**现状**：`view` state + 条件渲染，无 URL 路由。 + +```typescript +// 引入 React Router v7（Admin 端已用）： +// → 支持 URL 直达、浏览器前进后退、深链接分享 +} /> +} /> +} /> +} /> +} /> +``` + +### 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 | diff --git a/project_analysis.md b/project_analysis.md index c8ccbc0..410a3fa 100644 --- a/project_analysis.md +++ b/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
Wails+React 19"] --> G["2·Gateway
Gin"] - G --> N["3·NATS
JetStream"] - N --> D["4·Dispatcher
Eino"] - N --> T1["5a·MCP-Go
I/O工具"] - N --> T2["5b·MCP-Py
算法工具"] - 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.`) + 执行事件流 (`sundynix.exec.`) 分离 +- **实时节点点亮**：前端 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.) + → Dispatcher (Eino 图编排, 记忆/历史召回) + → NATS request-reply → MCP Tools (Go I/O + Python 算法) + → Token Stream (sundynix.streams.) 零拷贝回流 + → 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.`）：节点级实时观测（点亮、工具入参/产出、耗时） -- 运维控制台健康五盏灯 - -### 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** 阶段，核心数据流和关键功能闭环已通，具备向生产环境演进的基础。