$ cat ~/map/pi-relay.md

pi-relay

斜杠命令式交接：agent 写出封存的交接记录，后继会话在你选定的模型上核验后继续。

extensions✓ 9月17日

用 pi install git:github.com/jpowersdev/pi-relay@v0.1.0 安装指定 tag 并重启 pi；升级时显式安装新 tag 即可，也可以用 pi -e git:github.com/jpowersdev/pi-relay 临时试用当前代码而不永久安装

## 速览

一个为 pi 增加斜杠命令 /relay 的扩展，用于持久化的会话交接：当前 agent 把工作状态写成结构化的封存交接，全新的父子关联会话在交互选择器选定的模型上启动，接手的 agent 必须先在只读首轮核验仓库状态，然后才继续实现。

## 要点

• $交接流程：/relay 先让当前 agent 检查工作区并写出结构化交接，扩展校验并封存，然后创建一个与源会话关联的全新会话，恢复选定的模型与当前思考档位，并要求接手的 agent 在只读首轮核验仓库状态——等你确认之后，实现工作才会继续。
• $模型选择：pi 会弹出交互式选择器，列出本地安装当前可用的模型；/relay 后面的命令文本只作为交接的补充焦点，永远不会被当作模型名解析。
• $存储：交接文件保存在项目仓库之外的 ~/.pi/agent/handoffs/ 下，目录权限为 0700，封存文件为 0600（在支持 Unix 权限的平台上）；单文件上限 128 KiB，保存到你手动删除为止。
• $隐私边界：交接内容可以包含仓库状态、文件路径、实现摘要、决策以及指向源会话的路径——应视为私密开发数据；完整源转录不会被复制进交接，而是留在本地作为恢复路径。
• $不新增网络请求：扩展自身不发出任何网络请求；用于撰写与核验交接的仍是 pi 的正常模型轮次，上下文照常经过你配置的模型提供方。
• $失败行为：源会话保持原样；交接创建或校验失败时，relay 直接停止而不会替换当前会话；已校验的交接在后续切换被取消时会被保留。
• $运行要求：pi 0.82.1 或更新、Node.js 22.19.0 或更新、交互式 TUI 模式，且需要可用的 write 或 bash 工具来撰写交接、可用的 read 或 bash 工具来核验；首发版本在 pi 0.82.1 上测试，由于 pi 扩展 API 会演进，建议锁定 release tag。

## 常见问题

## 参考链接

• README ↗

最后更新: 2026年9月17日