安装与使用初体验

§3.1安装：三种方式对比

Pi 是一个跑在终端里的编码代理（coding agent）。动手读源码之前，先用官方推荐的方式把它装好——能跑起来的系统才值得读。三种安装方式的核心差异不在命令本身，而在依赖是否被锁定与由谁负责更新。

# macOS / Linux 官方安装脚本
curl -fsSL https://pi.dev/install.sh | sh

# Windows 官方安装脚本
powershell -c "irm https://pi.dev/install.ps1 | iex"

# npm 方式（不锁定传递依赖，要求 Node.js 22.19 或更新）
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# Nix 方式（源码构建；旧版本 Nix 用 nix profile install）
nix profile add github:earendil-works/pi/stable

# 验证安装
pi --version

三个容易忽略的细节：第一，官方脚本同时承担安装与更新——重跑 install.sh 会进入菜单，可选择卸载；第二，npm 安装特意加了 --ignore-scripts，因为 Pi 正常安装不需要依赖包的生命周期脚本，关掉它反而更安全；第三，三种方式互不清理——卸载任何一种都不会删除 ~/.pi/agent/ 下的配置、凭据、会话与已安装的 Pi 包。

§3.2首次配置：/login → /model → /thinking

安装完成后的第一次 pi 启动还什么都不能做——Pi 只是个「挽具」（harness），它需要一个可访问的大模型。先分清两个词：模型（model）生成 Pi 的回复；厂商（provider）是你访问该模型所用的服务或账号。

# 1. 进入 Pi 要工作的目录（目录决定文件发现、指令加载与会话分组）
cd /path/to/folder
pi

# 2. 在 Pi 交互界面内依次执行：
/login      # 选择厂商，按提示完成订阅账号登录或存储 API Key
/model      # （可选）切换到其他可用模型
/thinking   # 调整当前模型的思考（reasoning）强度

/login 支持两类凭据：走 OAuth 订阅账号（打开浏览器授权），或直接存 API Key。无论哪种，凭据都保存在 ~/.pi/agent/auth.json——这也是后续安全话题里最敏感的一个文件。不想进会话也可以在终端里完成：pi auth login <provider>（--api-key 存密钥，--no-browser 走设备码等非浏览器方式，适合 SSH 环境）。

/thinking 的等级从低到高是 off、minimal、low、medium、high、xhigh、max，但会被钳制（clamp）在模型能力范围内——给不支持的模型设 max 不会报错，只会取它支持的上限。交互模式里按 Shift+Tab 循环切换；编辑器边框即当前思考等级的指示器。命令行同样能预设：pi --model sonnet:high 里的 :high 后缀，或 --thinking <level>（后者会覆盖模型后缀）。

• /model：打开模型选择器；快捷键 Ctrl+L 打开同一选择器。
• /thinking：选择当前模型使用多少推理能力；Shift+Tab 循环切换。
• /login 与 /logout：管理厂商凭据的存取。

配置完成后给 Pi 一个真实任务即可。Quickstart 文档给的三个示例任务值得照抄一遍——它们分别覆盖「读文件 + 写文件」「仓库结构分析」「多文件对比」三种典型工作流：

Summarize @meeting-notes.md and save the action items to action-items.md.

Explain how this repository is structured and how to run its checks.

Compare @previous.csv with @current.csv and summarize the important changes.

§3.3交互工作流：prompt、steering、follow-up、abort

交互模式（interactive TUI）的界面由三块组成：transcript（对话区，显示你的 prompt、Pi 的回复、每次工具调用、结果与错误）、editor（输入区）与 footer（当前目录、会话、模型、上下文用量与累计费用）。工作流的心脏是一个问题：模型正在干活时，你说的话什么时候生效？

输入侧：prompt 怎么写

• Enter 发送；Shift+Enter 换行；Ctrl+G 在配置的外部编辑器里写长 prompt；
• 输入 @ 搜索并引用文件（Tab 补全路径）；粘贴或拖入图片；
• !git status：执行终端命令并把输出计入对话；!!cmd：执行但不把输出发给模型。

观察侧：Pi 怎么干活

Pi 会可视化每一次工具调用与结果——读了哪个文件、跑了什么命令、改了哪段代码，全部实时显示。Ctrl+O 展开/收起工具输出，Ctrl+T 显示/隐藏思考块。注意官方文档的明确声明：Pi 不会在每次工具调用前征求确认，所以重要工作要靠版本控制或备份兜底，不可信任务要进沙箱。

控制侧：三种「插话」的进入时机

这是本讲最值得画图的地方。你输入的消息有三种去向，官方 usage.md 的表述分别是：以 Enter 发送的消息「等待当前响应及其工具调用结束后，指导下一次响应」（steering）；以 Alt+Enter 发送的 follow-up「等待 Pi 完成当前任务」；Escape 则停止当前任务，且排队中的消息会退回编辑器。

§3.4会话命令：树、分叉、克隆与压缩

Pi 会话不是一条直线，而是一棵条目树（entry tree）：回到历史某点提问，不会抹掉你离开的那个分支。理解这一点后，七个命令的分工就清晰了。

