@mariozechner/pi-coding-agent

Pi 是一个极简的终端编程框架。让 pi 适应你的工作流程，而不是反过来，无需 fork 和修改 pi 内部代码。使用 TypeScript 扩展、技能、提示词模板和主题来扩展它。将你的扩展、技能、提示词模板和主题放入 Pi 包中，通过 npm 或 git 与他人分享。

Pi 自带强大的默认配置，但跳过了子代理和计划模式等功能。相反，你可以让 pi 构建你想要的功能，或者安装符合你工作流程的第三方 pi 包。

Pi 以四种模式运行：交互模式、打印或 JSON 模式、用于进程集成的 RPC 模式，以及用于嵌入你自己应用的 SDK 模式。参见 openclaw/openclaw 了解真实世界的 SDK 集成案例。

Quick Start

npm install -g @mariozechner/pi-coding-agent

使用 API 密钥进行认证：

export ANTHROPIC_API_KEY=sk-ant-...
pi

或使用你现有的订阅：

pi
/login  # 然后选择提供商

然后就可以与 pi 对话了。默认情况下，pi 为模型提供四个工具：read、write、edit 和 bash。模型使用这些工具来满足你的请求。通过技能、提示词模板、扩展或 pi 包添加功能。

供应商与模型

对于每个内置提供商，pi 维护一个支持工具调用的模型列表，每次发布都会更新。通过订阅（/login）或 API 密钥认证，然后通过 /model（或 Ctrl+L）从该提供商选择任意模型。

订阅：

• Anthropic Claude Pro/Max
• OpenAI ChatGPT Plus/Pro (Codex)
• GitHub Copilot
• Google Gemini CLI
• Google Antigravity

API 密钥：

• Anthropic
• OpenAI
• Azure OpenAI
• Google Gemini
• Google Vertex
• Amazon Bedrock
• Mistral
• Groq
• Cerebras
• xAI
• OpenRouter
• Vercel AI Gateway
• ZAI
• OpenCode Zen
• OpenCode Go
• Hugging Face
• Kimi For Coding
• MiniMax

交互模式

界面从上到下：

• 启动头部 - 显示快捷键（/hotkeys 查看全部）、已加载的 AGENTS.md 文件、提示词模板、技能和扩展
• 消息 - 你的消息、助手回复、工具调用和结果、通知、错误和扩展 UI
• 编辑器 - 你输入的地方；边框颜色表示思考级别
• 页脚 - 工作目录、会话名称、总 token/缓存使用量、费用、上下文使用率、当前模型

编辑器可以被其他 UI 临时替换，比如内置的 /settings 或扩展的自定义 UI（例如，让用户以结构化格式回答模型问题的问答工具）。扩展还可以替换编辑器、在其上方/下方添加组件、状态栏、自定义页脚或覆盖层。

编辑器

支持删除单词、撤销等标准编辑快捷键。参见 docs/keybindings.md。

命令

在编辑器中输入 / 触发命令。扩展可以注册自定义命令，技能以 /skill:name 形式使用，提示词模板通过 /templatename 展开。

键盘快捷键

完整列表见 /hotkeys。通过 ~/.pi/agent/keybindings.json 自定义。参见 docs/keybindings.md。

常用快捷键：

消息队列

在代理工作时提交消息：

• Enter 排队一条引导消息，在当前助手轮次完成工具调用执行后传递
• Alt+Enter 排队一条后续消息，仅在代理完成所有工作后传递
• Escape 中止并将排队消息恢复到编辑器
• Alt+Up 将排队消息取回编辑器

在设置中配置传递方式：steeringMode 和 followUpMode 可以是 "one-at-a-time"（默认，等待响应）或 "all"（一次性传递所有排队消息）。transport 为支持多种传输方式的提供商选择传输偏好（"sse"、"websocket" 或 "auto"）。

会话

会话以 JSONL 文件形式存储，具有树形结构。每个条目有一个 id 和 parentId，支持原地分支而无需创建新文件。文件格式参见 docs/session.md。

管理

会话自动保存到 ~/.pi/agent/sessions/，按工作目录组织。

pi -c                  # 继续最近的会话
pi -r                  # 浏览并选择过去的会话
pi --no-session        # 临时模式（不保存）
pi --session <path>    # 使用指定的会话文件或 ID
pi --fork <path>       # 将指定会话文件或 ID 分叉为新会话

分支

/tree - 原地导航会话树。选择任意之前的节点，从那里继续，并在分支之间切换。所有历史记录保存在单个文件中。

