sundynix/sundynix-agentix
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f7d12cbf6663db6910596cc5f36c194a68722963
sundynix-agentix/DEPTH_ROADMAP.md
T
Blizzard f7d12cbf66 docs: DEPTH_ROADMAP T4.A 多租户增量1 打勾（租户身份地基） 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-06 17:32:11 +08:00

22 KiB
Raw Blame History

sundynix-agentix · 深度路线图

目标：在现有广度下做深度 —— 不加新功能面，把已有的盘活、做实、能交付。 用法：完成一项勾一项 [ ]→[x]，子项同理。每完成一个 Tier 回顾一次。 图例：[ ] 未做 · [x] 完成 · [~] 进行中 · 🔴 高杠杆 · ⏸ 暂缓

诊断：深度不足分四类（别混排）

  • A 建了没激活/没校准：评测裁判恒给 ~1.00 → 纠偏闭环空转；多智能体后端通了但 Studio 画不出。
  • B 重复/欠债的税：两套编排引擎（graph.go + compose）；前端测试薄（自评 🔴）。
  • C AI 核心还浅：单模型无 fallback；RAG 三路部分降级/桩、无检索质量度量；无 prompt 版本管理/输出缓存。
  • D 生产硬化 🔴：审计日志 / NATS 集群 / DB HA / K8s / TLS —— 是"部署深度"非"产品深度"，无真实流量前暂缓。

🥇 Tier 0 — 激活已有投入（小改动，最高回报）

[x] T0.1 🔴 校准评测裁判 — 让恒温器真触发 ✅

现状：LLM judge 恒给 0.94/1.00，从不判 poor，低分自动纠偏闭环几乎从没启动。

  • eval.go judge 改对抗性/rubric 打分（默认怀疑、先挑毛病再打分、给死评分基准、用满 1–5）
  • grounded judge 同样收紧（忠实度按编造数递减，一处编造≤2；未支持说法进 Flags）
  • 根因更深的数学修复：归一 score/5(下限 0.2) → (v-1)/4(1→0)，否则 0.4*rule 底使 poor 永不可达
  • 校准测试：normJudge 区间 + 「流畅但跑题(judge=1)可达 poor」+ 好坏区分度
  • 复核阈值（poor<0.5 / warn<0.75）与新分布匹配
  • 验收 ✅ live(deepseek)：跑题→0.40 poor→触发纠偏(0.40→0.55)；截断→0.55 warn；好答案→1.00 ok。 校准前这三个全是 1.00→ok，恒温器从没触发。

[x] T0.2 多智能体进 Studio（多智能体 v2）✅

现状：coordinator 后端已通（见 MULTI_AGENT.md），但画布拖不出。

  • nodeCatalog 加 coordinator 节点（「多智能体协调」，indigo）+ 新 agentList 字段类型 + Specialist 接口
  • Inspector AgentListField：可增删的专家卡片（名/用途/系统提示词/工具逗号分隔）
  • dsl 校验：agentList 需 ≥1 个有名字的专家 + 名字不重复
  • 运行轨迹「工具调用」面板纳入专家派发（kind=agent）→ 改名「工具/专家」，专家项 indigo 标识
  • 后端验证：UI 同款 DSL 结构提交可跑（agents 数组经 exportDsl 透传 → parseSpecialists）
  • 验收 ✅：Studio 左栏出现「多智能体协调」节点，检查器配专家卡片，导出 DSL 对齐后端； 轨迹/工具面板能看到专家派发。（真机由用户在 wails 窗口确认）

🥈 Tier 1 — 收口 / 去税

[x] T1.1 退役 graph.go — 消灭双引擎 ✅

现状：compose 已默认，HITL/多智能体只在 compose 上；graph.go 是逃生舱。

  • compose soak（默认跑数天，HITL/多智能体/评测全在其上真实运行）
  • 删 runGraph（自研拓扑解释器）+ composeEnabled/EINO_COMPOSE 开关 + runConversation 死代码
  • compose 编译失败兜底改单轮对话（不再回退 graph.go）；清掉仅 runGraph 用的 import(otel)
  • 保留 board/各节点执行器/工具函数（compose 各 lambda 复用）；8 处测试 runGraph→runComposeGraph， 等价测试转为 compose 正确性测试，runConversation 测试转为「无 ChatModel 降级 runAgent」
  • 验收 ✅：单引擎，go test ./... 全绿 + vet 干净；冒烟 简单 agent/分支图 跑通；HITL/多智能体/branch/map 全在 compose 上。

