wonder/cs-note

Fork 0

Files

T

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

2026-06-09 23:15:17 +08:00

6.5 KiB

Raw Blame History

tags, create time

GrowthBook 适配器 - 自定义 Feature Flag 服务器接入

概述

Claude Code 的 GrowthBook 系统支持通过环境变量连接自定义 GrowthBook 服务器，实现远程 feature flag 控制。有配置时连接你的 GrowthBook 实例拉取并缓存 feature 值，无配置时所有 feature 读取直接返回代码中的默认值，零网络请求。

正文

环境变量

变量	必填	说明
`CLAUDE_GB_ADAPTER_URL`	是	GrowthBook API 地址，如 `https://gb.example.com/`
`CLAUDE_GB_ADAPTER_KEY`	是	GrowthBook SDK Client Key，如 `sdk-xxxxx`

两个变量都设置时启用适配器模式，否则完全跳过 GrowthBook。

使用方式

基本用法

CLAUDE_GB_ADAPTER_URL=https://gb.example.com/ \
CLAUDE_GB_ADAPTER_KEY=sdk-abc123 \
bun run dev

不使用 GrowthBook（默认行为）

bun run dev
# 所有 getFeatureValue_CACHED_MAY_BE_STALE("xxx", defaultValue) 直接返回 defaultValue

GrowthBook 服务端配置

部署 GrowthBook 服务端（Docker 自托管或 Cloud 版）
创建 Environment（如 production）
创建 SDK Connection，获得 SDK Key（即 CLAUDE_GB_ADAPTER_KEY）
按需添加 Feature，key 和类型见下方列表

Tip

核心原则：不配置任何 feature 也能正常运行——代码中每个调用都提供了默认值。只创建你想远程控制的 feature，其余走代码默认。GrowthBook 上配了某个 feature 后，其值会覆盖代码中的默认值。

Feature Key 列表

高频使用

Feature Key	类型	代码默认值	用途
`tengu_hive_evidence`	boolean	`false`	任务证据系统
`tengu_quartz_lantern`	boolean	`false`	文件写入/编辑保护
`tengu_auto_background_agents`	boolean	`false`	自动后台 Agent
`tengu_agent_list_attach`	boolean	`false`	Agent 列表附件
`tengu_amber_stoat`	boolean	`true`	内置 Agents
`tengu_slim_subagent_claudemd`	boolean	`true`	子 Agent CLAUDE.md
`tengu_attribution_header`	boolean	`true`	API 归因 Header
`tengu_cobalt_harbor`	boolean	`false`	Bridge 模式
`tengu_ccr_bridge`	boolean	`false`	CCR Bridge
`tengu_cicada_nap_ms`	number	`0`	后台刷新节流（毫秒）
`tengu_miraculo_the_bard`	boolean	`false`	启动欢迎信息

Agent / 工具控制

Feature Key	类型	代码默认值	用途
`tengu_surreal_dali`	boolean	`false`	远程触发工具
`tengu_glacier_2xr`	boolean	`false`	工具搜索增强
`tengu_plum_vx3`	boolean	`false`	Web Search 使用 Haiku
`tengu_destructive_command_warning`	boolean	`false`	危险命令警告
`tengu_birch_trellis`	boolean	`true`	Bash 权限控制
`tengu_harbor_permissions`	boolean	`false`	Harbor 权限模式

Bridge / 远程连接

Feature Key	类型	代码默认值	用途
`tengu_bridge_repl_v2`	boolean	`false`	Bridge REPL v2
`tengu_copper_bridge`	boolean	`false`	Copper Bridge
`tengu_ccr_mirror`	boolean	`false`	CCR Mirror

内存 / 上下文

Feature Key	类型	代码默认值	用途
`tengu_coral_fern`	boolean	`false`	内存目录功能
`tengu_passport_quail`	boolean	`false`	内存路径配置
`tengu_slate_thimble`	boolean	`false`	Slate Thimble
`tengu_herring_clock`	boolean	`false`	跳过索引
`tengu_session_memory`	boolean	`false`	会话内存
`tengu_pebble_leaf_prune`	boolean	`false`	内存修剪

UI / 体验

Feature Key	类型	代码默认值	用途
`tengu_terminal_sidebar`	boolean	`false`	终端侧边栏
`tengu_terminal_panel`	boolean	`false`	终端面板
`tengu_willow_mode`	boolean	`false`	Willow 模式
`tengu_collage_kaleidoscope`	boolean	`false`	UI 效果
`tengu_chrome_auto_enable`	boolean	`false`	Chrome 自动启用
`tengu_immediate_model_command`	boolean	`false`	即时模型切换
`tengu_remote_backend`	boolean	`false`	远程后端

配置对象（动态配置）

Feature Key	类型	代码默认值	用途
`tengu_file_read_limits`	object	`null`	文件读取限制配置
`tengu_cobalt_raccoon`	object	`null`	Cobalt 配置
`tengu_cobalt_lantern`	object	`null`	Lantern 配置
`tengu_desktop_upsell`	object	`null`	桌面版引导
`tengu_marble_sandcastle`	object	`null`	Marble 配置
`tengu_marble_fox`	object	`null`	Marble Fox 配置
`tengu_ultraplan_model`	string	`null`	Ultraplan 模型名

Gate（布尔门控）

Gate Key	代码默认值	用途
`tengu_chair_sermon`	`false`	功能门控
`tengu_scratch`	`false`	Scratch 功能
`tengu_thinkback`	`false`	Thinkback 功能
`tengu_tool_pear`	`false`	Tool Pear 功能

读取优先级链

每个 feature 的值按以下顺序解析，第一个命中即返回：

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

缓存与刷新机制

机制	说明
磁盘缓存	`~/.claude.json` 的 `cachedGrowthBookFeatures` 字段，跨进程持久化
周期刷新	每 6 小时自动从服务器拉取最新值（`setInterval` + `unref`）
初始化超时	首次连接超时 5 秒，超时后使用磁盘缓存或默认值
Auth 变更	登录/登出时自动销毁并重建客户端

实现细节

修改了 2 个文件共 3 处：

src/constants/keys.ts — getGrowthBookClientKey() 优先读取 CLAUDE_GB_ADAPTER_KEY
src/services/analytics/growthbook.ts — isGrowthBookEnabled() 适配器模式下直接启用
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 - 三层门禁系统全景

6.5 KiB Raw Blame History Unescape Escape