cs-note/claude-code-best/docs/internals/growthbook-ab-testing.md

---
tags: [growthbook, ab-testing, claude-code, 运行时门控, tengu]
create time: 2026-06-09 22:30
---

# GrowthBook A/B 测试体系 - 运行时功能发布

## 概述

构建时 `feature()` 是"全有或全无"的，但产品团队需要更精细的控制——灰度发布、按订阅差异化、远程关闭问题功能。GrowthBook 作为运行时 A/B 测试系统，通过 `tengu_*` 前缀的 500+ 个 flag 实现用户级的功能门控。

## 正文

### 为什么需要运行时 A/B 测试

构建时 `feature()` 是"全有或全无"的——要么所有用户都有，要么所有用户都没有。但产品团队需要更精细的控制：

- 只对 5% 的用户灰度发布新功能
- 按订阅类型（Free / Pro / Team）差异化体验
- 对特定组织静默开启实验性能力
- 随时远程关闭出问题的功能，无需发版

这就是 **GrowthBook** 的用武之地——一个运行时的、基于用户属性的功能门控和 A/B 测试系统。

### 集成架构

GrowthBook 的完整实现位于 `src/services/analytics/growthbook.ts`（1258 行），工作流程如下：

```mermaid
flowchart LR
    A["启动时获取远程配置"] --> B["计算用户属性"]
    B --> C["缓存到本地"]
    C --> D["代码中查询 flag"]

    A -.- A1["SDK 通过 API 端点获取配置和实验分组规则"]
    B -.- B1["收集设备 ID、订阅类型、组织 UUID 等"]
    C -.- C1["缓存到 ~/.claude.json"]
    D -.- D1["通过 tengu_* 前缀查询功能状态"]
```

1. **启动时获取远程配置**：CLI 启动时，GrowthBook SDK 通过 `https://api.anthropic.com/` 的 API 端点获取当前的功能配置和实验分组规则。使用 `remoteEval: true` 模式——在服务端计算分组，客户端只拿结果。
2. **计算用户属性**：SDK 收集当前用户的属性（设备 ID、订阅类型、组织 UUID 等），用于决定该用户属于哪些实验的哪个分组。
3. **缓存到本地**：计算结果缓存到 `~/.claude.json` 的 `cachedGrowthBookFeatures` 字段。刷新间隔：Anthropic 员工 20 分钟，外部用户 6 小时。
4. **代码中查询 flag**：业务代码通过 `tengu_*` 前缀的 flag 名查询功能状态，GrowthBook SDK 返回当前用户的分组值。

### 用户定向属性

GrowthBook 根据以下用户属性决定实验分组：

| 属性 | 类型 | 来源 | 用途 |
|------|------|------|------|
| `id` | string | 会话 ID | 按会话粒度分组 |
| `deviceID` | string | 持久化设备标识 | 跨会话一致性 |
| `sessionId` | string | 当前会话 ID | 会话级实验 |
| `platform` | enum | `process.platform` | 按操作系统差异化 |
| `organizationUUID` | string | API 认证信息 | 按组织灰度 |
| `accountUUID` | string | API 认证信息 | 按个人账户灰度 |
| `subscriptionType` | string | API 认证信息 | Free / Pro / Team 差异化 |
| `rateLimitTier` | string | API 认证信息 | 按速率限制层级 |
| `email` | string | API 认证信息 | 精确定向特定用户 |
| `appVersion` | string | `MACRO.VERSION` | 按版本号灰度 |
| `github` | object | GitHub Actions 元数据 | CI 环境特殊处理 |

> [!info]
> 这套定向系统意味着 Anthropic 可以做非常精细的实验——比如"只对 Mac 上的 Pro 订阅用户的 10% 开启新功能"。

### 代号文化：tengu_* 的世界

所有运行时 flag 都以 `tengu_` 为前缀——"Tengu"（天狗）是 Claude Code 的内部项目代号。flag 名采用**动物/植物/矿物 + 形容词**的命名约定，刻意保持不透明。

**tengu_kairos** — Kairos 助手模式：控制 KAIROS 功能的运行时开关。即使构建时 `feature('KAIROS')` 通过，仍需此 flag 命中才能激活。双重门控确保新功能可以分阶段发布。

**tengu_amber_stoat** — Explore Agent A/B 测试：控制内置的 Explore 子 Agent 的行为变体。"amber stoat"（琥珀色白鼬）是随机生成的代号，与功能内容无关——这是为了防止通过 flag 名猜测功能。

**tengu_auto_background_agents** — 后台 Agent 自动化：控制是否自动将某些任务分派给后台 Agent 执行，而不是在前台阻塞用户。

**tengu_onyx_plover** — Auto-Dream 后台记忆：控制"自动做梦"功能——在空闲时后台整理和巩固 Agent 的记忆。"onyx plover"（玛瑙鸻）又是一个不透明代号。

**tengu_glacier_2xr** — 工具搜索行为：控制 Tool Search 的行为变体，可能是搜索算法或排序策略的 A/B 测试。

**tengu_birch_trellis** — Bash 权限策略：控制 BashTool 权限判断的策略变体——可能在测试更宽松或更严格的权限规则。

**tengu_scratch** — 草稿本功能：控制一个实验性的"草稿本"功能，可能是让 AI 在处理复杂任务时使用中间暂存区。

**tengu_quartz_lantern** — Diff 计算策略：控制文件写入和编辑时的 diff 计算方式。可能在 A/B 测试不同的 diff 算法对用户体验的影响。

### Ant-Only 覆盖机制

Anthropic 员工拥有两种方式绕过 GrowthBook 的远程求值：

**环境变量覆盖**

```bash
# 仅在 USER_TYPE=ant 的构建中生效
CLAUDE_INTERNAL_FC_OVERRIDES='{"tengu_kairos": true}' claude
```

通过 `CLAUDE_INTERNAL_FC_OVERRIDES` 环境变量传入 JSON 对象，直接覆盖任意 flag 的值。

**Config 界面覆盖**

在内部构建中，`/config` 命令的 Gates 标签页提供了图形化的 flag 管理界面，可以实时切换任意 GrowthBook flag。

### 实验追踪

GrowthBook 集成了完整的实验曝光追踪：

- 每次查询 flag 时记录实验曝光事件
- 通过 protobuf 格式的 `GrowthbookExperimentEvent` 上报
- 包含 `variation_id`（0=对照组，1+=实验组）和 `in_experiment` 标记
- 数据用于分析功能对用户行为的因果影响

> [!info]
> GrowthBook 正在从 Statsig 迁移而来——代码中仍保留着 `checkStatsigFeatureGate_CACHED_MAY_BE_STALE()` 这样的迁移兼容层。

## 关联笔记

- [[feature-flags]] - 构建时 Feature Flags 全解
- [[growthbook-adapter]] - 自定义 GrowthBook 服务器接入
- [[three-tier-gating]] - 三层门禁系统全景
- [[ant-only-world]] - Anthropic 员工专属功能