sundynix/sundynix-agentix
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
32f50cd983c58d86ae92edd138b0ae8fb736deda
sundynix-agentix/project_analysis.md
T
Blizzard 32f50cd983 test(dispatcher): Handle 入口级集成测试 —— 钉死核心编排链 + harness 治理栈协同 
此前测试都直打 runGraph/evaluate，绕过真正的任务入口 Handle()——熔断、输入护栏门控、
状态机流转、token 预算、异步评测/用量这些治理逻辑的协同从未在入口级被覆盖。

新增 handle_test.go 6 例（全 fake 依赖，可断言各出口）：
- HappyPath：running→done + token 流出/收尾 + 异步评测落库(ok)
- ToolFeedsAgent：图执行→工具→agent 全程经 Handle，工具被调、产出注入
- CircuitBreakerOpen：熔断开 → 快速 failed、不执行图
- BudgetExceeded：meta token_budget=3 → failed + 用量回写带 Exceeded
- GuardrailBlocks：灰区 + LLM 分类器命中 → rejected、不进 running
- EmptyTaskDropped：空 id 直接丢弃、无状态回写

配套 fakeStatus/fakeUsageSink；fakeEvalSink 加锁（Handle 异步评测在 goroutine 写）。
go test -race ./internal/eino 干净，四模块全绿。

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

19 KiB
Raw Blame History

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、容量实测、本地模型）。

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

  • P1 评测闭环 ✅：eval 结果经 NATS 落 PG（sundynix_eval）+ 分级(ok/warn/poor) + poor 告警 + GET /tasks/:id/eval 可查。dispatcher 评→广播→网关落库。剩：桌面端质量面板、低分自动重试(P3)。
  • P1 RAG 忠实度评测 ✅：检索原文喂给 judge，一次评质量+忠实度，未被来源支持的说法进 Flags。 综合分(有来源)=0.3规则+0.35质量+0.35忠实。runGraph 透传 refs → evaluate。live 实测忠实 1.00/来源 1，单测覆盖。
  • P2 输出脱敏增强 ✅：有状态 StreamRedactor 跨分片缓冲，切点在原文上定且绝不切断完整匹配， 杜绝密钥被切成两片漏检 / 提前脱敏半截致碎片泄漏（逐字符 JWT 流亦完整捕获）；rune 边界安全（中文不乱码）； 新增 PII（手机号/邮箱/身份证）；opener+尾窗双兜底、暂留封顶防 DoS。3 流式点接入，7 单测，live 实测密钥/邮箱整条脱敏。
  • P2 输入护栏升级 ✅：两层。Tier1（网关同步、无 LLM）先归一化（小写/去零宽/同形字折叠/拆字间隔还原/base64 解码）再跑高精度正则——干掉编码/空格/同形字绕过；bannedTerms 经 env 落地。Tier2（dispatcher harness LLM 分类器）只对 Tier1 判「灰区」的软信号输入裁决（escalation，明确干净/恶意不付 LLM 成本），命中→rejected，fail-open 降级。live 实测：拆字/base64/西里尔同形字均拦；恶意灰区被 LLM 拒(severity 1)、良性灰区(海盗 roleplay)放行完成。
  • P3 坏输出自动纠偏 ✅：poor(<0.5) 触发评语驱动的重生成，重评后仅采纳更优者(不退步)， 采纳的修订版落会话历史 + 评测终值带 corrected 标记落库。maxRefineRounds=1、canRefine(模型就绪且熔断未开)门控； 单 goroutine 串 评测→纠偏→落历史避竞态。单测覆盖 采纳/不退步/非低分不触发，live 验证好答案不误触发。至此 harness 由「测温计」迈入「恒温器」。
  • 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 例，-race 干净）+ bus 真实 NATS e2e；剩 RAG 管线集成、前端 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 例（熔断/护栏/预算/状态机/工具→agent/异步评测）已补。剩 RAG 管线集成 + 前端 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 基于全程搭建经验 + 本次实测撰写；刻意压低自评水分。功能盘点可信， 评分按成熟度折扣阅读。如与旧版（自动分析）冲突，以本版为准。

Reference in New Issue View Git Blame Copy Permalink