pi 可以创建主题，为你的配置生成一个

badlogic 发布于 2026-07-10 阅读 11

本文详细介绍了 pi 工具的主题系统，包括主题的加载位置、选择方法、自定义主题的创建步骤、JSON 格式规范、颜色Token的定义（共51个必选Token）以及颜色值的四种格式（Hex、256色、变量引用、默认色）。还提供了颜色搭配建议和终端兼容性说明。

目录

位置

Pi 从以下位置加载主题：

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

使用 --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. 定义包含所有必需颜色的主题（参见 颜色 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",
    "thinkingMax": "#ff0088",
    "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 个必需的 Token。thinkingMax 可选，省略时则回退到 thinkingXhigh。

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

颜色 Token

每个主题必须定义所有 51 个必需的颜色 Token。thinkingMax 可选，为了兼容现有主题；省略时则使用 thinkingXhigh。

核心 UI（11 种颜色）

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

背景与内容（11 种颜色）

Token 用途
selectedBg 选中行背景
userMessageBg 用户消息背景
userMessageText 用户消息文本
customMessageBg 扩展消息背景
customMessageText 扩展消息文本
customMessageLabel 扩展消息标签
toolPendingBg 工具框（待处理）
toolSuccessBg 工具框（成功）
toolErrorBg 工具框（错误）
toolTitle 工具标题
toolOutput 工具输出文本

Markdown（10 种颜色）

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

工具差异（3 种颜色）

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

语法高亮（9 种颜色）

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

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

编辑器边框颜色，用于指示思考等级（从柔和到突出的视觉层次）：

Token 用途
thinkingOff 思考关闭
thinkingMinimal 极简思考
thinkingLow 低思考
thinkingMedium 中等思考
thinkingHigh 高思考
thinkingXhigh 极高思考
thinkingMax 最高思考；可选，回退到 thinkingXhigh

Bash 模式（1 种颜色）

Token 用途
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 以获得准确的色彩显示。

示例

参见内置主题：

  • 原文链接： github.com/badlogic/pi-m...
  • 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～
微信扫码分享

相关文章

0 条评论

登录后发表评论