Files
sundynix-agentix/project_analysis.md
Blizzard 165ecb4ec6 test(dispatcher): RAG 管线集成测试 —— 检索→注入→生成→refs→忠实度评测整条链
补全核心链路最后一块。此前只测了 retriever 组件的解析,整条 RAG 管线没被集成覆盖。

新增 rag_integration_test.go 4 例:
- ConversationInjectsAndReturnsRefs:input→retriever→agent,断言 kb_search 被调、
  kb 按 owner 作用域(u42/travel)、检索片段注入 agent system prompt、refs 经 runGraph 回流。
- RefsDriveGroundedEval:有 refs 时 evaluate 走「含检索资料」的 grounded judge 路径,
  记录忠实度分(而非无来源路径)。
- ReportSectionInjectsRefs:报告 writeSection 检索命中注入撰写 prompt。
- DegradesWhenRetrieverDown:kb_search 失败 → 空 refs,agent 仍正常出答案、整图不失败。

go test -race ./internal/eino 干净,四模块全绿。至此核心编排链 + RAG 管线均有集成兜底。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-26 14:21:11 +08:00

249 lines
19 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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,62847 文件)+ 运维台 1,18113 文件) |
| 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 多 4origin/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 传 traceparentJaeger 一棵 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 CI4 Go 模块 + 前端 tsc + mcp-py+ Releasetag→macOS/Windows 桌面端构建)+ 桌面端更新检查。
---
## 三·五、Harness 治理层专项(逐项优化清单)
Harness = 围绕 LLM 的可靠性 / 安全 / 质量治理层。4 个组件均为真实现 + 单测,成熟度参差。
| 组件 | 文件/规模 | 成熟度 | 实情 |
|------|----------|:------:|------|
| 熔断器 CircuitBreaker | 126 行 + 112 测试 | ⭐⭐⭐⭐½ | 三态 + 阈值 + 冷却 + 半开探测 + 可注入时钟 + `-race` 安全,**真·生产级** |
| 评测 Evaluator | 135 行 + 91 测试 | ⭐⭐⭐ | 规则分(空/过短/拒答/复读) + LLM-judge(15);异步离热路径 |
| 输出脱敏 RedactSecrets | 26 行 + 39 测试 | ⭐⭐⭐ | 4 正则(sk-/AKIA/JWT/Bearer),流式逐片 |
| 输入护栏 Guardrail | guardrail.go + 测试 | ⭐⭐½ | 注入正则(中英) + 体积限制 + 敏感词黑名单(默认空) |
**定性(更新)**:起初是**「测温计」(检测+记录)**——多数信号只打日志。经评测闭环、低分自动纠偏、
忠实度评测、输出脱敏增强、输入护栏升级、成本预算护栏六项,现已成**「恒温器」(检测→决策→门控/纠偏闭环)**:
熔断挡后端雪崩、输入护栏两层挡注入/越狱、评测分级+低分重生成、输出脱敏挡密钥/PII、预算护栏挡失控成本。
下一步重心转 P0/P1 生产硬骨头(优雅停机、HA、容量实测、本地模型)。
**已知短板 / 优化清单**(按性价比,逐项推进):
- [x] **P1 评测闭环** ✅:eval 结果经 NATS 落 PGsundynix_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 落地。Tier2dispatcher harness LLM 分类器)只对 Tier1 判「灰区」的软信号输入裁决(escalation,明确干净/恶意不付 LLM 成本),命中→rejectedfail-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 选项。liveOllama 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 顶不住),非 bugC≤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 基于全程搭建经验 + 本次实测撰写;刻意压低自评水分。功能盘点可信,
评分按成熟度折扣阅读。如与旧版(自动分析)冲突,以本版为准。*