Pi Agent 主题定制

Pi Agent 支持自定义终端界面配色。本章介绍如何使用内置主题和创建自定义主题。

主题概述

Pi Agent 使用 JSON 格式的主题文件来定义 TUI 界面的所有颜色。

每个主题需要定义 51 个颜色令牌（Color Token），覆盖核心 UI、消息背景、Markdown 渲染、语法高亮和编辑器边框等各种界面元素的颜色。

内置主题

Pi Agent 内置了两个主题：

主题名	适用场景	说明
dark	深色终端背景（默认）	适合绝大多数开发者的深色终端
light	浅色终端背景	适合浅色主题的终端

首次启动时，Pi Agent 会自动检测你的终端背景颜色并选择 dark 或 light。

切换主题的方式：

# 通过 /settings 交互式切换
/settings

# 在 settings.json 中设置

实例

{
"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 会自动热重载主题，让你立即看到修改效果，无需任何操作。

主题文件加载位置

位置	作用范围
内置	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 中通过名称引用。这让主题的维护更加方便。

颜色令牌分类

核心 UI（11 个）

令牌	用途
accent	主色调（Logo、选中项、光标）
border	普通边框
borderAccent	高亮边框
borderMuted	编辑器区域的柔和边框
success	成功状态
error	错误状态
warning	警告状态
muted	次要文字
dim	三级文字（更不显眼）
text	默认文字色（通常留空）
thinkingText	AI 推理过程文字

背景与内容（11 个）

令牌	用途
userMessageBg	用户消息背景
userMessageText	用户消息文字
customMessageBg	扩展消息背景
toolPendingBg	工具执行中背景
toolSuccessBg	工具执行成功背景
toolErrorBg	工具执行失败背景

Markdown 渲染（10 个）

令牌	用途
mdHeading	标题
mdLink	链接文字
mdCode	行内代码
mdCodeBlock	代码块内容
mdQuote	引用块文字
mdListBullet	列表符号

语法高亮（9 个）

令牌	用途
syntaxComment	注释
syntaxKeyword	关键字
syntaxFunction	函数名
syntaxString	字符串
syntaxNumber	数字
syntaxType	类型

推理等级边框（7 个）

令牌	对应等级
thinkingOff	推理关闭
thinkingMinimal	最少推理
thinkingLow	低度推理
thinkingMedium	中度推理
thinkingHigh	高度推理
thinkingXhigh	超高度推理
thinkingMax	最大推理（可选）

thinkingMax 是可选令牌，如果不定义则回退使用 thinkingXhigh 的颜色。

HTML 导出配色

如果你使用 /export 导出会话为 HTML，可以在主题中为导出页面定义配色：

实例

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

如果省略 export 配置，导出页面会从 userMessageBg 自动推导颜色。

主题制作技巧

深色终端：使用明亮、饱和的颜色，对比度要足够高
浅色终端：使用较深、柔和的颜色，对比度可以适当降低
色彩和谐：参考 Nord、Gruvbox、Tokyo Night 等成熟配色方案作为基础
全面测试：确保在不同消息类型、工具状态、Markdown 内容和长文本折行下都能正常显示

返回顶部

菜鸟教程