@dongh4o/wechat-ilink-bridge

v0.2.0

Published

9 days ago

Local WeChat iLink Bridge CLI for Agent-safe fetch, send, state, and media handoff workflows.

0High
0Medium
0Low

dongh4o

wechat ilink bot cli agent

WeChat-iLink Bridge

License: MIT

Public npm bin 公开稳定 CLI bin wxb 和 P2 MCP adapter bin wxb-mcp；wxb-spike 不作为公开 bin 发布。

WeChat-iLink Bridge（wxb）是一个面向 AI Agent 的微信 iLink 本地桥接 CLI。当前源码版本为 0.2.0：wxb send 支持文本、文件、图片和可选 typing 状态，wxb-mcp 暴露 fetch/send/status/listUsers/analyzeMedia 工具，上传密钥和 CDN URL 继续只在 bridge 内部流转。当前 npm 已发布版本仍为 M12 beta。

P0 能力范围

wxb login：扫码登录并把账号凭证写入本地状态目录。
wxb accounts：列出账号，stdout 不输出 token。
wxb status：查看账号、本地游标、会话数和消息历史数。
wxb fetch：短超时长轮询一批入站消息，先写入本地历史，再输出给 Agent。
wxb send：向已有入站上下文的用户发送文本，支持 --text 和 --stdin。
默认 fetch 仍只识别非文本消息类型和元数据；显式使用 --download-media 时下载并保存附件。

M7 能力范围

wxb poll：前台重复执行 fetch，用于轻量 keepalive 和本地处理。
wxb heartbeat：执行一次计划任务友好的 keepalive fetch，不启动 HTTP 服务。
wxb alias set/get/list/resolve/remove：为 opaque fromUserId 维护可读别名。
wxb queue list/clear：查看或清空延迟补发队列。
wxb cleanup：按消息保留天数、附件保留天数和最大历史条数清理本地状态。
invalid context 触发的发送失败会进入延迟补发队列；后续收到同一用户入站消息时，只补发队列中的第一条。

M8 能力范围

wxb fetch --download-media：下载图片、文件、语音和视频到本地 inbox。
支持 AES-128-ECB 解密，兼容 hex key、base64 原始 16 字节 key、base64 hex 字符串 key。
图片、语音、视频缺少协议 MIME 时，会根据下载后的文件头推断常见类型和扩展名。
CLI 输出附件绝对路径、文件名、MIME、字节数和下载状态。
CLI 不输出 AES key、CDN 下载 URL 或签名查询参数。
下载失败不会影响同一条消息中的文本项输出，也不会阻断游标和消息历史写入。
附件文件名会清理 Windows 保留字符、路径穿越和极长文件名。

M11 能力范围

wxb send --file <path>：AES-128-ECB 加密并上传本地文件，再发送给已有上下文的微信用户。
wxb send --image <path>：校验本地图片 MIME，上传并发送图片消息。
wxb send --typing：发送前获取 typing_ticket 并显示输入状态，发送后尽力停止输入状态。
本地文件不存在、目录路径、超过 WX_MAX_UPLOAD_BYTES、未知 MIME 或图片模式传入非图片文件时返回结构化错误。
stdout 不输出上传 URL、AES key、签名 query、bot token 或 context token。

M14 MCP Adapter

wxb-mcp：stdio MCP server，复用现有 core library 和本地状态目录。
MCP tools：fetchMessages、sendText、sendFile、listUsers、status、analyzeMedia。
Tool schema 不包含 context_token；Agent 只传账号、用户、文本或本地文件路径。
媒体内容继续通过 attachments[].path 或本地 filePath 交付，不暴露 CDN URL、上传参数或 AES key。
使用说明和客户端配置示例见 docs/m14-mcp-adapter.md。

M15 多模态辅助

analyzeMedia：检查本地媒体路径，返回 MIME、bytes、sha256、图片尺寸和 text-like 文件预览。
图片问答、语音转写、视频摘要默认返回 MULTIMODAL_HELPER_UNAVAILABLE 降级结果；真实模型能力由 Agent 使用 attachments[].path 自行调用，或由自定义 adapter host 注入 optional helper。
不需要模型 API key 时，bridge 的 fetch/send/媒体下载/媒体发送仍完整可用。
helper 失败不会修改 cursor、seen ID、context token 或消息历史。
使用说明见 docs/m15-multimodal-helper.md。

从源码安装

Windows PowerShell：

git clone https://github.com/DONGH4O/wechat-ilink-bridge.git
cd wechat-ilink-bridge
npm.cmd test
node .\src\cli\index.js help

可选安装为本机全局 wxb 命令：

npm.cmd install -g .
wxb help

npm Beta 安装

