pi-customization

Pi 自定义

依据

1. pi-mono/packages/coding-agent/docs/themes.md — 主题 JSON 格式（name、可选的 vars、必需的 51 个 colors 令牌）、位置（~/.pi/agent/themes/*.json、.pi/themes/*.json、包、设置、CLI --theme）、热重载、颜色值格式。
2. pi-mono/packages/coding-agent/docs/keybindings.md — 通过 ~/.pi/agent/keybindings.json 自定义、命名空间操作 ID（tui.input.submit、tui.editor.cursorUp、app.interrupt 等）、按键格式（modifier+key）、完整操作表。
3. pi-mono/packages/coding-agent/docs/prompt-templates.md — 通过 /name 调用的 Markdown 片段、位置（~/.pi/agent/prompts/*.md、.pi/prompts/*.md、包）、位置参数（$1、$2、$@、${@:N}）、包含可选 description 的 YAML frontmatter。
4. pi-mono/packages/coding-agent/README.md — .pi/SYSTEM.md、~/.pi/agent/SYSTEM.md 和 APPEND_SYSTEM.md 的上下文文件部分。
5. pi-mono/packages/coding-agent/docs/settings.md — 用于整合这些设置的整体 settings.json 结构。

不变量

• 主题格式：主题定义 name（必需且唯一）、用于可复用颜色别名的可选 vars，以及全部 51 个 colors 令牌。顶层没有 type、ui、syntax 或 borders 键——所有内容都在 colors 下。主题从 ~/.pi/agent/themes/*.json（全局）和 .pi/themes/*.json（项目）加载。
• 按键绑定配置：按键绑定在 ~/.pi/agent/keybindings.json 中配置（而非 settings.json）。ID 使用命名空间：tui.input.submit（提交）、tui.editor.cursorUp、app.interrupt 等。运行 /reload 即可应用更改，无需重启。
• 提示词模板参数：模板使用 $1、$2、$@、${@:N} 位置语法——而非 {variable} 或 <include>。文件名（去掉 .md 后缀）会成为 /name 命令。
• 系统提示词覆盖：使用 .pi/SYSTEM.md（项目级）或 ~/.pi/agent/SYSTEM.md（全局级）替换默认系统提示词。使用 APPEND_SYSTEM.md 可追加内容，而非替换。上下文文件和技能仍会在覆盖内容后追加。

工作流

• 创建主题：从 packages/coding-agent/src/modes/interactive/theme/ 复制 dark.json，自定义 colors 键下的颜色值，将其放入 ~/.pi/agent/themes/，然后通过 /settings 或 pi --theme <name> 选择。
• 覆盖按键绑定：创建或编辑 ~/.pi/agent/keybindings.json，将操作 ID 映射到按键数组（例如，"tui.input.submit": ["ctrl+enter"]）。运行 /reload 即可应用。
• 创建提示词模板：在 ~/.pi/agent/prompts/ 中编写 .md 文件，可选添加 YAML frontmatter（description）；使用 $1、$@ 传递参数。在编辑器中通过 /filename 调用。
• 覆盖系统提示词：在项目中创建 .pi/SYSTEM.md，或在全局位置创建 ~/.pi/agent/SYSTEM.md，以替换默认系统提示词。如果要追加自定义指令，请在相同位置使用 APPEND_SYSTEM.md。

反模式

• 不要将按键绑定硬编码到 Agent 组件源代码中——请使用 keybindings.md 中可配置的命名空间。
• 不要将按键绑定放入 settings.json——按键绑定有自己的文件（~/.pi/agent/keybindings.json）。
• 不要在提示词模板中使用 {variable} 或 <include src="..."> 语法——实际语法是 $1、$@、${@:N}。