[ ] T1.2 前端深度补齐

  • 评测质量面板（运行页展示 overall/质量/忠实/纠偏/flags，驱动 T0.1 的可见性）
  • HITL 边角（长等待后 token 重连、拒绝分支体验）
  • 补前端测试（自评 🔴 缺失）：关键流程（run/审批/多智能体）的组件/逻辑测试
  • 验收：后端已有能力在 UI 都可见可操作；前端测试覆盖核心流程。

[~] T1.3 管理端做实（admin 控制台从 mock → 真控制面）

管理端定位 = 系统控制塔（统筹全系统：全局吞吐/配置态/健康/安全/成本），区别于桌面端个人运行页。 RBAC 未做，暂以单管理员账号代理；概览口径必须是系统级而非个人作用域。

  • 接 vitest（此前零测试）+ 41 单测（api/diff/路由派生）
  • 新增「提示词」控制面页（接 /api/v1/prompts：建版本/激活热下发/对比 diff/撤销，live 验证）
  • 概览页重做为「系统控制塔」：全局任务吞吐 + 模型路由/Fallback 态 + 提示词控制面态 + 系统健康拓扑 （去掉个人作用域的 我的KB/我的token/我的运行feed，与桌面端运行页不再重复）
  • 🔴 下一步：admin 专属聚合接口 GET /api/v1/admin/overview（RequireAdmin） —— 概览现借桌面端个人接口 stats/overview（其任务/评测碰巧全局因 Task/Eval 无 owner），不干净。 新接口一处聚合系统治理口径：全平台用户总数 / 租户数 / 全局任务(今日/累计/趋势/终态) / 全局评测均分 / 模型配置态 / 提示词覆盖数 / 服务健康。前端概览改吃此接口，补上「用户/租户总数」缺口。
  • 其余 mock 页按需做实：Datasources / Evals / Tenants / Guardrails（多为本地 mock，无后端数据源）
  • 验收：概览/关键页吃真实系统级数据；admin 有独立聚合接口不再蹭个人接口。

🥉 Tier 2 — 把 AI 核心做深（差异化卖点）

[x] T2.1 模型路由 + Fallback ✅

现状：单模型，一家 provider 抖动全平台挂（自评 ⚠️缺失）。

  • 多 provider 配置：复用 admin 已有 models 表 —— 注册多个 chat 模型即自动成主备（active=主， 其它=按序备用），无需新 admin UI；ModelConfig 加 Fallbacks 骑主配置下发（不改 bus 签名）
  • 主调用失败/超时自动切备：failoverModel（model.ToolCallingChatModel）按序切，compose/ReAct/Chat 全路径透明；调用方取消不切；备用 api_key 一并解密
  • 按任务类型/成本选模（可选，v1 跳过）；熔断器联动（failover 在 model 层、熔断在编排层，互补未整合）
  • 验收 ✅ live：active=死 ollama 主 + deepseek 备 → 任务连主拒连→自动切 deepseek→4s 完成。
  • v1 局限：Stream 仅建流同步报错时切（已回流 token 的中途失败不切）。

[x] T2.2 RAG 深度（三路做实✅；离线质量评测✅）

