前言

为什么我觉得 pi 比 Claude code 更好？

1. 引用官方的话：现在前沿的AI已经足够强大，过多的限制未必会让模型能力得到提升。
2. 对我来说更实际的是可以省token费用。不写代码的时候就不需要太重的工具，同时不是谁都写代码。

像一些简单的安装软件或者查看日志的操作，通过 cc 无论用什么模型都是浪费。我想通过自然语言调用各种开源项目，例如用 mole 去清理 Mac 卸载软件的残留，根本不需要 cc 那么笨重的项目去做约束。

以下为我只输入了一句话让Claudecode给电脑安装并配置好oh my posh使用的token消耗量。我就说了一句话，全程按yes：

任务完成的特别好，我直接就可以用了。当然，费用也爆炸了。如果用 pi agent 保守估计五分之一可能都用不到。🫠

对于这种简单任务，用 Claude code 给我的感觉就好像写前端用 webstorm 一样，打开的时候已经有一层心理负担。

所以，pi就是一个好的选择，轻量、快、省 Token、模型自由、可完全掌控、免费开源，就好像 webstorm 相较于 vscode。

网上有一种论调说 pi 比较极客，但我不认为如此。以现在的模型能力，就算纯对话，对于一些简单乃至中等难度的对话，都可以做到得心应手，对于一点小需求，完全可以通过自然语言让它自己给自己装配新功能。所以，开箱即用，也完全没问题。

以下内容为我了解 pi 的心路历程与使用笔记，是根据我的疑问查看官方文档得出来的答案。

Pi 支持两种身份验证方式：

1. 执行 /login 命令，登录订阅服务商账号；
2. 使用API 密钥。

其中 API key 也有两种使用方式

1. 临时设置： 启动 Pi 前在终端执行export xxx_API_KEY=密钥，临时配置xxx平台密钥，再运行pi。
2. 永久保存： 进入 Pi 交互界面执行/login，选择对应 API 密钥服务商，密钥会存入~/.pi/agent/auth.json，后续无需重复设置。或者手动编辑 auth.json

常用的目录：

.pi/agent/
├── AGENTS.md           # 全局规则文件（需手动创建）
├── settings.json       # 系统设置
├── auth.json           # 认证配置
└── bin/                # 运行时工具（自动管理）
    ├── fd.exe          # 文件搜索工具
    └── xxx.exe          # xxx工具

作用：通过 AGENTS.md 或 CLAUDE.md 给 Pi 设定项目专属规则与行为要求，启动时自动加载。

• 全局规则：~/.pi/agent/AGENTS.md
• 项目规则：当前/上级目录的 AGENTS.md 或 CLAUDE.md
• 修改文件后，重启 Pi 或执行 /reload 即可生效。

Pi 会先找 AGENTS.md；如果没有，才 fallback 到 CLAUDE.md。

假如有几个完全不同的项目，那配置是怎么运行的？

Pi 启动时会自动查找当前目录及上级目录的 AGENTS.md 或 CLAUDE.md，项目规则会覆盖全局规则，未定义的规则继承全局配置，修改后执行 /reload 即可切换配置。

简而言之就是就近原则 ：离当前目录越近的规则优先级越高。Pi 会按当前目录向上找并叠加，就近优先。

项目规则（当前目录）
    ↓ 覆盖
项目规则（上级目录）
    ↓ 覆盖
全局规则（~/.pi/agent/AGENTS.md）
    ↓ 兜底
默认行为

想让各项目有完全独立行为，就要各自在根目录放 AGENTS.md；

全局规则 (~/.pi/agent/AGENTS.md)
├── 规则A: 4空格缩进
├── 规则B: 小写文件名
└── 规则C: 使用ESLint

项目X (无AGENTS.md)
└── 继承所有全局规则 (A+B+C)

项目Y (有AGENTS.md)
├── 继承全局规则 (A+B+C)
└── 覆盖/新增项目专属规则

