pi-agent

用途

Pi Agent 技能用于在用户希望操作 Pi 或基于 Pi 进行构建时提供指引。Pi 是一个极简的终端编码工具（coding harness），可通过 TypeScript 扩展、技能、提示模板、主题、包、自定义模型/提供商、SDK 集成、RPC 模式、JSON 事件流和 TUI 组件进行扩展。

主要能力与参考文档

该技能首先要求根据用户意图选择对应参考文档，包括：

概述、文档地图、安装方式：references/overview.md
安装、认证、首次运行：references/quickstart.md
日常 CLI 用法、命令、模式、标志、项目信任：references/usage.md
提供商认证、API 密钥、云提供商设置：references/providers.md
自定义模型条目、本地模型、代理、兼容标志：references/models.md
本地 llama.cpp 路由、/llama、模型下载/加载：references/llama-cpp.md
设置键与默认值：references/settings.md
PI_* 及其他环境变量：references/environment-variables.md
扩展开发、自定义工具、事件、命令：references/extensions.md
自定义提供商实现、OAuth、自定义流式传输：references/custom-provider.md
在 Node/TypeScript 中嵌入 Pi：references/sdk.md
从其他进程/语言集成：references/rpc.md
消费 JSONL 事件输出：references/json.md
构建终端 UI 组件：references/tui.md
打包扩展/技能/提示/主题：references/packages.md
委派给子代理、链、并行运行、编排：references/pi-subagents.md
连接 MCP 服务器、MCP 工具发现/配置：references/pi-mcp-adapter.md
交互式访谈表单、结构化用户输入：references/pi-interview.md
Web 搜索、URL/PDF/仓库抓取、视频理解：references/pi-web-access.md
编写 Pi 技能：references/skills.md
提示模板或主题：references/prompt-templates.md、references/themes.md
会话、分支、压缩、解析 JSONL：references/sessions.md、references/compaction.md、references/session-format.md
安全、沙箱、信任：references/security.md、references/containerization.md
键盘或终端问题：references/keybindings.md、references/terminal-setup.md、references/tmux.md、references/windows.md、references/termux.md、references/shell-aliases.md
开发 Pi 本身：references/development.md

构建于 Pi 之上的默认方案

对于需要类型安全、直接状态访问、进程内自定义工具/扩展或自定义资源加载的 Node/TypeScript 应用，优先使用 SDK。使用 createAgentSession() 创建单个稳定会话；当应用需要通过 new/resume/fork/clone/import 流程替换会话时，使用 createAgentSessionRuntime()。认证和模型查找通过 ModelRuntime.create() 进行。
当客户端不是 Node.js、需要进程隔离或希望使用语言无关的 JSONL 协议时，优先使用 RPC 模式。以 pi --mode rpc --no-session 开始进行无状态子进程集成，然后在需要持久化时添加会话标志。仅按 \n 拆分记录——Node readline 不符合协议。
对于只需要流式事件、不需要双向控制的一次性命令行管道，优先使用 JSON 模式：pi --mode json "prompt"。
对于 Pi 原生行为使用扩展：自定义工具、命令处理器、事件钩子、提供商注册、自定义压缩、路径保护、项目信任策略、UI 提示、小部件和 TUI 组件。
当需要在多台机器或项目间共享或安装可复用的扩展、技能、提示模板或主题时，使用包。

安全默认值

Pi 是本地运行的，默认不沙箱化。应将扩展、包、技能、shell 命令和项目本地 .pi 资源视为具有 Pi 进程权限的代码。项目信任仅保护哪些项目输入被加载——它不是沙箱。对于不受信任的仓库或无人值守的自动化，请使用 Docker、OpenShell、Gondolin、VM 或远程沙箱进行隔离。

不要将机密存储在项目文件中。优先使用环境变量、~/.pi/agent/auth.json、通过 /login 的 OAuth，或 models.json/提供商配置中由命令支持的机密查找。

常用命令

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi
pi -p "Summarize this codebase"
pi --mode json "List files"
pi --mode rpc --no-session
pi --provider anthropic --model claude-sonnet-4-5
pi --model sonnet:high "Solve this complex problem"
pi --tools read,grep,find,ls -p "Review this repository"
pi --tui-mode fullscreen
pi install npm:pi-subagents
pi update --all

来源覆盖

这些参考文档总结了 https://pi.dev/docs/latest 上的 Pi 文档及其下所有文档页面，截至 Pi 0.84.2（文档来源：https://github.com/earendil-works/pi 中的 packages/coding-agent/docs/，原为 pi-mono）。它们还涵盖 https://pi.dev/packages/ 上 pi-subagents、pi-mcp-adapter、pi-interview 和 pi-web-access 的包页面，并与已发布的 npm README 和包文档交叉核对（pi-web-access 0.22.0、pi-mcp-adapter 2.25.0、pi-subagents 0.49.0、pi-interview 0.11.0）。当确切的 API 行为很重要时，优先使用所引用的参考页面，并检查 node_modules/@earendil-works/pi-coding-agent/dist/ 和 node_modules/@earendil-works/pi-ai/dist/ 下已安装的 TypeScript 定义。

代理操作流程

检查环境。确认目标、评估指标、预算（时间、计算、金钱）和停止标准。
确定输入。从数据或用户处确认格式、标识符和参数。对于任何会改变结果的值，应询问而非猜测。
先运行小版本。端到端运行一次迭代，并在扩大规模前检查日志。
使用上述说明和参考执行完整任务。
验证结果。在留出数据上评估；保留每次迭代、假设和结果的审计轨迹。
报告。说明运行了什么（版本、命令、参数）、检查了什么，以及仍不确定的内容。

异常处理

如果某次迭代产生了可疑的巨大收益：在接受结果前检查是否存在泄漏或评估错误。
如果这些说明中的函数、标志或端点在已安装版本中缺失：检查已安装版本自己的文档（help()、--help、官方文档），进行调整，并告知用户。绝不要虚构 API。
如果所需的输入、标识符或参数不明确：询问用户，或在运行前明确说明假设。

完整性规则

绝不要捏造结果、参数、标识符、引用或统计数据。如果某事无法运行或验证，请明确说明。
记录负面结果；绝不要只选择或报告有利的运行。
将此处特定版本的细节视为可能过时：请对照已安装版本的官方文档进行确认。
在采取会花费金钱、消耗共享 GPU 或云配额、触及个人或患者数据，或无法撤销的操作前，请先询问。

技能介绍

用途