Kc's blog

Appearance

kc_shen2026-08-28
1503
6m

Pi Agent 使用指南 ​

Pi 是开源的 终端 Coding Agent（MIT）：在项目目录里读文件、改代码、跑命令。交互上接近 Claude Code、Codex CLI，但定位不同——它是一套极简 harness，默认不做 Plan Mode、子 Agent、MCP，把工作流留给 AGENTS.md、Skills 和扩展。

本文覆盖安装、登录、日常命令和一套可照着做的 Vue 流程。命令以 官方文档 为准，产品迭代快，遇歧义请查官网。

1. 适合谁、和 Claude Code 差在哪 ​

  • 适合：习惯终端、想自己选模型、希望用项目约定约束 Agent 的前端 / Node 仓库。
  • 不太适合：指望装完就有权限弹窗、Plan Mode、内置 MCP——这些要自己装扩展，或继续用 Claude Code / Cursor。
  • 核心差别：Claude Code 是功能完整的封闭产品；Pi 默认只给 read / edit / write / bash 等基础工具，一套 TUI 切 15+ 家模型（Anthropic、OpenAI、Gemini、OpenRouter、Ollama 等）。

工作循环和别的 Agent 一样：

text
读取项目 → 分析 → 改文件 → 跑命令 → 看结果 → 继续修

2. 安装 ​

需要已安装 Node.js。当前包在 @earendil-works 作用域（2026 年 5 月从 @mariozechner 迁出，旧包名不要再用）。

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

--ignore-scripts 是官方推荐：Pi 正常安装不依赖 lifecycle scripts。macOS / Linux 也可用：

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

验证：

bash
pi --version
pi --help

更新 CLI：pi update --self，或 npm update -g @earendil-works/pi-coding-agent。

3. 登录与选模型 ​

第一次进交互界面，先准备好 Claude / ChatGPT / Copilot 订阅，或任意支持厂商的 API Key。

text
/login

按提示走 OAuth 或填 Key。之后随时：

操作怎么做
切换模型/model 或 Ctrl + L
把当前模型存成启动默认在模型选择器里 Ctrl + S
在常用模型间循环/scoped-models 勾选后，用 Ctrl + P
改思考级别Shift + Tab，或 /thinking

思考级别不必拉满：

text
简单修改 → low
日常开发 → medium
复杂 Bug / 架构 → high / xhigh

4. 启动 ​

进入项目根目录再开 Pi（它会加载该目录及上层的 AGENTS.md）：

bash
cd /path/to/your-project
pi

进来后先让它看，不要改：

text
帮我分析一下这个项目的整体结构，暂时不要修改代码。

也可以启动时带上任务，或把文件塞进上下文：

bash
pi "帮我分析这个项目"
pi @package.json "这个项目用了哪些技术"
pi @src/api/user.ts @src/views/user/index.vue "分析这两个文件之间的数据流"

交互里输入 @ 会模糊搜索仓库文件。一次性脚本用 pi -p "问题"，跑完就退出。

5. 斜杠命令 ​

输入 / 会出现补全。日常够用的是这些：

命令作用
/help帮助
/login / /logout登录或退出
/model切换模型
/thinking思考级别
/settings主题、传输等
/new新 Session
/resume恢复历史 Session
/session当前 Session 信息
/tree跳到历史任意节点继续
/fork从某条用户消息分出新 Session
/compact压缩上下文（上下文快满时也会自动摘要）
/reload重载扩展、Skills、AGENTS.md
/quit退出（也可连按两次 Ctrl + C）

Session 存在 ~/.pi/agent/sessions/，按工作目录归档。任务做完用 /new；接着昨天的用 /resume，或启动时 pi -c 继续最近一次。对话太长就 /compact。

6. 终端命令：! 和 !! ​

text
!npm run build      # 执行，并把输出交给模型
!!npm run build     # 只执行，不把输出交给模型

典型循环：改代码 → !npm run build → 有错让它修 → 再 build。

Agent 还在跑时：Enter 插入转向消息（当前工具跑完再生效），Alt + Enter 排队等它全部做完再发（Windows Terminal 默认可能把 Alt + Enter 占成全屏，需在终端里改键）。

7. 快捷键 ​

快捷键功能
Shift + Tab切换 Thinking Level
Esc中断当前操作
Esc Esc打开 Session Tree
Ctrl + L模型选择
Ctrl + P在已勾选的常用模型间切换
Ctrl + O折叠 Tool 输出
Ctrl + T折叠 Thinking
Ctrl + G用外部编辑器写提示
Ctrl + C × 2退出

完整列表在会话里执行 /hotkeys。

8. AGENTS.md 和 Skills ​

长期用的话，在项目根放 AGENTS.md（也认 CLAUDE.md）。启动时会从 ~/.pi/agent/、父目录、当前目录层层加载。某层若有 AGENTS.override.md，该层只读 override。

前端仓库可以这样写：

markdown
# Project Instructions

## 技术栈

- Vue 3
- TypeScript
- Vite
- Pinia
- Axios

## 编码规范

- 使用 Composition API
- 优先使用 `<script setup>`
- 新增代码使用 TypeScript
- 优先复用已有组件
- 不要随意增加依赖
- 不要修改与当前任务无关的代码

## 验证

修改完成后运行：

npm run lint
npm run build

## Git

不要自动执行：

- git push
- git reset --hard
- git clean -fd

Skills 是按需加载的能力包（说明 + 工具），会话里以 /skill:名称 调用，避免一上来塞满 system prompt。项目级 skill 一般在 .agents/skills；第一次在含项目配置的目录启动时，Pi 会问是否信任该项目，同意后才加载项目本地扩展和 skill。改完 AGENTS.md 或 skill 可 /reload。

9. 推荐流程（Vue 项目） ​

bash
cd /path/to/your-project
pi

先对齐范围：

text
先不要修改代码。

分析当前项目结构，并告诉我实现这个需求需要修改哪些文件。

再动手：

text
按照刚才的方案开始修改。

要求：
1. 尽量复用已有代码
2. 不增加新的依赖
3. 不修改无关文件
4. 完成后运行 npm run build

出错就接着修：

text
分析刚才的错误并修复，修复完成后重新执行 build。

最后自己看 diff，再提交：

text
!git diff

10. 速查 ​

text
pi                         启动
pi -c                      继续最近 Session
pi -p "问题"               问完就退出
/login  /model  /thinking  登录、模型、思考级别
/new  /resume  /compact    Session
!npm run build             跑命令并给模型看输出
!!npm run build            只跑命令
@package.json              把文件放进上下文

长期使用优先配好：AGENTS.md + 默认模型 +（按需）Skills。源码与 Issue：github.com/earendil-works/pi。

最近更新