• 输入进行搜索，使用 Ctrl+←/Ctrl+→ 或 Alt+←/Alt+→ 折叠/展开和在分支间跳转，使用 ←/→ 翻页
• 过滤模式（Ctrl+O）：默认 → 无工具 → 仅用户 → 仅标签 → 全部
• 按 l 为条目添加书签标签

/fork - 从当前分支创建新的会话文件。打开选择器，复制到所选点的历史记录，并将该消息放入编辑器供修改。

--fork <path|id> - 直接从 CLI 分叉现有会话文件或部分会话 UUID。这会将源会话完整复制到当前项目的新会话文件中。

压缩

长会话可能耗尽上下文窗口。压缩会总结旧消息同时保留最近的消息。

手动： /compact 或 /compact <自定义指令>

自动： 默认启用。在上下文溢出时触发（恢复并重试）或接近限制时触发（主动）。通过 /settings 或 settings.json 配置。

压缩是有损的。完整历史保留在 JSONL 文件中；使用 /tree 回顾。通过扩展自定义压缩行为。内部实现参见 docs/compaction.md。

设置

使用 /settings 修改常用选项，或直接编辑 JSON 文件：

所有选项参见 docs/settings.md。

上下文文件

Pi 在启动时从以下位置加载 AGENTS.md（或 CLAUDE.md）：

• ~/.pi/agent/AGENTS.md（全局）
• 父目录（从当前工作目录向上遍历）
• 当前目录

用于项目说明、约定、常用命令。所有匹配的文件会被连接。

系统提示词

用 .pi/SYSTEM.md（项目）或 ~/.pi/agent/SYSTEM.md（全局）替换默认系统提示词。通过 APPEND_SYSTEM.md 追加而不替换。

自定义

提示词模板

可复用的提示词，作为 Markdown 文件。输入 /name 展开。

<!-- ~/.pi/agent/prompts/review.md -->
审查这段代码的 bug、安全问题和性能问题。
重点关注：{{focus}}

放在 ~/.pi/agent/prompts/、.pi/prompts/ 或 pi 包中与他人分享。参见 docs/prompt-templates.md。

技能

遵循 Agent Skills 标准的按需功能包。通过 /skill:name 调用或让代理自动加载。

<!-- ~/.pi/agent/skills/my-skill/SKILL.md -->
# 我的技能
当用户询问 X 时使用此技能。

## 步骤
1. 做这个
2. 然后做那个

放在 ~/.pi/agent/skills/、~/.agents/skills/、.pi/skills/ 或 .agents/skills/（从 cwd 向上遍历父目录）或 pi 包中与他人分享。参见 docs/skills.md。

扩展

用 TypeScript 模块扩展 pi，提供自定义工具、命令、键盘快捷键、事件处理器和 UI 组件。

export default function (pi: ExtensionAPI) {
  pi.registerTool({ name: "deploy", ... });
  pi.registerCommand("stats", { ... });
  pi.on("tool_call", async (event, ctx) => { ... });
}

可以实现：

• 自定义工具（或完全替换内置工具）
• 子代理和计划模式
• 自定义压缩和摘要
• 权限把关和路径保护
• 自定义编辑器和 UI 组件
• 状态栏、头部、页脚
• Git 检查点和自动提交
• SSH 和沙箱执行
• MCP 服务器集成
• 让 pi 看起来像 Claude Code
• 等待时的游戏（是的，Doom 可以运行）
• …任何你能想象的功能

放在 ~/.pi/agent/extensions/、.pi/extensions/ 或 pi 包中与他人分享。参见 docs/extensions.md 和 examples/extensions/。

主题

内置：dark、light。主题热重载：修改活动主题文件，pi 会立即应用更改。

放在 ~/.pi/agent/themes/、.pi/themes/ 或 pi 包中与他人分享。参见 docs/themes.md。

Pi 包

通过 npm 或 git 打包和分享扩展、技能、提示词和主题。在 npmjs.com 或 Discord 上查找包。

安全： Pi 包具有完整的系统访问权限。扩展执行任意代码，技能可以指示模型执行任何操作，包括运行可执行文件。安装第三方包之前请审查源代码。

