企业官网建设流程全解析

Windows Terminal 之 ColorTool：从 iTerm 主题到控制台配色表的控制台调色工具完整指南

【免费下载链接】terminalThe new Windows Terminal and the original Windows console host, all in the same place!项目地址: https://gitcode.com/GitHub_Trending/term/terminal

ColorTool 是 Windows Terminal 仓库（src/tools/ColorTool）中自带的一个独立 .NET 工具，它把 Windows 控制台的 16 色调色板与 iTerm2 主题、JSON 配色文件打通：一条命令即可把.ini、.json或.itermcolors配色方案应用到当前控制台、系统注册表默认值、支持 VT 转义序列的终端（含 WSL），或直接生成可粘贴进 Windows Terminalsettings.json的 JSON 色块。读完本文，你能掌握 ColorTool 的完整命令行用法、三种方案文件的格式细节与查找规则、四种输出目标背后的注册表/VT 实现原理，以及如何把自己的配色主题集成进控制台与 Windows Terminal。

一、ColorTool 是什么

按 src/tools/ColorTool/README.md 的定义，ColorTool 用于"帮助你设置 Windows Console 的调色板"：它默认把指定.itermcolors、.json或.ini文件中的颜色应用到当前控制台窗口，但不会自动保存属性——若想持久化，需要打开属性页并点"确定"，或者显式使用-d/-b参数直接写注册表。仓库在schemes/目录中附带了多种格式的方案示例，用户也可以往里添加自己偏好的方案。

理解 ColorTool 的关键背景是 Windows 控制台的16 色调色板：控制台文字颜色只有 16 个固定槽位（8 个暗色 + 8 个亮色），注册表中以ColorTable00～ColorTable15的 DWORD 值保存，而 DWORD 内部的通道排布是 BRG（R 在低字节、B 在高字节）。ColorTool 内部统一用RGB(r, g, b)宏把这个 BRG 值打包成uint，所有解析器和输出目标都围绕这张 16 色表工作（见 ColorScheme.cs）。

二、命令行参考：Functions 与 Options

README 给出的完整用法如下（源自 README.md，并与 Program.cs 中的参数解析逐一对应）：

Usage: ColorTool.exe <Function> ColorTool.exe [Options] <Scheme name> Parameters: <Function> : One and only one of the switches listed in the "Functions" section below. <Scheme name>: The name of a color scheme. ColorTool will try to first load it as an .ini file color scheme If that fails, it will look for it as a .json file color scheme If that fails, it will look for it as a .itermcolors file color scheme. Must be the last parameter passed to ColorTool. [Option] : One or more of the switches listed in the "Options" section below. Must appear before scheme name. Functions: -?, --help : Display this help message -c, --current : Print the color table for the currently applied scheme -v, --version : Display the version number -l, --location : Displays the full path to the schemes directory -s, --schemes : Displays all available schemes -o, --output <filename> : output the current color table to a file in .ini format Options: -q, --quiet : Don't print the color table after applying -e, --errors : Report scheme parsing errors on the console -d, --defaults : Apply the scheme to only the defaults in the registry -b, --both : Apply the scheme to both the current console and the defaults. -x, --xterm : Set the colors using VT sequences. Used for setting the colors in WSL. Only works in Windows versions >= 17048. -t, --terminal : Output the colors in JSON format for copying into a Windows Terminal settings file. -a, --allcolors: Output extended color table. best for >110 column terminals

几个使用要点：

• Function 每次调用只能指定一个，出现第一个功能开关后其余开关被忽略；Option 必须写在方案名之前，方案名必须是最后一个参数（Program.cs 中按args顺序switch解析，args[args.Length - 1]被当作方案名）。
• -o是唯一带参数的功能开关：把当前控制台的颜色表导出为.ini文件，实现在 IniSchemeWriter.cs 中。
• 常用组合示例：
  • 预览某个方案效果（只改当前窗口）：ColorTool.exe campbell
  • 静默应用并写注册表默认值：ColorTool.exe -q -b solarized_dark
  • 在 WSL 中通过 VT 序列改色：ColorTool.exe -x campbell
  • 生成 Windows Terminal 的 JSON 色块：ColorTool.exe -t OneHalfDark
  • 导出当前配色：ColorTool.exe -o mycolors.ini
  • 列出全部方案（带色块预览）：ColorTool.exe -s

