Pi Remote WeCom

English · 简体中文

用手机企微遥控电脑上的 Pi。一个 Pi 扩展，集成多会话管理、终端标签命名和任务结果回传。

• 随时接着聊：选择正在运行的会话，或查找历史会话继续任务。
• 远程开工：新建终端或后台会话，发送文字、图片和文件，切换模型、停止任务。
• 会话自动命名：根据首条输入生成名称，也可手动修改；终端标签与手机会话名同步。
• 本机直连：通过企微智能机器人长连接工作，无需额外服务器。

功能预览

命令帮助	会话管理	创建会话	切换模型	任务回传

安装

需要 macOS、Node.js ≥22.19、Pi Coding Agent（已验证 0.87.1），以及一个专用的企微智能机器人。

从 npm 安装：

pi install npm:pi-remote-wecom

或从 Git 安装：

pi install git:github.com/KKinsz/pi-remote-wecom

也可在仓库目录中直接源码安装：

npm ci --ignore-scripts
pi install "$PWD"

需要能创建 API 模式长连接机器人的企微账号；普通微信群机器人 webhook 不适用。不同企业的功能开放与管理策略可能不同，外部企业账号兼容性尚未单独确认。

1. 企微 工作台 → 智能机器人 → 创建机器人，选 API 模式 → 使用长连接，在详情页复制 BotID 和 Secret。需新建专用机器人（一个 BotID 只能有一条长连接），并分享给自己以便在手机上找到。
2. 在 Pi 中执行 /reload，再执行 /remote setup，填写 BotID 和 Secret，Pi 会显示 6 位绑定码。
3. 在企微单聊机器人发送绑定码，收到「绑定成功」卡片后，点 活跃会话 即可开始聊天。

自动命名：手机靠会话名挑选会话。执行 /tabmodel 选一个命名模型后，每个新会话会根据首条输入生成短标题，同步到终端标签和手机；不选则不命名、不耗 token，列表显示首条输入。

常用命令

手机企微：选中会话后，直接发消息即可。

缩写	命令	用途
ls	活跃会话	选择正在运行的会话
h	历史会话 [关键词]	查找并继续历史会话；默认隐藏 subagent 会话，加 全部 才显示（如 历史会话 全部 关键词）
n	创建会话 [目录] [消息]	打开新终端会话
nb	创建后台会话 [目录] [消息] / 新建后台会话 [目录] [消息]	在后台启动会话
model	切换模型 [关键词] / 模型 [关键词]	切换当前会话的模型；列表按 scope（enabledModels），关键词检索全部已认证模型
think	切换思考强度 [强度] / 思考强度 [强度]	切换当前会话的思考强度；列表只含当前模型支持的级别，可直接写 high 或 高
compact	压缩会话 [说明] / 压缩 [说明]	手动压缩当前会话上下文，可附说明作为压缩重点；运行中不可压缩，自动压缩仍由 Pi 负责
restart	重启 [force]	重启手机遥控后台服务（加载新代码）；有任务运行时默认拒绝并列出占用会话，重启 force 可强制中断
cd	切换目录 [别名] / 目录 [别名]	从目录别名中选择新建会话的默认目录（默认 ~）；已有会话不受影响
art	产物 / 查看产物	列出当前会话生成的 html/md/pdf/docx/xlsx/pptx/png/svg 文件：不超过 3 个时直接发送，更多时用卡片多选发送；有产物的会话在完成消息末尾提示（数量变化时）
status / stop / help	状态 / 停止 / 帮助	查看状态（目录与分支、模型与思考强度、上下文、花费、其他扩展经 setStatus 写入的状态项，可用 config statusKeys 限定白名单；按内置 footer 格式，无需安装 footer 扩展）、中断任务、查看全部命令

图片或文件可先发送，再在 5 分钟内补充说明；每次最多 10 件（本项目限制），每件不超过 100MiB（104,857,600 字节；官方标注为「100M」，仅指入站）。任务完成后自动回传结果，长结果以文件发送；回传方向受 SDK 分片上传限制约 50MiB。

中文别名需要与参数用空白字符分隔：模型 high 是命令，模型high 会当作普通消息发出；模型 这个怎么样 也会被当成命令并把后半句当参数。

