用 Pi Agent 打造独属于你的 AI Harness

听说 Pi Agent 很久了，一直没有时间来得及尝试，换一个自己不熟悉的 Coding Agent 还是有一定的成本的。

我过去一段时间里一直尝试过不同的 Coding Agent，从 Claude Code、Codex、OpenCode、Kimi Code 等，都是为了使用它们自家的模型，它们都有一个很明显的趋势，工具越来越完整，模型能力也越来越强。

Plan、Todo、Subagent、Web Search、MCP、Skills、LSP、Permission、Context Management ...... 基本上能够做到开箱即用的地步。

但随着对 AI Coding 的需求量越来越大，在不同的 Agent 之间切换，个人整套的工作流执行得不是很稳定，每个 Agent 都有一套预设的工作方式。

images-20260823-22.39.06@2x

Pi Agent 走的是极简的模式，拥有最小的内核以及丰富的扩展生态，全部都是开源，可以按照个人喜好快速增加想要的能力。有个问题大家不妨思考下？

当模型本身能力越来越强时，我们到底需要一个多复杂的 AI Harness？是预设的工作流好还是用户自行定义的好呢？

Pi Agent 到底是什么？

Pi 不只是一个 Coding CLI，它更接近一个可以持续扩展和嵌入的 Agent Runtime。核心可以简单理解成 4 层：

pi-ai：负责模型和 Provider，基本上可以对接大部分主流的 Coding 订阅账号或者 Api Key 访问。
pi-agent-core：负责 Agent Loop、Messages、Tools 和 State。
pi-coding-agent：在 Agent Core 上增加 Coding 能力。
pi-tui：负责 Terminal 中的交互界面。

默认情况下，最基础的几个 Tool 只有：read / write / edit / bash，另外还有 grep / find / ls 三个内置 Tool，可以按需开启。

至于很多 Coding Agent 已经默认具备的能力，例如 Web Search、Subagents、Permission、Plan、Todo、MCP 等，并没有全部塞进 Core。

这里最容易产生一个误解：Pi 并不是"功能还没做完"。

相反，这是它主动做出的架构选择。它认为这些能力并不一定适合所有人，也不应该强制成为每一个 Agent 的基础组成部分。

images-20260823-22.52.22@2x

Bash 本身已经可以调用大量成熟的开发工具。但专用 Tool 当然也有价值，它可以提供更加结构化的输入输出，让模型更容易正确调用，也能减少 Shell 命令拼接错误。但 Tool 数量更多，并不直接意味着 Coding 效果一定更好。

PI 自定义配置实战

Pi 的设计理念是极简模式，但是也是可以需要什么补什么的，扩展性和可玩性非常灵活。但是前期还是建议以少量为主。

01 安装

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

02 基础配置

在终端使用 pi 命令，进入 tui 界面：

使用 /login 命令，添加订阅账号或者 API Key，将你想要使用的模型添加进来，支持 Anthropic、Codex、Kimi、xAI 等订阅账号。也可以将 OpenCode 、DeepSeek 的 API Key 对接进来。基本上实现了所有主流模型的全量适配。

使用 /scoped-models 命令，只启用你需要使用的模型，不然大量的模型列表，选择起来非常的困难，一般只需要使用几个即可，用于不用的场景。

在 ~/.pi/agent/settings.json 中扩充的工具箱，加入 grep / find / ls 这三个内置 Tool：

  "defaultTools": [
    "read",
    "bash",
    "edit",
    "write",
    "grep",
    "find",
    "ls"
  ]

记住一些常用的快捷键，能够事半功倍：

Ctrl+L：打开模型选择器
Ctrl+P：切换到下一个 Scoped Model
Ctrl+Shift+P：切换到上一个 Scoped Model
Shift+Tab：切换当前模型的推理级别
Esc：中断当前模型运行
Ctrl+O：展开/折叠工具调用结果
Ctrl+T：展开/折叠 Thinking 内容
Enter：放入 Steering Queue，当前这一轮工具调用结束后，下一次模型调用立即看到
Alt/Option + Enter: 放入 Follow-up Queue，等当前整个任务完成后再执行

03 配置扩展

官方有一个扩展包下载广场，里面收录了非常多的 Package。下面推荐的包名直接在里面搜索就行。

