Pi 编程助手

终端编程助手，支持通过 TypeScript 扩展、技能（Skills）、提示模板（Prompt Templates）和主题（Themes）进行自定义。

使用场景

适用于安装配置、模型切换、扩展开发、会话管理、RPC/SDK 集成等场景。

安装

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
export ANTHROPIC_API_KEY=sk-ant-...; pi   # 或使用 pi → /login 选择服务提供商

基本用法

pi — 交互模式 | pi -p "q" — 脚本模式 | pi --mode rpc — 跨语言模式 | pi -c — 继续上一次会话 | pi -r — 浏览会话

四种运行模式

交互式（TUI） / -p 输出模式 / --mode json 事件流模式 / --mode rpc 标准输入/输出 JSONL 模式

[SDK 嵌入方式](references/sdk.md)：import { createAgentSession } from "@earendil-works/pi-coding-agent"

模型与快捷键

支持 15+ 服务提供商（Anthropic/OpenAI/Google 等），可通过 /login OAuth 或 API Key 登录。

使用 /model（Ctrl+L）切换模型，Ctrl+P 循环切换，Shift+Tab 切换思考层级。

[服务提供商详情](references/providers.md) | [自定义模型](references/models.md) | [快捷键列表](references/shortcuts.md)

会话管理

采用 JSONL 树状结构，支持就地分支。

使用 /tree 导航，/fork 分支，/compact 压缩历史。

使用 pi -c 可继续上一次的会话。

[会话管理](references/sessions.md) | [JSONL 格式与压缩机制](references/session-format.md)

控制与后续操作

在代理运行期间：

• Enter：插入控制指令（在工具执行后）
• Alt+Enter：后续提问（在代理完成任务后）
• Escape：中止当前操作

上下文工程

通过 AGENTS.md 实现级联加载，SYSTEM.md 或 APPEND_SYSTEM.md 可替换或追加系统提示。

自动压缩机制可总结旧消息，可通过扩展自定义。

技能与提示模板

技能：位于 ~/.pi/agent/skills/ 目录下，需包含 SKILL.md 文件，遵循 [Agent Skills 标准](https://agentskills.io)。可通过 /skill:name 调用或自动加载。

提示模板：位于 ~/.pi/agent/prompts/*.md，使用 /name 进行展开。

[技能详情](references/skills.md)

扩展功能

基于 TypeScript 模块，可注册工具、命令、快捷键、事件、UI 组件。

存放位置：~/.pi/agent/extensions/ 或 .pi/extensions/。

[扩展 API](references/extensions.md) | [TUI 组件](references/tui.md)

Pi 包管理

pi install npm:@foo/tools     # 安装 npm 包
pi install git:github.com/u/r # 安装 Git 仓库
pi install -l npm:@foo/tools  # 项目级安装
pi update                     # 更新所有包
pi config                     # 启用或禁用包

包格式：package.json 中包含 "pi": { "extensions/skills/prompts/themes": [...] } 字段，并带有关键字 "pi-package"。

[包管理说明](references/packages.md)

参考文档

运行时 API：[agent-core](references/agent-core.md) — 代理/工具/钩子/事件流

LLM API：[ai](references/ai.md) — getModel/streamProxy

扩展功能：[extensions](references/extensions.md) — 事件系统 | [tui](references/tui.md) — UI 组件

集成方式：[sdk](references/sdk.md) — Node SDK | [rpc](references/rpc.md) — JSONL 协议

配置管理：[config](references/config.md) — 设置项 | [providers](references/providers.md) — 认证方式 | [models](references/models.md) — 自定义模型

会话管理：[sessions](references/sessions.md) — 树形导航 | [session-format](references/session-format.md) — JSONL + 压缩

分发机制：[skills](references/skills.md) — 技能规范 | [packages](references/packages.md) — 包分发

用户界面：[shortcuts](references/shortcuts.md) — 快捷键 | [themes](references/themes.md) — 51-token 主题 | [cli](references/cli.md) — 所有 CLI 参数

注意事项

• 安装时请使用 --ignore-scripts（Pi 不需要生命周期脚本）
• Pi 包具有完整的系统访问权限；安装前请审查源码
• 可设置环境变量：PI_SKIP_VERSION_CHECK=1 / PI_TELEMETRY=0 / PI_OFFLINE=1
• 官网：[pi.dev](https://pi.dev) | 文档：[pi.dev/docs/latest](https://pi.dev/docs/latest)