用 Pi 学习 Agent 怎么运行

Thu, 09 Jul 2026 12:00:00 +0800

pi 是学习 harness 的好帮手

想搞懂一个 agent 到底怎么跑起来，最好的办法不是读别人的文章，而是拿一个真正可观察的 agent 自己跑一遍。

agent = model + harness。

model 做的事很单纯——收到一个 messages 列表，返回一段文本。它不知道文件系统在哪、不知道你项目里有什么、不知道上一次对话发生了什么。
harness（中文是缰绳还是线束什么的，随便把，反正是把模型和外部环境连起来的那一层）是让模型"变聪明"的关键：它把模型包进一个循环，负责拼装上下文、调用工具、把结果塞回下一轮对话。

harness 的核心是一个循环：

拼装 system prompt + 历史消息 → HTTP 请求体
发给模型 API，拿到响应
解析响应——是普通文本还是 tool call？是 tool call 就执行
把执行结果塞进下一轮的 messages，回到第 1 步
模型不再调工具，结束

想理解 agent，就得理解这个循环。而 pi 是学这个最好的工具。

例如可以让它帮你理解 harness 过程，因为它极度透明

大多数 agent 工具把和模型的对话过程藏起来，你只能看到最终输出的文本。pi 不一样：它把整个生命周期都暴露成事件——session 启动、消息拼装、API 请求发出去之前、响应回来之后、工具执行……每一个节点你都能插手。

换句话说，harness 在 pi 里不是黑盒，而是一组你能监听的事件。理解 agent 怎么运行，本质上就是理解 harness 在那个循环里做了什么——而 pi 让你直接看见它，甚至改写它。

比如我们可以让它展示在请求大模型时发送的 HTTP 内容

一个直接的例子：让 pi 展示它发给大模型 API 的完整请求。我写了一个 extension model-api-inspector 做这件事——监听 provider 的请求 / 响应事件，把每次调用的 request body 和 response body 都渲染到终端里：

pi System Prompt 构成详解

Tue, 30 Jun 2026 12:00:00 +0800

pi 的 system prompt 采用分层拼装机制，启动时按固定顺序叠放各层，最终拼接为发送给 LLM 的完整系统提示。

拼装顺序

┌─────────────────────────────────────────────┐
│  ① 基础系统提示 (pi 内置)                     │
│     角色、工具说明、行为准则、文档路径           │
│     ↓ 可被替换                                │
│  ② SYSTEM.md (如存在)                        │
│     完全替换①，而非追加                        │
│     ~/.pi/agent/SYSTEM.md 或 .pi/SYSTEM.md    │
│     ↓                                        │
│  ③ APPEND_SYSTEM.md (如存在)                  │
│     追加在②之后                                │
│     ↓                                        │
│  ④ 上下文文件                                 │
│     AGENTS.md / CLAUDE.md 全部拼接            │
│     来源：全局 + 沿目录树向上收集                │
│     ↓                                        │
│  ⑤ 技能列表 (XML)                             │
│     仅名称 + 描述，遵循 Agent Skills 规范       │
│     ↓                                        │
│  ⑥ 最终 System Prompt → 发送给 LLM            │
└─────────────────────────────────────────────┘

工具 Schema 不在 system prompt 中

工具定义（read、write、edit、bash 及扩展注册的自定义工具）作为 API 请求的 tools 参数单独传递，不进入 system prompt 正文。system prompt 中只包含工具的简要描述说明。