Blizzard
05c25d7099
滚动更新/重启时旧的"信号到→进程退"会硬切在途工作：dispatcher 在途任务被掐断、 mcp-go 在途工具调用让 dispatcher 干等超时、gateway 在途 HTTP 请求被截断。 共享 bus 加在途追踪 + drain： - ConsumeTasks/ServeTool 各加 sync.WaitGroup 跟踪在途 goroutine，返回 drain(ctx)： 先停止接新活（cc.Stop / Unsubscribe），再等在途跑完至 drain 超时。 - 关键修复：任务 handler 的 ctx 改为派生自 context.Background()（而非信号 ctx）， 否则 SIGTERM 会立即取消在途任务的 ctx，drain 形同虚设。超时未跑完才由 JetStream AckWait 重投兜底（不丢任务）。 - DrainTimeout()：SHUTDOWN_DRAIN_TIMEOUT 秒，默认 30s。 各服务收尾： - gateway：r.Run → http.Server + signal.NotifyContext + srv.Shutdown(drain 在途请求)， 随后 defer 关 db/redis/bus（HTTP 排空后才断后端连接）。 - dispatcher：收到信号 → drain 在途任务跑完再退。 - mcp-go：收到信号 → drain 在途工具调用回完再退（dispatcher 拿到结果而非超时）。 bus 加 TestGracefulDrain（drain 等满在途任务 + 验证在途 ctx 不被取消），e2e 测试适配 新签名，四模块全绿。live：在途任务执行中 kill -TERM dispatcher → 日志「drain 在途任务」 → 11s 后 task done(511字完整生成) → 「drain 完成，退出」，任务终态 done 非 failed； gateway/mcp-go 同样优雅退出。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
220 lines
16 KiB
Markdown
220 lines
16 KiB
Markdown
# 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` 极小）。
|
||
- **推理模型未适配**：主力 deepseek-v4-pro（及生产 Qwen thinking）答案在 `reasoning_content`，平台只读 `content`；思维链未流式呈现。
|
||
- **测试偏单元**：多为小函数单测；核心链路（图执行、RAG 管线）集成/e2e 稀疏；无前端 E2E。
|
||
|
||
---
|
||
|
||
## 五、缺失 / 生产硬门槛（最该正视）
|
||
|
||
| 缺口 | 现状 | 影响 |
|
||
|------|------|------|
|
||
| **高可用 / 单点** | 网关·调度·NATS 均单实例 | 任一挂即中断；无故障转移/自愈 |
|
||
| **备份 / 灾备** | PG/Milvus/Neo4j 无备份恢复方案 | 数据丢失风险 |
|
||
| **安全审计** | 全自述，未渗透/未审计 | "纵深防御"未被验证 |
|
||
| **配额 / 多租户** | 仅按 IP 全局限流；owner 基础隔离 | 无团队/组织/按用户配额 |
|
||
| **可靠性细节** | exec 轨迹流丢事件；~~停机不 drain~~（已优雅停机 drain） | 观测缺口 |
|
||
| **计量计费** | 计价配置有，计量×单价+配额未落地 | 商业化未闭环 |
|
||
| **本地模型** | 仅 OpenAI 兼容在线 API | vLLM/Ollama、模型路由/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 大文件需拆 |
|
||
| 测试覆盖 | ⭐⭐⭐ | 单测面广但多为小函数；集成/e2e 稀疏 |
|
||
| CI/CD | ⭐⭐⭐⭐ | CI+Release+更新检查；无签名公证 |
|
||
| 运维成熟度 | ⭐⭐ | 单点、无备份灾备、无配额、规模未验证 |
|
||
| 生态 / 商业化 | ⭐⭐ | 个人项目；计费未闭环 |
|
||
|
||
### 综合：**3.7 / 5.0** —— 单人项目里属于「相当能打」，离生产仍有实打实的距离。
|
||
|
||
---
|
||
|
||
## 八、改进优先级
|
||
|
||
| 优先级 | 项目 | 说明 |
|
||
|:------:|------|------|
|
||
| P0 | 真实负载 + 长稳压测，给容量曲线 | "生产级并发"需数据背书 |
|
||
| P0 | 本地模型(vLLM/Ollama) + 推理模型 reasoning_content 适配 | 对齐生产 Qwen |
|
||
| P1 | 高可用：网关/调度多副本 + NATS 集群 + 自愈 | 解单点 |
|
||
| P1 | 备份/灾备演练（PG/Milvus/Neo4j） | 数据安全 |
|
||
| ~~P1~~ ✅ | ~~优雅停机 drain~~：三 Go 服务全覆盖（gateway HTTP Shutdown / dispatcher 在途任务跑完 / mcp-go 在途工具回完），SIGTERM 后等在途至 SHUTDOWN_DRAIN_TIMEOUT(默认30s)再退；在途任务 ctx 脱离信号 ctx 不被掐断。剩 exec 轨迹 Redis 回放 | 可靠性 |
|
||
| P1 | 核心链路集成测试 + 前端 E2E | 测试纵深 |
|
||
| P2 | 计量计费闭环 + 按用户配额；OCR 完善；KbView 拆分；循环节点 | |
|
||
| P2 | 安全审计 / 渗透（让"纵深防御"从自述变已验证） | 外部 |
|
||
| P3 | 多租户/团队；插件体系；K8s Helm；代码签名 | |
|
||
|
||
---
|
||
|
||
*本报告由 Opus 4.8 基于全程搭建经验 + 本次实测撰写；刻意压低自评水分。功能盘点可信，
|
||
评分按成熟度折扣阅读。如与旧版（自动分析）冲突，以本版为准。*
|