Pi 微信会话枢纽

Pi WeChat Session Hub 是一个 Pi 扩展, 用微信管理本机多个 Pi 会话. Gateway 在独立后台进程中运行, 不依赖启动命令所在的 Pi TUI.

关闭所有 Pi TUI 后, 后台服务仍可通过微信收发消息; 在 Pi TUI 中用 /resume 恢复受管会话时, 会自动完成前后台 owner 交接, 微信消息随即进入可见终端.

目录

• 特性
• 系统要求
• 安装
• 首次使用
• 架构与会话行为
• 本机命令
• 微信端命令
• 在微信端找回上下文
• 配置
• 安全与运行边界
• 常见问题
• 开发与验证
• 许可证

特性

• 微信远程下发任务, 由本机 Pi 执行, 结果回到微信
• 会话常驻: Pi TUI 全部关闭后仍可在微信继续对话
• 前后台自动交接: TUI 打开即接管, TUI 关闭即交回后台, 始终只有一个 writer
• 多项目多会话: 每个项目可开多个会话, 稳定数字索引 + 会话名即可切换
• 恢复上下文: /last 只读回顾最近一轮对话, 不调模型不耗 token
• 严格安全边界: 授权根目录白名单, 未知命令 fail-closed, 审计不记录正文与凭证

系统要求

CI 在 ubuntu-latest 上跑 Pi 三版本兼容矩阵, 在 windows-latest 上额外覆盖 0.85.1 与 1.3.0 并验证真实平台的 wt.exe 探测逻辑.

平台限制的实际影响

非 Windows 平台, 或 Windows 上找不到 wt.exe 时:

• 扩展本身可以加载, /wx login、/wx start、/wx status 等本机命令可用
• 后台模式会话(/new 默认模式)完全可用
• 可见 UI 模式会被阻塞: 微信端 /new --mode ui、/resume 到 UI 会话、/wx autostart on 都会返回明确原因并拒绝执行, 不会静默降级或产生半启动状态
• /wx status 与微信端 /status 会单独显示 可见 UI 模式: 不可用 (原因), 便于提前判断

阻塞点位于 UI worker 启动前的平台与 wt.exe 能力校验, 因此不会留下孤儿窗口或双 writer. 失败结果不缓存, 安装 Windows Terminal 后无需重启 daemon 即可重试.

安装

方式一: 从官方渠道安装(推荐普通用户)

Pi 会从 npm 或 git 拉取包并自动安装依赖, 扩展注册到用户级配置.

# 从 npm 安装, 最省事, 版本可追
pi install npm:pi-wechat-session-hub

# 固定版本, 避免升级带来的行为差异
pi install npm:[email protected]

# 从 GitHub 安装, 跟随默认分支, 适合追最新提交
pi install git:github.com/yangfeng20/pi-wechat-session-hub

# 固定到 tag 或 commit
pi install git:github.com/yangfeng20/[email protected]

安装后:

pi list                                                    # 确认已在已安装包列表中
pi update --all                                            # 升级 Pi 与该包
pi remove npm:pi-wechat-session-hub                         # 卸载 npm 版本
pi remove git:github.com/yangfeng20/pi-wechat-session-hub   # 卸载 git 版本

只装到当前项目而非全局时, 在任意命令后加 -l, 包会写入 .pi/settings.json.

想临时试听不落盘, 用 -e 单次加载:

pi -e npm:pi-wechat-session-hub

方式二: 从源码本地开发安装

适合二次开发、调试与提交 PR.

git clone https://github.com/yangfeng20/pi-wechat-session-hub.git
cd pi-wechat-session-hub
npm install
npm run typecheck
npm test

三种加载方式, 按调试需求选择:

# A. 单次加载, 不改动任何设置, 最轻量
pi --extension ./extensions/wechat-session-hub.ts

# B. 把当前目录注册为本地包, 之后启动即生效(路径不会被复制)
pi install /absolute/path/to/pi-wechat-session-hub

# C. 项目级注册, 只对当前仓库生效
pi install -l .

方式 B/C 下修改源码后需要 /reload 或重启 Pi TUI; 若修改的是后台 daemon 代码, 还需 /wx restart 让新 daemon 生效.

首次使用

Node.js 需满足 package.json 中的最低版本. 首次使用顺序:

