feat: 案例记忆（Memory Case）— SRE/AIOps Agent 跨会话故障排查经验记忆

[niiish32x]

feat: 案例记忆（Memory Case）— SRE/AIOps Agent 跨会话故障排查经验记忆

Summary

为 OpenDerisk Agent 提供跨会话的故障案例记忆能力。Agent 排查故障前自动检索历史相似案例获得启发，排查后将结论回写积累经验。技术上是 MySQL FULLTEXT + ChromaDB 向量语义检索的混合系统，通过 MCP 内置插件以 4 个 LLM 可调用工具暴露给 Agent，以 零侵入可插拔 方式集成到任意 Agent 实现。

一句话

「每次排障前先看一眼历史上类似的坑，排完把经验写回去，下次别人遇到就少走弯路。」

核心设计

1. 零侵入可插拔架构

Agent 层完全不 import derisk-ext，通过三层解耦实现：

• ResourceResolver：启动时 derisk-ext 注册 tool(memory_case) → MemoryCaseToolPack 映射
• ConversationScopeHooks：core 定义 hook 协议，ext 实现，serve 装配。Agent 只调 bind_conversation_scope_for_agent(app_code, conv_id)
• MCP Service：依赖注入构建 DAO + 向量索引 + 配置

graph TB
    subgraph derisk_core["derisk-core (Agent 层)"]
        Agent["BAIZE / ReAct / Core v2 Agent"]
        Hooks["ConversationScopeHooks<br/>(hook 协议定义)"]
        Resolver["ResourceResolver<br/>(注册入口)"]
    end

    subgraph derisk_ext["derisk-ext (插件实现)"]
        ToolPack["MemoryCaseToolPack<br/>4 个工具注册 + scope 注入"]
        Service["MemoryCasePluginService<br/>search / upsert / feedback / render"]
        DAO["MemoryCaseDao<br/>(SQLAlchemy)"]
        Vector["CandidateCaseVectorIndex<br/>(ChromaDB, lazy init)"]
    end

    subgraph derisk_serve["derisk-serve (装配层)"]
        MCP["McpService.init_app()<br/>依赖注入 + 注册"]
        Bind["bind_memory_case_scope_for_agent()"]
    end

    Agent -->|"bind_conversation_scope_for_agent(app_code, conv_id)"| Hooks
    Hooks -.->|"遍历已注册 hook"| Bind
    Bind -->|"ContextVar.set(scope)"| ToolPack
    Agent -->|"tool_call"| Resolver
    Resolver -->|"tool(memory_case)"| ToolPack
    ToolPack --> Service
    Service --> DAO
    Service --> Vector
    MCP --> Service

    style derisk_core fill:#e1f5fe,stroke:#0288d1
    style derisk_ext fill:#fff3e0,stroke:#f57c00
    style derisk_serve fill:#e8f5e9,stroke:#388e3c

Loading

关键：Agent 代码中不出现 from derisk_ext.plugin.memory_case import ...，插件替换/卸载对 Agent 完全透明。

2. 混合检索：DB 全文 + 向量语义

graph TD
    Query["memory_case_search('Pod OOM JVM 堆内存')"]
    
    Query --> DB["Step 1: MySQL FULLTEXT<br/>5 列索引"]
    Query --> Vec["Step 2: ChromaDB 向量检索"]
    
    DB --> DBok{"成功?"}
    DBok -->|"是"| DBResult["MATCH ... AGAINST<br/>NATURAL LANGUAGE MODE"]
    DBok -->|"否 (err 1191)"| Fallback["LIKE '%query%' 回退"]
    
    Vec --> VecOk{"ChromaDB 可用?"}
    VecOk -->|"是"| VecResult["embedding(query) →<br/>语义相似度搜索"]
    VecOk -->|"否"| Degraded["degraded: true<br/>不阻塞主路径"]
    
    DBResult --> Merge["Step 3: 合并去重"]
    Fallback --> Merge
    VecResult --> Merge
    Degraded --> Merge
    
    Merge --> Rank["Wilson 分数排序<br/>+ scope 感知<br/>+ 时间衰减"]
    Rank --> Filter["过滤: REJECTED<br/>+ confidence < 0.5"]
    Filter --> Summary["返回轻量摘要<br/>~500 字符/条"]
    
    Summary --> Backfill["懒回填: DB 命中但<br/>向量缺失的案例<br/>自动补入 ChromaDB"]

    style DB fill:#e3f2fd,stroke:#1565c0
    style Vec fill:#fce4ec,stroke:#c62828
    style Merge fill:#fff3e0,stroke:#ef6c00
    style Summary fill:#e8f5e9,stroke:#2e7d32

Loading

