Pi 文档

Appearance

主题 ​

Pi 可以创建主题。请让它为您的设置构建一个。

目录 ​

位置 ​

Pi 从以下位置加载主题：

  • 内置主题：dark、light
  • 全局主题：~/.pi/agent/themes/*.json
  • 项目主题：.pi/themes/*.json（仅在项目被信任后）
  • 包主题：themes/ 目录或 package.json 中的 pi.themes 条目
  • 设置主题：settings.json 中的 themes 数组（包含文件或目录）
  • CLI：--theme <路径>（可重复指定）

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

选择主题 ​

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

json
{
  "theme": "my-theme"
}

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

创建自定义主题 ​

  1. 创建主题文件：
bash
mkdir -p ~/.pi/agent/themes
vim ~/.pi/agent/themes/my-theme.json
  1. 定义主题，包含所有必需的颜色（参见 颜色标记）：
json
{
  "$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",
    "thinkingMax": "#ff0088",
    "bashMode": "#ffaa00"
  }
}
  1. 通过 /settings 选择主题。

热重载： 当您编辑当前激活的自定义主题文件时，Pi 会自动重新加载它以提供即时视觉反馈。

主题格式 ​

json
{
  "$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。

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

颜色标记 ​

每个主题必须定义所有 51 个必需的颜色标记。thinkingMax 是兼容性可选的；省略时回退到 thinkingXhigh。

核心 UI（11 种颜色） ​

标记用途
accent主要强调色（Logo、选中项、光标）
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 个必需，1 个可选） ​

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

标记用途
thinkingOff思考关闭
thinkingMinimal最少思考
thinkingLow低思考
thinkingMedium中思考
thinkingHigh高思考
thinkingXhigh额外高思考
thinkingMax最大思考；可选，省略时回退到 thinkingXhigh

Bash 模式（1 种颜色） ​

标记用途
bashModeBash 模式下的编辑器边框（! 前缀）

HTML 导出（可选） ​

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

json
{
  "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 会回退到最近的近似值。

检查真彩色支持：

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

提示 ​

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

浅色终端： 使用较暗、饱和度较低的颜色，并降低对比度。

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

测试： 使用不同类型的消息、工具状态、Markdown 内容和长包裹文本来检查主题效果。

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

示例 ​

查看内置主题：

Pi 编码助手中文文档

Copyright © 2026 Earendil Works