feat: implement Context Intelligence v2 module

[MISTLXC]

目标

实现 Context Intelligence v2 模块（vip.mate.context.intelligence），通过动态探测每个 (provider, model) 的真实上下文窗口，替代原先硬编码的 128K 静态配置，优化历史消息裁剪与 token 预算分配。

核心目标：

• 自动学习每个模型的 effective context window，按需分配 token 预算
• 信号采集与推理主线程解耦，零阻塞
• 三层降级保证：动态 snapshot → yml 静态配置 → 128K 硬编码兜底
• 零侵入扩展：新增感知维度只需加 @EventListener，ReasoningNode 不变

---

v1 复盘 → v2 重构

v1 问题清单（附录 A）

v1 vip.mate.context.adaptive 模块存在 5 个 Bug、4 个死代码、2 个风格问题：

#	v1 问题	影响
Bug 1	loopContextWindowTokens 参数顺序反转	窗口查询错位
死代码 1-4	7 个 Properties 字段 / actualModelStates / ModelFamily.contextProfile / MIN_OBSERVATION_HOURS 均未使用	代码膨胀

v1 架构问题

维度	v1 问题	v2 改进
通信模式	同步直调（ReasoningNode → Monitor → Tracker）	事件驱动（ApplicationEventPublisher + @eventlistener）
信号覆盖	仅 tool-call 路径（遗漏 final-answer）	每次 LLM 调用统一发事件，全覆盖
组件耦合	ReasoningNode 直接依赖 3 层组件	仅依赖 ApplicationEventPublisher

---

v2 机制

架构：EDA + CQRS

ReasoningNode（推理主线程）
    │
    ├─ 读路径（sync, lock-free, 每次 ReAct 循环）
    │   EnvSnapshotStore.get() → TokenBudgetPlanner.plan() → LoopBudgetConfig → LoopMessageBudgeter
    │
    └─ 写路径（event publish, O(1) non-blocking）
        ApplicationEventPublisher.publishEvent(LlmSuccessSignal / LlmOverflowSignal)
            │
            ▼
        ContextSignalProcessor（@EventListener）
            ├─ onSuccess: @Async（signalExecutor 线程池）
            └─ onOverflow: sync（确保 PTL 重试前 confidenceUpper 已更新）

核心设计原则

1. EDA 事件驱动：信号采集与状态更新通过 Spring 事件总线异步解耦，推理主线程零阻塞
2. CQRS 读写分离：写路径（事件消费 + 状态机更新）异步；读路径（snapshot 查询 + 预算规划）同步无锁
3. 调整机制与环境感知分离：WindowProbe 状态机（上探激进/下探保守）与多样性检测/压力推断是独立关注点
4. 三层降级：动态 snapshot → yml 静态配置 → 硬编码 fallback，任一层故障不阻断推理
5. 零侵入扩展：新增感知维度只需监听器内加分支或新增 @EventListener

三层降级（§8.1）

层级	触发条件	数据来源
Tier 1	EnvSnapshot 有效（effectiveWindow > 0）	动态探测值 + 多因子预算规划

状态机（WindowProbe.Phase）

COLD → PROBING → BINARY_SEARCH → STABLE
                                    ↓
                               DEGRADED（压力升级时降级）

• COLD：冷启动，用 32K seed
• PROBING：采样填满 SAMPLE_SIZE/2 时上探
• BINARY_SEARCH：二分收敛（收敛阈值 10%）
• STABLE：稳定窗口，闲置 30 分钟后重探
• DEGRADED：压力升级时降级（连续成功 5 次恢复一级）

---

数据流

6 条核心数据流

数据流	方向	同步/异步	触发频率
信号采集	ReasoningNode → Event Bus	sync publish, O(1)	每次 LLM 调用

成功处理流程（异步，7 步）

1. WindowProbeRegistry.recordSuccess → 返回 ProbeUpdate(snapshot, previousPhase)
2. BackendDiversityRegistry.recordSuccess — 多样性检测
3. PressureInferencer.recordSuccess — 压力推断（连续成功降级）
4. 计算 safeWindow（多样性 P10）
5. EnvSnapshotStore.refreshIfChanged — 条件 CAS（仅关键字段变化时刷新）
6. 条件 DB 持久化（phase 变化或首次成功时）
7. PersistRetryQueue.retryOnce — 重试之前失败的持久化

溢出处理流程（同步，5 步）

1. WindowProbeRegistry.recordOverflow — 窗口收缩（overflowShrinkRatio = 0.85）
2. BackendDiversityRegistry.recordOverflow — 修复 v1 Bug 2
3. PressureInferencer.recordOverflow — 压力升级
4. EnvSnapshotStore.refreshIfChanged — 溢出必然导致窗口收缩，必刷新
5. WindowStateRepository.persist — 同步 DB 写入（溢出是低频事件）

预算规划流程（读路径，4 步）

1. 确定 base window：EnvSnapshot.effectiveWindow
2. 应用 P10 多样性天花板：min(effectiveWindow, safeWindow)（仅读取，不修改状态机）
3. 压力因子比例调整：NORMAL 0.60 / ELEVATED 0.70 / HIGH 0.80 / CRITICAL 0.85
4. 计算预算：historyBudget = available × historyRatio，keepTail = historyBudget × keepTailRatio

---

v2 组件清单

19 个组件，9 个子包

子包	组件	职责
event	LlmSuccessSignal	成功信号事件（异步消费）
event	LlmOverflowSignal	溢出信号事件（同步消费）
listener	ContextSignalProcessor	信号处理器（写路径入口，@eventlistener）
snapshot	EnvSnapshotStore	快照缓存（ConcurrentHashMap + AtomicReference）
probe	WindowProbeRegistry	多模型探测注册表（ConcurrentHashMap + compute 原子操作）
perception	BackendDiversityTracker	后端多样性检测（per-model 实例，P10 安全窗口）
budget	TokenBudgetTrace	决策追踪 record（监控/调试用）
metrics	ContextIntelMetrics	可观测指标网关（9 项 Micrometer 指标）
root	ContextIntelligenceAutoConfiguration	自动配置

