# Clavue v8.10.18 — Release Notes

**发布日期**：2026-05-17
**npm**：`clavue@8.10.18`
**GitHub**：https://github.com/mycode699/clavue/releases/tag/v8.10.18
**升级命令**：

```bash
npm install -g clavue@8.10.18
# 或一次性：
npx -y clavue@8.10.18
```

---

## TL;DR

8.10.18 是一次**地基版本**。User-visible 行为变化为零，但 v9 升级链上"已落但缺锚点"的不变量被全部 source-anchor 测试钉住，并兑现了 ARCHITECTURE.md 的 "one runtime decision per turn" 契约承诺。

三件事：

1. **`RuntimeDecision` 契约落地** —— ARCHITECTURE.md 写"每轮被一个 RuntimeDecision 治理"已经一年了，但 `src/` 没有这个 type。本版引入 `RuntimeDecision = CodingRoutePolicyDecision` 别名 + 9 字段契约测试 + purity guard，以后任何字段静默删除会立刻 fail。
2. **v9 升级链补 anchor 12 处** —— `dangerouslyDisableSandbox` 必须走 ask 通道、`find -delete/-exec/...` 不得 auto-approve、`.git/.vscode/.idea/.clavue/.claude/` 不得 bypass 模式自改、`/clear` 后 MCP 重连 key 保留、PostToolUse 的 `continueOnBlock` 降级路径，等等。这些 v9 plan 标 done 但没专属测试覆盖的关键不变量，本版全部钉住。
3. **v9 残余实现物 14 commit 固化** —— 把工作区里 9 处文件、约 4400 行未 commit 变更（settings schema / permissions / bash / mcp / provider headers / ergonomics / hooks / query loop split）按子系统切独立 commit，每个都附 anchor test。`npm test` 终态 1372 pass / 0 fail / 3 skipped。

升级风险：**零**。无新行为、无破坏性变更、无新 env 变量、无新 flag。

---

## 1. RuntimeDecision 契约层（ARCHITECTURE.md 兑现）

### 问题

`ARCHITECTURE.md` 第 19-30 行写：

> Every turn is governed by **one runtime decision** with these 10 fields:
> product identity, provider adapter, model family, transport, capability tier,
> workflow mode, plan discipline, verification discipline, recovery mode,
> visible tools.

但 `src/` 完全没有 `RuntimeDecision` 类型定义。文档说有，代码没。后果：每次有 contributor 想做"基于 RuntimeDecision 的优化"都要先重新理解一遍这 10 字段从哪些地方拼出来。

### 修复

`src/utils/model/codingRoutePolicy.ts` 加：

```ts
/**
 * Per-turn runtime decision contract — see ARCHITECTURE.md §"one decision per turn".
 * RuntimeDecision is currently aliased to CodingRoutePolicyDecision;
 * the alias is the contract anchor.
 */
export type RuntimeDecision = CodingRoutePolicyDecision
```

零 callsite 改动 —— 只是给现有 9 字段（product identity 在 PRODUCT.md 层，不在 per-turn decision 里，故 9 而非 10）的 single source of truth 起一个 architecture-认证的名字。

### 锚定

- `tests/runtime-decision-contract.test.mjs` — 3 个测试，断言：
  1. `RuntimeDecision` 别名导出存在
  2. 9 字段（provider adapter / model family / transport / capability tier / workflow mode / plan discipline / verification discipline / recovery mode / visible tools）一个不少
  3. product identity 排除原因 docblock 在
- `scripts/check-source-purity.mjs` — `checkRuntimeDecisionContract()`：alias 缺失或字段丢失立即 fail，进 `npm run check` gate。

### 影响

- 用户行为：零变化。
- 后续优化：v11 候选池的 "featureModules 静态化" / "per-turn capability gating" 现在有了锚点，不必再做"找出所有 per-turn 决定散落在哪"的考古工作。

---

## 2. v9 升级链 12 处不变量补 anchor

v9 计划状态表标记为 done 的若干安全关键不变量，**实现存在但没有专属 source-anchor 测试**。一次手快的 refactor 完全可能把它们悄悄抹掉。本版全部补齐：

