书籍

书籍栏目收录以整本书形式组织的文档。每本书拥有独立的目录、章节编号与侧边栏。

收录书目

• Pi 用户手册

Pi 用户手册

Pi 是一个极简的终端编码智能体框架。它的核心保持小巧，通过 TypeScript 扩展、技能、提示词模板、主题和 pi 包来扩展能力。

本手册翻译自 pi 官方文档。

快速开始

使用 npm 安装 Pi：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

--ignore-scripts 会在安装过程中禁用依赖的生命周期脚本。pi 在常规 npm 安装下不需要执行安装脚本。

在 Linux 或 macOS 上，也可以使用安装脚本：

curl -fsSL https://pi.dev/install.sh | sh

卸载 pi 本体时（无论当初用 curl 还是 npm 安装），使用 npm：

npm uninstall -g @earendil-works/pi-coding-agent

如果使用 pnpm、Yarn 或 Bun 安装，请使用对应的全局卸载命令：pnpm remove -g @earendil-works/pi-coding-agent、yarn global remove @earendil-works/pi-coding-agent 或 bun uninstall -g @earendil-works/pi-coding-agent。

然后在项目目录中运行：

pi

订阅制提供商通过 /login 完成认证，或在启动 pi 前设置 API 密钥（例如 ANTHROPIC_API_KEY）。

完整的首次运行流程参见快速开始。

目录

1 快速开始

本页带你从安装一路走到完成第一个实用的 pi 会话。

安装

Pi 以 npm 包的形式分发：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

--ignore-scripts 会在安装过程中禁用依赖的生命周期脚本。在常规 npm 安装下，Pi 不需要安装脚本。

卸载

使用安装 pi 时所用的包管理器来卸载。curl 安装器底层使用全局 npm，因此 curl 和 npm 安装的版本都用 npm 卸载：

# curl installer or npm install -g
npm uninstall -g @earendil-works/pi-coding-agent

# pnpm
pnpm remove -g @earendil-works/pi-coding-agent

# Yarn
yarn global remove @earendil-works/pi-coding-agent

# Bun
bun uninstall -g @earendil-works/pi-coding-agent

卸载 pi 后，设置、凭据、会话以及已安装的 pi 包会保留在 ~/.pi/agent/ 中。

然后在想让 pi 处理的项目目录中启动它：

cd /path/to/project
pi

认证

Pi 可以通过 /login 使用订阅型提供商，也可以通过环境变量或认证文件使用 API 密钥型提供商。

方式一：订阅登录

启动 pi 并运行：

/login

然后选择一个提供商。内置的订阅登录包括 Claude Pro/Max、ChatGPT Plus/Pro（Codex）以及 GitHub Copilot。

方式二：API 密钥

在启动 pi 之前设置 API 密钥：

export ANTHROPIC_API_KEY=sk-ant-...
pi

也可以运行 /login 并选择一个 API 密钥型提供商，把密钥存入 ~/.pi/agent/auth.json。

所有受支持的提供商、环境变量以及云端提供商的配置，请参阅提供商。

第一个会话

pi 启动后，输入一个请求并按回车：

Summarize this repository and tell me how to run its checks.

默认情况下，pi 会为模型提供四个工具：

• read - 读取文件
• write - 创建或覆盖文件
• edit - 修补文件
• bash - 运行 shell 命令

更多内置只读工具（grep、find、ls）可通过工具选项启用。Pi 在你当前的工作目录中运行，并且可以修改其中的文件。如果想要方便地回滚，请使用 git 或其他检查点工作流。

为 pi 提供项目指令

Pi 启动时会加载上下文文件。添加一个 AGENTS.md 文件，告诉它在这个项目中如何工作：

# Project Instructions

- Run `npm run check` after code changes.
- Do not run production migrations locally.
- Keep responses concise.

Pi 会加载：

• ~/.pi/agent/AGENTS.md：全局指令
• 当前目录及父目录中的 AGENTS.md 或 CLAUDE.md

如果某个目录中存在 AGENTS.override.md，Pi 会加载它来取代该目录中的 AGENTS.md 或 CLAUDE.md。

修改上下文文件后，请重启 pi 或运行 /reload。

常用操作

引用文件

在编辑器中输入 @ 可以模糊搜索文件，也可以在命令行上直接传入文件：

pi @README.md "Summarize this"
pi @src/app.ts @src/app.test.ts "Review these together"

图片或文本可以用 Ctrl+V 粘贴（Windows 上是 Alt+V）；图片也可以直接拖入支持的终端。

运行 shell 命令

在交互模式下：

!npm run lint

命令输出会发送给模型。使用 !!command 可以运行命令而不把输出加入模型上下文。

切换模型

使用 /model 或 Ctrl+L 为当前会话选择模型。在模型选择器中按 Ctrl+S，可以把高亮的模型保存为启动默认值。使用 /thinking 为当前会话选择思考级别；在该选择器中按 Ctrl+S 可保存启动默认的思考级别。使用 Shift+Tab 可以循环切换思考级别。使用 Ctrl+P / Shift+Ctrl+P 可以在限定范围（scoped）的模型之间循环切换。

稍后继续

会话会自动保存：

pi -c                  # Continue most recent session
pi -r                  # Browse previous sessions
pi --name "my task"    # Set session display name at startup
pi --session <path|id> # Open a specific session

在 pi 内部，使用 /resume、/new、/tree、/fork 和 /clone 管理会话。

非交互模式

一次性提示可以这样运行：

pi -p "Summarize this codebase"
cat README.md | pi -p "Summarize this text"
pi -p @screenshot.png "What's in this image?"

使用 --mode json 输出 JSON 事件流，或使用 --mode rpc 进行进程集成。

后续步骤

• 使用 Pi——交互模式、slash 命令、会话、上下文文件与 CLI 参考。
• 提供商——认证与模型配置。
• 设置——全局与项目配置。
• 快捷键——快捷键与自定义。
• Pi 包——安装共享的扩展、技能、提示词模板和主题。

平台说明：Windows、Termux、tmux、终端配置、Shell 别名。

2 使用 Pi

本页面收录了不适合放在快速开始页面中的日常使用细节。

交互模式

界面分为四个主要区域：

• 启动头部——快捷方式、已加载的上下文文件、提示词模板、技能和扩展
• 消息区——用户消息、助手回复、工具调用、工具结果、通知、错误和扩展 UI
• 编辑器——你输入内容的地方；边框颜色指示当前的思考级别
• 底部栏——工作目录、会话名称、token/缓存用量、费用、上下文用量和当前模型。总计包含助手回复、工具报告的用量以及摘要生成。

编辑器可以被内置 UI（如 /settings）或自定义扩展 UI 临时替换。

编辑器功能

所有快捷键及自定义方式参见快捷键。

斜杠命令

在编辑器中输入 / 打开命令补全。扩展可以注册自定义命令，技能以 /skill:name 的形式提供，提示词模板通过 /templatename 展开。

消息队列

你可以在智能体仍在工作时提交消息：

• Enter 将一条转向消息加入队列，在当前助手回合执行完其工具调用后送达。
• Alt+Enter 将一条后续消息加入队列，在智能体完成所有工作后送达。
• Escape 中止操作，并将排队的消息恢复到编辑器中。
• Alt+Up 将排队的消息取回编辑器。

在 Windows Terminal 中，Alt+Enter 默认是全屏快捷键。如果希望 pi 接收到该快捷键，请按终端设置中的说明重新映射。

可在设置中通过 steeringMode 和 followUpMode 配置送达方式。

会话

会话会自动保存到 ~/.pi/agent/sessions/，按工作目录组织。

pi -c                  # Continue most recent session
pi -r                  # Browse and select a session
pi --no-session        # Ephemeral mode; do not save
pi --name "my task"    # Set session display name at startup
pi --session <path|id> # Use a specific session file or session ID
pi --fork <path|id>    # Fork a session into a new session file

常用的会话命令：

• /session 显示当前会话文件和 ID。
• /tree 导航会话文件内的会话树，并可以总结被放弃的分支。
• /fork 从更早的用户消息创建新会话。
• /clone 将当前活动分支复制到一个新的会话文件。
• /compact 总结较旧的消息以释放上下文。

详情参见会话和上下文压缩。

上下文文件

Pi 启动时会从以下位置加载 AGENTS.md 或 CLAUDE.md：

• ~/.pi/agent/AGENTS.md 用于全局指令
• 从当前工作目录向上遍历的父目录
• 当前目录

如果某个目录包含 AGENTS.override.md，Pi 会改为加载它，而不再加载该目录中的 AGENTS.md 或 CLAUDE.md。来自其他目录的上下文文件仍照常分层叠加。

可以用上下文文件记录项目约定、命令、安全规则和偏好。使用 --no-context-files 或 -nc 禁用加载。

系统提示词文件

替换默认系统提示词：

• 项目级：.pi/SYSTEM.md
• 全局：~/.pi/agent/SYSTEM.md

在上述任一位置放置 APPEND_SYSTEM.md，可以在默认提示词后追加内容而不替换它。

项目信任

在交互式启动时，如果项目文件夹包含项目本地设置、资源或项目级 .agents/skills，且在 ~/.pi/agent/trust.json 中没有针对该文件夹或其父文件夹的已保存决定，pi 会先询问是否信任该项目。信任项目后，pi 才能加载 .pi/settings.json 和 .pi 资源、安装缺失的项目包，并执行项目扩展。

在做出信任决定之前，pi 只加载上下文文件、用户/全局扩展以及 CLI -e 扩展，以便它们能够处理 project_trust 事件。项目本地扩展、项目包管理的扩展和项目设置只有在项目被信任后才会加载。当切换到来自其他 cwd、且信任尚未在当前进程中确定的会话时，同样适用这一划分。

非交互模式（-p、--mode json 和 --mode rpc）不显示信任提示。在没有适用的已保存信任决定时，它们使用全局设置中的 defaultProjectTrust：ask（默认）和 never 会忽略这些项目资源，而 always 则信任它们。传入 --approve/-a 或 --no-approve/-na 可为单次运行覆盖项目信任。

如果没有扩展或已保存决定适用，则由 defaultProjectTrust 控制回退行为。在 ~/.pi/agent/settings.json 中将其设为 "ask"、"always" 或 "never"，或通过 /settings 修改。

pi config 和包管理命令使用相同的项目信任流程，但 pi update 从不弹出提示。传入 --approve 可为单条命令信任项目本地设置，传入 --no-approve 则忽略它们。

在交互模式下使用 /trust 可以为未来会话保存项目信任决定，包括对直接父文件夹的信任。它只写入 ~/.pi/agent/trust.json；当前会话不会重新加载，因此需重启 pi 才能生效。

导出与分享会话

使用 /export [file] 将会话写入 HTML 文件。

使用 /share 上传一个私有 GitHub gist，并附带可分享的 HTML 链接。

如果你将 pi 用于开源工作，并希望发布会话以供模型、提示词、工具和评估研究使用，请参见 badlogic/pi-share-hf。它可以将会话发布到 Hugging Face 数据集。

CLI 参考

pi [options] [--] [@files...] [messages...]

包管理命令