1. 在 Pi TUI 执行 /wx login 扫码授权.
2. 在 Pi TUI 执行 /wx start 启动后台服务. 如果 allowedProjectRoots 为空, Hub 会将当前 session 的 cwd 设为初始授权根, 并自动建立项目记录和默认项目.
3. 授权根内打开的 Pi session 会按当前文件夹名自动识别, 不需要逐个 /projects add. 如果后续要授权其他目录, 在本机 TUI 执行 /wx roots add-current, 或用 /wx roots add <绝对路径> 添加工作区根目录.

盘符根目录和用户主目录等过宽范围会要求本机确认. 授权根外的 Pi session 仍可在本机使用, 但不会接入 Hub; TUI 会提示如何添加授权根. Hub 不会扫描其他 session 文件.

配置和授权凭证保存在用户专属 Hub 目录, 仓库不包含账号凭证或授权 ID.

架构与会话行为

任意 Pi TUI
  /wx start|status|stop|restart
          │ 本机 HMAC IPC
          ▼
独立 Hub daemon
  ├─ 微信 iLink 长轮询、鉴权、route、持久队列
  └─ 每个会话唯一 writer
       ├─ Pi TUI 正在打开该会话: 消息进入前台并回显
       └─ 没有活跃 TUI owner: Pi RPC 后台处理

• /wx start 启动共享 daemon, 不绑定当前 Pi session. 关闭所有 Pi TUI 后, daemon 仍可通过微信收发消息.
• 每条微信 route 指向同一 Pi session. 在 Pi TUI 中 /resume 恢复 Hub 管理的会话时, 扩展通过 IPC 将 owner 从后台 RPC 安全切换到前台 TUI; 同一会话的微信消息和回复会在该 TUI 中显示. TUI 关闭后, route 返回后台 RPC.
• 新建微信会话默认在后台, 不自动打开 Windows Terminal tab. route、session JSONL 和稳定会话索引保留.
• 同一 session 同一时刻只允许一个 runtime writer. Pi TUI session 的 cwd 位于 allowedProjectRoots 内时会自动登记并纳入 Hub; 授权根外的会话仍可在本机使用, 但不接入微信管理.
• 当前 Pi TUI 已成功接入 Hub 时, footer 的扩展状态行会在 MCP 状态后显示 🟢 微信: 已接入; Gateway 重启或连接恢复期间显示 🟡 微信: 连接中, 确认未接入时显示 ⚪ 未接入.
• Gateway 进程在线不代表当前 TUI 已接入. /wx status 会单独展示当前终端的接入状态、实例 ID、上次接入时间、重连失败次数和断开原因, 便于区分是全局服务问题还是本终端连接问题. 会话切换导致 owner 释放后, bridge 会自动重建 registration 并恢复接入, 不需要重启 TUI.

本机命令

输入 /wx 并回车会打开交互式操作菜单; 输入 /wx 可补全子命令. /wechat-manager 是兼容别名. Pi 本机的 Hub 命令统一位于 /wx 下, 不会注册全局 /help、/projects 或 /status.

停止时, Gateway 先停止接收新微信消息, 再 drain 已入队 route 工作并等待正在处理的 Pi turn 收尾. /wx stop 在后台收尾期间提示"正在停止", 完成后再通知最终状态. /wx restart 会安全停止旧后台进程并启动新进程, 等待新服务就绪或报告失败; 它不会启动新旧并行 poller. 如果 daemon 非正常退出, durable queue 会保留未完成项; 这些项会在下次处理时被自动跳过并向微信回一条提示, 不会卡死后续消息. 需要重新执行时用 /retry <message-id> --confirm.

Windows 自动启动默认关闭; 开启后在当前用户登录 Windows 时使用已保存授权连接. 它不在 Windows 登录桌面前运行, 也不会在启动时弹出扫码窗口. 如果尚未完成微信授权或授权失效, 需要先在 Pi TUI 执行 /wx login. 非 Windows 平台执行 /wx autostart on 会被明确拒绝.

微信端命令

未知 slash command fail-closed, 不会任意透传 Pi 内置命令, 也不接受用户提供的 shell 或文件路径.

/new [--mode background|ui] [--project <alias>] [--name <名称>]
/sessions [--project <alias>] [--state active|saved|pending|all] [--page <n>]
/resume <会话索引|名称>
/last [会话索引|名称]
/stop [会话索引|名称]
/retry <message-id> --confirm
/status
/projects
/help

