# sundynix-agentix · 项目分析报告

> 撰写：2026-06-24 · 由 Opus 4.8 在**全程参与搭建**后基于实测与源码盘点撰写（覆盖旧版自动分析）。
>
> **立场**：本报告刻意避免营销腔。功能层面据实盘点；价值层面对"功能存在"与"成熟/被验证"严格区分。
> 本项目绝大多数能力为**单人新作、未经外部审计、未经真实流量与规模长稳验证**——请据此理解所有评分。

---

## 〇、一句话定位

**一个功能密度极高、架构品味很好的单人「准生产原型」。** 编排深度、安全覆盖面、可观测性在同类
开源项目里都属上乘；但离"生产可用"的差距不只在生态/商业化，更在**高可用、规模验证、灾备、审计**
这些运维硬门槛——这些目前基本是空白。

---

## 一、真实数据（本次实测）

| 维度 | 数据 | 备注 |
|------|------|------|
| 源码总量 | **~19,200 行**（不含依赖/生成） | 实测 |
| Go 后端 | 12,776 行（含测试 ~2,397） | gateway 3121 / dispatcher 4222 / mcp-go 3872 / shared 1561 |
| 前端 TS/TSX | 5,809 行 | 桌面端 4,628（47 文件）+ 运维台 1,181（13 文件） |
| Python 工具 | 456 行 | mcp-py |
| 测试文件 | **32**（Go 26 + 前端 5 + Py 1） | |
| 代码模块 | Go 4 工作区模块 + desktop(Wails) + 2 前端 + mcp-py | |
| 提交数 | dev 119 | dev 比 origin/dev 多 4 未推；origin/main 基本同步（差 1 文档提交） |
| 关键依赖 | Eino v0.9.9 · OTel v1.44 · nats.go v1.37 · gorm v1.31 · milvus-sdk v2.4.1 | |
| 基础设施 | docker-compose 8 服务 | nats/pg/redis/jaeger/neo4j/milvus(+etcd+minio) |

> 订正旧报告两处不实：① 旧版称"基于 main 117 提交"，实为 dev；② 之前我多次口头说的"14 个未推送
> commit"是**错的**——实测 dev 仅比 origin/dev 多 4，origin/main 已基本同步。

---

## 二、架构与请求生命周期

5 层 + NATS 总线：

```
桌面端(Wails)/运维台(Web) ──HTTP──▶ Gateway(Gin)
                                      │  鉴权·护栏·限流·DSL 解析·SSE 回流
                                      ▼  JetStream 发布 task
                                  NATS 总线 ──(W3C traceparent 注入消息头)
                                      ▼  限并发消费
                              Dispatcher(Eino 图编排)
                                      │  记忆召回→工具→注入→流式·HITL 审批·熔断·评测
                                      ▼  core NATS request-reply(带 trace)
                            mcp-go / mcp-py(MCP 工具层，队列组水平扩)
```

- **任务流**：JetStream 持久化 + 持久消费者 + 限并发 worker 池（`DISPATCHER_CONCURRENCY`，背压由信号量 + `MaxAckPending` 双约束）。
- **工具调用**：core NATS request-reply，队列组负载均衡；单实例工具已协程化并发。
- **回流**：Token 流（Redis Stream 可回放 + 断点续传）与执行轨迹流（实时 NATS）分离。
- **控制面**：模型配置经 NATS 热更新；启动竞态用后台重试根治。

这套解耦是真的、跑得通的（本会话端到端验证过多条链路）。**机制层面**支持独立替换/水平扩；
**但水平扩仅本地小规模验证，未上真实集群。**

---

## 三、做得扎实的部分（本会话实测确认）

### 1. 编排引擎（Eino A→D 深度集成）
- 自研 `graph.go` + `compose.Graph` 双轨（灰度开关，compose 编译失败自动降级，安全网真实存在）。
- **ReAct 自主智能体**：模型自主选工具；`list_tools` 自描述 + 动态发现——**加工具零改调度代码**（本会话加 6 个工具，dispatcher 一行没动，自主 agent 直接会用，已实测）。
- **HITL 人工审批**：审批节点暂停→`waiting`→批准续跑/拒绝中止；超时安全默认拒绝；前端轮询持久状态兜底（不依赖易丢的实时事件）。实测批准/拒绝两条路径正常。
- branch 条件选路 + map 有界并发 + aggregate 汇聚 + 多 agent 图接力。