v1 → v2 组件映射

v1 组件	v2 组件	说明
AdaptiveContextTracker	WindowProbeRegistry + ContextSignalProcessor	拆分为注册表 + 处理器

---

改动清单

新增文件（28 个）

• v2 模块：24 个 Java 文件（vip.mate.context.intelligence.**）
• 数据库迁移：3 个 SQL（V161__mate_model_context_state.sql，h2/mysql/kingbase 三方言）
• 设计文档：docs/context-intelligence-design -1.md

修改文件（7 个）

文件	改动
ReasoningNode.java	三层 fallback 预算配置 + LlmSuccessSignal/LlmOverflowSignal 信号发布

---

验证结果

验证项	结果
mvn compile（JDK 21）	BUILD SUCCESS，1242 源文件编译通过
代码注释英文化	30 个文件，97 处翻译，0 中文残留

---

可观测指标（9 项）

指标	类型	Tags	说明
context.intel.signal.process.duration	Timer	type=success|overflow	信号处理耗时

---

配置说明

mateclaw:
  context:
    intelligence:
      enabled: true                  # 模块总开关
      metrics:
        enabled: true                # 指标监控开关
      # 以下为可选项（含默认值）
      budget:
        normal-history-ratio: 0.60   # 正常压力下历史消息占比
        elevated-history-ratio: 0.70
        high-history-ratio: 0.80
        critical-history-ratio: 0.85
        output-reserve-ratio: 0.15   # 输出预留比例
        keep-tail-ratio: 0.60        # 尾部保留比例
      probe:
        sample-size: 20              # 采样数
        overflow-shrink-ratio: 0.85  # 溢出收缩比例
        binary-convergence: 0.10     # 二分收敛阈值
        stale-reprobe-ms: 1800000    # 闲置重探间隔（30 分钟）

---

已知限制

1. 冷启动期：首次调用时 snapshot 为空，走 legacy fallback，需几轮对话后动态预算才生效
2. 不调整 max_output_tokens：v2 仅优化输入侧（历史消息裁剪），输出上限仍为静态 16384
3. legacy 比例不可配置：TokenBudget.legacy() 硬编码 0.60/0.40/0.60/0.36（有意设计，保证 v1 兼容和平滑预热）

---

后续待办

• P1：动态 max_output_tokens（接入 buildChatOptions()）
• P2：冷启动优化（预填 EnvSnapshotStore from DB）
• P4：硬编码值可配置化（minTailMessages、targetMaxMessages 等）
• 长期：多模型差异化配置

[mateaix]

感谢这个 PR，能看出你在上下文预算这块投入了大量思考 👏 —— 把硬编码的 128K 静态窗口换成按 (provider, model) 动态探测、用事件驱动把信号采集与推理主线程解耦（EDA + CQRS）、并保留多层降级兜底，这个方向是有价值的。

不过坦诚地说，以目前的形态还不能直接合并，需要先做一些返工。下面按优先级列一下，方便你迭代：

1. 默认关闭（最重要）

application.yml 里 context.intelligence.enabled: true 让这个新模块对所有部署默认生效，并直接接入 ReasoningNode 的 token 预算与历史裁剪 —— 这是 agent 运行的核心路径。一个全新模块在充分验证前应当 opt-in：默认 enabled: false，由使用者显式开启做灰度。

2. 补测试

模块有约 2900 行，包含事件采集、CQRS 读写分离、异步执行器、retry queue、窗口探测等并发逻辑，但目前没有任何测试。核心路径建议至少覆盖：

• TokenBudgetPlanner.plan() 的预算计算与 P10 clamp；
• 三层降级（动态 snapshot → yml → 128K 兜底）在 snapshot 缺失 / 异常时的行为；
• 信号事件（success / overflow）的采集与最终落库；
• ReasoningNode 接入后，snapshot 不可用时回退到原 loopContextWindowTokens() 的等价性。

这样评审才能验证正确性，也能防止后续回归。

3. 拆分 PR

2890 行单 commit 很难做严肃审查。如果能拆成几个递进的 PR（例如：① 基础设施 + 表结构 → ② 事件采集 + 持久化 → ③ 预算规划器 → ④ ReasoningNode 接入），每个都能独立审查 / 测试 / 回滚，整体合并会顺畅很多。

4. Flyway 版本号 V161 撞号

V161 已被另一个待合并的 PR 占用（dev 当前最高是 V160）。请把这三处迁移改成 V162（h2 / mysql / kingbase 三个目录同步改名 + 更新文件头注释），否则启动会报 Found more than one migration with version 161。

5. 注释自洽，移除对外部设计文档的引用

代码和 application.yml 里有不少 design doc §10.1 / §5.5 / §C.9 这类指向外部设计文档的引用。本仓库的约定是代码注释应当自洽地说明做什么、为什么，不依赖读者去翻外部规划文档（章节号也会随文档演进而失效）。建议把这些 §X 引用改写成对当下逻辑的客观描述。

6. PR 描述里的 v1 对比

描述用了较大篇幅复盘 vip.mate.context.adaptive（v1）的 bug，但当前 dev 分支里并不存在这个模块（全仓库 grep 无命中），这让评审难以对照。如果 v1 是你在其他分支的工作，能否说明一下来源；或者直接精简掉这部分对比，聚焦 v2 本身的设计与权衡。

---

架构出发点我很认可，期待你按上面调整后再提一版~ 有任何疑问欢迎继续讨论 🙏