Pi 是近期热度极高的终端 AI Coding Agent（由 Mario Zechner / badlogic 主导开发）。它以“大道至简”为核心理念：默认只有 4 个基础工具（Read 读文件、Write 写文件、Edit 改文件、Bash 运行命令），系统提示词仅约 1000 Token。在 Pi 中随便打个招呼上传 Token 约 1100（占用上下文约 0.4%），而 Codex 同类操作可能占用约 18000 Token（约 7% 上下文）。极致精简带来更高效率：Composio 等基准测试显示，Pi 完成编程任务速度比主流 Coding Agent 快 1.5–2 倍，成本更低；Databricks 在百万行代码仓库的测试中，Pi + Claude Opus 等组合在同等成本下任务通过率（代码质量）常优于 Claude Code 和 Codex。

Pi 没有 MCP、SubAgent、Plan Mode、Todo、btw 等内置复杂功能（可通过插件扩展），设计哲学是“让工具适应你的工作流，而不是让你适应工具”。核心越小越干净，模型发挥越好，用户自由度最大。

1. 基础安装

Windows：

  • 右键桌面 → 在终端中打开（PowerShell）。
  • 访问 Pi 官网，复制一键安装命令并执行：
    1
    powershell -c "irm https://pi.dev/install.ps1 | iex"
  • 按提示输入 y 安装 Node.js（如未安装）、Pi 本体。
  • 若无 Git，建议输入 w 让 Pi 帮装 Git for Windows（Pi 用 Git Bash 作为命令环境）。
  • 关闭当前窗口，重新打开终端，输入 pi。出现对话界面即安装成功。

macOS / Linux：

  • 打开终端，执行：
    1
    curl -fsSL https://pi.dev/install.sh | sh
  • 安装完成后输入 pi 验证。

也可使用 npm 全局安装（推荐加 --ignore-scripts）：

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

2. 配置模型

启动 Pi 后输入 /login。

  • API Key 方式：支持 40+ 供应商。以 DeepSeek 为例：输入关键词筛选 → 回车 → 去官网创建 API Key → 粘贴到 Pi。完成后可打招呼测试。用 /model 或 Ctrl+L（Mac 同）切换模型；Shift+Tab 切换思考强度。
  • 订阅账号方式：选择 “Sign in with account” → 选 OpenAI Codex 等 → 浏览器登录。登录后模型列表会出现对应模型。

支持 Anthropic、OpenAI、DeepSeek、Kimi、MiniMax、小米 MiMo 等，同一会话可无缝切换模型且保留上下文。

3. 基础使用

在项目文件夹右键打开终端，输入 pi。窗口会显示当前项目路径，后续代码写在此处。

  • 多行输入：Shift+Enter 换行；或 Ctrl+G 打开记事本编辑提示词，保存后自动同步。
  • 底部状态栏：上箭头=输入 Token、下箭头=输出 Token、R=Cache Read、CH=最近一次缓存命中率、成本估算（订阅显示 sub）、上下文占用百分比 / 总窗口大小、auto（自动压缩）、模型名与思考强度。
  • 临时运行命令：!npm run dev（AI 可见结果）；!!命令（AI 不可见）。
  • 图片交互：截图后 Alt+V（Windows）或 Ctrl+V（Mac）粘贴，描述修改需求。
  • 引用文件：输入 @ 选择文件/目录，再继续对话。
  • 指令追加（核心机制）：
    • Steering（默认，回车）：实时引导，打断当前执行方向（像打方向盘）。
    • Follow-up（Windows Alt+Enter，Mac Option+Enter）：排队，等当前轮次完成后执行。冲突时先在 PowerShell 设置里删除 Alt+Enter 全屏快捷键。
    • 原理：Pi 核心是双层循环。内层循环处理模型+工具调用，Steering 消息注入内层；Follow-up 在外层，等内层完成后再处理。
  • 非交互模式：pi -p "指令"，后台静默执行，适合当 CLI 工具用。

示例：用 React 做宠物洗护网页 → 截图反馈 → @ 文件要求拆模块 → Steering 改用 Next.js + SQLite 等。

4. 会话管理（Session 与对话树）

Session = 一次连续对话历史。

  • /new：新 Session（清空上下文，推荐任务完成后使用，效果优于压缩）。
  • pi -c：继续最近 Session；pi -r：选择历史 Session。
  • 对话树（特色）：/tree 查看/回退节点，可基于历史节点创建分支（尝试不同方向）。注意：只能回退对话历史，不能自动回退代码（需配合 Git：!git reset --hard <commit>）。
    • 回退选项：不总结（彻底抛弃）、总结（AI 总结被丢弃分支）、自定义总结方式。只总结当前分支。
  • 其他命令：
    • /clone：完整复制当前 Session。
    • /fork：基于某个节点 fork 新 Session（只带之前历史）。
    • /compact：手动触发上下文压缩（总结精简历史，降低占用和干扰）。经验：清空（/new）通常优于压缩。

