pi agent快速入门和插件

Pi agent快速入门

模型的选择

思考强度

  • flash 模型, 没必要将think level调到max, 就像对于个智力一般的人思考更长时间也很难解决一个复杂数学难题, 但适当调高确实可以提升它的能力.
  • pro 模型, think level至少调为 high , 这样更能给出优质的答案.
  • 不同的模型通常会有几档可用档次的思考强度, pi agent内部维护着 agent 和 模型思考强度mapping关系.

按场景使用不同的模型

  • 可以在具体的 task markdown文档中, 通过内嵌 yaml的 frontmatter 语法, 为特定任务设定不同的模型. 但对于 SKILL.md, 因为pi启动时候为了节省skill中token消耗, 仅仅加载frontmatter中的name/description, 而忽略其他内容, 所以在后续skill执行中, 使用的当前回话的主模型, 并不会切换模型.
  • 也可以安装 pi-model-router 这样的插件, 统一确定模型路由规则.
  • 也可以在 bifrost AI 网关, 通过和自己的 routing rules设定路由规则.

session 和 run 和 turn 的关系

  • turn 一次模型请求+它的工具执行(3个工具仍算1 turn)
  • run 可包含多个 turn, 对应一个完整的 agent loop
  • session 可以包含多个 run

prompt模版和skill的对比

  • prompt是由人显示触发调用 调用方法是 /prompt_name , skill 通常由LLM自动按需调用, 当然也可以通过 /skill:skill_name 方式做确定性调用
  • prompt 通常只包含一个文本指令, skill通常包含指令/操作规范/可选脚本, 因此可以实现复杂的操作.
  • 上下文加载方式的不同, prompt模板不会在pi agent启动后自动加载, 而是由人手工调用加载, skill会在pi agent启动时加载少量信息, 在大模型确定需要此skill会加载全部markdown内容.

快速入门

-pi list 命令, 显示安装了哪些 package
-pi config 命令, 可以配置需要启用哪些 extension, 主要是在某个extension导致 pi 无法正常启动后使用.
-pi启动后, 可以输入 ctrl+O , 进一步查看使用指南, 以及加载了哪些extension/skill和常用快捷键.
-pi作者对于pi设计的思考 https://mariozechner.at/posts/2025-11-30-pi-coding-agent/ -中文使用 https://news.qiniu.com/archives/1787103478559#容器化与沙箱 -安装插件之前, 需要查看安装量和github issue, 至少通过 pi agent 检查一下这个插件的安全性(是否包含恶意代码、后门、网络外联、遥测或混淆代码)

理解 bash 工具 和 codemode 的区别

codemode 在pi 1.3中默认是没有启用的, 但即使是没有启用, 也不影响 pi agent 使用 bash 脚本来做一些事情(其实是大模型生成的bash脚本), 比如我问今天上海的天气如何, 或者问今天是几号, pi agent 会自动生成bash 脚本, 通过一个或几个bash脚本的执行完成了答复.

codemode 模式是, 允许大模型生成 javascript 脚本, pi agent 将js 脚本放入到 quickjs 沙箱中(wsam)中执行, 对比上面 bash 脚本方式, codemode 往往一个脚本就能直接获得答案, 使用 bash 脚本往往需要多轮执行, 所以codemode速度更快而且确定性更好.

token 节省

在流行的几款AI coding agent工具中, pi code已经是最节省token的工具, 一般情况下没有必要再使用更复杂的token节省策略了.

  1. sol-pi

安装命令:

pi install npm:@herbertgao/sol-pi

英伟达NVlabs/SoL-Pi项目还可以再降低更多token, 输出质量仅有少量降低(94%). 该插件提供4个类型的token使用优化机制, 我们一般开启 actionFusion 和 observationPack 两个local机制就可以, 修改项目级配置文件 .pi/sol-pi.json 或 用户级配置我文件 ~/.pi/agent/sol-pi.json

{
  "version": 1,
  "actionFusion": true,
  "observationPack": true,
  "evidencePreservingReducer": false,
  "onlineContextCompact": false,
  "cacheWriteReadRatio": 12.5
}

prompt 管理

  1. prompt模版路径

    可将常用prompt保存到文件系统, 方便以后反复使用.
    全局生效（所有项目可用）：保存至用户主目录下的 .pi/prompts/ 文件夹。

    • Windows 路径：C:\Users<用户名>.pi\prompts\
    • 项目独享（仅当前工作区可用）：保存至当前项目根目录下的 .pi/prompts/ 文件夹。

  2. prompt Markdown 模板示例

    下面是一个codereview prompt模版:

    ---
