gemini-cli 扩展主题机制实战用 themes-example 示例扩展为终端注入自定义配色【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli本文以 gemini-cli 仓库内置的 themes-example 示例扩展为核心完整讲解通过扩展贡献自定义主题这一机制从gemini-extension.json中的主题字段定义、~/.gemini/settings.json与/theme命令两种启用方式到ThemeManager中主题命名空间化、注册/注销生命周期与调色板自动补全的源码实现。读完本文你可以独立编写自己的主题扩展并准确理解每个颜色字段在 UI 中最终映射到了哪些元素。一、themes-example一个最小可运行的主题扩展仓库中提供了一个专门演示用扩展添加主题的最小示例位于 themes-example 目录只包含两个文件说明文档 README.md 与扩展清单 gemini-extension.json。按其 README 给出的三步流程操作1. 链接link扩展在仓库根目录下执行gemini extensions link packages/cli/src/commands/extensions/examples/themes-examplelink命令将一个本地目录注册为扩展适合在本地开发、调试自己的主题扩展。2. 在设置文件中指定主题将以下配置写入用户级设置文件~/.gemini/settings.json{ ui: { theme: shades-of-green (themes-example) } }注意主题值的格式是主题名 (扩展名)的命名空间写法。这个格式并非文档约定俗成的建议而是源码强制生成的ThemeManager.registerExtensionThemes在注册扩展主题时会统一构造namespacedName \${customThemeConfig.name} (${extensionName})见 [theme-manager.ts](https://link.gitcode.com/i/a018481104698b4746b7c48ba4dcac5e)因此设置文件里必须带上(themes-example)后缀才能被findThemeByName 命中。3. 通过交互界面切换替代方式不手动改 JSON 也可以运行gemini进入交互模式后输入/theme并回车在主题选择界面中会看到扩展主题被归类到Custom分区内置主题按 dark/light/ansi 排序custom 主题固定排在最后排序逻辑见getAvailableThemestheme-manager.ts。4. 观察效果设置生效后UI 会立即呈现该主题定义的颜色体系深绿色背景#1a362a、更亮的主文本#a6e3a1以及边框、状态色等一组绿色系配色全部由gemini-extension.json中声明的字段决定。二、逐字段解读 gemini-extension.json 的主题定义示例扩展的完整清单如下{ name: themes-example, version: 1.0.0, themes: [ { name: shades-of-green, type: custom, background: { primary: #1a362a }, text: { primary: #a6e3a1, secondary: #6e8e7a, link: #89e689 }, status: { success: #76c076, warning: #d9e689, error: #b34e4e }, border: { default: #4a6c5a }, ui: { comment: #6e8e7a } } ] }清单文件在磁盘上的数据结构由ExtensionConfig接口描述其中themes?: CustomTheme[]字段注释明确写道Custom themes contributed by this extension. These themes will be registered when the extension is activated.见 extension.ts。CustomTheme的完整字段定义位于 core 包见 config.ts结合示例可整理出如下对照表字段类型在示例中的值说明namestringshades-of-green主题名最终显示/引用时会自动追加扩展名后缀校验要求非空且不超过 50 字符isValidThemeNametypecustomcustom主题类型扩展贡献的主题固定为 custombackground.primary颜色#1a362a主背景色是整个主题的锚点色多个派生色由它插值计算text.primary颜色#a6e3a1主文本前景色text.secondary颜色#6e8e7a次要文本同时参与输入框/消息区背景的插值计算text.link颜色#89e689链接色同时映射到 AccentBlue / AccentCyan / LightBluestatus.success颜色#76c076成功状态色同时作为 AccentGreen 与聚焦背景插值的目标色status.warning颜色#d9e689警告状态色映射到 AccentYellowstatus.error颜色#b34e4e错误状态色映射到 AccentRedborder.default颜色#4a6c5a默认边框色ui.comment颜色#6e8e7a注释文本色代码高亮中的 hljs-comment 等除示例用到的字段外CustomTheme还支持text.accent、text.response、background.diff.added/removed、ui.symbol、ui.active、ui.focus、ui.gradient等可选字段全部字段均可省略。三、源码解析扩展主题如何注册进 ThemeManager扩展的主题并不是简单地合并进设置而是走一条独立的注册通道。ThemeManager单例themeManager见 theme-manager.ts内部维护四个主题池内置主题数组availableThemesDefaultDark、GitHubDark、Dracula、AyuLight 等 19 个内置主题、设置主题settingsThemes、扩展主题extensionThemes与文件主题fileThemes。registerExtensionThemes(extensionName, customThemes)对每个主题执行四步theme-manager.ts命名空间化生成${主题名} (${扩展名})使不同扩展可以提供同名主题而不冲突冲突检测若命名空间名与某个内置主题重名写入 debug 日志并跳过防御性检查校验validateCustomTheme检查主题名合法性非法主题被拒绝并记录警告默认值补全以...DEFAULT_THEME.colors为底叠加主题配置后调用createCustomTheme生成完整Theme对象存入extensionThemes。注销侧对应unregisterExtensionThemes按同样的命名空间名逐个删除theme-manager.tshasExtensionThemes则通过检查键名是否以(${extensionName})结尾来判断某扩展是否已有注册主题。注册时机启动时提前注册extension-manager.ts 中有两处注册点扩展启动路径extension.themes !themeManager.hasExtensionThemes(extension.name)时调用registerExtensionThemes约 L593hasExtensionThemes的防重复判断保证重载reload时不会重复注册启动早期路径start阶段遍历已激活扩展Register extension themes early so theyre available at startup约 L653 的注释确保用户设置中已指向扩展主题时首次渲染就能取到。测试用例 extension-manager-themes.spec.ts 从两端印证了这一生命周期should register themes from an extension when started断言扩展start时registerExtensionThemes被以扩展名和完整主题对象调用should revert to default theme when extension is stopped先将激活主题设为My-Awesome-Theme (my-theme-extension)再disableExtension断言激活主题自动回退到DEFAULT_THEME——即禁用提供主题的扩展后UI 不会停留在一个已注销的悬空主题上。四、从 6 个颜色到完整调色板createCustomTheme 的补全机制示例主题只声明了 7 个颜色但Theme对象需要一个完整的ColorsThemeBackground、Foreground、AccentBlue、Gray、DarkGray、InputBackground……与一整套代码高亮映射。这一扩写工作由createCustomTheme完成theme.ts核心规则语义色到渲染色的映射text.primary→Foregroundtext.link同时填充LightBlue/AccentBlue/AccentCyanstatus.success/warning/error分别填充AccentGreen/AccentYellow/AccentRedtext.secondary→Grayui.comment→Comment插值派生未显式声明的DarkGray、InputBackground、MessageBackground由interpolateColor(background.primary, text.secondary, opacity)在背景色与次要文本色之间按比例混合生成interpolateColor基于 tinygradient 实现theme.tsFocusBackground则向status.success插值示例中显式声明的border.default会直接覆盖派生的DarkGray语法高亮自动生成hljs-keyword、hljs-string、hljs-comment等几十条 highlight.js 类名到颜色的映射例如关键字用 AccentBlue、字符串用 AccentYellow、注释用 Comment 并斜体语义令牌同步生成SemanticColorstext / background / border / ui / status 五组供 Ink 组件按语义取色。resolveColortheme.ts负责把颜色值归一化支持#RGB/#RRGGBB、Ink 内置 16 色名black、greenbright 等、以及任意 CSS 颜色名经 tinycolor 转 hex所以主题配置里既能写#1a362a也能写green。五、主题查找顺序与终端背景适配当设置文件写入theme: shades-of-green (themes-example)后findThemeByName的查找顺序是内置主题 → 路径型主题以.json结尾或绝对路径时从文件加载且限制必须位于用户 home 目录下见 theme-manager.ts→settingsThemes→extensionThemes→fileThemestheme-manager.ts。扩展主题命中extensionThemes分支。两个值得注意的运行时细节终端背景适配若检测到终端背景色且与主题明暗兼容isThemeCompatible按背景亮度判断 light/darkgetColors会用真实终端背景替换Background并重新插值DarkGray/InputBackground/MessageBackground/FocusBackgroundtheme-manager.ts使自定义主题能贴合你的终端底色NO_COLOR 覆盖设置了NO_COLOR环境变量时getActiveTheme无条件返回NoColorThemetheme-manager.ts扩展主题同样不生效——在无彩输出、日志重定向等场景下这是刻意行为。六、小结与可深入的路径themes-example 用不到 30 行的 JSON 演示了 gemini-cli 扩展体系的主题贡献能力扩展清单声明themes数组 →ExtensionManager在扩展激活时调用themeManager.registerExtensionThemes完成命名空间化注册 →createCustomTheme将少量语义色扩写为完整调色板 → 通过ui.theme设置或/theme命令激活禁用扩展时激活主题自动回退默认值。如需继续深入建议按以下路径阅读示例扩展本身README.md、gemini-extension.json扩展清单结构extension.ts主题生命周期测试extension-manager-themes.spec.ts主题管理核心theme-manager.ts调色板生成与颜色解析theme.tsCustomTheme 类型定义config.ts内置主题实现可参考 docs/cli/themes.md 中的主题文档与packages/cli/src/ui/themes/builtin/目录【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 gemini-cli 扩展主题机制实战：用 themes-example 示例扩展为终端注入自定义配色
gemini-cli 扩展主题机制实战用 themes-example 示例扩展为终端注入自定义配色【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli本文以 gemini-cli 仓库内置的 themes-example 示例扩展为核心完整讲解通过扩展贡献自定义主题这一机制从gemini-extension.json中的主题字段定义、~/.gemini/settings.json与/theme命令两种启用方式到ThemeManager中主题命名空间化、注册/注销生命周期与调色板自动补全的源码实现。读完本文你可以独立编写自己的主题扩展并准确理解每个颜色字段在 UI 中最终映射到了哪些元素。一、themes-example一个最小可运行的主题扩展仓库中提供了一个专门演示用扩展添加主题的最小示例位于 themes-example 目录只包含两个文件说明文档 README.md 与扩展清单 gemini-extension.json。按其 README 给出的三步流程操作1. 链接link扩展在仓库根目录下执行gemini extensions link packages/cli/src/commands/extensions/examples/themes-examplelink命令将一个本地目录注册为扩展适合在本地开发、调试自己的主题扩展。2. 在设置文件中指定主题将以下配置写入用户级设置文件~/.gemini/settings.json{ ui: { theme: shades-of-green (themes-example) } }注意主题值的格式是主题名 (扩展名)的命名空间写法。这个格式并非文档约定俗成的建议而是源码强制生成的ThemeManager.registerExtensionThemes在注册扩展主题时会统一构造namespacedName \${customThemeConfig.name} (${extensionName})见 [theme-manager.ts](https://link.gitcode.com/i/a018481104698b4746b7c48ba4dcac5e)因此设置文件里必须带上(themes-example)后缀才能被findThemeByName 命中。3. 通过交互界面切换替代方式不手动改 JSON 也可以运行gemini进入交互模式后输入/theme并回车在主题选择界面中会看到扩展主题被归类到Custom分区内置主题按 dark/light/ansi 排序custom 主题固定排在最后排序逻辑见getAvailableThemestheme-manager.ts。4. 观察效果设置生效后UI 会立即呈现该主题定义的颜色体系深绿色背景#1a362a、更亮的主文本#a6e3a1以及边框、状态色等一组绿色系配色全部由gemini-extension.json中声明的字段决定。二、逐字段解读 gemini-extension.json 的主题定义示例扩展的完整清单如下{ name: themes-example, version: 1.0.0, themes: [ { name: shades-of-green, type: custom, background: { primary: #1a362a }, text: { primary: #a6e3a1, secondary: #6e8e7a, link: #89e689 }, status: { success: #76c076, warning: #d9e689, error: #b34e4e }, border: { default: #4a6c5a }, ui: { comment: #6e8e7a } } ] }清单文件在磁盘上的数据结构由ExtensionConfig接口描述其中themes?: CustomTheme[]字段注释明确写道Custom themes contributed by this extension. These themes will be registered when the extension is activated.见 extension.ts。CustomTheme的完整字段定义位于 core 包见 config.ts结合示例可整理出如下对照表字段类型在示例中的值说明namestringshades-of-green主题名最终显示/引用时会自动追加扩展名后缀校验要求非空且不超过 50 字符isValidThemeNametypecustomcustom主题类型扩展贡献的主题固定为 custombackground.primary颜色#1a362a主背景色是整个主题的锚点色多个派生色由它插值计算text.primary颜色#a6e3a1主文本前景色text.secondary颜色#6e8e7a次要文本同时参与输入框/消息区背景的插值计算text.link颜色#89e689链接色同时映射到 AccentBlue / AccentCyan / LightBluestatus.success颜色#76c076成功状态色同时作为 AccentGreen 与聚焦背景插值的目标色status.warning颜色#d9e689警告状态色映射到 AccentYellowstatus.error颜色#b34e4e错误状态色映射到 AccentRedborder.default颜色#4a6c5a默认边框色ui.comment颜色#6e8e7a注释文本色代码高亮中的 hljs-comment 等除示例用到的字段外CustomTheme还支持text.accent、text.response、background.diff.added/removed、ui.symbol、ui.active、ui.focus、ui.gradient等可选字段全部字段均可省略。三、源码解析扩展主题如何注册进 ThemeManager扩展的主题并不是简单地合并进设置而是走一条独立的注册通道。ThemeManager单例themeManager见 theme-manager.ts内部维护四个主题池内置主题数组availableThemesDefaultDark、GitHubDark、Dracula、AyuLight 等 19 个内置主题、设置主题settingsThemes、扩展主题extensionThemes与文件主题fileThemes。registerExtensionThemes(extensionName, customThemes)对每个主题执行四步theme-manager.ts命名空间化生成${主题名} (${扩展名})使不同扩展可以提供同名主题而不冲突冲突检测若命名空间名与某个内置主题重名写入 debug 日志并跳过防御性检查校验validateCustomTheme检查主题名合法性非法主题被拒绝并记录警告默认值补全以...DEFAULT_THEME.colors为底叠加主题配置后调用createCustomTheme生成完整Theme对象存入extensionThemes。注销侧对应unregisterExtensionThemes按同样的命名空间名逐个删除theme-manager.tshasExtensionThemes则通过检查键名是否以(${extensionName})结尾来判断某扩展是否已有注册主题。注册时机启动时提前注册extension-manager.ts 中有两处注册点扩展启动路径extension.themes !themeManager.hasExtensionThemes(extension.name)时调用registerExtensionThemes约 L593hasExtensionThemes的防重复判断保证重载reload时不会重复注册启动早期路径start阶段遍历已激活扩展Register extension themes early so theyre available at startup约 L653 的注释确保用户设置中已指向扩展主题时首次渲染就能取到。测试用例 extension-manager-themes.spec.ts 从两端印证了这一生命周期should register themes from an extension when started断言扩展start时registerExtensionThemes被以扩展名和完整主题对象调用should revert to default theme when extension is stopped先将激活主题设为My-Awesome-Theme (my-theme-extension)再disableExtension断言激活主题自动回退到DEFAULT_THEME——即禁用提供主题的扩展后UI 不会停留在一个已注销的悬空主题上。四、从 6 个颜色到完整调色板createCustomTheme 的补全机制示例主题只声明了 7 个颜色但Theme对象需要一个完整的ColorsThemeBackground、Foreground、AccentBlue、Gray、DarkGray、InputBackground……与一整套代码高亮映射。这一扩写工作由createCustomTheme完成theme.ts核心规则语义色到渲染色的映射text.primary→Foregroundtext.link同时填充LightBlue/AccentBlue/AccentCyanstatus.success/warning/error分别填充AccentGreen/AccentYellow/AccentRedtext.secondary→Grayui.comment→Comment插值派生未显式声明的DarkGray、InputBackground、MessageBackground由interpolateColor(background.primary, text.secondary, opacity)在背景色与次要文本色之间按比例混合生成interpolateColor基于 tinygradient 实现theme.tsFocusBackground则向status.success插值示例中显式声明的border.default会直接覆盖派生的DarkGray语法高亮自动生成hljs-keyword、hljs-string、hljs-comment等几十条 highlight.js 类名到颜色的映射例如关键字用 AccentBlue、字符串用 AccentYellow、注释用 Comment 并斜体语义令牌同步生成SemanticColorstext / background / border / ui / status 五组供 Ink 组件按语义取色。resolveColortheme.ts负责把颜色值归一化支持#RGB/#RRGGBB、Ink 内置 16 色名black、greenbright 等、以及任意 CSS 颜色名经 tinycolor 转 hex所以主题配置里既能写#1a362a也能写green。五、主题查找顺序与终端背景适配当设置文件写入theme: shades-of-green (themes-example)后findThemeByName的查找顺序是内置主题 → 路径型主题以.json结尾或绝对路径时从文件加载且限制必须位于用户 home 目录下见 theme-manager.ts→settingsThemes→extensionThemes→fileThemestheme-manager.ts。扩展主题命中extensionThemes分支。两个值得注意的运行时细节终端背景适配若检测到终端背景色且与主题明暗兼容isThemeCompatible按背景亮度判断 light/darkgetColors会用真实终端背景替换Background并重新插值DarkGray/InputBackground/MessageBackground/FocusBackgroundtheme-manager.ts使自定义主题能贴合你的终端底色NO_COLOR 覆盖设置了NO_COLOR环境变量时getActiveTheme无条件返回NoColorThemetheme-manager.ts扩展主题同样不生效——在无彩输出、日志重定向等场景下这是刻意行为。六、小结与可深入的路径themes-example 用不到 30 行的 JSON 演示了 gemini-cli 扩展体系的主题贡献能力扩展清单声明themes数组 →ExtensionManager在扩展激活时调用themeManager.registerExtensionThemes完成命名空间化注册 →createCustomTheme将少量语义色扩写为完整调色板 → 通过ui.theme设置或/theme命令激活禁用扩展时激活主题自动回退默认值。如需继续深入建议按以下路径阅读示例扩展本身README.md、gemini-extension.json扩展清单结构extension.ts主题生命周期测试extension-manager-themes.spec.ts主题管理核心theme-manager.ts调色板生成与颜色解析theme.tsCustomTheme 类型定义config.ts内置主题实现可参考 docs/cli/themes.md 中的主题文档与packages/cli/src/ui/themes/builtin/目录【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考