iagent-pi

Connect pi to a remote agent platform: use your local pi session as an online agent.

Packages

Package details

extension

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

首次使用选择「新建连接」,依次填写:

  1. 地区:国内 / 海外
  2. agent code:平台分配的连接编号
  3. agent key:平台分配的连接密钥
  4. 说明(可选):给这条连接起个便于辨认的名字

之后每次连接直接选「历史连接」即可,无需重复输入凭据。

日常操作:

操作 命令
选择/新建连接 /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 再重新连接。

为什么问我是否沿用上一次的会话? 同一连接再次上线时,如果上一次使用的会话与当前不同,插件会询问沿用上一次、使用当前,还是取消连接。选择「沿用」会切回上次的会话继续。

删除时提示在线? 在线或连接中的记录不允许删除,先断开再删。