| 测试 | 锁定的不变量 |
|---|---|
| `dangerously-disable-sandbox-respects-ask.test.mjs` | `dangerouslyDisableSandbox` 不绕过 ask rule（policy AND-gate） |
| `find-dangerous-flags-no-auto-approve.test.mjs` | `find -delete/-exec/-execdir/-ok/-okdir/-fprint(0)?/-fls/-fprintf` 不能 auto-approve |
| `dangerous-paths-no-auto-edit.test.mjs` | `--dangerously-skip-permissions` 不能 auto-edit `.git/.vscode/.idea/.clavue/.claude/`，`.clavue/settings(.local).json` 用 endsWith 边界匹配 |
| `bash-dev-tcp-udp-bypass.test.mjs` | bash 阻断 `/dev/(tcp\|udp)` 重定向旁路 |
| `sandbox-denied-domains.test.mjs` | sandbox `deniedDomains` 配置生效 |
| `permissions-deny-overrides-hook-ask.test.mjs` | hook ask 不能覆盖 permissions deny |
| `automode-hard-deny-and-defaults.test.mjs` | `hard_deny` 与 `$defaults` 行为契约 |
| `plan-mode-blocks-file-write.test.mjs` | plan-mode 写阻断 |
| `mcp-tool-timeout-default.test.mjs` | MCP 工具默认 60s timeout |
| `mcp-workspace-reserved-name.test.mjs` | "workspace" 是 MCP server 保留名 |
| `clear-preserves-mcp-reconnect.test.mjs` | `/clear` 保留 MCP 重连 key |
| `posttooluse-continue-on-block.test.mjs` + `posttooluse-updated-tool-output.test.mjs` | PostToolUse 的 `continueOnBlock` 降级 + `updatedToolOutput` 对称 |
| `precompact-block.test.mjs` | PreCompact block path |
| `prompt-cache-1h-ttl.test.mjs` | prompt-cache 1h TTL 门控顺序与 5m force-override |
| `bedrock-service-tier-env.test.mjs` | Bedrock service tier env 注入 |
| `anthropic-workspace-id.test.mjs` | `ANTHROPIC_WORKSPACE_ID` / `CLAVUE_WORKSPACE_ID` header 别名 |
| `agents-cwd-filter.test.mjs` | `claude agents --cwd` 过滤 |
| `subagent-type-case-insensitive.test.mjs` | subagent_type 大小写不敏感 |
| `rewind-undo-alias.test.mjs` | `/undo` → `/rewind` alias |
| `skill-name-space-wildcard.test.mjs` | skill `name *` 空格星号归一化 |
| `query-feature-modules-guard.test.mjs` | query loop 通过 featureModules 单一注册表读取可选子系统 |
| `stop-hook-loop-cap.test.mjs` | STOP_HOOK_MAX_LOOPS 上限 |
| `bash-security-validators.test.mjs` | bash 安全校验器组合 |
| `worktree-bg-isolation-baseref.test.mjs` | worktree `bgIsolation` / `baseRef` schema 字段 |

实现层在历次 v9 commit 已经存在；本版新增的是 _测试网_。

---

## 3. v9 残余实现物 14 commit 固化

发现 `v89-p0-development` 工作区还堆着 9 处源文件、约 4400 行未 commit 的 v9 实现。按子系统切独立 commit，每个 commit 内自带对应 anchor test：

| Commit | 子系统 | 内容 |
|---|---|---|
| `b9d9d2b` | settings schema | `worktree.bgIsolation` + `worktree.baseRef` 字段 |
| `2bcd205` | permissions | sandbox / autoMode / plan-mode 加固 + 4 测试 |
| `62edf61` | bash security | `/dev/(tcp\|udp)` 重定向阻断 + 测试 |
| `b8b75ea` | mcp | 60s timeout 默认 + workspace 保留名 + `/clear` 重连保留 + 3 测试 |
| `7e81bfa` | provider headers | Bedrock service tier + `ANTHROPIC_WORKSPACE_ID` header + 2 测试 |
| `ffd904f` | ergonomics | `claude agents --cwd` + subagent_type case + `/undo` alias + skill `name *` + 4 测试 |
| `78d86ae` | hooks | PreCompact block path + PostToolUse `updatedToolOutput` + 2 测试 |
| `e7f183d` | query loop | featureModules 注册表 + queryEngine/claude 拆分 + STOP_HOOK_MAX_LOOPS + 2 测试 |
| `986fa92` | tests | prompt-cache 1h TTL 不变量 anchor |

每个 commit 独立可 `git revert`，commit 内测试全过。

---

## 4. 升级路径

```bash
npm install -g clavue@8.10.18
# 或：
npx -y clavue@8.10.18
```

无破坏性变更：

- 命令行界面无变化。
- Provider 配置、credentials、teams、memory、MCP 已配置项全部兼容。
- 用户从 8.10.17 直接升级即可；旧 jsonl session 完全可读。
- 无新 env 变量、无新 flag、无新行为。**这是一个纯地基版本**。