/new 默认在后台创建会话, 也可显式使用 /new --mode ui 在新 Windows Terminal tab 中创建可见 UI 会话. /sessions 默认列出 Hub 管理的全部活跃前台和后台会话, 每页 5 条, 以 markdown 表格展示索引、标题、模式与状态, 当前微信路由在标题后标记为 （当前）, 表头下方汇总涉及的项目. 标题优先显示 session name; 未命名时使用 Pi /resume 同样采用的首条用户文本, 最长 32 个 Unicode 字符, 超出以 ... 省略. /resume 3 把微信 route 切换到索引为 3 的会话. 如果切换目标的 agent 已处于 idle, 回复会附带最近一次回复预览; 超过 3800 个 Unicode 字符时只显示结尾并提示完整内容仍在会话中. 如果 agent 正在运行, 只确认切换, 不发送旧回复. 索引在会话排序变化后保持不变, 不因列表重排而复用.

/status 会额外输出 可见 UI 模式 一行; 平台不支持或缺少 wt.exe 时显示 不可用 及具体原因.

在微信端找回上下文

从 PC TUI 切换到手机微信时, 往往不知道会话进行到哪里了. 补一条消息又可能让 agent 白跑一轮, 因此 /last 提供纯只读的上下文回顾:

/last              查看当前微信路由会话的最近一轮对话
/last 3            查看索引为 3 的会话最近一轮对话
/last "调查错误"   按唯一会话名称查看

输出内容

会话 #3 修复登录态失效 · 项目展示名
最后活动：10-29 14:04 · 后台

最近一轮对话
你：
<最近一条 user 提问, 最多 1200 字符, 保留开头>
AI：
<最近一条 assistant 回复, 最多 3800 字符, 保留结尾>

发送 /resume 3 可切换到此会话。

• 带选择器时未复现有会内固定尾行改为提示 发送 /resume <索引> 可切换到此会话; 无选择器时提示 发送任意内容可继续对话
• 提问超过 1200 个 Unicode 字符时截断并附 [提问较长, 已截断。], 保留开头以便判断问了什么
• 回复超过 3800 个 Unicode 字符时截断, 标题标为 AI（末段节选） 并附 [回复较长, 以上为结尾 3800 字; 完整内容仍保留在会话记录中。], 保留结尾以便看到结论与下一步
• 整条回复连同 header 受 单条消息 2000 字上限约束 (见下方“单条消息长度限制”)
• 工具输出与 thinking 推理 不会 进入摘要, 只展示用户提问与最终回复
• 会话正在运行时, 在 header 与正文之间插入 ⚠️ 该会话正在运行, 以下为目前已落盘的内容。, 避免把中间步骤误读为最终结论
• assistant 尚未产生回复时显式输出 AI：尚未产生回复。

微信 markdown 渲染能力

2026-11-11 对真实微信客户端 (手机 + PC) 实测, 微信会按 markdown 渲染回复:

关键约束: 单个 \n 会被当作空格合并进同一段落。因此多行内容必须依赖空行分隔或块级元素 (列表项、表格行)。由于引用块在两端行为不一致, Hub 内部拼装的回复只用表格与列表。

单条消息长度限制

发往微信的回复必须满足两个约束, 均由 2026-11-11 对真实 iLink 服务端的实测得出:

实测数据 (中文正文, 单个 text_item):

3100 汉字  JSON  9723 字节  ->  OK
4550 汉字  JSON 14073 字节  ->  OK
5275 汉字  JSON 16248 字节  ->  OK
5456 汉字  JSON 16791 字节  ->  OK   <- 实测成功上限
5501 汉字  JSON 16926 字节  ->  FAIL ret=-2
5637 汉字  JSON 17334 字节  ->  FAIL ret=-2

注意限制的是 UTF-8 字节数而非字符数: 一个汉字占 3 字节, ASCII 占 1 字节, 所以同一字节预算下中文能装的字数显著少于英文。

历史上 sendText 曾按 2000 字符切分为多个 text_item, 与上述两条约束直接冲突。由于此前没有任何回复超过 2000 字, 该切分分支从未执行, 直到放大 /last 摘要长度才首次触发 api_error 投递失败。

当前防护:

