Pi 本机安装与使用

本文不是通用教程，而是基于本机实际环境整理的一份安装与使用实录：记录了 pi（Pi Coding Agent）在这台机器上是怎么装的、配置文件放在哪、日常怎么用，以及当前已安装的扩展与包清单。通用玩法可以看站内另外几篇 pi 文章（使用教程、快速上手指南、扩展生态等）。

环境概览

本机当前环境：

• Node.js 由 fnm 管理，当前版本 v26.5.1
• pi 通过 npm 全局安装，包名 @earendil-works/pi-coding-agent
• 当前版本 0.83.0
• 可执行文件路径：~/.local/share/fnm/node-versions/v26.5.1/installation/bin/pi

pi --version
# 0.83.0

因为全局包挂在 fnm 管理的 node 版本目录下，切换 node 版本后如果找不到 pi 命令，检查一下全局包是否装在了当前激活的版本里。

安装

npm 全局安装（本机采用的方式）

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

--ignore-scripts 会跳过依赖的生命周期脚本；pi 的正常安装不需要执行这些脚本，所以可以放心加。装完验证：

pi --version
pi --help

官方安装脚本（替代方案）

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

两种方式任选其一，本机用的是 npm 方式。

升级

pi update --self          # 只升级 pi 本体
pi update --all           # 同时升级 pi 和已安装的包
pi update --extensions    # 只升级包
pi update --models        # 刷新模型目录

配置目录解析

pi 的所有配置都集中在 ~/.pi/agent/ 下，本机实际目录结构：

~/.pi/agent/
├── AGENTS.md            # 全局上下文文件（所有项目都会加载）
├── settings.json        # 全局设置（默认模型、主题、已装包等）
├── settings-extensions.json
├── auth.json            # 登录凭证（勿泄露，不要提交到仓库）
├── trust.json           # 项目信任记录
├── models.json          # 模型目录缓存
├── extensions/          # 本地扩展
│   ├── pi-guard/
│   ├── pi-permission-system/
│   └── pi-rtk-optimizer/
├── skills/              # 本地技能
│   └── find-skills/
├── npm/                 # npm 源安装的 pi 包
├── git/                 # git 源安装的 pi 包
├── sessions/            # 会话存档（JSONL）
└── state/               # 运行时状态

关键文件说明：

全局 vs 项目：~/.pi/agent/settings.json 是全局配置，项目根目录的 .pi/settings.json 会覆盖全局；上下文文件（AGENTS.md/CLAUDE.md）按 ~/.pi/agent → 父目录 → 当前目录的优先级全部加载并拼接。

本机 settings.json 说明

本机 ~/.pi/agent/settings.json 里的关键项：

{
  "compaction": { "enabled": true },
  "defaultModel": "opencode-go/deepseek-v4-flash",
  "defaultProvider": "pi-switch",
  "defaultThinkingLevel": "high",
  "hideThinkingBlock": true,
  "theme": "front-end-delight",
  "transport": "auto"
}

• 默认模型/provider：opencode-go/deepseek-v4-flash，provider 是 pi-switch（默认模型就是本机日常在用的）
• 思考级别：默认 high，可在会话中随时用 Shift+Tab 切换
• 主题：front-end-delight（来自 pi-curated-themes 包）
• compaction：开启，长会话自动压缩，防止撑爆上下文
• transport：auto，让 provider 自动选择 SSE 或 WebSocket

已安装的包清单（settings.json 的 packages 字段，共 22 个）：

pi-fff                      pi-permission-system      pi-extension-settings
pi-powerbar                 rpiv-ask-user-question    rpiv-todo
pi-btw                      pi-caffeinate             pi-goal
pi-plan-mode                pi-subagents              pi-raw-paste
pi-curated-themes           pi-agent-browser-native   pi-autoresearch
pi-cache-optimizer          pi-hashline-edit-pro      pi-mcp-adapter
pi-rtk-optimizer            pi-slopchop               pi-web-access
pi-workspace-history

登录与模型

登录

在交互模式中输入 /login（退出用 /logout），按提示选择 provider 并完成认证。pi 支持两类认证方式：

• 订阅：Anthropic Claude Pro/Max、OpenAI ChatGPT Plus/Pro（Codex）、GitHub Copilot
• API key：Anthropic、OpenAI、Azure OpenAI、DeepSeek、NVIDIA NIM、Google Gemini、Google Vertex 等

凭证保存位置见上文 auth.json，注意保密。

切换模型

也可以启动时直接指定：

