$ pi –theme

TL;DR. 主题是 JSON 文件，必须声明全部 51 个必填色值 token（Markdown、工具 diff、语法高亮、思考级别边框、bash 模式），可引用共享的 vars。发现顺序：内置 dark/light，然后 ~/.pi/agent/themes/，再 .pi/themes/（项目被信任后才生效），最后是包内主题。选用方式：settings.json 的 theme 键、/settings，或 pi --theme <path>（可重复）。当前活跃的自定义主题可热重载。把主题打包成 pi: { themes: [...] } 形式的 npm 包即可走 pi install npm: 分发。

Pi TUI 上的每一个像素都来自一个 JSON 主题文件。内置的 dark 与 light 随 agent 一起发布，其他一切 —— Catppuccin、Tokyo Night，或你自己的配色 —— 都是放在某个标准发现路径下的 JSON 文件。本文覆盖主题的选用方式、51 个必填色值 token 各自控制什么，以及如何编写并打包自己的主题。权威参考是 Themes 文档与仓库中的 JSON schema。

Pi 如何选主题

有四种优先级递增的选主题方式：

首次启动检测。第一次启动时 Pi 会采样你的终端背景色，并默认选 dark 或 light。
/settings。交互式设置 UI 会列出所有已发现的主题。
settings.json。通过 "theme": "my-theme" 让它在所有项目里持久生效。
CLI 参数。pi --theme <path>（可重复，可以叠加多个）或 pi --no-themes 完全跳过主题发现。

# 使用指定主题文件
pi --theme ~/.pi/agent/themes/catppuccin-mocha.json

# 在基础主题上叠加项目级微调
pi --theme ~/.pi/agent/themes/tokyonight.json --theme ./.pi/themes/local-tweaks.json

当前活跃的自定义主题文件会被自动热重载 —— 不需要重启 Pi，也不需要 /reload。

主题文件放在哪里

Pi 按以下顺序在四个位置发现主题：

内置：dark 与 light，编译进 agent。
全局：~/.pi/agent/themes/*.json。
项目：.pi/themes/*.json（仅在项目被信任后才会被加载）。
包：已安装包内的 themes/ 目录，或 package.json 里的 pi.themes 条目。

对于打包好的主题，你也可以在 settings.json 里通过 themes 数组列出文件或目录，这在你想指向标准路径之外的主题、又不想复制它时很有用。

本站资源地图的 themes 分类下收录了一些开箱即用的主题 —— 见 pi-catppuccin、pi-tokyonight、pi-ansi-themes 这几个可安装示例。

主题文件的结构

一个最小但合法的主题长这样：

{
  "$schema": "https://pi.dev/schema/theme.json",
  "name": "my-theme",
  "vars": {
    "primary": "#ff7b00"
  },
  "colors": {
    "accent": "primary",
    "border": "#3a3a3a",
    "text": "#e6e6e6"
    // ...还有 48 个必填 token
  }
}

name 必填，必须唯一，且不能包含 /。
vars 可选，用于在多个 token 之间复用同一颜色。
colors 必须定义全部 51 个必填 token（见下文）。其中两个可选：thinkingMax 回退到 thinkingXhigh，scrollbarThumb 回退到 selectedBg。
$schema 启用编辑器自动补全与 schema 校验 —— 建议保留。
export 是可选段，用于自定义 HTML 导出时的渲染（pageBg、cardBg、infoBg）。

颜色值可以是 hex 字符串（"#ff0000"）、xterm 256 色的整数、对 vars 条目的引用（"primary"），或空字符串（沿用终端默认色）。

51 个必填 token

schema 把它们分成七个功能组：

11 个核心 UI token：accent、border、borderAccent、borderMuted、success、error、warning、muted、dim、text、thinkingText。
11 个背景与消息 token：selectedBg、userMessageBg、userMessageText、customMessageBg、customMessageText、customMessageLabel、toolPendingBg、toolSuccessBg、toolErrorBg、toolTitle、toolOutput（scrollbarThumb 是可选的第 12 个）。
10 个 Markdown token：mdHeading、mdLink、mdLinkUrl、mdCode、mdCodeBlock、mdCodeBlockBorder、mdQuote、mdQuoteBorder、mdHr、mdListBullet。
3 个工具 diff token：toolDiffAdded、toolDiffRemoved、toolDiffContext。
9 个语法高亮 token：syntaxComment、syntaxKeyword、syntaxFunction、syntaxVariable、syntaxString、syntaxNumber、syntaxType、syntaxOperator、syntaxPunctuation。
6 个思考级别边框 token（thinkingMax 可选）：thinkingOff、thinkingMinimal、thinkingLow、thinkingMedium、thinkingHigh、thinkingXhigh。thinkingMax 在 v0.80.6 引入，用于为新增的 max 思考级别绘制边框。
1 个 bash 模式 token：bashMode。

完整列表维护在 theme-schema.json —— 想确认某个视觉元素是否对应一个 token 时去那里查。

一个完整的示例

假设你想要一个深色背景、暖橙色强调、冷灰边框、用户消息区对比度更高的主题。从 dark.json 起步，只覆盖需要改的部分：

{
  "$schema": "https://pi.dev/schema/theme.json",
  "name": "dusk",
  "vars": {
    "accent": "#ff7b00",
    "border": "#3a3a3a",
    "userBg": "#1a1f2b"
  },
  "colors": {
    "accent": "accent",
    "border": "border",
    "borderAccent": "accent",
    "borderMuted": "border",
    "text": "#e6e6e6",
    "userMessageBg": "userBg"
  }
}

保存为 ~/.pi/agent/themes/dusk.json，然后在 /settings → Theme 里选，或者直接 pi --theme ~/.pi/agent/themes/dusk.json。修改会实时生效。

终端兼容性

Pi 使用 24-bit RGB，并要求终端支持 truecolor：

echo $COLORTERM
# 期望输出: "truecolor" 或 "24bit"

在更老的终端上 Pi 会近似到最接近的 256 色，而不是退到 16 色。如果自定义主题发灰，先看终端。

把主题打包分发

如果想通过 pi install 分享主题，把它打包成 npm 或 git 包，并用 pi 字段指明主题入口：

{
  "name": "pi-theme-dusk",
  "pi": {
    "themes": ["./dusk.json"]
  }
}

用户用 pi install npm:pi-theme-dusk 安装，Pi 通过包的 themes/ 目录或 package.json 里的 pi.themes 列表发现它。完整发布流程见 Packages 文档；代码扩展所用的 pi.extensions 机制同样适用于主题。

主题与配色