pi install npm:@foo/pi-tools
pi install npm:@foo/[email protected]      # 指定版本
pi install git:github.com/user/repo
pi install git:github.com/user/repo@v1  # 标签或提交
pi install git:[email protected]:user/repo
pi install git:[email protected]:user/repo@v1  # 标签或提交
pi install https://github.com/user/repo
pi install https://github.com/user/repo@v1      # 标签或提交
pi install ssh://[email protected]/user/repo
pi install ssh://[email protected]/user/repo@v1    # 标签或提交
pi remove npm:@foo/pi-tools
pi uninstall npm:@foo/pi-tools          # remove 的别名
pi list
pi update                               # 跳过固定版本的包
pi config                               # 启用/禁用扩展、技能、提示词、主题

包安装到 ~/.pi/agent/git/（git）或全局 npm。使用 -l 进行项目本地安装（.pi/git/、.pi/npm/）。如果你使用 Node 版本管理器并希望包安装重用稳定的 npm 环境，在 settings.json 中设置 npmCommand，例如 ["mise", "exec", "node@20", "--", "npm"]。

通过在 package.json 中添加 pi 键来创建包：

{
  "name": "my-pi-package",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"]
  }
}

如果没有 pi 清单，pi 会从常规目录（extensions/、skills/、prompts/、themes/）自动发现。

参见 docs/packages.md。

编程使用

SDK

import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "@mariozechner/pi-coding-agent";

const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  authStorage: AuthStorage.create(),
  modelRegistry: new ModelRegistry(authStorage),
});

await session.prompt("当前目录下有哪些文件？");

参见 docs/sdk.md 和 examples/sdk/。

RPC 模式

对于非 Node.js 集成，使用基于 stdin/stdout 的 RPC 模式：

pi --mode rpc

RPC 模式使用严格的 LF 分隔 JSONL 帧。客户端必须仅在 \n 上分割记录。不要使用像 Node readline 这样的通用行读取器，它也会在 JSON 载荷内的 Unicode 分隔符上分割。

协议参见 docs/rpc.md。

设计理念

Pi 具有极强的可扩展性，因此无需规定你的工作流程。其他工具内置的功能可以通过扩展、技能构建，或从第三方 pi 包安装。这保持了核心的极简，同时让你塑造 pi 以适应你的工作方式。

没有 MCP。 构建带 README 的 CLI 工具（参见技能），或构建添加 MCP 支持的扩展。为什么？

没有子代理。 有很多方法可以实现这个。通过 tmux 启动 pi 实例，或用扩展构建你自己的，或安装一个按你方式做的包。

没有权限弹窗。 在容器中运行，或用扩展构建你自己的确认流程，与你的环境和安全要求一致。

没有计划模式。 把计划写到文件里，或用扩展构建，或安装一个包。

没有内置待办事项。 它们会混淆模型。使用 TODO.md 文件，或用扩展构建你自己的。

没有后台 bash。 使用 tmux。完全可观察性，直接交互。

阅读博客文章了解完整的理念说明。

CLI 参考

pi [选项] [@文件...] [消息...]

包命令

pi install <来源> [-l]     # 安装包，-l 表示项目本地
pi remove <来源> [-l]      # 移除包
pi uninstall <来源> [-l]   # remove 的别名
pi update [来源]           # 更新包（跳过固定版本）
pi list                    # 列出已安装的包
pi config                  # 启用/禁用包资源

模式

在打印模式下，pi 也会读取管道输入的 stdin 并将其合并到初始提示词中：

cat README.md | pi -p "总结这段文本"

模型选项

会话选项

工具选项

可用内置工具：read、bash、edit、write、grep、find、ls

资源选项

将 --no-* 与显式标志结合使用，可以精确加载你需要的内容，忽略 settings.json（例如 --no-extensions -e ./my-ext.ts）。

其他选项

文件参数

给文件添加 @ 前缀以包含在消息中：

pi @prompt.md "回答这个问题"
pi -p @screenshot.png "这张图片里有什么？"
pi @code.ts @test.ts "审查这些文件"

示例

# 带初始提示词的交互模式
pi "列出 src/ 中的所有 .ts 文件"

# 非交互模式
pi -p "总结这个代码库"

# 带管道输入的非交互模式
cat README.md | pi -p "总结这段文本"

# 使用不同模型
pi --provider openai --model gpt-4o "帮我重构"

# 带提供商前缀的模型（无需 --provider）
pi --model openai/gpt-4o "帮我重构"

# 带思考级别简写的模型
pi --model sonnet:high "解决这个复杂问题"

# 限制模型循环
pi --models "claude-*,gpt-4o"

# 只读模式
pi --tools read,grep,find,ls -p "审查代码"

# 高思考级别
pi --thinking high "解决这个复杂问题"

环境变量