电脑 Pi：

命令	用途
/remote	查看状态与管理服务
/remote setup	配置机器人
/remote bind	重新绑定企微账号
/remote restart / /remote stop	启动或重启 / 停止服务
/remote alias	设置常用目录别名
/tabmodel	选择自动命名模型；reset 关闭
/tabname 名称	手动修改会话名

支持的终端

支持 Ghostty、cmux、iTerm2、WezTerm、kitty、tmux。默认自动选择正在运行的终端；没有可用终端或屏幕锁定时，可创建后台会话。

终端设置

在 ~/.config/pi-remote-wecom/config.json 中设置 terminal，修改后执行 /remote restart。终端命令需在 PATH 中可用。

终端	terminal	前提
Ghostty	ghostty	≥1.3，允许 macOS 自动化控制
cmux	cmux	cmux ping 可用
iTerm2	iterm	允许 macOS 自动化控制
WezTerm	wezterm	wezterm cli list 可用
kitty	kitty	开启 allow_remote_control socket-only 和 listen_on，将实际 Unix socket 地址填入 kittySocket
tmux	tmux	≥3.0；可用 tmuxSession 指定会话

auto 自动选择，none 仅使用后台会话。更多字段见 配置示例。

验证范围

维护者已确认：主流程和主要指令通过真机验收。自动测试另覆盖 Pi 离线加载、会话路由、绑定校验、消息去重、附件与卡片协议。此记录不代表所有终端、外部企业账号或休眠/断网等异常场景均已逐项验收。

当前交互文案主要为中文，支持上表中的英文短命令。macOS 是主要支持平台；其他系统仅提供前台 daemon 运行方式，未声明完整支持。

升级与卸载

源码安装升级后，在包目录运行 npm ci --ignore-scripts，在 Pi 执行 /reload，待任务空闲后执行 /remote restart。Pi 管理的 Git/npm 安装可用 pi update --extensions 更新，再执行相同步骤；固定版本或标签需要显式修改安装源。

卸载前，先在包目录执行 node bin/remote.mjs uninstall 停止服务并删除自启动，再执行 pi remove <原安装源> 和 /reload。仅移除 Pi 包不会删除 launchd 服务。配置、日志和附件保留在 ~/.config/pi-remote-wecom/，按需自行清理。

使用说明

仅接受配置账号的单聊消息；电脑睡眠或关机时离线。后台会话与终端会话能力相同：加载你安装的扩展，可读写文件、执行命令。在电脑上用 pi -r 打开后台会话会把它接到终端里；后台还在运行时先等它结束，再自动刷新。

扩展确认转到手机：手机发起的任务里，扩展弹出的确认或选择（如 computer-use 的授权）会以卡片推到企微，点选即可继续；终端会话中电脑和手机谁先回答用谁的。无人处理时按 remoteConfirm 决定：ask-then-allow（默认，remoteConfirmTimeoutMs 默认 10 分钟后自动允许）、ask（超时拒绝）、allow（不询问直接允许）。需要输入文字的请求无法在手机上填写：后台会话直接取消；终端会话仍可在电脑上填写，到时未填则取消。扩展在后台会话启动时就请求确认的，会提示改用终端会话。

提问工具转到手机：兼容 Pi 示例的 question / questionnaire 工具，以及 AskUserQuestion 类工具（如 @juicesharp/rpiv-ask-user-question，多选题用多选卡片）。认不出的提问界面会提醒到电脑处理。当前绑定的终端会话里（电脑或手机发起的轮次均可），模型提问会以卡片推到企微，卡片说明行显示会话名，点选即可；未绑定会话的提问不推送，之后切换到该会话时补推；允许自由作答时，可点「自己写」或直接回复文字（当前会话有待答问题时，普通消息会作为答案）。多题逐题推送；电脑与手机谁先答用谁的；超时未答视为取消。后台会话不支持。

凭证保存在本机，Secret 输入不遮罩；日志、附件和结果需自行清理。详见 安全说明。

开发

npm ci --ignore-scripts
npm run check
npm run test:package

MIT License · 更新记录 · 贡献指南 · 来源说明