pi install <source> [-l]     # Install package, -l for project-local
pi remove <source> [-l]      # Remove package
pi uninstall <source> [-l]   # Alias for remove
pi update [source|self|pi]   # Update pi only, or one package source
pi update --all              # Update pi and packages; reconcile pinned git refs
pi update --extensions       # Update packages only; reconcile pinned git refs
pi update --models           # Refresh model catalogs only
pi update --self             # Update pi only
pi update --extension <src>  # Update one package
pi list                      # List installed packages
pi config                    # Enable/disable package resources

这些命令用于管理 pi 包，pi update 还可以更新 pi CLI 本体。要卸载 pi 本体，请参见快速开始。pi config 和项目包命令接受 --approve/--no-approve，用于为单条命令信任或忽略项目本地设置。pi update 从不因项目信任而弹出提示。

包来源与安全说明参见 Pi 包。

模式

在打印模式下，pi 还会读取管道传入的 stdin 并将其合并到初始提示词中：

cat README.md | pi -p "Summarize this text"

模型选项

会话选项

工具选项

内置工具包括：read、bash、powershell（Windows）、edit、write、grep、find、ls。

资源选项

将 --no-* 与显式标志组合使用，可以忽略设置、精确加载所需资源。示例：

pi --no-extensions -e ./my-extension.ts

其他选项

在 fullscreen 模式下，对话记录在终端视口内滚动，而排队消息、工作状态、扩展小部件、编辑器和底部栏固定在底部。鼠标/触控板输入会滚动指针所在区域；键盘视口操作始终可用。行内图片在支持 Kitty 图形协议的终端（包括 Kitty 和 Ghostty）中可以正常显示。在 iTerm2 中，它们会渲染为文本占位符，因为 iTerm2 的行内图片协议无法在应用接管滚动期间删除或裁剪已放置的图片。在 regular 模式下，pi 使用主屏幕和终端自带的回滚缓冲区，iTerm2 中的行内图片可继续正常渲染。各终端的专属设置与变通方案参见终端设置。

在 /settings 中设置 TUI 模式，可以立即在 regular 和 fullscreen 之间切换，并为未来会话选择默认值。全屏退出输出控制退出全屏时是打印最终对话记录，还是恢复之前的屏幕并只打印会话恢复提示。

文件参数

为文件名加上 @ 前缀可将其包含在消息中：

pi @prompt.md "Answer this"
pi -p @screenshot.png "What's in this image?"
pi @code.ts @test.ts "Review these files"

示例

# Interactive with initial prompt
pi "List all .ts files in src/"

# Non-interactive
pi -p "Summarize this codebase"

# Prompt beginning with a dash
pi -p -- "- Summarize these points"

# Non-interactive with piped stdin
cat README.md | pi -p "Summarize this text"

# Named one-shot session
pi --name "release audit" -p "Audit this repository"

# Different model
pi --provider openai --model gpt-4o "Help me refactor"

# Model with provider prefix
pi --model openai/gpt-4o "Help me refactor"

# Model with thinking level shorthand
pi --model sonnet:high "Solve this complex problem"

# Limit model cycling
pi --models "claude-*,gpt-4o"

# Read-only mode
pi --tools read,grep,find,ls -p "Review the code"

# Disable one extension or built-in tool while keeping the rest available
pi --exclude-tools ask_question

设计原则

Pi 保持核心小巧，将特定工作流的行为推送到扩展、技能、提示词模板和包中。

它有意不内置 MCP、子智能体、权限弹窗、计划模式、待办事项或后台 bash。你可以将这些工作流构建或安装为扩展或包，也可以使用容器和 tmux 等外部工具。

完整的设计理由请阅读博客文章。

3 提供商

Pi 通过 OAuth 支持订阅制提供商，通过环境变量或认证文件支持 API 密钥提供商。内置模型目录随 pi 一起发布；已配置的提供商可以刷新更新的目录，并将其缓存到 ~/.pi/agent/models-store.json 以供离线使用。

目录

• 订阅
• API 密钥
• 认证文件
• 云端提供商
• llama.cpp
• 自定义提供商
• 解析顺序

订阅

在交互模式下使用 /login，然后选择一个提供商：

• ChatGPT Plus/Pro（Codex）
• Claude Pro/Max
• GitHub Copilot
• xAI（Grok/X 订阅）
• OpenRouter（通过 OAuth 铸造的 API 密钥，从 OpenRouter 余额计费）
• Radius

使用 /logout 清除凭证。令牌存储在 ~/.pi/agent/auth.json 中，过期时自动刷新。OpenRouter 则会铸造一个由用户控制的 API 密钥，它不会自动过期。

OpenAI Codex

• 需要 ChatGPT Plus 或 Pro 订阅
• 由 OpenAI 官方背书：Codex for OSS

Claude Pro/Max

Anthropic 订阅认证适用于 Claude Pro/Max 账户。第三方工具的使用会消耗额外用量，并按 token 计费，而不计入 Claude 套餐限额。

GitHub Copilot

• 在 github.com 上直接按 Enter，或输入你的 GitHub Enterprise Server 域名
• 如果出现 “model not supported”，请在 VS Code 中启用该模型：Copilot Chat → 模型选择器 → 选择模型 → “Enable”

xAI（Grok/X 订阅）

• 运行 /login xai，然后选择 Use a subscription
• XAI_API_KEY 仍可通过 Use an API key 使用

OpenRouter

• 运行 /login openrouter，然后选择 Sign in with OpenRouter，打开 OpenRouter PKCE 授权流程
• 授权会创建一个由用户控制的 OpenRouter API 密钥，从你的 OpenRouter 余额中扣费
• 在远程/无头机器上（例如通过 SSH 连接），浏览器无法访问本地回环回调；此时请将最终重定向 URL（或授权码）粘贴到登录提示中
• OPENROUTER_API_KEY 仍可通过 Use an API key 使用

Radius

Radius 是一个动态 pi-messages 网关。/login radius 会将 OAuth 令牌存储到 auth.json；网关目录会独立刷新并缓存到 models-store.json。自定义 Radius 网关可以在 models.json 中通过 "oauth": "radius" 和网关 baseUrl 声明。

API 密钥

环境变量或认证文件

在交互模式下使用 /login 并选择一个提供商，即可将 API 密钥存入 auth.json；也可以通过环境变量设置凭证：

export ANTHROPIC_API_KEY=sk-ant-...
pi

环境变量与 auth.json 键的对照参见 packages/ai/src/env-api-keys.ts 中的 const envMap。

认证文件

将凭证存储在 ~/.pi/agent/auth.json：

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "ant-ling": { "type": "api_key", "key": "..." },
  "openai": { "type": "api_key", "key": "sk-..." },
  "deepseek": { "type": "api_key", "key": "sk-..." },
  "nvidia": { "type": "api_key", "key": "nvapi-..." },
  "google": { "type": "api_key", "key": "..." },
  "opencode": { "type": "api_key", "key": "..." },
  "opencode-go": { "type": "api_key", "key": "..." },
  "together": { "type": "api_key", "key": "..." },
  "qwen-token-plan":  { "type": "api_key", "key": "sk-sp-..." },
  "qwen-token-plan-individual": { "type": "api_key", "key": "sk-sp-..." },
  "qwen-token-plan-cn": { "type": "api_key", "key": "sk-sp-..." },
  "xiaomi": { "type": "api_key", "key": "..." },
  "xiaomi-token-plan-cn":  { "type": "api_key", "key": "..." },
  "xiaomi-token-plan-ams": { "type": "api_key", "key": "..." },
  "xiaomi-token-plan-sgp": { "type": "api_key", "key": "..." }
}

qwen-token-plan-individual 使用与 qwen-token-plan 相同的国际端点和 QWEN_TOKEN_PLAN_API_KEY，但会将选择器限制为个人（Individual）订阅文档所列的模型。已有提供商出于向后兼容保留了更宽的目录。使用 auth.json 时，请将凭证存储在你所选的提供商名下；环境变量则由两个国际版提供商共用。

该文件以 0600 权限创建（仅用户可读写）。认证文件中的凭证优先于环境变量。

API 密钥凭证还可以包含提供商作用域的环境值。在解析凭证密钥、提供商/模型请求头以及提供商配置（如 Cloudflare 账户 ID、Azure OpenAI 设置、Vertex 项目/位置、Bedrock 设置、PI_CACHE_RETENTION 和 HTTP_PROXY/HTTPS_PROXY）时，这些值优先于进程环境变量。

{
  "cloudflare-ai-gateway": {
    "type": "api_key",
    "key": "$CLOUDFLARE_API_KEY",
    "env": {
      "CLOUDFLARE_API_KEY": "...",
      "CLOUDFLARE_ACCOUNT_ID": "account-id",
      "CLOUDFLARE_GATEWAY_ID": "gateway-id"
    }
  }
}

当希望 pi 使用与项目 shell 环境不同的提供商设置时，可以使用这种方式。

密钥解析

key 字段支持命令执行、环境变量插值和字面量：

• Shell 命令： 以 "!command" 开头时，整个值会作为命令执行，并使用其 stdout（在进程生命周期内缓存）

  { "type": "api_key", "key": "!security find-generic-password -ws 'anthropic'" }
  { "type": "api_key", "key": "!op read 'op://vault/item/credential'" }

• 环境变量插值： "$ENV_VAR" 或 "${ENV_VAR}" 使用指定变量的值。插值也可以在更长的字面量中使用。

  { "type": "api_key", "key": "$MY_ANTHROPIC_KEY" }
  { "type": "api_key", "key": "${KEY_PREFIX}_${KEY_SUFFIX}" }

  $FOO_BAR 指向变量 FOO_BAR；如果 BAR 是字面文本，请使用 ${FOO}_BAR。环境变量缺失时该值视为未解析。
• 转义： "$$" 输出字面量 "$"；"$!" 输出字面量 "!" 而不触发命令执行。

  { "type": "api_key", "key": "$$literal-dollar-prefix" }
  { "type": "api_key", "key": "$!literal-bang-prefix" }

• 字面量： 直接使用。纯大写字符串（如 MY_API_KEY）是字面量；要引用环境变量请使用 $MY_API_KEY。

  { "type": "api_key", "key": "sk-ant-..." }
  { "type": "api_key", "key": "public" }

OAuth 凭证在 /login 之后也会存储在这里，并自动管理。

云端提供商

Azure OpenAI

export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_BASE_URL=https://your-resource.ai.azure.com
# also supported: https://your-resource.cognitiveservices.azure.com
# also supported: https://your-resource.openai.azure.com
# root endpoints are auto-normalized to /openai/v1
# or use resource name instead of base URL
export AZURE_OPENAI_RESOURCE_NAME=your-resource

# Optional
export AZURE_OPENAI_API_VERSION=2024-02-01
export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4=my-gpt4,gpt-4o=my-gpt4o

Amazon Bedrock

使用 /login amazon-bedrock 存储 Bedrock API 密钥，或配置以下任一 AWS 环境凭证来源：

# Option 1: AWS Profile
export AWS_PROFILE=your-profile

# Option 2: IAM Keys
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...

# Option 3: Bearer Token
export AWS_BEARER_TOKEN_BEDROCK=...

# Optional region (defaults to us-east-1)
export AWS_REGION=us-west-2

还支持 ECS 任务角色（AWS_CONTAINER_CREDENTIALS_*）和 IRSA（AWS_WEB_IDENTITY_TOKEN_FILE）。

pi --provider amazon-bedrock --model us.anthropic.claude-sonnet-4-20250514-v1:0

