Pi Coding Agent 到底怎么用：一套只给四个工具的编码代理

先记住这三句

你现在是什么处境，直接跳到哪一节

从零到能干活，只要这几步

读完你应该能

• 用一句话说清 Pi 和 Claude Code 这类"全家桶"代理差在哪，以及这个差别对你是好是坏；
• 从零装好、连上模型，在一个真实项目里让它完成一次"读 → 改 → 跑命令验证"；
• 说出它默认不做哪五件事，并知道每一件该用什么补；
• 写出你自己的第一个 Skill 或 AGENTS.md，让它的行为符合你们团队的习惯；
• 判断一个任务该用交互模式还是单发模式，该用 --tools 还是该套容器。

01Pi 到底是什么？

它是什么：一句话 + 三个名字

Pi（读音 /paɪ/，命令就是 pi）是一个运行在终端里的极简 AI 编码代理。官方给自己的定位叫 minimal agent harness——字面意思是"极简的代理驱动框架"。

这里有两个词要拆开。第一个是"代理"（agent）：它不是聊天机器人，它会动手。第二个是"驱动框架"（harness）：它是套在模型外面的那层壳——负责把工具递给模型、把工具的输出塞回给模型、把整个过程记下来。模型负责"想"，Pi 负责"让它能动手并且看得见"。

它由 Mario Zechner（网名 badlogic，LibGDX 游戏引擎的作者）和 Earendil 公司开发，MIT 协议开源。官网 pi.dev，源码在 github.com/earendil-works/pi，命令行的 npm 包名是 @earendil-works/pi-coding-agent。

它怎么干活：工具调用循环

这个循环在行业里叫 工具调用循环（tool-use loop）。它不是 Pi 独有的，几乎所有编码代理都这么跑。差别在于：循环里能用的工具有几个、上下文里被塞进了什么、以及这些事你能不能看见。

它和 Claude Code 差在哪：不是功能多少，是默认值

最省事的记法是：Claude Code 开箱就把一堆功能装好了；Pi 开箱只有四个工具，缺什么你自己加。

官方 README 的原话是 "Pi ships with powerful defaults but skips features like sub agents and plan mode"——它带着很强的默认值出厂，但主动跳过了子代理和 Plan 模式这类功能。跳过的理由是：与其替你决定工作流，不如让你把它改造成你的形状。

名字别搞混：这里的 Pi 指哪一个

Pi 这个字太小，网上至少还有另一个同名项目：一个 Python 写的 pi-agent，用 pip install pi-coding-agent 也能装出一个叫 pi 的命令。两者命令名相同，但互不相干。

本文讲的是官网 pi.dev 对应的这个。判断方法很简单：装完跑 pi --version，能对上 0.85.x 这个系列的才是。

三个最容易混的概念

新手最先误会的往往不是功能，而是"它是哪一层"。这三个区分清楚，后面全篇都好读：

02它解决什么问题，什么时候该用它

它解决什么问题

Pi 的作者长期用 Claude Code，后来形容它"变成了一艘 80% 功能他根本用不上的宇宙飞船"，而且每次发布都改系统提示和工具集，把他习惯的工作流打断。于是他按自己的需求重写了一个：内核可预测、不偷偷往上下文里塞东西、一切可以检查、会话格式干净、能接本地模型。

什么场景该用它

03它"刻意不做"什么？

理解 Pi 最快的方式，是看它主动删掉了哪些"标配"。下面每一行都是官方明说"不做"的，最后一列是它建议的替代路径。

四种运行形态，新手只需要先会用第一种

内核只有一个，但 Pi 对外提供四种"怎么用"的形态，覆盖从人机对话到嵌入你自己的程序：

04怎么装？三步装完还能自检

0. 前置条件：Node.js ≥ 22.19

Pi 是用 TypeScript 写的，通过 npm 分发，运行环境要求 Node.js 22.19 或更高（这是 npm 上声明的 engines 字段，本文按 0.85.1 核对）。如果你还没装 Node，macOS（Apple Silicon）推荐用 Homebrew：

