ylib-openclaw-weixin 2.1.7

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+[简体中文](CHANGELOG.zh_CN.md)
+
+This project follows the [Keep a Changelog](https://keepachangelog.com/) format.
+
+## [2.1.7] - 2026-04-07
+
+### Fixed
+
+- **Plugin registration re-entrance:** Lazy-import `monitorWeixinProvider` inside `startAccount` in `channel.ts` to avoid pulling in the monitor → process-message → command-auth chain at plugin registration time, which could re-enter the plugin/provider registry before the account starts.
+- **Initialization side effect:** Lazy-import `resolveSenderCommandAuthorizationWithRuntime` / `resolveDirectDmAuthorizationOutcome` in `process-message.ts` to prevent `ensureContextWindowCacheLoaded` from being triggered during module initialization, which caused `loadOpenClawPlugins` re-entrance.
+
+### Changed
+
+- **Tool-call outbound path:** `sendWeixinOutbound` now applies `StreamingMarkdownFilter` to the outbound text, consistent with the model-output path in `process-message`.
+
+## [2.1.4] - 2026-04-03
+
+### Changed
+
+- **QR login:** Remove client-side timeout for `get_bot_qrcode`; the request is no longer aborted on a fixed deadline (server / stack limits still apply).
+
+## [2.1.3] - 2026-04-02
+
+### Added
+
+- **`StreamingMarkdownFilter`** (`src/messaging/markdown-filter.ts`): outbound text no longer runs through whole-string `markdownToPlainText` stripping; a streaming character filter replaces it, so Markdown goes from **effectively unsupported** to **partially supported**.
+
+### Changed
+
+- **Outbound text path:** `process-message` uses `StreamingMarkdownFilter` (`feed` / `flush`) per deliver chunk instead of `markdownToPlainText`.
+
+### Removed
+
+- **`markdownToPlainText`** from `src/messaging/send.ts` (and its tests from `send.test.ts`); coverage moves to `markdown-filter.test.ts`.
+
+## [2.1.2] - 2026-04-02
+
+### Changed
+
+- **Config reload after login:** On each successful Weixin login, bump `channels.openclaw-weixin.channelConfigUpdatedAt` (ISO 8601) in `openclaw.json` so the gateway reloads config from disk, instead of writing an empty `accounts: {}` placeholder.
+- **QR login:** Increase client timeout for `get_bot_qrcode` from 5s to 10s.
+- **Docs:** Uninstall instructions now use `openclaw plugins uninstall @tencent-weixin/openclaw-weixin` (aligned with the plugins CLI).
+- **Logging:** `debug-check` log line no longer includes `stateDir` / `OPENCLAW_STATE_DIR`.
+
+### Removed
+
+- **`openclaw-weixin` CLI subcommands** (`src/weixin-cli.ts` and registration in `index.ts`). Use the host `openclaw plugins uninstall …` flow instead.
+
+### Fixed
+
+- Resolves the **dangerous code pattern** warning when installing the plugin on **OpenClaw 2026.3.31+** (host plugin install / static checks).

package/CHANGELOG.zh_CN.md

@@ -0,0 +1,53 @@
+# 变更日志
+
+[English](CHANGELOG.md)
+
+本项目遵循 [Keep a Changelog](https://keepachangelog.com/) 格式。
+
+## [2.1.7] - 2026-04-07
+
+### 修复
+
+- **插件注册重入：** `channel.ts` 中将 `monitorWeixinProvider` 改为在 `startAccount` 内部懒加载（`await import(...)`），避免插件注册阶段提前拉取 monitor → process-message → command-auth 依赖链，导致 plugin/provider registry 重入。
+- **初始化副作用：** `process-message.ts` 中将 `resolveSenderCommandAuthorizationWithRuntime` / `resolveDirectDmAuthorizationOutcome` 改为懒加载，避免模块初始化时触发宿主的 `ensureContextWindowCacheLoaded` 副作用，进而导致 `loadOpenClawPlugins` 重入。
+
+### 变更
+
+- **tool-call 外发路径：** `sendWeixinOutbound` 现在对发送文本应用 `StreamingMarkdownFilter`，与 `process-message` 中的 model-output 路径保持一致。
+
+## [2.1.4] - 2026-04-03
+
+### 变更
+
+- **扫码登录：** 移除 `get_bot_qrcode` 的客户端超时，请求不再因固定时限被 abort（仍受服务端与网络栈限制）。
+
+## [2.1.3] - 2026-04-02
+
+### 新增
+
+- **`StreamingMarkdownFilter`**（`src/messaging/markdown-filter.ts`）：外发文本由原先 `markdownToPlainText` 整段剥离 Markdown，改为流式逐字符过滤；**对 Markdown 从完全不支持变为部分支持**。
+
+### 变更
+
+- **外发文本：** `process-message` 在每次 `deliver` 时用 `StreamingMarkdownFilter`（`feed` / `flush`）处理回复，替代 `markdownToPlainText`。
+
+### 移除
+
+- 从 `src/messaging/send.ts` 删除 **`markdownToPlainText`**（相关用例从 `send.test.ts` 迁至 `markdown-filter.test.ts`）。
+
+## [2.1.2] - 2026-04-02
+
+### 变更
+
+- **登录后配置刷新：** 每次微信登录成功后，在 `openclaw.json` 中更新 `channels.openclaw-weixin.channelConfigUpdatedAt`（ISO 8601），让网关从磁盘重新加载配置；不再写入空的 `accounts: {}` 占位。
+- **扫码登录：** `get_bot_qrcode` 客户端超时由 5s 调整为 10s。
+- **文档：** 卸载说明改为使用 `openclaw plugins uninstall @tencent-weixin/openclaw-weixin`，与插件 CLI 一致。
+- **日志：** `debug-check` 日志不再输出 `stateDir` / `OPENCLAW_STATE_DIR`。
+
+### 移除
+
+- **`openclaw-weixin` 子命令**（删除 `src/weixin-cli.ts` 及 `index.ts` 中的注册）。请使用宿主自带的 `openclaw plugins uninstall …` 卸载流程。
+
+### 修复
+
+- 解决在 **OpenClaw 2026.3.31 及更新版本**上安装插件时出现的 **dangerous code pattern** 提示（宿主插件安装 / 静态检查）。

package/LICENSE

@@ -0,0 +1,27 @@
+Tencent is pleased to support the open source community by making openclaw-weixin available. 
+
+Copyright (C) 2026 Tencent.  All rights reserved. 
+
+openclaw-weixin is licensed under the MIT.
+
+
+Terms of the MIT:
+--------------------------------------------------------------------
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,312 @@
+# WeChat
+
+[简体中文](./README.zh_CN.md)
+
+OpenClaw's WeChat channel plugin, supporting login authorization via QR code scanning.
+
+## Compatibility
+
+| Plugin Version | OpenClaw Version       | npm dist-tag | Status      |
+|---------------|------------------------|--------------|-------------|
+| 2.0.x         | >=2026.3.22            | `latest`     | Active      |
+| 1.0.x         | >=2026.1.0 <2026.3.22  | `legacy`     | Maintenance |
+
+> The plugin checks the host version at startup and will refuse to load if the
+> running OpenClaw version is outside the supported range.
+
+## Prerequisites
+
+[OpenClaw](https://docs.openclaw.ai/install) must be installed (the `openclaw` CLI needs to be available).
+
+Check your version: `openclaw --version`
+
+## Quick Install
+
+```bash
+npx -y @tencent-weixin/openclaw-weixin-cli install
+```
+
+## Manual Installation
+
+If the quick install doesn't work, follow these steps manually:
+
+### 1. Install the plugin
+
+```bash
+openclaw plugins install "@tencent-weixin/openclaw-weixin"
+```
+
+### 2. Enable the plugin
+
+```bash
+openclaw config set plugins.entries.openclaw-weixin.enabled true
+```
+
+### 3. QR code login
+
+```bash
+openclaw channels login --channel openclaw-weixin
+```
+
+A QR code will appear in the terminal. Scan it with your phone and confirm the authorization. Once confirmed, the login credentials will be saved locally automatically — no further action is needed.
+
+### 4. Restart the gateway
+
+```bash
+openclaw gateway restart
+```
+
+## Adding More WeChat Accounts
+
+```bash
+openclaw channels login --channel openclaw-weixin
+```
+
+Each QR code login creates a new account entry, supporting multiple WeChat accounts online simultaneously.
+
+## Multi-Account Context Isolation
+
+By default, DMs can share one session bucket. For **multiple logged-in WeChat accounts**, isolate by account + channel + sender:
+
+```bash
+openclaw config set session.dmScope per-account-channel-peer
+```
+
+## Backend API Protocol
+
+This plugin communicates with the backend gateway via HTTP JSON API. Developers integrating with their own backend need to implement the following interfaces.
+
+All endpoints use `POST` with JSON request and response bodies. Common request headers:
+
+| Header | Description |
+|--------|-------------|
+| `Content-Type` | `application/json` |
+| `AuthorizationType` | Fixed value `ilink_bot_token` |
+| `Authorization` | `Bearer <token>` (obtained after login) |
+| `X-WECHAT-UIN` | Base64-encoded random uint32 |
+
+### Endpoint List
+
+| Endpoint | Path | Description |
+|----------|------|-------------|
+| getUpdates | `getupdates` | Long-poll for new messages |
+| sendMessage | `sendmessage` | Send a message (text/image/video/file) |
+| getUploadUrl | `getuploadurl` | Get CDN upload pre-signed URL |
+| getConfig | `getconfig` | Get account config (typing ticket, etc.) |
+| sendTyping | `sendtyping` | Send/cancel typing status indicator |
+
+### getUpdates
+
+Long-polling endpoint. The server responds when new messages arrive or on timeout.
+
+**Request body:**
+
+```json
+{
+  "get_updates_buf": ""
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `get_updates_buf` | `string` | Sync cursor from the previous response; empty string for the first request |
+
+**Response body:**
+
+```json
+{
+  "ret": 0,
+  "msgs": [...],
+  "get_updates_buf": "<new cursor>",
+  "longpolling_timeout_ms": 35000
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `ret` | `number` | Return code, `0` = success |
+| `errcode` | `number?` | Error code (e.g., `-14` = session timeout) |
+| `errmsg` | `string?` | Error description |
+| `msgs` | `WeixinMessage[]` | Message list (structure below) |
+| `get_updates_buf` | `string` | New sync cursor to pass in the next request |
+| `longpolling_timeout_ms` | `number?` | Server-suggested long-poll timeout for the next request (ms) |
+
+### sendMessage
+
+Send a message to a user.
+
+**Request body:**
+
+```json
+{
+  "msg": {
+    "to_user_id": "<target user ID>",
+    "context_token": "<conversation context token>",
+    "item_list": [
+      {
+        "type": 1,
+        "text_item": { "text": "Hello" }
+      }
+    ]
+  }
+}
+```
+
+### getUploadUrl
+
+Get CDN upload pre-signed parameters. Call this endpoint before uploading a file to obtain `upload_param` and `thumb_upload_param`.
+
+**Request body:**
+
+```json
+{
+  "filekey": "<file identifier>",
+  "media_type": 1,
+  "to_user_id": "<target user ID>",
+  "rawsize": 12345,
+  "rawfilemd5": "<plaintext MD5>",
+  "filesize": 12352,
+  "thumb_rawsize": 1024,
+  "thumb_rawfilemd5": "<thumbnail plaintext MD5>",
+  "thumb_filesize": 1040
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `media_type` | `number` | `1` = IMAGE, `2` = VIDEO, `3` = FILE |
+| `rawsize` | `number` | Original file plaintext size |
+| `rawfilemd5` | `string` | Original file plaintext MD5 |
+| `filesize` | `number` | Ciphertext size after AES-128-ECB encryption |
+| `thumb_rawsize` | `number?` | Thumbnail plaintext size (required for IMAGE/VIDEO) |
+| `thumb_rawfilemd5` | `string?` | Thumbnail plaintext MD5 (required for IMAGE/VIDEO) |
+| `thumb_filesize` | `number?` | Thumbnail ciphertext size (required for IMAGE/VIDEO) |
+
+**Response body:**
+
+```json
+{
+  "upload_param": "<original image upload encrypted parameters>",
+  "thumb_upload_param": "<thumbnail upload encrypted parameters>"
+}
+```
+
+### getConfig
+
+Get account configuration, including the typing ticket.
+
+**Request body:**
+
+```json
+{
+  "ilink_user_id": "<user ID>",
+  "context_token": "<optional, conversation context token>"
+}
+```
+
+**Response body:**
+
+```json
+{
+  "ret": 0,
+  "typing_ticket": "<base64-encoded typing ticket>"
+}
+```
+
+### sendTyping
+
+Send or cancel the typing status indicator.
+
+**Request body:**
+
+```json
+{
+  "ilink_user_id": "<user ID>",
+  "typing_ticket": "<obtained from getConfig>",
+  "status": 1
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `status` | `number` | `1` = typing, `2` = cancel typing |
+
+### Message Structure
+
+#### WeixinMessage
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `seq` | `number?` | Message sequence number |
+| `message_id` | `number?` | Unique message ID |
+| `from_user_id` | `string?` | Sender ID |
+| `to_user_id` | `string?` | Receiver ID |
+| `create_time_ms` | `number?` | Creation timestamp (ms) |
+| `session_id` | `string?` | Session ID |
+| `message_type` | `number?` | `1` = USER, `2` = BOT |
+| `message_state` | `number?` | `0` = NEW, `1` = GENERATING, `2` = FINISH |
+| `item_list` | `MessageItem[]?` | Message content list |
+| `context_token` | `string?` | Conversation context token, must be passed back when replying |
+
+#### MessageItem
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `number` | `1` TEXT, `2` IMAGE, `3` VOICE, `4` FILE, `5` VIDEO |
+| `text_item` | `{ text: string }?` | Text content |
+| `image_item` | `ImageItem?` | Image (with CDN reference and AES key) |
+| `voice_item` | `VoiceItem?` | Voice (SILK encoded) |
+| `file_item` | `FileItem?` | File attachment |
+| `video_item` | `VideoItem?` | Video |
+| `ref_msg` | `RefMessage?` | Referenced message |
+
+#### CDN Media Reference (CDNMedia)
+
+All media types (image/voice/file/video) are transferred via CDN using AES-128-ECB encryption:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `encrypt_query_param` | `string?` | Encrypted parameters for CDN download/upload |
+| `aes_key` | `string?` | Base64-encoded AES-128 key |
+
+### CDN Upload Flow
+
+1. Calculate the file's plaintext size, MD5, and ciphertext size after AES-128-ECB encryption
+2. If a thumbnail is needed (image/video), calculate the thumbnail's plaintext and ciphertext parameters as well
+3. Call `getUploadUrl` to get `upload_param` (and `thumb_upload_param`)
+4. Encrypt the file content with AES-128-ECB and PUT upload to the CDN URL
+5. Encrypt and upload the thumbnail in the same way
+6. Use the returned `encrypt_query_param` to construct a `CDNMedia` reference, include it in the `MessageItem`, and send
+
+> For complete type definitions, see [`src/api/types.ts`](src/api/types.ts). For API call implementations, see [`src/api/api.ts`](src/api/api.ts).
+
+## Uninstall
+
+```bash
+openclaw plugins uninstall @tencent-weixin/openclaw-weixin
+```
+
+## Troubleshooting
+
+### "requires OpenClaw >=2026.3.22" error
+
+Your OpenClaw version is too old for this plugin version. Check with:
+
+```bash
+openclaw --version
+```
+
+Install the legacy plugin line instead:
+
+```bash
+openclaw plugins install @tencent-weixin/openclaw-weixin@legacy
+```
+
+### Channel shows "OK" but doesn't connect
+
+Ensure `plugins.entries.openclaw-weixin.enabled` is `true` in `~/.openclaw/openclaw.json`:
+
+```bash
+openclaw config set plugins.entries.openclaw-weixin.enabled true
+openclaw gateway restart
+```