Claude Code SDK 会话状态指示器（Footer Indicator）Schema 深度解析：环境变量、模型能力与 Bootstrap 缓存的三级来源及 system/init 投递机制

• 文档
• 提示工程
• 人工智能

Claude Code 终端提示符页脚中的 "◆" 状态药丸（status pill）并非仅由本地终端决定：它遵循一条明确定义的三级来源优先级链（CLAUDE_CODE_FOOTER_INDICATOR环境变量、主模型的footer_indicator_<text>能力、bootstrap 缓存中的client_data），并随 SDK 的system/init消息与initialize响应投递给宿主 UI（Claude Desktop、IDE webview 等），使其渲染与终端完全一致的药丸。本文基于仓库中的 schema 文档 Data: SDK footer indicator schema，完整解析其三个配置来源、优先级顺序、投递通道以及缓存生效时机的细节，帮助 SDK 宿主开发者与运维人员准确实现状态药丸的渲染与配置验证。

1. 背景：本仓库与文档出处

本仓库（claude-code-system-prompts）收录的是从 Claude Code npm 包编译产物中提取的全部系统提示词与内嵌模板，由 Piebald AI 维护，覆盖 Claude Code v2.0.14 以来的 300 余个版本；README.md 指出仓库当前收录的是Claude Code v2.1.292的提示词全集，而 CLAUDE.md 说明这些文件是"提取的参考资料"，模板变量（如${BASH_TOOL_NAME}）在运行时才被插值，因此文件内出现的字面量变量应视为占位符。

本文解析的 Data: SDK footer indicator schema 属于仓库system-prompts/目录下的Data 类条目——即 Claude Code 内嵌模板/协议字段的 schema 描述，文档 frontmatter 中标注的ccVersion为2.1.286，代表该 schema 文本对应这一版本时期的行为。由于该 schema 描述的是 SDK 会话启动阶段的消息字段，它与同目录中另外两份 SDK 启动期文档直接相关：

• Data: SDK system init plugin_errors field——同一system/init消息上的插件加载错误数组；
• Data: SDK initialize response sdk_mcp_manifests_parked field——initialize响应上的另一个字段示例。

这三份文档共同说明一个模式：Claude Code 把会话启动期的状态信息统一收敛到system/init与initialize两条消息通道上，供宿主程序消费。

2. Footer Indicator 是什么：终端页脚的状态药丸

按照 Data: SDK footer indicator schema 的定义，session indicator（会话指示器）的完整语义如下：

• 呈现形态：终端将其渲染为提示符页脚中的 "◆" 药丸，其中<text>是配置的标签文本；
• 本质属性：这是一条不透明的状态注记（opaque status note），由运维人员按**队列（cohort）**为单位设置。所谓"不透明"，是指它对模型和会话逻辑没有语义——不参与提示词构造，也不影响行为，只是一个展示位；
• 典型用途：文档给出的例子是"证明某个测试配置确实到达了该会话"。也就是说，它首先是一个运维/发布验证工具：运维团队为某一批会话配置一个独特标签后，可以通过药丸是否出现来确认配置下发链路（环境变量注入、模型服务端配置、bootstrap 缓存）已经生效；
• 缺席语义：当三个来源都没有配置时，该字段整体缺席（而非空字符串），宿主此时应当不渲染任何东西。

这一点很关键：宿主实现必须把"字段缺失"与"字段为空"区分开——缺失代表"未配置，什么都不画"，而不是渲染一个只有 "◆" 的空药丸。

3. 三级配置来源与优先级

Schema 文档以"else"句式给出了完整的取值优先级链，按从高到低排列为：

三个来源的设计意图可以结合仓库中的版本演进理解。查阅 CHANGELOG.md 可以看到两个关键节点：

1. 首次收录（早期版本，CHANGELOG 标注为 NEW）："描述由操作员设置的、随system/init与initialize投递的状态药丸，使宿主 UI 能够渲染终端页脚所展示的内容"；
2. v2.1.286："为 footer indicator 增加了主模型的footer_indicator_<text>能力来源，位于环境变量与 bootstrapclient_data之间"。

也就是说，第二级来源（模型能力）是在 2.1.286 版本插入到环境变量与client_data之间的。这与文档 frontmatter 的ccVersion: 2.1.286相互印证——当前收录的 schema 文本正是该能力加入之后的形态。从版本顺序可以推断：最初只有环境变量和 bootstrapclient_data两级来源，模型能力级是为了让服务端（而非本地环境）也能按队列控制药丸而引入的，且其优先级被刻意压低于环境变量，保证本地显式配置永远能覆盖服务端配置。

