03 · 安装 Pi 与日常工作¶

3.1 建议从固定版本开始¶

node --version
npm install -g --ignore-scripts @earendil-works/[email protected]
pi --version
mkdir -p my-agent-workspace
cd my-agent-workspace
pi

需要 Node 22.19 或更高。这里选择 npm 并显式固定 1.0，避免学习途中自动换版本。官方还提供安装脚本，其安装锁可以固定传递依赖；本课程实验用 package-lock.json 和 npm ci --ignore-scripts 重现依赖。

如果你没有全局 npm 目录的写权限，可用 npm exec --package=@earendil-works/[email protected] -- pi，或自行设置 npm prefix；不需要因为一次目录权限错误就给 Pi root 权限。

3.2 模型认证与第一条任务¶

在 Pi 内执行 /login，选择你已有的 provider；用 /model 选模型。也可以在启动进程时提供该 provider 支持的环境变量。不要把真实 key 写进 AGENTS.md、课程示例或 Git。

第一条任务建议：

先只读研究这个目录。找出入口文件、主要模块和测试命令。
每个结论给出文件路径。没有验证的内容明确标注。
完成后写一份修改建议，先不要修改业务代码。

这段请求是任务约定。若要程序层只读，应选 read,grep,find,ls 并避免加载有写能力的扩展；若要对不可信内容形成安全边界，还需要进程权限或容器。

3.3 操作和会话¶

需求	操作
选择模型 / 推理级别	`/model`、`/thinking`
继续最近会话	`pi --continue`
从列表恢复	`pi --resume`
在会话树选分支	`/tree`
新会话	`/new`
压缩当前上下文	`/compact`
重读配置、资源	`/reload`
查看会话信息	`/session`
修改常见设置	`/settings`
查看信任配置	`/trust`
恢复普通终端滚动	`pi --tui-mode regular`

默认全屏是 1.0 的变化。键盘具体行为可配置；不要把某个终端的快捷键假设成业务逻辑。长任务执行中发送 steer，只会在轮次边界进入，当前轮工具仍会完成；真正取消需要 abort。

3.4 自动化入口¶

# 最终文字
pi --no-approve --tools read,grep,find,ls -p "列出项目入口文件并说明证据"

# JSONL 事件
pi --no-approve --tools read,grep,find,ls --mode json -p "说明项目结构"

# stdin / stdout 的 JSONL 控制协议
pi --mode rpc

--no-approve 拒绝项目受保护资源加载，不代表逐工具拒绝权限。要在自动化中加载自己审过的 .pi 包，可以显式用 --approve。非交互模式没有内建项目信任弹窗；默认 ask 时未获得决定的项目资源会跳过。

print 适合 shell；json 适合采集事件；rpc 适合 Python、Go 等控制子进程；同进程 TypeScript 应用优先 SDK。

3.5 配置文件职责¶

~/.pi/agent/                  # 个人全局
  settings.json
  auth.json                   # 私密，不分享
  models.json
  mcp.json
  trust.json
  extensions/
  skills/
  prompts/

my-project/
  AGENTS.md                   # 项目工作规则
  .pi/
    settings.json
    APPEND_SYSTEM.md
    extensions/
    skills/
    prompts/

SYSTEM.md 替换基础 prompt；APPEND_SYSTEM.md 追加。对应受信项目文件优先于个人同名文件，不是无条件把两个 APPEND 拼在一起。

AGENTS.override.md 只覆盖同目录 AGENTS / CLAUDE 文件，不会抹掉所有祖先规则。context files 的发现不要求项目信任，而 .pi 设置、扩展等要求。第 08 章解释这个区别。

3.6 第一轮练习¶

准备一个小型测试仓库，完成：

让 Pi 只读说明项目，再检查它给的路径是否存在。
让它新增一个低影响函数，检查 diff，运行项目测试。
在 /tree 回到修改前的分支，问不同方案，观察历史仍在。
用 /compact 后继续问之前的约束，核对哪些被保留、哪些丢失。
关闭 Pi，使用 --continue，确认模型选择和历史恢复。

这些练习建立的是对工具与状态的直觉，不能单凭一次回答满意就认定 Agent 可以无人值守处理所有任务。

依据：CLI、配置、会话。