# Clavue v8.13.10 — Website / Marketing Update Pack

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

---

## 1. 首页改动建议

### 1.1 顶部 banner / hero 副标题

替换或新增：

> **v8.13.10** — Skill 目录里的业务代码不再触发 bypass-immune 弹窗；权限弹窗终于有了"永久信任本项目"选项；reactive compact 可配置保留尾窗 N 轮；critical-heap cooldown 不再 silent 失败。

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

### 1.2 "新功能 / 新修复" 卡片

新增 3 张（第 4 个 bug 偏底层，并入 changelog 不单出卡片）：

**卡 1：Skill 目录不再被当作 config 整体保护**
- 标题：Skill directories are user content, not config
- 副标题：`.claude/skills/baidu-seo/scripts/keyword_inventory.php` 这类业务代码不再每次 Edit 都被 safetyCheck ask 拦截。bypass-immune 保护被收敛到 `<root>/skills/<name>/SKILL.md`——唯一承载 `hooks:` 的清单文件。深层 SKILL.md、scripts/、references/ 全部走正常 acceptEdits / trustedOps 通道。
- 数据点：用户实测 PHP/SEO 项目工作流的 friction 弹窗数从 "每次 Edit" 降为 0。
- 链接：`/docs/changelog#8-13-10`

**卡 2：权限弹窗新增 "Always allow for this project"**
- 标题：Stop re-confirming the same directory on every cold start
- 副标题：文件编辑权限弹窗新增第三个选项 `Yes, always allow edits in <dir>/ for this project`。一次点击写入项目本地 `.clavue/settings.local.json`，跨重启生效。Session-only 与单次放行选项保留；`.clavue/.claude` 自身的 self-edit 弹窗保持独立保护逻辑。
- 链接：`/docs/permissions#always-allow`

**卡 3：Reactive compact 真正分级预警 + 可配置保留尾窗**
- 标题：See context pressure earlier, lose less context on recovery
- 副标题：warning 阈值 buffer 从 20k 拉到 40k，与 error 阈值真正分离——UI 提示终于有"提前两个工具轮"的预警窗。reactive compact 新支持 `CLAUDE_REACTIVE_COMPACT_PRESERVE_GROUPS=<1-10>`，多步 agent 场景设 2 即可恢复足够上下文。默认仍是 1，向后兼容。
- 链接：`/docs/changelog#8-13-10`

---

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

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