description: 检查当前代码改动的潜在问题与性能隐患
---

请对我提交的代码改动进行详细 Code Review，重点关注：

1. 是否存在内存泄漏或潜在的边界异常
2. 变量与方法命名是否清晰规范
3. 是否符合项目的模块化规范

请给出具体的修改方案与优化后的示例代码。

    prompt 模版支持传入参数, $ARG 为模版使用时输入的完整参数清单, $1 为第一个参数, $2 为第二个参数, 以此类推

    下面是一个explan prompt模版:

---

## description: 解释指定的函数或架构概念

请使用通俗易懂的语言详细解释以下内容：
$ARG

请提供：

- 核心原理解析
- 典型的应用场景
- 简短的代码示例

  3. prompt的调用

    在pi终端输入区, 输入: /prompt文件名 (不要加上.md 后缀)

  4. pi-prompt-template-model

    为prompt预设模型, 而不是使用当前会话的模型, 设定的方式是, prompt template中, 增加如下 frontmatter

    ---
description: Debug Python in tmux REPL
model: claude-sonnet-4-20250514
thinking: off   合法取值有  off, minimal, low, medium, high, xhigh, or max.
---

    安装命令:

    pi install npm:pi-prompt-template-model

skill 增强插件

  1. rpiv-args

安装命令:

pi install npm:@juicesharp/rpiv-args

正常情况下 skill 不同与 prompt template, 后者允许在注入prompt时候给template传入一些参数, 而 skill 后面只能将用户传入一个自然语言指令, 由大模型从这个自然语言中理解其中关键信息, 最终生成一个工作流, 但我们可以安装 rpiv-args 扩展, 它允许我们在skill内部直接使用 $1 $2 $ARGUMENTS 这样的参数, 这样能规避大语言模型理解的不确定性, 这对于需要高确定性的场景非常有用, 当然需要该插件仅限于将 SKILL.md 文件完成参数替换, script 脚本中的$1 还是按照linux的方式做处理.

比如, 我们创建了一个deploy技能, 文件存放在 .pi/skills/deploy/SKILL.md , 其中包含两个参数.

---
name: deploy
description: Deploy a service to an environment
---

Deploy service $1 to $2.
Current branch: !`git branch --show-current`

调用技能的命令为:

/skill:deploy api production

结构化 chat 问答

  1. rpiv-ask-user-question

安装命令:

pi install npm:@juicesharp/rpiv-ask-user-question

使用的方法很简单, 在对话的文字中, 特别说出请使用 ask-user-question 来帮我做什么什么事情, 描述的越具体越好, 这个插件会根据上下文以及当前项目的信息, 以及你提问的意图, 形成一个问题选项卡供用户选择.

网页搜索插件

  1. pi-web-access
    pi agent可以使用bash + curl的方式, 做一些基础的搜索功能, 高级的搜索需要开通搜索服务+搜索插件, 比如deekseek就提供search/fetch api, 最常用的插件是 pi-web-access, 使用插件的优势有:
  • 经常要「搜索 → 读原文 → 引用来源」的调研类任务
  • 要读 JS 渲染页、Readability/Defuddle 提取正文、PDF、GitHub 仓库、视频
  • 需要稳定、可切换 provider、可配 key/路由
  • 需要批量搜索、长会话里反复取用已抓内容