• IlinkApiClient.sendText 不再拆分正文, 始终只发 1 个 text_item, 并在发送前用真实 body 字节数校验, 越界则报 message_too_long
• command-router.ts 中 MAX_SINGLE_MESSAGE_BYTES = 15000 作为发往微信前的最后一道保险, 按 UTF-8 字节精确截断并附 [回复过长, 已截断。]
• /last 与 /resume 的文本上限按最坏情况字节预算取值, 保证连同 header 后仍低于上限
• 回归测试同时断言 router 层字节预算与 client 层单 text_item 约束

无记录与未绑定会话

无副作用保证

/last 的读取策略是按需增窗, 不是固定只读末尾:

初始读末尾 256 KB
  ↓ 窗口内已找到完整一轮 (user + assistant)
  ↓ 否则倍数扩大窗口重试
上限 8 MB
  ↓ 仍不命中(单条消息超大)
流式全文件扫描兜底, 保证结果正确

无论走哪条路径, /last 都不改变 route 绑定、不写入 transcript、不调用模型、不产生 durable queue 项, 因此无副作用且无额外 token 消耗. 尾部首行可能是半行, 总是丢弃以避免解析到截断的 JSON. 看完后可直接发送新指令, 或用 /resume <索引> 切换过去继续工作.

Pi TUI 的内置 /resume 仍使用 Pi 自己的会话选择器. 如果目标是 Hub 会话, extension 会安全完成前后台 owner 交接. 未登记 session 不再因缺少 Hub 记录而阻止 Pi 原生恢复; 恢复后仅当 cwd 位于授权根内才自动接入 Hub.

配置

默认配置位置:

%USERPROFILE%\.pi\agent\wechat-session-manager.json

如果设置了 PI_CODING_AGENT_DIR, 配置保存在该目录下的 wechat-session-manager.json. 首次在 Pi TUI 执行 /wx start 时, Hub 会自动创建缺省配置并初始化当前 session 的授权根和项目记录. allowedProjectRoots 是安全边界, 一个根目录覆盖其子目录. 授权范围内的当前 Pi session 会按 cwd 文件夹名自动登记, 不需要逐个添加项目 alias, 也不会扫描其他目录或 Pi session 文件. 后续授权新工作区时, 可在本机 TUI 执行 /wx roots add-current 或 /wx roots add <绝对路径>. 示例:

{
  "schemaVersion": 1,
  "autoStartOnWindowsLogon": false,
  "allowedProjectRoots": [],
  "projects": {},
  "wechat": {
    "authorizedUserId": ""
  }
}

缺省字段会使用安全默认值. 历史配置中的 defaultMode 字段为兼容旧配置保留, 不决定微信端 /new 的运行模式; /new 默认创建后台会话, 也可通过 --mode ui 显式创建可见 UI 会话. wechat.credentialFile 固定指向 manager 数据目录中的 credentials.json; reader 拒绝目录外路径、符号链接、未知 schema 或授权用户不匹配. QR 凭证只在文件不存在时 create-only 写入, 不读取或覆盖其他应用数据.

Windows 首次创建空 manager 目录时会关闭继承 ACL, 仅授权当前用户、SYSTEM 和 Administrators; 已有非空目录不会自动修改权限, 登录和启动时会验证目录树. POSIX 要求 manager 目录和凭证文件无 group/other 权限, 且父目录不能被 group/other 写入. 权限无法验证时 fail-closed.

安全与运行边界

• Pi session JSONL 是对话历史事实源; Gateway 不直接编辑 transcript.
• Gateway 通过 manager.lock 保证单实例. control IPC 使用当前 lease token 完成 HMAC challenge, UI attach 使用 manager 目录 ACL 保护的稳定随机 key; 在线状态由活跃 IPC 校验, 不依赖过期 gateway.json.
• route 绑定、会话索引和 worker owner 持久保存; session 恢复前重新验证项目路径是否仍位于 allowedProjectRoots.
• 审计事件不记录消息正文、模型输出或凭证. 队列只在未完成期间保存原消息及 replyContext; 完成后压缩移除 payload, 并保留最近 1000 个 messageId 的 SHA-256 摘要用于去重.
• iLink sendtyping 仅提供 best-effort "正在输入"提示. Pi turn settled 后 Hub 发送一条完整最终回复, 不做 token 级微信流式回传.
• 关闭服务后不会自动登录或生成 QR. 自动启动仅由 autoStartOnWindowsLogon 和当前用户登录计划任务控制.
• 可见 UI 模式在执行前校验平台和 wt.exe, 校验不通过即阻塞, 不产生半启动进程.