向量在系统中的定位：DB 全文检索是主路径，向量是语义补充。向量不可用时服务降级不中断。这与通用 RAG 系统中以向量为主的模式不同——SRE 场景下精确的关键词匹配（OOM、GC、线程池）往往比语义相似度更可靠。

3. 两步交互：Search 摘要发现 → Render 按需深入

memory_case_search 只返回 ~500 字符的摘要（不含完整 markdown_summary 和 diagnosis），Agent 快速扫读后选中相关案例，再用 memory_case_render 按 case_id 加载完整 Markdown。

设计理由：5 条案例全量返回约 12,500 字符，Agent 容易被大量文本淹没。摘要化后只需 ~2,500 字符即可完成初筛，再用 render 按需深入 1-2 条（~6,500 字符）。render 时自动附带 similar_cases 关联案例，形成「发现 → 深入 → 展开关联」的三步信息获取。

Search 摘要字段（_to_summary()）：

字段	说明
symptom_summary	完整，Agent 靠它判断是否同一类故障
diagnosis_preview	前 300 字，足够判断排查思路是否相关
diagnosis_len	数字，让 Agent 知道全量多大
root_cause	完整，一句话信号密度最高
resolution	完整，Agent 判断方案是否可复用
confidence + lifecycle	判断可信度
feedback_h / feedback_u / feedback_cv_count	反馈统计，辅助判断经验可靠性
similar_count	数字，判断案例贫瘠还是丰富
markdown_summary	❌ 砍掉（最大头），用 render 按需加载
全量 diagnosis	❌ 砍掉，只给 300 字 preview

4. 三层案例关系自动关联

写入案例时自动发现语义相似案例，层层过滤防止文本相似但排查路径不同的案例被误关联：

graph TD
    NewCase["新写入案例<br/>upsert() 后触发"]
    
    NewCase --> L1["Layer 1: 分段加权向量粗筛 ✅"]
    
    L1 --> L1S["symptom 段 (权重 0.1)<br/>ChromaDB 独立搜索"]
    L1 --> L1D["diagnosis 段 (权重 0.5)<br/>ChromaDB 独立搜索"]
    L1 --> L1R["root_cause 段 (权重 0.4)<br/>ChromaDB 独立搜索"]
    
    L1S --> Merge["加权合并分数<br/>symptom×0.1 + diagnosis×0.5 + root_cause×0.4"]
    L1D --> Merge
    L1R --> Merge
    
    Merge --> Filter1{"weighted >= 0.6?"}
    Filter1 -->|"否"| Drop["丢弃"]
    Filter1 -->|"是"| L2
    
    L2["Layer 2: 结构化交叉验证 ✅"]
    L2 --> Check{"failure_layer 一致?<br/>runtime 一致?<br/>related_services 有交集?"}
    
    Check -->|"全部一致"| StructOK["struct_match: true"]
    Check -->|"字段缺失"| StructPass["struct_match: false<br/>(缺字段不惩罚)"]
    Check -->|"明确冲突"| StructFail["struct_match: false<br/>阻断误关联"]
    
    StructOK --> L3
    StructPass --> L3
    StructFail --> MarkSurface["标记: surface_similar<br/>仅文本像，排查路径不同"]
    
    L3["Layer 3: 关系类型分类"]
    L3 --> RootHigh{"root_cause >= 0.8<br/>AND struct_match?"}
    RootHigh -->|"是"| SameRoot["same_root_cause"]
    RootHigh -->|"否"| DiagHigh{"diagnosis >= 0.7<br/>AND struct_match?"}
    DiagHigh -->|"是"| SimDiag["similar_diagnosis"]
    DiagHigh -->|"否"| SurfSim["surface_similar"]

    style L1 fill:#e3f2fd,stroke:#1565c0
    style L2 fill:#fff3e0,stroke:#ef6c00
    style L3 fill:#f3e5f5,stroke:#7b1fa2
    style SameRoot fill:#c8e6c9,stroke:#2e7d32
    style SimDiag fill:#c8e6c9,stroke:#2e7d32
    style MarkSurface fill:#ffcdd2,stroke:#c62828
    style SurfSim fill:#ffcdd2,stroke:#c62828

Loading

具体案例：为什么需要 Layer 2 结构性验证？

case-A: order-svc Pod OOMKilled
  → JVM 堆配置 512M 过小 → 调大 -Xmx → 解决
  failure_layer: jvm, runtime: java, related_services: [order-svc]

case-B: trade-svc Pod OOMKilled
  → 下游 risk-engine 内存泄漏，请求堆积 → 升级 risk-engine → 解决
  failure_layer: application, runtime: go, related_services: [risk-engine]

Layer 1 向量得分: 0.89（反复出现 "Pod / OOMKilled / JVM / 内存 / GC"）
Layer 2 交叉验证: failure_layer 不同(jvm≠application) + runtime 不同(java≠go)
                 + related_services 无交集 → struct_match: false
