配置与扩展

这一页讨论的是扩展 Pi CLI 的工作流。如果你想做自己的 Vue Agent 产品，而不是给 Pi 增加命令或工具，请直接前往 SDK 与 Vue 最小集成。

先分清三个作用域

作用域	典型位置	适合放什么
全局	`~/.pi/agent/`	个人默认设置、通用技能、全局扩展
项目	仓库中的 `.pi/`	团队共享设置、Skill、扩展、模板和主题
兼容 Skill	仓库中的 `.agents/skills/`	只用于项目 Skill 的发现
上下文	`AGENTS.md`、`CLAUDE.md`	项目命令、约束、事实和协作偏好

全局设置通常位于 ~/.pi/agent/settings.json，项目设置位于 .pi/settings.json，项目值会覆盖全局值。项目资源需要你信任仓库后才会启用。

有一个重要例外：AGENTS.md 和 CLAUDE.md 默认会进入上下文，即使项目没有被信任。它们是提示上下文，不是可执行扩展，但仍可能影响 Agent 行为。

用最轻的机制解决问题

text

稳定项目约束
    ↓
AGENTS.md
    ↓ 高频提示
Prompt Template
    ↓ 可复用领域流程
Skill
    ↓ 新工具、命令、UI 或生命周期拦截
Extension
    ↓ 团队安装与版本分发
Pi Package

机制	本质	适合	不适合
`AGENTS.md`	始终加载的项目说明	命令、目录边界、完成标准	一次性任务、秘密
Prompt Template	可展开的提示文本	高频 review、发布说明骨架	新工具或自动执行
Skill	按需加载的说明与配套资源	领域流程、框架规范	直接注册 UI 或工具
Extension	在 Pi 进程内执行的 TypeScript / JavaScript	工具、命令、事件拦截、TUI	仅靠文字就能说明的规则
Pi Package	可安装的资源集合	团队共享和版本化	未审查的来源

Skill 的 SKILL.md 不会像 Extension 一样自动在 Pi 进程内执行，但 Skill 可以携带脚本，并引导 Agent 通过工具运行它们。审查 Skill 时要看完整目录，不只看说明文件。Extension 则是直接运行的代码，两者的风险机制不同。

想立即动手，可以分别完成第一个 Skill和第一个 Extension。两篇教程都从只读能力开始，并包含独立验证步骤。

常见发现位置

资源	全局	项目
Extensions	`~/.pi/agent/extensions/`	`.pi/extensions/`
Skills	`~/.pi/agent/skills/`、`~/.agents/skills/`	`.pi/skills/`、`.agents/skills/`
Prompt Templates	`~/.pi/agent/prompts/`	`.pi/prompts/`
Themes	`~/.pi/agent/themes/`	`.pi/themes/`

具体发现规则和包字段会随版本演进。创建资源前分别查看官方 Skills、Extensions 和 Prompt Templates。

`/reload` 还是重启

变化	推荐动作
修改快捷键、上下文、扩展、Skill、模板或主题	执行 `/reload`
用 `/trust` 保存新的项目决策	重启 Pi，让启动加载流程重新判断
修改启动参数或环境变量	退出并重新启动
只改当前任务要求	直接发送 steering 消息

/reload 适合开发扩展时快速迭代，但不能把未信任的项目变成可信，也不会改变操作系统权限。

从 `AGENTS.md` 开始

对大多数团队，第一项定制应该是项目根目录的 AGENTS.md：

markdown

# Project Instructions

- 使用 pnpm，不要生成 npm 或 Yarn lockfile。
- 只修改任务明确涉及的目录。
- 修改 TypeScript 后运行 `pnpm typecheck`。
- 不执行部署、发布、迁移或发送消息。
- 完成时列出改动、验证结果和剩余风险。

写稳定事实，不写某次任务的临时对话。命令变化后同步维护，否则陈旧说明会比没有说明更危险。

什么时候才写 Extension

只有在需要下面能力时，再进入 Extension：

注册模型可调用的新工具。
新增斜杠命令。
在工具执行前做策略校验或确认。
订阅会话生命周期事件。
提供自定义终端 UI。

不要从未经核对的博客复制一个 any 到处传递的示例。先从与当前 Pi 版本一致的官方扩展示例开始，并固定依赖版本。

安装 Package 前

Pi Package 可以分发 Extension、Skill、模板和主题。便捷不等于低风险：

检查发布者、源码与固定版本。
阅读安装脚本和依赖。
确认扩展会读取哪些文件、环境变量和网络资源。
先在隔离环境或低价值项目中试用。

相关安装命令见命令速查，完整风险模型见权限与安全边界。

关键数据目录

text

~/.pi/agent/
├── auth.json          # 认证信息
├── settings.json      # 全局设置
├── models.json        # 自定义模型
├── models-store.json  # 模型目录缓存
├── sessions/          # 会话
├── extensions/        # 全局扩展
├── skills/            # 全局 Skills
├── prompts/           # 全局模板
└── themes/            # 全局主题

卸载 CLI 不等于删除这些数据。迁移或清理前先区分凭据、会话和可重新生成的缓存，不要用一条递归删除命令处理整个目录。

下一步：先用 Skill 固化一个工作流，或用 Extension 注册代码级能力；如果要把能力嵌入其他程序，继续读自动化与程序集成。

配置与扩展 ​

先分清三个作用域 ​

用最轻的机制解决问题 ​

常见发现位置 ​

/reload 还是重启 ​

从 AGENTS.md 开始 ​

什么时候才写 Extension ​

安装 Package 前 ​

关键数据目录 ​