# Clavue v8.12.0 — Release Notes

**发布日期**:2026-05-18
**npm**:`clavue@8.12.0`
**GitHub**:https://github.com/mycode699/clavue/releases/tag/v8.12.0
**升级命令**:

```bash
npm install -g clavue@8.12.0
# 或一次性:
npx -y clavue@8.12.0
```

---

## TL;DR

8.12.0 把上下文压缩的三条故障路径(full / sessionMemory / emergency)的"模型看到什么"统一到一个可注入的 **Pinned Context** snapshot,新增可选的 **Micro-Reflection** 后采样钩子,并为后续的 **cache-aware boundary v2** 出了完整设计文档(`docs/CONTEXT-ARCHITECTURE-V2.md`)。

User-visible 行为变化仅在两个开关启用时出现:

- emergency truncate 触发时,如果用户在最近的轮次里产生了 micro-reflection 记录,这些"刚刚做了什么 / 学到什么 / 下一步"现在会写进 emergency summary 段。
- `ENABLE_CLAVUE_MICRO_REFLECTION=1` 之后,主 REPL 在自然停顿点(无 tool_use 的 turn、token delta ≥ 3K、tool-call delta ≥ 3)用 small/fast model 写一行 JSONL 反思到 `<sessionMemoryDir>/reflections.jsonl`。

测试基线 v11 1475 pass / 0 fail / 6 skipped → v12 **1489 pass / 0 fail / 6 skipped**(+14 新测试,全部针对纯逻辑层)。

升级风险:**极低**。Reflection hook 默认 OFF,emergency 路径在文件不存在时安静跳过反思段,行为退化到 v11。

---

## 1. P0 — Pinned Context tier

三条 compact 路径之前各自维护 plan / todos / recent_user_requests 的拉取与渲染。新增统一 snapshot:

- `src/services/pinnedContext/pinnedContextCore.ts` — 纯逻辑(无 fs,无 imports of `messages.js`),便于 `node --test` 直跑。
- `src/services/pinnedContext/pinnedContext.ts` — production wiring,提供 `buildPinnedContextSync`(emergency 路径用,零 await)和 `buildPinnedContext`(full/sessionMemory 路径用,async 读 V2 tasks)。
- `src/services/pinnedContext/renderPinned.ts` — 渲染为 markdown 块,emergency summary 段落顺序固定:reflection → plan → todos → sessionMemoryExcerpt。

emergency 路径已接入(`emergencyTruncateWiring.ts`),其余两条 full compact 路径维持原数据源(`getPlan` / appState todos)以避免引入循环 import,只在 P2 v2 boundary 上线后再统一切换。

P0 测试:`tests/pinned-context.test.mjs`(10 个),全过。

## 2. P1 — Micro-Reflection 钩子

- `src/services/SessionMemory/microReflectionStore.ts` — 纯逻辑:`buildReflection` / `serializeReflection` / `parseReflectionsLog` / `renderReflectionsExcerpt`。Field 上限 800 字符,JSONL 一行一条。
- `src/services/SessionMemory/microReflectionWiring.ts` — 文件 I/O。`appendReflection()` 异步追加,`readRecentReflectionsExcerptSync()` 在 critical heap 下同步读末尾 16KB(O(1) 无视会话长度)。
- `src/services/SessionMemory/microReflectionHookCore.ts` — 纯节流逻辑 + LLM 输出解析(容忍 markdown fence、前置 prose)。
- `src/services/SessionMemory/microReflectionHook.ts` — `registerPostSamplingHook` 接入,gated by `ENABLE_CLAVUE_MICRO_REFLECTION` env。仅在 `repl_main_thread` querySource 上运行,15s 硬超时,失败静默退出。

emergency 路径同步读 reflection 段已上线,即便 hook 未启用,只要文件存在(可由 SDK / 测试预写),emergency summary 就会带这一段。

P1 测试:`tests/micro-reflection.test.mjs`(10 个)+ `tests/micro-reflection-hook.test.mjs`(14 个),全过。

## 3. P2 — Cache-aware boundary v2(设计 only)

`docs/CONTEXT-ARCHITECTURE-V2.md` 全文落地。核心论点:今天 4 层 compact 都在 byte 0 插 boundary marker,prompt cache 命中率长会话观测 < 20%。v2 把 boundary 改为**逻辑范围标记 + append-only archived_history_blob**,system prompt 与早期消息保留原 byte offset,理论 cache hit rate 提升到 ≥ 70%。

文档涵盖:目标 prompt shape、boundary protocol 演进(`schemaVersion: 'v2'` + `archivedRange` + `summaryBlobOffset`)、四条 compact 路径的逐条改动清单、disk format 兼容策略(新增 `<sessionDir>/archive.md`,旧会话 fallback)、上线前必收的 4 个 baseline 指标、5 类风险、4 阶段 phased rollout。

**不实施**,等 Phase A 收完一周真实流量后再决策。

## 4. 测试与回归

```
node --test tests/pinned-context.test.mjs \
            tests/micro-reflection.test.mjs \
            tests/micro-reflection-hook.test.mjs \
            tests/emergency-truncate.test.mjs \
            tests/heap-soft-block-contract.test.mjs
# 43 pass / 0 fail
```

全测:`npm test` → **1489 pass / 0 fail / 6 skipped**(v11 基线 1475 + 14 新测试)。

## 5. 升级建议

- 默认升级即可,**无配置变更**。
- 想试 reflection,设 `ENABLE_CLAVUE_MICRO_REFLECTION=1`,观察 `<sessionMemoryDir>/reflections.jsonl` 是否在自然停顿点出现新行。
- emergency truncate 触发后查看新 summary 是否带 "Recent reflections" 段。
- 撤回:无需任何操作,关掉 env 变量即恢复 v11 行为。
