主题

pi 可以创建主题。让它为你的环境定制一个。

目录

• 主题位置
• 选择主题
• 创建自定义主题
• 主题格式
• 颜色令牌
• 颜色值
• 提示

主题位置

pi 从以下位置加载主题：

• 内置：dark、light
• 全局：~/.pi/agent/themes/*.json
• 项目：.pi/themes/*.json（仅在该项目受信任后）
• Pi 包：themes/ 目录或 package.json 中的 pi.themes 条目
• 设置：themes 数组，可包含文件或目录
• CLI：--theme <path>（可重复）

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

选择主题

通过 /settings 或在 settings.json 中选择主题：

{
  "theme": "my-theme"
}

首次运行时，pi 会检测你的终端背景，并默认使用 dark 或 light。

创建自定义主题

1. 创建主题文件：

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

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",
    "scrollbarThumb": "#555566",
    "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",
    "thinkingMax": "#ff0088",
    "bashMode": "#ffaa00"
  }
}

3. 通过 /settings 选择该主题。

热重载： 当你编辑当前正在使用的自定义主题文件时，pi 会自动重载它，以便立即获得视觉反馈。

主题格式

{
  "$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
  },
  "colors": {
    "accent": "blue",
    "muted": "gray",
    "text": "",
    ...
  }
}

• name 为必填项，必须唯一，且不能包含 /。
• vars 为可选项。在此定义可复用的颜色，然后在 colors 中引用。
• colors 必须定义全部 51 个必需的令牌。thinkingMax 为可选，缺省时回退到 thinkingXhigh；scrollbarThumb 为可选，缺省时回退到 selectedBg。

$schema 字段可启用编辑器的自动补全与校验。

颜色令牌

每个主题都必须定义全部 51 个必需的颜色令牌。出于与现有主题的兼容性，thinkingMax 和 scrollbarThumb 为可选；省略时分别使用 thinkingXhigh 和 selectedBg。

核心 UI（11 种颜色）

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

背景与内容（11 个必需，1 个可选）

令牌	用途
selectedBg	选中行背景
scrollbarThumb	全屏滚动条滑块背景；可选，缺省回退到 selectedBg
userMessageBg	用户消息背景
userMessageText	用户消息文本
customMessageBg	扩展消息背景
customMessageText	扩展消息文本
customMessageLabel	扩展消息标签
toolPendingBg	工具框（进行中）
toolSuccessBg	工具框（成功）
toolErrorBg	工具框（错误）
toolTitle	工具标题
toolOutput	工具输出文本

Markdown（10 种颜色）

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

工具差异（3 种颜色）

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

语法高亮（9 种颜色）

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

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

编辑器边框颜色，用于指示思考级别（视觉层次由轻微到突出）：

令牌	用途
thinkingOff	关闭思考
thinkingMinimal	极简思考
thinkingLow	低思考
thinkingMedium	中思考
thinkingHigh	高思考
thinkingXhigh	超高思考
thinkingMax	最高思考；可选，缺省回退到 thinkingXhigh

Bash 模式（1 种颜色）

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

HTML 导出（可选）

export 部分控制 /export HTML 输出的颜色。省略时，颜色从 userMessageBg 派生。

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

颜色值

支持四种格式：

格式	示例	描述
十六进制	"#ff0000"	6 位十六进制 RGB
256 色	39	xterm 256 色调色板索引（0-255）
变量	"primary"	对 vars 中某个条目的引用
默认	""	终端的默认颜色

256 色调色板

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

终端兼容性

Pi 使用 24 位 RGB 颜色。大多数现代终端都支持这种格式（iTerm2、Kitty、WezTerm、Windows Terminal、VS Code）。对于仅支持 256 色的旧终端，pi 会回退到最接近的近似色。

检查真彩色支持：

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

提示

深色终端： 使用更亮、饱和度更高的颜色，增强对比度。

浅色终端： 使用更深、更柔和的颜色，降低对比度。

颜色协调： 从一个基础调色板开始（Nord、Gruvbox、Tokyo Night），在 vars 中定义它，并保持一致地引用。

测试： 用不同类型的消息、工具状态、markdown 内容和长换行文本检查你的主题。

VS Code： 将 terminal.integrated.minimumContrastRatio 设置为 1，以获得准确的颜色。

示例

查看内置主题：

• dark.json
• light.json