pi-using

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pi — Using & Customizing

Pi — 使用与自定义

Two halves of "using pi":

Concern	Section
Workspace, sessions, /commands, providers, models, tmux/Termux/Windows	Workspace
Themes, keybindings, prompt templates, SYSTEM.md overrides	Customization

“使用Pi”分为两部分：

关注点	章节
工作区、会话、/命令、提供商、模型、tmux/Termux/Windows	工作区
主题、按键绑定、提示词模板、SYSTEM.md 覆盖配置	自定义

Workspace

工作区

Pi CLI and workspace

Pi CLI与工作区

Answer only from

pi-mono/

sources listed below. If something is not in the tree, say you cannot confirm from the corpus.

仅从下方列出的

pi-mono/

源文件中获取答案。如果内容不在该目录结构中，请说明无法从现有资料中确认。

Grounding (read in order)

参考依据（按顺序阅读）

```
pi-mono/packages/coding-agent/README.md
```
— product surface, commands, customization.

pi-mono/packages/coding-agent/docs/skills.md

— skill locations,

/skill:name

, frontmatter, collisions.

pi-mono/packages/coding-agent/docs/settings.md

— settings locations and keys.

```
pi-mono/AGENTS.md
```
— maintainer rules when editing pi-mono itself.
```
pi-mono/packages/coding-agent/docs/compaction.md
```
— auto-compaction triggers, cut-point algorithm,
```
reserveTokens
```
/
```
keepRecentTokens
```
settings, chained compactions, branch summarization.
```
pi-mono/packages/coding-agent/docs/session.md
```
— JSONL session format,
```
~/.pi/agent/sessions/
```
paths, entry types (message, compaction, branch_summary, custom, label),
```
buildSessionContext()
```
assembly.
```
pi-mono/packages/coding-agent/docs/tree.md
```
—
```
/tree
```
vs
```
/fork
```
, branch navigation, summarization options, tree UI keybindings.
```
pi-mono/packages/coding-agent/docs/providers.md
```
— subscription OAuth (
```
/login
```
), API-key providers,
```
auth.json
```
, env-var credential table, cloud providers (Azure, Bedrock, Vertex).

pi-mono/packages/coding-agent/docs/models.md

—

models.json

for Ollama/vLLM/LM Studio,

compat

flags,

modelOverrides

, provider-level config.

pi-mono/packages/coding-agent/docs/custom-provider.md

— extension-registered providers via

registerProvider()

, OAuth flows, proxy patterns.

```
pi-mono/packages/coding-agent/docs/terminal-setup.md
```
— Kitty keyboard protocol, Ghostty/iTerm/terminal keybinding caveats.

pi-mono/packages/coding-agent/docs/tmux.md

— tmux

extended-keys

csi-u

so modified keys work inside pi.

```
pi-mono/packages/coding-agent/docs/windows.md
```
— Windows bash discovery order (
```
shellPath
```
setting, Git Bash, PATH).
```
pi-mono/packages/coding-agent/docs/termux.md
```
— running pi on Android via Termux (install, clipboard, storage).

pi-mono/packages/coding-agent/docs/shell-aliases.md

— non-interactive bash and

shellCommandPrefix

to expand aliases from dotfiles.

pi-mono/packages/coding-agent/docs/development.md

— local development setup,

pi-test.sh

, fork/rebrand via

piConfig

, test commands.

Implementation (for precedence and prompt wiring):

pi-mono/packages/coding-agent/src/core/package-manager.ts

—

resourcePrecedenceRank

comment block (ordering intent).

pi-mono/packages/coding-agent/src/core/resource-loader.ts

—

reload()

