Pai Agent 完全教程 · 颜值笔记

AI AGENT 完全指南

PAI

大道至简 · 极速编程 Agent

基础工具

1000

系统提示词 Token

4‰

打招呼仅占上下文

1.5–2×

编程速度提升

✦

序章：大道至简

Pai 的核心设计哲学：极简。仅4个基础工具 + 1000 token 系统提示词。

同样的"你好"指令：Pai 仅占4‰上下文，Codex 却消耗 18000 token（约7%）。

在 DataBreaK 的百万行代码基准测试中，Pai + GPT 4.8 组合在不同成本下均表现优异，代码质量达到最高点。

核心理念：核心越小越干净，模型发挥越好，用户自由度最大。

⚡

安装指南

Windows

右键打开 PowerShell，从官网复制一键安装命令执行。未装 Node.js 时输入 Y 自动安装，随后输入 Y 安装 Pai。完成后重启终端输入 pai 启动。

macOS

打开终端，执行官网提供的 curl 命令即可完成安装。

✦

模型配置

方式一：API Key

在 Pai 中执行 /login，选择 API Key 方式。输入关键词筛选支持40+模型供应商，粘贴 Key 即可。

方式二：模型订阅

选择 Sign in with account，以 OpenAI 订阅为例，浏览器登录后 Ctrl+L 调出模型列表，即可看到 ChatGPT 模型。

常用命令： /model 切换模型 · Shift+Tab 思考强度 · Ctrl+L 快速选择

✦

基础操作

创建项目

新建文件夹 → 右键在终端打开 → 输入 pai，当前目录即为项目目录。

输入指令

换行：Shift + Enter 或 Ctrl + G 打开记事本编辑，保存后自动同步。

快速运行命令

指令前加 ! 临时运行，模型可见；!! 运行但模型不可见。

✦

指令追加：steering 与 follow-up

Steering（引导）

默认方式。A 执行中直接追加指令，立即干预方向。相当于"打方向盘"。

Follow-up（排队）

指令排队，等 A 完成当前轮次后才执行。Windows 需在 PowerShell 设置中删除 Ctrl+Alt+Enter 快捷键，然后使用 Alt+Enter（macOS 为 Option+Enter）发送。

原理：Pai 使用双层循环。内层循环注入 steering 消息实现实时响应；follow-up 等待内层完成后再进入外层循环。

✦

会话管理

Session 概念

每次对话历史为一个 Session，可用 /new 开启新会话。用 pai -c 从最近会话继续，pai -r 挑选会话。

对话树 /tree

Session 可分支。回退到历史节点后创建新分支，但只回退对话历史，不回退代码。需要搭配 git 来完全回滚。

克隆与分叉

/clone 复制整个 Session；/fork 选择节点复制新 Session。

上下文压缩 /compact

手动压缩历史对话，降低上下文占用。经验：清空优于压缩，任务结束建议直接开新会话。

✦

核心工具与哲学

四个基础工具：

读文件读取任意文件

写文件创建/覆写文件

改文件精准修改内容

运行命令执行 Shell / Bash

没有 MCP、没有 Subagent、没有 Todo，靠极简换取高效。但支持 Skill 扩展。

"让工具来适应你的工作流，而不是让你去适应工具。"

✦

插件生态：无限扩展

联网搜索

安装 pai-web-search 插件，获得联网能力，零配置，自动接入 Exa 服务。

子代理

agents 插件支持并行运行多个子代理。例如同时开发5个风格各异的网页。

MCP 接入

通过 pai-mcp-adapter 接入任意 MCP server，如高德地图（读取配置 .mcp.json）。

旁路对话（btw）

原生无 btw 功能，安装插件后执行 /btw 开启旁路对话，不影响主任务。

计划模式

pai-plan 插件，执行 /plan mode 进入计划模式，A 先输出计划，确认后执行。

Go 模式

pai-go 插件，执行 /go 给一个目标，A 自动迭代多次直到完成。

动态工作流

pai-dynamic-workflows 插件，类似 Cloud Code，调度多个子代理协同处理复杂任务。

移动端连接

pai-v-chat 插件，手机扫码配对后，通过微信/通讯录向 Pai 发送指令并接收结果。

✦

Skills 技能系统

遵循标准 Skills 协议，放到项目目录 .agents/skills 或全局目录（用户目录/.agents）即可识别。

常用 Skill 示例

Playwright CLI — 浏览器自动化，可操作 Chrome 完成网页任务。

Markdown Converter — 任意文档转 Markdown，需配合 uvx 工具。

tts — 文本转语音，免费无需 API Key。

可从 GitHub 或 Skill Hub 获取技能，也可以让 Pai 自己安装。

✦

网页版 UI

社区项目 4200+ Star，提供图形化界面。安装后自动打开浏览器，支持：

文件树浏览与项目切换

模型配置与订阅管理

技能/插件启停控制

对话面板支持截图粘贴

Token 与成本统计

✦

记忆系统：agent.md

在项目根目录创建 agent.md 文件，每次对话自动携带该上下文，避免重复交代背景。

该文件在 Codex、Open Code 等工具间通用。

全局提示词可放在用户目录 .pai/agent/agent.md，对所有项目生效。

更高优先级：全局配置目录下的 append-system.md，直接追加到系统提示词。

✦

安全机制

Pai 本体几乎不设防——启动后拥有极高权限，自动执行命令不中断。这是刻意设计：不做沙箱，保持极简。

安全方案：

容器/虚拟机 — 用 WSL、Docker 或 Hyper-V 运行 Pai，隔离风险。

权限插件 — 安装 pai-permission-system，敏感操作需审批。

✦

让 Pai 自己写插件

我们真的可以让 A 开发插件：

天气插件 — 让 A 编写代码，从 IP 查地理位置，再查天气并展示在 UI 上。

文件保护 — 禁止编辑 .env 文件，自动拦截。

删除确认 — 执行 rm 命令前弹窗询问。

插件本质是 TypeScript 文件，放项目目录 .pai/extensions 或全局配置目录。

✦

源码架构与 SDK

核心包组成：

pai-ai — 模型统一调用层，适配几十个模型厂商

agent — 实现核心双层循环机制

coding-agent — 编程功能、四个工具、Skills、插件实现

tui — 命令行界面

SDK 使用：可引入 pai-ai 的 createModel 方法接入任意模型；或引入 pai-agent 作为可嵌入的 Coding Agent。

给读者的行动建议

上手第1步：安装 Pai，用最小配置体验"大道至简"。

核心用法：用 steering 实时纠偏，用 follow-up 排队补充任务。

别忘了写 agent.md，让 Agent 记住项目背景。

复杂任务用 go 模式 + 子代理并行，成倍提速。

极简，是一种力量。