### 2. 安全治理（覆盖面广；自实现、未审计）
- 输入护栏（注入正则 + 体积限制）、**输出护栏（流式逐片脱敏 sk-/AKIA/JWT）**、三态熔断（`-race` 过）、LLM 评测（异步离热路径）。
- 代码沙箱（Docker 隔离 + AST 守卫 + 禁网/非 root/丢能力/只读根/限资源/超时 kill）。
- **API Key 端到端 AES-256-GCM**：磁盘 + NATS 线缆均密文，仅用时内存解密；历史明文平滑迁移（实测密文落库 + 解密打通 DeepSeek）。
- SSRF 防护（external_api/web_fetch）、SQL 只读三重防护、JWT（生产 fail-fast）。
- ⚠️ 价值定性：**覆盖广 ≠ 已验证安全**。无外部审计/渗透；"最强"无依据。

### 3. 知识库 / RAG
- Milvus 向量 + Bleve 全文 + Neo4j 图谱 → RRF 融合 → 可选 rerank。
- **Markdown 标题感知切块**（块带章节面包屑、不跨章节、跳过代码围栏，rune 安全）——实测入库面包屑正确、检索带章节上下文返回。
- Obsidian 式双链文库 + 入库可视化进度。

### 4. Agent 工具集（22 个 Go 注册，10 个 agent 可见 + mcp-py 5 个）
- 知识库/记忆/历史/报告/external_api +（本会话新增并实测）**web_search**（Tavily/DDG 兜底）、**web_fetch**、**calculator**（调度场算法）、**current_datetime**、**sql_query**（三重防护）、**chart**（产 JSON spec，前端 SVG 渲染，职责分离）。

### 5. 可观测性
- **OTel 全链路**：跨 NATS 传 traceparent，Jaeger 一棵 span 树（实测 14 span/3 服务）。
- **slog 带 trace_id**（日志↔链路互跳，实测同一 trace_id 命中）；Prometheus；健康探针；SSE 断点续传。

### 6. 性能/并发（本会话补齐 + 实测）
- 任务并发消费 + 工具协程化并发（垂直）× 队列组多副本（水平）。实测：一个 HITL 待审任务不阻塞其他任务；平台自身开销可忽略，瓶颈在外部 LLM。

### 7. 工程化 / CI/CD
- `make demo` 无 Docker 内嵌 NATS 跑全链路；docker-compose 零配置；模型热更新；DB 连接池上限；启动竞态修复。
- GitHub Actions CI（4 Go 模块 + 前端 tsc + mcp-py）+ Release（tag→macOS/Windows 桌面端构建）+ 桌面端更新检查。

---

## 三·五、Harness 治理层专项（逐项优化清单）

Harness = 围绕 LLM 的可靠性 / 安全 / 质量治理层。4 个组件均为真实现 + 单测，成熟度参差。

| 组件 | 文件/规模 | 成熟度 | 实情 |
|------|----------|:------:|------|
| 熔断器 CircuitBreaker | 126 行 + 112 测试 | ⭐⭐⭐⭐½ | 三态 + 阈值 + 冷却 + 半开探测 + 可注入时钟 + `-race` 安全，**真·生产级** |
| 评测 Evaluator | 135 行 + 91 测试 | ⭐⭐⭐ | 规则分(空/过短/拒答/复读) + LLM-judge(1–5)；异步离热路径 |
| 输出脱敏 RedactSecrets | 26 行 + 39 测试 | ⭐⭐⭐ | 4 正则(sk-/AKIA/JWT/Bearer)，流式逐片 |
| 输入护栏 Guardrail | guardrail.go + 测试 | ⭐⭐½ | 注入正则(中英) + 体积限制 + 敏感词黑名单(默认空) |

**定性（更新）**：起初是**「测温计」（检测+记录）**——多数信号只打日志。经评测闭环、低分自动纠偏、
忠实度评测、输出脱敏增强、输入护栏升级、成本预算护栏六项，现已成**「恒温器」（检测→决策→门控/纠偏闭环）**：
熔断挡后端雪崩、输入护栏两层挡注入/越狱、评测分级+低分重生成、输出脱敏挡密钥/PII、预算护栏挡失控成本。
下一步重心转 P0/P1 生产硬骨头（优雅停机、HA、容量实测、本地模型）。

**已知短板 / 优化清单**（按性价比，逐项推进）：

- [x] **P1 评测闭环** ✅：eval 结果经 NATS 落 PG（sundynix_eval）+ 分级(ok/warn/poor) + poor 告警 +
  `GET /tasks/:id/eval` 可查。dispatcher 评→广播→网关落库。剩：桌面端质量面板、低分自动重试(P3)。
