玩转 Pi 编码助手：从入门到团队协作的全指南

嗨，朋友们！今天要聊聊最近在开发圈里掀起一阵小风暴的 Pi 编码助手。如果你和我一样，平时喜欢在终端里敲敲代码，又怕手里那把钥匙——API Key——一不小心泄露，那么 Pi 可能正是你想要的那把“安全小刀”。我会把这把刀的各个刀锋——从最基本的使用，到进阶的扩展、成本控制、团队协作，甚至给你一些实际的操作小技巧——一一呈现出来，保证你看完以后能把它装进自己的工作流里。

1️⃣ 为什么会有人爱上 Pi？

想象一下，你在厨房里做饭，手里只有一把菜刀和一块砧板。传统的 IDE 像是配备了完整厨房用具的高端厨房，功能多但经常让人眼花缭乱。而 Pi 则是那把刀——极简、精准、随时可以换刀片。它只提供四个最核心的工具：read（读文件）、write（写文件）、edit（编辑）和bash（执行命令），所有高级功能都可以通过自己写的插件或脚本来补足。核心思想就是让 AI 适配你的工作方式，而不是你强迫自己去适配 AI。

2️⃣ 快速上手：从第一次启动说起

先把 Pi 安装好——在终端里跑一行 npm install -g @mariozechner/pi-coding-agent，像装系统一样简单。装好后敲 pi 进交互式界面，就像打开了一个和 AI 聊天的聊天框。下面是几种常见的启动方式：

交互式：pi——直接进入对话。
非交互式：pi -p "帮我列出 src/ 里所有 .ts 文件"——一次性完成任务后自动退出，适合写脚本。
会话恢复：pi -c "上次聊到哪了"——随时接着上次的思路继续。

如果你是新手，一定要先把API Key放到环境变量里。比如想用 Claude，export ANTHROPIC_API_KEY=sk-xxxx 就能让 Pi 正常工作。

3️⃣ 让 AI 真正帮你写代码的两大诀窍

很多人会直接把“大问题”丢给 AI，比如“写一个用户登录的后端”。AI 会给你一大段代码，但往往缺少项目特有的约定（比如统一日志、错误码）。这里有两个小技巧，能让 AI 的输出更贴合你的项目：

先喂给 AI 项目上下文——把 AGENTS.md、PLAN.md、已有的实体类（@src/main/java/com/example/Entity.java）一起发给 Pi。这样 AI 能在自己的思考中引用这些信息。
分步提问——先让 AI 只生成接口，再让它补全 实现类，最后再让它写 单元测试。每一步都可以用 Enter（Steering）插入小指令，让 AI 在当前工具执行完后立刻改动方向。

这种像“做饭时先切好配料、再下锅”的方式，能大大降低出错概率。

4️⃣ 只读模式 VS 写模式——安全第一

在企业项目里，代码审查和安全扫描是必须的，哪怕是 AI 也不例外。Pi 提供了只读模式：pi --tools read,grep,find,ls -p "审查 src/ 目录代码质量"。打开这个模式后，AI 只能读取文件、搜索关键字，根本没有改动文件的权限，等于在厨房里只给了你一把刀，却没给你调料。

如果你想让 AI 真正修改代码，一定要在「写」之前打开 write 或 edit 工具。推荐的做法是：

先用 read 看代码，确认业务流程。
用 edit 做精准的「查找-替换」——比如把所有 System.out.println 改成日志框架。
如果是全新文件，使用 write 创建并一次性写入。

这样既能保证安全，又能在需要时快速交付。

5️⃣ 多模型切换：让 AI 各显神通

Pi 支持 20+ 大模型，常见的有：

Claude 系列（擅长理解复杂需求、写架构）
OpenAI GPT‑4o（码力强、响应快）
Google Gemini（文档生成、阅读图片）
本地 Ollama（离线场景）

通过 --model 或者 --models 参数，你可以一次性列出多个模型，让 Ctrl+P 在它们之间快速切换。实际操作中，我会把「简单重复性任务」交给轻量模型（比如 haiku），把「需要深度思考的设计」交给 sonnet:high，这样不但省钱还能提升效率。

