# Clavue v8.13.6 — Website / Marketing Update Pack

**Audience**：clavue.com 的内容维护者 / marketing。
**目标**：把 8.13.6 的 user-visible 变化更新到首页、changelog、docs 三个地方。
**约束**：本仓库不含网站源码 UI；这份文档把所有"可粘"内容打包好。

---

## 0. 本版定位

8.13.6 是 **UX 修复版本**，user-visible 变化集中在一处：

- `/resume` 不再把 `/compact` 的合法行为误报为数据丢失
- 警告（warning）只在真有 user/assistant 消息无法重建到 chain 时才出现
- 真出问题时的提示更明确（具体丢了几条、是哪种类型）

适合在 changelog 写一条，可以发推。**不需要**改首页 hero。

---

## 1. 首页改动建议

### 1.1 顶部 banner / 版本号

只更新版本号字段：

> Latest stable: **v8.13.6** — `/resume` no longer cries wolf when `/compact` did its job.

CTA 链接到 changelog 锚点 `#8-13-6`。

### 1.2 "新功能 / 新修复" 卡片（建议加 1 张）

**卡：`/resume` 的恐慌警告下线了**
- 标题：Resume warnings now mean what they say
- 副标题：8.13.5 之前，凡是 `/resume` 加载的消息数比 checkpoint 少，都会弹出 `Resume loaded N of M (-K)` 警告。但其中绝大多数是 `/compact` 主动剪裁——磁盘上的 transcript 完整无缺。8.13.6 把 surface 拆成 4 类（`consistent` / `compacted` / `lost` / `reconstructed`），只有真正的 `lost`（磁盘有 user/assistant uuid 没进 chain）才走 warning。其他三类降级为 info 或不显示。
- 链接：`/docs/changelog#8-13-6`

---

## 2. Changelog 页（/changelog 或 /releases）

把以下 markdown 块直接 append 到 changelog 页顶部：

```markdown
## v8.13.6 — 2026-05-20

### Fixes
- **`/resume` 不再把 `/compact` 误报为数据丢失**：8.13.5 之前，
  `/resume` 加载的链长度只要小于写入端 checkpoint 的 `messageCount`
  就会弹出 `Resume loaded N of M messages (-K)` 警告。但 `/compact`
  主动剪裁旧轮次本来就会让两者不等——磁盘 transcript 是完整的。
  8.13.6 把 consistency 分析拆成 4 类（`consistent` / `compacted`
  / `lost` / `reconstructed`），只有真有 user/assistant uuid 在磁盘
  上但没重建进 chain 时才走 warning，其他降级为 info 或不显示。
- **真丢消息时的提示更具体**：`lost` 类提示会写明具体丢了几条
  user/assistant 消息，并提示 transcript 文件本身完整，可以用
  `/branches` 找回 chain-walk orphan。

### Internals
- 新增 `src/utils/resumeConsistency.ts` —— pure 分析函数，从
  `sessionStorage.ts` 拆出来便于直接 unit-test（旧文件依赖 fs、
  analytics、Bun-bundle stub，node test runner 跑不了）。
- `loadFullLog` 在 chain 构建时就把 `consistencyDelta` 计算好挂到
  `LogOption` 上，下游 `/resume` 路径直接读取，不再二次计算。
- `tengu_resume_consistency_delta` 事件新增 3 个字段：`reason`、
  `lost_user_assistant_count`、`compact_boundary_count`，便于
  分类回看。

### Tests
- 新增 `tests/resume-consistency.test.mjs` —— 9 个单测，覆盖每种
  `reason` 分类、lost-dominates-compacted 的优先级、sidechain 排除、
  legacy 无 fullMessageMap 的回退、以及两种返回 `null` 的边界。
- 测试基线 1530 → 1559 tests / 1553 pass / 6 skipped / 0 fail。

### No Breaking Changes
- 没有新 env / flag / 命令
- 没有破坏性变更
- 旧版会话 / 配置 / providers 全部继续工作

升级：

\`\`\`bash
npm install -g clavue@8.13.6
\`\`\`

完整发布说明：[docs/clavue-v8.13.6-release-notes.md](https://github.com/mycode699/clavue/blob/v8.13.6/docs/clavue-v8.13.6-release-notes.md)
```

---

## 3. Docs 页改动建议

### 3.1 `/resume` 文档

如果站点 docs 有 `/resume` 单独的文档页，加一段说明 4 种分类，并贴示例：

**Before (≤ 8.13.5)**

```
⚠ Resume loaded 3 of 12 messages (-9)
```

**After (≥ 8.13.6)**

```
ℹ Resume loaded 3 of 12 messages — earlier turns were merged by /compact
  (transcript on disk is intact).
```

真有损失的情况下会变成：

```
⚠ Resume loaded 4 of 6 messages — 2 user/assistant messages on disk
  could not be reconstructed into the chain.
```

### 3.2 Telemetry 字段表

如果站点 docs 有 `tengu_resume_consistency_delta` 字段说明，需要补 3 个新字段：

| 字段 | 类型 | 含义 |
|---|---|---|
| `reason` | `'consistent' \| 'compacted' \| 'lost' \| 'reconstructed'` | 本次 resume 的分类标签 |
| `lost_user_assistant_count` | `number` | 真正丢失的 user/assistant 消息条数（其他都是 0） |
| `compact_boundary_count` | `number` | chain 中跨过的 compact_boundary 数量 |

---

## 4. 社交 / 推文（建议发）

> clavue v8.13.6 just shipped. The `/resume` "loaded N of M messages"
> warning was crying wolf — most of the time the gap was just `/compact`
> doing its job and the on-disk transcript was fully intact. 8.13.6
> splits the surface into `consistent` / `compacted` / `lost` /
> `reconstructed` and only warns on the one that actually means data
> loss. 9 new unit tests pin the classifier.

中文版：

> clavue v8.13.6 已发布。8.13.5 之前，`/resume` 加载消息少于
> checkpoint 时会一律弹警告——但其中大部分是 `/compact` 正常剪裁，
> transcript 在磁盘上完好无损。8.13.6 把 surface 拆成 4 类，只在
> 真丢消息（磁盘上有 user/assistant uuid 没进 chain）时才警告。

---

## 5. 站点端 backend / API

**本版无站点端改动**。`server.mjs` 里的 `VERSION` 常量需要从 `8.13.5`
改成 `8.13.6`，这是 skill 流程标准动作，已在 deploy 脚本里覆盖。

---

## 6. 升级文案（FAQ / 安装页）

替换 install / upgrade 区块的版本号 8.13.5 → 8.13.6。

```bash
# 全局升级
npm install -g clavue@8.13.6

# 一次性运行（不安装）
npx -y clavue@8.13.6

# install.sh
curl -fsSL https://unpkg.com/clavue@8.13.6/install.sh | bash -s -- 8.13.6
```

无破坏性变更，可直接从任意 8.13.x 升级。
