iagent-pi
Connect pi to a remote agent platform: use your local pi session as an online agent.
Package details
Install iagent-pi from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:iagent-pi- Package
iagent-pi- Version
0.1.3- Published
- Nov 20, 2026
- Downloads
- 340/mo · 340/wk
- Author
- detaide
- License
- unknown
- Types
- extension
- Size
- 305.1 KB
- Dependencies
- 2 dependencies · 1 peer
Pi manifest JSON
{
"extensions": [
"./extensions/iagent-connect.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
iagent-pi
把 pi 接入远端智能体平台,让这台机器上的 pi 成为一个可被远程使用的在线智能体。
这是什么
iagent-pi 是 pi 的扩展。连接建立后,平台侧的对话会进入你正在使用的 pi 会话,pi 的输出会实时回到平台;平台派发的任务由 pi 在本机执行,结果同样回流。对平台上的用户来说,它与其它智能体没有区别;对你来说,它就是平时那个 pi 会话,历史、上下文、工具都在。
- 连接建立在打开它的那次会话上,不会额外创建或切换会话。
- 一个 pi 进程同时只允许一条连接。
- 一条连接可以服务多个会话房间,房间由平台分配。
- 平台与本地共用同一段对话历史,双方看到的是同一件事的进展。
能力
- 双向消息:平台消息进入 pi 会话,pi 的回复与过程实时上行。
- 远程工具:平台下发的工具可直接在 pi 会话中被调用。
- 群聊协作:在群聊中 @ 指定成员、向指定房间发送消息、查询房间详情、成员与历史、查询自身所在房间与运行信息。
- 模型可控:跟随当前 pi 会话使用的模型,也可在连接上切换。
- 断线自愈:网络中断后自动重连;被新连接顶替时旧连接自动退出。断连期间的上行消息先在本机缓存,重连后按原顺序补发,不会静默丢失。关闭码
4001(鉴权失败)、4000(被接管)、3001(注册被拒)属于终止信号:立即停止重连、落日志(含 hub 关闭原因)并提示用户,不再进入退避循环。 - 就近接入:新建连接时选择国内或海外入口。
环境要求
- 已安装 pi。
- 有可用的 Node.js 运行环境(安装依赖时需要)。
安装
pi install npm:iagent-pi
安装后随 pi 启动自动加载,但不会自动连接,需要手动发起。
使用
在 pi 里执行:
/iagent-connect
首次使用选择「新建连接」,依次填写:
- 地区:国内 / 海外
- agent code:平台分配的连接编号
- agent key:平台分配的连接密钥
- 说明(可选):给这条连接起个便于辨认的名字
之后每次连接直接选「历史连接」即可,无需重复输入凭据。
日常操作:
| 操作 | 命令 |
|---|---|
| 选择/新建连接 | /iagent-connect |
| 重新连接 | /iagent-connect connect |
| 查看连接状态与当前模型 | /iagent-connect status |
| 切换模型 | /iagent-connect model |
| 断开 | /iagent-connect disconnect |
| 删除连接记录 | /iagent-connect delete |
选择器里每一层都可以用 Esc 返回。
排队与恢复
- 平台发来的消息按房间排队,pi 同一时刻只跑一轮,其余房间按公平轮转依次开工。
- 排队内容默认落盘在
~/.iagent/pi/.room-queue/queue.json(写入位置跟随插件数据目录),只记录批次与完成状态,完成后清空正文。 - 默认不自动恢复:进程退出前没跑完的消息不会被重放。需要时设置环境变量
PI_QUEUE_RECOVERY=1,下次连接会把未完成的排队消息重新入队(模型与工具跑完的那一轮不会重复)。 PI_QUEUE_PERSIST=0可关闭落盘,队列只存在于内存。- 平台侧的「停止」是全局操作:清空所有房间的排队消息并中止当前这一轮,与官方智能体行为一致。
凭据与隐私
- 连接密钥只在首次填写时输入,之后保存在本机,界面与历史列表都不会回显。
- 密钥不会出现在日志里。
- 删除连接记录只清除这条连接本身,不涉及任何对话或会话数据。
常见问题
加载后为什么没有自动连上? 设计如此:扩展只负责在需要时建立连接,连接动作始终由你发起。
提示已有连接?
一个 pi 进程只允许一条连接,先执行 /iagent-connect disconnect 再重新连接。
为什么问我是否沿用上一次的会话? 同一连接再次上线时,如果上一次使用的会话与当前不同,插件会询问沿用上一次、使用当前,还是取消连接。选择「沿用」会切回上次的会话继续。
删除时提示在线? 在线或连接中的记录不允许删除,先断开再删。