16  主题

16.1 主题概述

Pi 的 TUI（终端用户界面）使用 JSON 格式的主题文件来定义所有颜色。主题系统支持 24-bit RGB 真彩色、256 色调色板以及终端默认颜色，让你可以根据个人喜好或团队品牌定制 Pi 的视觉风格。

16.2 内置主题

Pi 内置两个主题：

主题 说明
dark 深色主题（默认，适用于深色终端背景）
light 浅色主题（适用于浅色终端背景）

首次运行时，Pi 会自动检测终端背景色并选择合适的默认主题。

16.3 主题位置

Pi 从以下位置加载主题：

位置 作用域
内置 dark / light 默认
~/.pi/agent/themes/*.json 全局
.pi/themes/*.json 项目级（需受信任）
包的 themes/ 目录 包级
settings.json 的 themes 数组 配置
--theme <path> CLI

使用 --no-themes 可禁用主题发现。

16.4 选择主题

通过 /settings 命令或 settings.json 选择主题：

{
  "theme": "my-theme"
}
Tip

热重载：编辑当前激活的自定义主题文件时，Pi 会自动重新加载，提供即时视觉反馈。这使得主题调试非常方便。

16.5 创建自定义主题

16.5.1 步骤 1：创建主题文件

mkdir -p ~/.pi/agent/themes
vim ~/.pi/agent/themes/my-theme.json

16.5.2 步骤 2：定义颜色

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

16.5.3 步骤 3：选择主题

通过 /settings 选择 my-theme。

16.6 主题格式

{
  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/.../theme-schema.json",
  "name": "my-theme",
  "vars": {
    "blue": "#0066cc",
    "gray": 242
  },
  "colors": {
    "accent": "blue",
    "muted": "gray",
    "text": "",
    ...
  }
}
字段 说明
$schema JSON Schema URL，启用编辑器自动补全和验证
name 主题名称（必需，必须唯一，不能包含 /）
vars 可选，定义可复用的颜色变量
colors 必须定义全部 51 个必需的颜色 token

16.7 颜色 Token 分类

16.7.1 核心 UI（11 个颜色）

Token 用途
accent 主强调色（Logo、选中项、光标）
border 普通边框
borderAccent 高亮边框
borderMuted 微弱边框（编辑器）
success 成功状态
error 错误状态
warning 警告状态
muted 次要文本
dim 三级文本
text 默认文本（通常为 ""）
thinkingText 思考块文本

16.7.2 背景与内容（11 个颜色）

Token 用途
selectedBg 选中行背景
userMessageBg 用户消息背景
userMessageText 用户消息文本
customMessageBg 扩展消息背景
customMessageText 扩展消息文本
customMessageLabel 扩展消息标签
toolPendingBg 工具框（执行中）
toolSuccessBg 工具框（成功）
toolErrorBg 工具框（错误）
toolTitle 工具标题
toolOutput 工具输出文本

16.7.3 Markdown（10 个颜色）

Token 用途
mdHeading 标题
mdLink 链接文本
mdLinkUrl 链接 URL
mdCode 行内代码
mdCodeBlock 代码块内容
mdCodeBlockBorder 代码块边框
mdQuote 引用块文本
mdQuoteBorder 引用块边框
mdHr 水平分割线
mdListBullet 列表项目符号

16.7.4 工具 Diff（3 个颜色）

Token 用途
toolDiffAdded 新增行
toolDiffRemoved 删除行
toolDiffContext 上下文行

16.7.5 语法高亮（9 个颜色）

Token 用途
syntaxComment 注释
syntaxKeyword 关键字
syntaxFunction 函数名
syntaxVariable 变量
syntaxString 字符串
syntaxNumber 数字
syntaxType 类型
syntaxOperator 运算符
syntaxPunctuation 标点符号

16.7.6 思考级别边框（6 个必需，1 个可选）

编辑器边框颜色，指示当前思考级别（从微弱到醒目的视觉层次）：

Token 用途
thinkingOff 思考关闭
thinkingMinimal 最小思考
thinkingLow 低思考
thinkingMedium 中等思考
thinkingHigh 高思考
thinkingXhigh 超高思考
thinkingMax 最大思考（可选，缺省回退到 thinkingXhigh）

16.7.7 Bash 模式（1 个颜色）

Token 用途
bashMode bash 模式下的编辑器边框（! 前缀）

16.7.8 HTML 导出（可选）

控制 /export HTML 输出的颜色。省略时从 userMessageBg 推导：

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

16.8 颜色值格式

支持四种格式：

格式 示例 说明
Hex "#ff0000" 6 位十六进制 RGB
256 色 39 xterm 256 色调色板索引（0-255）
变量引用 "primary" 引用 vars 中定义的变量
终端默认 "" 使用终端默认颜色

16.8.1 256 色调色板

  • 0-15：基本 ANSI 颜色（取决于终端配置）
  • 16-231：6×6×6 RGB 立方体（16 + 36×R + 6×G + B，其中 R、G、B 为 0-5）
  • 232-255：灰度渐变

16.9 终端兼容性

Pi 使用 24-bit RGB 真彩色。大多数现代终端都支持：

  • iTerm2
  • Kitty
  • WezTerm
  • Windows Terminal
  • VS Code 集成终端

对于仅支持 256 色的旧终端，Pi 会自动回退到最接近的颜色近似值。

检查真彩色支持：

echo $COLORTERM  # 应输出 "truecolor" 或 "24bit"

16.10 主题设计技巧

16.10.1 深色终端

使用明亮、饱和的颜色，保持较高对比度：

{
  "vars": {
    "accent": "#00aaff",
    "success": "#00ff88",
    "error": "#ff4466"
  }
}

16.10.2 浅色终端

使用较暗、柔和的颜色，保持较低对比度：

{
  "vars": {
    "accent": "#0066cc",
    "success": "#008844",
    "error": "#cc3333"
  }
}

16.10.3 配色和谐

从成熟的配色方案开始，在 vars 中定义基础调色板：

  • Nord：冷色调蓝灰色系
  • Gruvbox：暖色调复古风格
  • Tokyo Night：深蓝紫色系
  • Catppuccin：柔和粉彩风格
  • Dracula：深紫暗色系
Tip

VS Code 用户：将 terminal.integrated.minimumContrastRatio 设为 1，以确保主题颜色准确显示，不受 VS Code 对比度调整的影响。

16.11 参考主题

查看 Pi 内置主题作为创建自定义主题的参考：