# 先确认有没有装 Homebrew（macOS 的包管理器）
brew --version

# 没有的话先装 Homebrew（官网脚本，粘贴到终端回车）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 用 Homebrew 安装 Node.js
brew install node

# 验证版本（应 >= 22.19.0）
node --version

1. 装 Pi（三选一）

官方提供三种入口。本文推荐 npm 方式——可预测、好升级。注意官方的 --ignore-scripts 不是可选项而是明确要求：Pi 正常安装不需要执行依赖的生命周期脚本，加上更安全。

# 方式 A（推荐）：npm 全局安装
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# 方式 B：官方一键安装脚本（curl 到管道给 sh，介意可不用）
curl -fsSL https://pi.dev/install.sh | sh

# 方式 C：Windows PowerShell 用户
# powershell -c "irm https://pi.dev/install.ps1 | iex"

官网还给了 pnpm add -g --ignore-scripts @earendil-works/pi-coding-agent 和 bun add -g --ignore-scripts @earendil-works/pi-coding-agent 两种等价写法——如果你平时用 pnpm 或 bun，就用你熟的那条。

2. 验证安装

pi --version    # 应显示当前版本号，如 0.85.1
pi --help       # 查看全部参数用法

3. 更新

Pi 每次启动会联网查一次最新版本（可以关，见 §99）。手动升级命令和"第三方包升级"是分开的，别搞混：

pi update            # 只升级 Pi 本身
pi update --models   # 只刷新各提供商的模型目录（推荐装完就执行一次）
pi update --all      # Pi + 所有已安装的第三方包
pi update --self --force   # 强制重装当前版本（用于修复损坏）

4. 启动前的三步自检

新手最常见的挫败不是 Pi 不好用，而是环境没到位。花 30 秒过一遍这三件事，能避开大半问题：

装在哪、想卸干净怎么卸

安装问题的三种典型症状

05怎么接上模型？Key、登录、换模型、本地跑

两种认证方式，先选一种

# 在终端里临时设置（当前窗口有效）
export ANTHROPIC_API_KEY=sk-ant-...

# 然后启动
pi

pi
/login

它支持哪些提供商

官网首页的表述是"15+ 提供商、数百个模型"，而 README 里逐个列出的内置提供商目录已经有三十多个。按 0.85.1 的官方列表，大致可以分成三类：

自定义提供商通过 ~/.pi/agent/models.json 添加——只要对方说 OpenAI / Anthropic / Google 三种方言之一就行。要接完全自定义的 API 或 OAuth，那得写扩展。

在会话里换模型 / 设默认

Pi 很方便的一点是：会话中途随时能换模型，不用重开。

不想先进交互界面也可以，直接带参数启动指定模型：

# 也可以不先进交互界面，直接带参数启动指定模型
pi --provider anthropic --model claude-... "帮我重构这个函数"

# 用 "提供商/模型" 前缀可以省略 --provider
pi --model openai/gpt-... "给这段代码写测试"

# 想加高思考强度（型号后接 :high）
pi --model anthropic/claude-...:high "解一道复杂算法题"

# 查看某提供商有哪些可选模型
pi --list-models anthropic

本地 / 私密运行（可选）

想把代码留在本机、或者单纯省 API 费，可以接本地模型：

• Ollama：装好 Ollama 并拉一个模型（如 qwen2.5-coder:7b），在 /login 里选 Ollama 提供商。Ollama 官方文档有专门收录 Pi 的接入说明。
• llama.cpp：Pi 支持 llama.cpp 的路由服务器，用 /llama 下载 / 加载模型，再用 /model 选。
• 任意 OpenAI 兼容服务：通过 models.json 指到你的端点，比如公司内网网关。

同时配了多个 Key，怎么指定用谁

你可以把 Anthropic、OpenAI、DeepSeek 的 Key 全设上。Pi 的规则是：

• 不指定时用默认提供商 / 模型（首次会引导你选，之后可用 Ctrl+S 存默认）；
• 想临时指定，启动时加 --provider deepseek --model deepseek-chat 之类参数，或启动后 Ctrl+L 切；
• 命令行 --api-key 可直接传 Key（会覆盖环境变量）——适合脚本里临时换账号，但它可能留在 shell 历史里。

