文章总结： PI是一个极简的codingagent，提供read/bash/edit/write四个工具，支持多种模型和APIKey，具有缓存和压缩功能，可进行技能和扩展的开发，适合进行代码和文本处理任务。
综合评分： 85
文章分类： 代码审计,安全工具,技术标准,安全建设,安全运营
PI上手实践教程
原创
洺熙
洺熙
Ai迷思录
2026年9月11日 14:45
四川
在小说阅读器读本章
去阅读
在公众号小说中沉浸阅读
很多人看完之前文章后 问我，PI到底哪里好，怎么用，那就写一章
首先 Pi走的是极简coding agent路线，p默认只给四个工具（read/bash/edit/write）
维持 系统提示，工具，agent loop，provider 转换层 整个架构运转
系统提示告诉模型是谁，工具给可调用的代码能力
Agent 循环让模型决定继续调工具还是收工,转换层让换模型不改工作流
四个工具让模型高效运转不受太多约束，也方便拿来二开
官方的一些方案也很有意思，我也很赞同，尤其是mcp与主子Agent
| 官方原则 | 替代方案 |
| — | — |
| 不内置 MCP | 写 Skill，或装一个加 MCP 的 Extension |
| 不内置子 Agent | tmux 起多个 pi 实例，或自己写 Extension |
| 不做权限弹窗 | 用容器/VM，或写自己的确认流 |
| 不做 plan mode | 写计划到文件，或装 Extension |
| 不做内置 to-do | 用 TODO.md |
| 不做后台 bash | 用 tmux |
PI省钱
实际现在很多消费也都在缓存，那先说缓存怎么计算的
每轮请求的输入大部分和上一轮相同
服务端把重复前缀算出的中间结果（KV cache）缓存住，下一轮只补算新增的部分
前缀中间有一个 token 变了，后面全部作废
读缓存比写缓存便宜，未命中要按整段历史重算
长会话里缓存过期后一句 continue，可能比重新生成整个回答还贵
那什么情况会破坏前缀？
空闲超时（Anthropic 默认 TTL 5 分钟）
换模型或换 provider,会话树换分支,压缩或手动改写历史
工具集变化,工具定义排在会话之前
增删一个工具或调顺序，首个不匹配点就被推到很前面
MCP 式用到才加载工具可能让后面重算,这也是我一向不用MCP的原因
MCP吃枣药丸
系统提示里有每轮变的东西（时间戳 / 随机值 / 项目上下文
扩展改写历史消息或 provider payload
而Pi的系统提示极薄，按启用工具动态拼装
（系统提示加工具定义 1000 token左右）对比claude code 几万token
历史只追加，新输入不中途插入，推迟到 turn 边界追加到尾部
/session案例
（本案例 全程没中途换模型，换档，整个会话只压缩一次）
很多人盯着缓存命中率
命中率只影响”每轮 token”这一项里的输入侧计费。真正决定账单的是三个数：
总成本 ≈ 轮数 × 每轮 token × 单价
以及失败记录（报错、试错的 diff、无效命令输出）如果留在上下文里，后面每一轮都要重新读一遍
命中率高不等于便宜，把失败记录全留着，命中率可以很好看，每一轮都在付费
PI压缩
上下文快满时，Pi 让模型把最近 5–20 轮之外的历史写成固定六段式摘要
压缩点落在 user / assistant / bash / custom 消息上，用它顶掉原文
原文仍留在会话文件里
好处是历史不丢会话,对话能一直往下走
摘要纯文本可审查，换模型能接着聊，换分支时还能把放弃的路径总结后挂到新位置
注意 模型不记得细节（精确报错和命令输出想留得写进文件）
PI上手实践
直接github下载安装即可 https://github.com/earendil-works/pi/tree/main/packages/coding-agent
pi –version显示版号即可
内置订阅类登录有
ChatGPT Plus/Pro(Codex)、GitHub Copilot、xAI、OpenRouter、Radius
API Key 类覆盖
Anthropic、OpenAI、Google、Bedrock、DeepSeek、Groq、Cerebras、Mistral、NVIDIA、Cloudflare、Vercel、HF、Kimi、MiniMax、Qwen、Xiaomi MiMo 等
（完整表见 pi.dev/docs/latest/providers）
直接进入pi，/model也可查阅
凭据优先级：
api-key > ~/.pi/agent/auth.json (0600) > 环境变量 > models.json 里的自定义 provider
auth.json 的 key 支持 !命令 和 $ENV_VAR 插值。
/model 选模型，/thinking 选思考档，
两个选择器里按 Ctrl+S 存为启动默认
任务写成四要素：
材料：@input/项目会议记录.md
处理：提取每个事项 + 负责人 + 截止日期 + 风险提醒
输出：output/行动清单.md
限制：不修改 input；原文没有的信息写"未知"；不要访问练习目录之外的内容
验收：完成后列出实际读写路径，并说明我应该怎样逐项核对
pi的链路思考是全可视化的 提交后先看读写记录而不是等结论
出现别的路径或准备写按 Esc 中止。然后自己验收
出错的反馈要指出具体错在哪一项，不要一直输入 “再检查一下”
常用命令
一些小技巧
上下文文件与项目信任
~/.pi/agent/AGENTS.md # 全局指令
<父目录…>/AGENTS.md
<当前目录>/AGENTS.md
若有 AGENTS.override.md → 该目录只用它
会话管理
pi --name "重构鉴权" # 命名从启动开始
pi -c # 继续最近
pi -r # 选择器：Ctrl+N 只看命名、Ctrl+R 改名、Ctrl+D 删除
一件事一个会话
互不相关的历史塞进来，模型每轮都要面对噪音，压缩也会压掉重要的东西
方向跑偏就 /tree 回分叉点，不要继续解释
长任务：状态写文件，不指望上下文
plan.md 目标、阶段、未完成项
decisions.md 做过什么选择、为什么
verification.md 怎么验证的、实际结果、遗留问题
任务描述里写清停止条件与阶段产物，中断后就能从检查点继续：
目标：整理 source 里的文章，建立内容清单
范围：只读 source，只写 output
阶段产物：每处理 20 篇更新 output/progress.md
停止条件：遇到损坏文件、需要登录、或要访问其他目录时停止
验收：给出文件数、失败列表、生成文件和复核命令
5. PI改装
| 形态 | 是什么 | 何时用 |
| — | — | — |
| Skill | 按需加载的能力包（说明 + 脚本 + 参考文档） | 同类任务做过几次，要固化方法 |
| Extension | 加载进 pi 进程的 TypeScript 模块 | 光靠说明不够，确实需要代码 |
| Prompt template | Markdown 片段，/name 展开 | 有固定话术模板 |
| Theme | JSON 颜色定义 | 视觉偏好 |
| Pi Package | 打包分发上面几种 | 跨项目或多人复用 |
顺序：先在真实任务里跑通，重复步骤写成 Skill
缺可执行能力再写 Extension，要配送才考虑 Package
很多人用PI喜欢 一开始装一堆插件 实际都没分清楚该在哪层做功
Skill
my-skill/
├── SKILL.md # 必需
├── scripts/ # 辅助脚本
├── references/ # 按需加载的文档
└── assets/
---
name: meeting-notes-review
description: 按固定字段核对会议记录整理出的行动清单，检查漏项、负责人与日期错配。用于审阅 output/行动清单.md 这类产物。
---
## 步骤
1. 读取原始会议记录与行动清单。
2. 逐项核对：事项、负责人、截止日期、风险提醒。
3. 原文没有的信息标记为"原文未说明"，不要补写。
规则：
description 决定模型何时加载它，要写清”做什么 + 什么时候用”
name 用小写字母数字连字符（≤64 字符），description ≤1024 字符
位置：~/.pi/agent/skills/、~/.agents/skills/
项目的 .pi/skills/ 与 .agents/skills/
想复用 Claude Code 的 skill 就把 ~/.claude/skills 加进 settings
只有 name/description 常驻上下文，全文等模型用到再读
要强制加载用 /skill:name
Skill 能诱导模型执行任意操作，装别人的之前先读内容
Extension
加载位置 ~/.pi/agent/extensions/、.pi/extensions/（需项目信任）
-e <path|npm:…|git:…> 与 packages，改完 /reload。先用 -e 临时加载，确认了再长期安装
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
export default function (pi: ExtensionAPI) {
pi.registerCommand("my-check", {
description: "确认扩展已加载",
handler: async (_args, ctx) => {
ctx.ui.notify("扩展已加载；本命令没有读取或修改文件。");
},
});
}
pi --no-extensions -e ./my-ext.ts # 只加载这一个
pi --no-extensions # 再启动一次，确认它消失了
改扩展时只需记住三件事：
agent_end 只是底层运行结束（之后还可能有重试、压缩、队列消息），
要表达”任务真的不会自动继续”用 agent_settled
压缩用 session_before_compact
改送进模型的 messages 用 context
其他事件名看官方 docs/extensions.md
自定义工具
工具结果整段进上下文，用 truncateHead/truncateTail 之类截断
全文写临时文件并把路径告诉模型
别每轮改工具集（等于打碎缓存，动态加载只做纯新增）
长跑工具把进度快照写进 toolResult.details
恢复点用 pi.appendEntry
本地模型走 llama.cpp router
/login llama.cpp 存连接，/llama 加载卸载下载，/model 选择
以上这些看起来可能有点懵，简单的办法则是发给AI让他给你改
6. 一些pi生态项目
| 需求 | 项目 |
| — | — |
| 状态栏与 token 观察 | wobondar/pi-footer |
| 终端体验套件 | minuque/pi-cc-extensions |
| 自动实验优化指标 | davebcn87/pi-autoresearch |
| 操作浏览器 | fitchmultz/pi-agent-browser-native |
| 连已有 Chrome | tianrendong/pi-chrome |
| 计划审批与 diff 标注 | CodeByPeete/plannotator-pi |
| 手机远程接入 | jacobaraujo7/remote_pi |
| 子 agent 分工 | edxeth/pi-subagents |
| 操作浏览器 | amankumarsingh77/pi-browser-harness |
| 扩展冲突排查 | dmae97/pi-extension-doctor |
| 通用 skill 素材 | badlogic/pi-skills 、Anthropic Skills |
| 生成图表与界面 | Michaelliv/pi-generative-ui |
这些项目没啥好说的，萝卜青菜各有所爱
实际上我只装了浏览器cli，web搜索，subagent让他Bash pi再启动，和一个远程连接的工具，剩下的没了
7. 排错
| 现象 | 先检查 |
| — | — |
| pi: command not found | 重开终端再 pi --version，不要随机改 PATH |
| 模型列表为空 | /login 是否完成、账号是否拥有调用权限 |
| 找不到会话 | 是否在创建会话时的同一工作目录 |
| 缓存命中率突然掉 | 超时 / 换模型 / 换分支 / 压缩 / 工具集 / 系统提示 / 扩展改写 / 路由） |
| Skill 没生效 | 看启动信息的 [Skills] 列表、name 与 description 是否合法 |
| Extension 加载报错 | 看路径与语法，不带 -e 重启即可绕过 |
| 压缩后行为不一致 | 让它复述目标与下一步，与 handoff.md 对照，以文件为准 |
| 选完模型状态栏没变 | 重开 /model 核对，别连续切多个 provider |
免责声明：
本文所载程序、技术方法仅面向合法合规的安全研究与教学场景，旨在提升网络安全防护能力，具有明确的技术研究属性。
任何单位或个人未经授权，将本文内容用于攻击、破坏等非法用途的，由此引发的全部法律责任、民事赔偿及连带责任，均由行为人独立承担，本站不承担任何连带责任。
本站内容均为技术交流与知识分享目的发布，若存在版权侵权或其他异议，请通过邮件联系处理，具体联系方式可点击页面上方的联系我。
本文转载自：Ai迷思录 洺熙
洺熙《PI上手实践教程》