主题与界面定制

pi 的 TUI（终端用户界面）默认配色走的是深沉暗色路线——对多数人的终端来说是舒服的。但用久了总会想换个风格。暗色看腻了切亮色，默认配色不够个性就自己调，甚至可以把 Gruvbox、Nord、Tokyo Night 这些经典配色搬进来。

好消息是 pi 的主题系统比你想象的完整得多。51 个颜色令牌覆盖了界面的每个角落，从 Markdown 标题到语法高亮再到推理等级边框，都能单独调。

本章基于 pi v0.84.1。

---

主题文件是什么

一个 pi 主题就是一个 JSON 文件。它用 vars 定义可复用的颜色变量，再用 colors 把每个界面元素的颜色映射上去。

理解这种设计的意图：51 个令牌看起来很多，但只要在 vars 里定义好你的基础调色板（主色、辅色、背景色），colors 里大部分令牌直接引用 vars 的值就行了。改一个主色调，所有引用它的令牌自动跟随更新——这就是 vars 存在的意义。

主题文件可以精准控制这些东西的颜色：核心 UI 元素、用户消息和 AI 回复的背景、Markdown 渲染的每个层级、代码块的语法高亮、工具执行的三种状态、推理等级对应的编辑器边框。

---

主题从哪加载

pi 从六个位置加载主题文件：