登录 / 连接问题速查

06最小例子：第一次让它干活

假设你已经装好并配好 Key。第一件事：先进入你打算让它干活的项目目录。Pi 只看得到当前目录（它把这个目录叫工作区），会话也默认按目录分开存。

cd ~/Desktop/my-demo-project   # 换成你的项目目录
pi                            # 启动交互式界面

然后像给同事发消息一样，直接敲任务。第一句先让它摸底：

这个目录里有什么？帮我看看结构。

它调用 bash 里的 ls、read 等工具探索目录，然后总结每个文件是干嘛的。注意你会看到每一步的原始输出，而不是只有结论。

第二句才是真正的活：

在 demo.py 里加一个函数 hello(name)，返回 "Hello, " + name，然后跑一下验证。

跑到一半想插话，有两种插法

比如你觉得它想复杂了：

先别加参数校验，保持简单。

按 Enter 发送，这是转向消息：它执行完当前工具后立刻送达，并打断剩下的动作。按 Alt+Enter 则是追问：排在队尾，等它把这一轮全部干完才送。选错的话，要么打断了它，要么白等半天。

让 Pi 一次看懂更多：@ 引用文件

在输入框里打 @ 会弹出项目文件的模糊搜索，选中就把该文件内容放进本次消息——等价于"把这份文件也看进去"：

@src/utils.ts 帮我看下这个文件里的格式化函数有没有 bug

命令行里也一样，可以在参数位置直接写 @文件。想让它一次性看两份文件再对比，就用两个 @：

pi @src/foo.ts @src/bar.ts "Review these two files"

想贴图片：交互界面里 Ctrl+V 粘贴，或直接把图片文件拖进终端；单发模式下用 pi -p @screenshot.png "What's in this image?"。

把这次会话起个名字

一行命令问完就走、还想以后能翻到它，用单发模式加个名字：

pi --name "release audit" -p "Audit this repository"

会话默认存在按目录分类的文件夹里，所以名字起得清楚，找起来省事。会话的完整玩法（树、分叉、压缩、导出）在 §10。

07完整演练：从零搭一个待办清单小工具

下面这场对话你可以照着在自己的空目录里跑一遍，体会"从想法到能跑"的全过程。每一句后括号里是 Pi 大概会做的事——你只需要发左边那句话，然后看它表演。

mkdir ~/Desktop/todo-demo && cd ~/Desktop/todo-demo && pi
做一个命令行待办清单工具 todo.py：支持 add "事项" 添加、list 列出、done 序号 标记完成。数据存在同目录 todos.json。

跑一下试试：添加两条，列出来，再完成第一条，确认输出和 todos.json 都正常。

再加一个子命令 clear，一键清空已完成的事项。

写个 README.md，把每个子命令的用法列清楚。

从这场演练里能学到的三件事

为什么"先圈地盘"和"先验证"是硬要求

08四种运行形态与常用 CLI：什么时候用哪个

形态总览

最常用的单发用法（print 模式）

不想进交互界面，问一次拿结果就走——非常适合作 shell 脚本或快捷命令：

# 一句话问答
pi -p "总结这个 README 的要点"

# 用 -- 让以横杠开头的内容不被当成参数
pi -p -- "- 用三点概括这个仓库"

# 把文件内容通过管道喂给它（print 模式会自动读 stdin）
cat README.md | pi -p "Summarize this text"

# 把文件作为消息的一部分（@ 前缀）
pi @prompt.md "按这个要求写代码"
pi @src/foo.ts @src/bar.ts "Review these two files"

# 附带截图问"图里有什么"（-p 单发 + 图片 @）
pi -p @screenshot.png "What's in this image?"

# 命名一次性会话（好找历史）
pi --name "release audit" -p "Audit this repository"

常用命令行参数

下面这张表按用途分组，名字和取值都按 0.85.1 的 pi --help 核对过。

默认内置工具与"只读"用法