images-20260823-23.16.17@2x

Pi 有一个 Prompt Template 的概念，很容易和 Skills 搞混。我的理解是 Prompt Template 是告诉 Agent 这次做什么，Skills 是告诉 Agent 怎么做。

Pi 核心资源和定制机制大概分为 4 类：System Prompt、Prompt Templates、Skills 以及 Extensions。

接下来列一下个人推荐的几个插件，以最小为目标，可以自行在官网按需搜索。

pi-web-access （必须）：提供网络搜索能力。
@gotgenes/pi-permission-system（必须）：提供安全沙箱，Pi 默认是完全开放的，尤其是 Bash ，基本上直接运行在当前用户环境。
pi-open-tui（可选）：一个好的 UI 界面，在日常开发过程中体验会大大增强，它不会改变 Agent 的 Coding 能力，只是让 Terminal 中的信息展示更加舒服。
@gotgenes/pi-subagents（可选）：本身单 Agent 可以完成大部分的任务了，也是一个可选能力。还有一个比较主流的 subagents 插件是 pi-subagents。它们的设计理念不同，一个是在主 Agent 中派发多个 Worker 去工作，然后汇总；一个是派生出不同能力的 Agent，类似于 Multi Agent，用于不同场景下的任务执行。

使用 permission 插件的话，需要进行额外的配置，我的配置思路是，配置关键的黑名单即可，避免大量的 Ask Approval 动作。

{
  "permission": {
    "*": "allow",

    "path": {
      "*": "allow",
      "*.env*": "deny",
      "*.env.example": "allow"
    },

    "bash": {
      "*": "allow",
      "git commit*": "ask",
      "git push*": "ask",
      "pnpm dev*": "ask",
      "*gradlew*bootRun*": "ask",
      "sudo *": "ask",
      "rm -rf *": "deny",
      "git push --force*": "deny"
    },

    "external_directory": {
      "*": "allow",
      "~/.ssh/*": "deny"
    }
  }
}

以下是我配置好的界面：

images-20260823-00.55.23@2x

PI 相较于其他 Coding Agent 的优势

最核心的点是 Pi 足够轻量，能把 Harness 的控制权交给用户。以下是个人的几个观点，仅供参考，毕竟每个人的情况差异比较大：

不想要被固定的 Harness 绑住：当你需要在不同模型之间切换，也已经有了自己的一套 Skills、规则和工作流。Pi 不强迫你接受一整套预设的工作方式。来达到：Agent 无关、模型可切换、工作流自己掌握。
希望强模型直接发挥，而不是被过重的 Agent 逻辑干扰：很多任务只需要少量的工具，加上代码库作为上下文，结合强模型就能够高效的完成。例如：SDD 文档的生成。我对比过在 Codex CLI 和 PI 同样都使用 GPT 5.6 Sol High，Pi 要快得多，生成的质量差不多，但是消耗的 Token 大幅减少。
你很在意上下文和 Token 成本：这也是我使用 Pi 最大的原因之一，现在几乎所有主流模型厂商都在削减订阅的用量，各种黑箱操作层出不穷，加价但是减量！所以自己可控的工具和工作流，主动减少内置 Agent 大量无用上下文的加载，变得重要起来。再加上我现在倾向于执行长时任务，多端任务一次 loop 完成，项目中需要加载的上下文非常多。但现在长上下文任务有两个非常恶心的地方，一是 Agent 频繁压缩上下文，导致核心项目上下文丢失，典型代表 Codex；二是超过一定上下文之后模型价格翻倍，如：Grok Build CLI > 200K 之后。
多模型、订阅额度和 Agent 解耦对你很重要：你不希望为了换一个 Agent 就重新买一套 API，也不希望模型额度被某个 CLI 绑死。你更偏向：同一套模型/订阅额度，Pi、OpenCode、Hermes 等 Harness 可以自由切换使用。

总之一句话就是：

你切到 Pi，不是因为它比 Claude Code / Codex / OpenCode 功能更多，而是因为它终于让 “模型、Harness、Skills、权限、Subagents” 这些东西重新解耦了，你可以自己决定 Agent 应该长什么样。

我的建议可以先并行一起使用，最终真正应该比较的，是实际任务中的:

