Pi Coding Agent（命令名是 pi）是一个很轻量的终端编码代理。它的核心只提供对话、读写文件和执行命令；计划模式、子代理、MCP、权限弹窗等能力都不强行内置，而是交给扩展、Skill 或你自己的工作流。因此它很适合希望自己决定工具链和约束方式的人。

三分钟开始

安装后，在目标仓库目录里启动即可：

1
2
3
4
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

cd /path/to/project
pi

首次启动可输入 /login，用订阅账号登录并选择模型；也可以在启动前设置对应供应商的 API Key：

1
2
export ANTHROPIC_API_KEY=sk-ant-...
pi

进入交互界面后，直接把任务讲清楚。例如：

1
先阅读这个仓库，说明启动、测试和构建命令；不要修改任何文件。

确认它理解项目后，再给具体任务：

1
2
修复用户列表加载失败的问题。先定位原因并说明修改方案，
然后只修改必要文件，最后运行相关测试并汇报结果。

好提示词不必很长，但最好包含四件事：目标、改动范围、不能做什么、如何验证。先让它只读分析，再授权修改，通常比一上来“帮我修一下”稳定得多。

日常最常用的操作

操作用法说明
引用文件@README.md在输入框输入 @ 可模糊搜索文件；也能在启动时传入 pi @README.md "解释这个项目"。
跑命令并让模型看结果!npm test命令输出会进入当前上下文，适合把测试失败信息交给 Pi 分析。
只在本地跑命令!!git status输出不发送给模型，适合自己快速查看。
切换模型/model也可用 Ctrl+L。
查看或恢复会话/resume、pi -c会话会按工作目录自动保存。
压缩长会话/compact在任务变长、上下文快满时保留关键信息继续工作。
重新读取配置/reload修改指令文件、Skill 或扩展后使用。

Pi 默认给模型 read、write、edit、bash 四类工具。因此它不是只会给建议的聊天工具：在当前工作目录里，它可以实际改文件、执行测试，也可能执行错误的命令。

用 AGENTS.md 固定项目规则

在仓库根目录放置 AGENTS.md，把每次都要重复说的约定写进去：

1
2
3
4
5
6
# Project Instructions

- 修改代码后运行 `npm run check`。
- 不要执行生产环境迁移。
- 先解释方案，再修改文件。
- 保持改动小且可测试。

Pi 会加载全局的 ~/.pi/agent/AGENTS.md，也会从父目录到当前目录查找 AGENTS.md 或 CLAUDE.md。修改这些文件后重启 Pi，或输入 /reload 使其生效。

一个稳妥的使用节奏

  1. 在干净分支或单独的 worktree 中启动 pi。
  2. 先让它概览仓库、列出计划，不修改文件。
  3. 明确限定改动范围和验收命令，再让它实施。
  4. 自己查看 git diff 与测试结果；重要改动不要只看它的总结。

Pi 没有内建的逐项权限确认机制，安全边界主要靠运行环境和工作习惯：不要在包含敏感凭据的目录里随意运行陌生提示词；对不信任的项目优先使用容器、沙箱或临时 worktree；安装第三方 Pi Package 前先读源码，因为扩展可以执行任意代码。

需要再扩展时

基础使用到这里已经足够。遇到重复工作时，再逐步加入：

  • Prompt Template：把常用的审查、排障提示固化成 /命令。
  • Skill：为特定任务提供可复用的操作说明，可手动调用或由 Pi 自动加载。
  • Extension：用 TypeScript 增加自定义工具、命令、事件处理或界面。
  • Pi Package：把上述内容打包，通过 npm 或 Git 在团队中复用。

Pi 的思路不是提供一套唯一正确的“AI 编程流程”，而是留出一个小而透明的底座。先把 AGENTS.md、Git 检查和测试流程用好，再按自己的习惯加扩展，往往是最省心的路线。

参考资料