```markdown
## v8.13.10 — 2026-05-22

### Fixed
- **Skill 目录不再被当作 config 整体保护**：`isClaudeConfigFilePath` 之前把整个 `.clavue/skills/` 和 `.claude/skills/` 推进 bypass-immune 的 safetyCheck ask 分支。结果是用户在 `.claude/skills/<name>/scripts/*.php` 等业务代码上的每一次 surgical edit 都触发弹窗，且 `bypassPermissions`/`acceptEdits`/`trustedOps` 都关不掉。修复后保护被收敛到 `<root>/skills/<name>/SKILL.md`——`loadSkillsDir.ts:parseHooksFromFrontmatter` 真正解析 `hooks:` frontmatter 的那一个文件。深层 SKILL.md（loader 不读）与 sibling 文件全部走正常权限通道。`commands/`、`agents/`、`settings.json`、`hooks/` 保护未动。
- **Critical-heap cooldown 不再 silent 失败**：当 `decideAutoCompactFromUsage` 的 60s 时间窗或 10% heap-relief gate 拒绝再次触发 emergency compaction 时，`autoCompactIfNeeded` 之前直接早返回 `{ wasCompacted: false }`，session 没有任何用户可见信号就继续在 critical heap 上跑。现在该分支主动 `tryForceMajorGc('autocompact-cooldown-suppressed')` 一次，并把带堆使用量与 `/clear` 提示的 failureReason 透传给 query loop。

### Added
- **文件权限弹窗新选项**：`Yes, always allow edits in <dir>/ for this project`。一次选择把目录级 Edit allow rule 写入 `.clavue/settings.local.json`，跨重启生效。`PermissionOption` 类型新增 `accept-always` 变体，handler 走 `generateSuggestions(..., 'localSettings')`。
- **`CLAUDE_REACTIVE_COMPACT_PRESERVE_GROUPS` 环境变量**：reactive compact 保留尾窗 N 轮（默认 1，上限 10）。多步 agent / 工具链场景下设 2 或 3 可显著降低"压缩后模型失忆"的概率。
- 4 个 contract test 文件（共 15 subtests）锁住上述 4 个修复的代码形状，任何后续 PR 改动结构都会立即爆红。

### Changed
- `generateSuggestions(filePath, op, ctx, paths, destination?)` 多加一个可选 destination 参数。destination !== 'session' 时产出真正的 `addRules / Edit allow / <dir>/**` PermissionUpdate（而不是 `addDirectories`，后者单独加进 workingDirectories 仍会被 step 9 ask 拦下）。
- `WARNING_THRESHOLD_BUFFER_TOKENS` 20_000 → 40_000，与 `ERROR_THRESHOLD_BUFFER_TOKENS = 20_000` 拉开。`calculateTokenWarningState` 的三档（warning / error / autocompact）从此严格单调，TokenWarning 组件的颜色与文案有了真正层次。
- `planReactiveCompaction` 从硬编码 "保留最后一个 group" 改为读 env + 计算 N，`groups.slice(-N).flat()` 替代 `groups.at(-1)`。

### Environment Flags（逃生开关）
- `CLAUDE_REACTIVE_COMPACT_PRESERVE_GROUPS=<1-10>` — 设置 reactive compact 保留的尾窗 group 数。默认 1（保持向后兼容）。
- `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=<1-100>` — 已存在的 autocompact 阈值百分比 override。
- `CLAVUE_DISABLE_EMERGENCY_TRUNCATE=1` — 已存在的 L3 紧急截断关闭开关。

### Tests
- 新增 4 个测试文件、共 15 个 subtest：
  - `tests/skill-manifest-narrow-protection.test.mjs`（5）
  - `tests/file-permission-always-allow.test.mjs`（4）
  - `tests/compact-trailing-window-and-ladder.test.mjs`（3）
  - `tests/autocompact-cooldown-visibility.test.mjs`（3）
- 全套 `npm run check`：1634 tests / 1628 pass / 6 skipped / 0 fail，~54s。

升级：

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

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

---

## 3. Docs 页改动建议

### 3.1 新增 `/docs/permissions#always-allow` 锚点

如果 `/docs/permissions` 已存在，在文件权限弹窗章节追加一节：

```markdown
### "Always allow for this project"

当 Clavue 请求文件编辑权限时，对话框会出现以下选项：

| 选项 | 行为 | 持久化位置 |
|---|---|---|
| Yes | 仅本次允许 | 无 |
| Yes, allow all edits in `<dir>/` during this session | 本会话内允许该目录下所有编辑 | 内存（关闭进程即失效） |
| **Yes, always allow edits in `<dir>/` for this project** | 在 `.clavue/settings.local.json` 写入 `Edit /<dir>/**` allow rule | `.clavue/settings.local.json` |
| No | 拒绝并退回模型 | 无 |

新选项只在非 `.clavue` / `.claude` 自身路径上出现，且仅对 write/create 操作可见。
读操作仍走 Read rule 路径（不需要持久化的同等选项）。
`.clavue` / `.claude` 自身的权限弹窗有独立的 "Yes, and allow Clavue to edit its own settings for this session" 选项，保留原有保护包络。
```

### 3.2 更新 `/docs/long-session-stability`

在 "Reactive compact" 小节追加：

```markdown
### Trailing window for reactive compact

`planReactiveCompaction` 默认保留最后 1 个 API round group。对于多步 agent / 工具链场景，"最后一个 group" 可能只是一条 assistant 文本，模型恢复后会丢失关键中间状态。

设置环境变量 `CLAUDE_REACTIVE_COMPACT_PRESERVE_GROUPS=2`（或 3）可让 reactive compact 保留尾部 N 个 group：

\`\`\`bash
export CLAUDE_REACTIVE_COMPACT_PRESERVE_GROUPS=2
clavue
\`\`\`

上限钳制为 10（防止 runaway env value 反过来 starve summary path）。
默认 1 保持向后兼容；只在你确实观察到 "compact 后模型失去任务上下文" 时调高。

### Critical-heap cooldown 的用户可见信号

当 autocompact 被 60s 时间窗或 10% heap-relief gate 抑制时，Clavue 会主动触发一次 GC 并在 UI 显示：

> Memory pressure is critical (X MB / Y MB) but auto-compact is in cooldown to avoid thrashing.
> A forced GC reclaimed ~Z MB. If responses slow down, run /clear to free context manually.

这是真正的用户操作建议：cooldown 期间 autocompact 不会再触发，模型质量会逐步下降。手动 `/clear` 是最直接的恢复手段。
```

### 3.3 `/docs/skills` 文档强调 SKILL.md 是唯一受保护文件

在 skills 文档顶部追加 Note：

```markdown
> **Note (v8.13.10+)**：只有 `<root>/skills/<name>/SKILL.md`（一级清单文件）受 bypass-immune 的 safetyCheck 保护，因为它的 frontmatter `hooks:` 字段可以授予执行权。
> 同一 skill 目录下的 `scripts/`、`references/`、深层 `SKILL.md`、README、`.py`/`.php`/`.js` 等 sibling 文件视为**用户内容**，走正常 acceptEdits / trustedOps / bypassPermissions 通道。
>
> 这是 v8.13.10 的修复，解决了"业务代码颜在 skill 目录下就被反复弹窗"的 friction。
```

---

## 4. 复盘要点（可选，作为 dev blog post）

如果有 dev blog 频道，4 个修复都适合写成短文：

- **#1 是"分层 vs 整层"的经典权衡**：把整个 `.claude/skills/` 当 config 是 v8.13.9 的过度防御；正确粒度是 frontmatter 字段所在的具体文件。
- **#2 是"UX 摩擦倒逼配置正确化"**：弹窗里直接写文件比让用户手动编辑 settings.local.json 友好 100 倍。
- **#3 是"分级阈值不能等号"**：warning == error 在产品上等于没有 warning。
- **#4 是"silent skip is the bug"**：任何 "聪明" 的抑制策略都必须配可见的 UX 通知，否则就是黑盒地让产品质量退化。

四个 bug 都来自同一种气味："这条路径被保护/抑制了，但用户/调用方完全感受不到"。修复方向是统一的：把不可见的状态变化转成可见的 UX 信号，把粗粒度的保护收敛到真正危险的最小单元。