当前公开 beta 已可通过 @dongh4o/wechat-ilink-bridge@beta 安装，npm beta dist-tag 仍指向 0.1.0-beta.1：

npm.cmd install -g @dongh4o/wechat-ilink-bridge@beta
wxb help
wxb status --json

发布前本地 .tgz smoke：

npm.cmd pack
npm.cmd install -g .\dongh4o-wechat-ilink-bridge-0.2.0.tgz
wxb help
wxb status --json

稳定版准备状态

M13 稳定版候选准备已完成，GitHub Actions CI 已在 Windows 2025、Ubuntu、macOS 和 Node.js 18/20/22 上通过。
最新 M13 CI 验证记录见 docs/m13-validation-report.md。
0.1.0 stable 发布仍需人工确认后再执行 version bump、CHANGELOG.md 稳定版条目、Git tag、GitHub Release 和 npm stable publish。
安装、登录、发送、媒体和状态文件的常见问题见 docs/troubleshooting.md。

macOS/Linux：

git clone https://github.com/DONGH4O/wechat-ilink-bridge.git
cd wechat-ilink-bridge
npm test
node ./src/cli/index.js help

Windows PowerShell 快速开始

建议先指定测试状态目录，避免读写真实默认目录：

$env:WX_STATE_DIR="C:\tmp\wxb-test"

运行测试：

npm.cmd test
npm.cmd run pack:dry-run

如果 PowerShell 执行策略拦截 npm.ps1，使用 npm.cmd 即可，不需要修改系统策略。

直接从源码运行 CLI：

node .\src\cli\index.js help
node .\src\cli\index.js login --json
node .\src\cli\index.js accounts --json
node .\src\cli\index.js status --json
node .\src\cli\index.js fetch --timeout 1000 --json
node .\src\cli\index.js fetch --timeout 3000 --download-media --json
node .\src\cli\index.js send --user <fromUserId> --text "收到" --json
"来自 PowerShell 管道的回复" | node .\src\cli\index.js send --user <fromUserId> --stdin --json
node .\src\cli\index.js send --user <fromUserId> --file "C:\path\to\report.pdf" --json
node .\src\cli\index.js send --user <fromUserId> --image "C:\path\to\image.jpg" --typing --json
node .\src\cli\index.js poll --limit 3 --interval 1000 --json
node .\src\cli\index.js heartbeat --json
node .\src\cli\index.js alias set <fromUserId> "张三"
node .\src\cli\index.js cleanup --dry-run --json

常用全局配置也可以放在命令前：

node .\src\cli\index.js --state-dir "C:\tmp\wxb 测试 状态" status --json
node .\src\cli\index.js --base-url "https://ilinkai.weixin.qq.com" fetch --json

配置

配置优先级为 CLI 参数 > 环境变量 > .env > 默认值。

| 环境变量 | CLI 参数 | 说明 | |---|---|---| | WX_STATE_DIR | --state-dir | 状态目录；支持空格和中文路径 | | WX_BASE_URL | --base-url | iLink API 地址 | | WX_CHANNEL_VERSION | --channel-version | iLink channel version | | WX_FETCH_TIMEOUT_MS | --fetch-timeout-ms | fetch/send 请求超时 | | WX_POLL_INTERVAL_MS | --poll-interval-ms | poll 循环间隔 | | WX_MIN_CHUNK_CHARS | --min-chunk-chars | 文本分片最小长度 | | WX_MAX_CHUNK_CHARS | --max-chunk-chars | 文本分片最大长度 | | WX_MAX_DELIVERY_MESSAGES | --max-delivery-messages | 单次发送最大分片数 | | WX_DELAYED_QUEUE_MAX_ITEMS | --delayed-queue-max-items | 每账号延迟补发队列最大条数 | | WX_MESSAGE_RETENTION_DAYS | --message-retention-days | cleanup 消息历史保留天数 | | WX_ATTACHMENT_RETENTION_DAYS | --attachment-retention-days | cleanup inbox 附件保留天数 | | WX_MAX_HISTORY_MESSAGES | --max-history-messages | cleanup 每账号最多保留消息条数 | | WX_MAX_UPLOAD_BYTES | --max-upload-bytes | 单个发送文件最大字节数，默认 25 MiB |

默认状态目录：

| 平台 | 默认状态目录 | |---|---| | Windows | %LOCALAPPDATA%\wxb | | macOS | ~/Library/Application Support/wxb | | Linux | ${XDG_DATA_HOME:-~/.local/share}/wxb |

账号 token 和 context token 只保存在本地状态文件中，不会出现在默认 JSON stdout。公开 issue、PR、日志或截图前，请删除 .env*、本地状态目录、真实 m*-*.stdout.json 捕获、CDN 签名 URL、AES key 和完整 token。

发布前检查