对于 ID 中包含可识别模型名称的 Claude 模型（基础模型和系统定义的推理配置文件），提示词缓存会自动启用。对于应用推理配置文件（其 ARN 不包含模型名称），请设置 AWS_BEDROCK_FORCE_CACHE=1 以启用缓存点：

export AWS_BEDROCK_FORCE_CACHE=1
pi --provider amazon-bedrock --model arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/abc123

如果你要连接 Bedrock API 代理，可以使用以下环境变量：

# Set the URL for the Bedrock proxy (standard AWS SDK env var)
export AWS_ENDPOINT_URL_BEDROCK_RUNTIME=https://my.corp.proxy/bedrock

# Set if your proxy does not require authentication
export AWS_BEDROCK_SKIP_AUTH=1

# Set if your proxy only supports HTTP/1.1
export AWS_BEDROCK_FORCE_HTTP1=1

Cloudflare AI Gateway

CLOUDFLARE_API_KEY 可以通过 /login 设置。账户 ID 和网关 slug 可以设置为环境变量，也可以放在 auth.json 中 API 密钥凭证的 env 对象里。

export CLOUDFLARE_API_KEY=...           # or use /login
export CLOUDFLARE_ACCOUNT_ID=...
export CLOUDFLARE_GATEWAY_ID=...        # create at dash.cloudflare.com → AI → AI Gateway
pi --provider cloudflare-ai-gateway --model "claude-sonnet-4-5"

通过 Cloudflare AI Gateway 路由到 OpenAI、Anthropic 和 Workers AI。Workers AI 使用 Unified API（/compat）和带前缀的模型 ID（workers-ai/@cf/...）。OpenAI 使用 OpenAI 透传路由（/openai）及原生 OpenAI 模型 ID（如 gpt-5.1）。Anthropic 使用 Anthropic 透传路由（/anthropic）及原生 Anthropic 模型 ID（如 claude-sonnet-4-5）。

AI Gateway 认证将 CLOUDFLARE_API_KEY 用作 cf-aig-authorization。上游认证可以是以下之一：

对于普通的 pi 用法，优先选择统一计费或存储式 BYOK。行内 BYOK 需要为 Cloudflare AI Gateway 提供商配置额外的上游 Authorization 请求头，例如通过 models.json 的提供商/模型覆盖来实现。

Cloudflare Workers AI

CLOUDFLARE_API_KEY 可以通过 /login 设置。CLOUDFLARE_ACCOUNT_ID 可以设置为环境变量，也可以放在 auth.json 中 API 密钥凭证的 env 对象里。

export CLOUDFLARE_API_KEY=...           # or use /login
export CLOUDFLARE_ACCOUNT_ID=...
pi --provider cloudflare-workers-ai --model "@cf/moonshotai/kimi-k2.6"

Pi 会自动设置 x-session-affinity，以享受前缀缓存折扣。

Google Vertex AI

使用应用默认凭证（Application Default Credentials）：

gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT=your-project
export GOOGLE_CLOUD_LOCATION=us-central1

或者将 GOOGLE_APPLICATION_CREDENTIALS 指向服务账号密钥文件。

llama.cpp

Pi 支持 llama.cpp 路由服务器。使用 /login llama.cpp 进行配置，用 /llama 管理已加载的模型，并用 /model 选择一个已加载的模型。

服务器搭建、模型目录布局、环境变量和命令用法参见 llama.cpp。

自定义提供商

通过 models.json： 添加 Ollama、LM Studio、vLLM，或任何使用受支持 API（OpenAI Completions、OpenAI Responses、Anthropic Messages、Google Generative AI）的提供商。参见 models.md。

通过扩展： 对于需要自定义 API 实现或 OAuth 流程的提供商，可以创建扩展。参见 custom-provider.md 和 examples/extensions/custom-provider-gitlab-duo。

解析顺序

解析某个提供商的凭证时，顺序如下：

1. CLI --api-key 标志
2. auth.json 条目（API 密钥或 OAuth 令牌）
3. 环境变量
4. 来自 models.json 的自定义提供商密钥

4 llama.cpp

Pi 支持 llama.cpp 路由服务器。路由器会发现多个 GGUF 模型，并按需加载或卸载它们。

请使用支持路由器功能的较新版本 llama.cpp。可以按照构建说明自行构建，或为你的平台安装预编译版本。

启动路由器

启动 llama-server 时不要带 --model 或 -m。如果传入模型，则会进入单模型模式而非路由器模式。

llama-server \
  --models-dir ~/models \
  --no-models-autoload \
  --jinja \
  --host 127.0.0.1 \
  --port 8080 \
  -ngl 999 \
  -c 32768

重要选项：

• --models-dir ~/models 用于发现本地 GGUF 文件。
• --no-models-autoload 让模型加载必须通过 /llama 显式进行。
• --jinja 启用兼容的聊天模板和工具调用。
• -ngl 999 将尽可能多的层卸载到 GPU。
• -c 32768 为每个已加载的模型设置上下文窗口。如果省略，则使用模型的原生上下文，这可能会显著增加内存占用。

单文件模型可以直接放在模型目录中。多模态和多分片模型请放在单独的子目录中：

~/models/
├── llama-3.2-1b-Q4_K_M.gguf
├── gemma-3-4b-it-Q4_K_M/
│   ├── gemma-3-4b-it-Q4_K_M.gguf
│   └── mmproj-F16.gguf
└── large-model-Q4_K_M/
    ├── large-model-Q4_K_M-00001-of-00003.gguf
    ├── large-model-Q4_K_M-00002-of-00003.gguf
    └── large-model-Q4_K_M-00003-of-00003.gguf

手动添加文件后请重启路由器。如需为每个模型设置上下文大小等选项，可以使用 llama.cpp 模型预设。

配置 Pi

启动 Pi 并配置提供商：

/login llama.cpp

输入路由器 URL 和可选的 API 密钥。默认 URL 为 http://127.0.0.1:8080。

如果启动路由器时使用了 --no-models-autoload，/login llama.cpp 只会保存连接信息。运行 /llama 加载模型，再运行 /model 为当前会话选择已加载的模型。

也可以通过环境变量配置相同的值，无需 /login：

export LLAMA_BASE_URL=http://127.0.0.1:8080
export LLAMA_API_KEY=optional-secret
pi

如果服务器使用了 API 密钥，请在启动 llama-server 时传入相同的 --api-key 值。保持 --host 127.0.0.1 可将访问限制在本地。

管理模型

运行：

/llama

• 选择一个未加载的模型即可加载它。
• 选择一个已加载的模型即可卸载它。
• 选择 Download model…，搜索 Hugging Face，然后选择仓库和量化版本。直接输入精确的 owner/repository[:quant] 值也可以。
• 在加载或下载过程中按 Escape 可确认取消。

Hugging Face 搜索在设置了 HF_TOKEN 时会使用它，然后依次检查 $HF_TOKEN_PATH、$HF_HOME/token、$XDG_CACHE_HOME/huggingface/token 和 ~/.cache/huggingface/token。未认证时也可以搜索，但会受到更低的速率限制。Pi 在下载受限仓库前会发出警告并链接到其访问页面。下载由 llama.cpp 服务器执行，因此当所选仓库需要访问权限时，该服务器进程也必须持有 HF_TOKEN。

如果已有其他模型处于加载状态，Pi 会询问是先卸载它们还是保持加载。Pi 不会静默卸载模型，也绝不会删除模型文件。路由器可能被其他客户端共享，因此 /llama 始终显示路由器的当前状态。

只有已加载的模型才会出现在 /model 中。加载模型后，运行 /model 为当前 Pi 会话选择它。

如果路由器连接断开，/llama 会显示 Retry 和 Close。重试会重新连接并刷新模型状态，但不会重放被中断的操作。

故障排除

检查路由器是否可达：

curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/models

• /llama 中没有模型： 检查 --models-dir 和目录布局，并重启路由器。
• /model 中缺少模型： 先用 /llama 加载它。
• 加载失败或内存占用过高： 降低 -c 或卸载其他模型。
• 服务器未处于路由器模式： 启动时不要带 --model、-m 或 -hf。

5 安全

Pi 是一个本地编码智能体。它以启动它的用户账户的权限运行，并把该用户可写的文件视为处于同一个本地信任边界之内。

项目信任

项目信任决定 pi 是否加载项目级设置、资源、包和扩展。它不是沙箱，也不会在你开始于某个目录中工作之后限制模型让工具执行的操作。

当 pi 从当前工作目录发现以下任意一项时，就会认为该项目包含需要信任的资源：

• .pi/settings.json
• .pi/extensions、.pi/skills、.pi/prompts 或 .pi/themes
• .pi/SYSTEM.md 或 .pi/APPEND_SYSTEM.md
• 当前目录或祖先目录中的项目级 .agents/skills

一个空的 .pi 目录不算作需要信任的项目资源。

当一个交互式会话在包含需要信任的资源、且当前目录或父目录没有已保存决定的项目中启动时，pi 会遵循全局设置中的 defaultProjectTrust。默认值为 "ask"，即在有可用 UI 时询问是否信任该项目。已保存的决定按规范化目录存储在 ~/.pi/agent/trust.json 中；当前路径或父路径上距离最近的已保存决定，会先于全局默认值生效。

信任一个项目后，pi 就可以加载需要信任的项目资源，包括：

• .pi/settings.json
• .pi 资源，例如扩展、技能、提示词模板、主题和系统提示词文件
• 通过项目设置配置的缺失项目包
• 项目级扩展和由项目包管理的扩展

拒绝信任则会跳过受保护的资源。AGENTS.override.md、AGENTS.md 和 CLAUDE.md 等上下文文件无论项目信任与否都会加载，除非上下文加载被禁用。在信任状态确定之前，pi 只加载上下文文件、用户/全局扩展以及 CLI -e 扩展。用户/全局扩展和 CLI 扩展可以处理 project_trust 事件；第一个返回是/否决定的扩展拥有该决定权。

非交互模式（-p、--mode json 和 --mode rpc）不会显示信任提示。在没有适用的已保存信任决定时，defaultProjectTrust: "ask" 和 "never" 会忽略这类资源，而 "always" 会信任它们。使用 --approve/-a 或 --no-approve/-na 可以为单次运行覆盖项目信任。

没有内置沙箱

Pi 不包含内置沙箱。内置工具可以读取文件、写入文件、编辑文件，并以 pi 进程自身的权限运行 shell 命令。扩展是以相同权限运行的 TypeScript 模块。包安装、shell 命令、语言服务器、测试命令和其他开发工具都表现为普通的本地进程。

这是有意为之。Pi 的设计目标是在本地源码树上操作、调用项目工具链，并与用户现有的开发环境集成。一个进程内的部分沙箱很容易被误解为安全边界，但它仍然要依赖宿主机的 shell、文件系统、包管理器、凭据和扩展代码。真正的隔离必须来自操作系统或虚拟化/容器边界。

项目信任只是一道输入加载防线。它可以防止仓库在你批准之前悄悄更改 pi 的设置或扩展。它无法让不受信任的代码、不受信任的提示词或不受信任的模型输出变得安全。来自仓库文件、注释、文档、上下文文件或构建输出的提示词注入，属于本地智能体预期之中且无法避免的风险，pi 无法可靠地防范。

运行不受信任或无人监督的工作

对于不受信任的仓库、你不打算密切监督的生成代码，或无人值守的自动化，请在受控环境中运行 pi。使用容器、虚拟机、微虚拟机、远程沙箱或受策略控制的沙箱，并且只提供任务所需的文件和凭据。

