@ericzhaozzz/wechat-channel

一个 Pi Agent 扩展，把你的私人微信变成 AI 助手的遥控器——手机上和 pi 对话，微信里 实时收到回答、进度和文件，基于腾讯 iLink Bot API。

English | 中文

功能特性

• 微信里对话，得到连贯回答 — 消息转发给 pi 的 Agent，回复保留 Markdown；连续短消息 会合并成一次带编号（[1]、[2]…）的调用，长回答分块送达、不乱序。
• 看得见的处理过程 — "正在输入"贯穿整轮，进度短语（⏳ 正在执行：npm test）显示 Agent 在做什么；消息排队、掉线补处理、回答未能送达都会明确告知。
• 双向富媒体 — 图片、文件、语音、视频自动下载，收到的图片直接以图像内容进入模型 上下文；Agent 也能在回答完成前主动把截图、图表、生成的文件推给你。
• 不在电脑前也能控制 — #status、#queue、#clear、#cancel、#help 直接发微信 即可。
• Agent 问你，而不是问空终端 — 只能在终端弹窗里提问的工具（ask_user_question）会把 整轮卡在没人看的屏幕前。微信驱动的轮次里这类工具被拦下，同时告诉 Agent 改用带编号的 文字提问——问题送到手机上，回一个"2"就是完整答案。可通过 terminalOnlyTools 配置。
• 一人一会话，安全 — 只有被绑定的所有者可用，其他人被静默丢弃；频道同时只归一个 pi 会话所有。
• 经得起折腾 — 自动重连、自动重新登录，掉线消息补处理，只排队不丢弃，状态跨重启、 崩溃存活。

安装

# 通过 npm 安装（推荐）— 自带编译好的 dist/，无需其他步骤
pi install npm:@ericzhaozzz/wechat-channel
pi

# 或从源码构建后复制到 pi 扩展目录 — pi 加载的是编译产物
# （pi.extensions 指向 ./dist/index.js）
npm install && npm run build          # 在 wechat-channel 源码目录内执行
cd .. && cp -r wechat-channel ~/.pi/agent/extensions/
cd ~/.pi/agent/extensions/wechat-channel
npm install --omit=dev                # 只需要微信 SDK，运行时不再需要 tsx

# 重启 pi（或执行 /reload）
pi

快速开始

1. 启动 pi 并执行 /wechat login
2. 用手机微信扫描二维码，并在手机上确认登录
3. 用你自己的微信向机器人发送一条消息 — 第一个发送者被绑定为所有者
4. 你的消息会转发给 pi；回复会自动返回给你

使用方法

微信侧指令

不在电脑前时，所有者可以直接发这些指令（前缀由 channelCommandPrefix 配置，默认 #， 设为空字符串即禁用）：

| 指令 | 说明 | |------|------| | #cancel / #停 | 中止当前正在处理的一轮 | | #status / #状态 | 连接状态、是否正忙、排队数、上下文占用 | | #queue / #队列 | 排队中的消息数 | | #clear / #清空 | 清空排队（不影响正在处理的那一轮） | | #help / #帮助 | 显示以上说明 |

只有完全匹配的指令名才算指令——拼错的 #cancle 会照常发给 Agent。

终端命令

/wechat login、/wechat status、/wechat config、/wechat history、 /wechat log --tail、/wechat owner、/wechat send / send-media、/wechat start / stop、/wechat qr、/wechat cancel、/wechat clean、/wechat prefix 覆盖登录、状态、 归属、发送与媒体（子命令自动补全，输入 /wechat st 后按 Tab）。pi 底部状态栏常驻一行 频道状态（wechat: ✓ busy q2）；掉线、回答被丢弃等会以 pi 通知的形式出现。

配置

所有可调项都在 ~/.pi/wechat/config.json，加载时读取一次，改动需 /reload 后生效； 没有该文件时行为与默认一致：

{
  "ownerUserId": "[email protected]",
  "aiPrefix": "",
  "autoLogin": true,
  "preserveMarkdown": true,
  "mergeDebounceMs": 1500,
  "maxMergeMessages": 10,
  "rateLimitMax": 20,
  "rateLimitWindowMs": 60000,
  "agentTimeoutMs": 3600000,
  "maxDeliveryAttempts": 3,
  "deliveryParkTimeoutMs": 600000,
  "progressUpdates": true,
  "progressIntervalMs": 45000,
  "notifyFailures": true,
  "channelCommandPrefix": "#",
  "inlineImages": true,
  "maxInlineImageBytes": 5242880,
  "terminalOnlyTools": ["ask_user_question"],
  "steerWhileBusy": false
}

常用项：channelCommandPrefix（微信侧指令前缀）、ownerUserId（预先固定所有者）、 mergeDebounceMs / maxMergeMessages（短消息合并）、steerWhileBusy（处理中收到的新 消息插入当前轮次而不是排队）、inlineImages、progressUpdates、notifyFailures。 terminalOnlyTools 列出"只能在终端弹窗里提问、因此不允许在微信轮次里运行"的工具——如果 你确实守在终端前，把它清空即可，这类提问会以通知的形式转发到微信，告诉你去终端作答。 读不出来或键名写错会保留默认值，并由 /wechat config 列出。

安全与归属

任何能接触到机器人的人理论上都可以通过 pi 读取文件或执行命令，因此非所有者的消息会被 静默丢弃。所有者首次使用即绑定并持久化到 ~/.pi/wechat/owner.json，也可通过 ownerUserId 预先固定；用 /wechat owner 查看或修改。

一个 iLink 账号只支持一个长轮询者，因此频道同时只归一个 pi 会话所有。不持有频道的会话 完全不启动 worker，并在持有者关闭后约 30 秒内自动接管；/wechat start --takeover 立刻 抢占。被 SIGKILL 的 pi 会在租约过期（约 90 秒）后释放频道。

与 Hermes Agent 对比

| 特性 | Hermes Agent | Pi WeChat 扩展 | |---------|:-----------:|:------------------:| | 长轮询 | ✅ asyncio Gateway | ✅ 子进程 | | QR 登录 | ✅ 内置 | ✅ 内置 | | Markdown 保留 | ✅ | ✅ | | 发送者授权 | ✅ 按用户策略 | ✅ 单一所有者（单白名单） | | 语音转文字/引用回复上下文 | ✅ | ✅ 透传给 Agent | | 接收媒体（自动下载） | ✅ 完整 | ✅ 图片/文件/视频/语音（仅首个附件） | | 发送媒体 | ✅ 完整 | ✅ 通过 /wechat send-media（路径/URL/Base64） | | 多用户会话 | ✅ 按用户隔离 | ⚠️ 单会话桥接 | | 7×24 守护进程 | ✅ systemd/launchd | ⚠️ 需要 pi 在前台运行 | | 正在输入指示 | ✅ | ✅ | | 消息去重 | ✅ | ✅ | | Context Token 持久化 | ✅ | ✅ | | 智能分块 | ✅ | ✅ | | SSRF 防护 | ✅ | ❌ 未来计划 | | 投递账本 | ✅ | ✅ 有界重试 + 持久化 |