Pi Coding Agent 入门与社区玩法

AI 参与说明（Agent：/root）：本文根据 Pi 官方文档、项目源码说明、本地 pi 0.84.2 环境与公开的社区 Package 页面协助整理。资料核验于 2026-08-20；Pi、模型目录和第三方 Package 都会持续变化，实际使用前应以目标版本的 pi --help、本机文档与文末一手资料为准。社区 Package 不代表 Pi 官方背书，安装前必须自行审查源码、权限和依赖。

先说结论#

Pi Coding Agent 是一个运行在终端中的最小化 Coding Agent Harness。它把模型、会话和工具调用组织成一个可持续工作的 Agent 循环：模型可以读取项目、修改文件、执行命令、检查结果，再根据反馈继续处理。

Pi 的特点不是“内置功能特别多”，而是核心刻意保持精简，再由以下机制组合出不同工作流：

• AGENTS.md：定义项目规则和验收方式。
• Skills：按需加载特定领域的操作说明、脚本和参考资料。
• Prompt Templates：复用经常使用的提示词。
• Extensions：用 TypeScript 增加工具、命令、事件处理和终端 UI。
• Pi Packages：通过 npm、Git 或本地路径分发上述资源。
• SDK、JSON mode 和 RPC mode：把 Agent 能力嵌入其他程序。

普通用户只需要安装 @earendil-works/pi-coding-agent。项目中同时出现的 @earendil-works/pi-agent-core 和 @earendil-works/pi-ai 是更底层的开发包，不需要为了使用 CLI 再单独安装。

Pi 的运行方式#

Pi 默认不是系统后台守护进程。最常用的是交互式和单次执行两种方式；集成场景还可以选择 JSON 或 RPC。

交互式会话退出后，Pi 进程会结束，但会话默认已经保存。之后可以运行 pi -c 继续最近一次会话，或用 pi -r 浏览历史会话。

安装与认证#

1. 安装 CLI#

官方 npm 安装命令是：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

也可以使用 pnpm：

pnpm add -g --ignore-scripts @earendil-works/pi-coding-agent

--ignore-scripts 会禁止依赖在安装期间执行生命周期脚本；Pi 的正常全局安装不依赖这些脚本。安装后检查实际版本和命令位置：

command -v pi
pi --version
pi --help

本文核验环境中的版本为：

0.84.2

2. 登录 Provider#

进入准备操作的项目目录后启动 Pi：

cd /path/to/project
pi

在交互界面运行：

/login

Pi 支持订阅登录和 API Key Provider。官方 Quickstart 当前列出的内置订阅登录包括 Claude Pro/Max、ChatGPT Plus/Pro（Codex）和 GitHub Copilot。具体选项取决于当前版本与账户状态。

如果使用环境变量提供 API Key，先在 Shell 中设置对应 Provider 的变量，再启动 Pi。不要把真实 Key 写进源码、AGENTS.md、公开文档或聊天记录。也可以通过 /login 将 API Key Provider 的凭据保存到 ~/.pi/agent/auth.json。

认证完成后检查模型：

pi --list-models

在交互界面中使用 /model 或 Ctrl+L 切换模型，用 Shift+Tab 调整 Thinking Level。

第一次使用：从只读检查开始#

Pi 默认可向模型提供 read、write、edit 和 bash，还支持 grep、find、ls 等内置工具。因为 write、edit 和 bash 可能改变本地状态，第一次运行建议先明确限制为只读工具：

pi --tools read,grep,find,ls -p \
  "检查这个仓库的结构、启动方式和测试命令，不要修改文件"

确认 Pi 能正确理解项目后，再进入交互模式完成一个小任务：

pi

定位当前失败测试的根本原因。先解释原因和修改计划，不要立即修改文件。

分析可信后再继续：

按照计划修复，只修改相关文件。完成后运行相关测试并检查 git diff。

这种“先调查、再实施、最后验证”的方式，比只说“帮我修一下”更容易控制范围和判断完成条件。

日常最有用的操作#

引用项目文件#

在交互编辑器里输入 @ 可以模糊搜索文件，也可以从命令行传入：

pi @README.md "总结安装和开发流程"
pi @src/app.ts @src/app.test.ts "结合测试审查这个实现"
pi -p @screenshot.png "解释截图中的错误"

执行 Shell 命令#

在 Interactive mode 中：

!npm test

单个 ! 会执行命令，并把输出加入模型上下文。两个 ! 会执行命令但不把结果提供给模型：

!!git status

后者适合不希望占用上下文、也不需要模型分析的人工检查。

在任务进行中改变方向#

Pi 支持消息队列：