因为无论怎么样，全局规则都会兜底生效这个特性，就可以这样配置：

• 全局规则 ：存放所有项目通用的配置（如编码规范、提交格式等）
• 项目规则 ：只存放该项目特有的规则（如框架特定规范、团队约定等）

对话常见问题

Pi 默认自带 read、write、edit、bash 四类工具，另有 grep、find、ls 等只读内置工具可启用，程序会在当前目录操作文件。

对话到一般需要执行命令/下载包/检查，但不想浪费上下文怎么办？

• 执行 npm run lint

• 输出结果会发送给 AI，AI 能看到结果并修复

• 执行 !npm run lint

• 输出结果不 发送给 AI，只显示在屏幕上，不用把日志塞进对话浪费上下文

例如对话到一半，需要下载一个包，就可以用这个命令而不用中断对话、浪费上下文。

断电、崩溃、意外关掉终端，聊天记录怎么办？

pi 默认每条消息都自动持久化到本地文件。所有会话都保存在：

~/.pi/agent/sessions/

按目录分组、每条会话一个 .jsonl 文件，实时写入

通过用下面的命令：

pi -c ： 继续最近一次对话，直接回到上次聊到的地方，上下文、文件、指令全都保留。

pi -r = 浏览所有历史对话，打开一个列表，查看之前所有聊过的内容，可以选一个旧对话继续聊。

1. 使用 /resume 查看选择之前的会话
2. 使用 pi -r 在启动时浏览和选择会话
3. 使用 pi -c 继续最近的会话
4. 使用 /session 查看当前会话信息
5. 使用 /tree 在会话树中导航

输入@，直接让pi读取指定的文件：

消息队列应该怎么使用？我可以打断它吗？

目前结合官方文档来看，默认不能直接打断、即时发送，所有输入都会进入消息队列排队执行。

最后两个有点相似，这两者的区别是：连续发了多条消息进队列，按 Alt+Up 可以逐条取回编辑；而按 Esc 会直接清空本次排队状态，所有待发内容一次性退回。

有新想法？如何回到对话的「过去某一步」重新开始

聊了 20 轮，发现第 10 轮的方向更好，想从第 10 轮重新聊，但不想删掉后面的内容。这时候需要新开一条平行时间线，就要用：

/fork

选择一个历史消息 → 从那里新开一条对话。

主线：1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10（已有代码不动）
                          ↳ 支线：5' → 6' → 7' ...（新分支，试错，成功就成为新的主分支）

用 fork 切出新分支，让每条支线专注一个小任务，更清晰。假设我只需要改第五步 → 合并后面 6-10 → 变成主分支 → 原来的变成分支 → 先 clone 备份防错：

# 只改其中一步
主线：1→2→3→4→5→6→7→8→9→10（不动）

分支：1→2→3→4→【你改了第5步】
                ↓
       对话：继续做原来6-10的任务
                ↓
分支：1→2→3→4→5新 →6'→7'→8'→9'→10'（AI自动重写）

# 改第五步，后续要重新实现/新方案
1 → 2 → 3 → 4 → 新5 → 新6 → 新7 → 新8 → 新9 → 新10

这里需要输入 /tree → 选择分支 → 切换分支

关于备份对话

原会话里用 /tree → 看不到 /clone 出来的那份新会话，输入 /clone → 会生成 B.jsonl（完全独立），在 A 里 /tree → 只显示 A 内部的分支，不包含 B

项目状态和对话的状态

若新分支运行异常需要切回原有主分支，且项目文件已被其他对话修改怎么办？

根据文档来看，目前Pi暂不支持同步回滚对话与代码，所以提前做好项目管理吧。

提示词模板

简而言之差不多就是上图那样的意思，预设好的提示词。

Pi 里基于 Markdown 编写的快捷提示词模板，把高频使用的提示词预制成文本片段，保存为 .md 文件后，在编辑器输入 /文件名 就能一键调用、自动展开成完整提示词，不用每次重复输入长文本。

