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

主题

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

目录

位置

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
  1. 使用所有必需颜色定义主题（见 颜色令牌）：
{
  "$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 选择主题。

热重载： 当你编辑当前启用的自定义主题文件时，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 个必需令牌。

$schema 字段启用编辑器自动补全和验证。

颜色令牌

每个主题必须定义全部 51 个颜色令牌。没有可选颜色。

核心 UI（11 种颜色）

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

背景与内容（11 种颜色）

令牌用途
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 种颜色）

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

令牌用途
thinkingOff关闭思考
thinkingMinimal最少思考
thinkingLow低强度思考
thinkingMedium中等强度思考
thinkingHigh高强度思考
thinkingXhigh超高强度思考

Bash 模式（1 种颜色）

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

HTML 导出（可选）

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

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

颜色值

支持四种格式：

格式示例描述
十六进制"#ff0000"6 位十六进制 RGB
256 色39xterm 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 会回退到最接近的近似颜色。

检查 truecolor 支持：

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

提示

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

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

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

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

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

示例

查看内置主题：

最近更新：:
Contributors: seepine