• Enter：加入 Steering message，在当前 Assistant turn 的工具调用结束后交付。
• Alt+Enter：加入 Follow-up message，等 Agent 完成本轮工作后再交付。
• Escape：中止当前运行，并把队列中的消息恢复到编辑器。
• Alt+Up：把排队消息取回编辑器。

这使开发者可以在 Pi 工作时补充“不要改这个模块”或“完成后再检查另一个问题”，不必等待整个任务结束。

控制模型、工具和会话#

# 明确指定 Provider、模型和 Thinking Level
pi --provider openai --model gpt-5.4 --thinking high

# 只读审查
pi --tools read,grep,find,ls -p "审查代码，不修改文件"

# 排除某个工具
pi --exclude-tools bash

# 临时会话，不保存记录
pi --no-session -p "总结这个目录"

# 为会话命名
pi --name "release-audit"

模型名称和可用 Thinking Level 会随 Provider 与版本变化，不能照抄示例后假定必然存在；应先运行 pi --list-models。

用 AGENTS.md 固定项目工作方式#

Pi 会加载以下 Context Files：

• 用户全局的 ~/.pi/agent/AGENTS.md。
• 从当前工作目录向上的 AGENTS.md 或 CLAUDE.md。
• 若某一级存在 AGENTS.override.md，该文件会替代同级的 AGENTS.md 或 CLAUDE.md。

项目根目录可以提供最小规则：

# Project Instructions

- 修改前先阅读相关实现和测试。
- 使用 pnpm，不要使用 npm。
- 修改后运行 pnpm lint 和 pnpm test。
- 不要执行生产数据库迁移。
- 不要读取或输出 .env 内容。
- 不要提交代码，除非用户明确要求。

规则改变后运行 /reload 或重启 Pi。AGENTS.md 适合放稳定约束，不适合堆积某一次任务的临时需求；任务范围和验收标准仍应写在当次 Prompt 中。

需要注意：Context Files 即使项目未被信任也可能加载，因此来自陌生仓库的 AGENTS.md、文档、源码注释和命令输出都应被视为不可信输入，不能把其中的指令当作用户授权。

Session、分叉与上下文管理#

Pi 默认把 Session 保存在 ~/.pi/agent/sessions/，并按工作目录组织。

pi -c                    # 继续最近一次 Session
pi -r                    # 浏览并选择历史 Session
pi --session <path|id>   # 打开指定 Session
pi --fork <path|id>      # 从指定 Session 创建分叉

交互界面的常用命令：

一个实用习惯是按真实目标给 Session 命名，例如“修复支付回调重复处理”，而不是“今天的任务”。任务变成完全不同的方向时使用 /new 或 /fork，避免无关上下文持续污染判断。

Pi 的扩展体系#

Pi 把定制能力分成不同层级：

Skills#

Skill 是带有 SKILL.md 的自包含能力包。Pi 启动时只把 Skill 的名称和描述加入上下文；任务匹配时再读取完整说明，这种 Progressive Disclosure 可以避免所有详细文档长期占用 Context Window。

常见位置包括：

~/.pi/agent/skills/     # 用户全局
~/.agents/skills/      # 跨 Agent Host 共享
.pi/skills/             # 项目级
.agents/skills/         # 项目级、可跨 Host 复用

可以让模型自动选择 Skill，也可以显式调用：

/skill:skill-name

Pi 还可以在 settings.json 中加载 Claude Code 或 Codex 的 Skill 目录。兼容加载不代表每个 Skill 都能直接运行；其中引用的工具、脚本和环境依赖仍需在 Pi 环境中存在。

Extensions#

Extension 是 TypeScript 或 JavaScript 模块，可以注册：

• 自定义 Tool 或替换内置 Tool。
• Slash Command、快捷键和 Prompt 处理。
• Permission Gate 与受保护路径。
• Plan mode、Subagents 和自定义 Compaction。
• 状态栏、编辑器组件和其他 TUI。
• SSH、Sandbox、MCP 或 Git 自动化。

临时试用本地 Extension：

pi -e ./my-extension.ts

全局 Extension 通常放在 ~/.pi/agent/extensions/，项目级 Extension 放在 .pi/extensions/。项目级资源必须结合 Project Trust 审查；全局 Extension 则对所有项目生效，更应谨慎。

Pi Packages#

Pi Package 可以来自 npm、Git 或本地路径：

pi install npm:@scope/package@1.2.3
pi install git:github.com/user/repo@v1
pi install ./local-package

pi list
pi config
pi remove npm:@scope/package

默认安装记录写入用户设置 ~/.pi/agent/settings.json。加 -l 会写入项目设置 .pi/settings.json，适合把项目依赖的资源与团队共享：

pi install -l npm:@scope/package@1.2.3

