01 安装与首次运行

2026-10-06 07:19

目标：在本机装好 Pi，连上模型，完成第一个任务，知道从哪里继续。

1. 前置条件

macOS / Linux 可用安装脚本：

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

跨平台用 npm（推荐加 --ignore-scripts，Pi 正常安装不需要依赖生命周期脚本）：

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

验证：

pi --version

cd /path/to/your-project
pi

工作目录是 Pi 的核心锚点，它同时决定四件事：

交互界面由三块组成：transcript（对话/工具调用/结果/错误）、editor（写 prompt 和命令）、footer（当前目录、会话、模型、上下文占用、累计用量与费用）。启动头部会列出 Pi 加载了哪些指令和资源。

Pi 里模型（model）负责生成回复，供应商（provider）是访问该模型的服务或账号。在 Pi 内执行：

/login

选择供应商，按提示走订阅登录或存 API key。凭据写入 <agent-dir>/auth.json（默认 ~/.pi/agent/auth.json）。之后用 /model 切换模型，用 /thinking 选择推理强度。

不想落盘凭据时，改用供应商的环境变量（如 ANTHROPIC_API_KEY），详见 03 模型与供应商。

Pi 会显示每一次文件读取、搜索、命令与编辑，但不会在每次工具调用前询问。输入自然语言任务即可，例如：

解释这个仓库的结构以及如何运行它的检查。

总结 @meeting-notes.md，并把行动项写入 action-items.md。

@ 唤起文件搜索，Tab 补全路径；图片可以直接粘贴或拖入兼容终端。

完成后检查回复与被改动的文件。重要工作请先用版本控制或备份；不可信内容或无人值守场景用容器等沙箱隔离。

除非用 --no-session，会话都会自动保存：

pi --continue       # 继续当前目录最近一次会话
pi --resume         # 打开会话选择器

交互模式里对应 /resume；/new 新开；/name 命名；/session 查看文件、ID、消息数、用量与费用。

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

安装器用户重跑安装脚本并选 Uninstall Pi。两种方式都不会删除 ~/.pi/agent/ 下的配置、凭据、会话和已安装的 Pi 包。

形态	入口	用途
交互模式	`pi`	日常开发、边做边指挥
Print 模式	`pi --print "..."`	一次性/脚本化任务，只输出最终文本
JSON 事件流	`pi --mode json`	消费结构化事件（JSONL）
RPC 模式	`pi --mode rpc`	用 JSONL 命令控制独立的 Pi 进程
SDK	`@earendil-works/pi-coding-agent`	在自己的应用内进程内运行 Pi

五种形态共用同一套 agent 与 session 机制，这是 Pi 架构的关键约束。

Pi 的设计原则是：优先用最弱的机制解决问题。