默认给模型的是四个：read（读文件）、write（写文件）、edit（精准改文件）、bash（执行命令；Windows 上另有 powershell）。另外还有 grep、find、ls 三个只读工具，默认不启用，需要用 --tools 打开。

pi -p "这个仓库结构怎么样？顺便跑一下测试"

pi --tools read,grep,find,ls -p "Review the code for bugs"

SDK 与 RPC：给想写程序的人的两扇门

前三种形态都是"Pi 是主角、你在旁边用"。想把 Pi 的能力嵌进自己的程序（内部助手、批处理工具），用后两种：

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

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

await session.prompt("当前目录下有哪些文件？");

pi --mode rpc

子进程怎么知道"自己在 Pi 里"

Pi 启动 CLI / RPC 时会给子进程注入两个标记：AI_AGENT=pi 和 PI_CODING_AGENT=true——通用工具据此识别"我正在被 AI 代理调用"。跑 shell 工具时还会带上当前会话元数据（PI_SESSION_ID、PI_MODEL、PI_PROVIDER、PI_REASONING_LEVEL 等），你写的脚本可以按需读取。

09界面从上到下是什么，快捷键记哪几个

界面从上到下

一段典型会话在界面里大概长这样（简化示意）：

┌────────────────────────────────────────────────────────────┐
│ ⌘ 快捷键: /hotkeys · AGENTS: 1 · 模板: 2 · skills: 3       │ ← 启动头部
├────────────────────────────────────────────────────────────┤
│ 你: 帮我看看 src/utils.ts 的格式化函数有没有 bug            │
│ Pi: 我先读一下这个文件…  [调用 read]                       │
│    ┌─ 工具输出 ────────────────────────────────────┐       │
│    │ (文件内容)                                     │       │
│    └────────────────────────────────────────────────┘       │ ← 消息区
│ Pi: 找到一个问题：第 12 行缺判空，我准备改一下…            │
├────────────────────────────────────────────────────────────┤
│ > _                      边框颜色=思考强度 · 流式指示灯     │ ← 输入框
├────────────────────────────────────────────────────────────┤
│ ~/demo · todo-demo · ↑1.2k ↓3.4k R2.0k W0 CH91% · $0.012   │ ← 底部状态栏
└────────────────────────────────────────────────────────────┘

输入框里的六个小技巧

斜杠命令：打 / 就会列出来

扩展可以注册自定义命令，Skill 以 /skill:名字 调用，提示模板用 /模板名 展开。内置的常用命令：

高频快捷键

消息队列：边跑边插话

Escape 中止当前运行并把排队消息退回输入框，方便你改。行为可在 /settings 里调：steeringMode / followUpMode 默认 "one-at-a-time"（发一条等一条），可改成 "all"（攒着一起发）。

学会读底部状态栏（省钱的第一步）

/settings 里可以调什么

常用偏好都在 /settings 面板里改，改动写进 settings.json（全局 ~/.pi/agent/settings.json，项目级 .pi/settings.json 可覆盖）：

• 主题：dark / light，主题文件改完即时热生效；
• 消息投递：转向 / 追问走 one-at-a-time 还是 all；
• transport：对支持多传输的提供商选 sse / websocket / auto；
• 自动压缩策略：临近上限是否主动压缩；
• 信任默认值：defaultProjectTrust 设为 ask / always / never。

进阶用户可以直接编辑 JSON 加更多键（完整选项表见官方 docs/settings.md）。项目级设置里写路径、资源时，只有"你信任了该项目"之后它才会被加载——这一点在 §14 细讲。

10会话怎么管：树、分叉、压缩、导出

会话存在哪、长什么样

每次会话自动保存成一条 JSONL 文件（每行一条记录），存在 ~/.pi/agent/sessions/，按工作目录分文件夹。文件内部是树结构：每条记录有 id 和 parentId。这意味着"反悔回到岔路口再走另一条路"不需要另存文件。

