$ pi –getting-started

Pi 是一个开源的终端编程智能体（coding agent），由 earendil-works 维护（最初由 Mario Zechner 以 pi-mono 之名创建）。它在你的项目目录中运行，可以读写文件、执行 shell 命令，并通过一个快速的 TUI 实时展示全过程。本指南带你从零完成第一次会话。

前置条件

Node.js 与 npm —— Pi 以 npm 包的形式分发（发布版也提供基于 Bun 的独立二进制，但常规安装方式是 npm）。
一个现代终端。如果你使用 Windows Terminal、tmux 或小众终端模拟器，请先查看官方的终端配置说明。
一个 LLM 账户：受支持的订阅（Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot、xAI、OpenRouter），或任一受支持提供商的 API key。

安装

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

--ignore-scripts 会在安装时禁用依赖的生命周期脚本；正常 npm 安装下 Pi 并不需要这些脚本。这是项目供应链加固的一部分：直接依赖全部锁定精确版本，发布包附带 shrinkwrap 文件。

也可以使用 curl 安装脚本（底层同样是 npm）：

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

验证安装：

pi --version

首次启动

在希望 Pi 工作的目录中启动：

cd /path/to/project
pi

Pi 以当前工作目录为作用域，可以直接修改其中的文件。它没有内置的权限弹窗系统——Pi 以你的用户权限运行——因此建议在 git 管理的代码树上工作（或使用检查点扩展），以便随时回滚。

启动后，TUI 顶部会显示已加载的上下文文件、提示词模板、技能和扩展，下方依次是消息区和输入编辑器。

认证

Pi 支持两种认证方式。

方式一：订阅登录（OAuth）

在 Pi 中运行 /login，然后选择提供商。内置的订阅登录包括：

Claude Pro/Max
ChatGPT Plus/Pro（Codex）
GitHub Copilot
xAI（Grok/X 订阅）
OpenRouter（生成一个从你的 OpenRouter 额度计费的 API key）
Radius

令牌保存在 ~/.pi/agent/auth.json 中，过期时自动刷新。使用 /logout 清除凭据。

方式二：API key

启动前导出环境变量，例如：

export ANTHROPIC_API_KEY=sk-ant-...
pi

或者运行 /login 并选择一个 API-key 提供商，将密钥写入 ~/.pi/agent/auth.json。其他常见变量包括 OPENAI_API_KEY、GEMINI_API_KEY、DEEPSEEK_API_KEY、GROQ_API_KEY、XAI_API_KEY、OPENROUTER_API_KEY。完整列表——超过 30 家提供商——见providers 文档。

第一次会话

输入请求并按回车：

Summarize this repository and tell me how to run its checks.

默认情况下，Pi 给模型四个工具：read、write、edit 和 bash。只读工具 grep、find、ls 可通过工具选项启用。智能体循环工作——模型回复、调用工具、读取结果、再次回复——直到任务完成。

值得立刻尝试的功能：

引用文件：在编辑器中输入 @ 可模糊搜索项目文件，也可以在命令行传文件：pi @README.md "Summarize this"。
执行 shell 命令：!npm run lint 执行命令并将输出发送给模型；!!command 执行但不把输出放入上下文。
粘贴图片：Ctrl+V（Windows 上 Alt+V），或直接拖拽图片到支持的终端中。
切换模型：/model 或 Ctrl+L；Shift+Tab 循环思考等级（thinking level）；Ctrl+P 在设定范围内循环模型。
工作中插话：回车排队一条 steering 消息（当前回合结束后送达），Alt+Enter 排队 follow-up，Escape 中止。

非交互模式

用于一次性提示和脚本集成：

pi -p "Summarize this codebase"
cat README.md | pi -p "Summarize this text"
pi -p @screenshot.png "What's in this image?"

--mode json 输出 JSON 事件流；--mode rpc 通过 stdin/stdout 提供 RPC 协议，用于进程间集成。

文件都在哪里

所有用户状态位于 ~/.pi/agent/：

settings.json —— 全局设置（项目级覆盖写在仓库内的 .pi/settings.json）
auth.json —— OAuth 令牌与 API key
sessions/ —— 已保存的会话，按工作目录组织
AGENTS.md —— 每个会话都会加载的全局指令
extensions/、skills/、themes/ —— 自动发现的资源目录
trust.json —— 已保存的项目信任决定
models-store.json —— 缓存的提供商模型目录

当项目包含 .pi/settings.json 或项目级扩展时，Pi 会在加载前询问是否信任该目录。用 /trust 保存决定。

更新

Pi 可以自我更新：

pi update --self     # 仅更新 pi CLI
pi update --all      # 更新 pi 和已安装的包

如果通过 npm 安装，npm update -g @earendil-works/pi-coding-agent 同样有效。卸载：npm uninstall -g @earendil-works/pi-coding-agent——注意这会保留 ~/.pi/agent/（设置、凭据、会话）。

Pi 快速上手