完成质量
稳定性
Context 使用
Token 消耗
以及最后还需要多少人工返工

而不是谁的功能列表更长。

最后

上手 Pi Agent 非常快，组合安装自己想要的插件也很容易，不妨试下。回头想想：代码库（上下文） + 强模型 + 极简 Harness 也许是一条可行的路线。

Pi Agent 到底是什么？

Pi 不只是一个 Coding CLI，它更接近一个可以持续扩展和嵌入的 Agent Runtime。核心可以简单理解成 4 层：

pi-ai：负责模型和 Provider，基本上可以对接大部分主流的 Coding 订阅账号或者 Api Key 访问。
pi-agent-core：负责 Agent Loop、Messages、Tools 和 State。
pi-coding-agent：在 Agent Core 上增加 Coding 能力。
pi-tui：负责 Terminal 中的交互界面。

默认情况下，最基础的几个 Tool 只有：read / write / edit / bash，另外还有 grep / find / ls 三个内置 Tool，可以按需开启。

至于很多 Coding Agent 已经默认具备的能力，例如 Web Search、Subagents、Permission、Plan、Todo、MCP 等，并没有全部塞进 Core。

这里最容易产生一个误解：Pi 并不是"功能还没做完"。

相反，这是它主动做出的架构选择。它认为这些能力并不一定适合所有人，也不应该强制成为每一个 Agent 的基础组成部分。

images-20260823-22.52.22@2x

Bash 本身已经可以调用大量成熟的开发工具。但专用 Tool 当然也有价值，它可以提供更加结构化的输入输出，让模型更容易正确调用，也能减少 Shell 命令拼接错误。但 Tool 数量更多，并不直接意味着 Coding 效果一定更好。

PI 自定义配置实战

Pi 的设计理念是极简模式，但是也是可以需要什么补什么的，扩展性和可玩性非常灵活。但是前期还是建议以少量为主。

01 安装

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

02 基础配置

在终端使用 pi 命令，进入 tui 界面：

使用 /scoped-models 命令，只启用你需要使用的模型，不然大量的模型列表，选择起来非常的困难，一般只需要使用几个即可，用于不用的场景。

在 ~/.pi/agent/settings.json 中扩充的工具箱，加入 grep / find / ls 这三个内置 Tool：

  "defaultTools": [
    "read",
    "bash",
    "edit",
    "write",
    "grep",
    "find",
    "ls"
  ]

记住一些常用的快捷键，能够事半功倍：

Ctrl+L：打开模型选择器
Ctrl+P：切换到下一个 Scoped Model
Ctrl+Shift+P：切换到上一个 Scoped Model
Shift+Tab：切换当前模型的推理级别
Esc：中断当前模型运行
Ctrl+O：展开/折叠工具调用结果
Ctrl+T：展开/折叠 Thinking 内容
Enter：放入 Steering Queue，当前这一轮工具调用结束后，下一次模型调用立即看到
Alt/Option + Enter: 放入 Follow-up Queue，等当前整个任务完成后再执行

03 配置扩展

官方有一个扩展包下载广场，里面收录了非常多的 Package。下面推荐的包名直接在里面搜索就行。

images-20260823-23.16.17@2x

Pi 有一个 Prompt Template 的概念，很容易和 Skills 搞混。我的理解是 Prompt Template 是告诉 Agent 这次做什么，Skills 是告诉 Agent 怎么做。

Pi 核心资源和定制机制大概分为 4 类：System Prompt、Prompt Templates、Skills 以及 Extensions。

接下来列一下个人推荐的几个插件，以最小为目标，可以自行在官网按需搜索。

pi-web-access （必须）：提供网络搜索能力。
@gotgenes/pi-permission-system（必须）：提供安全沙箱，Pi 默认是完全开放的，尤其是 Bash ，基本上直接运行在当前用户环境。
pi-open-tui（可选）：一个好的 UI 界面，在日常开发过程中体验会大大增强，它不会改变 Agent 的 Coding 能力，只是让 Terminal 中的信息展示更加舒服。
@gotgenes/pi-subagents（可选）：本身单 Agent 可以完成大部分的任务了，也是一个可选能力。还有一个比较主流的 subagents 插件是 pi-subagents。它们的设计理念不同，一个是在主 Agent 中派发多个 Worker 去工作，然后汇总；一个是派生出不同能力的 Agent，类似于 Multi Agent，用于不同场景下的任务执行。