常见模式记录在容器化一章中：

• 将整个 pi 进程放入容器/沙箱中运行
• 在宿主机上运行 pi，同时把内置工具的执行路由到 Gondolin 微虚拟机
• 只挂载智能体应该访问的工作区路径
• 避免挂载宿主机的 ~/.pi/agent，除非容器需要访问宿主机的会话、设置和凭据
• 只传入必需的最少 API 密钥，或使用短期凭据
• 在任务不需要网络时限制网络访问
• 在把结果复制回受信任系统之前，先审查 diff 和输出

如果你以读写方式绑定挂载宿主机工作区，容器或虚拟机内部的写入仍然可以修改宿主机文件。当你需要更强的保护、防止意外写入时，请使用只读挂载，或者以复制文件的方式把内容移入和移出沙箱。

报告安全问题

要报告安全问题，请遵循仓库的安全策略。不要为安全敏感的报告创建公开 issue。

预期中的本地智能体行为、缺少内置沙箱、来自不受信任内容的提示词注入，以及用户安装的扩展或技能的行为，通常不在安全边界范围之内，除非报告演示了真实的权限边界绕过，或表明 pi 授予了本地用户原本并不拥有的访问权限。

6 容器化

Pi 默认以全部权限运行，但在某些情况下，你会希望更好地控制 Pi 可以写入哪些目录、拥有哪些访问权限。

总体上有两种选择：

1. 将整个 pi 进程放在隔离环境中运行，或者
2. 在宿主机上运行 pi，把工具执行路由到隔离环境中。

选择模式

扩展在 pi 进程所在的位置运行。如果你在宿主机上运行 pi 并使用工具路由扩展，其他自定义扩展工具仍会在宿主机上运行，除非它们也把自己的操作委托出去。

Gondolin

Gondolin 是一个本地 Linux 微虚拟机。 当你想让 pi 留在宿主机上、而所有内置工具都路由到虚拟机内执行时，可以使用示例扩展。

安装：

cp -R packages/coding-agent/examples/extensions/gondolin ~/.pi/agent/extensions/gondolin
cd ~/.pi/agent/extensions/gondolin
npm install --ignore-scripts

在要挂载的项目中运行：

cd /path/to/project
pi -e ~/.pi/agent/extensions/gondolin

该扩展会把宿主机当前工作目录挂载到虚拟机内的 /workspace，并接管 read、write、edit、bash、grep、find 和 ls。 用户的 ! 命令同样会被路由到虚拟机中。 /workspace 下的文件改动会直接写回宿主机。

环境要求：@earendil-works/gondolin 需要 Node.js >= 23.6.0，另外需要 QEMU（须通过你的包管理器安装）。

普通 Docker

当你想要最简单的本地容器边界时，可以把整个 pi 进程放进 Docker 中运行。

Dockerfile.pi：

FROM node:24-bookworm-slim