- [x] **P1 RAG 忠实度评测** ✅：检索原文喂给 judge，一次评质量+忠实度，未被来源支持的说法进 Flags。
  综合分(有来源)=0.3规则+0.35质量+0.35忠实。runGraph 透传 refs → evaluate。live 实测忠实 1.00/来源 1，单测覆盖。
- [x] **P2 输出脱敏增强** ✅：有状态 `StreamRedactor` 跨分片缓冲，切点在原文上定且**绝不切断完整匹配**，
  杜绝密钥被切成两片漏检 / 提前脱敏半截致碎片泄漏（逐字符 JWT 流亦完整捕获）；rune 边界安全（中文不乱码）；
  新增 PII（手机号/邮箱/身份证）；opener+尾窗双兜底、暂留封顶防 DoS。3 流式点接入，7 单测，live 实测密钥/邮箱整条脱敏。
- [x] **P2 输入护栏升级** ✅：两层。Tier1（网关同步、无 LLM）先**归一化**（小写/去零宽/同形字折叠/拆字间隔还原/base64 解码）再跑高精度正则——干掉编码/空格/同形字绕过；`bannedTerms` 经 env 落地。Tier2（dispatcher harness LLM 分类器）只对 Tier1 判「灰区」的软信号输入裁决（escalation，明确干净/恶意不付 LLM 成本），命中→rejected，fail-open 降级。live 实测：拆字/base64/西里尔同形字均拦；恶意灰区被 LLM 拒(severity 1)、良性灰区(海盗 roleplay)放行完成。
- [x] **P3 坏输出自动纠偏** ✅：poor(<0.5) 触发评语驱动的重生成，重评后**仅采纳更优者(不退步)**，
  采纳的修订版落会话历史 + 评测终值带 `corrected` 标记落库。`maxRefineRounds=1`、`canRefine`(模型就绪且熔断未开)门控；
  单 goroutine 串 评测→纠偏→落历史避竞态。单测覆盖 采纳/不退步/非低分不触发，live 验证好答案不误触发。**至此 harness 由「测温计」迈入「恒温器」。**
- [x] **P3 成本/Token 预算护栏** ✅：用量估算计量(CJK/ASCII 启发式，无需分词器)。**单任务硬上限**：Budget 挂 ctx 沿图透传，各 LLM 节点(对话/ReAct/compose/报告)入口计输入、出口计输出，触顶即中止(报告优雅降级跳过剩余章节)；防失控成本。**单用户日预算**：dispatcher 收尾经 NATS 回写 UsageEvent → 网关按用户按天累计 Redis → 提交前门控(USER_DAILY_TOKEN_BUDGET，超额 402)，`/billing` 出当日用量/预算/余额。live：单任务 budget=30 → failed(已用约689)；用户日 budget=200 → 402。

---

## 四、原型级 / 未验证（别当生产能力看）

- **规模未真实验证**：并发是近期才补的，仅本地小规模测过；无长稳、无容量上限实测曲线。
- **compose 引擎仍灰度**（默认走自研 graph.go）；compose 路径下 HITL 审批未实现。
- **OCR 多模态是骨架**：`parse_document` 真支持 txt/md/csv/docx/xlsx/文本 PDF，但 MinerU/PaddleOCR 扫描件路径是 TODO 空实现（`mineru.py` 极小）。
- **推理模型已部分适配**：reasoning 模型的 `reasoning_content` 已捕获并 surface 到 exec 轨迹「推理过程」事件（不污染答案）；尚未在最终答案区把思维链单独流式呈现给前端。
- **测试纵深改善中**：除小函数单测，已补 `Handle()` 入口级集成（熔断/护栏/预算/状态机/工具→agent/异步评测 6 例）+ **RAG 管线集成**（检索→注入 prompt→生成→refs 回流→grounded 忠实度评测 + owner 作用域 + 优雅降级 4 例）+ bus 真实 NATS e2e，均 -race 干净；剩前端 E2E。

---

## 五、缺失 / 生产硬门槛（最该正视）

| 缺口 | 现状 | 影响 |
|------|------|------|
| **高可用 / 单点** | 🟡 代码层多副本安全（调度队列组 + 网关队列组订阅去重，均实测）；NATS 集群/网关 LB/PG·Redis HA 待部署期 | 进程级已可水平复制；基础设施 HA 仍缺 |
| **备份 / 灾备** | PG/Milvus/Neo4j 无备份恢复方案 | 数据丢失风险 |
| **安全审计** | 全自述，未渗透/未审计 | "纵深防御"未被验证 |
| **配额 / 多租户** | 仅按 IP 全局限流；owner 基础隔离 | 无团队/组织/按用户配额 |
| **可靠性细节** | ~~exec 轨迹流丢事件~~（已 Redis 回放/断点续传）；~~停机不 drain~~（已优雅停机 drain） | ✅ 两项已补 |
| **计量计费** | 计价配置有，计量×单价+配额未落地 | 商业化未闭环 |
| **本地模型** | ✅ vLLM/Ollama 已接（provider 感知，自动补 /v1 + 占位 key）；模型路由/多模型 fallback 仍未做 | |

