pi 可以创建 theme。让它为你的配置生成一个。

主题

Theme 是定义 TUI 颜色的 JSON 文件。

目录

• 位置
• 选择 theme
• 创建自定义 theme
• 主题格式
• 颜色 token
• 颜色值
• 技巧

位置

Pi 会从这些位置加载 theme：

• 内置：dark、light
• 全局：~/.pi/agent/themes/*.json
• 项目：.pi/themes/*.json（只有在项目被信任后才会启用）
• Packages：themes/ 目录，或 package.json 中的 pi.themes 条目
• 设置：themes 数组，里面可以放文件或目录
• CLI：--theme <path>（可重复）

使用 --no-themes 可禁用自动发现。

选择 theme

可以通过 /settings，或者在 settings.json 里选择 theme：

{
  "theme": "my-theme"
}

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

创建自定义 theme

1. 创建一个 theme 文件：

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

1. 按照所有必需颜色定义 theme（见 颜色 token）：

{
  "$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"
  }
}

1. 通过 /settings 选择这个 theme。

热重载： 当你编辑当前正在使用的自定义 theme 文件时，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 个必需 token。

$schema 字段可以让编辑器自动补全并进行校验。

颜色 token

每个 theme 都必须定义全部 51 个颜色 token，没有可选颜色。

核心 UI（11 种颜色）

背景与内容（11 种颜色）

Markdown（10 种颜色）

Tool Diff（3 种颜色）

语法高亮（9 种颜色）

Thinking Level 边框（6 种颜色）

用于表示思考等级的编辑器边框颜色（视觉层级从弱到强）：

Bash Mode（1 种颜色）

HTML 导出（可选）

export 部分控制 /export 生成的 HTML 输出颜色。如果省略，颜色会从 userMessageBg 推导出来。

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

---

颜色值

支持四种格式：

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-bit RGB 颜色。大多数现代终端都支持这一点（iTerm2、Kitty、WezTerm、Windows Terminal、VS Code）。对于只支持 256-color 的旧终端，pi 会回退到最接近的近似值。

检查 truecolor 支持：

echo $COLORTERM  # Should output "truecolor" or "24bit"

提示

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

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

配色协调： 先选一个基础调色板（Nord、Gruvbox、Tokyo Night），把它定义到 vars 里，再保持一致地引用。

测试： 用不同的消息类型、tool 状态、markdown 内容，以及较长的自动换行文本来检查你的主题。

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

示例

查看内置主题：

• dark.json
• light.json