RUN apt-get update \
  && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
  && rm -rf /var/lib/apt/lists/*
RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent

WORKDIR /workspace
ENTRYPOINT ["pi"]

构建并运行：

docker build -t pi-sandbox -f Dockerfile.pi .

docker run --rm -it \
  -e ANTHROPIC_API_KEY \
  -v "$PWD:/workspace" \
  -v pi-agent-home:/root/.pi/agent \
  pi-sandbox

-v "$PWD:/workspace" 会把你当前所在的目录挂载到容器内的 /workspace，这样 Docker 内部对 /workspace 的读写会直接影响宿主机文件，效果与 Gondolin 示例相同。

如果希望容器内有独立的设置和会话，可以为 /root/.pi/agent 使用命名卷。挂载宿主机的 ~/.pi/agent 会把宿主机的认证和会话文件暴露给容器。

OpenShell

当你需要带有文件系统、进程、网络、凭据和推理控制的策略型沙箱时，可以使用 NVIDIA OpenShell。 OpenShell 可以通过由 Docker、Podman 或虚拟机运行时支撑的本地网关运行沙箱，也可以通过远程 Kubernetes 网关运行。

每个沙箱都需要一个活跃的网关。 在创建沙箱之前，先注册并选择一个：

openshell gateway add <gateway-url> --name <name>
openshell gateway select <name>

在 OpenShell 沙箱内启动 pi：

openshell sandbox create --name pi-sandbox --from pi -- pi

在这种模式下，整个 pi 进程都在沙箱内运行。 内置工具、! 命令和扩展工具都在 OpenShell 边界内执行。

如果网关是远程的，项目文件不会从宿主机绑定挂载，也就是说沙箱内的写入不会反映到你的机器上。 请在沙箱内克隆仓库，或使用 OpenShell 的文件传输命令：

openshell sandbox upload pi-sandbox ./repo /workspace
openshell sandbox download pi-sandbox /workspace/repo ./repo-out

OpenShell 提供商可以让原始的模型 API 密钥留在沙箱之外。 配置推理路由之后，沙箱内的代码可以调用 https://inference.local，由网关在上游注入配置好的提供商凭据。 如果你希望模型流量走这条路线，可以将 Pi 配置为使用对应的 OpenAI 兼容或 Anthropic 兼容端点。

Docker Sandboxes

Docker Sandboxes 是 Docker 提供的托管沙箱运行时，会把整个 pi 进程放进沙箱中运行。 它是没有内置沙箱所指的那种容器边界之一。

与上面的普通 Docker 模式不同，提供商凭据不会传入容器。 沙箱收到的是一个哨兵值（sentinel），由 sbx 代理在出口处向 api.anthropic.com 替换为真实凭据。 凭据在创建时接线，因此在创建沙箱之前，要先把凭据存放在宿主机上。

对于 Claude Pro/Max 订阅，先在一台装有 Claude Code 的机器上运行 claude setup-token，然后把结果存储到宿主机上。 如果已经绑定了 anthropic secret，请先移除它：否则代理会在 Bearer token 之外再附加一个 x-api-key 头，Anthropic 会拒绝该请求。 sbx secret set-custom 从 stdin 读取 token，因此不会留在 shell 历史记录中。

sbx secret rm anthropic

sbx secret set-custom \
  --host api.anthropic.com \
  --env ANTHROPIC_OAUTH_TOKEN \
  --placeholder 'sk-ant-oat01-{rand}'

沙箱拿到的是 OAuth 形式的占位符而非真实 token，由代理在出口到该主机时替换；ANTHROPIC_OAUTH_TOKEN 是 pi 本身就会读取并优先于 API 密钥使用的变量，因此无需额外的 pi 配置。

如果是 API 密钥，则改用 sbx secret set anthropic 存储。该套件（kit）以相同的方式接线：作为一个由代理在出口处替换的哨兵值。

凭据存放好之后，在要挂载的项目中启动 pi：

sbx run --kit "docker.io/sbx/pi-kit:latest" pi

该套件已把 pi 预置到镜像中，因此沙箱启动时无需安装任何东西，当前目录就是沙箱工作区。

不要在沙箱内认证：在里面运行 /login 会把真实 token 写入容器，破坏代理模型。

脚本化使用的方式相同：

sbx exec <sandbox-name> -- pi -p "list the failing tests"

完整的凭据矩阵、故障排除和版本固定，请参阅套件文档。

7 设置

Pi 使用 JSON 设置文件，项目设置会覆盖全局设置。

可以直接编辑，也可以使用 /settings 调整常用选项。要以交互方式保存启动时的默认模型，请使用 /model 并在所需模型上按 Ctrl+S。要保存启动时的思考级别，请使用 /thinking 并按 Ctrl+S。

项目信任

在交互式启动时，如果项目文件夹包含项目本地设置、资源或项目级 .agents/skills，且在 ~/.pi/agent/trust.json 中没有针对该文件夹或其父文件夹的已保存决定，pi 会先询问是否信任该项目。信任项目后，pi 才能加载 .pi/settings.json 和 .pi 资源、安装缺失的项目包，并执行项目扩展。

非交互模式（-p、--mode json 和 --mode rpc）不显示信任提示。在没有适用的已保存信任决定时，它们使用全局设置中的 defaultProjectTrust：ask（默认）和 never 会忽略这些项目资源，而 always 则信任它们。传入 --approve/-a 或 --no-approve/-na 可为单次运行覆盖项目信任。

如果没有扩展或已保存决定适用，则由 defaultProjectTrust 控制回退行为。在 ~/.pi/agent/settings.json 中将其设为 "ask"、"always" 或 "never"，或通过 /settings 修改。

pi config 和包管理命令使用相同的项目信任流程，但 pi update 从不弹出提示。传入 --approve 可为单条命令信任项目本地设置，传入 --no-approve 则忽略它们。

在交互模式下使用 /trust 可以为未来会话保存项目信任决定，包括对直接父文件夹的信任。它只写入 ~/.pi/agent/trust.json；当前会话不会重新加载，因此需重启 pi 才能生效。

全部设置

模型与思考

thinkingBudgets

{
  "thinkingBudgets": {
    "minimal": 1024,
    "low": 4096,
    "medium": 10240,
    "high": 32768
  }
}

UI 与显示

对于 VS Code，请加上 --wait，这样编辑器退出后 pi 会继续运行：

{
  "externalEditor": "code --wait"
}

遥测与更新检查

enableInstallTelemetry 控制发送到 https://pi.dev/api/report-install 的匿名安装/更新 ping，以及 OpenRouter、NVIDIA NIM 和 Cloudflare 提供商请求中的 Pi 归因请求头。关闭后会同时禁用两者。它不会禁用更新检查；Pi 仍可能获取 https://pi.dev/api/latest-version 以查询最新版本。

设置 PI_SKIP_VERSION_CHECK=1 可禁用 Pi 版本更新检查。使用 --offline 或 PI_OFFLINE=1 可禁用本文所述的所有启动网络操作，包括更新检查、包更新检查和安装/更新遥测。

网络

{
  "httpProxy": "http://127.0.0.1:7890"
}

警告

{
  "warnings": {
    "anthropicExtraUsage": false
  }
}

上下文压缩

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}

每模型压缩覆盖

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000,
    "modelOverrides": {
      "some-provider/big-model": {
        "reserveTokens": 400000
      },
      "local/small-model": {
        "reserveTokens": 2048,
        "keepRecentTokens": 4096
      }
    }
  }
}

键必须精确匹配区分大小写的 provider/modelId 值，而不是名称或 glob 模式。模型 ID 可能包含斜杠（例如 openrouter/anthropic/claude-sonnet-4）。

每个 token 设置独立解析：匹配的模型覆盖 → 普通 compaction 设置 → 内置默认值。在上面的例子中，some-provider/big-model 仍保留普通的 20000 近期 token。token 值必须是非负的安全整数。匹配的模型覆盖中存在无效值时会在读取时报错；只有省略的字段才会回退到普通设置。模型覆盖条目必须是对象。普通 token 设置存在无效值时同样会在读取时报错，即使当前模型有有效的覆盖。只有省略的普通值才使用内置默认值。零是允许的，但 reserveTokens: 0 会失去回复余量，并将摘要输出预算也设为零。

全局和项目设置在模型查找之前递归合并。项目可以只覆盖某个模型的某一个字段，而不替换它的其他字段或其他模型。全局的模型专属值优先于项目范围的回退值；要更改它，需在项目中覆盖同一模型条目。

enabled 不区分模型。当前模型的 token 设置适用于手动压缩、自动阈值检查（包括助手回合之间）以及溢出恢复。切换模型会在下一次检查或压缩时生效。覆盖请在 JSON 中配置；/settings 只保留普通的自动压缩开关。

触发和摘要行为参见 compaction.md。

分支摘要

重试

智能体级重试使用以 retry.maxAgentDelayMs 为上限的指数退避，因此即使长时间故障，较长的重试过程也能保持响应。

当提供商请求的重试延迟超过 retry.provider.maxRetryDelayMs 时，请求会立即失败并给出有说明的错误，而不是静默等待。将其设为 0 可禁用该限制。

除非确实需要提供商级重试，否则请将 retry.provider.maxRetries 保持为 0。将其设为大于 0 可能让 SDK/提供商重试在 Pi 察觉之前处理超出用量限额的错误，某些情况下这会阻塞智能体，直到提供商配额重置。

{
  "retry": {
    "enabled": true,
    "maxRetries": 3,
    "baseDelayMs": 2000,
    "maxAgentDelayMs": 60000,
    "provider": {
      "timeoutMs": 3600000,
      "maxRetries": 0,
      "maxRetryDelayMs": 60000
    }
  }
}

消息送达

终端与图片

Shell

JSON 中的 Windows 路径必须使用正斜杠或转义的反斜杠：

{
  "shellPath": "C:/Program Files/Git/bin/bash.exe"
}

{
  "shellPath": "C:\\Program Files\\Git\\bin\\bash.exe"
}

{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}

npmCommand 用于所有 npm 包管理器操作，包括安装、卸载以及 git 包内部的依赖安装。用户范围的 npm 包安装在 ~/.pi/agent/npm/ 下；项目范围的 npm 包安装在 .pi/npm/ 下。请按进程的实际启动方式使用 argv 形式的条目。配置了 npmCommand 后，git 包的依赖安装会使用纯 install，以避免包装器或替代包管理器中的 npm 专属标志。

工具

defaultTools 选择启动时启用的内置工具。扩展和 SDK 自定义工具仍然保持启用。可用的内置工具有 read、bash、powershell、edit、write、grep、find 和 ls：

{
  "defaultTools": ["bash", "edit", "write"]
}

在 Windows 上，请选择 powershell 而不是 bash，或者两者都包含：

{
  "defaultTools": ["read", "powershell", "edit", "write"]
}

空数组表示启动时不启用任何内置工具，同时保留扩展和 SDK 自定义工具。--tools 会以针对所有工具的严格白名单取代这一行为，--no-tools 禁用所有工具，--no-builtin-tools 禁用内置默认工具。--exclude-tools 会在结果列表上再做过滤。项目的 defaultTools 数组会替换全局数组。

会话

{ "sessionDir": ".pi/sessions" }

当多个来源指定会话目录时，优先级依次为 --session-dir、PI_CODING_AGENT_SESSION_DIR、settings.json 中的 sessionDir。

模型循环

{
  "enabledModels": ["claude-*", "gpt-4o", "gemini-2*"]
}

Markdown

资源

这些设置定义从哪里加载扩展、技能、提示词和主题。

~/.pi/agent/settings.json 中的路径相对于 ~/.pi/agent 解析。.pi/settings.json 中的路径相对于 .pi 解析。支持绝对路径和 ~。

数组支持 glob 模式和排除项。使用 !pattern 排除。使用 +path 强制包含某个精确路径，使用 -path 强制排除某个精确路径。

packages

字符串形式会加载包中的所有资源：

{
  "packages": ["pi-skills", "@org/my-extension"]
}

对象形式可以过滤要加载的资源：

{
  "packages": [
    {
      "source": "pi-skills",
      "skills": ["brave-search", "transcribe"],
      "extensions": []
    }
  ]
}

包管理详情参见 packages.md。

示例

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "modelThinkingLevels": {
    "anthropic/claude-sonnet-4-20250514": "high"
  },
  "theme": "dark",
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "retry": {
    "enabled": true,
    "maxRetries": 3
  },
  "enabledModels": ["claude-*", "gpt-4o"],
  "warnings": {
    "anthropicExtraUsage": true
  },
  "packages": ["pi-skills"]
}

项目覆盖

项目设置（.pi/settings.json）会覆盖全局设置。嵌套对象会被合并：

// ~/.pi/agent/settings.json (global)
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 16384 }
}

// .pi/settings.json (project)
{
  "compaction": { "reserveTokens": 8192 }
}

// Result
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 8192 }
}

8 快捷键

所有键盘快捷键都可以通过 ~/.pi/agent/keybindings.json 自定义。每个动作可以绑定一个或多个按键。

该配置文件使用与 pi 内部以及扩展作者在 keyHint() 和注入的 keybindings 管理器中相同的带命名空间快捷键 ID。

使用 cursorUp 或 expandTools 等旧版无命名空间 ID 的配置会在启动时自动迁移为带命名空间的 ID。

编辑 keybindings.json 后，在 pi 中运行 /reload 即可应用更改，无需重启会话。

按键格式

格式为 modifier+key，其中修饰键为 ctrl、shift、alt、super（可组合），按键包括：

• 字母： a-z
• 数字： 0-9
• 特殊键： escape、esc、enter、return、tab、space、backspace、delete、insert、clear、home、end、pageUp、pageDown、up、down、left、right
• 功能键： f1-f12
• 符号： `、-、=、[、]、\、;、'、,、.、/、!、@、#、$、%、^、&、*、(、)、_、+、|、~、{、}、:、<、>、?

修饰键组合：ctrl+shift+x、alt+ctrl+x、ctrl+shift+alt+x、super+k、ctrl+super+k、ctrl+1 等。

super 绑定要求终端能够单独上报该修饰键，通常需要 Kitty 键盘协议。在不支持的终端中可能无法工作。

全部动作

TUI 编辑器光标移动

专用的历史动作始终切换历史条目，与多行提示词中的光标位置无关。当主编辑器获得焦点时，显式的历史绑定优先于应用动作，因此将 tui.editor.historyPrevious 绑定到 ctrl+p 只会在该上下文中覆盖模型循环切换，而不会改变选择器中的 Ctrl+P。

TUI 编辑器删除

TUI 输入

TUI 剪切环

TUI 剪贴板与选择

TUI 全屏视口

这些动作在交互模式使用 --tui-mode fullscreen 时生效，作用于主对话记录滚动区域。双指触控板和鼠标滚轮输入会滚动指针所在区域；当指针位于固定的编辑器/状态栏/底部栏停靠区上时，则回退为滚动对话记录。点击 OSC 8 超链接会用默认处理器打开它。按住主鼠标键拖动会选择文本并复制到剪贴板；在对话记录的上、下边缘按住不动时会自动滚动到屏幕外的内容。对话记录向上滚动时，其底部行会显示可点击的 “Jump to latest message” 标签，展示 tui.altScreen.bottom 快捷键。各终端专属的鼠标与触控行为参见终端设置。

全屏对话记录绑定优先于编辑器绑定。因此在全屏模式下，默认的无修饰导航键控制对话记录，而它们的 ctrl 变体继续控制编辑器。在非全屏模式下，两种变体都控制编辑器。

对话记录搜索面板会显示已配置的上一个/下一个快捷键以及可点击的箭头控件。再次按下 tui.altScreen.search，或使用 tui.altScreen.searchClose，即可关闭它。

这一路由仍可通过常规的动作绑定进行配置。例如，"tui.altScreen.pageUp": "ctrl+pageUp" 会让全屏模式下的 pageUp 控制编辑器、ctrl+pageUp 控制对话记录。绑定 tui.altScreen.halfPageUp 和 tui.altScreen.halfPageDown 可以按半页步进，绑定 tui.altScreen.lineUp 和 tui.altScreen.lineDown 可以按单行步进。设置 "tui.altScreen.pageUp": [] 会完全禁用该对话记录快捷键。用户绑定会替换该动作的默认值。

应用

会话

模型与思考

显示与消息队列

树状导航

作用域模型选择器

用于作用域模型选择器内部（通过 /scoped-models 打开）。

自定义配置

创建 ~/.pi/agent/keybindings.json：

{
  "tui.editor.historyPrevious": "ctrl+p",
  "tui.editor.historyNext": "ctrl+n",
  "tui.editor.deleteWordBackward": ["ctrl+w", "alt+backspace"]
}

每个动作可以绑定单个按键或一个按键数组。用户配置会覆盖默认值。

在原生 Windows 上，app.suspend 没有默认绑定，因为 Windows 终端不支持 Unix 作业控制。如果你手动绑定它，pi 会显示一条状态消息而不是挂起进程。在 WSL 中，正常的 Linux ctrl+z/fg 行为仍然适用。

Emacs 示例

{
  "tui.editor.historyPrevious": "ctrl+p",
  "tui.editor.historyNext": "ctrl+n",
  "tui.editor.cursorLeft": ["left", "ctrl+b"],
  "tui.editor.cursorRight": ["right", "ctrl+f"],
  "tui.editor.cursorWordLeft": ["alt+left", "alt+b"],
  "tui.editor.cursorWordRight": ["alt+right", "alt+f"],
  "tui.editor.deleteCharForward": ["delete", "ctrl+d"],
  "tui.editor.deleteCharBackward": ["backspace", "ctrl+h"],
  "tui.input.newLine": ["shift+enter", "ctrl+j"]
}

Vim 示例

{
  "tui.editor.cursorUp": ["up", "alt+k"],
  "tui.editor.cursorDown": ["down", "alt+j"],
  "tui.editor.cursorLeft": ["left", "alt+h"],
  "tui.editor.cursorRight": ["right", "alt+l"],
  "tui.editor.cursorWordLeft": ["alt+left", "alt+b"],
  "tui.editor.cursorWordRight": ["alt+right", "alt+w"]
}

9 会话

Pi 会把对话保存为会话，让你可以继续之前的工作、从更早的回合分叉，或者回顾之前走过的路径。

会话存储

会话自动保存到 ~/.pi/agent/sessions/，按工作目录组织。每个会话都是一个具有树状结构的 JSONL 文件。

pi -c                  # Continue most recent session
pi -r                  # Browse and select from past sessions
pi --no-session        # Ephemeral mode; do not save
pi --name "my task"    # Set session display name at startup
pi --session <path|id> # Use a specific session file or partial session ID
pi --fork <path|id>    # Fork a session file or partial session ID into a new session

在交互模式下使用 /session 可以查看当前会话文件、会话 ID、消息数、token 数和费用。

关于 JSONL 文件格式和 SessionManager API，请参阅会话格式。

会话命令

恢复和删除会话

/resume 会打开当前项目的交互式会话选择器。pi -r 则在启动时打开同一个选择器。

在选择器中你可以：

• 输入内容进行搜索
• 用 Ctrl+P 切换路径显示
• 用 Ctrl+S 切换排序方式
• 用 Ctrl+N 只显示命名会话
• 用 Ctrl+R 重命名
• 用 Ctrl+D 删除，然后确认

可用时，pi 会使用 trash CLI 执行删除，而不是永久移除文件。

命名会话

使用 /name <name> 设置人类可读的会话名称：

/name Refactor auth module

也可以在启动时用 --name 或 -n 设置名称：

pi --name "Refactor auth module"
pi --name "CI audit" -p "Review this build failure"

命名会话在 /resume 和 pi -r 中更容易找到。

使用 /tree 进行分支

会话以树的形式存储。每个条目都有 id 和 parentId，当前位置就是活动叶子。/tree 让你跳到之前的任意节点并从那里继续，而不必创建新文件。

示例结构：

├─ user: "Hello, can you help..."
│  └─ assistant: "Of course! I can..."
│     ├─ user: "Let's try approach A..."
│     │  └─ assistant: "For approach A..."
│     │     └─ user: "That worked..."  ← active
│     └─ user: "Actually, approach B..."
│        └─ assistant: "For approach B..."

树状视图操作

过滤模式包括：default、no-tools、user-only、labeled-only 和 all。可在设置中通过 treeFilterMode 配置默认值。

选择行为

选中一条用户消息或自定义消息时：

1. 把叶子移动到所选消息的父节点。
2. 把所选消息的文本放入编辑器。
3. 让你编辑并重新提交，从而创建一个新分支。

选中助手、工具、压缩或其他非用户条目时：

1. 把叶子移动到该条目。
2. 编辑器保持为空。
3. 让你从该位置继续。

选中根用户消息会把叶子重置为空对话，并把原始提示词放入编辑器。

/tree、/fork 与 /clone

当你想把不同方案保留在同一个会话中时，使用 /tree。当你想要一个独立的会话文件时，使用 /fork 或 /clone。

分支摘要

当 /tree 从一个分支切换到另一个分支时，pi 可以对被放弃的分支生成摘要，并把该摘要附加到新位置。这样既保留了你所离开路径上的重要上下文，又不必重放整个分支。

出现提示时，从以下选项中选择：

1. 不生成摘要
2. 使用默认提示词生成摘要
3. 使用自定义侧重点指令生成摘要

关于分支汇总的内部机制和扩展钩子，请参阅上下文压缩。

会话格式

会话文件为 JSONL 格式，包含消息条目、模型变更、思考级别变更、标签、压缩记录、分支摘要和扩展条目。

关于解析器、扩展、SDK 用法和完整的 SessionManager API，请参阅会话格式。

10 上下文压缩与分支摘要

LLM 的上下文窗口是有限的。当对话变得过长时，Pi 会使用上下文压缩来总结较早的内容，同时保留近期的工作。本页面同时介绍自动压缩和分支摘要。

源码文件（pi）：

• packages/coding-agent/src/core/compaction/compaction.ts - 自动压缩逻辑
• packages/coding-agent/src/core/compaction/branch-summarization.ts - 分支摘要
• packages/coding-agent/src/core/compaction/utils.ts - 共享工具（文件跟踪、序列化）
• packages/coding-agent/src/core/session-manager.ts - 条目类型（CompactionEntry、BranchSummaryEntry）
• packages/coding-agent/src/core/extensions/types.ts - 扩展事件类型

如需项目中的 TypeScript 定义，请查看 node_modules/@earendil-works/pi-coding-agent/dist/。

概述

Pi 有两种摘要机制：

两者使用相同的结构化摘要格式，并累积跟踪文件操作。压缩和分支摘要请求使用全新的路由会话 ID，并且在提供商支持的情况下禁用提示词缓存写入，因为这些一次性提示词不太可能被复用。

上下文压缩

触发时机

自动压缩在以下条件满足时触发：

contextTokens > contextWindow - reserveTokens

默认情况下，reserveTokens 为 16384 token（可在 ~/.pi/agent/settings.json 或 <project-dir>/.pi/settings.json 中配置）。这为 LLM 的回复留出空间。

在多回合的智能体运行过程中，Pi 会在工具完成且结果被追加之后、开始下一条助手回复之前检查该阈值。如果超过阈值，Pi 会在同一次智能体运行内完成压缩，并带着摘要和保留的消息继续。当已完成的工具批次结束了本次运行、且没有排队消息需要再次回复时，Pi 会跳过这次回合间检查。Pi 还会在新的用户提示词之前以及底层智能体运行结束后检查该阈值。

也可以使用 /compact [instructions] 手动触发，可选的指令用于聚焦摘要内容。

工作原理

1. 确定切割点：从最新消息向前回溯，累积 token 估算值，直到达到 keepRecentTokens（默认 20k，可在 ~/.pi/agent/settings.json 或 <project-dir>/.pi/settings.json 中配置）
2. 提取消息：收集从上一次保留边界（或会话起点）到切割点之间的消息
3. 生成摘要：调用 LLM 以结构化格式进行总结，存在前一份摘要时将其作为迭代上下文传入
4. 追加条目：保存包含摘要和 firstKeptEntryId 的 CompactionEntry
5. 重建上下文：会话为下一次请求重建上下文，使用摘要 + 从 firstKeptEntryId 起的消息

Before compaction:

  entry:  0     1     2     3      4     5     6      7      8     9
        ┌─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┬─────┐
        │ hdr │ usr │ ass │ tool │ usr │ ass │ tool │ tool │ ass │ tool│
        └─────┴─────┴─────┴──────┴─────┴─────┴──────┴──────┴─────┴─────┘
                └────────┬───────┘ └──────────────┬──────────────┘
               messagesToSummarize            kept messages
                                   ↑
                          firstKeptEntryId (entry 4)

After compaction (new entry appended):

  entry:  0     1     2     3      4     5     6      7      8     9     10
        ┌─────┬─────┬─────┬──────┬─────┬─────┬──────┬──────┬─────┬─────┬─────┐
        │ hdr │ usr │ ass │ tool │ usr │ ass │ tool │ tool │ ass │ tool│ cmp │
        └─────┴─────┴─────┴──────┴─────┴─────┴──────┴──────┴─────┴─────┴─────┘
               └──────────┬──────┘ └──────────────────────┬───────────────────┘
                 not sent to LLM                    sent to LLM
                                                         ↑
                                              starts from firstKeptEntryId

What the LLM sees:

  ┌────────┬─────────┬─────┬─────┬──────┬──────┬─────┬──────┐
  │ system │ summary │ usr │ ass │ tool │ tool │ ass │ tool │
  └────────┴─────────┴─────┴─────┴──────┴──────┴─────┴──────┘
       ↑         ↑      └─────────────────┬────────────────┘
    prompt   from cmp          messages from firstKeptEntryId

在多次压缩中，被摘要的范围从上一次压缩的保留边界（firstKeptEntryId）开始，而不是从压缩条目本身开始；如果该保留条目在路径中找不到，则回退到上一次压缩之后的那条条目。这样，在上一次压缩中幸存的消息也会被纳入下一次摘要过程，从而得到保留。Pi 还会在写入新的 CompactionEntry 之前，根据重建后的会话上下文重新计算 tokensBefore，使 token 计数反映被替换的实际压缩前上下文。

拆分回合

“回合"从一条用户消息开始，包含直到下一条用户消息之前的所有助手回复和工具调用。通常，压缩在回合边界处切割。

当单个回合超过 keepRecentTokens 时，切割点会落在回合中间的某条助手消息上。这就是"拆分回合”：

Split turn (one huge turn exceeds budget):

  entry:  0     1     2      3     4      5      6     7      8
        ┌─────┬─────┬─────┬──────┬─────┬──────┬──────┬─────┬──────┐
        │ hdr │ usr │ ass │ tool │ ass │ tool │ tool │ ass │ tool │
        └─────┴─────┴─────┴──────┴─────┴──────┴──────┴─────┴──────┘
                ↑                                     ↑
         turnStartIndex = 1                  firstKeptEntryId = 7
                │                                     │
                └──── turnPrefixMessages (1-6) ───────┘
                                                      └── kept (7-8)

  isSplitTurn = true
  messagesToSummarize = []  (no complete turns before)
  turnPrefixMessages = [usr, ass, tool, ass, tool, tool]

对于拆分回合，Pi 会生成两份摘要并合并它们：

1. 历史摘要：之前的上下文（如果有）
2. 回合前缀摘要：拆分回合的前半部分

切割点规则

有效的切割点是：

• 用户消息
• 助手消息
• BashExecution 消息
• 自定义消息（custom_message、branch_summary）

绝不在工具结果处切割（它们必须与对应的工具调用待在一起）。

CompactionEntry 结构

定义于 session-manager.ts：

interface CompactionEntry<T = unknown> {
  type: "compaction";
  id: string;
  parentId: string;
  timestamp: number;
  summary: string;
  firstKeptEntryId: string;
  tokensBefore: number;
  usage?: Usage;       // LLM usage that generated the summary
  fromHook?: boolean;  // true if provided by extension (legacy field name)
  details?: T;         // implementation-specific data
}

// Default compaction uses this for details (from compaction.ts):
interface CompactionDetails {
  readFiles: string[];
  modifiedFiles: string[];
}

扩展可以在 details 中存储任何可 JSON 序列化的数据。默认压缩会跟踪文件操作，但自定义的扩展实现可以使用自己的结构。生成和扩展提供的摘要会在可用时存储其 LLM usage，使会话总计包含摘要工作。

实现参见 prepareCompaction() 和 compact()。如需直接以编程方式生成摘要，generateSummary() 返回摘要文本，generateSummaryWithUsage() 返回 { text, usage }。

分支摘要

触发时机

当你使用 /tree 导航到另一个分支时，Pi 会提议对你正在离开的工作进行摘要。这会把被离开分支的上下文注入新分支。

工作原理

1. 寻找共同祖先：旧位置与新位置共享的最深节点
2. 收集条目：从旧叶子回溯到共同祖先
3. 在预算内准备：包含不超过 token 预算的消息（优先最新）
4. 生成摘要：以结构化格式调用 LLM
5. 追加条目：在导航位置保存 BranchSummaryEntry

Tree before navigation:

         ┌─ B ─ C ─ D (old leaf, being abandoned)
    A ───┤
         └─ E ─ F (target)

Common ancestor: A
Entries to summarize: B, C, D

After navigation with summary:

         ┌─ B ─ C ─ D
    A ───┤
         └─ E ─ F ─ [summary of B,C,D] (new leaf)

累积文件跟踪

压缩和分支摘要都会累积跟踪文件。生成摘要时，pi 会从以下来源提取文件操作：

• 正在被摘要的消息中的工具调用
• 之前的压缩或分支摘要 details（如果有）

这意味着文件跟踪会在多次压缩或嵌套的分支摘要之间累积，保留已读取和已修改文件的完整历史。

BranchSummaryEntry 结构

定义于 session-manager.ts：

interface BranchSummaryEntry<T = unknown> {
  type: "branch_summary";
  id: string;
  parentId: string;
  timestamp: number;
  summary: string;
  fromId: string;      // Entry we navigated from
  usage?: Usage;       // LLM usage that generated the summary
  fromHook?: boolean;  // true if provided by extension (legacy field name)
  details?: T;         // implementation-specific data
}

// Default branch summarization uses this for details (from branch-summarization.ts):
interface BranchSummaryDetails {
  readFiles: string[];
  modifiedFiles: string[];
}

与压缩相同，扩展可以在 details 中存储自定义数据。

实现参见 collectEntriesForBranchSummary()、prepareBranchEntries() 和 generateBranchSummary()。

摘要格式

压缩和分支摘要使用相同的结构化格式：

## Goal
[What the user is trying to accomplish]

## Constraints & Preferences
- [Requirements mentioned by user]

## Progress
### Done
- [x] [Completed tasks]

### In Progress
- [ ] [Current work]

### Blocked
- [Issues, if any]

## Key Decisions
- **[Decision]**: [Rationale]

## Next Steps
1. [What should happen next]

## Critical Context
- [Data needed to continue]

<read-files>
path/to/file1.ts
path/to/file2.ts
</read-files>

<modified-files>
path/to/changed.ts
</modified-files>

消息序列化

在摘要之前，消息会通过 serializeConversation() 序列化为文本：

[User]: What they said
[Assistant thinking]: Internal reasoning
[Assistant]: Response text
[Assistant tool calls]: read(path="foo.ts"); edit(path="bar.ts", ...)
[Tool result]: Output from tool

这样可以避免模型将其视为需要继续的对话。

序列化时，工具结果会被截断到 2000 个字符。超出该限制的内容会替换为一个标记，指明被截断的字符数。这样可以让摘要请求保持在合理的 token 预算内，因为工具结果（尤其是来自 read 和 bash 的）通常是上下文大小的最大来源。

通过扩展自定义摘要

扩展可以拦截并自定义压缩和分支摘要。事件类型定义参见 extensions/types.ts。

session_before_compact

在自动压缩或 /compact 之前触发。可以取消操作或提供自定义摘要。参见类型文件中的 SessionBeforeCompactEvent 和 CompactionPreparation。

pi.on("session_before_compact", async (event, ctx) => {
  const { preparation, branchEntries, customInstructions, reason, willRetry, signal } = event;

  // preparation.messagesToSummarize - messages to summarize
  // preparation.turnPrefixMessages - split turn prefix (if isSplitTurn)
  // preparation.previousSummary - previous compaction summary
  // preparation.fileOps - extracted file operations
  // preparation.tokensBefore - context tokens before compaction
  // preparation.firstKeptEntryId - where kept messages start
  // preparation.settings - effective settings after applying model overrides

  // branchEntries - all entries on current branch (for custom state)
  // reason - "manual" (/compact), "threshold", or "overflow"
  // willRetry - whether the aborted turn is retried after compaction (overflow recovery)
  // signal - AbortSignal (pass to LLM calls)

  // Cancel:
  return { cancel: true };

  // Custom summary:
  return {
    compaction: {
      summary: "Your summary...",
      firstKeptEntryId: preparation.firstKeptEntryId,
      tokensBefore: preparation.tokensBefore,
      // usage: summaryResponse.usage, // Optional; included in session totals
      details: { /* custom data */ },
    }
  };
});