pi --provider anthropic --model claude-sonnet "帮我重构这个函数"
pi --model openai/gpt-4o "你好"
pi --model sonnet:high "思考级别简写"
pi --list-models          # 列出可用模型

日常使用

启动方式

pi                        # 交互模式（新会话）
pi "列出 src/ 下所有 .ts 文件"   # 带初始提示词进入
pi -c                     # 继续最近的会话
pi -r                     # 浏览并选择历史会话
pi --name "release 审计"   # 给会话起显示名
pi --no-session           # 临时会话，不落盘
pi -p "总结这个代码库"      # 非交互模式，打印结果后退出

非交互模式还支持管道输入：

cat README.md | pi -p "总结这份文档"

常用命令

编辑器里输入 / 触发命令：

常用快捷键

编辑器特性

• @：模糊搜索并引用项目文件
• Tab：补全路径
• Shift+Enter：多行输入
• Ctrl+V：粘贴图片或文本，也可以直接把图片拖进终端
• !command：执行 shell 命令并把输出发送给模型；!!command 执行但不发送
• Enter：排入一条 steering 消息（当前回合工具执行完后送达）
• Alt+Enter：排入一条 follow-up 消息（等 agent 全部工作结束才送达）
• Esc：中止并把排队消息退回编辑器；Alt+Up 取回排队消息

会话管理

会话以 JSONL 文件存放在 ~/.pi/agent/sessions/，按工作目录组织，用 id + parentId 构成树状结构，支持原地分支而不新建文件。

• /tree：在会话树中原地导航，选中任意历史节点继续、切换分支；支持搜索、折叠（Ctrl+←/→、Alt+←/→）、过滤模式（Ctrl+O），Ctrl+X 复制选中消息，Shift+L 加书签
• /fork：从活动分支的某条历史消息派生新会话文件
• /clone：把当前分支完整复制到新会话文件
• --fork <path|id>：从 CLI 直接 fork 指定会话

压缩（compaction）在上下文接近上限时自动触发（也可 /compact 手动触发），会总结旧消息、保留新消息。压缩是有损的，完整历史仍在 JSONL 里，随时可用 /tree 回溯。

本机已装扩展与包

extensions/（手工放置的本地扩展）

skills/（本地技能）

• find-skills：查找可用技能的技能

已装包清单及简要用途

查看/管理已装包：

pi list                  # 列出已装包
pi install npm:@foo/pi-tools   # 安装（npm/git/URL 源）
pi install git:github.com/user/repo@v1
pi remove npm:@foo/pi-tools     # 卸载
pi config                # 启用/禁用包里的扩展、技能、提示词、主题

安全提醒：pi 包以完整系统权限运行，扩展会执行任意代码，技能可以指使模型做任何事（包括执行程序）。安装第三方包前先审查源码。

环境变量与常见问题

常用环境变量

项目信任

pi 启动交互会话时，如果项目目录里有项目级设置（.pi/settings.json）、项目资源或项目 .agents/skills，会先询问是否信任。信任后才能加载项目级配置和扩展。相关行为：

• 用 /trust 保存信任决策（写入 ~/.pi/agent/trust.json，重启生效）
• 非交互模式（-p、--mode json/rpc）不弹信任提示，受 defaultProjectTrust 控制（ask/always/never，可在全局 settings 里设置）
• 单次运行可用 -a（信任）/ -na（忽略）覆盖

常见问题

• 切换 fnm node 版本后找不到 pi：全局包装在当前 node 版本的目录下，切版本后需在对应版本重装或改回原版本
• 提示包被更新检查/网络请求卡住：网络受限环境用 pi --offline 或 PI_OFFLINE=1
• 想完全不落盘地试一下：pi --no-session
• 只读模式审查代码：pi --tools read,grep,find,ls -p "Review the code"
• 权限系统拦截命令：本机装了 pi-permission-system，未授权路径/命令会被拦截，这是预期行为；需要放行时调整权限配置或改用授权方式执行

验证与自查

1. pi --version 输出版本号，pi --help 正常打印帮助
2. pi list 列出的已装包与 settings.json 的 packages 字段一致
3. 启动 pi 后发起一次对话，/session 能看到当前会话的 ID、消息数与 token 消耗
4. 修改 ~/.pi/agent/settings.json 或 models.json 后，会话内 /model 或 /reload 热加载生效，无需重启

本文记录的是本机 2026-08 的实际状态，pi 迭代很快，配置目录结构、默认值等以 pi --version 和 ~/.pi/agent/ 实际内容为准。

参考

• Pi 官网（pi.dev）
• Pi Coding Agent GitHub 仓库