Pi Agent 主题定制
Pi Agent 支持自定义终端界面配色。
本章介绍如何使用内置主题和创建自定义主题。
主题概述
Pi Agent 使用 JSON 格式的主题文件来定义 TUI 界面的所有颜色。
每个主题需要定义 51 个必填令牌 + 4 个可选令牌（thinkingMax、scrollbarThumb、searchMatchBg、searchMatchText），覆盖核心 UI、消息背景、Markdown 渲染、语法高亮和编辑器边框等各种界面元素的颜色。
内置主题
Pi Agent 内置了两个主题：
| 主题名 | 适用场景 | 说明 |
|---|---|---|
| dark | 深色终端背景（默认） | 适合绝大多数开发者的深色终端 |
| light | 浅色终端背景 | 适合浅色主题的终端 |
首次启动时，Pi Agent 会自动检测你的终端背景颜色并选择 dark 或 light。
交互模式下输入 /settings，在主题选项中直接切换：
/settings
也可以在 settings.json 中写入 theme 字段，把 theme 的值改成主题名即可：
实例
"theme": "light"
}
创建自定义主题
首先创建主题目录和文件：
mkdir -p ~/.pi/agent/themes vim ~/.pi/agent/themes/my-theme.json
然后定义主题文件，以下是一个完整的自定义主题示例：
实例
"name": "my-theme",
"vars": {
"blue": "#0066cc",
"gray": 242,
"orange": "#ffaa00",
"green": "#00aa55"
},
"colors": {
"accent": "blue",
"border": "blue",
"borderAccent": "#00ffff",
"borderMuted": "gray",
"success": "green",
"error": "#ff0000",
"warning": "#ffff00",
"muted": "gray",
"dim": 240,
"text": "",
"thinkingText": "gray",
"selectedBg": "#2d2d30",
"userMessageBg": "#2d2d30",
"userMessageText": "",
"customMessageBg": "#2d2d30",
"customMessageText": "",
"customMessageLabel": "blue",
"toolPendingBg": "#1e1e2e",
"toolSuccessBg": "#1e2e1e",
"toolErrorBg": "#2e1e1e",
"toolTitle": "blue",
"toolOutput": "",
"mdHeading": "orange",
"mdLink": "blue",
"mdLinkUrl": "gray",
"mdCode": "#00ffff",
"mdCodeBlock": "",
"mdCodeBlockBorder": "gray",
"mdQuote": "gray",
"mdQuoteBorder": "gray",
"mdHr": "gray",
"mdListBullet": "#00ffff",
"toolDiffAdded": "green",
"toolDiffRemoved": "#ff0000",
"toolDiffContext": "gray",
"syntaxComment": "gray",
"syntaxKeyword": "blue",
"syntaxFunction": "#00aaff",
"syntaxVariable": "orange",
"syntaxString": "green",
"syntaxNumber": "#ff00ff",
"syntaxType": "#00aaff",
"syntaxOperator": "blue",
"syntaxPunctuation": "gray",
"thinkingOff": "gray",
"thinkingMinimal": "blue",
"thinkingLow": "#00aaff",
"thinkingMedium": "#00ffff",
"thinkingHigh": "#ff00ff",
"thinkingXhigh": "#ff0000",
"thinkingMax": "#ff0088",
"bashMode": "orange"
}
}
然后在 settings.json 中启用你的主题：
实例
"theme": "my-theme"
}
当你编辑当前正在使用的自定义主题文件时，Pi Agent 会自动热重载主题，让你立即看到修改效果，无需任何操作。
主题文件加载位置
Pi Agent 会按以下位置查找主题文件。
放在不同位置的主题，可见范围和加载条件并不相同。
| 位置 | 作用范围 |
|---|---|
| 内置 | dark、light 始终可用 |
| ~/.pi/agent/themes/*.json | 全局主题，所有项目可用 |
| .pi/themes/*.json | 项目主题，需项目信任后才加载 |
| Pi Packages | 包中的 themes/ 目录 |
| --theme 路径 | 命令行临时加载 |
颜色值格式
Pi Agent 支持四种颜色值格式：
| 格式 | 示例 | 说明 |
|---|---|---|
| Hex 颜色 | "#ff0000" | 6 位十六进制 RGB 颜色 |
| 256 色调色板 | 39 | xterm 256 色调色板索引（0-255） |
| 变量引用 | "blue" | 引用 vars 中定义的变量 |
| 终端默认色 | "" | 使用终端的默认前景/背景色 |
vars 区域用于定义可复用的颜色变量，在 colors 中通过名称引用。
把主色抽成变量后，换配色只需要改一处，主题维护起来更方便。
颜色令牌分类
colors 中每个令牌对应界面上一类元素的颜色。
下面按用途把全部令牌分成六类，方便对照查找。
核心 UI（11 个）
这一组控制编辑器、状态栏等基础界面元素的颜色。
| 令牌 | 用途 |
|---|---|
| accent | 主色调（Logo、选中项、光标） |
| border | 普通边框 |
| borderAccent | 高亮边框 |
| borderMuted | 编辑器区域的柔和边框 |
| success | 成功状态 |
| error | 错误状态 |
| warning | 警告状态 |
| muted | 次要文字 |
| dim | 三级文字（更不显眼） |
| text | 默认文字色（通常留空） |
| thinkingText | AI 推理过程文字 |
背景与内容（11 个必填 + 3 个可选）
这一组控制选中项、消息气泡和工具输出区域的背景与文字。
| 令牌 | 用途 |
|---|---|
| selectedBg | 选中项背景（列表中的当前条目） |
| userMessageBg | 用户消息背景 |
| userMessageText | 用户消息文字 |
| customMessageBg | 扩展消息背景 |
| customMessageText | 扩展消息文字 |
| customMessageLabel | 扩展消息的标题标签色 |
| toolPendingBg | 工具执行中背景 |
| toolSuccessBg | 工具执行成功背景 |
| toolErrorBg | 工具执行失败背景 |
| toolTitle | 工具卡片标题文字 |
| toolOutput | 工具输出文字 |
| scrollbarThumb | 全屏滚动条拇指色（可选，缺省时回退 selectedBg） |
| searchMatchBg | 搜索匹配背景（可选，缺省时回退 selectedBg） |
| searchMatchText | 搜索匹配文字（可选，缺省时回退 text） |
Markdown 渲染（10 个）
这一组控制 AI 回复中 Markdown 元素的颜色。
| 令牌 | 用途 |
|---|---|
| mdHeading | 标题 |
| mdLink | 链接文字 |
| mdLinkUrl | 链接的 URL 地址 |
| mdCode | 行内代码 |
| mdCodeBlock | 代码块内容 |
| mdCodeBlockBorder | 代码块边框 |
| mdQuote | 引用块文字 |
| mdQuoteBorder | 引用块边框 |
| mdHr | 分隔线 |
| mdListBullet | 列表符号 |
语法高亮（9 个）
这一组控制代码块内的语法高亮配色。
| 令牌 | 用途 |
|---|---|
| syntaxComment | 注释 |
| syntaxKeyword | 关键字 |
| syntaxFunction | 函数名 |
| syntaxVariable | 变量名 |
| syntaxString | 字符串 |
| syntaxNumber | 数字 |
| syntaxType | 类型 |
| syntaxOperator | 运算符 |
| syntaxPunctuation | 标点符号 |
推理等级边框（7 个）
这一组控制当前推理等级在编辑器边框上的提示色。
| 令牌 | 对应等级 |
|---|---|
| thinkingOff | 推理关闭 |
| thinkingMinimal | 最少推理 |
| thinkingLow | 低度推理 |
| thinkingMedium | 中度推理 |
| thinkingHigh | 高度推理 |
| thinkingXhigh | 超高度推理 |
| thinkingMax | 最大推理（可选） |
thinkingMax 是可选令牌，如果不定义则回退使用 thinkingXhigh 的颜色。
Diff 与 Bash 配色（4 个）
这一组控制 diff 高亮和 bash 模式提示色，编辑代码时最常看到它们。
| 令牌 | 用途 |
|---|---|
| toolDiffAdded | diff 新增行（通常用绿色） |
| toolDiffRemoved | diff 删除行（通常用红色） |
| toolDiffContext | diff 上下文行（保持低调） |
| bashMode | bash 模式下的提示色 |
HTML 导出配色
如果你使用 /export 导出会话为 HTML，可以在主题中为导出页面定义配色：
实例
"export": {
"pageBg": "#18181e",
"cardBg": "#1e1e24",
"infoBg": "#3c3728"
}
}
如果省略 export 配置，导出页面会从 userMessageBg 自动推导颜色。
主题制作技巧
下面几条经验能让自定义主题在不同终端上都表现稳定。
- 深色终端：使用明亮、饱和的颜色，对比度要足够高
- 浅色终端：使用较深、柔和的颜色，对比度可以适当降低
- 色彩和谐：参考 Nord、Gruvbox、Tokyo Night 等成熟配色方案作为基础
- 全面测试：确保在不同消息类型、工具状态、Markdown 内容和长文本折行下都能正常显示