【pi】-----极简是一种力量

Pi（Pi Coding Agent）学习笔记

本文基于当前文件夹下的全部资料整理：

39 张 B 站视频截图（技术爬爬虾《Pi 大道至简》教程分 P 截图）

1 张长图《AI Agent 完全指南 · PAI》（CuteNote 笔记，1789459153520.png）

官方站点 https://pi.dev/ 与官方安全文档校验

教程同源图文版：https://www.cnblogs.com/tech-shrimp/p/22508506

视频地址：https://www.bilibili.com/video/BV139bD6gEa8

仓库：https://github.com/earendil-works/pi ｜ npm：@earendil-works/pi-coding-agent ｜ MIT License

[Pi 是什么：大道至简](#Pi 是什么：大道至简)
安装
模型配置
基础操作
[指令追加：Steering 与 Follow-up](#指令追加：Steering 与 Follow-up)
[Agent Loop 双层循环架构](#Agent Loop 双层循环架构)
非交互模式（-p）
会话管理
[对话树 /tree（Pi 的特色功能）](#对话树 /tree（Pi 的特色功能）)
[会话克隆与分叉 /clone 与 /fork](#会话克隆与分叉 /clone 与 /fork)
[上下文压缩 /compact](#上下文压缩 /compact)
核心工具与设计哲学
[插件生态（Extensions / Packages）](#插件生态（Extensions / Packages）)
[Agent Skills 技能系统](#Agent Skills 技能系统)
[Web UI 网页版界面](#Web UI 网页版界面)
[跨 Session 记忆：AGENTS.md](#跨 Session 记忆：AGENTS.md)
[全局配置目录 ~/.pi/agent 全解析](#全局配置目录 ~/.pi/agent 全解析)
安全机制
[自己动手 DIY 插件](#自己动手 DIY 插件)
开放接口（API）速查
[源码架构与 SDK 集成](#源码架构与 SDK 集成)
[命令 / 快捷键 / 目录速查表](#命令 / 快捷键 / 目录速查表)
图片来源索引
行动建议

1. Pi 是什么：大道至简

Pi 是一个极简的 Agent Harness（智能体外壳 / 编程 Agent）。官方首页的一句话概括了它的全部立场：

"There are many agent harnesses, but this one is yours."

"Adapt Pi to your workflows, not the other way around."

（让工具来适应你的工作流，而不是让你去适应工具。）

1.1 核心数据（来自长图与视频）

指标	数值	说明
基础工具数量	4 个	Read / Write / Edit / Bash
系统提示词	约 1000 Token	极简系统提示词是 Pi 的设计核心
一句"你好"的上下文占比	约 4‰（0.4%）	上传 Token 约 1100
对比：Codex 一句"你好"	约 18000 Token（约 7%）	什么都没做就白烧掉 7% 上下文窗口
编程速度	1.5 ~ 2× 提升	依据 Composio 基准测试
代码质量	同成本下通过率最高点	Databricks 百万行代码仓库基准测试

Databricks 基准测试读法 ：横轴是任务成本 ，纵轴是任务通过率（代码质量） 。红线代表"同等成本下任务成功率最高的 Agent + 模型组合"。Pi 在大部分场景下表现优于 Claude Code 和 Codex；而整张图代码质量的最高点，是 Pi + Claude Opus 4.8 的组合。

1.2 核心设计哲学

核心越小越干净，模型发挥越好，用户自由度最大。

Pi 刻意不做的功能（"What we didn't build"）------这些恰好是别的 Agent 的卖点：

Pi 没有	官方给你的替代方案
MCP	用带 README 的 CLI 工具（见 Skills），或写一个 extension 加 MCP 支持
Sub-agents（子代理）	用 tmux 拉起多个 Pi 实例，或自己写 extension，或装现成包
权限弹窗	跑在容器里，或用 extension 自建确认流程
Plan Mode（计划模式）	把计划写进文件，或用 extension / 装包
内置 Todo	用 `TODO.md` 文件，或自己写 extension
后台 bash	用 tmux，换来完整的可观测性与直接交互

Pi 的定位是 "Primitives, not features"（提供原语，而非成品功能）------把决定权交回用户。

2. 安装

Pi 安装不需要任何准备工作（Node.js / Git 缺失时安装脚本会引导补装）。

2.1 Windows

在桌面或目标文件夹 右键 → 在终端中打开，进入 Windows PowerShell。
打开 Pi 官网，复制 PowerShell 一键安装命令：

powershell 复制代码

powershell -c "irm https://pi.dev/install.ps1 | iex"

若电脑没装 Node.js ，输入 y 回车自动安装。
下一步继续输入 y 回车，安装 Pi 本体。
Pi 使用 git bash 作为命令行运行环境；若没装过 Git，会先询问，建议输入 w 让 Pi 自动装好 Git。
关闭当前命令行窗口 ，重新右键打开终端，输入 pi 启动。

2.2 macOS / Linux

打开终端，执行官网提供的 curl 命令：

bash 复制代码

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

官网还提供 npm / pnpm / bun 等安装方式的标签页可切换。

2.3 验证安装

能正常显示出对话窗口（TUI）即安装成功。

3. 模型配置

启动 Pi 后输入命令 /login，有两种接入方式。

3.1 方式一：API Key

输入 /login，选择 API Key 方式。
输入关键词筛选供应商（支持 40+ 家模型供应商）。
去对应厂商官网创建 API Key（如 DeepSeek：API 开放平台 → API keys → 创建），复制粘贴到 Pi 中回车。
发一句问候，有回复即配置完成。

text 复制代码

/login          # 进入登录/配置流程

3.2 方式二：模型订阅

输入 /login，选择 Sign in with account。
以 OpenAI 订阅为例：选择 OpenAI Codex → 选择浏览器登录 → 浏览器完成登录。
回到 Pi，敲 Ctrl + L 调出模型列表，即可看到 ChatGPT 系列模型。

3.3 支持的供应商（官方列举 15+，教程提到 40+）

Anthropic、OpenAI、Google、Azure、Bedrock、Mistral、Groq、Cerebras、xAI、Hugging Face、Kimi For Coding、MiniMax、NVIDIA、OpenRouter、Ollama 等。可通过 API Key 或 OAuth 认证。

3.4 常用模型操作

操作	方式
切换模型	`/model`
切换模型的思考强度	`Shift + Tab`（Windows / Mac 相同）
快速打开模型选择器	`Ctrl + L`
在收藏的模型间循环	`Ctrl + P`
添加自定义 provider / model	`models.json` 或写 extension

思考强度 （截图右下角显示的 high 等）用于按任务复杂度选择推理深度：简单任务调低更省更省时，复杂任务调高更稳。

3.5 状态栏信息解读（TUI 底部一行）

以截图中的 ↑8.8k ↓355 R6.1k CH80.3% $0.002 (sub) 0.7%/272k (auto) ... (openai-codex) gpt-5.6-luna • high 为例：

字段	含义
`↑ 8.8k`	整个 Session 的输入 Token
`↓ 355`	输出 Token
`R 6.1k`	Cache Read：整个 Session 有多少 Token 命中缓存
`CH 80.3%`	Cache Hit Rate ：注意统计的是最近一次 AI 调用请求的缓存命中率，不是整个 Session
`$0.002`	本次对话预估成本
`(sub)`	subscription，表示当前用的是订阅，故前面的成本仅供参考
`0.7%/272k`	占用模型上下文窗口的比例 / 模型总上下文窗口（如 GPT-5.6 为 272k）
`(auto)`	上下文压缩机制为自动压缩
`(openai-codex) gpt-5.6-luna`	供应商 + 当前模型名
`• high`	当前模型的思考强度

4. 基础操作

4.1 创建项目

新建一个文件夹 → 在该文件夹内右键在终端打开 → 输入 pi 启动。当前目录即项目目录，Pi 后续写的代码都会落在这里。

4.2 输入指令与换行

需求	操作
发送	`Enter`
换行	`Shift + Enter`（Mac 相同）
打开记事本编辑器写长提示词	`Ctrl + G`（Mac 相同），编辑后保存并关闭，内容自动同步回输入框

4.3 快速运行命令

写法	行为
`!` + 命令	在当前对话窗口临时运行命令；运行过程与结果 AI 可见
`!!` + 命令	运行命令但 AI 看不到

text 复制代码

!npm run dev      # 启动开发服务器，AI 能看到输出
!!git log         # 跑一条命令但不给 AI 看

教程用它启动 Vite 开发服务器（npm run dev，端口 5173 → 5174），也用它执行 git reset --hard <commit> 回滚代码。

4.4 用图片沟通

系统	快捷键
Windows	`Alt + V` 粘贴剪贴板图片
macOS	`Control + V` 粘贴剪贴板图片

典型用法：网页 UI 某一处不满意 → 截图 → 粘贴到 Pi → 用自然语言描述问题（例："浮动卡片的数量太少了"）→ Pi 读图后修改。

4.5 用 @ 引用文件

输入 @ 即可选择代码文件（支持逐级选择，如 src → / → main），然后让 AI 针对该文件操作。例："不要把代码都放到一个文件里面，把它拆分成模块"。

4.6 首次启动的信任询问

如果目录下有项目级插件 / Skill，第一次启动会询问是否信任当前目录------选择信任，插件才会加载。这也就是 Pi 唯一的"安全机制"（详见第 18 节）。

5. 指令追加：Steering 与 Follow-up

这是 Pi 最经典、最常用的两种"边跑边补话"的方式。在 AI 执行过程中直接输入新指令，不需要打断它。

方式	中文	行为	快捷键
Steering	引导	默认方式。立即干预方向，相当于"打方向盘"，AI 立刻改变执行路径	`Enter`
Follow-up	排队	不影响当前工作，排队等 AI 完成当前这一轮后才看到并执行	`Alt + Enter`（Mac：`Option + Enter`）

5.1 Steering（引导）

追加的指令前面会标注 Steering。
发送后 AI 立即改变执行方向：例如 AI 想用 Express 做后端，你说"我需要 Next.js 框架，数据库用 SQLite"，AI 立刻停止 Express 方向，改为安装 Next.js 相关依赖。
官方描述：Enter 发送 steering 消息，在当前工具执行完后投递 ，并中断剩余工具调用。

5.2 Follow-up（排队）

追加的指令前面会标注 Follow-up，进入队列。
必须等 AI 把这一轮工作全部做完，才会读取并执行。
Windows 需要先改一个配置 ：
1. 右键打开 PowerShell 设置；
2. 在"操作"里找到 Alt + Enter（让 PowerShell 全屏化的默认快捷键）；
3. 删除该快捷键（它与 Pi 的 Follow-up 快捷键冲突）；
4. 右下角保存。
Mac 无需改配置 ，直接用 Option + Enter。
取回排队中的指令 ：Alt + ↑（上箭头）可以把排队中的消息拿回来重新编辑，改完再 Alt + Enter 送回队列。

6. Agent Loop 双层循环架构

Pi 的核心 Agent Loop 是双层循环，这正是 Steering / Follow-up 能工作的原因。

6.1 流程图（对应截图《Pi Agent Loop 架构图》）

text 复制代码

┌─ 外层循环: while true ────────────────────────────────────────┐
│                                                               │
│   有 follow-up 消息? ──否──► 退出                             │
│        │ 是                                                   │
│   设置为 pending                                              │
│        │                                                      │
│   ┌─ 内层循环 ────────────────────────────────┐               │
│   │                                            │              │
│   │   注入 steering 消息                       │              │
│   │        │                                   │              │
│   │   调用 LLM                                  │              │
│   │        │                                   │              │
│   │   提取 tool calls                          │              │
│   │        │                                   │              │
│   │   执行工具                                  │              │
│   │        │                                   │              │
│   │   结果推入上下文                            │              │
│   │        │                                   │              │
│   │   shouldStop? ──否──► (回到"注入 steering") │              │
│   │        │ 是                                │              │
│   │   有 steering 消息? ──是──► (回到"注入")    │              │
│   │        │ 否                                │              │
│   └────────┴────────────────────────────────────┘              │
│        │                                                      │
│   检查 follow-up ────────────────────────────────────────────┘
└───────────────────────────────────────────────────────────────┘

6.2 流程讲解（截图原图文字）

外层循环负责持续检查是否还有 follow-up 任务。
有新消息时先标记为 pending，再进入内层处理。
内层循环先注入 steering 消息，再调用 LLM 做决策。
LLM 输出中的 tool calls 会被解析并执行。
工具执行结果会回填到上下文，供后续推理继续使用。
shouldStop 用于判断本轮是否结束；若结束则检查 follow-up。

6.3 关键要点

Steering 消息在内层循环每轮注入 → 所以能"实时响应"。
Follow-up 消息在外层循环读取 → 所以必须等内层全部处理完毕。
内层结束且还有 steering 消息时，不退出，继续内层；都没有了，才回到外层检查 follow-up。
这个设计的巧妙之处：用户随时能插话，而 AI 不必被打断重来。

7. 非交互模式（-p）

除了常规交互式 TUI，Pi 还提供一次性非交互模式，非常适合把 Pi 当成一条 CLI 命令使用。

powershell 复制代码

pi -p "查找今天的天气，然后在桌面写一个 天气.txt 文件"

Pi 会在后台静默执行，中间过程看不到，执行完输出结果。
生成的文件（如桌面的 天气.txt）会正常落盘。
适合脚本化、批处理、CI 场景。

官方给出的四种模式：

模式	用途
Interactive	完整的 TUI 体验（默认）
Print / JSON	`pi -p "query"` 用于脚本；`--mode json` 输出事件流
RPC	stdin/stdout 上的 JSON 协议，供非 Node 集成
SDK	把 Pi 嵌入到自己的应用中

8. 会话管理

8.1 Session 概念

Session = 一段连续的对话记录，记录了 AI 多轮对话的整个工作过程。

示例（教程演示）：

text 复制代码

Session1（水果）:  新增苹果 → 新增香蕉 → 新增橘子
Session2（蔬菜）:  新增茄子 → 新增芹菜 → 新增白菜

这样就拥有了两份独立的对话历史 。新开 Session 后，AI 没有过去的对话历史，上下文窗口被清空。

8.2 三个核心命令

命令	作用
`/new`	新开一个 Session（清空上下文，推荐在每轮任务结束后使用）
`pi -c`	Continue ：从最近一次 Session 继续对话
`pi -r`	Resume ：列出并挑选一个 Session 继续

pi -r 的选择界面（截图）：

text 复制代码

Resume Session (Current Folder)            ● Current Folder | ○ All   Name: All  Sort: Threaded
tab scope · re:<pattern> regex · "phrase" exact
ctrl+s sort · ctrl+n named · ctrl+d delete · ctrl+p path (off)

> 在蔬菜列表新增茄子                                    19  7m
  在水果列表新增苹果                                    19  45m

支持 tab 切换范围（当前文件夹 / 全部） 、正则/短语搜索 、排序、命名、删除、显示路径。

退出 Pi：连按两次 Ctrl + C。

9. 对话树 /tree（Pi 的特色功能）

Pi 的每个 Session 不是纯线性的 ，而是树状结构------这是一个 Session 内部的分支能力。

9.1 进入与操作

text 复制代码

/tree      # Navigate session tree (switch branches)

进入后可以上下移动选中任意历史节点，回车选中，再回车确认。

Session Tree 界面（截图）的完整操作键：

按键	作用
`↑` / `↓`	移动（move）
`←` / `→`	翻页（page）
`ctrl+←/→`	切换分支（branch）
`ctrl+x`	复制（copy）
`shift+l`	打标签（label）
`shift+t`	标签时间（label time）
`ctrl+d` / `t` / `u` / `l` / `a`	过滤器（filter）
`ctrl+o` / `shift+ctrl+o`	循环（cycle）
直接输入	Type to search

界面示例（每条消息带类型标签）：

text 复制代码

Session Tree
• user: 在蔬菜列表新增茄子
• [bash: ls -la && find . -maxdepth 3 -type f | sort]
• [read: vegetables.txt]
• [read: fruits.txt]
• [write: vegetables.txt]
• assistant: 已在 `vegetables.txt` 中新增"茄子"。
▸ user: 新增芹菜
• [read: vegetables.txt]
• [edit: vegetables.txt]
• assistant: 已在 `vegetables.txt` 中新增"芹菜"。
• user: 新增白菜
• [edit: vegetables.txt]
• assistant: 已在 `vegetables.txt` 中新增"白菜"。
(7/13)

9.2 回退历史 + 创建分支

/tree 进入对话树，选中某个历史节点（如"新增芹菜"）→ 回车 → 再回车。
对话历史回退到该状态，可以基于这个状态创建分支做不同尝试。
例：回退后不再加蔬菜，改为让它"新增海鲜（皮皮虾）"。
再次 /tree 即可看到时间线产生了分支：一条继续加蔬菜，一条新增了海鲜。

图形化效果（截图）：茄子节点下分出"新增皮皮虾"和"新增芹菜 → 新增白菜"两条枝干。

9.3 回退时的三种总结选项

回退时 Pi 会给三个选项：

选项	行为
No summary	彻底回退，被丢弃的对话历史完全抛弃
Summarize	AI 对当前分支上被回退掉的这段历史做一次总结
Summarize with custom prompt	自定义总结提示词，告诉 AI 该怎么总结

重要细节 ：AI 总结时只总结这段分支上的工作，不会总结别的分支。例：从"白菜"回退到"茄子"并选择 summarize，只有被回退的那段分支会被总结，"皮皮虾"那条分支不会被总结。

展开总结内容：Ctrl + O。

9.4 ⚠️ 关键限制：只回退对话，不回退代码

用 /tree 回退时，只能回退对话历史，不能回退代码。

要连代码一起回滚，必须配合 git：

text 复制代码

# 1. 用 /tree 把对话历史回退到"新增茄子"节点
/tree → 选中"新增茄子" → 回车 → 回车

# 2. 用 git 把代码回退到对应 commit
!git reset --hard <commit-id>

# 结果：代码里只剩茄子，芹菜/白菜/皮皮虾都没了

这样才能把一段历史从对话记录和代码两个层面全部回滚。

9.5 官方补充的对话树能力

所有分支存放在同一个文件里。
可按消息类型过滤，可给条目打标签当书签。
/export 导出为 HTML；/share 上传到 GitHub gist 得到可分享的 URL。

10. 会话克隆与分叉 /clone 与 /fork

命令	作用	结果
`/clone`	克隆：把当前 Session 完整复制一份成为新的 Session	Session1（茄子→芹菜→白菜）复制成 Session2（完全相同的三条）
`/fork`	分叉：选择一个对话节点，基于该节点复制出一个新 Session	Session1（苹果→香蕉→橘子）在"香蕉"节点 fork → Session2 只携带"苹果→香蕉"这段历史

区别一句话：/clone 复制整棵树，/fork 从指定节点复制。

text 复制代码

/clone     # 完整复制当前 Session
/fork      # 基于节点复制 Session（会先让你选择节点）

验证方式：Ctrl+C 两次退出，再 pi -r 就能看到多出来的 Session。

11. 上下文压缩 /compact

11.1 自动压缩

状态栏出现 (auto) 表示自动压缩开启：当上下文使用量达到阈值时，Pi 会自动触发一次上下文压缩。

11.2 手动压缩

text 复制代码

/compact      # 手动触发上下文压缩

Pi 会把之前的对话历史总结和精简。
效果示例：上下文占用从 18.1% 降到 10%。
好处：提高 AI 专注力 + 降低后续 Token 消耗。

压缩后界面会显示压缩记录，例如：

text 复制代码

[compaction]
Compacted from 49,141 tokens (ctrl+o to expand)

11.3 ⭐ 通用经验：清空优于压缩

在 Agent 领域有一条通用经验：清空好于压缩。

因为过多的历史会话会干扰 AI 的注意力 。所以执行完一轮任务后，最好的方式是直接输入 /new 新开一个 Session，清空模型上下文，让 AI 把注意力全部集中到新任务上，从而提高执行效果。

12. 核心工具与设计哲学

12.1 四个基础工具（有且仅有）

工具	图标含义	说明
Read（读文件）	放大镜 + 文档	读取任意文件
Write（写文件）	铅笔 + 文档	创建 / 覆盖文件
Edit（改文件）	铅笔 + 便签	精准修改内容
Bash（运行命令）	命令行	执行 Shell / Bash

12.2 Bash 是"万能工具"

Bash 本身就是一个强大的万能工具，可以进一步调用：

命令	用途
`find`	搜索文件
`grep`	检索代码
`ls`	调查目录

截图中的真实调用示例：

bash 复制代码

ls -la && find . -maxdepth 3 -type f | sort

12.3 设计理念

Pi 的设计理念是用最小的一组工具来覆盖绝大多数的编程任务。

核心越小越干净，模型反而能更好地发挥，同时让用户有最大的自由度去组装其他能力。

除了这四个工具，Pi 就只支持 Agent Skill ，然后就没有其他了------没有 MCP、没有 SubAgent、没有 Plan Mode、没有 Todo、没有 btw。

Pi 的源码被开发者称为 "Agent 设计规范的教科书"。

13. 插件生态（Extensions / Packages）

Pi 提供非常丰富的扩展能力，主要体现在两个方面 ：插件（插件/Extension/Package） 与 Skill。

13.1 安装 / 卸载插件

powershell 复制代码

# 全局安装（对所有项目生效，默认）
pi install npm:pi-web-access

# 项目级安装（只对当前文件夹生效）：命令末尾加 -l（local）
pi install npm:pi-subagents -l

# 卸载
pi uninstall npm:pi-web-access

要点：

在 Pi 官网 Packages 页找到插件，复制它的一键安装命令即可。
安装完成后，Pi 启动界面会出现 [Extensions] 标记，表示插件已加载。
项目级安装的插件会落在项目目录的 .pi 文件夹下。
每装一个插件，其实都是增加了一部分系统提示词。如果某个项目用不到这个插件，就是白白给模型增加负担 ------ 所以支持项目级安装。
也可从 git 安装：pi install git:github.com/...。

13.2 常用插件速查

插件	能力	备注
pi-web-access	联网搜索 + 更方便地提取网页信息	⭐ 零配置，接入 Exa 服务，无需任何 API Key，装上即用
pi-subagents	子代理：并行运行多个 agent	例：同时开发 5 个风格各异的网页；用 `/pi-subagents` 调用其自带技能
pi-mcp-adapter	MCP 接入：接入任意 MCP Server	自动读取项目内的 `.mcp.json` 配置文件（如高德地图 MCP）
btw 插件	旁路对话：不影响主任务地开一个子窗口提问	输入 `/btw` 开启；`Ctrl+C` 退出子对话回主对话
pi-plan	计划模式：AI 先输出计划，确认后再执行	输入 `/plan-mode` 进入/退出；计划写到 `PLAN.md`
pi-go	Go 模式：给一个目标，自动多轮迭代直到完成	输入 `/go` + 目标；迭代历史在 iterations 里
pi-dynamic-workflows	动态工作流：编写 JS 编排脚本，后台调度几十上百个子代理协同	类似 Claude Code 的 Dynamic Workflows；用 `/workflows` 查看后台工作
pi-v-chat / wechat 插件	移动端连接：手机扫码配对，用微信/通讯录向 Pi 发指令并收结果	`/wechat login` 配对 → `/wechat start` 启动连接
pi-permission-system	权限系统：敏感操作先弹审批窗口	由 `@gotgenes/pi-permission-system` 等提供；会拖慢开发效率

⚠️ 教程提示：搜索插件时如果有多个同名插件 ，建议选择更新时间更靠前、下载量更大的那个。

13.3 几个插件的使用细节

pi-web-access（联网搜索）

text 复制代码

安装后测试："青岛天气怎么样" → Pi 调用联网搜索并总结输出

pi-subagents（子代理）

text 复制代码

/pi-subagents → "设计 5 个不同风格的个人网页"
→ 启动 5 个 worker 并行开发，并完成并行审查与修复，交付 5 个页面

pi-mcp-adapter（MCP）

在项目目录新建 .mcp.json（例如配置高德地图 MCP，需替换从高德开放平台申请的 Key）。启动后显示 MCP Server 准备就绪，即可让它查公交路线、坐标信息、规划路线等。

btw（旁路对话）

text 复制代码

AI 正在紧张工作时输入：/btw  Next.js 是什么
→ 弹出一个独立子窗口回答，不干扰主对话
→ Ctrl+C 退出子对话

Plan Mode（计划模式）

text 复制代码

/plan-mode                      # 进入（底部出现 plan 小标记，AI 不动手，只输出计划）
"把数据库改造成 Supabase"        # AI 生成计划并写入 PLAN.md
（人工修改计划，对齐需求）
/plan-mode                      # 再输一次关闭
"确认实施计划"                   # AI 正式开发

Go 模式

text 复制代码

/goal /go  + 一个较大的目标
例："做一个 html 坦克大战，完成后启动试玩，输出测试结论，再重做一版，迭代到跟红白机坦克大战越像越好"
→ Pi 自动迭代 3 次完成开发，iterations 里可看历史迭代过程

动态工作流

text 复制代码

/workflows → 触发动态工作流，例："调研 22 年到 26 年 AI 领域具有重大影响力的论文"
→ 启动 10 个 Agent 并行工作
/workflows  # 查看后台各子代理的工作情况（含 running 状态）

14. Agent Skills 技能系统

14.1 放置路径（遵循标准 Skills 协议）

Pi 遵循标准 Agent Skills 协议，把 Skill 放到对应目录即被识别：

text 复制代码

# 项目级（只对当前项目生效）
<项目目录>/.agents/skills/skill-name1/SKILL.md
<项目目录>/.agents/skills/skill-name2/SKILL.md
<项目目录>/.agents/skills/skill-name3/SKILL.md

# 全局（对所有项目生效）
~/.agents/skills/skill-name1/SKILL.md

~ 的含义（截图专门解释）：

系统	`~` 目录
Windows	`C:\Users\{你的用户名}`
macOS	`/home/{你的用户名}`

两层含义 ：一是"注释：~ 就是当前用户的 Home 目录"；二是"也就是放到用户的 ~/.agents 文件夹下面"。

加载成功后，Pi 启动界面的 Skills 区域会列出已识别的技能。

14.2 常用 Skill 示例

Skill	用途	备注
Playwright CLI	浏览器自动化，可自动操作 Chrome 完成网页任务	需先安装 Playwright CLI 工具本体，再放置配套 Skill
Markdown Converter	任意文档转 Markdown	依赖 uvx 工具（缺了可以让 Pi 帮你装 UV）
tts（Edge TTS）	文本转语音	免费、无需 API Key、零成本

14.3 安装 Skill 的三种方式

下载 zip 手动放置 ：从 GitHub 的 skills/<name>/SKILL.md 目录结构下载源码 zip，把 skills 目录直接复制到 .agents/ 下。
让 AI 自己装：把 Skill 页面的安装提示词复制给 Pi，Pi 会自己完成安装（缺依赖如 uvx 时也会自己补装）。
从 Skill Hub 获取：Skill Hub 是不错的技能检索渠道。

14.4 项目级 → 全局级

把项目目录下包含 skills 的文件夹直接拖拽到全局目录 ~/.agents/ 下即可。之后在任意项目启动 Pi，都能在加载的 Skills 里看到它。

14.5 使用示例

text 复制代码

"打开谷歌搜索并且进入 Pi Agent 的官网，让我能看到执行过程"
→ Pi 读取 Playwright CLI 技能，操作 Chrome 打开谷歌、填入搜索词、打开官网

text 复制代码

（把 PDF 教案粘贴进来）"把它转换成 Markdown 格式"
→ Pi 读取 Markdown Converter 技能完成转换

text 复制代码

"帮我把这段话转成音频发送"
→ Pi 自主选择 edge-tts Skill 生成音频（无需特别指定技能）

⭐ 要点：不需要特别指定用哪个技能，Pi 会根据工作场景自主选择。

15. Web UI 网页版界面

社区项目（4,200+ Star，由国内作者"第四种黑猩猩"发布）提供图形化界面。

15.1 安装

bash 复制代码

npx ...        # 使用项目 GitHub 首页 Quick Start 里的 npx 安装命令，输入 y 确认

安装完成后自动打开浏览器。

15.2 界面能力

文件树浏览与项目切换：左上角切换项目，也可点击自定义路径打开本地任意文件夹作为项目目录。
文件浏览器：左下角展示项目文件夹内的文件。
模型配置与订阅管理：左下角"模型"按钮可添加 provider（例：Kimi → moonshot AI cn，填入后台创建的 API Key），配置后即可在中央模型选择器里选用。
技能 / 插件启停控制 ：
- 技能与插件都区分 project （项目级）和 global（全局）两部分；
- 可单独开启/关闭，关闭后在提示词中隐藏，模型看不到，从而节省 Token；
- 还有"添加技能"面板，可搜索并安装技能（例：Edge TTS 文本转语音，无需 API Key，零成本），并选择装到项目还是全局。
对话面板 ：支持 / 斜线命令、@ 选择文件、Control + V 粘贴截图；可调整模型思考强度。
Token 与成本统计：任务完成后显示输入/输出 Token 与预估花费。
重启：关闭浏览器后想再用，运行对应启动命令即可重新打开。

16. 跨 Session 记忆：AGENTS.md

16.1 问题：每次新对话，都是全新的开始

❌ 问题	✅ 解决方案
新对话 = 全新上下文；完全不记得之前的任何内容	在项目根目录创建 `AGENTS.md`
项目记忆为空白 → 需要重新交代背景，或让 AI 自己读代码、搜索	AI 获得完整上下文，理解项目，直接开干
这是低效的工作方式	结果：高效、准确、一致

16.2 项目级 AGENTS.md

text 复制代码

<项目根目录>/AGENTS.md

这是 AI 每次对话时必读的指南，后续所有对话都会带上该文件内容作为上下文。
编写示例（教程作者写的）：

markdown 复制代码

我叫技术爬爬虾。
我擅长的语言是......

我对前端一窍不通，如果遇到网页问题，需要用大白话给我解释。

验证：重启 Pi 后问"我叫什么，擅长什么技术"，Pi 能直接答出来。
可以让 Pi 自己写：让它"通读当前文件夹，然后把学到的关于项目的知识保存到 AGENTS.md 文件里"。Pi 会读源码、配置、文档，然后生成这个文件。

结论：对于复杂项目来说，这个 AGENTS.md 文件是必须要写的。

该文件在 Codex、OpenCode 等其它 AI Agent 工具里也是通用的。

16.3 全局 AGENTS.md + 安全兜底提示词

text 复制代码

Windows: C:\.pi\agent\AGENTS.md        （实际为 <用户目录>\.pi\agent\AGENTS.md）
macOS  : ~/.pi/agent/AGENTS.md

放在这里的 AGENTS.md 对这台电脑上的所有项目都生效。

教程作者因为看过"AI 命令失误把整个 D 盘删掉"的新闻，所以在全局 AGENTS.md 里加了一段安全兜底提示词：

markdown 复制代码

禁止批量删除文件或目录。
不要使用：
- `del /s`
- `rmdir /s`
- `Remove-Item -Recurse`
- `rm -rf`
需要删除文件时，只能删除一个或多个明确路径的文件。
正确示例：
rm a.txt b.txt
如果需要批量删除文件，应停止操作，并向用户请求，让用户手动删除。

测试：随便开一个项目问"删除文件有什么规矩"，Pi 会遵循这条全局提示词。

16.4 更高优先级：APPEND_SYSTEM.md

在同一个全局配置目录下新增：

text 复制代码

~/.pi/agent/APPEND_SYSTEM.md

append = 追加，system = 系统 ------ 即追加系统提示词。
Pi 会把这个文件的内容直接追加到系统提示词里。
因此优先级更高、效果更强。
但一般场景下，推荐用通用的 AGENTS.md 就够了。

16.5 官方说明的上下文文件加载规则

AGENTS.md ：启动时从 ~/.pi/agent/、各级父目录 、以及当前目录加载项目指令。
SYSTEM.md ：按项目替换或追加默认系统提示词。
Compaction：接近上下文上限时自动总结旧消息，可通过 extension 完全自定义（如按主题压缩、代码感知摘要、用不同模型做摘要）。
Skills：按需加载的能力包，渐进式披露且不破坏 prompt 缓存。
Prompt templates ：Markdown 形式的可复用提示词，输入 /名字 展开。
Dynamic context：extension 可以在每轮前注入消息、过滤历史、实现 RAG 或构建长期记忆。
AGENTS.override.md、AGENTS.md、CLAUDE.md 这类上下文文件无论项目是否被信任都会加载（除非禁用上下文加载）。

17. 全局配置目录 ~/.pi/agent 全解析

Windows 下路径为 C:\Users\<用户名>\.pi\agent\，macOS 下为 ~/.pi/agent/。

截图中的实际目录内容：

text 复制代码

.pi/agent/
├── missions/                 # 文件夹
├── npm/                      # 文件夹
├── sessions/                 # 文件夹（所有会话记录）
├── wechat-assistant/         # 文件夹（微信插件相关）
├── AGENTS.md                 # 全局项目指令（对所有项目生效）
├── APPEND_SYSTEM.md          # 追加系统提示词（优先级更高）
├── auth.json                 # 认证信息（如 API Key / 登录态）
├── mcp-cache.json            # MCP 缓存
├── models-store.json         # 模型配置存储
├── run-history.jsonl         # 运行历史
├── settings.json             # 全局设置
└── trust.json                # 项目信任决策记录（按规范化目录保存）

18. 安全机制

18.1 Pi 只有一个非常基础的安全机制

项目信任（Project Trust） ：在一个包含插件或 Skill 的陌生目录 下启动 Pi 时，它会询问用户是否信任并加载这些插件/Skill。

触发信任询问的资源包括（官方文档）：

.pi/settings.json
.pi/extensions、.pi/skills、.pi/prompts、.pi/themes
.pi/SYSTEM.md、.pi/APPEND_SYSTEM.md
当前目录或祖先目录中的项目 .agents/skills

注意：一个空的 .pi 目录不算 需要信任的项目资源。

默认值 defaultProjectTrust: "ask"（有 UI 时询问）。

非交互模式 （-p、--mode json、--mode rpc）不会弹信任提示 ；可用 --approve / -a 或 --no-approve / -na 单次覆盖。

18.2 ⚠️ 一旦开始运行，Pi 就没有任何安全限制

永远处于最高权限（以启动它的用户账号权限运行）。
编辑文件、执行命令等全部自动执行，不会停下来询问用户。
没有任何内置沙箱机制。

这是开发者有意为之 ：Pi 的设计哲学是打造极简 Agent，让本体永远保持简洁高效，用最快的速度完成任务，而不是制造一个"看似安全但实际上不完整"的沙箱。

官方文档的原始表述很直白：项目信任只是一个输入加载的护栏 （input-loading guard），它防止仓库在你批准前悄悄改掉 pi 的设置或扩展；它不是沙箱 ，也不会在你开始工作后限制模型让工具做什么。真正的隔离必须来自操作系统或虚拟化/容器边界。

18.3 两种保障安全的方案

方案一：容器 / 虚拟机隔离（官方推荐）

用 WSL、Docker 或 Hyper-V 运行 Pi，隔离风险。

WSL（Windows Subsystem for Linux） ：运行在 Windows 上的 Linux 子系统。用它跑 Pi，即使 AI 把环境搞坏了 （例如 sudo rm -rf /、apt 崩了、systemctl --failed 满屏红），通常只需要删掉虚拟机重建一个即可，不会影响宿主机。
因为 Pi 极简易轻量 ，启动速度快、内存占用低，是最适合在容器或虚拟机里运行的 Agent ，也很适合用 Docker 容器或 K8S 批量部署。

官方建议的容器化要点：

把整个 pi 进程跑在容器/沙箱里；
或宿主机跑 pi，把内置工具执行路由进 micro-VM；
只挂载 agent 应该访问的工作区路径；
避免挂载宿主机 ~/.pi/agent；
只传最小必要 API Key，或用短期凭据；
任务不需要网络时限制网络；
把结果拷回可信系统前先审阅 diff 与输出。

⚠️ 注意：如果以读写方式 bind-mount 宿主工作区，容器/VM 内的写入依然会修改宿主文件。需要更强保护时用只读挂载，或把文件拷进拷出。

方案二：权限插件

安装 pi-permission-system，Pi 执行敏感操作前会弹出审批窗口，等用户批准后再执行------有点像 Claude Code 的权限系统。

教程作者注：这种插件会拖慢开发效率，所以他本人不装。

18.4 其它已知风险

Prompt Injection ：来自仓库文件、注释、文档、上下文文件、构建输出的提示注入，属于本地 agent 的预期风险 ，Pi 无法可靠防止。
用户安装的 extension / skill 的行为，一般不在安全边界内。

19. 自己动手 DIY 插件

Pi 开放了大量接口，几乎允许对任意功能 自由定制：模型、工具系统、会话管理，甚至 UI 界面都能修改。

最有趣的一点：编写插件不需要你自己写代码------Pi 本身内置了插件开发知识，Pi 能自己给自己写插件。

教程中演示的三个插件都是用 GPT-5.6 SOL 一把跑通的。

19.1 插件存放位置

级别	位置
项目级	`<项目目录>/.pi/extensions/`
全局	`~/.pi/agent/extensions/`（把项目里的 `extensions` 文件夹整个复制过去即可）

插件本质上就是一个 TypeScript (.ts) 文件。

改完插件后执行：

text 复制代码

/reload      # 重新加载插件

19.2 三个实战示例

① 天气插件（定制 UI）

提示词："编写一个插件，根据 IP 查询我的地理坐标，再根据地理坐标查询当地天气，最后把天气展示到对话窗口上面。"

结果：Pi 自己读开发插件的文档 → 生成 .pi/extensions/xxx.ts → /reload → 地理位置坐标、天气数据全部显示在对话框上方。这就是"修改 UI"。

② 文件保护插件

提示词："给自己开发一个插件，禁止 AI 后续编辑/读取这个受保护的 .env 文件，如果 AI 尝试操作直接阻止，并提示这是受保护的文件。"

结果：/reload 后再让 AI 看 .env，AI 无法读取内容。

③ 删除确认插件

提示词："当准备执行 rm（删除）命令的时候，先弹窗询问我是否允许执行。"

结果：/reload 后测试删除文件 → 弹窗询问 ；选 No 文件还在，选 Yes 文件被删除。

19.3 其它可 DIY 的方向（长图列举）

天气插件：从 IP 查地理，再查天气并展示在 UI 上。
文件保护 ：禁止编辑 .env 文件，自动拦截。
删除确认 ：执行 rm 前弹窗询问。
官方示例还包括：sub-agents、plan mode、permission gates、path protection、SSH execution、sandboxing、MCP 集成、自定义编辑器、状态栏、浮层等（50+ 示例）。

20. 开放接口（API）速查

Pi 通过丰富的接口扩展与定制自身能力（截图《Pi 开放的接口 (API)》原表）：

#	分类	主要接口	能力说明
1	生命周期 / 事件 Hooks	`pi.on()`	监听、拦截 Pi 运行过程中的生命周期事件
2	Tool 工具系统	`registerTool()`、`getAllTools()`、`setActiveTools()`	给 AI 增加、获取、启用或修改工具
3	Agent / 消息 / 上下文	`sendMessage()`、`sendUserMessage()`、`getSystemPrompt()`、`compact()`	发送与管理消息，操作 Prompt 与上下文，控制上下文长度
4	Session / 对话树	`newSession()`、`fork()`、`navigateTree()`、`switchSession()`	创建会话、Fork 分支、遍历与切换会话，管理对话树
5	UI / TUI / 渲染	`ctx.ui.*`、`registerMessageRenderer()`、...	定制 Pi 的界面、弹窗、状态栏，以及消息渲染方式
6	命令 / 快捷键 / 输入	`registerCommand()`、`registerShortcut()`、`registerFlag()`	注册命令、快捷键与 CLI 参数，扩展输入与交互能力
7	模型 / Provider	`setModel()`、`registerProvider()`、`setThinkingLevel()`	注册模型源（Provider）、切换模型、调整思考等级
8	系统 / 执行 / 扩展通信	`pi.exec()`、`pi.events`、`ctx.signal`、`ctx.shutdown()`	执行系统命令、订阅事件、扩展间通信与控制运行

原始说明：以上接口可通过 pi 或 ctx 对象在插件/扩展中调用，帮助你深度集成与扩展 Pi。

截图中还有一句弹幕式注释："甚至 UI 界面都能修改"。

21. 源码架构与 SDK 集成

21.1 核心包组成

仓库的 packages/ 目录下，重点看四个包：

包	职责
`ai`	模型统一调用层，适配几十个模型厂商，把它们的接口统一成一套规范
`agent`	实现核心双层循环机制（Agent Loop）
`coding-agent`	编程功能的具体实现：四个基础工具、系统提示词、Skills 机制、插件实现机制等
`tui`	命令行界面的全部实现

Pi 的源码就是一个 Agent 设计规范的教科书------如果从事 Agent 开发相关工作，这套源码非常值得深入学习。

21.2 SDK 使用

用 Pi AI 接入任意模型：

bash 复制代码

npm install ...

引入 pi-ai 的 createModel 方法，就能在自己的项目里接入任何一种模型并与模型对话。

把 Pi Coding Agent 嵌入自己的项目：

同样用 npm 装上 pi-agent，项目里就有了一个开箱即用的 Agent ：先创建一个 Session，然后就可以直接开启任务。

22. 命令 / 快捷键 / 目录速查表

22.1 斜线命令（TUI 内）

命令	作用
`/login`	配置模型（API Key 或订阅登录）
`/model`	切换模型（也可 `Ctrl+L` 打开选择器）
`/new`	新开 Session（清空上下文）
`/tree`	进入对话树，切换分支 / 回退历史
`/clone`	完整复制当前 Session
`/fork`	基于选中节点复制出新 Session
`/compact`	手动压缩上下文
`/reload`	重新加载插件 / 扩展
`/settings`	打开设置菜单
`/export`	导出会话（HTML 等）
`/share`	上传到 GitHub gist 获得分享链接
`/btw`	（装插件后）开启旁路对话
`/plan-mode`	（装 pi-plan 后）进出计划模式
`/go` `/goal`	（装 pi-go 后）目标驱动的多轮迭代
`/workflows`	（装 pi-dynamic-workflows 后）查看/触发动态工作流
`/wechat login` `/wechat start`	（装微信插件后）配对与启动移动端连接
`/pi-subagents`	调用 pi-subagents 自带技能

22.2 CLI 命令

命令	作用
`pi`	在当前目录启动交互式 TUI（当前目录即项目目录）
`pi -p "..."`	非交互一次性执行
`pi -c`	从最近一次 Session 继续
`pi -r`	挑选一个 Session 继续
`pi --mode json`	输出 JSON 事件流
`pi --mode rpc`	RPC 模式（stdin/stdout JSON 协议）
`pi install npm:<pkg>`	全局安装插件
`pi install npm:<pkg> -l`	项目级安装插件（local）
`pi install git:<repo>`	从 git 安装插件
`pi uninstall npm:<pkg>`	卸载插件
`pi -a` / `pi -na`	`--approve` / `--no-approve`，单次覆盖项目信任（非交互模式用）

22.3 快捷键

快捷键	作用
`Enter`	发送；执行中发送 = Steering 引导
`Shift + Enter`	输入框内换行
`Ctrl + G`	打开记事本编辑提示词
`Alt + Enter`（Mac `Option + Enter`）	Follow-up 排队（Windows 需先删除 PowerShell 的全屏快捷键）
`Alt + ↑`	取回排队中的 Follow-up 消息重新编辑
`Ctrl + L`	快速打开模型选择器
`Ctrl + P`	在收藏模型间循环
`Shift + Tab`	切换模型思考强度
`Ctrl + O`	展开压缩/总结详情
`Alt + V`（Win） / `Ctrl + V`（Mac）	粘贴剪贴板图片
`Ctrl + C` ×2	退出 Pi
`!` / `!!` + 命令	临时运行命令（AI 可见 / 不可见）
`@`	引用文件
`/`	触发斜线命令

22.4 目录与文件速查

路径	作用
`<项目>/.agents/skills/<name>/SKILL.md`	项目级 Skill
`~/.agents/skills/<name>/SKILL.md`	全局 Skill
`<项目>/AGENTS.md`	项目级记忆 / 指令（必写，跨工具通用）
`~/.pi/agent/AGENTS.md`	全局记忆 / 指令（对所有项目生效）
`~/.pi/agent/APPEND_SYSTEM.md`	追加系统提示词（优先级更高）
`<项目>/.pi/extensions/`	项目级插件（.ts）
`~/.pi/agent/extensions/`	全局插件
`<项目>/.pi/settings.json`	项目级设置
`~/.pi/agent/settings.json`	全局设置
`~/.pi/agent/sessions/`	会话记录（树状结构，单文件含所有分支）
`~/.pi/agent/trust.json`	项目信任决策
`~/.pi/agent/auth.json`	认证信息
`<项目>/.mcp.json`	MCP Server 配置（配合 pi-mcp-adapter）
`<项目>/PLAN.md`	计划模式下生成的计划文件
`<项目>/TODO.md`	官方推荐的待办替代方案

24. 行动建议

长图结尾给出的四条建议（可直接作为上手路线）：

第一步 ：安装 Pi，用最小配置体验"大道至简"。
核心用法 ：用 Steering 实时纠偏，用 Follow-up 排队补充任务。
别忘了写 AGENTS.md，让 Agent 记住项目背景。
复杂任务用 Go 模式 + 子代理并行，成倍提速。

补充几条视频里反复强调的实践经验：

🔁 任务结束就 /new，清空优于压缩。
🌳 想试不同方案用 /tree 开分支，但记得配合 git 回滚代码。
📦 用不到的插件和 Skill 要及时关掉（尤其是在 Web UI 里），它们都在吃系统提示词的 Token。
🌐 联网搜索装 pi-web-access（零配置、免 Key），性价比最高。
🛡️ 全局 AGENTS.md 里加一条防批量删除的兜底提示词；要更强隔离就用 WSL / Docker / Hyper-V 跑 Pi。
🤖 想要什么功能就直接让 Pi 给自己写插件 ------它内置了插件开发知识，/reload 即生效。

极简，是一种力量。

------ 摘自长图《AI Agent 完全指南》结尾