---

## 六、对标主流开源项目（口径：功能存在性，非成熟度）

> **重要**：下表 ✅/❌ 仅表示"功能是否内置存在"，**不含成熟度、规模、生态、可靠性权重**。
> 此类矩阵天然利好新项目（可挑竞品没内置的新特性，而竞品的护城河——生态/被验证程度/可靠性——
> 无法用勾选体现）。Dify/Langflow 等的真实优势在这些"勾不出来"的地方。

| 维度 | sundynix | 说明（去掉滤镜） |
|------|:--------:|------|
| 可视化编排 / DAG | ✅ 双轨 | 与主流持平；缺循环/迭代节点 |
| ReAct + 工具动态发现 | ✅ | `list_tools` 自描述是亮点；Dify 用插件市场（机制不同，非"做不到"） |
| 人工审批 HITL | ✅ | 有；Dify 也有，FastGPT/Flowise 无 |
| 多智能体 | ✅ 图接力 | **AutoGen 等专门框架更强**，别自比第一 |
| 三路混合检索 + 图谱 | ✅ Neo4j | 较少见的内置组合，是真亮点 |
| 标题感知切块 | ✅ | 主流也有多策略切块，非独有 |
| 输出流式脱敏 / AES 加密 / OTel 跨总线 | ✅ | 内置且齐全，属较稀有组合（成熟度另说） |
| 原生桌面端 (Wails) + 自动更新 | ✅ 独有 | 竞品多纯 Web |
| 生态 / 社区 / 被生产验证 | ❌ | **竞品真正的护城河，本项目空白** |
| 商业化（计费/多租户/插件市场） | 🟡/❌ | 未闭环 |

**结论**：在"内置功能的齐全度"上，本项目确实能和数万 star 项目掰手腕，部分组合更超前；
但**"超越"它们是不成立的**——它们赢在被千万次真实使用打磨出的可靠性、生态与运维成熟度，
这正是单人项目无法靠堆功能追平的。

---

## 七、评级（功能完成度 vs 成熟度分列）

| 维度 | 评分 | 说明（已含成熟度折扣） |
|------|:----:|------|
| 架构设计 | ⭐⭐⭐⭐ | 解耦清晰、品味好；单点无 HA、规模未验证 |
| 编排引擎 | ⭐⭐⭐⭐½ | 双轨+ReAct+HITL+多 Agent，完成度高；缺循环、compose 仍灰度 |
| 安全治理 | ⭐⭐⭐⭐ | 覆盖面广；未审计/未渗透 |
| 知识库 RAG | ⭐⭐⭐⭐ | 三路+图谱+标题切块；OCR 骨架 |
| Agent 工具集 | ⭐⭐⭐⭐½ | 丰富 + 动态发现 + SQL/图表 |
| 可观测性 | ⭐⭐⭐⭐ | OTel+Prometheus+slog；轨迹流会丢事件 |
| 性能 / 并发 | ⭐⭐⭐½ | 双扩机制具备；规模未实测 |
| 代码质量 | ⭐⭐⭐⭐ | 注释充足、降级完善；KbView 大文件需拆 |
| 测试覆盖 | ⭐⭐⭐½ | 单测面广 + Handle 入口集成 + bus 真实 NATS e2e；剩 RAG 管线集成、前端 E2E |
| CI/CD | ⭐⭐⭐⭐ | CI+Release+更新检查；无签名公证 |
| 运维成熟度 | ⭐⭐ | 单点、无备份灾备、无配额、规模未验证 |
| 生态 / 商业化 | ⭐⭐ | 个人项目；计费未闭环 |

### 综合：**3.7 / 5.0** —— 单人项目里属于「相当能打」，离生产仍有实打实的距离。

---

## 八、改进优先级