配套的 CLI 入口：pi --continue 恢复当前目录最近一次会话；pi --resume 打开选择器；pi --fork <path|id> 直接分叉。会话默认持久化在 ~/.pi/agent/sessions/，按工作目录分组——每个会话记录创建时的工作目录且永不更改，恢复时 Pi 会在那个目录里运行，工具与 @path 引用都从那里解析。--no-session 则得到一个退出即消失、无法恢复的内存会话。

§3.5四种接口：interactive / print / JSON / RPC

同一套会话与模型配置，有四种消费方式。选型只看两个维度：谁来读输出（人还是程序），以及谁控制生命周期（一次跑完还是长期驻留）。源码层面它们就在 src/modes/ 下各占一个模块。

print 与 JSON：同一 prompt 的两种输出

pi
pi --print "Summarize this repository"
git diff | pi --print "Review this change"
pi --mode json "Inspect this repository" > events.jsonl

print 模式适合「只要答案」：pi --print "Summarize this repository" 只把最终回复写到 stdout；管道场景 git diff | pi --print "Review this change" 会把 stdin 内容前置到 prompt。要看过程就换 JSON 模式——每一行是一个以 LF 结尾的 JSON 对象，首行是 session header，随后是 agent/turn/message/tool 事件：

{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path"}
{"type":"agent_start"}
{"type":"turn_start"}
{"type":"message_start","message":{"role":"user","content":"Review this repository","timestamp":1733234401000}}
{"type":"message_end","message":{"role":"user","content":"Review this repository","timestamp":1733234401000}}
{"type":"message_start","message":{"role":"assistant","content":[],"stopReason":"pending","...":"..."}}
{"type":"message_update","usage":{"...":"..."},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Hello"}}
{"type":"message_end","message":{"role":"assistant","...":"..."}}
{"type":"turn_end","message":{"role":"assistant","...":"..."},"toolResults":[]}
{"type":"agent_end","messages":[{"...":"..."}],"willRetry":false}
{"type":"agent_settled","aborted":false}

两个关键语义：agent_end 只表示一个底层运行结束——自动重试、溢出恢复、压缩重试、steering、follow-up 仍可能继续；agent_settled 才表示 Pi 对这次会话级运行没有剩余的自动工作。文档还给出一个即用的过滤示例：

# 打印一次性运行里已完成的消息
pi --mode json "List files" 2>/dev/null | jq -c 'select(.type == "message_end")'

RPC：把 Pi 变成受控子进程

RPC 模式通过 stdin/stdout 的 JSONL 记录实现双向控制：stdin 写命令，stdout 收response 与会话事件。命令可带字符串 id，响应原样回带用于关联——因为命令处理是异步的，不能按响应顺序对号入座。

# 启动
pi --mode rpc --no-session

# stdin：查询状态 → stdout：带相同 id 的 response
{"id":"req-1","type":"get_state"}
{"id":"req-1","type":"response","command":"get_state","success":true,"data":{"...":"..."}}

# stdin：发送 prompt；success=true 只表示「已接受」，不代表模型跑完
{"id":"req-2","type":"prompt","message":"Review this repository"}
{"id":"req-2","type":"response","command":"prompt","success":true,"data":{"disposition":"started"}}

# 之后继续消费事件流，直到 agent_settled

注意 prompt 的响应语义：success:true 只说明 prompt 被接受、排队或处理（disposition:"started" 表示已启动运行），模型何时跑完要看后续事件；若 disposition:"handled" 则该 prompt 没有启动运行，不必等 agent_settled。帧解析也有一条官方警告：不要用 Node.js 的 readline——它会把 JSON 字符串内合法的 U+2028/U+2029 也当行边界，必须按字节/LF 切分，并持续读取 stdout 以免管道缓冲填满卡住进程。

源码速览：modes/ 目录

四种接口在仓库里各有落点。现在只需记住地图，第 8 讲与第 13 讲会深入：

modes/
├── index.ts                # 模式分发入口
├── interactive/            # 交互 TUI（interactive-mode.ts、tui-renderer.ts）
│   ├── components/         # footer / model-selector / thinking-selector /
│   │                       # tree-selector / login-dialog / tool-execution …
│   └── theme/              # dark.json / light.json / theme-controller
├── print-mode.ts           # print 模式
├── json-event.ts           # JSON 事件流的线格式转换
└── rpc/                    # rpc-mode.ts / rpc-client.ts / rpc-types.ts / jsonl.ts

§3.6配置地图：~/.pi/agent/ 与项目级 .pi/

用户级配置全部住在agent 目录（默认 ~/.pi/agent，可用环境变量 PI_CODING_AGENT_DIR 重定位）；项目级配置住在工作目录的 .pi/ 下，且在项目获得信任后才加载。第 3 讲先建立地图，每个文件在后续讲次逐一展开。

图 3-2 · agent 目录结构（依据 configuration.md 的 Agent directory 与 Project .pi directory 两表）。注意 sessionDir 是唯一在信任判定前读取的例外。

§3.7动手实践

§3.8常见误区

§3.9自测问答