Pi Coding Agent

终端编程助手，支持通过 TypeScript 扩展、Skills（技能）、Prompt 模板与主题进行定制化配置。

使用场景

适用于安装、配置、模型切换、扩展开发、会话管理、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 基于 stdin/stdout 的 JSONL 模式
SDK 嵌入方式：import { createAgentSession } from "@earendil-works/pi-coding-agent"

模型与快捷键

支持 15+ 家服务商（Anthropic/OpenAI/Google/……），可通过 /login 使用 OAuth 或 API Key 登录。/model（Ctrl+L）切换模型，Ctrl+P 循环切换，Shift+Tab 切换思维层级。
服务商详情 | 自定义模型 | 快捷键列表

会话管理

采用 JSONL 树形结构 + 原地分支机制。/tree 导航会话树，/fork 创建分支，/compact 压缩历史消息。pi -c 可继续最近一次会话。
会话管理 | JSONL 格式与压缩机制

引导控制与后续追问

代理运行期间：
Enter = 引导（在工具执行完成后插入指令）
Alt+Enter = 后续追问（在代理完成响应后插入指令）
Escape = 中止当前操作

上下文工程

AGENTS.md 支持级联加载；SYSTEM.md/APPEND_SYSTEM.md 分别用于替换或追加系统提示词。自动压缩功能可对历史消息进行摘要，行为可通过 Extensions 自定义。

Skills 与 Prompt 模板

Skills：位于 ~/.pi/agent/skills/ 目录下，每个 Skill 对应一个 SKILL.md 文件，遵循 Agent Skills 规范。/skill:name 显式调用，或由系统自动加载。
Prompt 模板：存放于 ~/.pi/agent/prompts/*.md，使用 /name 即可展开。
Skills 详情

Extensions（扩展）

TypeScript 模块，可用于注册工具、命令、快捷键、事件及 UI 组件。
路径位置：~/.pi/agent/extensions/ 或项目级 .pi/extensions/。
扩展 API 文档 | TUI 组件说明

Pi Packages（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                     # 启用/禁用配置项

Pi 包格式要求：package.json 中需包含 "pi": { "extensions/skills/prompts/themes": [...] } 字段，并声明关键字 "pi-package"。
包管理说明

参考文档

运行时 API：agent-core — Agent/Tool/Hooks/事件流
LLM API：ai — getModel/streamProxy
Extensions：extensions — 事件系统 | tui — UI 组件
集成能力：sdk — Node SDK | rpc — JSONL 协议
配置系统：config — 全局设置 | providers — 认证配置 | models — 自定义模型
会话系统：sessions — 树形导航 | session-format — JSONL+Compaction 格式规范
分发机制：skills — Skill 规范 | packages — 包分发协议
用户界面：shortcuts — 键盘快捷键 | themes — 51-token 主题格式 | cli — 全部 CLI 参数说明

注意事项

• 请使用 --ignore-scripts 参数安装（Pi 不依赖 npm 生命周期脚本）
• Pi Packages 拥有完整的系统访问权限；安装前请务必审查源码
• 环境变量支持：PI_SKIP_VERSION_CHECK=1 / PI_TELEMETRY=0 / PI_OFFLINE=1
• 官网主页：pi.dev | 文档地址：pi.dev/docs/latest