会话管理

  1. pi-memory
    PI 原生没有跨会话的记忆能力, 在长期开发的项目中, 我们不希望每次开会话, 都需要不断告诉它这个项目是什么, 有什么约定. 这时候就需要使用一些跨会话的memory插件, pi-memory 和 pi-hermes-memory 插件都可以很好的解决这个问题, 其中 pi-memory 相对更加轻量级一些, 所有记忆都存储到md文件中, pi-hermes-memory 相比更加重量级一些, 后者会将记忆分成项目级(MEMORY.md), User级(USER.md) 和过程类型(SKILL.md), 并会在 sqlite 中为session history 建立全文搜索 index, 另外 pi-hermes-memory 插件,而每隔一定轮次就启动后台学习进程, 进行记忆复盘并萃取成 skill .

    pi-memory 更加轻量, 而且记忆存储更加透明, 可以随时手工更新markdown文件, 所以我更加推荐, pi-memory 的分层记忆: - 长期记忆, MEMORY.md - 待办任务, scratchpad - 日常日志, daily 目录的下的md文件 - 可选装轻量级的语义检索工具 qmd , 可实现持语义检索, 更容易找到相关记忆.

    记忆更新方式非常灵活多样, 可以直接在对话框中告知agent, 将某些信息写入到记忆中, 也可以直接下命令删除某个记忆, 也可以手工编辑markdown文件完成记忆的更新

    安装命令:

    pi install npm:pi-memory

    并提供多个slash命令:

       Tool	Description
    memory_write	Write to MEMORY.md (long-term) or daily log
    memory_forget	Delete matching entries and create a durable recovery record
    memory_restore	Restore a deletion using the recovery ID returned by memory_forget
    memory_read	Read any memory file or list daily logs
    scratchpad	Add/done/undo/clear/list checklist items
    memory_search	Search across all memory files (requires qmd)
    memory_status	Health check: where files live, qmd/collection/embeddings state, active config

  2. pi-context-view

    安装命令:

    pi install npm:pi-context-view

    通过 /context 命令可以对上下文用量做可视化的展现, 比如system prompt/user message/tool calls/tool output等, 这个插件非常值得安装, 可以帮我们更好了解pi agent与大模型交互过程.

subagents 管理

  1. pi-subagents 安装量最大的那个

    其他很多subagents插件, 会要求操作系统是linux或者装WSL, 这个插件在windows下的兼容性很好.
    使用 subagent 的优点有, (1)每个subagent和主agent的上下文是隔离的, 防止旁路任务污染主agent的上下文, 包含: 一般情况下该插件会为子agent提供要给干净上下文, 另外子agent的运行过程生成的文字也不会带回到主agent中, 只有subagent运行的结果传回给主agent. 也就是说主agent只关注子agent的结果而不关注过程. (2)每个subagent都是一个单独的进程, 所以不会阻塞主agent进程.

    本插件底层并没有使用类似 langgraph 框架的DAG来调度各个子代理, 而是使用 js 语言的顺序和并行控制语句实现子代理之间的串行/并行协调, 各个代理之间使用 json/jsonl 文件来传递消息, 并没有引入什么消息总线, 每个child agent都是一个完整的 runtime 进程.

    安装命令:

    pi install npm:pi-subagents

    插件安装完毕后, 会增加若干个命令(以subagents开头的) 和skill.
    subagents-guide 命令, 能显示内置的agent 角色, 包括 scout(侦察兵)/researcher/evidence-auditor/worker/review/oracle(适合在行动之前再挑毛病).
    subagents-stop 命令, stop 运行中的subagent.

    启动subagent的方法: 在chat中, 需要我们明确agent, 含糊表述主agent可能并不会启动subagent. 通常的话术是: 请使用 scout 角色做进行代码理解, 然后使用 worker 进行编码, 然后使用review 角色进行代码审查, 使用 oracle 角色进行风险分析.

  2. pi-btw
    在处理某个事情的过程中, 经常会突然想起个什么事情, 比如查询某个函数有哪些引用, 就可以使用 btw 工具, pi agent 不等当前会话是否完成, 会立即启动一个新的会话来处理这个临时指令, 默认情况下, 不会将处理结果返回到主会话中.
    使用 ECS 快捷键可关闭btw窗口

    安装命令:

    pi install npm:pi-btw

    usage:

    /btw what file defines this route?