将消息转换为文本

要用你自己的模型生成摘要，请使用 serializeConversation 将消息转换为文本：

import { convertToLlm, serializeConversation } from "@earendil-works/pi-coding-agent";

pi.on("session_before_compact", async (event, ctx) => {
  const { preparation } = event;
  
  // Convert AgentMessage[] to Message[], then serialize to text
  const conversationText = serializeConversation(
    convertToLlm(preparation.messagesToSummarize)
  );
  // Returns:
  // [User]: message text
  // [Assistant thinking]: thinking content
  // [Assistant]: response text
  // [Assistant tool calls]: read(path="..."); bash(command="...")
  // [Tool result]: output text

  // Now send to your model for summarization
  const { summary, usage } = await myModel.summarize(conversationText);
  
  return {
    compaction: {
      summary,
      firstKeptEntryId: preparation.firstKeptEntryId,
      tokensBefore: preparation.tokensBefore,
      usage,
    }
  };
});

使用不同模型的完整示例参见 custom-compaction.ts。

session_compact_failed

在手动或自动压缩失败或中止时触发。对于需要将 session_before_compact 尝试与最终结果配对的遥测扩展来说非常有用。

pi.on("session_compact_failed", async (event, ctx) => {
  const { reason, errorMessage, aborted, willRetry, fromExtension } = event;
  // reason - "manual" (/compact), "threshold", or "overflow"
  // errorMessage - present for non-abort failures
  // aborted - true for cancelled/aborted compactions
  // willRetry - whether the aborted turn would have retried after compaction
  // fromExtension - whether extension-provided compaction content was being used
});