# 会话相关的 CLI
pi -c                    # 继续最近一次会话
pi -r                    # 浏览并挑一个历史会话
pi --no-session          # 临时模式：这次不存
pi --name "我的任务"      # 启动时给会话起个名
pi --session <路径或ID>  # 指定用某个会话文件
pi --fork <路径或ID>     # 把某个会话分叉成新会话

会话树：回到任意节点重新来

把会话当作一棵树：你在每个岔路口（某条消息之后）都可能走过不同的路。用 /tree 上下选择任意历史节点，从这个节点继续，或在不同分支间切换。所有分支都在同一个文件里，历史不丢。

另外两个快捷方式是"把某条思路单独拎出来继续"：/fork 从某条历史消息另起新会话；/clone 把当前分支复制成新会话。做实验性改动时很有用——改坏了主线还在。

上下文压缩（compaction）

会话长了会顶到模型的上下文上限。Pi 的处理办法是把较早的消息总结成摘要、保留较新的，腾出空间继续聊：

• 手动：/compact，或 /compact 加自定义指令（比如"重点保留我们决定的接口"）；
• 自动（默认开）：临近上限时主动压缩；溢出时能自动恢复并重试。可在 /settings 里调。

导出、分享、继续

会话文件长什么样（一瞥）

想理解"为什么能回退、能分支"，瞄一眼 JSONL 就懂了。每行一条记录，靠 id / parentId 串成一棵树（字段为示意，结构以官方 docs/session-format.md 为准）：

{"id":"m1","parentId":null,"role":"user","content":"列一下文件"}
{"id":"m2","parentId":"m1","role":"assistant","content":"我用 ls 看看","toolCalls":["ls"]}
{"id":"m3","parentId":"m2","role":"tool","name":"bash","output":"a.py  b.py  README.md"}
{"id":"m4","parentId":"m2","role":"assistant","content":"目录里有三个文件…"}   ← m2 下另一条路 = 一个分支

留意最后一条：它在 m2 下面"另起炉灶"，就是你在 /tree 里看到的分叉。好处是原始记录永远在文件里——哪怕上下文被压缩成了摘要，翻文件仍能找回当时细节。所以别乱改或乱删 sessions 文件。

想知道当前会话 ID，用 /session；拿到 ID 后可以在命令行 pi --session 该ID 精确续跑，或 pi --fork 该ID 分叉。

会话会占多少空间，怎么清理

11Skills：怎么给 Pi 加一项新能力（不写代码）

Skill 是什么

一个 Skill（技能）就是一个目录，里面放一份 SKILL.md，用来说明这个能力"何时用、怎么用、注意什么"，另外可以带若干脚本或文件。Pi 遵循通用的 Agent Skills 标准（agentskills.io）。

关键在于它不会把每个 Skill 都塞进上下文，而是按相关性按需加载。官网把这叫"渐进式披露而不击穿提示缓存"——既给了模型能力，又不白白烧 token。

一个最小 Skill 长这样

# ~/.pi/agent/skills/my-skill/SKILL.md
# My Skill
当用户要求处理 X 类事情时使用本技能。

## 步骤
1. 先做这件事
2. 再做那件事

放哪、怎么分享

技能按"项目 < 全局 < 打包"分布，Pi 会逐层找：

• 项目级：.pi/skills/、.agents/skills/（从当前目录往上逐级）；
• 全局级：~/.pi/agent/skills/、~/.agents/skills/；
• 打包分享：装进一个 Pi Package，团队一条命令装好。

# 命令行可临时指定技能目录 / 禁用技能发现
pi --skill ./my-skill-dir "..."
pi --no-skills "只用默认能力"

一个可直接复制的完整例子

假设你想让 Pi 学会"按你们团队的清单做发布前检查"。建一个 Skill 目录：

# 项目级：放进 .pi/skills/deploy-check/（从当前项目往上逐级都能识别）
# 全局级：放进 ~/.pi/agent/skills/deploy-check/

deploy-check/
├── SKILL.md        # 给模型看的"何时用、怎么用"
└── preflight.sh    # 实际干活的脚本

两份文件的内容分别是：

# SKILL.md
# 发布前检查（deploy-check）
当用户要求"发布 / 上线前检查"时使用本技能。