6️⃣ 扩展 & Skill：把 Pi 打造成你的个人助理

Pi 的最大亮点是可以通过 Extension、Skill、Prompt Template、Theme 四大插件系统随意加功能。

Extension 用 TypeScript 编写，你可以在里面注册自定义工具（比如 git-checkpoint，每次写文件后自动 git commit），或者拦截工具调用做“权限门”。

示例代码（省略细节）大概是：

export default function (pi) {
  pi.on('tool_call', async (event, ctx) => {
    if(event.toolName === 'write') {
      // 自动 git add & commit
    }
  });
}

把它放在 .pi/extensions/ 目录下，重启 Pi 就能生效。

Skill 更像是“一套预设的指令”。比如把「写单元测试」封装成一个 skill，AI 在需要时自动加载。使用方法：

/skill:test-generator

配合 AGENTS.md 中的项目约定（比如统一使用 JUnit5、AssertJ），就能让 AI 自动生成符合团队规范的测试代码。

7️⃣ 成本控制小技巧

AI 费用是大家最关心的事，尤其是大模型。下面的几招可以帮你把每月的 token 费用压到 几块钱：

开启 Prompt Cache：只要系统提示不变，模型会直接缓存，省下大量 token。可以在 .pi/agent/settings.json 里把 PI_CACHE_RETENTION 设为 long。
使用 思考等级控制费用。--thinking off 直接关闭思考，适合简单的文件读取；--thinking high 用在复杂的设计讨论。
把「一次性大任务」拆成「多轮小任务」，每轮只让模型看到必要的上下文，避免一次性把整个项目的大文件全塞进去。
定期 /compact 会话，压缩旧的对话，防止 context overflow。

实际运营时，我会在每次 PR 检查前跑一次 pi --tools read,grep,find,ls -p "审查 src/"，只用轻量模型做代码审计，费用几乎可以忽略不计。

8️⃣ 团队协作：让每个人都能玩转 Pi

Pi 天然支持 多会话，每个功能模块可以独立一个会话文件，放在 ~/.pi/agent/sessions/。

团队推荐的工作流：

在项目根目录创建 .pi/ 目录，里面放 AGENTS.md、PLAN.md、自定义 settings.json。
把 AGENTS.md 写成项目的“约定手册”，包括技术栈、代码规范、命名规则。这样新同事只要打开 Pi，就能快速了解团队标准。
使用 pi list 查看已装的 Pi Packages，把常用的 extension（比如 git-checkpoint、permission gate）做成内部仓库，让大家 pi install npm:@myteam/pi-tools 一键同步。
在 CI 中加入非交互模式：pi -p "代码审查" --mode json，把审查结果保存为 JSON，CI 直接根据结果决定是否通过。

9️⃣ 常见坑 & 解决方案

下面列出几个新手最容易踩的坑，和对应的避免方法：

坑点	表现	解决办法
Context Overflow（上下文溢出）	AI 开始答非所问，输出变糊	使用 `/compact` 手动压缩，或定期开启新会话 `/new`
模型幻觉	AI 编造不存在的类或方法	让它先 `read` 相关文件，再再提问；适当调高 `--thinking high`
误删代码	使用 `edit` 时误把整段代码删掉	先在 `read` 中确认行号；开启 `--tools read,edit` 只读模式审查后再写
API Key 泄露	把 key 写进源码、提交到 Git	统一使用 `.env` 或系统环境变量；不要把 `auth.json` 加入代码仓库

🔚 结语：把 AI 当作钥匙，而不是钥匙孔

Pi 的魅力在于它把 AI 的强大能力」和「终端的灵活操作」完美结合。你不需要像使用大型 IDE 那样在 UI 里点点点，只要会写几行 Bash、会点 Ctrl+P，就能让 AI 像一个随叫随到的编程小伙伴。
如果你已经在用 VS Code 的 Copilot，却发现它有时候像是“先把所有的调料倒进锅里”，那不妨试试 Pi——把调料（模型）放在抽屉里，真正需要时再拿出来。

祝大家玩转 Pi，写出更乾净、更安全、更高效的代码！如果有任何使用中的疑问，欢迎在评论里聊聊，咱们一起把「终端 AI」这件事玩出花样。