📚 编程进阶教程站

第 2 章 · 安装与快速上手 ​

本章目标：完成 pi 的安装与首次认证，在真实项目里跑通第一个任务，掌握 @ 引用文件、! 执行命令、会话续聊等高频上手操作。

2.1 安装 ​

pi 以 npm 包分发，推荐安装命令带 --ignore-scripts：

bash
# 官方推荐：跳过依赖的生命周期脚本（pi 本身不需要安装脚本）
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# 备选：curl 安装脚本（内部同样走 npm 全局）
curl -fsSL https://pi.dev/install.sh | sh

验证与卸载：

bash
pi --version        # 查看版本，如 0.84.x

# 用安装时对应的包管理器卸载
npm uninstall -g @earendil-works/pi-coding-agent

卸载不会清空数据

卸载包只会移除程序本身；你的设置、凭据、会话和已安装的 pi 包都保留在 ~/.pi/agent/ 目录。想彻底重来需要手动删除该目录。

2.2 首次认证 ​

pi 支持两类接入方式，任选其一：

方式一：订阅登录（Claude Pro/Max、ChatGPT Plus/Pro Codex、GitHub Copilot 等）：

text
$ pi
/login        # 在交互界面输入该命令，按提示选择 provider 完成 OAuth 登录

方式二：API Key 环境变量：

bash
export ANTHROPIC_API_KEY=sk-ant-...
pi

也可以通过 /login 选择 API-key 类 provider，把密钥持久化到 ~/.pi/agent/auth.json（权限 0600），之后就不必每次 export。第 3 章会展开全部 provider 与密钥解析规则。

2.3 第一个任务 ​

进入目标项目目录启动：

bash
cd /path/to/project
pi

直接用自然语言下达任务并回车：

text
总结这个仓库，并告诉我如何运行它的检查。

模型会用默认的 read/bash 等工具自行浏览文件、执行命令、汇总答案。注意：pi 在当前工作目录中拥有真实的文件修改能力，重要项目请先用 git 建立可回滚状态。

2.4 高频上手操作速览 ​

bash
# 1. 用 @ 模糊引用文件（编辑器里输入 @ 触发搜索）
pi @README.md "总结这个文件"
pi @src/app.ts @src/app.test.ts "把两者放在一起评审"

# 2. ! 前缀执行 shell 命令并把输出交给模型；!! 则不进入模型上下文
!npm run lint
!!ls -la

# 3. 切换模型与思考等级
/model          # 或快捷键 Ctrl+L 打开模型选择器
# Shift+Tab 循环切换思考(thinking)等级

# 4. 会话续聊
pi -c           # 继续最近一次会话
pi -r           # 浏览历史会话列表
pi --name "重构认证模块"   # 启动时给会话命名

给项目补充长期指令：在仓库根目录放一个 AGENTS.md（或 CLAUDE.md），pi 启动时自动加载：

markdown
# 项目指令示例（AGENTS.md）

- 代码修改后运行 `npm run check`。
- 不要在本地执行生产环境迁移。
- 回答保持简洁。

修改上下文文件后无需重启，执行 /reload 即可生效。

2.5 升级与版本管理 ​

bash
npm install -g @earendil-works/pi-coding-agent@latest   # 升级到最新版
pi --version                                            # 确认当前版本
pi changelog                                            # 查看版本历史(交互内可用 /changelog)

关闭启动联网检查

pi 启动时会检查新版本（可通过 PI_SKIP_VERSION_CHECK=1 关闭）；离线环境加 --offline 可禁用全部启动期网络请求。

2.6 快速上手走读小结 ​

对照官方 quickstart 的动线：install → authenticate → first session → AGENTS.md → 常见玩法（@ 引用 / ! 命令 / 切模型 / 续聊）→ 非交互模式。建议现在就在一个玩具项目上完整走一遍，再进入下一章了解 provider 与模型的配置细节。

本章小结 ​

  • 安装用 npm i -g --ignore-scripts @earendil-works/pi-coding-agent，数据独立存放在 ~/.pi/agent/；
  • 认证二选一：/login 订阅 OAuth，或 API Key 环境变量/auth.json；
  • 默认工具 read/write/edit/bash 即可完成大部分任务，git 是你的回滚保险；
  • @ 引用文件、! 执行命令、-c/-r/--name 管理会话是四大高频操作；
  • 项目级指令写进 AGENTS.md，改动后 /reload 生效。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. 官方推荐的 pi 安装命令是？

2. 卸载 pi 之后，以下哪类数据仍会保留？

3. 编辑器中想让一条命令的输出"只给自己看、不发给模型"，应该用？

4. 修改了项目的 AGENTS.md 后，让它立即生效的正确做法是？

🛠️ 动手实践 ​

  1. 安装 pi 并用 /login 或环境变量完成一次认证，记录你选择的 provider 与理由。
  2. 在一个 git 仓库里让 pi "总结仓库并说明如何运行测试"，观察它调用了哪些工具、顺序如何。
  3. 为该项目编写一个最小 AGENTS.md（至少 3 条约定），重启 pi 后验证它是否遵守（例如要求它回答末尾附上"已读 AGENTS.md"）。

跑通了第一个任务？进入下一章：Providers 与 Models 配置，把模型层彻底玩明白。