## 步骤
1. 读 preflight.sh，先跑一遍；任何一步失败都停下来报告，不要继续。
2. 逐条给用户列出 通过 / 失败 及失败原因。
3. 只有全部通过，才允许用户执行 git push / 部署命令。

# preflight.sh
#!/usr/bin/env bash
# 示例：三条检查，都通过才返回 0
set -e
echo "1) 语法检查：pnpm tsc --noEmit"
pnpm tsc --noEmit
echo "2) 测试：pnpm test"
pnpm test
echo "3) 无未提交改动：git status --porcelain 应为空"
[ -z "$(git status --porcelain)" ] || { echo "还有未提交改动，先提交或 stash"; exit 1; }
echo "全部通过 ✔"

用法：在会话里发"帮我做发布前检查"，Pi 命中 Skill 描述后自动加载 SKILL.md，按指示执行 bash preflight.sh，并把结果逐条汇报给你。

复用你已有的脚本

你已经有的检查脚本、一键部署脚本，包一层 SKILL.md 就是 Skill。很多"给 Pi 加能力"的需求，本质都是"把已有命令行工具用文档喂给它"。

12上下文工程：AGENTS.md、SYSTEM.md 与提示模板

Pi 官方把"控制什么进上下文"称为 上下文工程（context engineering）。这是它跟全家桶型代理最大的区别点：系统提示极短、注入内容全部可见可管。这一节讲四个控制入口和一张路径表。

AGENTS.md：项目指令，最值得先写的一个

启动时 Pi 会从三处拼接项目级指令文件（等价于 Claude Code 的 CLAUDE.md）：

• ~/.pi/agent/AGENTS.md —— 全局，所有项目都用；
• 当前目录各级父目录里的 AGENTS.md（往上逐级找，拼接）；
• 当前目录里的 AGENTS.md（也认 CLAUDE.md 这个名字）。

# 项目根目录 AGENTS.md 示例
# 项目约定
- 用 pnpm 装依赖；命令统一 `pnpm run dev` 起本地服务
- 代码注释写中文，变量名/函数名用英文
- 提交信息按 Conventional Commits：feat: / fix: / docs:
- 测试放在 test/ 目录，改动后必须跑 `pnpm test`

细节：若某目录存在 AGENTS.override.md，Pi 会用它替代该目录下的 AGENTS.md / CLAUDE.md（其余目录的仍然拼接）。想整条关掉上下文文件，用 --no-context-files（-nc）。

SYSTEM.md：替换 / 追加系统提示

Pi 内置一个极简系统提示，这是它省 token 的来源之一。你可以按项目覆盖：

提示模板：把常用需求存成斜杠命令

把"经常重复的一整段要求"存成一个 Markdown 文件，之后在输入框打 /模板名 一键展开。模板支持 {{变量名}} 占位：

<!-- ~/.pi/agent/prompts/review.md -->
Review this code for bugs, security issues, and performance problems.
Focus on: {{focus}}

# 使用时
/review          # 展开模板，把 {{focus}} 替换成你想聚焦的内容再回车

动态上下文：扩展注入、RAG、长期记忆

对进阶用户，扩展可以在每轮对话前注入消息、过滤历史、实现检索增强（RAG）甚至长期记忆。也就是说，"Pi 记不记得上个礼拜的事"不是内置功能，而是可以自己用扩展做出来的东西——这正是"原语而非功能"哲学的落点。

配置与数据都在哪：一张路径表

想备份、迁移或排查，先知道东西放哪。Pi 的"地盘"以 ~/.pi/agent/ 为根（可用环境变量 PI_CODING_AGENT_DIR 改），项目级则用 .pi/：

整体备份 = 复制 ~/.pi/agent/；换机器恢复时，重装 Pi 再把这个目录放回去即可（~/.agents/skills/ 这类系统级位置也常一起搬）。

13扩展系统：把 Pi 变成"你自己的"

一个扩展就是一个 TypeScript 模块