想先试用而不持久安装，可以使用：

pi -e npm:@scope/package

更新命令要注意语义：pi update 或 pi update --self 更新 Pi 本身；pi update --extensions 更新 Packages；pi update --all 才同时更新 Pi 和 Packages。固定到明确版本或 Git ref 的 Package 不会被普通 Package 更新自动推进到新版本。

社区里好玩的用法#

Pi 的社区玩法本质上是“把自己需要的 Agent 工作台拼出来”。下面是截至资料整理日可以从公开 Package 页面和官方示例核验的代表方向，不是必须安装清单。

1. 用 Subagents 分工#

社区 Package pi-subagents 为 Pi 增加 Delegation、并行审查、串行 Workflow、后台任务和运行状态界面。安装示例：

pi install npm:pi-subagents

安装后可以用自然语言要求：

先让 scout 找出相关入口，再让 reviewer 独立审查修改方案。
并行运行三个 reviewer，分别检查正确性、测试遗漏和不必要复杂度。

Subagent 并不会神奇地提高每个模型的能力；它的价值是隔离上下文、分离角色并获得独立复核。代价是更多 Token、更多并发状态，以及多个写入 Agent 之间的冲突风险。实现任务应限制写入者数量，审查 Agent 则优先使用只读工具。

Pi 官方仓库本身也提供 Subagent Extension 示例，展示 Single、Parallel 和 Chain 三种模式；这说明 Subagents 是可由 Extension 构造的工作流，而不是 Pi Core 的固定能力。

2. 通过 MCP 接入外部工具#

Pi Core 故意不内置 MCP。社区的 pi-mcp-adapter 可以读取 .mcp.json 等配置，把 MCP Server 接入 Pi：

pi install npm:pi-mcp-adapter

适合连接浏览器调试、GitHub、数据库、内部开发工具或其他已经提供 MCP Server 的系统。Adapter 支持 Lazy connection 和 Tool metadata cache，但每个 MCP Server 都扩大了 Agent 的数据与操作边界。只启用当前任务需要的 Server，并分别审查 Server、启动命令、凭据来源和 Tool 权限。

3. 给 Pi 增加 Web 与多媒体能力#

例如社区 Package pi-web-access 提供 Web 搜索、网页抓取、GitHub 仓库读取、PDF 提取，以及部分视频内容处理能力：

pi install npm:pi-web-access

这种扩展适合“查官方文档后再修改代码”或“把外部资料整理成研究简报”。它通常还依赖搜索 Provider、API Key 或浏览器交互，因此必须检查配置成本、数据会发往哪里，以及是否会把私有代码或查询发送给第三方服务。

4. 把终端变成自定义 Agent UI#

Extension 可以修改状态栏、Footer、Editor、弹窗、快捷键和 Tool rendering。社区开发者会加入模型用量面板、任务进度、角色切换、远程 Web UI，甚至让手机连接一个正在运行的 Pi Session。

这些界面不是单纯装饰：对长任务而言，可见的成本、Context usage、后台任务和权限状态有助于判断是否继续。但远程 UI 会额外引入监听地址、认证和传输安全问题，不应直接暴露到公网。

5. Plan mode、权限门和自动 Git 检查点#

官方 Extension Examples 包含以下可组合思路：

• plan-mode/：先在只读阶段探索并维护步骤，再切换到实现阶段。
• permission-gate.ts：危险 Shell 命令执行前请求确认。
• protected-paths.ts：阻止修改 .env、.git/、node_modules/ 等路径。
• dirty-repo-guard.ts：存在未提交改动时阻止危险的 Session 切换。
• Git checkpointing / auto-commit：在关键节点建立可恢复状态。
• ssh.ts：把 Tool 调用委托到远程机器。

这些例子体现了 Pi 的设计取舍：Core 不强制一种审批或规划流程，而是允许个人或团队按风险模型组合。不过，应用层的 Permission popup 不是操作系统级 Sandbox，不能替代 Container、VM 或 Policy-controlled Sandbox。

6. 在等待模型时运行 Doom#

官方文档甚至把“等待时运行 Doom”列为 Extension 能做到的事情，并在示例和文档资源中提供相关演示图片。它更多是一种能力展示：Pi 的 TUI 不只渲染文本和 Tool call，也能承载完全自定义的交互组件。

这个例子虽然好玩，但真正值得借鉴的是 Extension API 的开放程度。相同机制可以实现 Diff viewer、测试面板、结构化表单、部署确认窗口或团队内部仪表盘。

如何选择社区 Package#

不要按 Package 数量组装 Pi。更稳妥的顺序是：