不过这玩意也分全局 / 项目。全局模板所有项目可用，项目专属模板仅当前项目生效。

模板存放位置（Pi 自动读取路径）

flowchart LR
    A["启动 Pi"] --> B["开始加载模板"]
    B --> C["1. 全局模板<br>~/.pi/agent/prompts/*.md"]
    C --> D["2. 项目模板"]
    D --> D1{是否信任项目?}
    D1 -- 是 --> D2[项目根目录 .pi/prompts/*.md]
    D1 -- 否 --> D3[跳过项目模板]
    D2 & D3 --> E["3. 软件包模板<br>依赖包prompts/ + package.json pi.prompts"]
    E --> F["4. 配置文件指定<br>配置内prompts数组"]
    F --> G["5. 命令行临时加载<br>--prompt-template <路径>"]
    G --> H["模板加载完成"]

1. 全局模板：~/.pi/agent/prompts/ 下所有 .md 文件，本机全局生效
2. 项目模板：项目根目录 .pi/prompts/ 下 .md 文件（需先信任该项目才会加载）
3. 软件包模板：依赖包内 prompts/ 目录，或 package.json 里 pi.prompts 配置项
4. 配置文件指定：通过配置里的 prompts 数组，手动指定模板文件 / 文件夹
5. 命令行临时加载：启动 Pi 时用 --prompt-template <文件路径> 临时引入（可多次使用）

进阶用法

自定义主题

Pi 主题就是一个 JSON 文件，没啥好说的，让AI自己写自己写一个自己装配就行。

System Prompt .md（系统提示文件）

用来替换或追加 pi 的默认系统提示词。大多数情况下不需要管。 默认情况下 pi 使用内置的系统提示词，已经包含了：工具使用说明、代码风格指导、安全规则、基本的交互规范。

什么时候需要？想让 pi 始终遵守特定的代码规范、特殊的输出格式、项目特定的安全要求、想调整 pi 的默认行为。

   默认系统提示词
       │
       ├── SYSTEM.md 存在？ ──是──→ 完全替换
       │                            │
       │                            ↓
       │                      SYSTEM.md 内容
       │                            │
       │         否                 │
       │         ↓                  │
       ├── 保留默认提示词            │
       │         │                  │
       │         ↓                  ↓
       ├── APPEND_SYSTEM.md？──是──→ 追加到后面
       │         │
       │         ↓
       ├── AGENTS.md？──是──→ 追加到后面
       │         │
       │         ↓
       └── Skills？──是──→ 追加到后面

默认是什么样的？

默认情况下没有这些文件。

如果创建 SYSTEM.md，就会完全替换这个默认提示词。用 APPEND_SYSTEM.md 则是在后面追加内容。 需要自己创建：

  # 项目级
  mkdir -p .pi
  echo "你的自定义提示词" > .pi/SYSTEM.md

  # 全局级
  mkdir -p ~/.pi/agent
  echo "你的自定义提示词" > ~/.pi/agent/SYSTEM.md

系统提示词文件和上下文文件有什么区别？

加载顺序：

  1. 系统提示文件（SYSTEM.md）← 最底层，定义角色
     ↓
  2. 上下文文件（AGENTS.md）← 附加项目规则
     ↓
  3. 技能文件（Skills）← 附加能力说明
     ↓
  4. 用户输入 ← 最终指令

Pi Extensions（扩展）

根据官方文档的定义，这是基于TypeScript编写的模块，用于拓展 Pi 的功能。有两条路：自己写 / 下载别人的，同时支持这两种模式。

存放与加载方式：

全局扩展：~/.pi/agent/extensions/，项目本地扩展：.pi/extensions/，可被自动识别，支持/reload热重载。临时测试用 pi -e 文件路径 快速加载。

上面说过，目前 pi 没有同时回滚对话+代码的功能。所以只能自己做好项目管理。这时候就可以写一个自动 Git 备份扩展来防止代码被改崩，每次操作前自动 stash /commit，出错了一键回滚。另外一个典型应用场景就是拦截高危命令，或者路径防护、Git 状态管理、交互式功能、外部服务对接。

例如：可以写一个扩展，让 AI：执行 rm -rf 前必须你手动确认，禁止修改 .env、node_modules、package-lock.json，禁止执行 sudo 高危命令。

这种只做基本概念了解就行，具体编写规范直接让AI参考官方文档写，也没必要自己瞎琢磨。

Skill

这里我有个疑问，那就是skill和AGENTS.md会不会冲突？

根据文档的意思答案就是：AGENTS.md 是全局“规矩/人设”，每次会话都常驻上下文；Skills 是按需加载的“能力包/工具箱”，用的时候才载入。

Pi 中的具体行为

• AGENTS.md
  • 路径：~/.pi/agent/AGENTS.md（全局）+ 项目根目录 AGENTS.md
  • 假设：# 项目规范 - 使用 ESLint + Prettier - 函数用箭头函数，优先 async/await - 提交前必须跑 npm run check
  • 生效：每次对话自动注入，无需手动触发。
• Skills
  • 路径：~/.pi/agent/skills/、项目 .pi/skills/ 等（目录）
  • 结构示例（一个技能目录）：skills/deploy/ ├─ SKILL.md # 技能说明、步骤、规则 └─ scripts/ # 辅助脚本（可选）
  • 生效：
    • 启动时 Pi 扫描所有技能，只加载名称+描述（轻量）
    • 任务匹配时（如“部署到生产”），自动加载完整 SKILL.md + 脚本
    • 也可手动触发：/skill:deploy

SKill存放位置：

结合文档，Pi 的 Skill（技能）存放位置分为五大类，同时附加载规则、禁用方式：

四、配置文件指定 ：在 Pi 的设置中添加 skills 数组，填写文件/目录路径，示例：

{
  "skills": [
    "~/.claude/skills",
    "../.claude/skills"
  ]
}

五、命令行临时指定 ：启动命令加参数，可重复使用、强制加载：

--skill <文件/目录路径>

package

本质就是把扩展、技能、模板、主题打包后的可分享单元；

通过package.json 声明 或 固定目录自动识别。官方的态度就是把安全责任交给使用者。Pi 包拥有完整系统权限，能执行任意代码、运行程序、读写文件。所以：只安装你信任的包，安装前尽量看一眼源码或者用AI审查一下，不要装陌生第三方包。

Pi 安装包

# 从 npm 安装
pi install 包名

# 从 Git 仓库安装
pi install git+https://github.com/xxx/xxx.git

# 安装本地文件夹里的包
pi install ./本地文件夹路径

# 查看已安装包
pi list

# 卸载包
pi uninstall 包名

Pi 实现子代理（subagent）任务委派

目前看来这个是比较通用且实用的包，假设我搞到一半了，这时候需要AI帮我提交暂存代码或者运行项目调试，我可以直接和它说用子代理去执行这些任务而不占用原对话窗口上下文。

通过对话，子代理去后台帮你跑腿干活，干完就把结果丢给主窗口。

如果后续需要继续和子代理对话用 /agents 命令打开子代理列表，选中它就能直接进入专属对话窗口。

pi-subagents 是Pi 平台的扩展包，为 Pi 实现子代理（subagent）任务委派，支持任务链式执行、并行运行、文本交互界面（TUI），广泛用于代码审查、问题排查、功能开发、并行校验等。

1. 安装命令

执行 pi install npm:pi-subagents 即可完成安装，无需复杂配置。

1. 极简使用方式，支持自然语言直接调用，无需编写配置或命令
2. 运行模式：
   1. 前台运行：过程实时展示在对话中；可通过 timeoutMs 设置运行超时，到点自动停止，避免卡死、无限等待。
   2. 后台运行：任务离线执行，不占用当前对话，适合耗时任务，后续可随时查看进度与结果。

插件自带开箱即用的专业代理，分工明确：