---

## 5. Tests / Verify

```
npm run check
# tests 1375
# pass 1372
# skipped 3
# fail 0
# duration_ms ~60s
# exit 0
```

新增锚定测试 26 个（v10 contract 3 + v9 invariants 23）。基线从 1361 → 1372 pass。

---

## 6. 改动文件清单

### 源码 (`src/`)

| 文件 | 性质 |
|---|---|
| `src/utils/model/codingRoutePolicy.ts` | 加 `RuntimeDecision` 别名 + product identity docblock |
| `src/query/featureModules.ts` | 新增 — featureModules 单一注册表 |
| `src/queryEngine/handleSystemMessage.ts` 等 5 个 | 新增 — `QueryEngine.ts` 拆分（systemPrompt / processUserInputContext / resultFields / noQueryOutput / handleSystemMessage） |
| `src/services/api/claude/cacheControl.ts` 等 3 个 | 新增 — `claude.ts` 拆分（cacheControl / effort / maxTokens） |
| `src/QueryEngine.ts` | 引用上述 5 个新 helper，删除内联 |
| `src/services/api/claude.ts` | 引用上述 3 个新 helper，删除内联 |
| `src/query.ts` | featureModules 注册表 + STOP_HOOK_MAX_LOOPS 强约束 |
| `src/utils/permissions/{filesystem,permissions,yoloClassifier}.ts` | sandbox/autoMode/plan-mode 加固 |
| `src/tools/BashTool/{bashSecurity,pathValidation,shouldUseSandbox}.ts` | bash 安全 + sandbox AND-gate |
| `src/services/mcp/{config,utils}.ts` | 60s timeout + workspace 保留名 |
| `src/utils/hooks.ts` + `src/services/tools/toolHooks.ts` | PreCompact + PostToolUse |
| `src/cli/handlers/agents.ts` + `src/main.tsx` | `--cwd` flag |
| `src/commands/rewind/index.ts` | `/undo` alias |
| `src/tools/AgentTool/{AgentTool.tsx,agentToolUtils.ts}` | subagent_type case |
| `src/tools/SkillTool/SkillTool.ts` | skill `name *` 归一化 |
| `src/services/api/client.ts` | provider header 注入 |
| `src/services/compact/compact.ts` | reactive compact preserved messages |
| `src/utils/sandbox/sandbox-adapter.ts` | sandbox adapter 路径 |
| `src/utils/settings/{settings,types}.ts` | worktree.bgIsolation / baseRef schema |
| `src/entrypoints/sandboxTypes.ts` | sandbox type |
| `src/constants/branding.ts` | `APP_VERSION_FALLBACK` → 8.10.18 |

### 测试 (`tests/`)

26 个新增 source-anchor 测试，命名一一对应锁定的不变量。

### 配置 / 文档

| 文件 | 性质 |
|---|---|
| `package.json` | 8.10.17 → 8.10.18 |
| `package-lock.json` | 同步 |
| `README.md` | 版本号同步到 8.10.18 |
| `content-artifacts/llms.txt` / `llms-full.txt` | 版本字段同步 |
| `docs/clavue-roadmap-v10.md` | 新增 — 取代 v9 slice 堆砌视角 |
| `docs/clavue-upgrade-plan-v9.md` | redirect stub → 归档 |
| `docs/archive/2026-q2/clavue-upgrade-plan-v9.md` | v9 plan 归档原文 |
| `scripts/check-source-purity.mjs` | 加 `checkRuntimeDecisionContract` |
| `docs/clavue-v8.10.18-release-notes.md` | 本文件 |
| `docs/clavue-v8.10.18-website-update.md` | 站点更新包 |

---

## 7. Why this version exists

> "v10 = 把 v9 已落的事兑现到契约层 + 解锁 v11 的运行时统一。
> 不是新功能，是地基。"
> — `docs/clavue-roadmap-v10.md`

8.10.17 修了用户能感知的代理问题（attribution header、遥测、WebFetch）。8.10.18 反过来：用户感觉不到任何变化，但项目内部的 "ARCHITECTURE.md 承诺与代码现实之间的鸿沟" 被填上了。后面任何"基于 per-turn decision"的优化（capability gating / featureModules 静态化 / 路由感知的工具可见性）都从 8.10.18 起有了锚点。

不要为了"显得在工作"而升级。如果你在跑 8.10.17 且没遇到问题，等 8.10.19/8.11 都行。
