pi-agent

Pi Agent

当用户想要操作 Pi 或基于 Pi 构建时，使用此技能。Pi 是一个精简的终端编码框架，可通过 TypeScript 扩展、技能、提示词模板、主题、软件包、自定义模型／提供商、SDK 集成、RPC 模式、JSON 事件流和 TUI 组件进行扩展。

首要决策

回答或编写代码前，先选择要查阅的参考文档：

用户意图	阅读
Pi 是什么、文档索引、安装方式	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
委派给子 Agent、链式调用、并行运行、编排	references/pi-subagents.md
连接 MCP 服务、发现／配置 MCP 工具	references/pi-mcp-adapter.md
交互式访谈表单、结构化用户输入	references/pi-interview.md
网络搜索、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()；如果应用需要通过新建／恢复／分叉／克隆／导入流程替换会话，则使用 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、虚拟机或远程沙箱进行隔离。

请勿在项目文件中存储机密。优先使用环境变量、~/.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 定义。

Agent 操作流程

1. 检查环境。 确认目标、评估指标、预算（时间、算力、资金）和停止条件。
2. 明确输入。 根据数据或用户提供的信息确认格式、标识符和参数。任何会改变结果的值都应询问，不要猜测。
3. 先运行小规模版本。 端到端运行一次迭代，并在扩大规模前检查日志。
4. 使用上述说明和参考资料执行完整任务。
5. 验证结果。 使用留出数据进行评估；为每次迭代、假设和结果保留审计记录。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及还有哪些不确定之处。

如果发生这种情况	请这样做
某次迭代产生了可疑的大幅提升	在接受结果前，检查是否存在数据泄漏或评估错误。
这些说明中提到的函数、标志或端点在已安装版本中不存在	查阅已安装版本自身的文档（help()、--help、官方文档），调整做法并告知用户。切勿编造 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明所作的假设。

诚信准则

• 切勿编造结果、参数、标识符、引用或统计数据。如果某项内容无法运行或验证，请明确说明。
• 记录负面结果；切勿只选择或报告有利的运行结果。
• 请将此处的特定版本信息视为可能过时，并对照已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，必须先征求同意。

相关技能

• qiskit：使用 Qiskit 和 IBM Quantum Runtime 构建、模拟、转译并执行量子电路。