pi 是一个极简的终端编码助手(terminal coding harness),由 Mario Zechner(badlogicgames)开发并开源。官方描述只有一句话:“A minimal terminal coding harness."——轻量、可扩展、不做预设。本文来自公众号「代码猎奇站」的入门教程。相关实操参见 Pi agent 接入 DeepSeek Responses API。

pi 是什么

与 Cursor、Copilot、Windsurf 等 IDE 内嵌助手不同,pi 不是插件、不是 IDE、不是"AI 编辑器”,而是运行在终端中的代理框架:只给 AI 四个核心工具(read / write / edit / bash),让模型直接操作文件系统完成开发任务。

  • 适用人群:终端重度用户、Vim/Neovim 用户、DevOps/SRE(脚本、CI/CD、代码审查)、全栈开发者、想学 AI 代理开发的人。
  • 适用场景:代码重构迁移、写测试与文档、代码审查与安全审计、脚手架搭建、CI/CD 集成、自动化运维。

核心理念:适应你,而不是反过来

设计哲学是 “adapt pi to your workflows, not the other way around”。

四个内置工具:read(读文件)、write(创建/覆盖文件)、edit(基于文本替换的精确编辑)、bash(执行命令)。没有 MCP、子代理、权限弹窗、计划模式、待办事项——理由:

其他工具的做法 pi 的做法 原因
内置 MCP 支持 写 CLI 工具 + README(Skill),或写扩展 MCP 是临时方案,生态不够成熟
内置子代理 用 tmux 起多个 pi 实例,或用扩展实现 子代理实现因人而异,不替你做选择
弹窗询问权限 在容器中运行,或用扩展实现确认流 安全策略由你的环境决定,不是工具
内置计划模式 把计划写到文件,或用扩展实现 计划模式对你真有帮助吗?试试写文件
内置待办任务 用 TODO.md,或用扩展实现 待办事项会混淆模型,不如写在文件里

四大定制支柱:

支柱 说明 复杂度
Skill(技能) 遵循 Agent Skills 标准的 Markdown 指令文件,告诉 AI 怎么做特定任务 ⭐
Prompt Template 可复用提示片段,用 /name 调用 ⭐
Theme(主题) JSON 颜色方案,可热重载 ⭐⭐
Extension(扩展) TypeScript 模块,注册自定义工具、命令、事件监听和 UI 组件 ⭐⭐⭐

快速上手

安装(二选一):

npm install -g @earendil-works/pi-coding-agent
# 或
curl -fsSL https://pi.dev/install.sh | sh
pi --version

第一次对话:设置 API Key(如 export ANTHROPIC_API_KEY=xxx)后直接 pi 进入交互模式,输入需求即可,pi 会自动调用 bash/read 等工具并展示每一步。

选择模型:

  • 订阅制:pi/login,OAuth 登录 Anthropic Claude / OpenAI ChatGPT / GitHub Copilot,用订阅配额。
  • API Key 方式:设置环境变量(ANTHROPIC_API_KEY / OPENAI_API_KEY / DEEPSEEK_API_KEY 等),支持 Anthropic / OpenAI / DeepSeek / Gemini / Mistral / Groq / Cerebras / xAI / OpenRouter,国内还有 Kimi for Coding / MiniMax / 小米 MiMo / ZAI。
  • 本地:通过 models.json 配置 Ollama / vLLM / LM Studio。

运行模式一览

模式 命令 用途
交互模式 pi(默认) 日常开发,对话式交互
打印模式 pi -p "问题" 单次请求,输出后退出,适合脚本/Git hooks
JSON 模式 pi --mode json "问题" 事件流输出,用于工具集成
RPC 模式 pi --mode rpc 子进程集成协议
SDK 模式 在代码中调用 SDK 嵌入到你的应用

第一个实操:在项目目录启动 pi,输入"把我的 utils.js 迁移到 TypeScript,添加类型注解",pi 会 read 读取 → bash 检查 tsconfig → write 创建 utils.ts → edit 修复导入路径;一键完成用 pi -p "..."。

终端界面拆解

启动头(快捷键提示、已加载的 AGENTS.md、Skills/Extensions 数量,/hotkeys 查看全部)、消息区(对话历史 + 思考块 + 可折叠工具输出)、编辑器(输入框,边界颜色表示思考层级:灰=off,蓝系=minimal/low/medium,红系=high/xhigh/max)、底部栏(工作目录、会话名、Token 用量 ↑输入/↓输出/R缓存读/W缓存写、缓存命中率 CH、费用、上下文进度条、当前模型、思考层级)。

编辑器技巧

  • @ 文件引用:输入 @ 触发文件模糊搜索,如"帮我看看 @src/utils 这个文件"。
  • ! 与 !! 嵌入 bash:!git status 执行命令并把结果发给 AI;!!ls -la src/ 只执行不发给 AI(不污染上下文)。
  • 粘贴图片/拖拽文件:Ctrl+V(Windows Alt+V)或拖拽,AI 可看图(截图、设计稿、手绘图)。
  • Ctrl+G 外部编辑器:settings.json 设 {"externalEditor": "code --wait"} 后,Ctrl+G 用 VS Code 编辑临时文件;优先级 externalEditor → $VISUAL → $EDITOR → nano/Notepad。
  • Shift+Enter 多行输入(Enter 发送)。

常用快捷键备忘

  • 发送/取消:Enter 发送(steer 队列);Alt+Enter 队列消息(follow-up);Escape 取消;Esc 两次打开 /tree;Ctrl+C 清空编辑器;Ctrl+D 退出。
  • 显示控制:Ctrl+O 折叠/展开工具输出;Ctrl+T 折叠/展开思考块。
  • 模型与思考层级:Ctrl+L 模型选择器;Ctrl+P / Shift+Ctrl+P 切换下一个/上一个模型;Shift+Tab 循环思考层级。
  • 编辑器:Ctrl+G 外部编辑器;Shift+Enter 换行;Ctrl+U/K 删到行首/行尾;Ctrl+W 删前一个词;Ctrl+Y 粘贴最近删除;Alt+Y 浏览删除历史;Alt+←/→ 按词移动光标。
  • 会话:Ctrl+R(重命名)、Ctrl+D(删除),均在 resume 界面中。

消息队列

不需要等 AI 回复完就能输入下一条指令:

  • Enter = Steer(引导):在当前 AI 本轮工具调用完成后立即插入(如"注意不要改变公共 API 签名")。
  • Alt+Enter = Follow-Up(跟进):等 AI 完全处理完所有工作后再插入(如"顺便加个单元测试")。

settings.json 可配置 "steeringMode": "one-at-a-time" / "followUpMode": "one-at-a-time"(或 "all" 一次性发出全部)。Alt+Up 把排队消息撤回编辑器修改;Escape 中止操作并恢复所有排队消息。

常用内置命令(/ 命令)

  • 日常:/model 切换模型、/settings 设置界面、/session 会话信息、/name <名称>、/trust 保存项目信任决策、/reload 热重载、/hotkeys、/changelog、/quit。
  • 认证:/login(OAuth)、/logout。
  • 会话管理:/resume、/new、/tree、/fork、/clone、/compact [指令] 手动压缩上下文、/export [文件] 导出 HTML/JSONL、/import <文件>、/share 上传私有 Gist 生成分享链接、/copy 复制上一条 AI 回复。

原文:从 pi 开始掌握你的 Agent:入门与日常使用(公众号「代码猎奇站」)