session_before_tree

在 /tree 导航之前触发。无论用户是否选择摘要都会触发。可以取消导航或提供自定义摘要。

pi.on("session_before_tree", async (event, ctx) => {
  const { preparation, signal } = event;

  // preparation.targetId - where we're navigating to
  // preparation.oldLeafId - current position (being abandoned)
  // preparation.commonAncestorId - shared ancestor
  // preparation.entriesToSummarize - entries that would be summarized
  // preparation.userWantsSummary - whether user chose to summarize

  // Cancel navigation entirely:
  return { cancel: true };

  // Provide custom summary (only used if userWantsSummary is true):
  if (preparation.userWantsSummary) {
    return {
      summary: {
        summary: "Your summary...",
        // usage: summaryResponse.usage, // Optional; included in session totals
        details: { /* custom data */ },
      }
    };
  }
});

参见类型文件中的 SessionBeforeTreeEvent 和 TreePreparation。

设置

在 ~/.pi/agent/settings.json 或 <project-dir>/.pi/settings.json 中配置压缩：

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}

使用 "enabled": false 禁用自动压缩。你仍可以使用 /compact 手动压缩。

每模型覆盖

使用 compaction.modelOverrides 为不同模型调整 token 预算：

{
  "compaction": {
    "reserveTokens": 16384,
    "keepRecentTokens": 20000,
    "modelOverrides": {
      "some-provider/big-model": {
        "reserveTokens": 400000
      }
    }
  }
}

对于上下文窗口为 1M 的模型，这个覆盖会在超过 600K token 时触发压缩，并保留普通的 20000 近期 token。其他模型仍使用普通的 16384 token 保留量。reserveTokens 还会影响摘要输出上限（以模型的最大输出 token 为上限）；它并不只是一个触发阈值。

键必须是精确、区分大小写的 provider/modelId 值，包括模型 ID 中的任何斜杠。每个 reserveTokens 和 keepRecentTokens 值都独立回退：从模型覆盖到普通设置，再到内置默认值。值必须是非负的安全整数。匹配的模型覆盖中存在无效值时会在读取时报错；只有省略的字段才回退到普通设置。模型覆盖条目必须是对象。普通 token 设置存在无效值时同样会在读取时报错，即使当前模型有有效的覆盖。只有省略的普通值才使用内置默认值。enabled 始终是全局的，不区分模型。

这些解析后的值用于手动压缩、所有自动阈值检查、溢出恢复，以及扩展可见的 preparation.settings。切换模型会影响后续的检查和压缩，但不会更改普通设置。已在进行中的压缩使用为该操作捕获的模型和设置。分支摘要设置不受影响。

覆盖在全局和项目设置中都可以使用。两个文件在查找之前递归合并，因此全局的模型专属值优先于项目范围的回退值；项目必须覆盖该模型条目才能更改它。详情参见 settings.md。

11 扩展

pi 自己也能创建扩展。可以让它为你的使用场景构建一个。

扩展是用于扩展 pi 行为的 TypeScript 模块。它们可以订阅生命周期事件、注册可由 LLM 调用的自定义工具、添加命令等。

/reload 的存放位置： 若要被自动发现，请将扩展放在 ~/.pi/agent/extensions/（全局）或 .pi/extensions/（项目本地）。pi -e ./path.ts 仅用于快速测试。位于自动发现位置的扩展可以通过 /reload 热重载。

核心能力：

• 自定义工具 - 通过 pi.registerTool() 注册可由 LLM 调用的工具
• 事件拦截 - 阻止或修改工具调用、注入上下文、自定义上下文压缩
• 用户交互 - 通过 ctx.ui 提示用户（select、confirm、input、notify）
• 自定义 UI 组件 - 通过 ctx.ui.custom() 使用带键盘输入的完整 TUI 组件，应对复杂交互
• 自定义命令 - 通过 pi.registerCommand() 注册 /mycommand 之类的命令
• 会话持久化 - 通过 pi.appendEntry() 存储可在重启后保留的状态
• 自定义渲染 - 控制工具调用/结果和消息在 TUI 中的呈现方式

典型用例：

• 权限门禁（在 rm -rf、sudo 等操作前确认）
• Git 检查点（每轮 stash，在分支上恢复）
• 路径保护（阻止写入 .env、node_modules/）
• 自定义上下文压缩（按你的方式总结对话）
• 对话摘要（参见 summarize.ts 示例）
• 交互式工具（提问、向导、自定义对话框）
• 有状态工具（待办列表、连接池）
• 外部集成（文件监视器、webhook、CI 触发器）
• 等待期间的小游戏（参见 snake.ts 示例）

可运行的实现参见 examples/extensions/。

目录

• 快速开始
• 扩展位置
• 可用的导入
• 编写扩展
  • 扩展形式
• 事件
  • 生命周期概览
  • 资源事件
  • 会话事件
  • 智能体事件
  • 模型事件
  • 工具事件
• ExtensionContext
• ExtensionCommandContext
• ExtensionAPI 方法
• 状态管理
• 自定义工具
  • 动态工具加载
• 自定义 UI
• 错误处理
• 模式行为
• 示例参考

快速开始

创建 ~/.pi/agent/extensions/my-extension.ts：

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

export default function (pi: ExtensionAPI) {
  // React to events
  pi.on("session_start", async (_event, ctx) => {
    ctx.ui.notify("Extension loaded!", "info");
  });

  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
      const ok = await ctx.ui.confirm("Dangerous!", "Allow rm -rf?");
      if (!ok) return { block: true, reason: "Blocked by user" };
    }
  });

  // Register a custom tool
  pi.registerTool({
    name: "greet",
    label: "Greet",
    description: "Greet someone by name",
    parameters: Type.Object({
      name: Type.String({ description: "Name to greet" }),
    }),
    async execute(toolCallId, params, signal, onUpdate, ctx) {
      return {
        content: [{ type: "text", text: `Hello, ${params.name}!` }],
        details: {},
      };
    },
  });

  // Register a command
  pi.registerCommand("hello", {
    description: "Say hello",
    handler: async (args, ctx) => {
      ctx.ui.notify(`Hello ${args || "world"}!`, "info");
    },
  });
}

使用 --extension（或 -e）标志进行测试：

pi -e ./my-extension.ts

扩展位置

安全提示： 扩展以你的完整系统权限运行，可以执行任意代码。只从你信任的来源安装。

扩展会从受信任的位置自动发现。项目本地的 .pi/extensions 条目只会在项目获得信任后加载。

还可以通过 settings.json 添加额外路径：

{
  "packages": [
    "npm:@foo/bar@1.0.0",
    "git:github.com/user/repo@v1"
  ],
  "extensions": [
    "/path/to/local/extension.ts",
    "/path/to/local/extension/dir"
  ]
}

要通过 npm 或 git 以 pi 包的形式分享扩展，参见 packages.md。

可用的导入

npm 依赖也可以使用。在扩展旁边（或其上级目录中）添加一个 package.json，运行 npm install，来自 node_modules/ 的导入就会被自动解析。

对于通过 pi install 安装的分布式 pi 包（npm 或 git），运行时依赖必须位于 dependencies 中。包安装默认使用生产安装（npm install --omit=dev），因此 devDependencies 在运行时不可用；配置了 npmCommand 时，git 包会使用普通的 install，以兼容各类包装器。

Node.js 内置模块（node:fs、node:path 等）同样可用。

编写扩展