准备公开 GitHub 或 npm 前，先运行：

npm.cmd test
npm.cmd run pack:dry-run

检查 npm pack --dry-run 的 file list，确保不包含 .env、你的真实测试状态目录、m*-*.stdout.json、test/fixtures/raw/live-*、完整 token、CDN 签名 URL 或 AES key。完整流程见 docs/release-process.md。

Agent 收发循环

运行 fetch --json 获取新消息。
把 data.messages 视为用户输入。
生成回复文本。
使用消息里的 fromUserId 调用 send --user <fromUserId>。

文本、文件和图片发送：

node .\src\cli\index.js send --user <fromUserId> --text "收到" --json
node .\src\cli\index.js send --user <fromUserId> --file "C:\path\to\report.pdf" --json
node .\src\cli\index.js send --user <fromUserId> --image "C:\path\to\image.jpg" --typing --json

--file 和 --image 只接受本地文件路径。bridge 会负责 AES 加密、上传 URL 获取、CDN 上传和 sendmessage，Agent 不需要也不应处理上传密钥、CDN 签名 URL 或 context_token。

如果 send 返回 NO_CONTEXT_TOKEN，说明还没有该用户的可用入站上下文，需要先让用户发来一条消息并运行 fetch。如果返回 SESSION_EXPIRED，需要重新执行 login。

M7 运维命令

前台 poller：

node .\src\cli\index.js poll --limit 10 --interval 1000 --timeout 15000 --json
node .\src\cli\index.js poll --limit 10 --interval 1000 --jsonl

计划任务 heartbeat：

node .\src\cli\index.js heartbeat --timeout 15000 --max-attempts 1 --json

无新消息时，如果客户端 timeout 先于 iLink 服务端长轮询返回，heartbeat 会输出 ok: true 和 status: "idle_timeout"，这表示本次 keepalive 没拿到新消息，但计划任务不应判为失败。

alias 管理：

node .\src\cli\index.js alias set <fromUserId> "张三"
node .\src\cli\index.js alias get <fromUserId>
node .\src\cli\index.js alias resolve "张三"
node .\src\cli\index.js send --alias "张三" --text "你好" --json

cleanup：

node .\src\cli\index.js cleanup --dry-run --message-retention-days 30 --attachment-retention-days 30 --max-history-messages 10000 --json
node .\src\cli\index.js cleanup --message-retention-days 30 --attachment-retention-days 30 --max-history-messages 10000 --json

延迟补发队列：

node .\src\cli\index.js queue list --json
node .\src\cli\index.js queue clear --user <fromUserId> --json

当 send 因 iLink 返回 INVALID_CONTEXT_TOKEN 失败且尚未投递任何分片时，消息会入队。下一次 fetch 收到同一用户携带新 context token 的入站消息时，只尝试补发该用户队列中的第一条，避免一次性刷屏。

M8 媒体下载

node .\src\cli\index.js fetch --download-media --timeout 15000 --json

带媒体的消息会包含：

{
  "attachments": [
    {
      "kind": "image",
      "fileId": "media id",
      "fileName": "safe local file name",
      "path": "C:\\tmp\\wxb-test\\inbox\\bot_id\\2026-05-17\\message-1-image.jpg",
      "mimeType": "image/jpeg",
      "bytes": 12345,
      "encrypted": true,
      "decrypted": true
    }
  ],
  "mediaDownload": {
    "requested": 1,
    "succeeded": 1,
    "failed": 0
  }
}

如果下载失败，消息仍会输出文本和元数据，并在对应 item 上标记 download.ok: false。如果 download.error.code 为 MEDIA_URL_MISSING 且 metadata 为空，请保留该 item 的 diagnostics.itemKeys 和 diagnostics.payloadKeys，用于补齐真实协议字段映射；这些诊断只包含字段名，不包含 token。

M8 验收清单

Windows PowerShell 下 npm.cmd test 全部通过。
Windows 下能完成 login、fetch、send 手工链路。
poll 连续运行不会破坏游标。
heartbeat 可被计划任务调用，不启动常驻服务。
cleanup --dry-run 与实际清理数量一致，且不删除账号凭证和 context token。
alias 不影响 userId 直发。
延迟补发每次入站最多补发一条。
WX_STATE_DIR 包含空格或中文时命令能正常读写状态。
fetch --download-media 能保存图片/文件/语音/视频，并返回绝对路径。
下载失败不会影响文本项处理。
附件路径被规范化到 inbox 内，不允许路径穿越。
损坏 JSON/JSONL 状态文件会返回结构化错误和恢复提示。
stdout/stderr/错误 JSON 不输出完整 botToken 或 contextToken。
默认非文本消息不会导致 fetch 失败，显式下载时返回附件或下载失败状态。