vault backup: 2026-06-09 23:15:17

claude-code-best/docs/internals/growthbook-adapter.md

@@ -1,17 +1,17 @@
 ---
-title: "GrowthBook 适配器 - 自定义 Feature Flag 服务器接入"
-description: "通过环境变量连接自定义 GrowthBook 服务器，实现远程 feature flag 控制。无配置时自动回退到代码默认值。"
-keywords: ["growthbook", "feature flags", "远程配置", "适配器", "环境变量"]
+tags: [growthbook, feature-flags, claude-code, 远程配置, 适配器]
+create time: 2026-06-09 22:30
 ---
 
+# GrowthBook 适配器 - 自定义 Feature Flag 服务器接入
+
 ## 概述
 
-Claude Code 的 GrowthBook 系统支持通过环境变量连接自定义 GrowthBook 服务器，实现远程 feature flag 控制。
+Claude Code 的 GrowthBook 系统支持通过环境变量连接自定义 GrowthBook 服务器，实现远程 feature flag 控制。有配置时连接你的 GrowthBook 实例拉取并缓存 feature 值，无配置时所有 feature 读取直接返回代码中的默认值，零网络请求。
 
-- **有配置时**：连接你的 GrowthBook 实例，拉取并缓存 feature 值
-- **无配置时**：所有 feature 读取直接返回代码中的默认值，零网络请求
+## 正文
 
-## 环境变量
+### 环境变量
 
 | 变量 | 必填 | 说明 |
 |---|---|---|
@@ -20,9 +20,9 @@ Claude Code 的 GrowthBook 系统支持通过环境变量连接自定义 GrowthB
 
 两个变量都设置时启用适配器模式，否则完全跳过 GrowthBook。
 
-## 使用方式
+### 使用方式
 
-### 基本用法
+**基本用法**
 
 ```bash
 CLAUDE_GB_ADAPTER_URL=https://gb.example.com/ \
@@ -30,31 +30,26 @@ CLAUDE_GB_ADAPTER_KEY=sdk-abc123 \
 bun run dev
 ```
 
-### 不使用 GrowthBook（默认行为）
+**不使用 GrowthBook（默认行为）**
 
 ```bash
 bun run dev
 # 所有 getFeatureValue_CACHED_MAY_BE_STALE("xxx", defaultValue) 直接返回 defaultValue
 ```
 
-## GrowthBook 服务端配置
-
-### 步骤
+### GrowthBook 服务端配置
 
 1. **部署 GrowthBook 服务端**（Docker 自托管或 Cloud 版）
 2. **创建 Environment**（如 `production`）
 3. **创建 SDK Connection**，获得 SDK Key（即 `CLAUDE_GB_ADAPTER_KEY`）
 4. **按需添加 Feature**，key 和类型见下方列表
 
-### 核心原则
+> [!tip]
+> **核心原则**：不配置任何 feature 也能正常运行——代码中每个调用都提供了默认值。只创建你想远程控制的 feature，其余走代码默认。GrowthBook 上配了某个 feature 后，其值会覆盖代码中的默认值。
 
-- **不配置任何 feature 也能正常运行**——代码中每个调用都提供了默认值
-- 只创建你想远程控制的 feature，其余走代码默认
-- GrowthBook 上配了某个 feature 后，其值会覆盖代码中的默认值
+### Feature Key 列表
 
-## Feature Key 列表
-
-### 高频使用
+#### 高频使用
 
 | Feature Key | 类型 | 代码默认值 | 用途 |
 |---|---|---|---|
@@ -70,7 +65,7 @@ bun run dev
 | `tengu_cicada_nap_ms` | number | `0` | 后台刷新节流（毫秒） |
 | `tengu_miraculo_the_bard` | boolean | `false` | 启动欢迎信息 |
 
-### Agent / 工具控制
+#### Agent / 工具控制
 
 | Feature Key | 类型 | 代码默认值 | 用途 |
 |---|---|---|---|
@@ -81,7 +76,7 @@ bun run dev
 | `tengu_birch_trellis` | boolean | `true` | Bash 权限控制 |
 | `tengu_harbor_permissions` | boolean | `false` | Harbor 权限模式 |
 