从源码结构看，第二级来源的标签是内嵌在能力名里的（footer_indicator_<text>，<text>为具体标签文本），即能力清单中每出现一个形如footer_indicator_xxx的能力名，就对应一个候选标签；这与 Claude Code 网关协议中按模型下发能力清单的既有机制是同一类设计（可参考 Data: Claude Code gateway protocol 中模型发现与能力声明的章节）。

4. 投递通道：system/init 与 initialize 响应

药丸值在会话启动阶段有两条对外投递通道，文档原文为 "Carried onsystem/initand theinitializeresponse"：

• system/init消息：SDK 会话建立时发出的系统级初始化消息。同一消息上还携带其他启动期状态字段，例如插件加载错误（见 Data: SDK system init plugin_errors field，其中plugin_errors数组采用同样的"干净时省略该键"的缺席语义，且文档建议 CI 用(plugin_errors?.length ?? 0) > 0判断是否失败）；
• initialize响应：客户端initialize请求的应答体，同样携带启动期状态，例如sdk_mcp_manifests_parked字段（见 Data: SDK initialize response sdk_mcp_manifests_parked field）。

设计目标是明确的：让宿主 UI（文档点名 Claude Desktop、IDE webview）能够渲染与终端页脚相同的药丸。由于宿主进程并不直接拥有终端渲染权，它只能依赖 SDK 消息里的字段来复刻这个视觉状态，因此该字段属于"宿主应当原样转绘"的展示型数据，而不是可被模型解释的上下文。

对宿主实现的要点可以归纳为：

1. 在system/init与initialize响应两处都解析该字段（两个通道都携带，避免只监听其一导致某些宿主模式缺失）；
2. 字段存在 → 按 "◆" 规则渲染药丸；
3. 字段缺席 → 不渲染任何占位内容。

5. 缓存语义：为什么标签可能"晚一拍"才出现

Schema 中最容易被忽视、也最容易踩坑的一点是第三级来源的读取时机。文档原文指出：

The client_data source is read from the CLI's cached bootstrap data, so a label configured there after that cache was last written first appears on a latersystem/init.

拆解其含义：

• client_data.footer_indicator不是实时读取远端配置的，而是读取 CLI 本地缓存的 bootstrap 数据（bootstrap 数据是会话启动时缓存下来的引导信息）；
• 因此，如果运维在缓存最后一次写入之后才在 bootstrap 端配置了新的标签，本次会话读到的仍是旧值（或空值）；
• 新标签最早要在下一次system/init（即下一会话/下一次重新初始化）才会出现。

这一缓存语义对"证明配置到达会话"这一核心用途有直接影响：验证流程不能假设"刚配完就能在当前会话看到"，而应把验证动作放在新会话里执行，或先确认 bootstrap 缓存已刷新。相较之下，第一级来源（环境变量）是进程级即时生效的，适合作为需要立刻可见的调试通道；第二级来源（模型能力）随模型能力清单下发，同样不走 CLI 本地缓存。

6. 适用前提与边界说明

基于仓库文档，以下几点应作为使用与解读前提：

• 版本前提：本文描述的三级来源形态对应 v2.1.286 及之后的行为（第二级来源由该版本引入）；仓库当前整体收录版本为 v2.1.292（见 README.md），两者之间 CHANGELOG.md 未再记录该 schema 的变更，可以认为当前版本仍维持三级优先级；
• 不透明性：该字段是展示层数据，对模型侧的提示词、工具行为均无影响，运维不应依赖它传递任何语义信息给模型；
• 缺席即未配置：与同族的plugin_errors等启动期字段一样，Claude Code 的 SDK 启动字段普遍采用"有问题/有值才出现"的省略式 schema，宿主的健壮性检查应基于键的存在性而非默认值；
• 文档性质：本仓库文件为提取的参考文本（CLAUDE.md 强调修改这些文件不会改变 Claude Code 行为），字段最终行为以实际运行的 Claude Code 版本为准。

7. 小结

Data: SDK footer indicator schema 以极短的篇幅定义了一个完整的启动期字段契约：三级来源（环境变量 > 主模型footer_indicator_<text>能力 > 缓存 bootstrap 的client_data.footer_indicator）、双通道投递（system/init与initialize响应）、缺席即不渲染的展示语义，以及一条关键的缓存滞后规则（client_data来源的新标签最早在下一轮system/init生效）。对 SDK 宿主开发者而言，它是实现"与终端一致的状态药丸"的规范依据；对运维而言，它解释了为什么按队列下发的标签会延迟一个会话才可见，并指明了用环境变量做即时验证的路径。

• 文档
• 提示工程
• 人工智能