PI上手实践教程

原创

洺熙
洺熙

Ai迷思录

2026年9月11日 14:45
四川

在小说阅读器读本章

去阅读

在公众号小说中沉浸阅读

很多人看完之前文章后 问我，PI到底哪里好，怎么用，那就写一章

首先 Pi走的是极简coding agent路线，p默认只给四个工具（read/bash/edit/write）

维持 系统提示，工具，agent loop，provider 转换层 整个架构运转

系统提示告诉模型是谁，工具给可调用的代码能力

Agent 循环让模型决定继续调工具还是收工,转换层让换模型不改工作流

四个工具让模型高效运转不受太多约束，也方便拿来二开

官方的一些方案也很有意思，我也很赞同，尤其是mcp与主子Agent

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，要配送才考虑 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生态项目

这些项目没啥好说的，萝卜青菜各有所爱

实际上我只装了浏览器cli，web搜索，subagent让他Bash pi再启动，和一个远程连接的工具，剩下的没了

7. 排错