1. 先用裸 Pi 完成真实任务，确认缺少的能力。
2. 优先检查 Pi 官方 Extension Examples 是否已有可复用实现。
3. 在 Pi Package Catalog 查找对应 Package。
4. 检查源码仓库、维护状态、依赖、安装脚本和 Issue。
5. 先用 pi -e npm:<package> 临时试用。
6. 只在可信测试仓库中验证，并限制模型可见 Tool。
7. 确认需要长期使用后，再全局或项目级安装固定版本。

Package Catalog 是发现入口，不是安全认证或质量背书。下载量、发布时间和 README 都不能代替源码审查。

使用 SDK：什么时候需要底层三个包#

如果只使用 CLI，无需单独理解 monorepo 中的所有 Package。只有开发自己的 Agent 产品时，分层才重要：

@earendil-works/pi-coding-agent
  ├─ 完整 CLI、AgentSession、资源加载和开发工具
  ├─ 使用 @earendil-works/pi-agent-core 管理 Agent Loop 与状态
  └─ 使用 @earendil-works/pi-ai 统一不同 LLM Provider API

Node.js 应用通常从最高层开始：

pnpm add @earendil-works/pi-coding-agent

import {
  createAgentSession,
  ModelRuntime,
  SessionManager,
} from "@earendil-works/pi-coding-agent";

const modelRuntime = await ModelRuntime.create();
const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  modelRuntime,
});

session.subscribe((event) => {
  if (
    event.type === "message_update" &&
    event.assistantMessageEvent.type === "text_delta"
  ) {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});

await session.prompt("What files are in the current directory?");

SDK 已包含在 @earendil-works/pi-coding-agent，不需要再安装一个名为 pi-sdk 的包。只有需要自己重组底层 Agent Runtime，或只想使用统一 Provider API 时，才考虑直接依赖 pi-agent-core 或 pi-ai。

非 Node.js 宿主通常优先使用 RPC：

pi --mode rpc

调用方需要维护 Pi 子进程，并正确处理以换行分隔的 JSONL 消息。只做自动化输出时，JSON mode 通常比完整 RPC 更简单。

安全边界#

Pi 是本地 Coding Agent，默认继承启动它的用户权限。官方安全文档明确说明：Pi 没有内置 Sandbox，Project Trust 也不是 Sandbox。

Project Trust 主要控制项目级 .pi/settings.json、Extensions、Skills、Prompts、Themes、System Prompt 和 Package 是否在启动时加载。它不能阻止模型之后通过已开放的 bash、write 或 edit 操作本机资源。

实际使用至少应遵循以下原则：

• 陌生仓库先使用 --tools read,grep,find,ls 只读检查。
• 不信任项目级 Extensions、Skills、AGENTS.md、源码注释和构建输出中的指令。
• 安装第三方 Package 前审查源码；Extension 与普通本地程序拥有相同权限。
• 把 API Key、SSH Key、云凭据和浏览器登录状态限制在任务必需范围。
• 重要修改前保留 Git checkpoint，完成后检查 git diff 和测试结果。
• 无人值守、来源不明或高风险任务应在 Container、VM、micro-VM 或其他操作系统级隔离环境中运行。
• 即使使用 Container，读写挂载的宿主目录仍会被容器内进程修改；需要更强保护时使用只读挂载或复制进出。

只读 Tool allowlist、应用内确认弹窗和 Project Trust 都有价值，但它们解决的是不同层次的问题，不能被描述为完整隔离。

推荐学习路线#

第一天：掌握核心循环#

1. 安装并完成 /login。
2. 在 Git 仓库里运行一次只读分析。
3. 让 Pi 修改一个小问题并运行测试。
4. 学会用 @file、!command 和 git diff 检查过程。

第二阶段：建立可重复工作流#

1. 编写简短的项目 AGENTS.md。
2. 用 --tools 为审查任务建立只读模式。
3. 用 Session name、/tree、/fork 和 /compact 管理长任务。
4. 把经常重复的 Prompt 做成 Prompt Template 或 Skill。

第三阶段：按需扩展#

1. 先临时加载一个经过审查的 Extension。
2. 根据真实需求选择 MCP、Subagents、Web access 或 Permission gate。
3. 为团队工作流编写自己的 Skill 或 Extension。
4. 只有需要嵌入产品时，再学习 SDK、JSON mode 或 RPC mode。

参考资料#

• Pi Documentation
• Pi Quickstart
• Using Pi
• Providers
• Security
• Extensions
• Skills
• Pi Packages
• SDK
• RPC mode
• Pi 官方 GitHub 仓库
• 官方 Extension Examples
• Pi Package Catalog
• pi-subagents Package 页面
• pi-mcp-adapter Package 页面
• pi-web-access Package 页面