/side what file defines this route?
/btw how would you refactor this parser?
/btw --save summarize the last error in one sentence
/btw:new let's start a fresh thread about auth
/btw:tangent brainstorm from first principles without using the current chat context
/btw:ask what does this module do?
/btw:ask --save explain the latest test failure
/btw:model openai gpt-5-mini openai-responses
/btw:thinking low
/btw:inject implement the plan we just discussed
/btw:summarize turn that side thread into a short handoff
/btw:clear

  3. pi-dynamic-workflows
    安装命令:

    pi install npm:@quintinshaw/pi-dynamic-workflows

    这个插件和 pi-subagents 插件有部分功能重叠, 但它的重点是提供一个可编程的多agent协调workflow, 当然我们无需自己写workflow代码, 可由AI agent写, 写好后的workflow代码再交由AI agent执行, 就能按照预设的workflow完成多agent的编排.

    这个插件除了支持可编程编排特性外, 还提供给强大的TUI交互面板(通过/workflows 命令)和持久化的 journal 日志, 如果某个节点失败, 可以在后台面板中进行检查, 甚至支持断点续跑(resume)功能.

    下面是一个固定流程的示例, 基本能满足绝大多数情况, 其实该插件更厉害之处, 就是可以按照用户要求, 生成动态的流程结构, 即由顶层Agent动态规划流程结构, 然后在codemode沙箱动态执行, 这就是一个Meta-Agent架构, 后面另起一个博文介绍.

    固定流程示例, 要实现一个 A -> (B1//B2) -> C -> D 这样的既有串行又有并行的workflow, 可以先让AI按照codemode方式生成workflow脚本代码, 提示语为:

      请使用 @quintinshaw/pi-dynamic-workflows 来构建一个A->(B1//B2)->C->D的这样工作流, 每个节点也都是一个子agent, 工作流的构建使用pi 的codemode构建, 请生成对应的codemode 代码

    AI生成代码如下:

    // 1. 执行节点 A
const resA = await agent("Prompt for node A...", {
  model: "medium",
  effort: "medium",
});

// 2. 并行执行节点 B1 和 B2 (对应 B1 // B2)
const [resB1, resB2] = await parallel([
  () =>
    agent(`Prompt for B1 using input from A: ${resA}`, { model: "small" }),
  () =>
    agent(`Prompt for B2 using input from A: ${resA}`, { model: "small" }),
]);

// 3. 汇聚节点 C (处理 B1 和 B2 的输出)
const resC = await agent(
  `Prompt for C, consolidating B1 and B2 results:\nB1: ${resB1}\nB2: ${resB2}`,
  { model: "big" },
);

// 4. 最终节点 D
const finalResult = await agent(
  `Prompt for final step D using input C: ${resC}`,
  { model: "medium" },
);

return finalResult;

项目管理插件

  1. pi-init

    安装命令:

    pi install npm:@bacnh85/pi-init

    为pi agent当前目录做项目初始化, 提供一个命令 /init, 它会检视当前项目编译工具是什么, 然后确定项目变成语言, 最后自动为当前目录创建合适的 AGENTS.md 文件和内容.

  2. pi-project-switcher
    如果PI agent管理了很多项目, 来回切换当前项目, 很不方便, 可安装这个插件, 将所有项目放置到一个公共的workspace目录下, 然后使用这个插件就很方便切换项目

    安装命令:

    pi install npm:pi-project-switcher

    使用方式:
    首先, 创建一个 pi-project-switcher 配置, 配置文件名: C:\Users\username.pi\agent\project-switcher.json
    配置文件中需要指定这个公共workspace的路径, 比如:

    然后, 使用 /project 命令切换

    使用该命令可切换当前项目, 但在pi中的当前的目录还是保持原样.
    当前项目验证: 直接在pi中询问当前项目名
    当前目录验证: 使用命令, !! cwd

安全管理

  1. cc-safety-net

cc-safe-net 插件不是一个沙箱(备注:windows下目前没有可用的沙箱方案), 而是一个shell命令的防护, 具体为它对bash命令在执行前做检查, 如果识别出这是一个有风险的命令, 则会被阻止, 比较神奇的是它的判断的依据是按照命令的实际作用(通过分析引擎), 而非简单的字面内容比较.

需要说明的是, 该插件并不能阻止codemode js脚本中的破坏性操作, 但可以拦截codemode tools.bash(command) 中的破坏性操作.

它提供多种命令阻止模式:

  • standard: 默认模式, 阻止所有内置规则识别出的破坏性 Git 和文件系统操作。
  • strict: 除了standard规则, 还包括所有无法解析的命令, 无法验证破坏性的命令
  • paranoid: 除了strict规则, 还包括当前工作目录内的一些递归删除命令, 比如 rm -r 等

安装命令:

pi install npm:cc-safety-net

编程资料查询

  1. context7-pi

安装命令:

pi install npm:@upstash/context7-pi

查询流行库和工具对应编程文档, 使用方式非常简单, 只需要用自然语言告诉大模型要查什么就行, 比如: 请查询如何进行Next.js 16 版的缓存配置

编程相关

  1. ponytail

安装命令:

pi install npm:@dietrichgebert/ponytail

AI 写的代码通常太过啰嗦和复杂, 很多时候没有必要, 长期看这样做增加了代码的维护成本, 这个插件就是致力解决这个问题. 安装后, 在代码生成和评审阶段都可以像资深程序员一样给出不过度编码的真知灼见, 该插件的工作原理其实很简单, 该插件会在AI agent很多hook点注入精简代码的prompt到上下文中.

代码精简的几个不同强度档位ladder:

  • lite：温和版，正常实现需求，但会顺便提一句"其实有更懒的写法"
  • full（默认）：严格执行 ladder
  • ultra：YAGNI 极端主义者，能删就删，先质疑需求合不合理再写
  • off：关闭

配套的slash 命令:

  • /ponytail-review 审核当前的change diff
  • /ponytail-audit 审核当前repo
  • /ponytail-debt 追踪被我们延后的精简项
  • /pony-gain 查看影响指标

界面美化

  1. pi-powerline-footer

    为 pi tui 提供一个更好看的 footer, 能显示模型/思考强度/当前工作目录/git分支/context窗口占用情况/cache命中/费用.

    安装命令:

    pi install npm:pi-powerline-footer

  2. pi-quota

    在状态栏增加当前回话花费以及剩余钱包, 并提供 /usage 命令

    安装命令:

    pi install npm:@astrosheep/pi-quota

spec 驱动开发(暂时没有使用)

  1. @pi-unipi/workflow

安装命令:

pi install npm:@pi-unipi/workflow

典型的工作流程为:
brainstorm → plan → work → review-work → consolidate
↑ │
└────────────────────────────────────────┘

对应的命令:

# 1. Brainstorm an idea
/unipi:brainstorm redesign auth system

# 2. Create implementation plan
/unipi:plan specs:2026-04-26-auth-redesign-design

# 3. Execute plan in worktree
/unipi:work worktree:feat/auth specs:2026-04-26-auth-redesign-plan

# 4. Review what was built
/unipi:review-work plan:2026-04-26-auth-redesign-plan

# 5. Consolidate learnings
/unipi:consolidate

文档目录结构:

.unipi/
├── docs/
│   ├── specs/          ← brainstorm output (design specs)
│   ├── plans/          ← plan output (implementation plans)
│   ├── generated/      ← document output (docs, guides)
│   ├── reviews/        ← review remarks (in plan docs)
│   ├── debug/          ← debug reports
│   ├── fix/            ← fix reports
│   ├── quick-work/     ← quick-work summaries
│   └── chore/          ← reusable chore definitions
├── memory/             ← consolidate memory
├── ralph/              ← ralph loop state

mcp 安装

需要安装哪些mcp工具, 可到 MCP marketplace 和 awesome清单找.
https://github.com/punkpeye/awesome-mcp-servers
https://registry.modelcontextprotocol.io/

pi agent已经内置了mcp功能, 我们可以直接使用该功能增加mcp server, 下面是增加github mcp server的命令过程:

  1. 准备 GitHub 个人访问令牌 (PAT)

    进入 GitHub -> Settings -> Developer settings -> Personal access tokens -> Fine-grained tokens（或经典的 Tokens (classic)）。

生成一个 Token，并勾选你需要的权限（例如 repo、issues、pull_requests 的读写权限）。

复制生成的 Token 字符串备用。

  2. 使用 pi mcp 命令安装该mcp server

    pi-mcp-adapter, pi-mcp-adapter是更早的社区方案，比pi内置的mcp功能更丰富（如支持 OAuth等）, 两者最终都读写同一套 mcp.json 配置文件，因此无论通过哪种方式添加，配置都是互通的。

    如下命令安装后, 会在 ~/.pi/agent/mcp.json 增加对应的server,

    pi mcp add github_mcp --env GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_GitHub_Token -- npx -y @modelcontextprotocol/server-github

参数:
 github_mcp 是我们给该mcp server起的名字
 npx -y @modelcontextprotocol/server-github：代表通过 Node.js 的 npx 动态拉取并运行官方的 GitHub MCP 服务。

  3. 安装检查mcp清单

    下面命令会列出所有已配置的 MCP 服务器，并显示它们的连接状态和可用工具数量。
    也可以在pi中, 使用 /mcp 来查看.
    故障排查：如果服务器未能连接，可以查看 ~/.pi/agent/mcp.log 获取详细错误信息，或在 Pi 会话中运行 /mcp 查看连接失败的原因。

    pi mcp list
posted @ 2026-10-19 21:29  harrychinese  阅读(108)  评论(0)    收藏  举报