位置	作用范围	何时可用
内置	全局	dark 和 light 始终可用
~/.pi/agent/themes/*.json	全局（所有项目）	始终加载
.pi/themes/*.json	项目	项目信任后加载
Pi Packages 的 themes/ 目录	全局或项目	随 package 分发
settings.json 的 themes 数组	手动指定	始终加载
--theme <路径> 命令行参数	临时	本次运行

可以通过 --no-themes 禁用除内置主题外的所有主题发现。

---

切换主题

两种方式，效果一样：

方式一：用 /settings 命令。 在交互模式中敲 /settings，会打开一个交互式设置面板。找到 Theme 选项，从下拉列表里选你想要的。

方式二：直接改 settings.json。

{
  "theme": "light"
}

"theme" 的值就是主题文件的文件名（不带 .json 后缀）。内置的 dark 和 light 直接写名字就行，自定义主题写你创建的文件名。

首次启动时，pi 会自动检测终端背景色，帮你选 dark 或 light。如果自动检测不准（有些终端不报背景色），手动切一下就好。

---

内置主题速览

pi 内置了两个主题，一暗一亮：

主题	终端背景	主色调	适合场景
dark	深色（默认）	蓝色系 accent，灰调柔和边框	绝大多数暗色终端的日常使用
light	浅色	深色主色调，对比度略低	浅色终端用户，或需要截图做文档

整体风格偏克制——不花哨，不刺眼，长时间看代码不会累。这也是 pi 界面的设计意图：作为编码代理，它的大部分时间是展示代码和 diff，配色应该为内容服务而不是抢风头。

如果你的终端设置了透明背景或者用了非纯黑背景色，内置 dark 主题一般也能兼容，因为 pi 的大部分令牌使用相对柔和的灰阶而非纯黑纯白。

---

自己写主题

第一步：创建文件

mkdir -p ~/.pi/agent/themes
# 用你喜欢的编辑器
vim ~/.pi/agent/themes/my-theme.json

第二步：写主题内容

下面是一个完整的自定义主题模板，定义了 51 个必须的令牌（thinkingMax 可选，不写则回退到 thinkingXhigh）：

{
  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
  "name": "my-theme",
  "vars": {
    "blue": "#0066cc",
    "gray": 242,
    "orange": "#ffaa00",
    "green": "#00aa55"
  },
  "colors": {
    "accent": "blue",
    "border": "blue",
    "borderAccent": "#00ffff",
    "borderMuted": "gray",
    "success": "green",
    "error": "#ff0000",
    "warning": "#ffff00",
    "muted": "gray",
    "dim": 240,
    "text": "",
    "thinkingText": "gray",
    "selectedBg": "#2d2d30",
    "scrollbarThumb": "#555566",
    "userMessageBg": "#2d2d30",
    "userMessageText": "",
    "customMessageBg": "#2d2d30",
    "customMessageText": "",
    "customMessageLabel": "blue",
    "toolPendingBg": "#1e1e2e",
    "toolSuccessBg": "#1e2e1e",
    "toolErrorBg": "#2e1e1e",
    "toolTitle": "blue",
    "toolOutput": "",
    "mdHeading": "orange",
    "mdLink": "blue",
    "mdLinkUrl": "gray",
    "mdCode": "#00ffff",
    "mdCodeBlock": "",
    "mdCodeBlockBorder": "gray",
    "mdQuote": "gray",
    "mdQuoteBorder": "gray",
    "mdHr": "gray",
    "mdListBullet": "#00ffff",
    "toolDiffAdded": "green",
    "toolDiffRemoved": "#ff0000",
    "toolDiffContext": "gray",
    "syntaxComment": "gray",
    "syntaxKeyword": "blue",
    "syntaxFunction": "#00aaff",
    "syntaxVariable": "orange",
    "syntaxString": "green",
    "syntaxNumber": "#ff00ff",
    "syntaxType": "#00aaff",
    "syntaxOperator": "blue",
    "syntaxPunctuation": "gray",
    "thinkingOff": "gray",
    "thinkingMinimal": "blue",
    "thinkingLow": "#00aaff",
    "thinkingMedium": "#00ffff",
    "thinkingHigh": "#ff00ff",
    "thinkingXhigh": "#ff0000",
    "thinkingMax": "#ff0088",
    "bashMode": "orange"
  }
}

第三步：启用主题

在 settings.json 中把 theme 设为你的主题名：

{
  "theme": "my-theme"
}

保存后 pi 会立刻切换。而且如果你在 pi 运行期间编辑当前使用的自定义主题文件，pi 会自动热重载——改完即视，不需要 /reload。

---

四种颜色值格式

pi 支持四种写法，可以混用：

格式	写法示例	说明
Hex 颜色	"#ff0000"	标准 6 位十六进制 RGB
256 色调色板	39（数字，不加引号）	xterm 256 色调色板索引，0-255
变量引用	"blue"	引用 vars 中定义的同名变量
终端默认	""（空字符串）	使用终端的前景色/背景色

什么时候用哪个？

Hex 最灵活，可以精确到任何颜色。256 色索引省事，随便找个 xterm 色表挑数字就行。变量引用用于统一管理，改一个 vars 值全局生效。空字符串留给那些你不想改的令牌——比如 text 和 userMessageText 通常留空让终端自己决定默认前景色。

256 色调色板的分段：

• 0-15：基础 ANSI 色（取决于终端配置）
• 16-231：6×6×6 RGB 色立方（公式 16 + 36×R + 6×G + B，RGB 各取 0-5）
• 232-255：灰阶渐变

---

令牌分类速查

51 个令牌太多了，按功能区记会更直观：

核心 UI（11 个）：accent 主色调、border/borderAccent/borderMuted 三级边框、success/error/warning 状态色、muted/dim/text/thinkingText 文字层级

背景与消息（12 个）：selectedBg/scrollbarThumb 选中和滚动条、userMessageBg/userMessageText 用户消息、customMessageBg/customMessageText/customMessageLabel 扩展消息、toolPendingBg/toolSuccessBg/toolErrorBg 工具三种状态背景、toolTitle/toolOutput 工具标题和输出

Markdown 渲染（10 个）：mdHeading 标题、mdLink/mdLinkUrl 链接文字和地址、mdCode/mdCodeBlock/mdCodeBlockBorder 行内代码和代码块、mdQuote/mdQuoteBorder 引用块、mdHr 分割线、mdListBullet 列表符号

工具 Diff（3 个）：toolDiffAdded 绿色新增、toolDiffRemoved 红色删除、toolDiffContext 灰色上下文

语法高亮（9 个）：syntaxComment、syntaxKeyword、syntaxFunction、syntaxVariable、syntaxString、syntaxNumber、syntaxType、syntaxOperator、syntaxPunctuation

推理等级边框（7 个）：thinkingOff → thinkingMinimal → thinkingLow → thinkingMedium → thinkingHigh → thinkingXhigh → thinkingMax（可选），从淡到醒目，在编辑器边框上体现当前推理深度

其他（2 个）：bashMode（感叹号模式下的编辑器边框颜色）

HTML 导出配色

用 /export 导出会话为 HTML 时，你可以在主题里单独定义导出页面的配色：

{
  "export": {
    "pageBg": "#18181e",
    "cardBg": "#1e1e24",
    "infoBg": "#3c3728"
  }
}

不写 export 的话，导出页面会从 userMessageBg 自动推导颜色，效果也不会差。

---

终端兼容性

pi 使用 24-bit 真彩色（True Color）渲染。绝大多数现代终端都支持：iTerm2、Kitty、WezTerm、Windows Terminal、VS Code 内置终端、Warp。

如果你的终端比较老，只支持 256 色，pi 会自动降级到最近似的颜色。效果会打折扣但不会报错。

检查你的终端是否支持 True Color：

echo $COLORTERM

输出 "truecolor" 或 "24bit" 就是支持的。没输出也不一定不支持，很多终端用 True Color 但不设这个环境变量。

在 VS Code 里，建议把 terminal.integrated.minimumContrastRatio 设为 1。默认值是 4.5，会扭曲本来正确的颜色，让主题看起来和你设计的不一样。

---

配色技巧

暗色终端：用明亮、饱和的颜色，对比度要高。暗底亮字是常态，灰色文字和边框反而要压暗一点才不会抢戏。

亮色终端：用较深、柔和的颜色，对比度适当降低。亮底暗字是天经地义，高饱和度颜色在白色背景上容易刺眼。

从成熟配色方案起步：Nord、Gruvbox、Tokyo Night、Catppuccin 都是经过大量实战验证的优秀调色板。把它们的核心色值抄到 vars 里，再逐个调整令牌引用，比自己从零调配快得多。

全面测试：不同消息类型（用户消息、AI 回复、工具输出、错误信息）、不同 Markdown 内容（代码块、引用、列表嵌套）、长文本折行——都扫一遍看看有没有不协调的地方。

让 pi 帮你写主题。 你可以在 pi 里说”帮我做一个 Nord 风格的主题”，它会生成一个完整的 JSON 文件。试试看，比自己手写快。