| 优先级 | 项目 | 说明 |
|:------:|------|------|
| ~~P0~~ 🟡 | ~~容量压测曲线~~（首版）：`cmd/loadtest` 闭环加压器 + 平台天花板实测（见下「容量实测」）。剩长稳/真实 LLM 大压 | "生产级并发"需数据背书 |
| ~~P0~~ ✅ | ~~本地模型(vLLM/Ollama) + reasoning_content 适配~~：Pool provider 感知（Ollama/vLLM 自动补 /v1 + 占位 key），统一走 OpenAI 兼容路径；ChatStream 加 onReasoning，思考过程 surface 到 exec 轨迹（不污染答案）。控制台加 ollama 选项。live：Ollama qwen2.5:0.5b 端到端出答案；deepseek-v4-pro「推理过程」入轨迹 | 对齐生产 Qwen |
| ~~P1~~ 🟡 | 高可用（代码层就绪）：调度/工具本就队列组可多副本（实测 2 副本 8 任务 4/4 分摊）；**网关改为队列组订阅**（eval/usage/status/config），多副本不再重复落库/重复计费（单测+实测去重）。剩 NATS 集群 + 网关 LB + PG/Redis HA 属部署期 | 解单点 |
| P1 | 备份/灾备演练（PG/Milvus/Neo4j） | 数据安全 |
| ~~P1~~ ✅ | ~~优雅停机 drain~~：三 Go 服务全覆盖（gateway HTTP Shutdown / dispatcher 在途任务跑完 / mcp-go 在途工具回完），SIGTERM 后等在途至 SHUTDOWN_DRAIN_TIMEOUT(默认30s)再退；在途任务 ctx 脱离信号 ctx 不被掐断。**+ exec 轨迹 Redis 回放**（与 token 流同构，连晚/刷新重连不丢轨迹，实测事后连仍补齐全程）| 可靠性 |
| ~~P1~~ 🟡 | ~~核心链路集成测试~~：Handle 入口级 6 例 + RAG 管线 4 例（检索→注入→生成→refs→grounded 评测）已补。剩前端 E2E | 测试纵深 |
| P2 | 计量计费闭环 + 按用户配额；OCR 完善；KbView 拆分；循环节点 | |
| P2 | 安全审计 / 渗透（让"纵深防御"从自述变已验证） | 外部 |
| P3 | 多租户/团队；插件体系；K8s Helm；代码签名 | |

---

## 容量实测（首版，2026-06-26）

**方法**：`cmd/loadtest` 闭环加压（阶梯并发，SSE 流检测完成、非轮询，避免轮询放大）。
dispatcher 开 `LLM_FORCE_STUB=1 LLM_STUB_*_MS=0` 绕开真实 LLM 推理，量**平台自身全链路天花板**
（网关→NATS/JetStream→调度→图执行→工具RTT→Token回流→PG状态写），单 dispatcher、DISPATCHER_CONCURRENCY=64。

| 并发 | 吞吐/s | p50 | p95 | 备注 |
|---:|---:|---:|---:|---|
| 1 | 23 | 42ms | 46ms | **单任务纯平台开销 ~42ms** |
| 8 | 76 | 103ms | 115ms | |
| 16 | 96 | 161ms | 176ms | |
| 32 | 112 | 269ms | 345ms | **吞吐峰值** |
| 64 | 112 | 557ms | 676ms | 饱和（延迟翻倍、吞吐不增）|
| 128 | 102 | 1173ms | 1590ms | 过载、优雅降速 |
| 256 | 0 | — | — | 硬崩（连接/DNS 抖动）|

**结论**：
1. **单节点平台天花板 ≈ 110 全链路任务/秒**，单任务固有开销 ~42ms，饱和点 ~并发 32–64。
2. **吞吐瓶颈不是 DB 连接数**（池 25→80 吞吐不变），而是每任务多跳管线（JetStream fsync + 多次
   NATS 回写 + Redis 录制 + 3 次 PG 状态写）的综合成本。
3. **C=256 停摆**是单节点饱和（任务排队 + PG 状态写 + 网关 handler 顶不住），非 bug；C≤128 优雅可用。
   DSN 已由 `localhost` 改 `127.0.0.1`（消除每连接 DNS 解析，卫生改进，但不解决饱和）。正解是横向扩。
4. **关键判断**：平台开销 42ms ≪ 真实 LLM 出一轮答案的秒级延迟，**平台不是瓶颈，GPU 才是**。
   单 GPU 跑 Qwen 32B 约出几十轮/秒，远低于平台的 ~110/s → 横向拆服务（队列组多副本喂满 GPU 集群）
   的意义成立；要提总吞吐应加 dispatcher 副本与 GPU，而非优化平台代码。
5. 待补：长稳（小时级）压测看内存/句柄泄漏；真实 LLM 端到端容量（受 provider 限流，需自部署后测）。

---

*本报告由 Opus 4.8 基于全程搭建经验 + 本次实测撰写；刻意压低自评水分。功能盘点可信，
评分按成熟度折扣阅读。如与旧版（自动分析）冲突，以本版为准。*
