# Clavue v8.10.17 — Release Notes

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

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

---

## TL;DR

8.10.17 是一次"网络卫生 + 第三方代理兼容"修复版。三件事：

1. **彻底移除 `x-anthropic-billing-header` 注入** — upstream Claude Code 在每个 `/v1/messages` 请求上插一段每轮变化的 attribution header（含 cch + fingerprint）。该 header 在每次请求间都会变 → 第三方 Anthropic-兼容代理的 prefix-cache 命中率掉到 0 → token 暴涨、首 token 延迟显著上升。Clavue 不需要这玩意，全部摘掉。
2. **默认关闭遥测** — 4 个外发端点（domain block-list / MCP registry / event logging / GrowthBook features）默认全部关闭。`CLAVUE_TELEMETRY=1` 显式 opt-in 才发包，且基址改到 `www.clavue.com`，不再走 `api.anthropic.com`。
3. **WebFetch 域名校验全放行** — 之前 `WebFetchTool` 必须先 ping `api.anthropic.com/api/web/domain_info` 拿放行才能 fetch，对国内 / 企业内网 / 离线场景是硬阻断。现在 `www.clavue.com` 兼容路由一律返回 `{can_fetch:true}`，等价"默认放行 + 用户已批准的域名前置审批仍然在"。MCP 官方注册表改为静态列表（11 条主流 MCP server），不再每次启动拉远端。

逃生开关：`CLAVUE_TELEMETRY=1` 重新打开遥测；`CLAVUE_DISABLE_NONESSENTIAL_TRAFFIC=1` 保留作为强制静默兜底。

测试：1298 / 1301 pass / 3 skipped / 0 fail（`npm run check`，~60s）。Dist 4 个暗病指纹（`x-anthropic-billing-header` / `CLAUDE_CODE_ATTRIBUTION_HEADER` / `tengu_attribution_header` / `59cf53e54c78`）全部 0。

---

## 1. 移除 `x-anthropic-billing-header` 注入

### 问题

`src/utils/api.ts` 和 `src/utils/fingerprint.ts` 之前会为每个 `/v1/messages` 请求注入：

```
x-anthropic-billing-header: <base64(cch + fingerprint + 还有几个 rotating 字段)>
```

- 字段每轮都变 → 第三方 OpenAI-兼容 / Anthropic-兼容代理（如 OneAPI、Newapi、各种自部署中转）做 prefix-cache 时把整个请求体 + headers 一起 hash，header 一变缓存 key 就变，命中率直接归零。
- 用户实测同一 prompt 反复发，token 使用从 ~3K 涨到 ~12K，p50 首 token 延迟从 800ms 涨到 4s+。
- Clavue 是独立产品，不需要 upstream 的 billing attribution。

### 修复

`src/utils/api.ts`：删除所有 `x-anthropic-billing-header` 注入点；删除 `CLAUDE_CODE_ATTRIBUTION_HEADER` 控制变量；删除 `tengu_attribution_header` 事件。

`src/utils/fingerprint.ts`：留下纯本地、不参与请求 header 的最小 fingerprint helper（部分 in-process 日志仍引用），不再编码 cch 也不再下发。

`src/constants/system.ts`：清理与 attribution 强耦合的常量。

dist/cli.js 重建后这 4 个字面量在产物里出现次数全部为 0。

### 影响面

- 用 Clavue 直连 Anthropic 官方 API：行为不变（官方网关本来就 ignore 这个 header）。
- 用 Clavue 走第三方代理：prefix-cache 重新命中，token 消耗显著下降，延迟回到正常水平。
- 用 Clavue 走完全本地模型（Ollama / vLLM）：本来就不看这个 header。

---

## 2. 默认关闭遥测；端点全部迁到 www.clavue.com

### 问题

upstream Claude Code 默认会从主进程外发 4 路非必要请求：

1. `api.anthropic.com/api/web/domain_info` — WebFetch 前置域名 block-list 检查
2. `api.anthropic.com/api/mcp-registry/v0/servers` — 启动时拉 MCP 官方注册表
3. `api.anthropic.com/api/v1/events` — 事件 / metrics logging
4. `api.anthropic.com/api/v1/growthbook/...` — 实验配置 / feature flags

对独立 Clavue 用户来说这 4 个请求都是不必要的网络副作用。

### 修复

- `src/services/analytics/config.ts`：遥测默认 off。`CLAVUE_TELEMETRY=1` 显式 opt-in；保留 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 兼容兜底。
- `src/services/analytics/firstPartyEventLoggingExporter.ts`：基址硬切到 `https://www.clavue.com`。
- `src/services/analytics/growthbook.ts`：基址硬切到 `https://www.clavue.com`，默认禁用 SDK 调用。
- `src/services/mcp/officialRegistry.ts`：基址硬切到 `https://www.clavue.com/api/mcp-registry/v0/servers`。
- `src/tools/WebFetchTool/utils.ts`：domain 检查基址硬切到 `https://www.clavue.com/api/web/domain_info`。