实测纠正：RAG 三路(向量/全文/图谱)+RRF+rerank 早已实现，之前"降级/桩"全是基建没起的假象。 基建拉起后发现真问题：对中文只有向量路在干活（hybrid: 向量=1 全文=0 图谱=0）。

  • 修全文路：Bleve 默认分词器不切中文 → text 字段改 cjk 分词器（bigram），kb/doc 用 keyword
  • 修图谱路：$q CONTAINS a.name 漏后缀错配（查"星云一号"漏实体"星云一号卫星"）→ 加查询 字符 n-gram(2..8) 双向子串匹配
  • live 验证：同查询 向量=1 全文=0 图谱=0 → 向量=1 全文=1 图谱=9，三路全活；中文混合 1/3→3/3
  • 检索质量度量（离线评测集 recall@k/MRR + 混合 vs 单路对比）—— scripts/rageval.py 可复用评测台； 引擎加 SearchByMode(vector/fulltext/graph/hybrid 纯检索)，kb_search 加 mode 参数。 live 跑分(24篇语料/16查询，含纯语义改写)：
    模式 recall@5 MRR 纯语义改写
    vector 1.00 ~0.9 4/4
    fulltext 0.88 0.77 2/4
    graph 0.75 0.59 1/4
    hybrid 1.00 ~0.9 4/4
    结论：关键词/实体查询各路都强；纯语义改写让全文/图谱漏召回，混合兜回 4/4——
    混合 = 各路上界的稳健组合，recall 始终 ≥ 最佳单路。图谱路最弱(依赖 LLM 抽取+实体匹配)。
  • 验收 ✅：三路都真出结果 + 质量可度量、混合价值量化（稳健兜底）。

[x] T2.3 Prompt 版本管理 + 输出缓存（缓存✅ + prompt版本化✅：文件覆盖+DB控制面热切换；灰度%可选）

  • 模型输出缓存：cachingModel（llm/cache.go）包在 failover 外层，缓存 Generate（非流式）， 键=模型+工具+消息哈希，默认 TTL 60s（env 可调/关）。单测全过。 ⚠️ 诚实：本平台以流式创作为主、Generate 输入每次变，真实命中率天然偏低（主要吃短窗内 逐字相同的重试/双发）；机制对、零风险，但非大成本杠杆。更大的省钱项（语义缓存/确定性工具结果 缓存）是后续。
  • prompt 版本化 v1（地基）—— shared/prompts 注册表：内置默认(随代码) + 运行期覆盖(PROMPTS_FILE)。 9 处散落硬编码 system prompt(graph抽取/eval质量/eval修订/越狱护栏/协调者/记忆对账等)收口为 prompts.Get(key)， 不重编译即可改/回滚/对比。单测(默认/覆盖/文件) + live A/B：覆盖 graph.extract→图谱抽取 2 条→0 条，向量仍正常。
  • prompt 版本化 v2（管理层）✅ —— sundynix_prompt 表(key/version/content/active) + 控制面热切换： API(GET/POST /prompts、version/activate/deactivate) → 激活某版经 NATS 广播 → dispatcher/mcp-go ApplyOverrides 热更新(镜像 model-config 控制面)。live：建版本→激活→不重启 mcp-go 图谱抽取 2→0→回滚 2； 版本留存可回溯；deactivate 回退代码默认。灰度%/审计是可选后续。
  • 验收：缓存 ✅；prompt 版本化地基 ✅(文件覆盖) + DB 控制面热切换 ✅(live)；灰度%可选。

[~] T2.4 大文件 RAG 生产化（切片/向量/队列✅；检索持久 + 治理待补）

准生产目标：几十万字文件从上传到可检索，全链路抗并发、抗崩溃、抗大体量。三段已做实并全 live 验证。

  • 存储：正文一律落 MinIO（去 <8000字内联PG 阈值，仅 MinIO 挂时回退兜底）；sundynix_doc 删死字段 MD5
  • 切片：不改（chunk.go 语义切块 500字/重叠80/句界，对大文件本就 OK）
  • 向量化：串行→embedAll 并发分批(并发4，保序)；几十万字上千块快数倍
  • 图谱：整篇喂LLM(爆上下文只抽开头)→extractGraphWindowed 窗口化(4000字/窗，封顶60，并发3)，实体按 kb+name 去重。live：16k→6窗，末段实体进图谱=全覆盖
  • 入库工作队列：裸 go runIngest → JetStream 持久队列（claim-check 暂存 + durable consumer + MaxAckPending 背压 + AckWait 30min + MaxDeliver 4 + 优雅 drain）
  • live 验证：202/80ms 异步入队；kill -9 中途崩→作业不丢→重启重投续跑完成；4次重投实体数 81 不翻倍（幂等：先删后写+MERGE）
  • 验收 ✅：切片/向量/队列三段准生产级；下列待补项按 ROI 排序见下。

