Pi 小白入门教程

一句话：Pi 是一个运行在终端里的 AI 智能体——你在终端里启动它，直接跟它说人话，它就能帮你读写文件、执行命令、完成实际任务。

它和普通聊天机器人有什么区别？

聊天机器人只负责「说」。Pi 会「做」——它默认拥有四个基础能力：

• 读文件（read）——翻看你电脑里的任何文本、图片
• 写文件（write）——创建新文件
• 改文件（edit）——精确修改已有内容
• 跑命令（bash）——在终端里执行命令，比如装软件、跑脚本

它拿到你的任务后，会自己决定「先读什么、再改什么、最后跑什么验证」，像真人程序员一样一步步干完。

核心设计理念

Pi 刻意做得很小、很克制，把选择权交给你：

• 默认不带子代理、不带计划模式——需要的话自己装或让 Pi 给你写一个
• 没有权限弹窗——在容器里跑，或自己加确认流程
• 强扩展性——技能（Skills）、提示词模板、主题、TypeScript 扩展、可分享的 Pi 包
• 四种运行模式——交互式、一次性打印、JSON 输出、RPC 进程对接，甚至可作为 SDK 嵌入你自己的应用

第 1 步：安装（Windows 和 Linux 通用）

Pi 用 npm 分发，前提是电脑上有 Node.js（推荐 18+）。确认后执行：

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

没有 Node.js 的话，Linux/macOS 也可以用官方安装脚本：

$ curl -fsSL https://pi.dev/install.sh | sh

第 2 步：配置模型

Pi 支持订阅（Claude、ChatGPT、Copilot）和 API Key 两种方式，几十家供应商可选。最简单的方式是启动后输入 /login 交互式登录：

$ pi
/> /login    # 选择供应商 → 授权或填 Key

也可以直接设置环境变量（以 Anthropic 为例）：

$ export ANTHROPIC_API_KEY=sk-...
$ pi

第 3 步：第一次对话

启动后直接说人话就行。试试这些：

/> 帮我看看当前文件夹里有什么
/> 把这份笔记整理成 markdown 文件
/> 写一个脚本，批量重命名这些图片

第一次进入某个文件夹，Pi 可能询问是否信任该项目——选择信任后，它才能读取项目内的配置和扩展。

输入框里的小技巧

• @ 引用文件——输入 @ 模糊搜索项目里的文件，直接拖进对话上下文
• Tab 补全路径——打路径时按 Tab 自动补全
• Shift+Enter 换行——写多行指令用
• Ctrl+V 粘贴图片——可以直接把截图贴给 Pi 看（Windows 用 Alt+V）
• ! 前缀跑命令——!df -h 执行并把输出发给模型；!!df -h 只执行不发送
• Ctrl+G 外部编辑器——打开 nano/vim/记事本写长文本

最常用的快捷键

常用命令（输入 / 触发）

非交互用法（脚本友好）

$ pi -p "总结一下这个代码库"          # 打印结果后退出
$ cat README.md | pi -p "摘要这段文字"   # 管道输入
$ pi @文件.ts "帮我审查这个文件"          # 携带文件启动
$ pi --mode json "..."                 # 输出 JSON 事件流
$ pi --mode rpc                        # RPC 模式，对接外部程序

Pi 的每一次对话都自动保存为会话文件（JSONL 格式），存放在 ~/.pi/agent/sessions/，按工作目录分门别类。这意味着：

随时回来继续

• pi -c —— 继续最近的会话
• pi -r —— 浏览并选择历史会话
• /resume —— 在交互界面里挑
• --name "任务名" —— 启动时给会话起名，方便以后找

分支：一条对话，多线剧情

Pi 的会话是树状结构。你可以在 /tree 里跳到任意一个历史节点，从那里「另起炉灶」，原来的路径原样保留，互不覆盖——适合「这个方案先试 A 路，再回退试 B 路」的场景。

上下文压缩

模型有上下文窗口限制。Pi 默认开启自动压缩：上下文快满时，它会把较早的消息总结掉，保住最近的内容。你也可以手动 /compact，甚至带上自定义指令告诉它怎么总结。完整历史始终保留在会话文件里，随时 /tree 回去看。

导出与分享

/> /export 会话.html   # 导出为 HTML 或 JSONL
/> /share              # 作为私有 GitHub Gist 生成分享链接

Pi 最核心的哲学是「让它适应你的工作流，而不是你去适应它」。四种官方扩展方式：

① 技能 Skills（最常用）

按需加载的能力包，遵循通用的 Agent Skills 标准。每个技能就是一个文件夹，里面有一份 SKILL.md 说明触发条件和使用步骤。放在 ~/.pi/agent/skills/（全局）或项目的 .pi/skills/（仅该项目）。写任务时模型会自动调用，也可以手动 /skill:技能名。

例如：装一个「公文排版」技能后，你丢一段纯文字给它，它就能自动生成符合国标的 .docx 文件。

② 提示词模板 Prompts

把常用指令存成 Markdown 文件放在 ~/.pi/agent/prompts/，输入 /模板名 一键展开。支持 {{变量}} 占位符。

③ 主题 Themes 与设置

主题放 ~/.pi/agent/themes/，改完立即热生效。全局设置在 ~/.pi/agent/settings.json，项目级在 .pi/settings.json，后者覆盖前者。

④ 扩展 Extensions 与 Pi 包

TypeScript 编写的扩展可以注册自定义工具、命令、快捷键、事件处理甚至整个界面组件——子代理、计划模式、权限确认、自动 git 提交……官方刻意不做的东西，全靠扩展补。扩展可以打包成 Pi 包通过 npm 或 Git 分发：

$ pi install npm:@某用户/某包      # 装包
$ pi install git:github.com/用户/仓库
$ pi list                            # 查看已装
$ pi update --all                    # 全部更新

语境文件 AGENTS.md

Pi 启动时会自动读取 AGENTS.md（或 CLAUDE.md）：全局的 ~/.pi/agent/AGENTS.md 加上从当前目录向上逐级找到的所有 AGENTS.md。这里写项目约定、常用命令、注意事项，模型每轮都会看到。

先说结论：Pi 的内核和功能在两大平台上完全一致，差别全在「环境」。Linux 是它的原生主场，开箱即用；Windows 需要先备好一套 bash 环境，装好后体验基本无差。

# 1. 装 Git for Windows（自带 Git Bash）
#    https://git-scm.com/download/win
# 2. 装 Node.js（官网 LTS 版即可）
# 3. 打开 Windows Terminal 设置 (Ctrl+Shift+,) 的 settings.json，
#    加入以下两条，把 Shift+Enter / Alt+Enter 转发给 Pi：
{
  "actions": [
    { "command": { "action": "sendInput", "input": "\u001b[13;2u" }, "keys": "shift+enter" },
    { "command": { "action": "sendInput", "input": "\u001b[13;3u" }, "keys": "alt+enter" }
  ]
}
# 改完完全关闭并重开 Windows Terminal，再启动 pi

# 支持 Kitty 键盘协议的终端，Shift+Enter 等快捷键零配置可用：
$ sudo apt install kitty      # 或 wezterm / ghostty / alacritty
$ tmux new -s pi            # 远程会话建议挂 tmux，断线不丢