pi 上手：把终端 AI Agent 捏成你的工作流

我之前试过不少 coding agent，强是强，但经常有种“要先适应它”的感觉：

• 它决定流程，我只能跟着走
• 想加一个自己的工具，改起来很重
• 项目规范想复用到新仓库，还得重新配

后来我用了一阵 pi，感觉它的思路很直接：核心尽量小，定制全部开放。

不是“把你塞进产品逻辑里”，而是“给你骨架，你自己长肉”。

---

这是什么

一句话：pi 是一个极简 terminal coding harness。

默认给模型最常用的四个工具：read、write、edit、bash。然后你按需要叠加：

• Prompt Templates（复用提示词）
• Skills（按任务封装能力）
• Extensions（TypeScript 扩展工具/UI/事件）
• Themes（界面主题）
• Pi Packages（把上面这些打包共享）

它有四种运行形态：

1. 交互模式（默认）
2. print / JSON 模式（脚本友好）
3. RPC 模式（进程集成）
4. SDK（嵌进你自己的应用）

---

效果展示（最小可用）

# 1) 安装
npm install -g @mariozechner/pi-coding-agent

# 2) 登录（任选一种）
pi
/login

# 或者 API key
export ANTHROPIC_API_KEY=sk-ant-...
pi

# 3) 开始干活
pi "帮我扫描 src 下所有 .ts 文件，找出 TODO 并按优先级分组"

在交互界面里，你会看到它调用工具、执行命令、回填结果。会话自动保存，后面还能 /tree 回到历史节点继续分支聊。

---

5 分钟跑通后的第一件事：放好 AGENTS.md

pi 启动时会加载上下文文件（AGENTS.md / CLAUDE.md），而且是分层拼接：

• ~/.pi/agent/AGENTS.md（全局）
• 当前目录向上遍历到根目录的同名文件
• 当前项目目录里的文件

所以最实用的动作是：

1. 在全局写你的通用习惯（语言、风格、禁区）
2. 在项目里写仓库规范（命令、测试、提交规则）

这样你每次开新会话，不用重复解释“这个项目怎么干活”。

---

四个定制入口（从轻到重）

1) Prompt Templates：固定话术，秒复用

放到 ~/.pi/agent/prompts/review.md：

Review this code for bugs, security issues, and performance problems.
Focus on: {{focus}}

然后在 pi 里直接 /review。

---

2) Skills：把“步骤”封成能力

目录：~/.pi/agent/skills/my-skill/SKILL.md

# My Skill
Use this skill when the user asks about release checks.

## Steps
1. Run tests
2. Lint changed files
3. Summarize risk in bullet points

用法：/skill:my-skill，或者让 agent 自动触发。

---

3) Extensions：真正的“能力加法”

最小示例：

export default function (pi) {
  pi.registerTool({
    name: "deploy",
    description: "Deploy current app",
    parameters: { type: "object", properties: {}, additionalProperties: false },
    async execute() {
      return { content: [{ type: "text", text: "deployed" }] };
    },
  });
}

Extensions 不只加工具，还能加命令、快捷键、事件处理，甚至改编辑器 UI。

---

4) Themes + Keybindings：手感问题一次解决

• 主题目录：~/.pi/agent/themes/
• 快捷键：~/.pi/agent/keybindings.json

主题支持热重载，改完马上生效；快捷键可以把常用动作改成你自己的肌肉记忆。

---

三个很实用的模式

1) Print 模式（脚本里最好用）

pi -p "Summarize this repo"

2) JSON 模式（事件流集成）

pi --mode json "Refactor this module"

3) RPC / SDK（接入你自己的系统）

pi --mode rpc

如果你是 Node/TypeScript 项目，也可以直接用 SDK 创建会话，把 pi 当底层 agent 引擎。

---

我踩过的 3 个坑

1) 第三方 Pi Package 权限太大

Pi package 本质上可以执行任意代码。安装前一定先看源码，尤其是 extension 里有没有危险命令。

2) 上下文叠加太多，指令互相打架

全局 AGENTS.md + 项目 AGENTS.md 都写太满时，模型会纠结。建议：

• 全局只放“长期不变”的偏好
• 项目只放“当前仓库必须遵守”的规则

3) 在陌生仓库里开太大权限

默认工具有写能力。第一次看陌生代码时，我会先用只读工具：

pi --tools read,grep,find,ls -p "Review this codebase"

先看清再改，安全很多。

---

推荐资源

---

下一步

如果你刚准备上手，我建议这个顺序：

1. 跑起来（安装 + 登录）
2. 先写好 AGENTS.md
3. 做一个 Prompt Template
4. 做一个你最高频的 Skill
5. 最后再上 Extension

你会很快从“会用 agent”变成“有一套自己的 agent 工作流”。

---

附录：给 AI 的复现指令

目标：
写一篇介绍 pi 的实战文章，面向有命令行基础但没用过 pi 的开发者。

技术栈：
- pi CLI
- Node.js / npm
- Markdown

项目结构：
- 文章放在 Obsidian 仓库中
- frontmatter 必须包含 title/category/tags/summary/slug/share

环境变量：
- ANTHROPIC_API_KEY（示例值 sk-ant-...）

核心逻辑：
1) 安装并启动 pi
2) 解释默认工具和交互方式
3) 展示 Skills / Prompt Templates / Extensions / Themes / Packages 的关系
4) 给出最小可执行命令
5) 补充真实踩坑和规避方法

运行命令：
- npm install -g @mariozechner/pi-coding-agent
- pi
- /login

成功标志：
- 文章可读、可复制、可复现
- 命令能直接运行
- 发布后拿到 share URL

附录：常用命令速查

# 启动 / 续聊
pi
pi -c
pi -r

# 切换模型
/model

# 会话操作
/tree
/fork
/compact

# 发布分享会话 HTML
/share

# 仅输出文本
pi -p "Summarize changes"