AI 编程助手 Pi 上手指南：安装、模型接入与首个任务

AI 编程助手 Pi：模型由你选，工作流程由你定

Pi 是一个精简的智能体运行框架，负责把模型连接到文件和命令。可以把它看作工作台：你选定的模型决定要做什么，Pi 则提供执行所需的工具。

默认启用的四个内置工具，覆盖了核心工作循环：

模型发起工具调用，Pi 执行后把结果送回对话。这个过程可以不断重复，直到任务完成。这里列出的是默认启用的四个工具，并非 1.0 版本提供的全部内置工具。Pi 工具参考、智能体工作循环。

如果你已经在用 Claude Code 或 Codex，判断 Pi 是否值得尝试，关键是你希望掌控哪些工作流程。我的建议是：有明确的定制需求时再试，比如想加一个仓库审查命令，或者制作一项可复用的迁移技能。想比较更多选择，可以看不绑定模型提供商的编程智能体。

Pi 1.0 在终端界面和工具调用上改了什么？

1.0.0 版本默认使用全屏界面，并改进了 codemode 和登录流程。TUI 指直接显示在终端里的交互界面。初次配置时，以下变化最值得留意：

MCP 用于把智能体连接到外部工具。OAuth 是一种授权登录流程，让工具获得访问权限，而不必拿到你的密码。codemode 允许模型用 JavaScript 组合工具调用，再将选定的结果返回对话。提示词缩减针对的是这一工作方式，并不意味着所有任务的账单都会减少 40%。Pi 1.0.0 发布说明、codemode 参考。

这一版本还支持通过 codemode 脚本生成图像，在 /login 中新增 Radius，并加入 quietStartup: "header"。完成首个编程任务时，可以先不用这些功能。发布说明。

Pi 教程：用 28 分钟完成配置和首个任务

从熟悉的代码仓库开始，确认测试命令能正常运行，并准备好受支持模型的访问权限。下面的时间只是建议预算；下载、登录和测试实际要多久，取决于你的环境。任务要足够小，确保结束前还有时间检查改动。

第 0 至 5 分钟：安装 Pi，打开项目

通过项目提供的 npm 方式安装，需要 Node.js 22.19 或更新版本。下面的命令固定安装 Pi 1.0.0，让操作过程与本文介绍的版本一致：

node --version
npm install -g --ignore-scripts @earendil-works/pi-coding-agent@1.0.0
pi --version
cd /path/to/project
pi --tui-mode regular

把 /path/to/project 换成你的项目目录。pi --version 应显示 1.0.0。直接运行 pi，则会使用新版默认的全屏界面。macOS/Linux 还有官方提供的另一种安装方式：curl -fsSL https://pi.dev/install.sh | sh，该命令会安装当前版本。项目安装文档、快速入门。

第 5 至 10 分钟：接入已有账户

在 Pi 中运行 /login，选择提供商，按提示完成相应的认证流程。接着运行 /model，选择一个可用模型。提供商决定你通过什么渠道访问，模型则负责生成回答。

Pi 的认证文档列出了 Anthropic 订阅和 OpenAI Sign in with ChatGPT 这两种接入方式。OpenAI 的说明是：符合条件的请求可获授权使用套餐额度，但账户必须满足资格要求。选择 API key，则会走另一条计费路径。Pi OAuth 提供商说明、OpenAI 登录文档。

Pi 官网列出的提供商包括 Anthropic、OpenAI、Google、OpenRouter、Ollama 等。支持某个提供商，并不代表每个账户都能看到它的全部模型。如果缺少某个模型，先检查认证；/model 只显示有可用凭据的模型。在选择器中按 Ctrl+S，即可保存默认模型。模型选择文档。

使用 Ollama 时，可以参照项目的兼容端点示例，在 ~/.pi/agent/models.json 中配置：端点为 http://localhost:11434/v1，API 类型为 openai-completions，占位 key 为 ollama，模型 ID 则填写本地安装实际提供的模型。打开 /model 会重新加载该文件。想在没有付费模型账户的情况下试用 Pi，可以走这条本地接入路径。

