主題

pi 可以建立主題。要求它為您的設定建立一個。

主題是定義 TUI 顏色的 JSON 檔案。

• Locations
• Selecting a Theme
• Creating a Custom Theme
• Theme Format
• Color Tokens
• Color Values
• Tips

Pi 從以下位置載入主題：

• 內建：dark、light
• 全球：~/.pi/agent/themes/*.json
• 項目：.pi/themes/*.json（僅在專案信任後）
• 包：themes/目錄或package.json中的pi.themes條目
• 設定：themes包含檔案或目錄的陣列
• CLI: --theme <path>（可重複）

使用 --no-themes 禁用發現。

透過 /settings 或 settings.json 選擇主題：

{
  "theme": "my-theme"
}

首次運作時，pi 會偵測您的終端背景並預設為 dark 或 light。

1. 建立主題檔案：

mkdir -p ~/.pi/agent/themes
vim ~/.pi/agent/themes/my-theme.json

2. 使用所有必需的顏色定義主題（參見Color Tokens）：

{
  "$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",
    "scrollbarThumb": "#555566",
    "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"
  }
}

3. 透過/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 個必需的標記。 thinkingMax 是可選的，並回落到 thinkingXhigh； scrollbarThumb 是可選的，並回落到 selectedBg。

$schema 欄位支援編輯器自動完成和驗證。

每個主題必須定義所有 51 個必需的顏色標記。 thinkingMax和scrollbarThumb是可選的，以兼容現有主題；省略時，它們分別使用 thinkingXhigh 和 selectedBg。

編輯器邊框顏色表示思考層次（視覺層次從微妙到突出）：

export 部分控制 /export HTML 輸出的顏色。如果省略，則顏色源自 userMessageBg。

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

支援四種格式：

• 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  # Should output "truecolor" or "24bit"

深色終端： 使用明亮、飽和且對比較高的顏色。

燈終端： 使用較暗、柔和的顏色和較低的對比。

色彩和諧： 從基礎調色板（Nord、Gruvbox、Tokyo Night）開始，在 vars 中定義它，並一致地引用。

測試： 使用不同的訊息類型、工具狀態、Markdown 內容和長換行文字檢查您的主題。

VS Code： 將 terminal.integrated.minimumContrastRatio 設為 1 以獲得準確的顏色。

查看內建主題：

• dark.json
• light.json