Themes

pi 可以创建主题。要求它为你的设置构建一个。

主题是定义 TUI 颜色的 JSON 文件。

• Locations
• Selecting a Theme
• Creating a Custom Theme
• Theme Format
• Color Tokens
• Color Values
• Tips

Pi 从以下位置加载主题：

• 内置：dark、light
• 全局：~/.pi/agent/themes/*.json
• 项目：.pi/themes/*.json（仅在项目被信任后）
• 包：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. 使用所有必需的颜色定义主题（参见Color Tokens）：

{
  "$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",
    "searchMatchBg": "#2d2d30",
    "searchMatchText": "",
    "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、scrollbarThumb 及两个搜索高亮标记都是可选的，并使用下文列出的回退值。

$schema 字段支持编辑器自动完成和验证。

每个主题必须定义所有 51 个必需的颜色标记。可选标记用于兼容现有主题：thinkingMax 回退到 thinkingXhigh，scrollbarThumb 和 searchMatchBg 回退到 selectedBg，searchMatchText 回退到 text。其他搜索匹配项会在 searchMatchBg 上使用带下划线的 searchMatchText；当前匹配项则会反转这组前景色和背景色，并使用粗体。

编辑器边框颜色表示思考级别（视觉层次从微妙到突出）：

export 部分控制 /export HTML 输出的颜色。如果省略，则颜色源自 userMessageBg。

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

支持四种格式：

• 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  # Should output "truecolor" or "24bit"

深色终端： 使用明亮、饱和且对比度较高的颜色。

灯终端： 使用较暗、柔和的颜色和较低的对比度。

色彩和谐： 从基础调色板（Nord、Gruvbox、Tokyo Night）开始，在 vars 中定义它，并一致地引用。

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

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

查看内置主题：

• dark.json
• light.json