`www.clavue.com` 站点（`clavue-site.service`）这一版同步加了 4 个兼容路由：

| 路径 | 行为 |
|---|---|
| `/api/web/domain_info` | 始终返回 `{ can_fetch: true }`（"全放行 + 已有用户审批"策略） |
| `/api/mcp-registry/v0/servers` | 返回 11 条精选静态 MCP server 列表（Notion / Linear / Sentry / Atlassian / Intercom / Asana / PayPal / Stripe / Cloudflare / DeepWiki / Context7） |
| `/api/v1/events` | 接收 + 静默 200（opt-in 后才会真的有 payload） |
| `/api/v1/growthbook/...` | 返回空 features 集合，等价"无任何 A/B 实验" |

### 影响面

- 离线 / 国内 / 企业内网用户：CLI 启动期间不再阻塞或抖动在 `api.anthropic.com` 解析失败上。
- 想要协助产品改进的用户：`CLAVUE_TELEMETRY=1` 显式打开后只发到 `www.clavue.com`，不再混进 upstream。
- 走第三方代理的用户：CLI 不再在请求拓扑外多打 4 条到第三方域名的连接。

---

## 3. WebFetch / MCP 注册表静默化

### WebFetch

原先 `WebFetchTool` 在第一次访问每个域名时会先做一次 preflight 到 `api.anthropic.com/api/web/domain_info`。对企业网内能直连第三方模型代理、但出不去 `api.anthropic.com` 的用户，整个工具事实上不可用。

新行为：preflight 走 `www.clavue.com`，并且站点返回 `{can_fetch:true}` 一律放行。Clavue 自身的"每个域名首次使用需要用户在 TUI 里 approve"机制不变，这才是真正的访问控制层。

### MCP 注册表

原先每个 CLI 实例启动会拉 `api.anthropic.com/api/mcp-registry/v0/servers?version=latest&visibility=commercial`。新行为：静态 11 条列表，每条都是经过验证的主流 MCP server。需要新增 / 删除时在 `server.mjs` 注释里描述如何更新 — 离线友好，无网络副作用。

---

## 4. 升级路径

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

无破坏性变更：

- 命令行界面无变化。
- Provider 配置、credentials、teams、memory、MCP 已配置项全部兼容。
- 用户从 8.10.16 直接升级即可；旧 jsonl session 完全可读。
- 唯一行为差异：上述 4 条外发请求默认关闭；如有人显式依赖（极少见）请加 `CLAVUE_TELEMETRY=1`。

---

## 5. Tests / Verify

```
npm run check
# tests 1301
# pass 1298
# skipped 3
# fail 0
# duration_ms ~60s
```

Dist 暗病字面量复检（rebuild 后全部为 0）：

| 字面量 | dist/cli.js 出现次数 |
|---|---|
| `x-anthropic-billing-header` | 0 |
| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 0 |
| `tengu_attribution_header` | 0 |
| `59cf53e54c78` | 0 |

---

## 6. 改动文件清单

| 文件 | 性质 |
|---|---|
| `src/utils/api.ts` | 删除 attribution header 注入 |
| `src/utils/fingerprint.ts` | 收缩到纯本地最小 helper，不再下发 |
| `src/constants/system.ts` | 清理 attribution 相关常量 |
| `src/services/analytics/config.ts` | 默认关闭遥测，opt-in via `CLAVUE_TELEMETRY=1` |
| `src/services/analytics/firstPartyEventLoggingExporter.ts` | 基址 → `www.clavue.com` |
| `src/services/analytics/growthbook.ts` | 基址 → `www.clavue.com`；默认禁用 SDK |
| `src/services/mcp/officialRegistry.ts` | 基址 → `www.clavue.com`（站点返回静态列表） |
| `src/tools/WebFetchTool/utils.ts` | domain 检查基址 → `www.clavue.com`（始终放行） |
| `src/constants/branding.ts` | APP_VERSION_FALLBACK → 8.10.17 |
| `package.json` | 8.10.16 → 8.10.17 |
| `README.md` | 全文版本号同步到 8.10.17 |
| `content-artifacts/llms.txt` | 版本字段同步到 8.10.17 |
| `content-artifacts/llms-full.txt` | 版本字段同步到 8.10.17 |
| `.remote-clavue-site/server.mjs` | 4 个兼容路由 + VERSION → 8.10.17 |

---

## 7. Environment Flags

| 变量 | 作用 |
|---|---|
| `CLAVUE_TELEMETRY=1` | 重新打开 4 路外发（domain_info / mcp-registry / events / growthbook），全部到 `www.clavue.com` |
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` | 兼容 upstream 变量，等价强制静默 |