最终判定: surface_similar — 文本像，排查路径完全不同

5. Structured Feedback + Wilson 分数排序

Feedback 以结构化方式记录在三层 scope 中：

"fb": {
  "global":           {"h": 8, "u": 2, "ts": "...", "cv": ["conv-a", "conv-c"]},
  "by_app":           {"order-svc": {"h": 6, "u": 0, "ts": "..."}},
  "by_app_env":       {"order-svc:production": {"h": 5, "u": 0, "ts": "..."}}
}

排序公式：

rank_score = base × exp(-λ × days)

base = weight × wilson_score(h, total) + (1-weight) × confidence
       ↑                                       ↑
   经验分数（样本越多越信任）                LLM 先验（feedback 不足时兜底）

weight = min(1.0, total / 10)

Wilson 分数效果：样本量越小，下界越保守：

helpful/total	简单比例	Wilson 下界	含义
2/2	1.00	0.34	样本太小，不可信
8/10	0.80	0.49	有争议，压低
15/15	1.00	0.82	大量验证，高置信

Scope 感知的三层降级：同一案例在不同场景下自动差异化排名。

graph LR
    Search["Agent 搜索<br/>app_code=order-svc<br/>env=production"]
    
    Search --> L1["查 fb.by_app_env<br/>['order-svc:production']"]
    L1 --> L1Check{"total >= 3?"}
    L1Check -->|"是"| Use1["用这层的 Wilson 分数"]
    L1Check -->|"不足"| L2
    
    L2["降级: fb.by_app<br/>['order-svc']"]
    L2 --> L2Check{"total >= 3?"}
    L2Check -->|"是"| Use2["用这层的 Wilson 分数"]
    L2Check -->|"不足"| L3
    
    L3["降级: fb.global"]
    L3 --> L3Check{"total > 0?"}
    L3Check -->|"是"| Use3["用这层的 Wilson 分数"]
    L3Check -->|"无"| Fallback["兜底: LLM confidence 先验"]

    style Use1 fill:#c8e6c9,stroke:#2e7d32
    style Use2 fill:#fff9c4,stroke:#f9a825
    style Use3 fill:#fff3e0,stroke:#ef6c00
    style Fallback fill:#ffcdd2,stroke:#c62828

Loading

DRAFT → ACCEPTED 门槛：

需同时满足:
  confidence >= 0.8
  AND fb.global.h >= 2          (至少 2 次 helpful)
  AND fb.global.cv 包含非 source_conv_id 的会话  (跨会话独立验证)

防止同一轮排查中 Agent 自产自评。同会话 feedback 只调 confidence 不改 lifecycle。

6. 零侵入 Scope 注入

Agent 完全不感知 scope 逻辑。三级优先级：

1. LLM 显式传入的 scope（最高优先）
2. ContextVar 中的 scope（Agent 构建时 bind 的 app_code / conv_id 自动注入）
3. 兜底 "default"（通配，不过滤）

inject_memory_scope() 是 scope 注入的唯一入口，被 MCP 服务路径和 ToolPack 路径共享，逻辑不重复。

写入时自动将 scope 中的 app_code / environment 注入 case_context，conv_id 注入 source_conv_id，LLM 无需手动填写。

文件结构

packages/derisk-ext/src/derisk_ext/plugin/memory_case/
├── __init__.py             # 公共 API 导出
├── models.py               # CandidateCase, lifecycle, FeedbackStats, wilson_score
├── service.py              # 核心服务：search / upsert / feedback / render
├── sqlalchemy_dao.py       # MySQL/SQLite 持久化 (FULLTEXT + LIKE fallback)
├── vector_index.py         # ChromaDB 向量索引 (lazy init + 优雅降级)
├── case_context.py         # Scope 过滤 + 结构化交叉验证
├── markdown.py             # Markdown 渲染
├── tool_pack.py            # Agent ToolPack 适配 + scope 注入
├── integration.py          # ResourceResolver 注册
├── scope_binding.py        # ContextVar scope 绑定
├── plugin_resolver.py      # 插件解析器
├── resource_resolve.py     # 资源解析
├── dao_protocol.py         # DAO 抽象协议
├── tests/
│   ├── test_memory_case_service.py  # 核心服务测试 (38 个)
│   ├── test_dao_upsert.py           # DAO 测试
│   └── test_vector_search.py        # 向量检索测试
└── skill/memory_case_agent/
    └── SKILL.md             # Agent 使用技能 (v2.0)

# 跨包集成点
packages/derisk-core/       # ConversationScopeHooks, ResourceResolver
packages/derisk-serve/       # MCP Service, Agent scope binding
packages/derisk-app/         # Feature plugin 装配

---