三、方案文件格式与查找规则

3.1 解析器机制：先 INI，后 JSON，再 iTerm

SchemeManager.GetScheme依次尝试各解析器，第一个成功解析出非空结果的解析器胜出（SchemeManager.cs）：

public static ColorScheme GetScheme(string schemeName, bool reportErrors = false) { return GetParsers() .Select(parser => parser.ParseScheme(schemeName, reportErrors)) .FirstOrDefault(x => x != null); }

解析器通过反射在程序集中自动发现所有ISchemeParser实现（SchemeManager.cs），接口定义为Name、FileExtension与ParseScheme三个成员（ISchemeParser.cs）。当前有内置三个解析器：INI 解析器、concfg JSON 解析器、iTerm XML 解析器。

3.2 查找路径：7 个候选位置

无论哪种格式，文件查找都走同一套搜索路径（SchemeManager.cs）：

// Search order, for argument "name", where 'exe' is the dir of the exe. // 1. ./name // 2. ./name.ext // 3. ./schemes/name // 4. ./schemes/name.ext // 5. exe/schemes/name // 6. exe/schemes/name.ext // 7. name (as an absolute path)

也就是说，你既可以cd到一个装满*.itermcolors的目录直接运行，也可以把方案放进schemes/目录，或传绝对路径——这正是 README 中"把任意.itermcolors粘贴进schemes/目录，或者先cd到含*.itermcolors文件的目录再运行"这一工作方式的底层依据。

3.3 INI 格式：控制台"属性页"同款格式

IniSchemeParser.cs 通过GetPrivateProfileString读取三个段落：

• [table]：16 个固定键名，顺序即 Windows 调色板顺序（注意是 BRG 排布的 16 色表）：DARK_BLACK、DARK_BLUE、DARK_GREEN、DARK_CYAN、DARK_RED、DARK_MAGENTA、DARK_YELLOW、DARK_WHITE、BRIGHT_BLACK…BRIGHT_WHITE。取值支持R,G,B或#RRGGBB两种写法（ParseColor按首字符是否为#分派）。
• [screen]：FOREGROUND、BACKGROUND、CURSOR。前两个值可以直接引用[table]中的颜色名（如DARK_WHITE），也可以是具体颜色值；解析器会先查颜色名索引，查不到再按颜色值解析（IniSchemeParser.cs）。
• [popup]：弹窗（菜单等）的FOREGROUND/BACKGROUND，同样支持颜色名引用。

以仓库自带的 schemes/campbell.ini 为例，这是一个完整、可直接使用的 INI 方案：

[table] DARK_BLACK = 12,12,12 DARK_BLUE = 0,55,218 DARK_GREEN = 19,161,14 DARK_CYAN = 58,150,221 DARK_RED = 197,15,31 DARK_MAGENTA = 136,23,152 DARK_YELLOW = 193,156,0 DARK_WHITE = 204,204,204 BRIGHT_BLACK = 118,118,118 BRIGHT_BLUE = 59,120,255 BRIGHT_GREEN = 22,198,12 BRIGHT_CYAN = 97,214,214 BRIGHT_RED = 231,72,86 BRIGHT_MAGENTA = 180,0,158 BRIGHT_YELLOW = 249,241,165 BRIGHT_WHITE = 242,242,242 [screen] FOREGROUND = DARK_WHITE BACKGROUND = DARK_BLACK [popup] FOREGROUND = DARK_MAGENTA BACKGROUND = BRIGHT_WHITE [info] name = Campbell author = crloew

如果[table]缺任何一个颜色且开启了-e/--errors，会打印解析错误并放弃该方案；-e参数对应源码中的reportErrors标志，控制是否向控制台报告解析失败原因。

3.4 JSON 格式：concfg 风格