常见问题

Q: 非 Windows 系统能用吗?
能装能用后台模式, 但不能创建可见 UI 会话. /new 用默认后台模式正常; /new --mode ui、/wx autostart on 会返回"仅支持 Windows"并拒绝执行.

Q: 提示"未找到 Windows Terminal (wt.exe)"怎么办?
从 Microsoft Store 安装 Windows Terminal, 或确认 %LOCALAPPDATA%\Microsoft\WindowsApps\wt.exe 存在且在 PATH 中. 安装后不必重启 daemon, 直接重试即可(失败结果不缓存). 也可一直使用后台模式, 不依赖 wt.exe.

Windows Terminal 常以 App Execution Alias 形式存在. 该目录权限受限, 对它执行 Test-Path / existsSync 会返回 false, 因此探测逻辑不依赖文件存在性, 而以 where.exe 解析结果与路径归属为准.

Q: 扫码后 /wx start 报需要重新授权?
凭证文件只在不存在时 create-only 写入, 不会覆盖. 若授权失效, 重新执行 /wx login 覆盖 Hub 自己的凭证文件即可.

Q: 微信消息一直没回复?
先 /wx status 看当前终端接入状态与未完成消息数. 单条消息处理或回复投递失败时, 该消息会被自动跳过, 微信会收到一条包含消息 ID 的提示, 后续消息不受影响; 需要重新执行时用 /retry <message-id> --confirm, 该操作可能产生副作用.

Q: 为什么 /sessions 看不到我在别的目录开的会话?
Hub 只管理 allowedProjectRoots 内的会话, 且不扫描本机其他 session 文件. 用 /wx roots add <绝对路径> 授权该目录后重新打开会话即可接入.

Q: 安装时 npm 拉依赖失败?
pi install git: 与 npm install 需要访问 npm registry. 可配置 npm 镜像, 或在 settings.json 中用 npmCommand 指定包装命令(如 mise、asdf).

Q: /last 和 /resume 区别?
/last 纯只读, 看完不动 route, 适合先确认上下文再决定下一步; /resume 会真实切换当前微信 route 并可能重启 Pi worker. 两者都支持索引和唯一名称选择器.

Q: 升级后行为异常?
执行 pi update --all 拉齐 Pi 与包版本, 然后 /wx restart. 版本兼容范围见 package.json 的 piCompatibility.

Q: 二次开发后我的修改需要公开吗?
本仓库使用 AGPL-3.0-or-later. 分发修改后的版本, 或将其作为网络服务提供给他人在线使用, 都需要以同等许可开放对应源码. 详见下方许可证章节.

开发与验证

npm install
npm run typecheck
npm test
npm run test:pi-runtime

当前自动化测试覆盖配置/索引迁移、Gateway IPC 和 detached daemon 启动失败保护、Windows 登录任务参数、前后台 session handoff、durable queue、iLink fake transport、typing indicator、凭证隔离、UI 模式平台阻塞和 worker 生命周期. npm test 使用 fake Pi/iLink, 不访问真实微信服务、不启动真实 Windows Terminal, 也不调用模型. 条件 ACL 集成测试默认跳过, 可单独启用:

PI_WECHAT_VERIFY_WINDOWS_ACL=1 node --experimental-transform-types --test --test-name-pattern="Windows manager ACL integration" tests/credential-store.test.ts

Pi RPC smoke 使用隔离配置检查扩展命令注册, 不访问真实账号凭证. 版本兼容范围和 CI 矩阵见 package.json 的 piCompatibility 与 .github/workflows/pi-compat.yml.

设计背景见 docs/implementation-spec.md 与 docs/decisions/.

许可证

本项目以 GNU Affero General Public License v3.0 or later 发布, SPDX 标识为 AGPL-3.0-or-later.

选择 AGPL 而非宽松许可, 是为了保证基于本项目的二次开发也持续开源:

• 修改并分发本项目或其衍生作品, 必须公开对应源码
• 将修改后的版本作为网络服务提供给他人使用, 同样必须提供源码
• 必须保留版权声明与许可证, 并用相同许可证发布衍生作品

若你的组织无法接受 AGPL 的传染性条款, 需要单独的商业授权, 请通过仓库 Issue 联系维护者.

Link

linuxdo