扩展导出一个接收 ExtensionAPI 的默认工厂函数。该工厂函数可以是同步的，也可以是异步的：

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  // Subscribe to events
  pi.on("event_name", async (event, ctx) => {
    // ctx.ui for user interaction
    const ok = await ctx.ui.confirm("Title", "Are you sure?");
    ctx.ui.notify("Done!", "info");
    ctx.ui.setStatus("my-ext", "Processing...");  // Footer status
    ctx.ui.setWidget("my-ext", ["Line 1", "Line 2"]);  // Widget above editor (default)
  });

  // Register tools, commands, shortcuts, flags
  pi.registerTool({ ... });
  pi.registerCommand("name", { ... });
  pi.registerShortcut("ctrl+x", { ... });
  pi.registerFlag("my-flag", { ... });
}

扩展通过 jiti 加载，因此 TypeScript 无需编译即可使用。

如果工厂函数返回 Promise，pi 会在继续启动之前等待它完成。也就是说，异步初始化会在 session_start 之前、resources_discover 之前完成，也会先于通过 pi.registerProvider() 排队的提供商注册被刷新。

异步工厂函数

如果需要一次性的启动工作，例如获取远程配置或动态发现可用模型，可以使用异步工厂函数。

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default async function (pi: ExtensionAPI) {
  const response = await fetch("http://localhost:1234/v1/models");
  const payload = (await response.json()) as {
    data: Array<{
      id: string;
      name?: string;
      context_window?: number;
      max_tokens?: number;
    }>;
  };

  pi.registerProvider("local-openai", {
    baseUrl: "http://localhost:1234/v1",
    apiKey: "$LOCAL_OPENAI_API_KEY",
    api: "openai-completions",
    models: payload.data.map((model) => ({
      id: model.id,
      name: model.name ?? model.id,
      reasoning: false,
      input: ["text"],
      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
      contextWindow: model.context_window ?? 128000,
      maxTokens: model.max_tokens ?? 4096,
    })),
  });
}

这种模式让获取到的模型在正常启动期间可用，也能被 pi --list-models 列出。

长生命周期资源与关闭

扩展工厂可能在从不启动会话的调用中运行。不要在工厂函数中启动后台资源，例如进程、socket、文件监视器或定时器。

把后台资源的启动推迟到 session_start 或需要该资源的命令/工具/事件。注册一个幂等的 session_shutdown 处理器，用于关闭你启动的所有会话级资源。

扩展形式

单文件 - 最简单，适合小型扩展：

~/.pi/agent/extensions/
└── my-extension.ts

带 index.ts 的目录 - 适合多文件扩展：

~/.pi/agent/extensions/
└── my-extension/
    ├── index.ts        # Entry point (exports default function)
    ├── tools.ts        # Helper module
    └── utils.ts        # Helper module

带依赖的包 - 适合需要 npm 包的扩展：

~/.pi/agent/extensions/
└── my-extension/
    ├── package.json    # Declares dependencies and entry points
    ├── package-lock.json
    ├── node_modules/   # After npm install
    └── src/
        └── index.ts

// package.json
{
  "name": "my-extension",
  "dependencies": {
    "zod": "^3.0.0",
    "chalk": "^5.0.0"
  },
  "pi": {
    "extensions": ["./src/index.ts"]
  }
}

在扩展目录中运行 npm install，之后来自 node_modules/ 的导入就会自动生效。

事件

生命周期概览

pi starts
  │
  ├─► project_trust (user/global and CLI extensions only, before project resources load)
  ├─► session_start { reason: "startup" }
  └─► resources_discover { reason: "startup" }
      │
      ▼
user sends prompt ─────────────────────────────────────────┐
  │                                                        │
  ├─► (extension commands checked first, bypass if found)  │
  ├─► input (can intercept, transform, or handle)          │
  ├─► (skill/template expansion if not handled)            │
  ├─► before_agent_start (can inject message, modify system prompt)
  ├─► agent_start                                          │
  ├─► message_start / message_update / message_end         │
  │                                                        │
  │   ┌─── turn (repeats while LLM calls tools) ───┐       │
  │   │                                            │       │
  │   ├─► turn_start                               │       │
  │   ├─► context (can modify messages)            │       │
  │   ├─► before_provider_headers (can mutate headers)     |
  │   ├─► before_provider_request (can inspect or replace payload)
  │   ├─► after_provider_response (status + headers, before stream consume)
  │   │                                            │       │
  │   │   LLM responds, may call tools:            │       │
  │   │     ├─► tool_execution_start               │       │
  │   │     ├─► tool_call (can block)              │       │
  │   │     ├─► tool_execution_update              │       │
  │   │     ├─► tool_result (can modify)           │       │
  │   │     └─► tool_execution_end                 │       │
  │   │                                            │       │
  │   └─► turn_end                                 │       │
  │                                                        │
  ├─► agent_end                                            │
  └─► agent_settled (no retry/compaction/follow-up left)   │
                                                           │
user sends another prompt ◄────────────────────────────────┘

/new (new session) or /resume (switch session)
  ├─► session_before_switch (can cancel)
  ├─► session_shutdown
  ├─► session_start { reason: "new" | "resume", previousSessionFile? }
  └─► resources_discover { reason: "startup" }

/fork or /clone
  ├─► session_before_fork (can cancel)
  ├─► session_shutdown
  ├─► session_start { reason: "fork", previousSessionFile }
  └─► resources_discover { reason: "startup" }

/name or pi.setSessionName()
  └─► session_info_changed

/compact or auto-compaction
  ├─► session_before_compact (can cancel or customize)
  ├─► session_compact (success)
  └─► session_compact_failed (failure or abort)

/tree navigation
  ├─► session_before_tree (can cancel or customize)
  └─► session_tree

/model or Ctrl+P (model selection/cycling)
  ├─► thinking_level_select (if model change changes/clamps thinking level)
  └─► model_select

thinking level changes (settings, keybinding, pi.setThinkingLevel())
  └─► thinking_level_select

exit (Ctrl+C, Ctrl+D, SIGHUP, SIGTERM)
  └─► session_shutdown

启动事件

project_trust

在 pi 决定是否信任一个带有动态配置（.pi 或 .agents/skills）的项目之前触发。它在启动期间触发，也会在会话替换（例如 /resume）进入一个其信任状态尚未在当前进程中解析的 cwd 时触发。只有用户/全局扩展和 CLI -e 扩展会参与；项目本地扩展要等到信任解析之后才会加载。

pi.on("project_trust", async (event, ctx) => {
  // event.cwd - current working directory
  // ctx has a limited trust context: cwd, mode, hasUI, and select/confirm/input/notify UI helpers
  if (await ctx.ui.confirm("Trust project?", event.cwd)) {
    return { trusted: "yes", remember: true };
  }
  return { trusted: "undecided" };
});

project_trust 处理器必须返回 { trusted: "yes" | "no" | "undecided" }。返回 "yes" 或 "no" 的用户/全局扩展或 CLI 扩展即拥有决定权；第一个 yes/no 决定会胜出并抑制内置的信任提示。使用 remember: true 可持久化 yes/no 决定；否则它只对当前进程生效。返回 "undecided" 则交给后续处理器或内置信任流程决定。弹出提示前先检查 ctx.hasUI。如果没有处理器返回 yes/no，则继续正常的信任解析：先应用已保存的 trust.json 决定，再由 defaultProjectTrust 控制 pi 默认是询问、信任还是拒绝。

资源事件

resources_discover

在 session_start 之后触发，让扩展可以贡献额外的技能、提示词和主题路径。启动路径使用 reason: "startup"，重载使用 reason: "reload"。

pi.on("resources_discover", async (event, _ctx) => {
  // event.cwd - current working directory
  // event.reason - "startup" | "reload"
  return {
    skillPaths: ["/path/to/skills"],
    promptPaths: ["/path/to/prompts"],
    themePaths: ["/path/to/themes"],
  };
});

会话事件

会话存储内部结构和 SessionManager API 参见 会话格式。

session_start

在会话启动、加载或重载时触发。

pi.on("session_start", async (event, ctx) => {
  // event.reason - "startup" | "reload" | "new" | "resume" | "fork"
  // event.previousSessionFile - present for "new", "resume", and "fork"
  ctx.ui.notify(`Session: ${ctx.sessionManager.getSessionFile() ?? "ephemeral"}`, "info");
});

session_info_changed

当通过 /name、RPC 或 pi.setSessionName() 设置当前会话的显示名称时触发。

pi.on("session_info_changed", async (event, ctx) => {
  // event.name - current normalized name, or undefined if cleared
  ctx.ui.notify(`Session renamed: ${event.name ?? "(none)"}`, "info");
});

session_before_switch

在启动新会话（/new）或切换会话（/resume）之前触发。

pi.on("session_before_switch", async (event, ctx) => {
  // event.reason - "new" or "resume"
  // event.targetSessionFile - session we're switching to (only for "resume")

  if (event.reason === "new") {
    const ok = await ctx.ui.confirm("Clear?", "Delete all messages?");
    if (!ok) return { cancel: true };
  }
});

成功切换或新建会话之后，pi 会为旧的扩展实例发出 session_shutdown，为新会话重新加载并重新绑定扩展，然后发出带有 reason: "new" | "resume" 和 previousSessionFile 的 session_start。 清理工作放在 session_shutdown 中完成，然后在 session_start 中重建任何内存状态。

session_before_fork

在通过 /fork 分叉或通过 /clone 克隆时触发。

pi.on("session_before_fork", async (event, ctx) => {
  // event.entryId - ID of the selected entry
  // event.position - "before" for /fork, "at" for /clone
  return { cancel: true }; // Cancel fork/clone
  // OR
  return { skipConversationRestore: true }; // Reserved for future conversation restore control
});

成功分叉或克隆之后，pi 会为旧的扩展实例发出 session_shutdown，为新会话重新加载并重新绑定扩展，然后发出带有 reason: "fork" 和 previousSessionFile 的 session_start。 清理工作放在 session_shutdown 中完成，然后在 session_start 中重建任何内存状态。

session_before_compact / session_compact / session_compact_failed

在上下文压缩时触发。详情参见 compaction.md。

pi.on("session_before_compact", async (event, ctx) => {
  const { preparation, branchEntries, customInstructions, reason, willRetry, signal } = event;

  // reason - "manual" (/compact), "threshold", or "overflow"
  // willRetry - whether the aborted turn is retried after compaction (overflow recovery)

  // Cancel:
  return { cancel: true };

  // Custom summary:
  return {
    compaction: {
      summary: "...",
      firstKeptEntryId: preparation.firstKeptEntryId,
      tokensBefore: preparation.tokensBefore,
      // usage: summaryResponse.usage, // Optional; included in session totals
    }
  };
});

pi.on("session_compact", async (event, ctx) => {
  // event.compactionEntry - the saved compaction
  // event.fromExtension - whether extension provided it
  // event.reason - "manual" (/compact), "threshold", or "overflow"
  // event.willRetry - whether the aborted turn is retried after compaction (overflow recovery)
});

pi.on("session_compact_failed", async (event, ctx) => {
  // event.reason - "manual" (/compact), "threshold", or "overflow"
  // event.errorMessage - present for non-abort failures
  // event.aborted - true for cancelled/aborted compactions
  // event.willRetry - whether the aborted turn would have retried after compaction
  // event.fromExtension - whether extension-provided compaction content was being used
});