JsonParser.cs（自称 "concfg Parser"）读取旧版控制台 JSON 配色文件。根节点需包含 16 个小写颜色键：black、dark_blue、dark_green、dark_cyan、dark_red、dark_magenta、dark_yellow、gray（对应 Dark White）、dark_gray（对应 Bright Black）、blue、green、cyan、red、magenta、yellow、white。此外还支持两个可选的逗号对：screen_colors（形如"fg_name,bg_name"，引用上面的颜色名）与popup_colors，解析器把这两个名字对映射回调色板索引，得到前景/背景与弹窗颜色（JsonParser.cs）。

3.5 .itermcolors 格式：iTerm2 plist

XmlSchemeParser.cs 解析 iTerm2 的 plist 结构：

• 调色板 16 色的键是"Ansi 0 Color"～"Ansi 15 Color"，注意 ANSI 编号到 Windows 调色板槽位的映射关系（0 黑、4 蓝、2 绿、6 青、1 红、5 紫、3 黄、7 白，亮色为 8 加偏移）；
• 额外支持"Foreground Color"、"Background Color"、"Cursor Color"三个键；
• 每个颜色由"Red Component"/"Green Component"/"Blue Component"三个0～1 的浮点数给出，源码乘以 255 取整（XmlSchemeParser.cs）；
• 找齐 16 个调色板颜色才算解析成功，否则（配合-e）报告InvalidNumberOfColors。

四、四种应用目标：同一个方案，四种落地方式

README 中 Options 的四个"去向"开关（默认当前控制台 /-d/-b/-x/-t）在源码里体现为一组IConsoleTarget实现，由 Program.cs 的GetConsoleTargets()按命令行标志组合出目标列表：

if (setDefaults) { yield return new DefaultConsoleTarget(); } if (setProperties) { if (setUnixStyle) yield return new VirtualTerminalConsoleTarget(); else if (setTerminalStyle) yield return new TerminalSchemeConsoleTarget(); else yield return new CurrentConsoleTarget(); }

注意-x与-t在解析时都会置位setProperties，因此它们与默认行为互斥（VT 模式、Terminal JSON 模式与"直接改当前控制台"三选一），而-d/-b控制是否追加注册表目标。

4.1 当前控制台（默认）

CurrentConsoleTarget通过封装的 Console API（ConsoleAPI.cs）直接改写当前窗口的 16 色表与前后景色。这也是 README 强调"不会自动保存"的原因：改的是窗口级属性，关窗即失。

4.2 注册表默认值（-d/-b）

DefaultConsoleTarget直接写HKEY_CURRENT_USER\Console（DefaultConsoleTarget.cs）：

• ColorTable00～ColorTable15：16 个 DWORD 调色板值（注意键名补零的格式）；
• CursorColor：光标色，方案未定义时写-1（表示用默认）；
• ScreenColors：一个 16 位属性字，低 4 位是前景色索引、高 4 位是背景色索引；
• DefaultForeground/DefaultBackground：只有当颜色在调色板中没有完全相同的槽位时才写入具体 RGB 值，否则写-1让系统用属性字里的索引值；
• PopupColors：弹窗配色属性字。

由于ScreenColors只能存调色板索引而非任意 RGB，ColorTool 在 ColorScheme.cs 里做了"最近邻"计算：把方案的前景色、背景色分别与 16 槽 RGB 值比相似度，取最接近的索引。相似度采用加权 RGB 距离（ColorScheme.cs），绿色通道权重恒为 4，红/蓝通道权重随亮度动态调整——这是比欧氏距离更符合视觉感知的近似度量；源码注释中还保留了 HSV 空间最近邻、L2 距离等备选启发式。

4.3 VT 转义序列（-x，用于 WSL）

VirtualTerminalConsoleTarget不改任何 API，而是直接打印 OSC 序列（VirtualTerminalConsoleTarget.cs）：

• \x1b]10;rgb:RR/GG/BB\x1b\\：前景色；
• \x1b]11;rgb:RR/GG/BB\x1b\\：背景色；
• \x1b]12;rgb:RR/GG/BB\x1b\\：光标色；
• \x1b]4;{i};rgb:RR/GG/BB\x07：对 16 个 ANSI 索引 i 逐个设置调色板颜色。

