这个集成做什么
Pi 集成是一个扩展包，而不是 MCP 配置。它在 Pi 内部加载，直接监听 Pi 的
会话和工具事件，并通过 @open-pets/client 将一小组安全反应转
发到正在运行的 OpenPets 桌面应用。
| 组成部分 | 作用 | 意义 |
|---|---|---|
| Pi 扩展 | 订阅 Pi 的会话、代理和工具事件。 | 当 Pi 思考、编辑、执行命令、成功或出错时，宠物会自动作出反应。 |
| OpenPets IPC 客户端 | 通过本地 IPC 发送反应和简短的状态消息。 | 运行完全本地化。Pi 永远不需要远程服务来控制宠物。 |
| /openpets 命令 | 添加 status、test、react 和 say 子命令。 |
用户可以在 Pi 内验证连接并触发手动反应。 |
运行时控制是尽力而为的。如果 OpenPets 桌面应用关闭，Pi 会继续正常工作；扩展 会安静地跳过宠物更新，直到桌面应用再次可达。
安装
保持 OpenPets 桌面应用运行，然后使用 Pi 安装扩展包。可以选择对当前机器进行 全局安装，或对单个仓库进行项目本地安装。
pi install npm:@open-pets/pipi install -l npm:@open-pets/pi
全局安装会写入 Pi 的全局包设置。项目本地安装会写入
.pi/settings.json，适合需要让仓库显式携带 OpenPets 行为的场景。
修改包设置后，请重新加载或重启 Pi，以便新扩展生效。
Slash 命令
扩展只注册一个面向用户的命令命名空间，让你无需添加额外的 Pi 工具就能测试 和控制集成。这些命令都不会转发 prompt 或工具输出。
| 命令 | 用途 |
|---|---|
/openpets status | 检查 OpenPets 桌面应用是否可达，以及当前目标宠物。 |
/openpets test | 发送一个简短的测试反应和挥手消息。 |
/openpets react <reaction> | 手动设置安全反应，例如 thinking、testing、success 或 error。 |
/openpets say <message> | 显示一条经过校验的简短气泡消息。 |
/openpets help | 在 Pi 内打印可用的子命令列表。 |
say 的输入会经过与桌面应用相同的 OpenPets 校验器：简短、单
行、面向用户，绝不能包含代码、日志、路径、URL、prompt 或密钥。
自动事件反应
扩展会把 Pi 的生命周期事件映射为宠物反应，无需模型主动调用工具。大多数事件 只更新反应、不说话；只有出错时可能发送一条固定的安全消息。
| Pi 事件 | 条件 | 反应 | 语音 |
|---|---|---|---|
session_start | Pi 启动、恢复或重新加载。 | waving | 默认无。 |
agent_start | 代理循环开始。 | thinking | 无。 |
turn_start | 新的对话回合开始。 | working | 无。 |
tool_execution_start | 工具像 edit/write/patch/apply。 | editing | 无。 |
tool_execution_start | 工具或 shell 命令像测试。 | testing | 无。 |
tool_execution_start | 非测试的 shell/bash 命令。 | running | 无。 |
tool_execution_start | 其它工具。 | working | 无。 |
tool_execution_end | isError 为 true。 | error | 固定错误池消息，已限频。 |
agent_end | 代理循环结束，且最近未发生工具错误。 | success | 无。 |
session_shutdown | Pi 退出、重新加载、切换或 fork。 | idle | 无。 |
扩展只会读取有限的工具名和命令片段用于分类反应。它不会把原始命令、输出、 prompt 或文件路径写入语音气泡。与 OpenPets 相关的命令会被忽略，避免宠物自 触发循环。
安全与行为
Pi 扩展遵循与 Claude Code、OpenCode 和 MCP 服务器相同的安全模型。它的目标 只是提供环境状态显示。
| 保护 | 行为 |
|---|---|
| 不转发对话内容 | 自动事件绝不会发送 prompt、助手文本、工具输入、工具输出、文件内容、URL、路径或密钥。 |
| 校验手动语音 | /openpets say 会拒绝多行、过长、像代码、像 URL/路径或像密钥的文本。 |
| 尽力而为的运行时 | OpenPets 故障绝不会阻塞 Pi 的模型调用或工具执行。 |
| MVP 不注册 Pi 工具 | 扩展只注册一个用户 slash 命令，不暴露模型可调用的 Pi 工具。 |
| 包信任边界 | Pi 扩展以本地系统权限运行，请只安装你信任的包。 |
| 自触发防护 | 与 OpenPets 相关的工具调用会被事件映射器忽略。 |
宠物路由
默认情况下，自动反应和手动命令都指向桌面默认宠物。每扩展级别的显式宠物路由 会留到后续 Pi 子阶段，让当前的运行时契约保持简洁。
Pi
-> @open-pets/pi 扩展
-> @open-pets/client
-> OpenPets 桌面本地 IPC
-> 默认宠物故障排查
宠物没有反应
- 确认 OpenPets 桌面应用正在运行。
- 在 Pi 中运行
/openpets status。 - 安装或移除包之后重新加载或重启 Pi。
- 记住：大多数自动事件是纯反应，本来就是静默的。
移除扩展包
pi remove npm:@open-pets/pi对项目本地安装，请在原始安装的项目目录下运行 remove 命令，并遵循 Pi 的项 目设置行为。
状态
@open-pets/pi 包已发布到 npm，并遵循与其他 OpenPets 集成相同的
安全模型。当前版本基于 @earendil-works/pi-coding-agent 的 Pi
包 API 构建；请按你日常更新 Pi 的方式来固定或升级它。