第 10 至 13 分钟：告诉 Pi 仓库的工作规则

在仓库根目录添加一份简短的 AGENTS.md，或补充你已经维护的那份文件。Pi 会从 ~/.pi/agent/、父目录和当前目录发现指令。会话中修改后，运行 /reload 重新加载。配置文档。

指令应描述仓库的真实情况。例如：

Use the existing test runner and neighboring test conventions.
Keep this task within the function and tests I name.
Do not add dependencies or change the public API.
Run the focused tests and report the exact command and result.
Leave commits and publishing to me.

如果知道对应的测试命令，也把它写进去。AGENTS.md 用来指导模型，并不能强制划定权限边界。

第 13 至 23 分钟：完成一项有用的小改动

选一个已有的辅助函数：它对空输入的处理方式已有明确规定，但还缺少回归测试。用 Pi 的 @ 文件选择器附上这个函数和相邻的测试文件，再提出以下任务：

回归测试用于防止预期行为在后续改动中被破坏。这项任务会产生具体、可查看的代码差异，也不需要 Pi 重新设计整个应用。快速入门文档介绍了 @ 文件选择，以及任务完成后如何检查改动文件。首个任务文档。

第 23 至 28 分钟：检查改动和测试结果

阅读修改后的测试，并查看 git diff 中的文件改动。确认断言检查的是预期行为，再亲自运行对应的测试命令。测试通过可以为改动提供依据；断言是否有用、范围是否合适，仍要由你判断。

首次使用的完成标准很简单：选定的提供商能正常工作，Pi 做出了预期改动，而且你能解释代码差异。定制工作留到下一次会话。

Pi 软件免费，模型用量决定账单

Pi 采用 MIT 许可证，不额外收取软件席位费。通过订阅接入，会消耗套餐提供的使用额度；使用 API key，会产生提供商的用量账单。本地模型则把成本转移到你的硬件和运行维护上。

以 API 计费为例，OpenAI 为 GPT-6.1 Sol 的标准短上下文用量定价：每百万输入 token 为 $2，每百万输出 token 为 $10。token 是计费时统计的内容单位。OpenAI 官方价格。

假设一项小任务的各次请求累计产生以下用量：

这只是算例，并非实测任务用量。计算假设使用标准处理方式，每次请求的输入不超过 272,000 token，且没有缓存写入或单独收费的工具。缓存输入、缓存写入、更长的请求以及其他处理档位，适用不同费率。如果一百项任务都使用完全相同的用量模式，基础模型费用就是 $30。GPT-6.1 Sol 定价细则。

做预算时，真正要衡量的是：你需要的定制功能，是否值得持续维护。Pi 省去了智能体框架的授权费，但模型开销、人工检查，以及支持工作流程所需的工程时间，仍然要计入成本。

扩展工作流程，先选够用的机制

用指令约定规范，用技能保存可重复执行的流程，用扩展实现可执行的功能。

技能的 SKILL.md 开头要写明名称和描述。想显式加载某项技能，可以调用 /skill:name。扩展在 Pi 进程内运行，加载前应检查其代码。技能文档、扩展文档。

pi install ./local-package 用于安装你在本地准备好的包。安装已发布的包时，使用 pi install npm:@scope/package@version，并填入真实名称和版本。加上 --local，会把项目级的包声明写入 .pi/settings.json。在进行中的会话里修改资源后，运行 /reload。包文档。

接入外部 MCP 服务时，先配置服务器；如果需要 OAuth，再运行 /mcp login <server>。建议等基础配置正常工作后，再添加这部分。MCP 文档。

六项实用任务，按实际收益排序

最适合入手的，是熟悉仓库中反复出现的工作。以下是可尝试的流程；实际收益取决于你的代码库，以及检查改动时是否严谨。