使用 permission 插件的话，需要进行额外的配置，我的配置思路是，配置关键的黑名单即可，避免大量的 Ask Approval 动作。

{
  "permission": {
    "*": "allow",

    "path": {
      "*": "allow",
      "*.env*": "deny",
      "*.env.example": "allow"
    },

    "bash": {
      "*": "allow",
      "git commit*": "ask",
      "git push*": "ask",
      "pnpm dev*": "ask",
      "*gradlew*bootRun*": "ask",
      "sudo *": "ask",
      "rm -rf *": "deny",
      "git push --force*": "deny"
    },

    "external_directory": {
      "*": "allow",
      "~/.ssh/*": "deny"
    }
  }
}

以下是我配置好的界面：

images-20260823-00.55.23@2x

PI 相较于其他 Coding Agent 的优势

最核心的点是 Pi 足够轻量，能把 Harness 的控制权交给用户。以下是个人的几个观点，仅供参考，毕竟每个人的情况差异比较大：

不想要被固定的 Harness 绑住：当你需要在不同模型之间切换，也已经有了自己的一套 Skills、规则和工作流。Pi 不强迫你接受一整套预设的工作方式。来达到：Agent 无关、模型可切换、工作流自己掌握。
希望强模型直接发挥，而不是被过重的 Agent 逻辑干扰：很多任务只需要少量的工具，加上代码库作为上下文，结合强模型就能够高效的完成。例如：SDD 文档的生成。我对比过在 Codex CLI 和 PI 同样都使用 GPT 5.6 Sol High，Pi 要快得多，生成的质量差不多，但是消耗的 Token 大幅减少。
你很在意上下文和 Token 成本：这也是我使用 Pi 最大的原因之一，现在几乎所有主流模型厂商都在削减订阅的用量，各种黑箱操作层出不穷，加价但是减量！所以自己可控的工具和工作流，主动减少内置 Agent 大量无用上下文的加载，变得重要起来。再加上我现在倾向于执行长时任务，多端任务一次 loop 完成，项目中需要加载的上下文非常多。但现在长上下文任务有两个非常恶心的地方，一是 Agent 频繁压缩上下文，导致核心项目上下文丢失，典型代表 Codex；二是超过一定上下文之后模型价格翻倍，如：Grok Build CLI > 200K 之后。
多模型、订阅额度和 Agent 解耦对你很重要：你不希望为了换一个 Agent 就重新买一套 API，也不希望模型额度被某个 CLI 绑死。你更偏向：同一套模型/订阅额度，Pi、OpenCode、Hermes 等 Harness 可以自由切换使用。

总之一句话就是：

你切到 Pi，不是因为它比 Claude Code / Codex / OpenCode 功能更多，而是因为它终于让 “模型、Harness、Skills、权限、Subagents” 这些东西重新解耦了，你可以自己决定 Agent 应该长什么样。

我的建议可以先并行一起使用，最终真正应该比较的，是实际任务中的:

完成质量
稳定性
Context 使用
Token 消耗
以及最后还需要多少人工返工

而不是谁的功能列表更长。

最后

上手 Pi Agent 非常快，组合安装自己想要的插件也很容易，不妨试下。回头想想：代码库（上下文） + 强模型 + 极简 Harness 也许是一条可行的路线。

Pi Agent 到底是什么？

PI 自定义配置实战

01 安装

02 基础配置

03 配置扩展

PI 相较于其他 Coding Agent 的优势

最后

推荐阅读

更多文章

Pi Agent 接入 Grok 的上下文管理实战

从 Pi 压缩机制到 Handoff 技能实战

使用 Pi Agent 搭建个人开发工作流实战

用 Pi Agent 打造独属于你的 AI Harness

Pi Agent 到底是什么？

PI 自定义配置实战

01 安装

02 基础配置

03 配置扩展

PI 相较于其他 Coding Agent 的优势

最后

推荐阅读

更多文章

Pi Agent 接入 Grok 的上下文管理实战

从 Pi 压缩机制到 Handoff 技能实战

使用 Pi Agent 搭建个人开发工作流实战