-### Bridge / 远程连接
+#### Bridge / 远程连接
 
 | Feature Key | 类型 | 代码默认值 | 用途 |
 |---|---|---|---|
@@ -89,7 +84,7 @@ bun run dev
 | `tengu_copper_bridge` | boolean | `false` | Copper Bridge |
 | `tengu_ccr_mirror` | boolean | `false` | CCR Mirror |
 
-### 内存 / 上下文
+#### 内存 / 上下文
 
 | Feature Key | 类型 | 代码默认值 | 用途 |
 |---|---|---|---|
@@ -100,7 +95,7 @@ bun run dev
 | `tengu_session_memory` | boolean | `false` | 会话内存 |
 | `tengu_pebble_leaf_prune` | boolean | `false` | 内存修剪 |
 
-### UI / 体验
+#### UI / 体验
 
 | Feature Key | 类型 | 代码默认值 | 用途 |
 |---|---|---|---|
@@ -112,7 +107,7 @@ bun run dev
 | `tengu_immediate_model_command` | boolean | `false` | 即时模型切换 |
 | `tengu_remote_backend` | boolean | `false` | 远程后端 |
 
-### 配置对象（动态配置）
+#### 配置对象（动态配置）
 
 | Feature Key | 类型 | 代码默认值 | 用途 |
 |---|---|---|---|
@@ -124,7 +119,7 @@ bun run dev
 | `tengu_marble_fox` | object | `null` | Marble Fox 配置 |
 | `tengu_ultraplan_model` | string | `null` | Ultraplan 模型名 |
 
-### Gate（布尔门控）
+#### Gate（布尔门控）
 
 | Gate Key | 代码默认值 | 用途 |
 |---|---|---|
@@ -133,23 +128,22 @@ bun run dev
 | `tengu_thinkback` | `false` | Thinkback 功能 |
 | `tengu_tool_pear` | `false` | Tool Pear 功能 |
 
-## 读取优先级链
+### 读取优先级链
 
 每个 feature 的值按以下顺序解析，第一个命中即返回：
 
-```
-1. CLAUDE_INTERNAL_FC_OVERRIDES 环境变量（JSON 对象覆盖）
-   ↓ 未命中
-2. growthBookOverrides 配置（~/.claude.json，仅 ant 构建）
-   ↓ 未命中
-3. 内存缓存（remoteEvalFeatureValues，本次进程从服务器拉取）
-   ↓ 未命中
-4. 磁盘缓存（~/.claude.json 的 cachedGrowthBookFeatures）
-   ↓ 未命中
-5. 代码中的 defaultValue 参数
+```mermaid
+flowchart TD
+    A["CLAUDE_INTERNAL_FC_OVERRIDES 环境变量"] --> B["growthBookOverrides 配置"]
+    B --> C["内存缓存（本次进程从服务器拉取）"]
+    C --> D["磁盘缓存（~/.claude.json）"]
+    D --> E["代码中的 defaultValue 参数"]
+
+    style A fill:#fee,stroke:#c66
+    style E fill:#efe,stroke:#6a6
 ```
 
-## 缓存与刷新机制
+### 缓存与刷新机制
 
 | 机制 | 说明 |
 |---|---|
@@ -158,7 +152,7 @@ bun run dev
 | **初始化超时** | 首次连接超时 5 秒，超时后使用磁盘缓存或默认值 |
 | **Auth 变更** | 登录/登出时自动销毁并重建客户端 |
 
-## 实现细节
+### 实现细节
 
 修改了 2 个文件共 3 处：
 
@@ -167,3 +161,9 @@ bun run dev
 3. **`src/services/analytics/growthbook.ts`** — base URL 优先使用 `CLAUDE_GB_ADAPTER_URL`
 
 所有 130+ 个调用方文件无需修改。
+
+## 关联笔记
+
+- [[growthbook-ab-testing]] - GrowthBook A/B 测试体系
+- [[feature-flags]] - 构建时 Feature Flags 全解
+- [[three-tier-gating]] - 三层门禁系统全景