第 10 课：Pi 包与命令行参考

最后一课！今天讲：如何把你构建的一切（扩展、技能、提示词、主题）作为 pi 包 分享出去，以及 TUI 之外的完整 CLI 工具集。

Pi 包：打包与分享

一个 pi 包把扩展、技能、提示词和主题打包，通过 npm 或 git 分发。在 package.json 里用 pi 键定义：

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

没有清单？pi 会自动发现约定目录：extensions/、skills/、prompts/、themes/。

安装包：

pi install npm:@foo/pi-tools
pi install npm:@foo/pi-tools@1.2.3            # 固定版本
pi install git:github.com/user/repo
pi install git:github.com/user/repo@v1        # tag/commit
pi install https://github.com/user/repo
pi install ssh://git@github.com/user/repo

• -l 表示项目本地安装（.pi/git/、.pi/npm/）
• 包安装到 ~/.pi/agent/git/ 或 ~/.pi/agent/npm/
• pi list 查看已安装；pi remove/pi uninstall 移除

管理：

pi update               # 更新 pi 本身
pi update --all         # pi + 包
pi update --extensions  # 只更新包
pi update --models      # 刷新模型目录
pi update --self --force
pi config               # 启用/禁用包的资源

过滤资源 — 只加载你想要的：

{
  "packages": [
    { "source": "pi-skills", "skills": ["brave-search"], "extensions": [] }
  ]
}

安全警告： 包以完整系统权限运行——扩展执行任意代码，技能可以指示模型做任何事。安装前审查源码。通过 npm search keywords:pi-package 或 Discord 找包。

CLI 参考

TUI 之外，pi 是一个完整的命令行工具：pi [options] [@files...] [messages...]。

模式：

pi -p "Summarize this codebase"              # 打印模式，回答后退出
cat README.md | pi -p "Summarize this text"  # 管道输入
pi --mode json                               # JSON 事件行（自动化）
pi --mode rpc                                # 进程集成协议
pi --export session.jsonl out.html           # 导出为 HTML

模型选项： --provider、--model pattern（支持 provider/id 和 :thinking）、--api-key、--thinking level、--models "claude-*,gpt-4o"、--list-models。

会话选项： -c（继续）、-r（恢复选择器）、--session、--fork、--session-dir、--no-session、--name。

工具选项：

pi --tools read,grep,find,ls -p "Review"     # 白名单
pi --exclude-tools ask_question              # 禁用某一个
pi --no-builtin-tools                        # 只要扩展工具
pi --no-tools                                # 全禁用

资源选项： -e/--extension、--skill、--prompt-template、--theme（都可重复），加上 --no-extensions、--no-skills、--no-prompt-templates、--no-themes、--no-context-files。把 --no-* 和显式加载组合起来可以完全忽略设置：pi --no-extensions -e ./my-ext.ts。

其他： --system-prompt、--append-system-prompt、-a/--approve（信任项目）、-na、--verbose、-h、-v。

文件参数： pi @code.ts @test.ts "Review these files"。

值得了解的环境变量： PI_CODING_AGENT（检测是否运行在 pi 内）、PI_OFFLINE=1（无网络）、PI_SKIP_VERSION_CHECK=1、PI_TELEMETRY=0、PI_CODING_AGENT_DIR（配置目录覆盖）、PI_CACHE_RETENTION=long（延长提示缓存）。

一句话哲学

Pi 保持核心精简，把工作流专属行为推到扩展、技能、提示词、主题和包里。没有 MCP、没有子代理、没有权限弹窗、没有计划模式、没有待办、没有后台 bash——这是设计使然。按需自己构建，或安装别人的，正好在你需要的时候。

下一步

• 复习任何一课：/hotkeys、/settings、/tree 查看会话历史
• 阅读文档：~/.npm-global/lib/node_modules/@earendil-works/pi-coding-agent/docs/
• 探索真实示例：examples/extensions/
• 可安装的仓库：badlogic/pi-skills、anthropics/skills
• 加入 Discord（README 中有链接）——社区分享各种包

最终作业： 用你之前实验的成果（一个提示词模板 + 一个扩展）创建一个微型 pi 包，从一个 git 仓库 pi install 它，再用 pi config 切换它的资源。这就是完整的闭环：构建 → 分享 → 使用。

现在你已经完整掌握了 pi。🎉