@workclaw/openclaw-workchat 1.0.0 → 1.0.4

package/README.md

@@ -1,210 +1,210 @@
-# openclaw-workchat
-
-WorkChat 开放平台 OpenClaw 通道插件仓库。插件源码平铺在仓库根目录
-（参照官方 `@tencent-weixin/openclaw-weixin` 的包布局），业务协议来自
-zhixiaotu_channel。
-
-- 插件包：`@workclaw/openclaw-workchat`（根目录 index.ts + src/）
-- 部署目标：`work-claw-desktop`（openclaw-extensions/workchat → 运行时 third-party-extensions）
-- 使用方式：`npm run sync` 一键同步并打包
-
-## 快速开始
-
-```bash
-npm install
-npm run sync      # 同步插件到 ../work-claw-desktop 并预编译
-```
-
-## 仓库结构
-
-```
-openclaw-workchat/
-├── index.ts                  # 插件入口（buildChannelConfigSchema 注册）
-├── openclaw.plugin.json      # OpenClaw 插件清单
-├── package.json              # @workclaw/openclaw-workchat
-├── tsconfig.json
-├── vendor.d.ts               # 无类型依赖的声明（qrcode-terminal）
-├── src/
-│   ├── channel.ts            # ChannelPlugin 契约（gateway/loginWithQr/auth.login/outbound/status）
-│   ├── compat.ts             # 宿主版本 fail-fast 守卫
-│   ├── api/
-│   │   ├── api.ts            # 开放平台 HTTP 客户端（token 缓存/开连接/收发）
-│   │   └── types.ts          # 协议类型与常量
-│   ├── auth/
-│   │   ├── accounts.ts       # 账号索引+每账号数据文件+resolveAccount
-│   │   ├── login-qr.ts       # bind-hardware 二维码本地生成 + INIT_AGENT 等待
-│   │   ├── login-qr-terminal.ts  # CLI 终端二维码显示
-│   │   └── pairing.ts        # 框架 allowFrom 配对存储（文件锁）
-│   ├── config/config-schema.ts  # zod 通道配置 schema
-│   ├── messaging/
-│   │   ├── inbound.ts        # 帧解析 + MsgContext 转换
-│   │   ├── process-message.ts # 入站处理链（鉴权→路由→记录→派发）
-│   │   ├── send.ts           # reply/push 出站发送
-│   │   ├── slash-commands.ts # /echo、/toggle-debug 斜杠指令
-│   │   ├── debug-mode.ts     # 每 bot debug 开关（持久化）
-│   │   ├── markdown-filter.ts # 流式 markdown 过滤器
-│   │   ├── error-notice.ts   # 回复失败的错误提示
-│   │   └── outbound-hooks.ts # message_sending/sent 框架 hook
-│   ├── monitor/monitor.ts    # WebSocket 监听循环（退避重连/ping-pong）
-│   ├── storage/state-dir.ts  # OPENCLAW_STATE_DIR 解析
-│   └── util/                 # logger（JSON 行主日志）/redact/random
-├── openclaw-extensions/      # 官方插件源码参考（只读，不参与构建）
-├── scripts/
-│   ├── bundle.mjs            # esbuild 打包 index.js（免网关 jiti 转译）
-│   └── sync-to-desktop.mjs   # 同步到 work-claw-desktop 并预编译
-└── package-lock.json
-```
-
-## 使用流程（对应用户三步）
-
-1. **安装插件**：`npm run sync` 把插件源码同步到
-   `../work-claw-desktop/openclaw-extensions/workchat`，打包出 `index.js`，
-   并同步进运行时 `third-party-extensions/workchat`；桌面端在 openclaw.json
-   启用 `openclaw-workchat`。
-2. **获取二维码**：桌面端设置页点「扫码绑定 WorkChat」→ 网关 RPC
-   `web.login.start`（channel=openclaw-workchat）→ 插件**本地生成**
-   bind-hardware 二维码。CLI 用户也可 `openclaw channels login
-   --channel openclaw-workchat`（auth.login 适配器，终端渲染二维码）。
-3. **扫码绑定**：插件本地组装 bind-hardware JSON（cmd/type/name 固定，
-   其余为设备实时信息 + 当前用户 app_key），用户用 WorkChat App 扫码；
-   平台通过 WebSocket 推送 `INIT_AGENT` 事件，插件绑定智能体+创建账户
-   （**不写 apiKey**——凭据已由网关环境变量注入），`web.login.wait` 由该
-   事件唤醒返回。之后即可在 WorkChat 与本地 OpenClaw 对话。
-
-## bind-hardware 二维码（本地生成，无平台接口）
-
-```json
-{
-  "cmd": "bind-hardware",
-  "data": {
-    "type": "99",                           // 固定
-    "name": "WorkClaw 桌面端",               // 固定
-    "serial_number": "WC-XXXXXXXXXXXXXXXX", // 主机名+MAC 哈希，稳定设备序列号
-    "product_model": "WorkClaw Desktop",
-    "main_processor": "<os.cpus() 型号>",
-    "memory": "<os.totalmem() 取整>GB",
-    "emmc": "<fs.statfs 系统磁盘总容量>",
-    "system": "<os.type() release() arch()>",
-    "app_key": "<当前用户 WORKCHAT_API_KEY>"
-  }
-}
-```
-
-绑定确认不走 HTTP 轮询：用户扫码后平台往 WebSocket 推 `INIT_AGENT` 事件
-（data 带 `id`/`agentId` 与 `futureId`/`userId`），插件 `completeWorkChatBinding`
-唤醒挂起的 `web.login.wait`。
-
-## 与 openclaw-weixin 的对齐清单
-
-- **入站处理链**：斜杠命令拦截 → `resolveSenderCommandAuthorizationWithRuntime`
-  配对鉴权（allowFrom 文件 + 文件锁）→ `resolveAgentRoute` →
-  `recordInboundSession` → `createReplyDispatcherWithTyping` →
-  `dispatchReplyFromConfig`
-- **出站**：StreamingMarkdownFilter 过滤 → `message_sending` hook（可取消/改写）
-  → 发送 → `message_sent` hook；失败走 error-notice
-- **channel 契约**：`messaging.targetResolver`、`agentPrompt.messageToolHints`
-  （cron 投递必须带 to+accountId）、`status` 三件套、`auth.login` CLI 入口、
-  `gatewayMethods` QR RPC
-- **运维**：`/toggle-debug` 开启全链路耗时统计；JSON 行日志写入主 openclaw
-  日志文件（与其他渠道同格式）；`compat.ts` 宿主版本守卫
-- **协议差异**（合理保留）：WebSocket 推送代替长轮询（无 sync-buf 游标）；
-  二维码本地生成（非平台下发）；绑定确认靠 WS 事件（非 HTTP 轮询）；
-  凭据为环境变量注入的 appKey/appSecret（非扫码 token）；无 typing API
-
-## 凭据链路（与微信插件的关键差异）
-
-凭据不是扫码登录获得：桌面端登录后从
-`/open-apis/desktop/oauth2/workchat/credentials` 换取 `workchatApiKey`/
-`workchatAppSecret`，以 `WORKCHAT_API_KEY` / `WORKCHAT_APP_SECRET` /
-`USER_ID` 环境变量注入网关进程；openclaw.json 使用 `${WORKCHAT_API_KEY}` /
-`${WORKCHAT_APP_SECRET}` 占位符，密钥不落盘。
-
-## 连接协议
-
-```
-POST {base}/authen/v1/access_token/internal   app_key/app_secret -> accessToken
-POST {base}/open-apis/v1/connections/open      subscriptions     -> endpoint + ticket
-WS   {endpoint}?ticket=...                     AGENT_MESSAGE/EVENT/SYSTEM
-```
-
-- 开连接时的订阅声明：`[{type:"CALLBACK",topic:"AGENT_MESSAGE"},{type:"EVENT",topic:"*"},{type:"SYSTEM",topic:"*"}]`。
-- `SYSTEM` + topic `ping` → 回 `pong`；topic `disconnect` → 关闭并重连。
-- `EVENT` + `AGENT_CREATED|AGENT_UPDATED|AGENT_DELETED|INIT_AGENT` → 账号生命周期。
-- `CALLBACK` + topic `AGENT_MESSAGE` → 用户消息。
-
-## WebSocket 帧协议详解（信封结构）
-
-每帧是一个 JSON 信封：`{ type, metadata: { time, event|topic, contentType }, data }`，
-`data` 可能是对象，也可能是 JSON 字符串（解析前需二次 `JSON.parse`），甚至是裸标量
-（如 INIT_AGENT 的 data 为字符串化的 agent id，需归一化为 `{id}`）。
-
-| type | metadata 判定 | data 内容 | 插件处理 |
-|------|--------------|-----------|----------|
-| `SYSTEM` | topic=`ping` | 任意（回显） | 回 pong：`{code:200,message:"pong",metadata:{contentType:"application/json"},data:JSON.stringify(原data)}`；成功回包即刷新 `lastEventAt`（连通性判据） |
-| `SYSTEM` | topic=`disconnect` | — | 主动关闭 WS，交给重连循环 |
-| `EVENT` | event=`INIT_AGENT` | `{id, futureId}`（或裸 agentId） | 扫码绑定完成事件：持久化账号、绑定 agentId/userId、唤醒 web.login.wait；重绑时先清理旧 agent 账号 |
-| `EVENT` | event=`AGENT_CREATED` | `{id, futureId, ...}` | 平台创建智能体：保存账号并回执状态（notifyAgentCreatedStatus） |
-| `EVENT` | event=`AGENT_UPDATED` | agent 对象 | 无本地动作（记录日志） |
-| `EVENT` | event=`AGENT_DELETED` | `{id, ...}` | 删除对应本地账号绑定（含状态文件/索引/allowFrom/openclaw.json accounts 条目）并触发渠道重载 |
-| `CALLBACK` | topic=`AGENT_MESSAGE` | `{userId, conversationId, msgId, agentId, message: {content}}` | 用户消息：斜杠命令 → 配对鉴权 → 路由 → 记录会话 → 派发回复 |
-| — | 其他/未知 | — | 忽略 |
-
-zhixiaotu 参考实现（`zhixiaotu_channel/packages/plugin`）中还存在但 workchat 插件
-暂未接的 EVENT 类型：`TOOLS_LIST`、`SKILLS_LIST`、`SKILL_DO_REMIND`（skills 事件）、
-`CRON_REMIND`（定时任务事件）——协议格式见
-`zhixiaotu_channel/packages/plugin/src/gateway/message-context.ts`。
-
-### 连通性判据（诊断口径）
-
-- **连接已建立**：WS `onopen` 成功后插件才上报 `running: true`（`monitor.ts`）。
-- **连接保活**：服务端周期性下发 `SYSTEM/ping`（节奏约 1-2 分钟），插件回 pong
-  成功后刷新 `lastEventAt`。因此「WS 活着」= `running === true && lastError 为空
-  && lastEventAt 距今 < 10 分钟`。
-- 桌面端连通性测试（`work-claw-desktop/src/main/im/imGatewayManager.ts`
-  `testWorkchatOpenClawConnectivity`）通过网关 `channels.status` RPC 读取上述快照，
-  按此口径给出 pass/fail。
-
-## 开发
-
-```bash
-npm install            # 安装 esbuild/typescript
-npm run bundle         # 打包 index.js
-npm run sync           # 同步到 ../work-claw-desktop（可传路径参数）
-npm run typecheck
-```
-
-## 配置项（channels.openclaw-workchat）
-
-| 配置项 | 类型 | 必填 | 说明 |
-|--------|------|------|------|
-| enabled | boolean | 否 | 是否启用通道 |
-| baseUrl | string | 否 | 默认 `https://workbrain.cn/backend-api` |
-| websocketUrl | string | 否 | 默认从 baseUrl 推导 |
-| appKey | string | 是 | `${WORKCHAT_API_KEY}` 占位符 |
-| appSecret | string | 是 | `${WORKCHAT_APP_SECRET}` 占位符 |
-| accounts | object | 否 | 多账号配置，每项可覆盖 agentId/userId |
-
-## 断线重连
-
-- 指数退避（5s 起步，上限 5 分钟），鉴权失败（errCode 2001 /
-  unauthorized / 缺凭据）停止重连。
-- 限频（“访问过于频繁”）时以 1s 最小退避重试。
-
-## 测试
-
-```bash
-npm test    # vitest：accounts（索引/清理/prune 边界）+ inbound（帧解析/data 归一化）
-```
-
-## TODO（已知留白）
-
-- **事件接入**：`TOOLS_LIST` / `SKILLS_LIST` / `SKILL_DO_REMIND` / `CRON_REMIND`
-  暂不处理（归入 ignored，debug 日志记录 `ignoredKind`）。协议参考
-  `zhixiaotu_channel/packages/plugin/src/gateway/message-context.ts`，接入时按
-  zhixiaotu 的 dispatcher 补 handler。
-- **账号文件写入加锁**：`handleAgentLifecycleEvent` 里保存/清理账号与
-  `triggerWorkChatChannelReload` 触发的重载存在并发读写 accounts.json 的窗口；
-  可复用 `pairing.ts` 的 `withFileLock`。
-- **serial 持久化**：`buildDeviceSerial` 每次扫码按主机名+MAC 现算，网卡变化
-  （VPN/虚拟网卡）会得到不同 serial，平台可能视为新设备导致重复绑定；
-  建议首次生成后持久化到 state 目录。
+# openclaw-workchat
+
+WorkChat 开放平台 OpenClaw 通道插件仓库。插件源码平铺在仓库根目录
+（参照官方 `@tencent-weixin/openclaw-weixin` 的包布局），业务协议来自
+zhixiaotu_channel。
+
+- 插件包：`@workclaw/openclaw-workchat`（根目录 index.ts + src/）
+- 部署目标：`work-claw-desktop`（openclaw-extensions/workchat → 运行时 third-party-extensions）
+- 使用方式：`npm run sync` 一键同步并打包
+
+## 快速开始
+
+```bash
+npm install
+npm run sync      # 同步插件到 ../work-claw-desktop 并预编译
+```
+
+## 仓库结构
+
+```
+openclaw-workchat/
+├── index.ts                  # 插件入口（buildChannelConfigSchema 注册）
+├── openclaw.plugin.json      # OpenClaw 插件清单
+├── package.json              # @workclaw/openclaw-workchat
+├── tsconfig.json
+├── vendor.d.ts               # 无类型依赖的声明（qrcode-terminal）
+├── src/
+│   ├── channel.ts            # ChannelPlugin 契约（gateway/loginWithQr/auth.login/outbound/status）
+│   ├── compat.ts             # 宿主版本 fail-fast 守卫
+│   ├── api/
+│   │   ├── api.ts            # 开放平台 HTTP 客户端（token 缓存/开连接/收发）
+│   │   └── types.ts          # 协议类型与常量
+│   ├── auth/
+│   │   ├── accounts.ts       # 账号索引+每账号数据文件+resolveAccount
+│   │   ├── login-qr.ts       # bind-hardware 二维码本地生成 + INIT_AGENT 等待
+│   │   ├── login-qr-terminal.ts  # CLI 终端二维码显示
+│   │   └── pairing.ts        # 框架 allowFrom 配对存储（文件锁）
+│   ├── config/config-schema.ts  # zod 通道配置 schema
+│   ├── messaging/
+│   │   ├── inbound.ts        # 帧解析 + MsgContext 转换
+│   │   ├── process-message.ts # 入站处理链（鉴权→路由→记录→派发）
+│   │   ├── send.ts           # reply/push 出站发送
+│   │   ├── slash-commands.ts # /echo、/toggle-debug 斜杠指令
+│   │   ├── debug-mode.ts     # 每 bot debug 开关（持久化）
+│   │   ├── markdown-filter.ts # 流式 markdown 过滤器
+│   │   ├── error-notice.ts   # 回复失败的错误提示
+│   │   └── outbound-hooks.ts # message_sending/sent 框架 hook
+│   ├── monitor/monitor.ts    # WebSocket 监听循环（退避重连/ping-pong）
+│   ├── storage/state-dir.ts  # OPENCLAW_STATE_DIR 解析
+│   └── util/                 # logger（JSON 行主日志）/redact/random
+├── openclaw-extensions/      # 官方插件源码参考（只读，不参与构建）
+├── scripts/
+│   ├── bundle.mjs            # esbuild 打包 index.js（免网关 jiti 转译）
+│   └── sync-to-desktop.mjs   # 同步到 work-claw-desktop 并预编译
+└── package-lock.json
+```
+
+## 使用流程（对应用户三步）
+
+1. **安装插件**：`npm run sync` 把插件源码同步到
+   `../work-claw-desktop/openclaw-extensions/workchat`，打包出 `index.js`，
+   并同步进运行时 `third-party-extensions/workchat`；桌面端在 openclaw.json
+   启用 `openclaw-workchat`。
+2. **获取二维码**：桌面端设置页点「扫码绑定 WorkChat」→ 网关 RPC
+   `web.login.start`（channel=openclaw-workchat）→ 插件**本地生成**
+   bind-hardware 二维码。CLI 用户也可 `openclaw channels login
+   --channel openclaw-workchat`（auth.login 适配器，终端渲染二维码）。
+3. **扫码绑定**：插件本地组装 bind-hardware JSON（cmd/type/name 固定，
+   其余为设备实时信息 + 当前用户 app_key），用户用 WorkChat App 扫码；
+   平台通过 WebSocket 推送 `INIT_AGENT` 事件，插件绑定智能体+创建账户
+   （**不写 apiKey**——凭据已由网关环境变量注入），`web.login.wait` 由该
+   事件唤醒返回。之后即可在 WorkChat 与本地 OpenClaw 对话。
+
+## bind-hardware 二维码（本地生成，无平台接口）
+
+```json
+{
+  "cmd": "bind-hardware",
+  "data": {
+    "type": "99",                           // 固定
+    "name": "WorkClaw 桌面端",               // 固定
+    "serial_number": "WC-XXXXXXXXXXXXXXXX", // 主机名+MAC 哈希，稳定设备序列号
+    "product_model": "WorkClaw Desktop",
+    "main_processor": "<os.cpus() 型号>",
+    "memory": "<os.totalmem() 取整>GB",
+    "emmc": "<fs.statfs 系统磁盘总容量>",
+    "system": "<os.type() release() arch()>",
+    "app_key": "<当前用户 WORKCHAT_API_KEY>"
+  }
+}
+```
+
+绑定确认不走 HTTP 轮询：用户扫码后平台往 WebSocket 推 `INIT_AGENT` 事件
+（data 带 `id`/`agentId` 与 `futureId`/`userId`），插件 `completeWorkChatBinding`
+唤醒挂起的 `web.login.wait`。
+
+## 与 openclaw-weixin 的对齐清单
+
+- **入站处理链**：斜杠命令拦截 → `resolveSenderCommandAuthorizationWithRuntime`
+  配对鉴权（allowFrom 文件 + 文件锁）→ `resolveAgentRoute` →
+  `recordInboundSession` → `createReplyDispatcherWithTyping` →
+  `dispatchReplyFromConfig`
+- **出站**：StreamingMarkdownFilter 过滤 → `message_sending` hook（可取消/改写）
+  → 发送 → `message_sent` hook；失败走 error-notice
+- **channel 契约**：`messaging.targetResolver`、`agentPrompt.messageToolHints`
+  （cron 投递必须带 to+accountId）、`status` 三件套、`auth.login` CLI 入口、
+  `gatewayMethods` QR RPC
+- **运维**：`/toggle-debug` 开启全链路耗时统计；JSON 行日志写入主 openclaw
+  日志文件（与其他渠道同格式）；`compat.ts` 宿主版本守卫
+- **协议差异**（合理保留）：WebSocket 推送代替长轮询（无 sync-buf 游标）；
+  二维码本地生成（非平台下发）；绑定确认靠 WS 事件（非 HTTP 轮询）；
+  凭据为环境变量注入的 appKey/appSecret（非扫码 token）；无 typing API
+
+## 凭据链路（与微信插件的关键差异）
+
+凭据不是扫码登录获得：桌面端登录后从
+`/open-apis/desktop/oauth2/workchat/credentials` 换取 `workchatApiKey`/
+`workchatAppSecret`，以 `WORKCHAT_API_KEY` / `WORKCHAT_APP_SECRET` /
+`USER_ID` 环境变量注入网关进程；openclaw.json 使用 `${WORKCHAT_API_KEY}` /
+`${WORKCHAT_APP_SECRET}` 占位符，密钥不落盘。
+
+## 连接协议
+
+```
+POST {base}/authen/v1/access_token/internal   app_key/app_secret -> accessToken
+POST {base}/open-apis/v1/connections/open      subscriptions     -> endpoint + ticket
+WS   {endpoint}?ticket=...                     AGENT_MESSAGE/EVENT/SYSTEM
+```
+
+- 开连接时的订阅声明：`[{type:"CALLBACK",topic:"AGENT_MESSAGE"},{type:"EVENT",topic:"*"},{type:"SYSTEM",topic:"*"}]`。
+- `SYSTEM` + topic `ping` → 回 `pong`；topic `disconnect` → 关闭并重连。
+- `EVENT` + `AGENT_CREATED|AGENT_UPDATED|AGENT_DELETED|INIT_AGENT` → 账号生命周期。
+- `CALLBACK` + topic `AGENT_MESSAGE` → 用户消息。
+
+## WebSocket 帧协议详解（信封结构）
+
+每帧是一个 JSON 信封：`{ type, metadata: { time, event|topic, contentType }, data }`，
+`data` 可能是对象，也可能是 JSON 字符串（解析前需二次 `JSON.parse`），甚至是裸标量
+（如 INIT_AGENT 的 data 为字符串化的 agent id，需归一化为 `{id}`）。
+
+| type | metadata 判定 | data 内容 | 插件处理 |
+|------|--------------|-----------|----------|
+| `SYSTEM` | topic=`ping` | 任意（回显） | 回 pong：`{code:200,message:"pong",metadata:{contentType:"application/json"},data:JSON.stringify(原data)}`；成功回包即刷新 `lastEventAt`（连通性判据） |
+| `SYSTEM` | topic=`disconnect` | — | 主动关闭 WS，交给重连循环 |
+| `EVENT` | event=`INIT_AGENT` | `{id, futureId}`（或裸 agentId） | 扫码绑定完成事件：持久化账号、绑定 agentId/userId、唤醒 web.login.wait；重绑时先清理旧 agent 账号 |
+| `EVENT` | event=`AGENT_CREATED` | `{id, futureId, ...}` | 平台创建智能体：保存账号并回执状态（notifyAgentCreatedStatus） |
+| `EVENT` | event=`AGENT_UPDATED` | agent 对象 | 无本地动作（记录日志） |
+| `EVENT` | event=`AGENT_DELETED` | `{id, ...}` | 删除对应本地账号绑定（含状态文件/索引/allowFrom/openclaw.json accounts 条目）并触发渠道重载 |
+| `CALLBACK` | topic=`AGENT_MESSAGE` | `{userId, conversationId, msgId, agentId, message: {content}}` | 用户消息：斜杠命令 → 配对鉴权 → 路由 → 记录会话 → 派发回复 |
+| — | 其他/未知 | — | 忽略 |
+
+zhixiaotu 参考实现（`zhixiaotu_channel/packages/plugin`）中还存在但 workchat 插件
+暂未接的 EVENT 类型：`TOOLS_LIST`、`SKILLS_LIST`、`SKILL_DO_REMIND`（skills 事件）、
+`CRON_REMIND`（定时任务事件）——协议格式见
+`zhixiaotu_channel/packages/plugin/src/gateway/message-context.ts`。
+
+### 连通性判据（诊断口径）
+
+- **连接已建立**：WS `onopen` 成功后插件才上报 `running: true`（`monitor.ts`）。
+- **连接保活**：服务端周期性下发 `SYSTEM/ping`（节奏约 1-2 分钟），插件回 pong
+  成功后刷新 `lastEventAt`。因此「WS 活着」= `running === true && lastError 为空
+  && lastEventAt 距今 < 10 分钟`。
+- 桌面端连通性测试（`work-claw-desktop/src/main/im/imGatewayManager.ts`
+  `testWorkchatOpenClawConnectivity`）通过网关 `channels.status` RPC 读取上述快照，
+  按此口径给出 pass/fail。
+
+## 开发
+
+```bash
+npm install            # 安装 esbuild/typescript
+npm run bundle         # 打包 index.js
+npm run sync           # 同步到 ../work-claw-desktop（可传路径参数）
+npm run typecheck
+```
+
+## 配置项（channels.openclaw-workchat）
+
+| 配置项 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| enabled | boolean | 否 | 是否启用通道 |
+| baseUrl | string | 否 | 默认 `https://workbrain.cn/backend-api` |
+| websocketUrl | string | 否 | 默认从 baseUrl 推导 |
+| appKey | string | 是 | `${WORKCHAT_API_KEY}` 占位符 |
+| appSecret | string | 是 | `${WORKCHAT_APP_SECRET}` 占位符 |
+| accounts | object | 否 | 多账号配置，每项可覆盖 agentId/userId |
+
+## 断线重连
+
+- 指数退避（5s 起步，上限 5 分钟），鉴权失败（errCode 2001 /
+  unauthorized / 缺凭据）停止重连。
+- 限频（“访问过于频繁”）时以 1s 最小退避重试。
+
+## 测试
+
+```bash
+npm test    # vitest：accounts（索引/清理/prune 边界）+ inbound（帧解析/data 归一化）
+```
+
+## TODO（已知留白）
+
+- **事件接入**：`TOOLS_LIST` / `SKILLS_LIST` / `SKILL_DO_REMIND` / `CRON_REMIND`
+  暂不处理（归入 ignored，debug 日志记录 `ignoredKind`）。协议参考
+  `zhixiaotu_channel/packages/plugin/src/gateway/message-context.ts`，接入时按
+  zhixiaotu 的 dispatcher 补 handler。
+- **账号文件写入加锁**：`handleAgentLifecycleEvent` 里保存/清理账号与
+  `triggerWorkChatChannelReload` 触发的重载存在并发读写 accounts.json 的窗口；
+  可复用 `pairing.ts` 的 `withFileLock`。
+- **serial 持久化**：`buildDeviceSerial` 每次扫码按主机名+MAC 现算，网卡变化
+  （VPN/虚拟网卡）会得到不同 serial，平台可能视为新设备导致重复绑定；
+  建议首次生成后持久化到 state 目录。