sundynix-agentix/DEPTH_ROADMAP.md

# 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，低分自动纠偏闭环几乎从没启动。
- [x] `eval.go` judge 改对抗性/rubric 打分（默认怀疑、先挑毛病再打分、给死评分基准、用满 1–5）
- [x] grounded judge 同样收紧（忠实度按编造数递减，一处编造≤2；未支持说法进 Flags）
- [x] **根因更深的数学修复**：归一 `score/5`(下限 0.2) → `(v-1)/4`(1→0)，否则 0.4*rule 底使 poor 永不可达
- [x] 校准测试：normJudge 区间 + 「流畅但跑题(judge=1)可达 poor」+ 好坏区分度
- [x] 复核阈值（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），但画布拖不出。
- [x] nodeCatalog 加 `coordinator` 节点（「多智能体协调」，indigo）+ 新 `agentList` 字段类型 + Specialist 接口
- [x] Inspector `AgentListField`：可增删的专家卡片（名/用途/系统提示词/工具逗号分隔）
- [x] dsl 校验：agentList 需 ≥1 个有名字的专家 + 名字不重复
- [x] 运行轨迹「工具调用」面板纳入专家派发（kind=agent）→ 改名「工具/专家」，专家项 indigo 标识
- [x] 后端验证：UI 同款 DSL 结构提交可跑（agents 数组经 exportDsl 透传 → parseSpecialists）
- 验收 ✅：Studio 左栏出现「多智能体协调」节点，检查器配专家卡片，导出 DSL 对齐后端；
  轨迹/工具面板能看到专家派发。（真机由用户在 wails 窗口确认）

---

## 🥈 Tier 1 — 收口 / 去税

### [x] T1.1 退役 graph.go — 消灭双引擎 ✅
现状：compose 已默认，HITL/多智能体只在 compose 上；graph.go 是逃生舱。
- [x] compose soak（默认跑数天，HITL/多智能体/评测全在其上真实运行）
- [x] 删 `runGraph`（自研拓扑解释器）+ `composeEnabled`/`EINO_COMPOSE` 开关 + `runConversation` 死代码
- [x] compose 编译失败兜底改单轮对话（不再回退 graph.go）；清掉仅 runGraph 用的 import(otel)
- [x] 保留 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 都可见可操作；前端测试覆盖核心流程。

---

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

### [x] T2.1 模型路由 + Fallback ✅
现状：单模型，一家 provider 抖动全平台挂（自评 ⚠️缺失）。
- [x] 多 provider 配置：复用 admin 已有 models 表 —— 注册多个 chat 模型即自动成主备（active=主，
  其它=按序备用），无需新 admin UI；ModelConfig 加 Fallbacks 骑主配置下发（不改 bus 签名）
- [x] 主调用失败/超时自动切备：`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`）。
- [x] 修全文路：Bleve 默认分词器不切中文 → text 字段改 cjk 分词器（bigram），kb/doc 用 keyword
- [x] 修图谱路：`$q CONTAINS a.name` 漏后缀错配（查"星云一号"漏实体"星云一号卫星"）→ 加查询
  字符 n-gram(2..8) 双向子串匹配
- [x] live 验证：同查询 `向量=1 全文=0 图谱=0` → `向量=1 全文=1 图谱=9`，三路全活；中文混合 1/3→3/3
- [x] 检索质量度量（离线评测集 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 抽取+实体匹配)。
- 验收 ✅：三路都真出结果 + 质量可度量、混合价值量化（稳健兜底）。

### [~] T2.3 Prompt 版本管理 + 输出缓存（缓存半做）
- [x] 模型输出缓存：`cachingModel`（llm/cache.go）包在 failover 外层，缓存 Generate（非流式），
  键=模型+工具+消息哈希，默认 TTL 60s（env 可调/关）。单测全过。
  ⚠️ **诚实**：本平台以流式创作为主、Generate 输入每次变，**真实命中率天然偏低**（主要吃短窗内
  逐字相同的重试/双发）；机制对、零风险，但非大成本杠杆。更大的省钱项（语义缓存/确定性工具结果
  缓存）是后续。
- [ ] prompt 版本化（可回溯/对比/灰度）—— 未做，是 T2.3 的另一半，独立较大块。
- 验收：缓存 ✅ 单测；prompt 版本切换待做。

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

#### 待补 backlog（按 ROI 排序）
- [x] **🔴 P0 Bleve 落盘**（瓶颈②）✅ —— 全文索引 `NewMemOnly` → 落盘 scorch（env `BLEVE_PATH`，默认 `.data/bleve`，
  落盘失败退内存兜底；`Engine.Close` 刷盘释放锁）。修复"重启即丢、三路退两路"。
  单测 `TestBleve_PersistsAcrossReopen`(写→关→重开仍可检索)；**live：入库后全文=1 → 重启 mcp-go 不重入库 → 全文仍=1**。
- [x] **P1 图谱抽取单配便宜模型**（瓶颈⑤）✅ —— 加 `graphChat`(env `GRAPH_CHAT_BASE/KEY/MODEL`)，
  `graphChatClient()` 优先专用模型、未配回退控制面主 chat。每篇≤60次图谱抽取走便宜模型，主对话仍用好模型。
  单测 `TestGraphChatClient_FallsBackToMain`(回退/启用)。
- [x] **P1 图谱封顶/窗口可配**（瓶颈①）✅ —— `graphMaxWindows/WindowRunes/Concurrency` 改 env 可配
  (`GRAPH_MAX_WINDOWS` 等)。单测 + **live：16k(默认6窗) 设 GRAPH_MAX_WINDOWS=2 → 实抽 2 窗 + 截断告警**。
- [x] **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 | 完成 / 总 |
|---|---|
| T0 激活 | 2 / 2 ✅ |
| T1 收口 | 1 / 2 |
| T2 深化 | 3 / 4 |
| T3 硬化 ⏸ | 0 / 5 |

> 推进顺序：T0.1 → T0.2 → T1.1 → T1.2 → T2.1 → T2.4(三段✅) → **T2.4 P0 Bleve 落盘** → … → （T3 按需）。