skill path merge (

cliEnabledSkills

enabledSkills

additionalSkillPaths

pi-mono/packages/coding-agent/src/core/skills.ts

—

loadSkills

formatSkillsForPrompt

, name collision handling.

pi-mono/packages/coding-agent/src/core/system-prompt.ts

— default harness text and

hasRead

gate for skills XML.

pi-mono/packages/coding-agent/src/core/agent-session.ts

—

_expandSkillCommand

inlines

/skill:name

body.

```
pi-mono/packages/coding-agent/README.md
```
§Editor —
```
@
```
fuzzy-search, Tab completion, Ctrl+V image paste,
```
!
```
/
```
!!
```
bash commands.
```
pi-mono/packages/coding-agent/README.md
```
§Message Queue — steering (Enter) vs follow-up (Alt+Enter),
```
steeringMode
```
/
```
followUpMode
```
/
```
transport
```
settings.

pi-mono/packages/coding-agent/README.md

§Modes, §CLI Reference — interactive,

-p

--print

--mode json

--mode rpc

, piped stdin.

pi-mono/packages/coding-agent/README.md

§CLI Reference — full flag table,

@files

--tools

--no-tools

--no-extensions

--no-skills

--no-prompt-templates

--no-themes

, resource control.

pi-mono/packages/coding-agent/README.md

§Environment Variables —

PI_CODING_AGENT_DIR

PI_PACKAGE_DIR

PI_SKIP_VERSION_CHECK

PI_CACHE_RETENTION

VISUAL

EDITOR

```
pi-mono/packages/coding-agent/README.md
```
§Philosophy — what core intentionally omits (no MCP, no sub-agents, no permission popups, no plan mode, no built-in todos, no background bash); everything buildable via extensions.

```
pi-mono/packages/coding-agent/README.md
```
—— 产品界面、命令、自定义配置。

pi-mono/packages/coding-agent/docs/skills.md

—— 技能位置、

/skill:name

、前置内容、命名冲突。

pi-mono/packages/coding-agent/docs/settings.md

—— 设置文件位置及配置项。

```
pi-mono/AGENTS.md
```
—— 维护者编辑pi-mono时需遵循的规则。
```
pi-mono/packages/coding-agent/docs/compaction.md
```
—— 自动压缩触发条件、分割点算法、
```
reserveTokens
```
/
```
keepRecentTokens
```
设置、链式压缩、分支摘要。
```
pi-mono/packages/coding-agent/docs/session.md
```
—— JSONL会话格式、
```
~/.pi/agent/sessions/
```
路径、条目类型（消息、压缩、分支摘要、自定义、标签）、
```
buildSessionContext()
```
组装逻辑。
```
pi-mono/packages/coding-agent/docs/tree.md
```
——
```
/tree
```
与
```
/fork
```
的区别、分支导航、摘要选项、树形UI按键绑定。
```
pi-mono/packages/coding-agent/docs/providers.md
```
—— 订阅OAuth（
```
/login
```
）、API密钥提供商、
```
auth.json
```
、环境变量凭证表、云提供商（Azure、Bedrock、Vertex）。

pi-mono/packages/coding-agent/docs/models.md

—— 针对Ollama/vLLM/LM Studio的

models.json

、

compat

标志、

modelOverrides

、提供商级配置。

pi-mono/packages/coding-agent/docs/custom-provider.md

—— 通过

registerProvider()

注册的扩展提供商、OAuth流程、代理模式。

```
pi-mono/packages/coding-agent/docs/terminal-setup.md
```
—— Kitty键盘协议、Ghostty/iTerm/终端按键绑定注意事项。
```
pi-mono/packages/coding-agent/docs/tmux.md
```
—— tmux的
```
extended-keys
```
/
```
csi-u
```
配置，确保修改后的按键在pi中正常工作。
```
pi-mono/packages/coding-agent/docs/windows.md
```
—— Windows下bash的发现顺序（
```
shellPath
```
设置、Git Bash、PATH）。
```
pi-mono/packages/coding-agent/docs/termux.md
```
—— 通过Termux在Android上运行pi（安装、剪贴板、存储）。
```
pi-mono/packages/coding-agent/docs/shell-aliases.md
```
—— 非交互式bash及
```
shellCommandPrefix
```
配置，用于从点文件中展开别名。
```
pi-mono/packages/coding-agent/docs/development.md
```
—— 本地开发环境设置、
```
pi-test.sh
```
、通过
```
piConfig
```
进行复刻/重命名、测试命令。

实现细节（优先级及提示词关联）：

pi-mono/packages/coding-agent/src/core/package-manager.ts

——

resourcePrecedenceRank

注释块（优先级顺序定义）。

pi-mono/packages/coding-agent/src/core/resource-loader.ts

——

reload()

技能路径合并逻辑（

cliEnabledSkills

、

enabledSkills

、

additionalSkillPaths

）。

pi-mono/packages/coding-agent/src/core/skills.ts

——

loadSkills

、

formatSkillsForPrompt

、命名冲突处理。

pi-mono/packages/coding-agent/src/core/system-prompt.ts

—— 默认框架文本及技能XML的

hasRead

gate。

pi-mono/packages/coding-agent/src/core/agent-session.ts

——

_expandSkillCommand

内联

/skill:name

内容。

```
pi-mono/packages/coding-agent/README.md
```
§编辑器 ——
```
@
```
模糊搜索、Tab补全、Ctrl+V图片粘贴、
```
!
```
/
```
!!
```
bash命令。
```
pi-mono/packages/coding-agent/README.md
```
§消息队列 —— 引导消息（Enter）与跟进消息（Alt+Enter）的区别、
```
steeringMode
```
/
```
followUpMode
```
/
```
transport
```
设置。
```
pi-mono/packages/coding-agent/README.md
```
§模式、§CLI参考 —— 交互式模式、
```
-p
```
/
```
--print
```
、
```
--mode json
```
、
```
--mode rpc
```
、管道输入。

pi-mono/packages/coding-agent/README.md

§CLI参考 —— 完整标志表、

@files

、

--tools

、

--no-tools

、

--no-extensions

、

--no-skills

、

--no-prompt-templates

、

--no-themes

、资源控制。

pi-mono/packages/coding-agent/README.md

§环境变量 ——

PI_CODING_AGENT_DIR

、

PI_PACKAGE_DIR

、

PI_SKIP_VERSION_CHECK

、

PI_CACHE_RETENTION

、

VISUAL

EDITOR

。

```
pi-mono/packages/coding-agent/README.md
```
§设计理念 —— 核心刻意省略的功能（无MCP、无子Agent、无权限弹窗、无计划模式、无内置待办事项、无后台bash）；所有功能均可通过扩展实现。

Invariants

固定规则

Skill name collisions: first registered name wins; later paths emit collision diagnostics (
```
pi-mono/packages/coding-agent/src/core/skills.ts
```
). Path order is assembled in
```
resource-loader.ts
```
then fed to
```
loadSkills
```
.
Resource precedence rank (lower = earlier in sorted package-manager lists): project local (0), project auto (1), user local (2), user auto (3), package (4) —
```
pi-mono/packages/coding-agent/src/core/package-manager.ts
```
.

Merged skill paths:

mergePaths([...cliEnabledSkills, ...enabledSkills], additionalSkillPaths)

— CLI paths appear before package-manager lists; see

pi-mono/packages/coding-agent/src/core/resource-loader.ts

```
<available_skills>
```
is appended to the system prompt only when the read
tool is among selected tools —
```
pi-mono/packages/coding-agent/src/core/system-prompt.ts
```
.
Default system prompt already points models at packaged docs paths (
```
readmePath
```
,
```
docsPath
```
, examples) —
```
pi-mono/packages/coding-agent/src/core/system-prompt.ts
```
. This skill adds workspace and precedence detail, not a duplicate README.
Session format version is v3 (tree-based
```
id
```
/
```
parentId
```
);
```
buildSessionContext
```
assembles compaction summary + branch summary + messages after the compaction point — see
```
pi-mono/packages/coding-agent/docs/session.md
```
.
Compaction cut-point selection avoids splitting tool results;
```
firstKeptEntryId
```
links chained compactions — see
```
pi-mono/packages/coding-agent/docs/compaction.md
```
.
Credential resolution order:
```
--api-key
```
flag >
```
auth.json
```
> environment variables >
```
models.json
```
custom keys — see
```
pi-mono/packages/coding-agent/docs/providers.md
```
.
SYSTEM.md / APPEND_SYSTEM.md: Replace the default system prompt with
```
.pi/SYSTEM.md
```
(project) or
```
~/.pi/agent/SYSTEM.md
```
(global). Append without replacing via
```
APPEND_SYSTEM.md
```
at the same locations. Context files and skills are still appended after override —
```
pi-mono/packages/coding-agent/README.md
```
§Context Files.
Message queue: Enter queues a steering message (delivered between tool calls); Alt+Enter queues a follow-up (delivered after the agent finishes all work). Escape aborts; Alt+Up retrieves queued messages. Settings:
```
steeringMode
```
and
```
followUpMode
```
(
```
"one-at-a-time"
```
default vs
```
"all"
```
);
```
transport
```
(
```
"sse"
```
,
```
"websocket"
```
,
```
"auto"
```
) —
```
pi-mono/packages/coding-agent/README.md
```
§Message Queue,
```
pi-mono/packages/coding-agent/docs/settings.md
```
.
Built-in tools: Default four:
```
read
```
,
```
bash
```
,
```
edit
```
,
```
write
```
. Additional available:
```
grep
```
,
```
find
```
,
```
ls
```
. Control via
```
--tools <list>
```
(e.g.,
```
--tools read,grep,find,ls
```
for read-only) and
```
--no-tools
```
(disables all built-in; extension tools still work) —
```
pi-mono/packages/coding-agent/README.md
```
§Tool Options.
Editor features:
```
@
```
fuzzy-searches project files; Tab completes paths; Ctrl+V pastes images (Alt+V on Windows);
```
!command
```
runs and sends output to LLM;
```
!!command
```
runs without sending —
```
pi-mono/packages/coding-agent/README.md
```
§Editor,
```
pi-mono/packages/coding-agent/docs/keybindings.md
```
.
Print mode:
```
-p
```
/
```
--print
```
for non-interactive stdout output. Reads piped stdin:
```
cat README.md | pi -p "Summarize"
```
. Combine with
```
--mode json
```
for JSON-line output —
```
pi-mono/packages/coding-agent/README.md
```
§Modes.
CLI session flags:
```
-c
```
/
```
--continue
```
(most recent session),
```
-r
```
/
```
--resume
```
(browse/select),
```
--session <path>
```
(specific file or partial UUID),
```
--fork <path>
```
(fork from CLI),
```
--no-session
```
(ephemeral),
```
--session-dir <dir>
```
(custom storage) —
```
pi-mono/packages/coding-agent/README.md
```
§Session Options.
@files CLI arguments: Prefix files with
```
@
```
on CLI:
```
pi @screenshot.png "What's in this?"
```
,
```
pi @code.ts @test.ts "Review"
```
. Included as part of the initial message —
```
pi-mono/packages/coding-agent/README.md
```
§File Arguments.

Resource control flags:

--no-extensions

--no-skills

--no-prompt-templates

--no-themes

disable auto-discovery.

-e

--extension

--skill

--prompt-template

--theme

for explicit loading. Combine

--no-*

with explicit flags for exact control (e.g.,

--no-extensions -e ./my-ext.ts

) —

pi-mono/packages/coding-agent/README.md

§Resource Options.

Model shorthand:

--model provider/id

(e.g.,

openai/gpt-4o

--model name:thinking

(e.g.,

sonnet:high

--models <patterns>

for Ctrl+P cycling,

--list-models

—

pi-mono/packages/coding-agent/README.md

§Model Options.

Slash commands (full interactive list):

/login

/logout

/model

/scoped-models

/settings

/resume

/new

/name

/session

/tree

/fork

/compact

/copy

/export

/share

/reload

/hotkeys

/changelog

/quit

. Extensions register custom commands; skills expose

/skill:name

; prompt templates expand via

/templatename

—

pi-mono/packages/coding-agent/README.md

§Commands.

Environment variables:
```
PI_CODING_AGENT_DIR
```
(override config dir),
```
PI_PACKAGE_DIR
```
(override package dir),
```
PI_SKIP_VERSION_CHECK
```
,
```
PI_CACHE_RETENTION
```
(
```
long
```
for extended prompt cache),
```
VISUAL
```
/
```
EDITOR
```
(external editor for Ctrl+G) —
```
pi-mono/packages/coding-agent/README.md
```
§Environment Variables.
Philosophy (what pi intentionally omits): No MCP (use CLI tools or extensions), no sub-agents (use tmux or extensions), no permission popups (use container or extension), no plan mode (use files or extension), no built-in to-dos, no background bash (use tmux). Everything is buildable via extensions —
```
pi-mono/packages/coding-agent/README.md
```
§Philosophy.

技能命名冲突：先注册的名称优先；后续路径会触发冲突诊断（
```
pi-mono/packages/coding-agent/src/core/skills.ts
```
）。路径顺序由
```
resource-loader.ts
```
组装后传入
```
loadSkills
```
。
资源优先级排名（数值越小，在包管理器列表中越靠前）：项目本地（0）、项目自动（1）、用户本地（2）、用户自动（3）、包内置（4）—— 详见
```
pi-mono/packages/coding-agent/src/core/package-manager.ts
```
。

合并后的技能路径：

mergePaths([...cliEnabledSkills, ...enabledSkills], additionalSkillPaths)

—— CLI路径出现在包管理器列表之前；详见

pi-mono/packages/coding-agent/src/core/resource-loader.ts

。

```
<available_skills>
```
仅在**
```
read
```
工具**被选中时才会追加到系统提示词中 —— 详见
```
pi-mono/packages/coding-agent/src/core/system-prompt.ts
```
。
默认系统提示词已指向打包文档路径（
```
readmePath
```
、
```
docsPath
```
、示例）—— 详见
```
pi-mono/packages/coding-agent/src/core/system-prompt.ts
```
。本技能补充工作区及优先级细节，并非重复README内容。
会话格式版本为v3（基于树形结构的
```
id
```
/
```
parentId
```
）；
```
buildSessionContext
```
会组装压缩摘要 + 分支摘要 + 压缩点之后的消息 —— 详见
```
pi-mono/packages/coding-agent/docs/session.md
```
。
压缩分割点选择会避免拆分工具结果；
```
firstKeptEntryId
```
关联链式压缩 —— 详见
```
pi-mono/packages/coding-agent/docs/compaction.md
```
。
凭证解析顺序：
```
--api-key
```
标志 >
```
auth.json
```
> 环境变量 >
```
models.json
```
自定义密钥 —— 详见
```
pi-mono/packages/coding-agent/docs/providers.md
```
。
SYSTEM.md / APPEND_SYSTEM.md：使用项目目录下的
```
.pi/SYSTEM.md
```
或全局的
```
~/.pi/agent/SYSTEM.md
```
替换默认系统提示词。使用相同位置的
```
APPEND_SYSTEM.md
```
可追加内容而非替换。覆盖后仍会追加上下文文件和技能 —— 详见
```
pi-mono/packages/coding-agent/README.md
```
§上下文文件。
消息队列：Enter键将消息加入引导队列（在工具调用之间传递）；Alt+Enter将消息加入跟进队列（在Agent完成所有工作后传递）。Escape键中止；Alt+Up键检索已排队消息。设置项：
```
steeringMode
```
和
```
followUpMode
```
（默认
```
"one-at-a-time"
```
vs
```
"all"
```
）；
```
transport
```
（
```
"sse"
```
、
```
"websocket"
```
、
```
"auto"
```
）—— 详见
```
pi-mono/packages/coding-agent/README.md
```
§消息队列、
```
pi-mono/packages/coding-agent/docs/settings.md
```
。
内置工具：默认四个工具：
```
read
```
、
```
bash
```
、
```
edit
```
、
```
write
```
。额外可用工具：
```
grep
```
、
```
find
```
、
```
ls
```
。可通过
```
--tools <列表>
```
（例如
```
--tools read,grep,find,ls
```
启用只读模式）和
```
--no-tools
```
（禁用所有内置工具；扩展工具仍可使用）控制 —— 详见
```
pi-mono/packages/coding-agent/README.md
```
§工具选项。
编辑器功能：
```
@
```
模糊搜索项目文件；Tab键补全路径；Ctrl+V粘贴图片（Windows下为Alt+V）；
```
!command
```
运行命令并将输出发送给LLM；
```
!!command
```
运行命令但不发送输出 —— 详见
```
pi-mono/packages/coding-agent/README.md
```
§编辑器、
```
pi-mono/packages/coding-agent/docs/keybindings.md
```
。
打印模式：
```
-p
```
/
```
--print
```
用于非交互式标准输出。支持管道输入：
```
cat README.md | pi -p "Summarize"
```
。结合
```
--mode json
```
可输出JSON行格式 —— 详见
```
pi-mono/packages/coding-agent/README.md
```
§模式。
CLI会话标志：
```
-c
```
/
```
--continue
```
（最近会话）、
```
-r
```
/
```
--resume
```
（浏览/选择会话）、
```
--session <路径>
```
（指定文件或部分UUID）、
```
--fork <路径>
```
（从CLI复刻会话）、
```
--no-session
```
（临时会话）、
```
--session-dir <目录>
```
（自定义存储目录）—— 详见
```
pi-mono/packages/coding-agent/README.md
```
§会话选项。
@files CLI参数：在CLI中用
```
@
```
前缀指定文件：
```
pi @screenshot.png "What's in this?"
```
、
```
pi @code.ts @test.ts "Review"
```
。文件内容会作为初始消息的一部分传入 —— 详见
```
pi-mono/packages/coding-agent/README.md
```
§文件参数。

资源控制标志：

--no-extensions

、

--no-skills

、

--no-prompt-templates

、

--no-themes

禁用自动发现。

-e

--extension

、

--skill

、

--prompt-template

、

--theme

用于显式加载。结合

--no-*

与显式标志可实现精确控制（例如

--no-extensions -e ./my-ext.ts

）—— 详见

pi-mono/packages/coding-agent/README.md

§资源选项。

模型简写：

--model provider/id

（例如

openai/gpt-4o

）、

--model name:thinking

（例如

sonnet:high

）、

--models <模式>

用于Ctrl+P循环切换、

--list-models

列出所有模型 —— 详见

pi-mono/packages/coding-agent/README.md

§模型选项。

斜杠命令（完整交互式列表）：
```
/login
```
、
```
/logout
```
、
```
/model
```
、
```
/scoped-models
```
、
```
/settings
```
、
```
/resume
```
、
```
/new
```
、
```
/name
```
、
```
/session
```
、
```
/tree
```
、
```
/fork
```
、
```
/compact
```
、
```
/copy
```
、
```
/export
```
、
```
/share
```
、
```
/reload
```
、
```
/hotkeys
```
、
```
/changelog
```
、
```
/quit
```
。扩展可注册自定义命令；技能可暴露
```
/skill:name
```
；提示词模板可通过
```
/templatename
```
展开 —— 详见
```
pi-mono/packages/coding-agent/README.md
```
§命令。
环境变量：
```
PI_CODING_AGENT_DIR
```
（覆盖配置目录）、
```
PI_PACKAGE_DIR
```
（覆盖包目录）、
```
PI_SKIP_VERSION_CHECK
```
、
```
PI_CACHE_RETENTION
```
（
```
long
```
表示扩展提示词缓存）、
```
VISUAL
```
/
```
EDITOR
```
（Ctrl+G调用的外部编辑器）—— 详见
```
pi-mono/packages/coding-agent/README.md
```
§环境变量。
设计理念（pi刻意省略的功能）：无MCP（使用CLI工具或扩展）、无子Agent（使用tmux或扩展）、无权限弹窗（使用容器或扩展）、无计划模式（使用文件或扩展）、无内置待办事项、无后台bash（使用tmux）。所有功能均可通过扩展实现 —— 详见
```
pi-mono/packages/coding-agent/README.md
```
§设计理念。

Workflows

工作流程

Find where a skill is discovered: Walk
```
docs/skills.md
```
locations, then cross-check
```
package-manager.ts
```
auto-discovery and
```
settings.json
```
```
skills
```
arrays.
Explain shadowing: Combine
```
resourcePrecedenceRank
```
ordering with
```
mergePaths
```
/
```
loadSkills
```
"first name wins" using file citations only.

User forced load:

/skill:name

expansion —

pi-mono/packages/coding-agent/src/core/agent-session.ts

Debug compaction: Read
```
compaction.md
```
algorithm; check
```
reserveTokens
```
/
```
keepRecentTokens
```
in
```
settings.json
```
; trace chained compactions via
```
firstKeptEntryId
```
.
Add custom model: Follow
```
models.md
```
minimal example for Ollama/vLLM/LM Studio; check
```
compat
```
flags for non-standard OpenAI-compatible servers.
Session archaeology: Parse
```
.jsonl
```
using the switch example in
```
session.md
```
; navigate branches via
```
/tree
```
per
```
tree.md
```
.
Configure providers: Check
```
providers.md
```
for subscription OAuth (
```
/login
```
) vs API-key flow; see
```
auth.json
```
layout and env-var table.
Platform setup: For tmux, read
```
tmux.md
```
(
```
extended-keys
```
); for Windows,
```
windows.md
```
(
```
shellPath
```
); for Android,
```
termux.md
```
; for terminal quirks,
```
terminal-setup.md
```
.
Shell aliases: Read
```
shell-aliases.md
```
for
```
shellCommandPrefix
```
to make pi's bash tool see dotfile aliases.
Develop pi from source: Read
```
development.md
```
for clone/build/test and
```
pi-test.sh
```
runner.
Control tools: Use
```
--tools read,grep,find,ls
```
for read-only mode;
```
--no-tools
```
to disable all built-in tools (extension tools still work). Default is
```
read,bash,edit,write
```
.
Non-interactive mode:
```
pi -p "prompt"
```
or
```
cat file | pi -p "Summarize"
```
for CI/scripts. Combine with
```
--mode json
```
for machine-readable JSON-line output.
Custom system prompt: Place
```
.pi/SYSTEM.md
```
in a project or
```
~/.pi/agent/SYSTEM.md
```
globally to replace the default prompt. Use
```
APPEND_SYSTEM.md
```
at the same locations to append without replacing.

查找技能发现位置：查看
```
docs/skills.md
```
中的位置，然后交叉验证
```
package-manager.ts
```
中的自动发现逻辑和
```
settings.json
```
中的
```
skills
```
数组。
解释阴影覆盖：结合
```
resourcePrecedenceRank
```
排序与
```
mergePaths
```
/
```
loadSkills
```
的“先注册名称优先”规则，仅引用文件说明。

用户强制加载：

/skill:name

展开逻辑 —— 详见

pi-mono/packages/coding-agent/src/core/agent-session.ts

。

调试压缩功能：阅读
```
compaction.md
```
中的算法；检查
```
settings.json
```
中的
```
reserveTokens
```
/
```
keepRecentTokens
```
设置；通过
```
firstKeptEntryId
```
追踪链式压缩。
添加自定义模型：按照
```
models.md
```
中的最简示例配置Ollama/vLLM/LM Studio；为非标准OpenAI兼容服务器检查
```
compat
```
标志。
会话溯源：使用
```
session.md
```
中的示例解析
```
.jsonl
```
文件；通过
```
/tree
```
按照
```
tree.md
```
中的说明导航分支。
配置提供商：查看
```
providers.md
```
中的订阅OAuth（
```
/login
```
）与API密钥流程；参考
```
auth.json
```
结构和环境变量表。
平台设置：tmux参考
```
tmux.md
```
（
```
extended-keys
```
）；Windows参考
```
windows.md
```
（
```
shellPath
```
）；Android参考
```
termux.md
```
；终端兼容性参考
```
terminal-setup.md
```
。
Shell别名：阅读
```
shell-aliases.md
```
中的
```
shellCommandPrefix
```
配置，使pi的bash工具能识别点文件中的别名。
从源码开发pi：阅读
```
development.md
```
中的克隆/构建/测试步骤及
```
pi-test.sh
```
运行器。
控制工具：使用
```
--tools read,grep,find,ls
```
启用只读模式；使用
```
--no-tools
```
禁用所有内置工具（扩展工具仍可使用）。默认工具为
```
read,bash,edit,write
```
。
非交互式模式：
```
pi -p "prompt"
```
或
```
cat file | pi -p "Summarize"
```
适用于CI/脚本场景。结合
```
--mode json
```
可输出机器可读的JSON行格式。
自定义系统提示词：在项目目录下创建
```
.pi/SYSTEM.md
```
或全局创建
```
~/.pi/agent/SYSTEM.md
```
以替换默认提示词。使用相同位置的
```
APPEND_SYSTEM.md
```
可追加自定义指令而非替换。

Anti-patterns

反模式

Do not invent MCP or sub-agent behavior as "built into core"; check
```
pi-mono/packages/coding-agent/README.md
```
philosophy section for what core omits.
Do not claim exact merge behavior without citing
```
resource-loader.ts
```
and
```
skills.ts
```
.
Do not describe compaction cut-point behavior from memory; cite
```
compaction.md
```
algorithm section.
Do not guess credential resolution order; cite
```
providers.md
```
for the exact precedence.

不要将MCP或子Agent行为描述为“核心内置”；查看
```
pi-mono/packages/coding-agent/README.md
```
中的设计理念部分了解核心省略的功能。
不要在未引用
```
resource-loader.ts
```
和
```
skills.ts
```
的情况下描述合并行为。
不要凭记忆描述压缩分割点行为；引用
```
compaction.md
```
中的算法部分。
不要猜测凭证解析顺序；引用
```
providers.md
```
中的精确优先级。

Customization

自定义

Pi Customization

Pi自定义配置

Grounding

参考依据

```
pi-mono/packages/coding-agent/docs/themes.md
```
— theme JSON format (
```
name
```
, optional
```
vars
```
, required 51
```
colors
```
tokens), locations (
```
~/.pi/agent/themes/*.json
```
,
```
.pi/themes/*.json
```
, packages, settings, CLI
```
--theme
```
), hot reload, color value formats.

pi-mono/packages/coding-agent/docs/keybindings.md

— customization via

~/.pi/agent/keybindings.json

, namespaced action IDs (

tui.input.submit

tui.editor.cursorUp

app.interrupt

, etc.), key format (

modifier+key

), full action tables.

pi-mono/packages/coding-agent/docs/prompt-templates.md

— Markdown snippets invoked via

/name

, locations (

~/.pi/agent/prompts/*.md

.pi/prompts/*.md

, packages), positional arguments (

$1

$2

$@

${@:N}

), YAML frontmatter with optional

description

pi-mono/packages/coding-agent/README.md

— Context Files section for

.pi/SYSTEM.md

~/.pi/agent/SYSTEM.md

, and

APPEND_SYSTEM.md

pi-mono/packages/coding-agent/docs/settings.md

— the overall

settings.json

structure for tying these together.

```
pi-mono/packages/coding-agent/docs/themes.md
```
—— 主题JSON格式（
```
name
```
、可选
```
vars
```
、必填51个
```
colors
```
令牌）、位置（
```
~/.pi/agent/themes/*.json
```
、
```
.pi/themes/*.json
```
、包内置、设置、CLI
```
--theme
```
）、热重载、颜色值格式。

pi-mono/packages/coding-agent/docs/keybindings.md

—— 通过

~/.pi/agent/keybindings.json

自定义、命名空间化的动作ID（

tui.input.submit

、

tui.editor.cursorUp

、

app.interrupt

等）、按键格式（

modifier+key

）、完整动作表。

```
pi-mono/packages/coding-agent/docs/prompt-templates.md
```
—— 通过
```
/name
```
调用的Markdown片段、位置（
```
~/.pi/agent/prompts/*.md
```
、
```
.pi/prompts/*.md
```
、包内置）、位置参数（
```
$1
```
、
```
$2
```
、
```
$@
```
、
```
${@:N}
```
）、带可选
```
description
```
的YAML前置内容。

pi-mono/packages/coding-agent/README.md

—— 上下文文件章节，介绍

.pi/SYSTEM.md

、

~/.pi/agent/SYSTEM.md

和

APPEND_SYSTEM.md

。

pi-mono/packages/coding-agent/docs/settings.md

—— 整合所有配置的

settings.json

整体结构。

Invariants

固定规则

Theme Format: Themes define
```
name
```
(required, unique), optional
```
vars
```
for reusable color aliases, and all 51
```
colors
```
tokens. There is no
```
type
```
,
```
ui
```
,
```
syntax
```
, or
```
borders
```
top-level key — everything is under
```
colors
```
. Loaded from
```
~/.pi/agent/themes/*.json
```
(global) and
```
.pi/themes/*.json
```
(project).
Keybinding Config: Keybindings are configured in
```
~/.pi/agent/keybindings.json
```
(not
```
settings.json
```
). IDs are namespaced:
```
tui.input.submit
```
(submit),
```
tui.editor.cursorUp
```
,
```
app.interrupt
```
, etc. Run
```
/reload
```
to apply changes without restarting.
Prompt Template Arguments: Templates use
```
$1
```
,
```
$2
```
,
```
$@
```
,
```
${@:N}
```
positional syntax — not
```
{variable}
```
or
```
<include>
```
. The filename (minus
```
.md
```
) becomes the
```
/name
```
command.
System Prompt Override: Replace the default system prompt with
```
.pi/SYSTEM.md
```
(project) or
```
~/.pi/agent/SYSTEM.md
```
(global). Use
```
APPEND_SYSTEM.md
```
to append instead of replace. Context files and skills are still appended after the override.

主题格式：主题需定义
```
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
```
可追加内容而非替换。覆盖后仍会追加上下文文件和技能。

Workflows

工作流程

Create a Theme: Copy

dark.json

from

packages/coding-agent/src/modes/interactive/theme/

, customize color values under the

colors

key, place it in

~/.pi/agent/themes/

, and select via

/settings

pi --theme <name>

Override Keys: Create or edit
```
~/.pi/agent/keybindings.json
```
mapping action IDs to key arrays (e.g.,
```
"tui.input.submit": ["ctrl+enter"]
```
). Run
```
/reload
```
to apply.
Create a Prompt Template: Write a
```
.md
```
file in
```
~/.pi/agent/prompts/
```
with optional YAML frontmatter (
```
description
```
); use
```
$1
```
,
```
$@
```
for arguments. Invoke with
```
/filename
```
in the editor.
Override the System Prompt: Create
```
.pi/SYSTEM.md
```
in the project or
```
~/.pi/agent/SYSTEM.md
```
globally to replace the default system prompt. Use
```
APPEND_SYSTEM.md
```
at the same locations if you want to append custom instructions instead.

创建主题：复制

packages/coding-agent/src/modes/interactive/theme/

中的

dark.json

，自定义

colors

下的颜色值，将其放入

~/.pi/agent/themes/

，然后通过

/settings

或

pi --theme <名称>

选择。

覆盖按键绑定：创建或编辑
```
~/.pi/agent/keybindings.json
```
，将动作ID映射到按键数组（例如
```
"tui.input.submit": ["ctrl+enter"]
```
）。运行
```
/reload
```
应用更改。
创建提示词模板：在
```
~/.pi/agent/prompts/
```
中创建
```
.md
```
文件，可添加可选的YAML前置内容（
```
description
```
）；使用
```
$1
```
、
```
$@
```
定义参数。在编辑器中通过
```
/filename
```
调用。
覆盖系统提示词：在项目目录下创建
```
.pi/SYSTEM.md
```
或全局创建
```
~/.pi/agent/SYSTEM.md
```
以替换默认系统提示词。如果希望追加自定义指令而非替换，可使用相同位置的
```
APPEND_SYSTEM.md
```
。

Anti-patterns

反模式

Do not hardcode keybindings into agent component source code — use the configurable namespaces from
```
keybindings.md
```
.
Do not put keybindings in
```
settings.json
```
— keybindings have their own file (
```
~/.pi/agent/keybindings.json
```
).
Do not use
```
{variable}
```
or
```
<include src="...">
```
syntax in prompt templates — the actual syntax is
```
$1
```
,
```
$@
```
,
```
${@:N}
```
.

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

另请参阅（相关技能 — Pi系列）

If your issue relates to:

extending Pi: TypeScript extensions, npm packages, JSON-RPC SDK, pi_agent_rust internals — check
```
pi-extending
```
if appropriate.

如果你的问题涉及：

扩展Pi：TypeScript扩展、npm包、JSON-RPC SDK、pi_agent_rust内部实现 —— 请查看
```
pi-extending
```
技能（如有）。

pi-using

Original

Translation

Pi — Using & Customizing

Pi — 使用与自定义

Workspace

工作区

Pi CLI and workspace

Pi CLI与工作区

Grounding (read in order)

参考依据（按顺序阅读）

Invariants

固定规则

Workflows

工作流程

Anti-patterns

反模式

Customization

自定义

Pi Customization

Pi自定义配置

Grounding

参考依据

Invariants

固定规则

Workflows

工作流程

Anti-patterns

反模式

See also (related skills — Pi family)

另请参阅（相关技能 — Pi系列）