待补 backlog（按 ROI 排序）

  • 🔴 P0 Bleve 落盘（瓶颈②）✅ —— 全文索引 NewMemOnly → 落盘 scorch（env BLEVE_PATH，默认 .data/bleve， 落盘失败退内存兜底；Engine.Close 刷盘释放锁）。修复"重启即丢、三路退两路"。 单测 TestBleve_PersistsAcrossReopen(写→关→重开仍可检索)；live：入库后全文=1 → 重启 mcp-go 不重入库 → 全文仍=1。
  • P1 图谱抽取单配便宜模型（瓶颈⑤）✅ —— 加 graphChat(env GRAPH_CHAT_BASE/KEY/MODEL)， graphChatClient() 优先专用模型、未配回退控制面主 chat。每篇≤60次图谱抽取走便宜模型，主对话仍用好模型。 单测 TestGraphChatClient_FallsBackToMain(回退/启用)。
  • P1 图谱封顶/窗口可配（瓶颈①）✅ —— graphMaxWindows/WindowRunes/Concurrency 改 env 可配 (GRAPH_MAX_WINDOWS 等)。单测 + live：16k(默认6窗) 设 GRAPH_MAX_WINDOWS=2 → 实抽 2 窗 + 截断告警。
  • P2 join key → file_id（瓶颈④）✅ —— 下游键从 doc名 改稳定 file_id(gateway 传 docID； Milvus/Bleve 按它键；Neo4j 关系打 file_id 属性、实体仍 kb+name 共享)。新增 kb_delete 工具
    • DELETE /api/v1/kb/doc 级联删(三库 + MinIO + PG/双链，owner 隔离)。 live：删一篇 → PG404/向量0/全文0/图谱0/孤儿实体0/MinIO空 五处皆净；重名重入库 id 稳定不孤儿。

🗄️ Tier 3 — 生产硬化 ⏸（等有真实流量再上）

  • 审计日志（敏感操作留痕）
  • NATS 集群（3 节点 + JetStream Raft）+ DB HA
  • K8s 部署 + 多副本
  • 网络安全（TLS / CORS 严格化）
  • 备份 / DR 演练

🧱 Tier 4 — 后端做实（2026-06-30 三路 Explore 审计产出）

来源：三个 Explore agent 全量扫 gateway / dispatcher+shared / mcp 后端，找出"未实现 + 可优化"。 工作量：S=1–2 天 · M=3–5 天 · L=1–2 周。一项项做，完成勾选 + 注明 live 结果。 推荐起步：T4.B（审计可溯源 + admin/overview） —— 内聚、全 M、直接喂管理端、不依赖大重构。

[~] T4.A 多租户 / RBAC / 用户治理（结构性地基，体量大）—— 已启动，方向见 SAAS_DESIGN.md

2026-07-06 用户定方向：真·多租户商业化 + 桌面端仍主产品(非Web-first)。按 SAAS_DESIGN.md P1 分阶段。

  • 增量1：租户身份地基✅（693a8f0）—— Tenant/TenantMember 表 + 注册建默认租户 + 存量回填 + TenantContext 中间件注入 tenant_id + GET /tenants/current。live 验证。未动查询隔离。
  • 增量2：核心表加 tenant_id + 统一 gorm scope 强制隔离 + 存量行回填 + 重写查询（PG 先行）| L
  • Redis/MinIO/Milvus/Neo4j 的 tenant 前缀/namespace | M
  • 真正的 RBAC：User 加 role 字段 + 角色/权限表，RequireAdmin(middleware/auth.go:46) 从白名单升级为角色校验 | M
  • 用户管理接口：列举 / 禁用 / 改角色（现仅注册/登录/查我，handler/auth.go）| M
  • 多租户：Task/Eval/KB/Agent 加 tenant_id，owner_id 之上补租户隔离边界 + 租户表/关联表（store 全表，单租户假设）| L