扩展是给 Pi 加"新器官"的正规方式：可以注册自定义工具（让模型能调用）、斜杠命令、键盘快捷键、订阅生命周期事件，甚至画整块界面。骨架如下：

// ~/.pi/agent/extensions/my-ext.ts  或  .pi/extensions/my-ext.ts
export default function (pi: ExtensionAPI) {
  // 给模型加一个能调用的新工具
  pi.registerTool({ name: "deploy", description: "部署到测试环境", ... });

  // 给自己加一个 /命令
  pi.registerCommand("stats", { ... });

  // 监听事件，比如每次工具调用后做点事
  pi.on("tool_call", async (event, ctx) => { ... });
}

默认导出也可以写成 async——Pi 会等异步初始化完成再继续启动。适合"启动时联网拉一次远程模型列表，再注册提供商"这种一次性初始化。

能做出什么（官方列举）

改完热生效

写好或改好扩展、Skill、提示模板、主题后，不用重启：在会话里执行 /reload 即可重新加载。放扩展的目录：全局 ~/.pi/agent/extensions/、项目级 .pi/extensions/，或打进包。

打包分享：Pi Package

把自己攒的扩展、Skills、提示模板、主题一起打包成一个 Pi 包，别人（或团队）一条命令装好：

# 安装第三方包（来源：npm 或 git）
pi install npm:@foo/pi-tools
pi install npm:@foo/pi-tools@1.2.3      # 锁版本
pi install git:github.com/user/repo@v1   # 锁 tag / commit
pi install https://github.com/user/repo

# 管理
pi list                # 看装了哪些包
pi update --all        # Pi + 包一起更新
pi update npm:@foo/pi-tools   # 只更新某个包
pi remove npm:@foo/pi-tools    # 卸载
pi config              # 启用 / 禁用某个包里的资源
# 想只装进当前项目，加 -l（项目级）

包本身就是一个带 package.json 的仓库，通过 pi 字段声明要暴露的目录；没声明时，Pi 会自动识别约定的 extensions/、skills/、prompts/、themes/ 目录：

{
  "name": "my-pi-package",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"]
  }
}

动手试：让 Pi 自己写你的第一个扩展

扩展不是只能你自己写——这是 Pi 很妙的一点：你可以让 Pi 写扩展给 Pi 用。流程通常是：

扩展 vs Skill：怎么选

14安全边界：默认很"敢"，护栏要自己搭

先认清默认值

Pi 没有内置权限弹窗，启动后基本就是以你的用户身份在跑命令。这既是效率（不被打断），也是风险（无人把关）。官方给的安全策略由松到严一共四档：

"项目信任"到底在决定什么

项目里有本地设置或资源时，Pi 启动会问你是否信任该项目。它的门道是：信任决定的是"项目里的代码和设置要不要被加载"，不只是弹个窗。

非交互模式（-p / --mode json / --mode rpc）不弹信任框，按全局的 defaultProjectTrust 处理：ask 是默认值（忽略项目资源），never 忽略，always 信任。可以针对单次运行用 -a/--approve（临时信任）或 -na/--no-approve（临时忽略）覆盖。

日常最佳实践清单

给三类人的起步配方

15常见坑：九种典型翻车与怎么绕开

开工前最容易踩的三个

这三个的共同点是：出事的那一刻你还没意识到自己在出错。它们排在最前面，是因为代价最大、也最容易避免。

用着用着才暴露的三个

这三个通常发生在你已经用它干了几天活之后——不是它坏了，是它的工作方式和你以为的不一样。

长会话与协作时的三个

这三个跟"用得久"有关：上下文越攒越多、分享的东西越来越杂，风险也跟着变。

99速查表：命令、环境变量、键位

命令速查

环境变量速查

键位速查

想深入某块？官方文档地图

本文是"把 Pi 用起来"的入门。官方仓库 packages/coding-agent/docs/ 里每块都有专门文档，按需查：

17参考来源与证据边界

16术语对照表

只收正文里反复出现、值得回头查的词。第三列回答的是"为什么重要 / 什么时候用 · 别当什么用"，不是翻译。

18一句话总结