速查表

一页纸 | 最常用的 Pi 命令、配置、API、技巧。

安装与启动

1
2
3
4
5
6
7
8
9
10
11

# 安装
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# 启动
pi

# 指定目录
pi /path/to/project

# 版本
pi --version

CLI 常用参数

内置工具

Pi 内置 7 个工具，其中 read / write / edit / bash 默认启用，grep / find / ls 同为内置但默认关闭，需要 --tools read,grep,find,ls 显式打开。

交互命令

/ 开头的是交互命令。下方列表按用途分组；用 pi / 或 /help 风格的入口都能弹出补全。

配置路径

1
2
3
4
5
6
7
8
9
10

~/.pi/agent/
├── settings.json
├── auth.json
├── models.json
├── AGENTS.md
├── skills/
├── prompts/
├── extensions/
├── themes/
└── sessions/

项目级：

1
2
3
4
5

./AGENTS.md
./CLAUDE.md
./AGENTS.override.md
./.pi/settings.json
./.pi/extensions/

AGENTS.md 加载顺序

1
2
3
4

~/.pi/agent/AGENTS.md
父目录 AGENTS.md / CLAUDE.md
当前目录 AGENTS.md / CLAUDE.md
当前目录 AGENTS.override.md（替换同级）

环境变量

Pi 原生识别的 API key 环境变量有：ANTHROPIC_API_KEY、OPENAI_API_KEY、GEMINI_API_KEY、DEEPSEEK_API_KEY、GROQ_API_KEY、MISTRAL_API_KEY、XAI_API_KEY、OPENROUTER_API_KEY。其他 provider（Azure、Bedrock、Cerebras、Cloudflare、Vercel、ZAI、OpenCode、Radius、Hugging Face、Fireworks、Together、Baseten、Kimi、Xiaomi 等）的 env var 名称见 Providers 文档。

安全等级

会话快捷键（TUI）

JSON 模式示例

1

pi --mode json -p "解释这个项目" | jq -r 'select(.type=="done") | .result'

RPC 模式示例

1
2
3

pi --mode rpc
# stdin 发送 JSON 命令
{"type":"prompt","text":"hello"}

扩展最小模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

export default function (pi: ExtensionAPI) {
  pi.on("session_start", async (_event, ctx) => {
    ctx.ui.notify("Extension loaded", "info");
  });

  pi.registerTool({
    name: "my_tool",
    label: "My Tool",
    description: "...",
    parameters: Type.Object({ x: Type.String() }),
    async execute(toolCallId, params) {
      return { content: [{ type: "text", text: params.x }], details: {} };
    },
  });

  pi.registerCommand("my_cmd", {
    description: "...",
    handler: async (_args, ctx) => {
      ctx.ui.notify("ok", "info");
    },
  });
}

Prompt Template 模板

1
2
3
4
5
6
7
8
9
10

---
name: refactor
description: Refactor code
---

Refactor the following code to improve readability and type safety. Do not change behavior.

$@

Provide a plan first, then implement after confirmation.

调试清单

1. pi --version
2. pi --verbose
3. /system
4. /tools
5. /model
6. /session
7. /tree
8. /reload
9. /compact

下一步

• 术语表 — 术语表

这一页是查询用的，不是阅读用的。遇到具体问题再翻相应表格。