[x] 🔴 T4.B 审计 / 可溯源 + 管理端聚合 ✅（大头全 live；剩 HITL 明细可选）

  • GET /api/v1/admin/overview(RequireAdmin) 系统级聚合 ✅ —— 全平台用户/KB/任务/评测/模型态/prompt 覆盖/健康；概览页已切过去(5调用→2)，live 验证 users=7/kb 22/50 全平台口径。
  • audit_log 表 + 中间件 ✅ —— store.AuditLog + middleware.Audit(db) 挂管理组 + prompt 激活/撤销 + HITL 审批；只审计变更类(POST/PUT/DELETE/PATCH)，best-effort 落库不拖垮主流程；GET /admin/audit 列表(倒序翻页)。live：PUT pricing / POST deactivate 留痕，GET 不记。
  • 护栏拦截事件落库 guardrail_event ✅ —— Guardrail 中间件命中(blocked/suspect)best-effort 落库(actor/kind/reason/signals/path/ip) + GET /admin/guardrail-events；live：注入 payload→422 硬拦+事件留痕。
  • 前端「审计 & 安全」页 ✅ —— /audit(运维组)接 /admin/audit + /admin/guardrail-events：安全事件(护栏拦截/灰区)+ 操作审计(方法配色/状态码/actor/ip/时间)+ 顶栏统计 + 30s 自刷；live 验证。
  • HITL 审批决定明细落库（现审批已进 audit_log 但只有 who/when/status，无 approve/reject 决定与理由；可 enrich audit Detail 或单独表）| S ← T4.B 唯一剩项(可选小项)

[ ] T4.C 真实成本计费

  • token×单价 落库 token_usage（现仅 Redis 按天计数 TTL48h，task_handler.go:532）| L
  • 消费聚合 + 账单生成，Pricing 表与真实消费挂钩（现表建了未挂）| —（并入上条）

[ ] T4.D AI 核心深化

  • 记忆 Consolidate 层：盲目 upsert→记忆腐烂，补 Mem0 式 ADD/UPDATE/DELETE 对账（mcp-go/internal/memory/store.go，见 memory-upgrade-plan）| M
  • prompt 灰度% A/B：激活某版按小流量验证再全量（shared/prompts，现激活即全量，见 [T2.3]）| M
  • 外部接入做实：mcp-go/internal/external/apis.go:13 Call 空壳 → provider 路由 + 统一鉴权/重试/限流/审计 | M
  • mcp-py 算法层去桩：文档解析接 PaddleOCR/magic-pdf（mineru.py:11 返回空块）| M
  • 报告原生 PDF（现仅 Word，office/unioffice.go）| M

[x] T4.E 编排引擎边角 ✅（5/5 全清）

  • Map 节点错误传播 + 汇总 ✅ —— writeSection 返回 (body,err) 仅真·LLM 失败计错(预算/无模型是主动降级不算)；writeSections 汇总失败数、失败项 Body 带可见标记；mapNode 全失败→置 b.fatalErr(判 failed 非静默 done-空)、部分失败→trace+流式告警。report handleReport 同步提示部分失败。3 单测(全失败/部分精确计数/mapNode 置 fatalErr)。
  • 熔断器接回 failover（harness/circuitbreaker.go 与 llm/failover.go 未接合，可能长卡备用）| M
  • coordinator 专家超时 ✅ —— specialistTool 加 timeout(默认 specialistTimeout=3min)，InvokableRun 包 WithTimeout；超时作为"观察"跳过该专家(err=nil，lead 据其余综合，不中断协调)。2 单测(超时~50ms 跳过 / 正常不受影响)。
  • Branch else 兜底 ✅ —— branchNode 识别 default/else 边，主选择(true/false)未命中时走它；trace 明确区分「走 default / 未匹配收口结束(END) / 正常选路」，杜绝静默落 END 被误当 bug。3 断言单测(default 命中/条件真走 true/无 default 仍空)。compose 层原有 len==0→END 收口保留。
  • DSL 拓扑校验 ✅ —— gateway ParseAndAssemble 加 validateTopology：拦重复/空 id + 悬挂边(source/target 指向不存在节点)；对空图/报告任务{topic}/非标准载荷宽松放过不误伤。单测(合法/重复id/空id/悬挂边×2/空端点/空图放过) + live(悬挂边→422，合法→202)。节点-工具映射校验需工具注册表，留后续。
  • 熔断器接回 failover ✅ —— failover 加每模型熔断器(阈值3/冷却20s)：主持续失败→熔断→后续请求跳过主直连备用(省重复白试)；冷却半开探测回主、成功自动恢复(无需外部通知)。WithTools 重包共享 breakers(状态不清零，关键坑)。harness 加 NewCircuitBreakerWith 参数化构造。3 新单测(熔断跳过/WithTools共享状态/冷却恢复)。澄清：原审计"卡在备用"不准——failover 每次都重试主，真问题是宕机时每次白试主，本项修的是这个。

