$ cat ~/map/pi-agent-substrate.md

pi-agent-substrate

为 pi 与 Oh My Pi 提供可挂起的远程工作区，驻留在自建的 Agent Substrate 集群上。

extensions✓ 9月22日

从检出目录安装：先 bun install --frozen-lockfile，再 pi install .（也可用 pi -e ./src/pi.ts --substrate-endpoint <url> 直接试用，端点指向你部署的 Environment API 或回环隧道）；需要 Pi 0.86.1 搭配 Node 22.19+、已部署的 Environment API 端点，以及操作者提供的含 ate-env-guest 的 actor 模板——本包不负责搭建基础设施

## 速览

pi-agent-substrate 把 pi 或 Oh My Pi 接入自建的 Agent Substrate 集群：文件与进程驻留在可挂起的远程工作区，对话仍留在本地——四个 substrate 工具、/substrate 生命周期命令、可选的空闲挂起与明确的隔离边界。

## 要点

• $远程工具面：substrate_read、substrate_write、substrate_shell、substrate_process 经 sh 远程 shell 覆盖远程文件、编辑、搜索与 Git 操作；传输与收集的输出以 1 MiB 为上限，前台 shell 调用以 120 秒为上限，更长的任务用 background: true 运行并经 substrate_process 查看。
• $环境生命周期命令：/substrate create、attach、status、suspend、detach、delete——删除要求输入与所附环境完全一致的 ID 并经交互确认，无头模式下不可用；空闲挂起是显式的可选项，取值 0 到 86400 秒，且活动调用、被跟踪任务或不确定的进程状态都会阻止挂起。
• $检查点/恢复有 README 背书的验证：在自建 kind 集群上端到端验证了环境挂起为 FULL 范围快照，恢复后文件系统与同进程内存均还原。
• $会话绑定规则：同一会话以相同 endpoint 与 atespace 恢复时，会还原已保存的附着关系与进程跟踪；分支或新会话不会静默继承附着关系——需要共享时请显式 attach；关闭 harness 既不删除也不挂起远程环境。
• $歧义处理：进程启动响应丢失时视为状态不确定且不重放命令；前台取消、超时、输出溢出或输出失败时，扩展会尝试终止已知的远程进程。
• $安全姿态：非回环端点使用 HTTPS 并保留标准 TLS 证书校验，SUBSTRATE_TOKEN 经秘密管理器下发而不进 URL 或命令参数，会话绑定中不保存任何 token。

## 常见问题

## 参考链接

• README ↗

最后更新: 2026年9月22日