Themes
Gemini CLI themes 的用途：终端 UI 个性化、可读性和团队教程截图一致性。
Themes 影响 Gemini CLI 的终端显示。它不是核心能力，但会影响长时间使用的可读性。
主题配置的目标是可读和一致，不是把教程截图做得花哨。终端工具最重要的是文本、diff、warning 和 error 都能看清。
可以通过 /theme 交互选择，也可以在 settings.json 的 ui.theme 或 ui.customThemes 固定。官方内置深色和浅色主题，也支持 extension 提供主题。
什么时候需要配置主题
- 深色/浅色终端不匹配。
- 录屏或截图需要统一风格。
- 字体颜色在当前终端里不清晰。
- 团队教程要保持截图一致。
配置方式
交互方式：
/theme如果 settings.json 里已经固定了 ui.theme，需要先移除该配置，否则 /theme 中的交互选择可能不会覆盖文件里的配置。
自定义主题放在 ui.customThemes，至少要定义 name、type: "custom"、背景色和主要文字色。也可以把主题放在独立 JSON 文件里，再在 ui.theme 指向该文件路径。出于安全考虑，Gemini CLI 只会加载位于用户 home 目录内的主题文件。
官方主题变量不只影响普通文字。常见变量包括 Background、Foreground、AccentBlue、AccentPurple、AccentCyan、AccentGreen、AccentYellow、AccentRed、Comment、Gray，以及用于 diff 的 DiffAdded、DiffRemoved、DiffModified。如果主题没有覆盖关键状态色，代码修改和错误提示会很难读。
一个稳定的教程主题至少要检查三类画面：普通对话、工具确认、diff 展示。只看欢迎页好不好看没有意义，真正影响学习体验的是 warning、error、added、removed 这些状态是否清晰。
教程截图建议
教程站不要追求花哨主题，优先选对比度稳定、浅深色都可读的主题。截图前固定主题、终端字体和窗口宽度，否则同一篇教程里 UI 变化会显得不专业。
| 场景 | 推荐做法 | 避免 |
|---|---|---|
| 教程截图 | 固定主题、字体、窗口宽度 | 每张图随机主题 |
| 长时间编码 | 选择对比度稳定的主题 | 低对比度彩色主题 |
| 团队文档 | 用项目文档记录截图环境 | 只靠个人终端偏好 |
| 自定义主题 | 先检查 warning、error、diff 色 | 只看普通文本 |
如果教程面向新手，主题更应该接近默认体验。过度自定义会让读者打开自己的终端后找不到对应 UI 状态。
不要过度投入
主题不会提升 agent 质量。先把上下文、权限、工具、验证流程做好，再调视觉。
如果主题只是个人偏好，放用户级 settings；只有教程录屏、团队截图规范或共享开发环境需要一致时，才考虑写入项目文档。不要因为自己喜欢某个颜色，就把 ui.theme 固定进仓库级配置。
常见排错
主题不生效时，先看 settings.json 里是否已经固定 ui.theme。如果文件里写死了主题，/theme 的交互选择可能不会覆盖这个配置。第二步检查自定义主题文件是否在 home 目录内；官方出于安全原因不会从任意路径加载主题 JSON。
颜色看不清时，不要只调背景色。优先检查 Foreground、Comment、AccentRed、AccentYellow 和 diff 相关变量。warning、error、diff 删除行是教程截图里最容易出问题的地方。
截图验收清单
教程站截图要固定三件事：终端宽度、字体大小、主题名称。每次换主题后，至少截一张普通对话、一张命令确认、一张文件 diff。三张都清楚，才说明主题适合教学内容。
如果页面要给读者复制配置，建议同时说明这是视觉配置，不影响模型能力、配额、上下文和工具权限。新手最容易把 UI 变化误解成“模型模式变化”，这一点要在教程里主动消除。
主题只服务可读性，不应承担功能解释，也不应掩盖真实命令输出和错误信息。
验收方式
运行 /theme 确认可选列表里出现预期主题。自定义主题要同时检查普通文本、代码块、diff added/removed、warning/error 状态色，确保录屏和截图中不会看不清。
接下来去哪
Trusted folders
UI 配置结束后，继续看 workspace 信任和安全边界。
Settings
主题最终要回到 settings.json 固化。
Local development
如果是录屏或教程环境，继续看本地开发配置。