[ ] T4.F 健壮性 / 安全 / 性能收口（多为 S，可穿插着做）

  • 关键 DB 写失败上浮 5xx（现 best-effort 返 200，前端无感，task_handler.go:69 等）| M
  • KB 级联删「事务化」✅（2026-07-06）—— 类事务：先删依赖存储(三库/MinIO)、PG 记录最后删； 任一存储删失败→不删 PG、报错可重试(三库删幂等)，杜绝「PG 删了却在三库/MinIO 留不可删孤儿」。 milvus/bleve.deleteDoc + blob.Delete 改返 error；rag.DeleteDoc 三库全试+聚合错误(原只回 Neo4j 的错)。 live：杀 mcp-go→删→502「未删除请重试」+文档保留；mcp-go 活→删→200+清空（清场僵尸进程后验证）。
  • 预算硬顶兜底（budget.go ≤0 即无限，单任务可无限烧）| M
  • 审批 checkpoint 落盘失败重试（compose_compiler.go:323 现只 log → 任务永卡 waiting）| M
  • [~] 安全收口（部分）：
    • CORS 生产默认收紧 ✅ —— 开发期缺省仍 *(便利)；生产(APP_ENV=prod/GIN_MODE=release)未显式配 CORS_ALLOW_ORIGIN 则不发 ACAO 头(浏览器同源拦截)，逼显式配置。
    • 限流按登录用户 ✅ —— RateLimit 键改「已认证按 uid、未认证按 IP」；middleware 顺序 Auth 前置于 RateLimit。live 冒烟通过(登录/认证请求正常，dev CORS 仍 *)。
    • X-Session-ID 防伪 / 开发 JWT 密钥外置 / 输入校验补强 | S（待）
  • 性能：ListModels 去 O(N²)（admin.go:48）、KB/Agent 列表分页、报告分章检索缓存、Milvus 批量 ensure | S~M
  • 可观测：panic 进 trace span + 回写通知、TTFT/token-s/各路检索耗时指标 | M
  • 🔴 模型健康/熔断态 surface 到管理端 ✅（2026-07-06）—— harness CircuitBreaker.Snapshot() + llm.Pool.ModelHealth()(主备链每模型 provider/model/role/state/fails，同包读 failoverModel.breakers) → dispatcher 心跳带 models[] → gateway /admin/overview 独立超时 Ping dispatcher 合并 → admin 概览 「模型路由」新增「运行时链路态(实时)」逐模型状态点(🟢在线/🔴熔断中+失败数/🟡半开/单点)。 单测(Snapshot/ModelHealth 名字↔态配对) + live：配坏主→提交任务打熔断→概览 broken-demo 显示「熔断中·失败3」。
  • 配置化：切块大小 / history 轮数 / 各并发度 收口为统一可配 | S
  • 拆除 search.Hybrid 残骸 ✅ —— 该包空转(NewHybrid 返空、Query 返 nil)、构造后存进 Gateway 却从不调用(真 RAG 走 rag.Engine)。删整个 internal/search 包 + gateway/main.go 接线。build/vet 干净。（审计原说"死代码删文件"不准：它是接了线的残骸，需拆接线）

进度回顾

Tier 完成 / 总
T0 激活 2 / 2 ✅
T1 收口 T1.1 ✅ / T1.2 进行中 / T1.3 进行中
T2 深化 4 / 4 ✅
T3 硬化 ⏸ 0 / 5
T4 后端做实 0 / 6 组（A–F）

推进顺序：T0/T1.1/T2 已清。当前在 T1.2/T1.3（前端深化 + 管理端做实）。 后端下一步：T4.B（审计可溯源 + admin/overview） —— 内聚、全 M、喂管理端、不依赖大重构。 之后按价值挑：T4.D(AI 核心) / T4.E(编排边角) / T4.F(健壮性收口，可穿插) / T4.A(RBAC 大地基) / T4.C(计费)。

Reference in New Issue View Git Blame Copy Permalink