由于控制台必须先开启ENABLE_VIRTUAL_TERMINAL_PROCESSING模式才能理解这些序列，Program.DoInVTMode（Program.cs）会先保存原ConsoleMode、打开 VT 位、执行动作后再恢复原模式——-s的色块预览也复用了这套机制。这里同样存在 Windows 槽位与 ANSI 索引的换算表（VirtualTerminalConsoleTarget.cs），与 iTerm 解析器中的映射同源。README 注明该模式要求 Windows 版本 ≥ 17048。

4.4 生成 Windows Terminal JSON（-t）

TerminalSchemeConsoleTarget不做任何"应用"，而是打印一段可直接粘进 Windows Terminalsettings.json的schemes数组的 JSON 色块（TerminalSchemeConsoleTarget.cs），键名为 Windows Terminal 认识的black/blue/…/brightWhite加可选的foreground/background/cursorColor，颜色格式为#RRGGBB。它会提示你别忘了在上一条方案后补逗号。这是把社区 iTerm 主题快速搬进 Windows Terminal 的最短路径之一。

五、内置方案与"加方案"实践

schemes/目录（src/tools/ColorTool/schemes/）当前自带 10 个方案文件：

• cmd-legacy.ini：2017 年 7 月之前的 Windows 控制台旧版经典配色；
• campbell.ini：秋季创作者更新起成为控制台默认的 Campbell 配色（另有campbell-legacy.ini、campbell-absolute.ini两个变体）；
• iTerm 格式：OneHalfDark、OneHalfLight、solarized_dark、solarized_light、tango_dark、tango_light、deuteranopia（色盲友好）。

README 建议从社区的 iTerm2-Color-Schemes 仓库（含大量方案与预览图）挑选.itermcolors文件，也可以借助在线配色编辑器 terminal.sexy 的 Import/Export 功能以 iTerm2 格式可视化编辑方案；两者都把文件放进schemes/即可被 ColorTool 识别。

仓库还附带了一个"方案巡礼"脚本 all.bat：遍历schemes\*，逐个套用并pause，一路翻到喜欢的配色后 Ctrl+C 结束即可：

for %%i in (schemes\*) do ( echo %%i .\colortool.exe "%%i" pause )

脚本注释里也提醒：当前窗口历史会被不断改写，只有最近一个主题的表格显示的是它自己的颜色。

六、构建与使用前提

• 使用：README 指引下载 ColorTool 的独立发布包并解压即用；在仓库内查看对应源码位于 src/tools/ColorTool/，工程入口为ColorTool/ColorTool.csproj与解决方案 ColorTool.sln。
• 构建：可用 Visual Studio 打开解决方案，或按 README 说明使用自带的build.bat从命令行自动探测 MSBuild 版本构建。
• 前提与限制：
  • -x依赖新版 Windows 的 VT 处理（≥ 17048），且目标终端必须允许 VT 输出；
  • 默认应用只影响当前控制台窗口，持久化需要属性页"确定"或-d/-b写HKCU\Console；
  • 解析顺序固定为 INI → JSON → iTerm，同名文件在不同目录时按第 3.2 节的 7 路径顺序取第一个存在者；
  • -a/--allcolors输出扩展色表，适合超过 110 列的宽终端，避免表格截断。

七、小结

ColorTool 用不到千行 C# 代码解决了控制台配色的完整闭环：多格式解析（INI / concfg JSON / iTerm plist，反射自动注册）、统一查找规则（工作目录与安装目录的schemes/）、四种落地目标（当前控制台 API、HKCU\Console注册表、OSC VT 序列、Windows Terminal JSON），再加上最近邻颜色索引这类针对控制台 16 色表约束的工程细节。无论是想给老 conhost 换一口味觉熟悉的 iTerm 主题，还是想为 Windows Terminal 批量导入社区方案，它都是仓库中现成、可直接构建的工具。

【免费下载链接】terminalThe new Windows Terminal and the original Windows console host, all in the same place!项目地址: https://gitcode.com/GitHub_Trending/term/terminal