5. 插件扩展

默认只有 4 个工具 + Skills。插件可扩展联网、SubAgent、MCP、btw、Plan Mode、Goal、Dynamic Workflows、微信等。

安装（官网 packages 列表复制命令）：

  • 全局：直接执行安装命令。
  • 项目级：命令后加 -l（local），装到项目 .pi 目录。
  • 卸载：把 install 改成 uninstall。

常见插件示例：

  • pi-web-access：联网搜索（零配置，用 Exa）。
  • pi-subagents：并行子代理（如同时生成 5 种风格网页）。
  • pi-mcp-adapter：支持 MCP（在项目建 .mcp.json 配置 Server，如高德地图）。
  • btw：旁路对话（/btw 问题，不打断主任务）。
  • Plan Mode：/plan-mode 先出计划（写到 PLAN.md），确认后再执行。
  • Goal：/goal 目标，多轮迭代直到完成。
  • Dynamic Workflows：复杂任务自动调度多 Agent。
  • 微信：/wechat login 扫码，/wechat start 连接手机。

首次加载含插件/Skill 的目录会询问是否信任。

6. Skills

遵循标准 Skills 协议。放在：

  • 项目：.agents/skills/（或类似路径）
  • 全局：~/.agents/skills/（Windows 对应用户目录）

示例：Playwright CLI（浏览器自动化）——先装工具本体，再复制 SKILL.md 文件夹。SkillHub 可搜索更多（如 Markdown Converter，可用提示词让 Pi 自己装）。

Pi 会自动识别并按需加载。

7. Pi Web（网页 UI）

社区高星项目（如“第四种黑猩猩”版，约 4200 stars）：

  • 执行 npx 一键命令，自动打开网页。
  • 支持切换项目、文件浏览器、模型配置、技能/插件开关、斜线命令、@ 文件、粘贴截图、Token 统计等。
  • 关闭后用命令重新启动。

掌握 TUI 后，Web UI 上手很快。

8. 记忆系统（跨 Session）

  • 项目级 AGENTS.md（根目录）：每次对话自动加载为上下文。可让 Pi 通读项目后自己生成。
  • 全局 AGENTS.md（~/.pi/agent/ 或 Windows C:\Users\你的用户名\.pi\agent\）：对所有项目生效。建议加安全规则（如禁止批量删除，只允许单文件明确删除）。
  • APPEND_SYSTEM.md（同全局目录）：直接追加到系统提示词，优先级更高。

复杂项目强烈建议维护 AGENTS.md。

9. 安全约束

Pi 安全机制极简：仅陌生目录加载插件/Skill 时询问信任。运行后无沙箱、无权限确认（自动执行所有操作），这是有意设计（保持极简高效）。

推荐方案：

  • 在 WSL、Hyper-V、Docker 等容器/虚拟机中运行（坏了重建即可，不影响宿主机）。Pi 轻量，极适合容器化/批量部署。
  • 或装 pi-permission-system 等插件增加审批（会降低效率）。

10. 自己写插件（DIY）

Pi 开放大量接口（模型、工具、会话、UI 等），社区插件都基于此。Pi 自己就能写插件！

示例：

  1. 让 Pi 写一个根据 IP 查坐标再查天气并显示在窗口顶部的插件 → 放到项目 .pi/extensions/ → /reload。
  2. 禁止读写 .env 的保护插件。
  3. 执行 rm 前弹窗确认的插件。

项目级放 .pi/extensions/；全局复制到 ~/.pi/agent/ 对应位置。用 GPT 等模型一次通过率很高，只需清晰描述需求。

11. 架构与 SDK

源码在 GitHub（earendil-works/pi 或相关仓库）：

  • pi-ai：统一多厂商 LLM API。
  • agent：核心双层 Agent Loop。
  • coding-agent：4 个工具、系统提示、Skills、插件机制。
  • tui：终端界面。

已封装为 SDK：

  • 需要统一模型调用：npm install 后用 createModel。
  • 需要开箱 Agent：装 coding-agent SDK，创建 Session 即可开启任务。

源码是 Agent 设计的优秀参考教材。

总结与建议：Pi 的核心优势是精简、高效、可高度定制。先装好基础 → 配置模型 → 熟悉 Steering/Follow-up 与对话树 → 按需装插件/Skills → 用 AGENTS.md 管理记忆。安全上优先用容器。遇到问题可直接问 Pi 自身（它内置相关知识）。

官网：pi.dev
GitHub 搜索 earendil-works/pi 或 badlogic 相关仓库获取最新文档与插件列表。