1. 为已报告的 bug 补上回归测试。 维护订阅制 Web 应用的创始人，可以附上 bug 的复现过程、实现代码和测试，让 Pi 先写一个能触发失败的测试，再做范围明确的修复，最后重跑相关检查。价值在于把已经观察到的故障固定为长期保留的测试。
2. 提交 pull request 前先审查改动。 开发者可以给 Pi 一份本地代码差异和仓库审查技能，要求它找出潜在缺陷，并附上文件位置和解释。正式审查前发现具体问题，可能少一轮来回沟通。
3. 迁移应用中范围明确的一部分。 维护者可以把迁移步骤写成技能，先应用到一个模块，再运行对应检查。节省时间的可能性来自：在相似模块中复用同一流程，同时逐次检查代码差异。
4. 理解不熟悉的代码仓库。 新加入的工程师可以让 Pi 从入口到存储追踪一条请求，再保存带有文件位置和相关检查命令的笔记。这些笔记有助于减少重复的环境配置问题。
5. 编写小型维护脚本。 负责处理过期测试数据的运维人员，可以让 Pi 起草脚本，用样例输入试跑，并记录使用方法。经过检查的脚本，可能替代反复进行的手工修改。
6. 搭建内部开发流程。 技术负责人可以把自定义命令和技能打包，也可以通过 print mode 集成一次性命令，通过 RPC 控制独立进程，或使用 SDK 库把会话嵌入应用。收益来自让智能体适配经常要做的工作；集成和支持则由负责人承担。集成接口。

最值得开发的方向：面向特定仓库的代码审查工具

合并前审查包是最清晰的机会：这项工作会重复发生，买方也已经了解审查延误的代价。小型工程团队可能愿意为一个持续维护的包付费，让它检查团队自己的规范，并向审查者提供依据。

需求检索得到的结果是：“ai code review” 在美国 Google 的估算月搜索量为 1,300。CodeRabbit Essentials 提供了一个价格参照：按年付费，每位开发者每月 $24；按月付费则为 $30。这些信息表明有人关注代码审查，而且市场上已有付费产品，但不能据此认定 Pi 包也有需求。搜索量来自 DataForSEO 关键词概览，核查日期为 2026 年 10 月 3 日。CodeRabbit 价格。

最小可售版本可以包含一项审查技能、一个收集本地代码差异的命令、针对仓库的检查，以及附有文件位置的报告。初期先在本地完成交付。难点在于差异化：通用提示词很容易被复制，而 Pi 包也需要维护、访问控制和支持。值得出售的是仓库检查的质量，以及持续维护这些检查的服务。

第二个机会是团队入门配置包。工程负责人可能会购买配置和维护服务，用来统一提供商配置、AGENTS.md、共享技能，以及少量经过团队认可的扩展。需求检索中，“open source ai coding assistant” 在美国的估算月搜索量为 1,600，由 DataForSEO 在同一天测得。首个版本可以是一份包，加上一套面向某个团队仓库的入门流程。难点在于：搜索兴趣不能证明用户愿意为安装付费；持续价值必须来自对团队工作流程的维护。

没人愿意维护默认配置时，Pi 就不合适

如果团队希望权限审批、隔离和标准化流程由有支持服务的产品直接提供，就应选择由产品方维护的工具。Pi 的工具沿用启动该进程的权限。项目信任机制控制哪些项目资源会被加载，却不会把工具调用关进沙箱。指定工作目录，也不能阻止命令访问其他有权限访问的路径。Pi 安全模型。

扩展可以添加确认流程或路径保护，容器可以提供操作系统层面的隔离边界。但这些选择都需要团队自行实现并维护。codemode 的 JavaScript 沙箱同样不会改变被调用工具的权限。扩展能力、codemode。

Pi 的核心也没有内置子智能体和规划模式。我的判断是：对于想从精简基础出发、自行塑造工具的开发者，这样的取舍很合适；对于希望由别人承担这些决策的团队，则不合适。项目设计取舍。

周一，在你维护的仓库里给 Pi 一项范围明确的 bug 修复或测试任务。保留代码差异和测试结果，再判断哪种重复流程值得做成技能。如果想为团队开发定制工作流程，可以从 AI 智能体开发服务开始。