@cubeai/dsh-weixin-channel 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/LICENSE +201 -0
  2. package/NOTICE +18 -0
  3. package/README.md +64 -2
  4. package/client.js +3112 -0
  5. package/cordis.patch.yml +4 -0
  6. package/docs/dsh-weixin-channel.md +473 -0
  7. package/icon.svg +15 -0
  8. package/locale/en.json +6 -0
  9. package/locale/zh.json +6 -0
  10. package/package.json +76 -4
  11. package/src/channels/connection-state.js +12 -0
  12. package/src/channels/diagnostics.js +77 -0
  13. package/src/channels/factory.js +22 -0
  14. package/src/channels/file-send.js +34 -0
  15. package/src/channels/media.js +9 -0
  16. package/src/channels/meta.js +24 -0
  17. package/src/channels/qr/hub.js +229 -0
  18. package/src/channels/qr/render.js +8 -0
  19. package/src/channels/qr/shared.js +50 -0
  20. package/src/channels/qr/weixin.js +76 -0
  21. package/src/channels/weixin.js +965 -0
  22. package/src/engine/abort.js +35 -0
  23. package/src/engine/access.js +23 -0
  24. package/src/engine/agent-options.js +19 -0
  25. package/src/engine/approval.js +70 -0
  26. package/src/engine/assistant-settings.js +38 -0
  27. package/src/engine/assistant-text.js +11 -0
  28. package/src/engine/atomic-file.js +45 -0
  29. package/src/engine/chat-commands.js +752 -0
  30. package/src/engine/choice-delivery.js +20 -0
  31. package/src/engine/choices.js +103 -0
  32. package/src/engine/command-locale.js +70 -0
  33. package/src/engine/command-messages.js +434 -0
  34. package/src/engine/command-permissions.js +38 -0
  35. package/src/engine/command-replies.js +59 -0
  36. package/src/engine/credentials.js +54 -0
  37. package/src/engine/deferred-delivery.js +260 -0
  38. package/src/engine/delivery-history.js +39 -0
  39. package/src/engine/file-delivery.js +215 -0
  40. package/src/engine/file-input.js +52 -0
  41. package/src/engine/file-log.js +25 -0
  42. package/src/engine/gateway.js +1337 -0
  43. package/src/engine/image-input.js +31 -0
  44. package/src/engine/json-state.js +25 -0
  45. package/src/engine/keyed-queue.js +20 -0
  46. package/src/engine/merge.js +56 -0
  47. package/src/engine/message-progress.js +274 -0
  48. package/src/engine/question.js +201 -0
  49. package/src/engine/quiet-logger.js +25 -0
  50. package/src/engine/reply-stream.js +86 -0
  51. package/src/engine/router.js +759 -0
  52. package/src/engine/secure-file.js +8 -0
  53. package/src/engine/seen-store.js +43 -0
  54. package/src/engine/session-export.js +64 -0
  55. package/src/engine/session-history.js +30 -0
  56. package/src/engine/session-id.js +62 -0
  57. package/src/engine/session-store.js +109 -0
  58. package/src/engine/session-title.js +29 -0
  59. package/src/engine/split.js +291 -0
  60. package/src/engine/workspace-path.js +9 -0
  61. package/src/index.js +62 -0
  62. package/src/manager.js +1297 -0
@@ -0,0 +1,4 @@
1
+ # DSH微信频道:把微信机器人应用接入本机 DeepSeek Harness。
2
+ - insert:
3
+ - id: weixin-channel
4
+ name: '@cubeai/dsh-weixin-channel'
@@ -0,0 +1,473 @@
1
+ # DSH微信频道技术实现说明
2
+
3
+ > 本文面向需要了解插件内部机制、排障或二次开发的读者。安装、添加频道等日常操作请见 [README.md](../README.md)。
4
+
5
+ ## 1. 定位与边界
6
+
7
+ 「DSH微信频道」把个人微信机器人接入本机 DeepSeek Harness。插件只支持个人微信,不包含企业微信或其他 IM 通道,也不依赖云端中转:微信消息由本机 Host 通过腾讯 iLink Bot 长轮询接收(`ilinkai.weixin.qq.com`),再交给 DSH 的 Agent 处理。
8
+
9
+ 一个**微信频道**对应:
10
+
11
+ - 一次微信扫码登录得到的机器人登录态(`botToken`);
12
+ - 一条本机长轮询连接;
13
+ - 一组本地配置:模型、工作区、权限、Agent 预设、私聊准入、发送方式和命令权限。
14
+
15
+ 因为个人微信一个用户只能创建一个 AI 机器人,插件在设计上**只允许存在一个微信频道**:
16
+
17
+ - 首次安装后主界面中央显示「添加微信频道」;
18
+ - 已有频道后不再提供添加入口,右上角显示「设置」;
19
+ - 只有删除现有频道后才能再次添加。
20
+
21
+ ## 2. 包结构与加载
22
+
23
+ | 部分 | 文件 | 作用 |
24
+ |---|---|---|
25
+ | Cordis bundle patch | `cordis.patch.yml` | 向 profile 插入 Host 插件行 `weixin-channel` |
26
+ | Host 入口 | `src/index.js` | 注册 Config、初始化状态目录和日志、创建 `ChannelManager` |
27
+ | Host 核心 | `src/manager.js` | 频道生命周期、单频道约束、状态、凭据、HTTP API、扫码、诊断 |
28
+ | 消息引擎 | `src/engine/*` | 会话路由、消息合并、Agent 调用、审批/提问、命令、投递 |
29
+ | 微信通道 | `src/channels/weixin.js` | iLink 长轮询、媒体加解密、typing、诊断 |
30
+ | 微信扫码 | `src/channels/qr/weixin.js` | 获取登录二维码、轮询扫码状态 |
31
+ | Client 入口 | `client.js` | 注册侧边栏菜单项、主面板、会话行图标和 composer |
32
+ | 本地化 | `locale/*.json` | 中文/英文插件元数据 |
33
+
34
+ `package.json` 中:
35
+
36
+ - `dsh.bundle.patch` 指向 `cordis.patch.yml`;
37
+ - `dsh.client.platform` 为 `web`;
38
+ - `dsh.client.inject` 注入 locale、slots 和 UI primitives。
39
+
40
+ Host Config:
41
+
42
+ | 配置 | 默认值 | 作用 |
43
+ |---|---|---|
44
+ | `stateDir` | 空(使用 `$DSH_HOME/dsh-weixin-channel`) | 状态目录和日志目录 |
45
+ | `cwd` | `process.cwd()` | 默认工作区 |
46
+ | `provider` | 空 | 新频道的默认模型提供商 |
47
+ | `model` | 空 | 新频道的默认模型 |
48
+ | `agentPreset` | `standard` | 默认 Agent 预设 |
49
+ | `mergeTimeoutSecs` | `5` | 连续消息合并等待时间 |
50
+
51
+ Host 启动顺序:
52
+
53
+ ```text
54
+ apply()
55
+ → 解析 Config(stateDir/cwd/provider/model/agentPreset/mergeTimeoutSecs)
56
+ → 创建状态目录和 gateway.log
57
+ → new ChannelManager(...)
58
+ → manager.registerApi(ctx)
59
+ → manager.initEnabled() # 启动已启用的频道
60
+ → manager.attachMappedSessions() # 恢复已有 dwc: 会话
61
+ ```
62
+
63
+ `src/index.js` 的 `ctx.effect` 在卸载时调用 `disposeApi()`,停止 API、扫码、频道连接和消息引擎。
64
+
65
+ ## 3. Host 架构
66
+
67
+ ```text
68
+ src/index.js
69
+ └─ ChannelManager
70
+ ├─ channels.json / allowlist / pending
71
+ ├─ CredentialVault(ctx.credentials 或 secrets.json 回退)
72
+ ├─ PairingHub(微信扫码)
73
+ └─ WeixinChannelAdapter(iLink 长轮询)
74
+ └─ ImEngine
75
+ ├─ SessionRouter(dwc: 会话)
76
+ ├─ SessionMerger / ReplyStreamHub
77
+ ├─ ApprovalBroker / QuestionBroker
78
+ ├─ ChatCommands / CommandPermissions
79
+ ├─ DeferredDelivery
80
+ └─ FileDelivery / ImageInput
81
+ ```
82
+
83
+ ### 3.1 ChannelManager
84
+
85
+ 负责:
86
+
87
+ - 加载、迁移和原子写入 `channels.json`;
88
+ - 维护频道启用状态、接收状态和运行中的 adapter;
89
+ - 保存/解析凭据引用,不把登录令牌写进普通状态文件;
90
+ - 扫码配对、连接、重连、诊断、移除;
91
+ - 提供管理 API;
92
+ - 将微信消息交给 `ImEngine`,把 Agent 回复送回微信;
93
+ - 维护 `dwc:` 会话映射,并挂载到对应工作区。
94
+
95
+ 单频道约束在 `connectNow()` 中强制:如果已存在任意微信频道,且本次扫码得到的不是同一个频道身份,返回:
96
+
97
+ ```text
98
+ 已有微信频道,请先删除现有频道后再添加
99
+ ```
100
+
101
+ 同一微信用户重复扫码会命中相同 `accountId`,因此可以安全地刷新登录态。
102
+
103
+ ### 3.2 PairingHub
104
+
105
+ 扫码登录入口:
106
+
107
+ 1. `POST /ilink/bot/get_bot_qrcode?bot_type=3` 获取二维码 ID 与内容;
108
+ 2. Host 用 `qrcode` 在本地生成二维码图片(不调用第三方二维码服务);
109
+ 3. 轮询 `get_qrcode_status`,支持 `waiting` / `scanned` / `confirmed` / `expired`;
110
+ 4. 确认后取得 `bot_token`、`ilink_user_id`、`baseurl`;
111
+ 5. 保存凭据并创建频道,随后启动 adapter。
112
+
113
+ ### 3.3 WeixinChannelAdapter
114
+
115
+ 基于腾讯官方 iLink Bot 协议的长轮询适配器:
116
+
117
+ - `getupdates` 长轮询收消息,游标保存在 `wechat-state.json`;
118
+ - 文本、图片、语音、文件、视频解析;
119
+ - CDN 媒体使用 AES-128-ECB 加解密;
120
+ - `context_token` 回复,同一聊天出站串行;
121
+ - `getconfig` → `sendtyping` 的「正在输入」状态;
122
+ - 登录态失效(`ret=-14`)时清除令牌并要求重新扫码;
123
+ - 暴露连接状态和诊断信息。
124
+
125
+ ### 3.4 ImEngine
126
+
127
+ 与具体 IM 平台解耦的消息/会话层,负责:
128
+
129
+ - 将微信聊天映射为 DSH 会话;
130
+ - 消息去重、合并、分流;
131
+ - 调用 DSH Agent;
132
+ - 审批、提问、选择按钮和命令处理;
133
+ - 流式回复、分片、失败重试和延迟投递;
134
+ - 私聊准入;
135
+ - 文件和图片输入输出;
136
+ - 会话标题、历史恢复和工作区挂载。
137
+
138
+ Host 通过 `ctx` 使用这些宿主服务:
139
+
140
+ ```text
141
+ webServer, credentials, agents, agentPresets,
142
+ agentDefaultModel, llm, permissionPresets
143
+ ```
144
+
145
+ `connection`、`sessionPersistence`、`workspaceRegistry`、`userQuestions` 等通过 `ctx.get(...)` 按需读取;宿主缺少对应服务时会降级,而不是让插件启动失败。
146
+
147
+ ## 4. 状态、凭据与会话
148
+
149
+ ### 4.1 状态目录
150
+
151
+ 默认:
152
+
153
+ ```text
154
+ $DSH_HOME/dsh-weixin-channel
155
+ ```
156
+
157
+ 未设置 `DSH_HOME` 时通常是 `~/.dsh/dsh-weixin-channel`。可通过 Host Config 的 `stateDir` 覆盖。
158
+
159
+ | 文件 | 内容 |
160
+ |---|---|
161
+ | `channels.json` | 频道配置、允许列表、待批准请求、默认设置 |
162
+ | `sessions.json` | `dwc:` 会话映射 |
163
+ | `seen.json` | 消息去重记录 |
164
+ | `deferred-delivery.json` | 发送失败后的延迟投递状态 |
165
+ | `gateway.log` | 插件运行日志(滚动文件) |
166
+ | `secrets.json` | 仅当 Host 没有 credentials 服务时的本地凭据回退文件 |
167
+ | `accounts/<channelId>/wechat-state.json` | 登录用户、`context_token`、轮询游标、服务端 base URL |
168
+ | `accounts/<channelId>/wechat-login.txt` | 最近一次登录二维码 URL(仅排障用) |
169
+ | `accounts/<channelId>/media/` | 入站媒体落盘 |
170
+
171
+ ### 4.2 channels.json
172
+
173
+ 当前结构版本为 2,核心字段如下:
174
+
175
+ ```jsonc
176
+ {
177
+ "version": 2,
178
+ "channels": {
179
+ "weixin_ab12cd34ef56": {
180
+ "id": "weixin_ab12cd34ef56",
181
+ "platform": "weixin",
182
+ "name": "微信频道 1",
183
+ "nameOrdinal": 1,
184
+ "enabled": true,
185
+ "receiveEnabled": true,
186
+ "config": {
187
+ "allowedUserId": "wxid_xxx",
188
+ "baseUrl": "https://ilinkai.weixin.qq.com",
189
+ "botTokenRef": "dwc_weixin_ab12cd34ef56_botToken"
190
+ },
191
+ "assistant": { "provider": "deepseek-official", "model": "deepseek-flash" },
192
+ "agentPreset": "standard",
193
+ "cwd": "/path/to/workspace",
194
+ "permission": "workspace-write",
195
+ "commandPermissions": {},
196
+ "privateAccess": "approved",
197
+ "sendMode": "queue",
198
+ "lastCheckedAt": "2026-11-19T..."
199
+ }
200
+ },
201
+ "allowlist": { "weixin_ab12cd34ef56": ["wxid_xxx"] },
202
+ "pending": {},
203
+ "assistant": {},
204
+ "cwd": "/path/to/workspace",
205
+ "permission": "workspace-write"
206
+ }
207
+ ```
208
+
209
+ 说明:
210
+
211
+ - `accountId` 由 `weixin + "\0" + allowedUserId` 的 SHA-256 前 12 位生成,格式为 `weixin_<hash>`;
212
+ - 扫码确认后 `allowedUserId` 会同时写入 `channels.json`、`wechat-state.json` 和允许列表;
213
+ - 若状态文件残留 `config.provisioning` 快照,加载时会自动删除并 flush;
214
+ - `lastCheckedAt` 只记录最近一次连接诊断时间,不保存诊断明细。
215
+
216
+ ### 4.3 凭据
217
+
218
+ 优先使用 DSH credentials 服务:
219
+
220
+ ```text
221
+ dwc_<channelId>_botToken
222
+ ```
223
+
224
+ `channels.json` 只保存 `botTokenRef`,不保存明文令牌。普通 `/channels` 响应只暴露 `hasToken`;插件不提供读取令牌的 API。
225
+
226
+ ### 4.4 会话 ID 与映射
227
+
228
+ 微信会话 ID 格式:
229
+
230
+ ```text
231
+ dwc:<channelId>:<dm|group>:<13位以上时间戳>:<chatId>
232
+ ```
233
+
234
+ 例如:
235
+
236
+ ```text
237
+ dwc:weixin_ab12cd34ef56:dm:1793773379160:wxid_xxx
238
+ ```
239
+
240
+ - `dwc:` 与会话页签中的普通任务、`im:` 会话完全分开;
241
+ - `sessions.json` 的 key 是 `channelId:dm|group:chatId`;
242
+ - `SessionRouter` 只恢复 `dwc:` 前缀的会话;
243
+ - 插件把 `dwc:` 会话从「任务」列表排除,通过微信频道面板和会话行图标呈现。
244
+
245
+ ## 5. 管理 API
246
+
247
+ 基础路径:
248
+
249
+ ```text
250
+ /api/dsh-weixin-channel
251
+ ```
252
+
253
+ 请求约束:
254
+
255
+ - 入口调用宿主 `connection.requestRejection(req)` 做登录/来源校验;宿主认证服务不可用时返回 503;
256
+ - 变更请求必须带:
257
+
258
+ ```text
259
+ x-dsh-weixin-channel-client: 1
260
+ content-type: application/json
261
+ ```
262
+
263
+ - 请求体上限 1 MB;超限返回 413;
264
+ - GET 不做变更标记校验;
265
+ - 响应格式统一为 `{ ok, ... }`,错误只返回安全文案,不返回凭据。
266
+
267
+ 主要路由:
268
+
269
+ | 方法 | 路径 | 作用 |
270
+ |---|---|---|
271
+ | GET | `/channels` | 频道、会话分组、待批准请求和默认设置 |
272
+ | GET | `/assistant` | 默认模型/权限/预设/工作区和模型目录 |
273
+ | POST | `/assistant` | 保存默认设置 |
274
+ | POST | `/sessions/rename` | 重命名微信会话 |
275
+ | POST | `/sessions/remove` | 删除微信会话 |
276
+ | POST | `/sessions/cleanup-missing` | 清理已不存在的会话 |
277
+ | POST | `/sessions/ensure` | 确保会话已挂载 |
278
+ | GET | `/channels/weixin/qr/status` | 查询扫码状态 |
279
+ | POST | `/channels/weixin/qr/start` | 开始扫码 |
280
+ | POST | `/channels/weixin/qr/refresh` | 刷新二维码 |
281
+ | POST | `/channels/weixin/qr/cancel` | 取消扫码 |
282
+ | POST | `/channels/weixin/connect` | 使用登录凭据建立频道(界面走扫码,不直接使用) |
283
+ | POST | `/channels/weixin/receive` | 设置接收开关 |
284
+ | POST | `/channels/weixin/disconnect` | 断开连接 |
285
+ | POST | `/channels/weixin/remove` | 移除频道 |
286
+ | POST | `/channels/weixin/approve` | 批准私聊用户 |
287
+ | POST | `/channels/weixin/deny` | 拒绝私聊用户 |
288
+ | POST | `/accounts/:id/settings` | 保存频道级设置 |
289
+ | POST | `/accounts/:id/receive` | 设置频道接收开关 |
290
+ | POST | `/accounts/:id/reconnect` | 重连频道 |
291
+ | POST | `/accounts/:id/check` | 运行连接诊断 |
292
+ | POST | `/accounts/:id/remove` | 移除频道 |
293
+ | POST | `/accounts/:id/approve` | 批准频道用户 |
294
+ | POST | `/accounts/:id/deny` | 拒绝频道用户 |
295
+
296
+ 界面主要使用 `/channels`、`/assistant`、二维码和 `/accounts/:id/*`。
297
+
298
+ ## 6. 消息运行流程
299
+
300
+ ### 6.1 添加频道
301
+
302
+ ```text
303
+ 用户填写频道名称和初始设置
304
+ → POST /channels/weixin/qr/start
305
+ → PairingHub 获取 iLink 登录二维码
306
+ → 用户在手机微信扫码并确认
307
+ → PairingHub 取得 bot_token / ilink_user_id / baseurl
308
+ → 保存凭据到 credentials,写入频道配置和登录态
309
+ → ChannelManager.connect() → startOne()
310
+ → WeixinChannelAdapter 长轮询启动
311
+ → 频道出现在主面板
312
+ ```
313
+
314
+ ### 6.2 入站消息
315
+
316
+ ```text
317
+ iLink getupdates 长轮询
318
+ → WeixinChannelAdapter 解析文本与媒体
319
+ → ImEngine
320
+ → 去重(seen.json)
321
+ → 私聊准入
322
+ → 斜杠命令或普通消息
323
+ → SessionMerger / SessionRouter
324
+ → DSH Agent
325
+ → 流式回复 / 审批 / 提问 / 文件
326
+ → WeixinChannelAdapter sendmessage
327
+ ```
328
+
329
+ ### 6.3 出站与失败处理
330
+
331
+ - 文本按微信消息大小限制分片(`maxMessageLength = 1200`);
332
+ - 图片、视频、文件先加密上传 CDN,再以对应 item 发送;
333
+ - 处理中显示「正在输入」;
334
+ - 发送失败按分片退避重试;
335
+ - 明确拒收(429/503、`ret=-2`)进入 `deferred-delivery.json`,由后台恢复逻辑重试;
336
+ - 工具调用前的过渡文字不占用微信有限的回复窗口(`skipInterimText`)。
337
+
338
+ ### 6.4 访问控制与命令
339
+
340
+ - 私聊准入支持 `approved` 和 `all`;
341
+ - 扫码登录用户会加入允许列表;
342
+ - 未批准用户在面板中显示,可批准/拒绝;
343
+ - 每个频道可配置命令权限(私聊/群聊、允许的命令);
344
+ - 常用命令包括 `/status`、`/workspace`、`/new`、`/model` 等,具体以当前命令实现为准。
345
+
346
+ ## 7. Client 结构与界面
347
+
348
+ `client.js` 通过 `window.__ModuleLoader__.load` 注册模块,模块 id 为:
349
+
350
+ ```text
351
+ @cubeai/dsh-weixin-channel
352
+ ```
353
+
354
+ ### 7.1 左侧边栏菜单项
355
+
356
+ 插件使用 DSH 公开的全局面板槽位:
357
+
358
+ - `sidebar.panellist` 注册 `id = weixin-channel`、`order = 30` 的菜单项;
359
+ - 菜单图标由插件绘制,标签来自 `locale`,与「DSH飞书客户端」「CubeAI应用中心」等条目平级;
360
+ - 不包装、不替换 `sidebar.workspaces`,也不使用私有 Registry 约定。
361
+
362
+ ### 7.2 主面板
363
+
364
+ `main` 槽位以 `key = weixin-channel` 注册主面板:
365
+
366
+ - 没有微信频道时,主界面中央显示「添加微信频道」按钮;
367
+ - 已有频道时,右上角显示「设置」按钮;标题栏显示频道名称与连接状态;
368
+ - 频道页正文直接内嵌该频道的微信会话(官方 `conversation.content` 的 `embedded` 变体),消息、工具卡片、审批/提问和底部的微信只读输入条都在频道页内;
369
+ - 内嵌区顶部显示会话标题、更新时间和会话切换器(多会话时),正文为官方对话视图与底部微信只读输入条;
370
+ - 只有一个会话时不再显示会话列表;会话多于一个时,内嵌区顶部提供会话切换器;
371
+ - 频道设置弹窗:
372
+ - 频道名称;
373
+ - 微信绑定信息(微信用户 ID、登录状态);
374
+ - 工作区;
375
+ - 模型和推理等级;
376
+ - 权限;
377
+ - Agent 预设;
378
+ - 私聊准入;
379
+ - 发送方式(排队/插话);
380
+ - 命令权限;
381
+ - 连接诊断、重连、移除。
382
+ - 删除频道后,`channels.json`、登录态和会话映射会被清理,页面回到空状态,可以重新添加。
383
+
384
+ 添加频道弹窗只保留扫码流程,包含频道名称和初始频道设置。
385
+
386
+ ### 7.3 会话行图标与 Composer
387
+
388
+ - 主面板通过声明 session 作用域的 `weixin-channel.conversation` 子槽位,用 `SessionProvider` + `renderFactorySlot('conversation.content', { variant: 'embedded' })` 把官方会话嵌进频道页;`sessions.retain()` 的引用在切换/卸载时释放;
389
+ - 通过 `sidebar.session.row.leading` 槽位,为 `dwc:` 会话显示微信品牌小图标;
390
+ - 对 `dwc:` 会话注册 `conversation.composer`:
391
+ - 如果会话存在待审批/待回答交互,让位给宿主自身的交互 composer;
392
+ - 否则替换为微信只读提示栏:模型只读展示、不允许本地输入;
393
+ - 运行中显示停止按钮,确认后调用会话级 `conversation.cancel()`。
394
+
395
+ ### 7.4 国际化与样式
396
+
397
+ - 中文/英文词典内置在 client 中;
398
+ - 服务端错误通过 `server.*` 键映射,未知错误显示通用文案;
399
+ - 样式选择器统一使用 `.dwc-` 前缀;
400
+ - 颜色使用 DSH 主题 token(`--dsw-alias-*`);
401
+ - 不覆盖宿主全局样式,不写 `body`/`#root` 规则。
402
+
403
+ ## 8. 与其他插件的共存
404
+
405
+ | 项目 | dsh-im-connect | dsh-feishu-channels | 本插件 |
406
+ |---|---|---|---|
407
+ | 会话前缀 | `im:` | `dfc:` | `dwc:` |
408
+ | 侧栏入口 | 工作区页签 | 工作区页签 | 全局面板菜单项 |
409
+ | 面板 id | `channels` | `feishu` | `weixin-channel` |
410
+ | 状态目录 | 各自独立 | 各自独立 | 各自独立 |
411
+ | API 前缀 | 各自独立 | 各自独立 | 各自独立 |
412
+ | 凭据 | 各自独立 | 各自独立 | 各自独立 |
413
+
414
+ 本插件与另外两个插件没有 npm 依赖,也不共享状态。全局面板槽位是公开 API,不需要识别或包装其他插件的实现。
415
+
416
+ ## 9. 安全与隔离
417
+
418
+ - 管理 API 复用宿主登录/来源校验,不自行实现登录;
419
+ - 变更请求要求客户端标记头和 JSON content-type,降低跨站表单误操作风险;
420
+ - 登录令牌只通过 credentials 服务保存,列表只暴露 `hasToken`;
421
+ - 优先使用宿主 credentials 服务;
422
+ - `secrets.json` 回退文件权限为 0600;
423
+ - 二维码在 Host 本地生成,不调用第三方二维码服务;
424
+ - 微信 CDN 图片下载校验 HTTPS、主机名和大小上限,并禁止重定向;
425
+ - 插件不自带更新器,不修改其他插件的状态或代码。
426
+
427
+ ## 10. 诊断与运维
428
+
429
+ ### 10.1 日志
430
+
431
+ 默认日志:
432
+
433
+ ```text
434
+ $DSH_HOME/dsh-weixin-channel/gateway.log
435
+ ```
436
+
437
+ 日志包含启动、频道启动/停止、扫码、API 注册、消息投递和错误摘要。
438
+
439
+ ### 10.2 连接诊断
440
+
441
+ `POST /accounts/:id/check` 会执行连接探测,返回:
442
+
443
+ - 当前频道状态;
444
+ - 是否已登录;
445
+ - 平台响应摘要;
446
+ - 诊断检查项。
447
+
448
+ 未登录或令牌失效时返回 `auth` 失败。诊断结果只用于当前操作,不写入 `channels.json`。
449
+
450
+ ### 10.3 重连与移除
451
+
452
+ - 重连:`POST /accounts/:id/reconnect`;
453
+ - 移除:`POST /accounts/:id/remove`,删除频道配置、登录态、会话映射和凭据引用;
454
+ - 卸载插件本身不会自动删除状态目录;若要彻底清除,需要手动删除状态目录和 `dwc:` 会话记录。
455
+
456
+ ## 11. 已知限制
457
+
458
+ - 只支持个人微信,不包含企业微信或其他 IM 通道;
459
+ - 只允许一个微信频道;个人微信一个用户只能创建一个机器人;
460
+ - 登录协议使用腾讯官方 iLink Bot 接口,建议使用专用小号;
461
+ - 登录态失效后需要重新扫码(重新添加频道,或重新连接后在微信中确认);
462
+ - 插件不负责刷新/更新自身版本;
463
+ - 宿主认证服务不可用时,管理 API 会返回 503,页面无法加载频道数据;
464
+ - 客户端页面依赖 DSH Web profile 的 slots、locale 和 UI primitives。
465
+
466
+ ## 12. 验证
467
+
468
+ ```bash
469
+ node scripts/check.js
470
+ node --test tests/*.test.mjs
471
+ ```
472
+
473
+ 测试覆盖 Host API、单频道约束、扫码/配对、微信协议工具、会话 ID、凭据、频道模型刷新和客户端注册与渲染。
package/icon.svg ADDED
@@ -0,0 +1,15 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="DSH 微信频道">
2
+ <defs>
3
+ <linearGradient id="dwc-bg" x1="8" y1="6" x2="56" y2="58" gradientUnits="userSpaceOnUse">
4
+ <stop stop-color="#07c160"/>
5
+ <stop offset="1" stop-color="#0e9f8f"/>
6
+ </linearGradient>
7
+ </defs>
8
+ <rect x="4" y="4" width="56" height="56" rx="16" fill="url(#dwc-bg)"/>
9
+ <path d="M15.5 25.7c0-6.1 5.6-11 12.6-11s12.6 4.9 12.6 11-5.6 11-12.6 11c-1.5 0-3-.2-4.3-.6l-5.6 3.1c-.7.4-1.5-.3-1.3-1.1l1.1-4.3c-1.6-2-2.5-4.4-2.5-8.1Z" fill="#ffffff" opacity=".96"/>
10
+ <path d="M33.4 31.2c3.9 1.9 6.4 5.1 6.4 8.8 0 2.8-.9 5.2-2.5 7l1.1 4.3c.2.8-.6 1.5-1.3 1.1l-5-2.8c-1.3.4-2.8.6-4.3.6-4.5 0-8.4-2.1-10.6-5.3" fill="none" stroke="#ffffff" stroke-width="3.4" stroke-linecap="round" stroke-linejoin="round" opacity=".96"/>
11
+ <circle cx="23.4" cy="24.4" r="2.1" fill="#0aa457"/>
12
+ <circle cx="31.8" cy="24.4" r="2.1" fill="#0aa457"/>
13
+ <circle cx="38.6" cy="39.1" r="1.9" fill="#0aa457"/>
14
+ <circle cx="45.4" cy="39.1" r="1.9" fill="#0aa457"/>
15
+ </svg>
package/locale/en.json ADDED
@@ -0,0 +1,6 @@
1
+ {
2
+ "meta": {
3
+ "title": "DSH WeChat Channel",
4
+ "description": "DSH WeChat Channel: connect a personal WeChat bot to the local DeepSeek Harness and drive local agents from WeChat."
5
+ }
6
+ }
package/locale/zh.json ADDED
@@ -0,0 +1,6 @@
1
+ {
2
+ "meta": {
3
+ "title": "DSH微信频道",
4
+ "description": "DSH微信频道:把个人微信机器人接入本机 DeepSeek Harness,在微信里随时驱动本机智能体。"
5
+ }
6
+ }
package/package.json CHANGED
@@ -1,6 +1,78 @@
1
1
  {
2
2
  "name": "@cubeai/dsh-weixin-channel",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "DSH微信频道 — 将个人微信机器人接入本机 DeepSeek Harness。",
5
+ "type": "module",
6
+ "main": "src/index.js",
7
+ "exports": {
8
+ ".": "./src/index.js",
9
+ "./client": "./client.js",
10
+ "./cordis.patch.yml": "./cordis.patch.yml",
11
+ "./package.json": "./package.json",
12
+ "./locale/*.json": "./locale/*.json",
13
+ "./icon": "./icon.svg"
14
+ },
15
+ "files": [
16
+ "src",
17
+ "client.js",
18
+ "cordis.patch.yml",
19
+ "locale",
20
+ "icon.svg",
21
+ "README.md",
22
+ "LICENSE",
23
+ "NOTICE",
24
+ "docs"
25
+ ],
26
+ "keywords": [
27
+ "dsh",
28
+ "dsh-plugin",
29
+ "weixin",
30
+ "wechat",
31
+ "im",
32
+ "微信"
33
+ ],
34
+ "author": "huolongshe",
35
+ "license": "Apache-2.0",
36
+ "engines": {
37
+ "node": "^22.19.0 || >=24.0.0"
38
+ },
39
+ "dsh": {
40
+ "bundle": {
41
+ "patch": "./cordis.patch.yml"
42
+ },
43
+ "client": {
44
+ "platform": "web",
45
+ "inject": [
46
+ "@deepseek-ai/dsh-client-locale",
47
+ "@deepseek-ai/dsh-client-ui-slots",
48
+ "@deepseek-ai/dsh-client-ui-primitives"
49
+ ]
50
+ }
51
+ },
52
+ "dependencies": {
53
+ "@deepseek-ai/schemastery": "^3.18.2",
54
+ "qrcode": "^1.5.4"
55
+ },
56
+ "peerDependencies": {
57
+ "@deepseek-ai/cordis": "^4.0.2",
58
+ "@deepseek-ai/dsh-agent": "^0.2.1-rc.2",
59
+ "@deepseek-ai/dsh-client-locale": "^0.2.1-rc.2",
60
+ "@deepseek-ai/dsh-client-ui-primitives": "^0.2.1-rc.2",
61
+ "@deepseek-ai/dsh-client-ui-slots": "^0.2.1-rc.2",
62
+ "@deepseek-ai/dsh-host-webserver": "^0.2.1-rc.2",
63
+ "@deepseek-ai/schemastery": "^3.18.2"
64
+ },
65
+ "scripts": {
66
+ "check": "node scripts/check.js",
67
+ "test": "node --test tests/*.test.mjs"
68
+ },
69
+ "repository": {
70
+ "type": "git",
71
+ "url": "git+https://github.com/cube-ai/dsh-weixin-channel.git"
72
+ },
73
+ "homepage": "https://github.com/cube-ai/dsh-weixin-channel",
74
+ "publishConfig": {
75
+ "access": "public",
76
+ "registry": "https://registry.npmjs.org/"
77
+ }
78
+ }
@@ -0,0 +1,12 @@
1
+ /** Maps the Weixin adapter's status text to the account view state. */
2
+ const readyStates = new Set(['已登录', '已登录(自动恢复)']);
3
+ const connectingStates = new Set(['登录中', '等待扫码', '连接中']);
4
+
5
+ export function connectionState(status) {
6
+ if (readyStates.has(status)) return 'connected';
7
+ if (connectingStates.has(status)) return 'connecting';
8
+ if (status === '已停止') return 'stopped';
9
+ if (status === '未登录' || status === '未连接' || status === '已断开') return 'disconnected';
10
+ if (status === '连接失败' || status === '连接失败,请查看本机日志' || status === '连接错误') return 'error';
11
+ return 'unknown';
12
+ }
@@ -0,0 +1,77 @@
1
+ export class DiagnosticError extends Error {
2
+ reason;
3
+ httpStatus;
4
+ platformCode;
5
+ constructor(reason, httpStatus, platformCode) {
6
+ super(reason);
7
+ this.reason = reason;
8
+ this.httpStatus = httpStatus;
9
+ this.platformCode = platformCode;
10
+ }
11
+ }
12
+ export async function probe(id, signal, run) {
13
+ const started = Date.now();
14
+ try {
15
+ signal.throwIfAborted();
16
+ await run();
17
+ signal.throwIfAborted();
18
+ return { id, status: 'passed', reason: 'ok', durationMs: Date.now() - started };
19
+ }
20
+ catch (error) {
21
+ const failure = error instanceof DiagnosticError ? error : new DiagnosticError(signal.aborted ? signal.reason?.name === 'TimeoutError' ? 'timeout' : 'cancelled' : 'network');
22
+ return { id, status: ['cancelled', 'missing-context', 'not-connected', 'unsupported', 'changed'].includes(failure.reason) ? 'unverified' : 'failed', reason: failure.reason, durationMs: Date.now() - started,
23
+ ...(failure.httpStatus === undefined ? {} : { httpStatus: failure.httpStatus }), ...(failure.platformCode === undefined ? {} : { platformCode: failure.platformCode }) };
24
+ }
25
+ }
26
+ /** 新请求、不跟随重定向、限制回包大小;调用方负责平台业务码与必要字段校验。 */
27
+ export async function diagnosticJson(url, signal, body, headers, fetcher = fetch) {
28
+ const response = await fetcher(url, { method: body === undefined ? 'GET' : 'POST', headers: { 'content-type': 'application/json', ...headers }, body: body === undefined ? undefined : JSON.stringify(body), signal, redirect: 'error' });
29
+ if (!response.ok) {
30
+ await response.body?.cancel();
31
+ const status = response.status;
32
+ throw new DiagnosticError(status === 401 ? 'auth' : status === 403 ? 'permission' : status === 429 ? 'rate-limit' : status >= 500 ? 'server' : 'rejected', status);
33
+ }
34
+ if (!response.body)
35
+ throw new DiagnosticError('invalid-response');
36
+ const reader = response.body.getReader();
37
+ const chunks = [];
38
+ let size = 0;
39
+ try {
40
+ for (;;) {
41
+ const { done, value } = await reader.read();
42
+ if (done)
43
+ break;
44
+ size += value.length;
45
+ if (size > 65536)
46
+ throw new DiagnosticError('invalid-response');
47
+ chunks.push(value);
48
+ }
49
+ let result;
50
+ try {
51
+ result = JSON.parse(Buffer.concat(chunks).toString('utf8'));
52
+ }
53
+ catch {
54
+ throw new DiagnosticError('invalid-response');
55
+ }
56
+ if (!result || typeof result !== 'object' || Array.isArray(result))
57
+ throw new DiagnosticError('invalid-response');
58
+ return result;
59
+ }
60
+ finally {
61
+ await reader.cancel().catch(() => undefined);
62
+ reader.releaseLock();
63
+ }
64
+ }
65
+ export function requireDiagnostic(value) {
66
+ if (!value)
67
+ throw new DiagnosticError('invalid-response');
68
+ }
69
+ export function platformResult(code, authCodes = []) {
70
+ if (!(typeof code === 'number' || typeof code === 'string' && /^-?\d+$/.test(code)))
71
+ throw new DiagnosticError('invalid-response');
72
+ const numeric = Number(code);
73
+ if (!Number.isFinite(numeric))
74
+ throw new DiagnosticError('invalid-response');
75
+ if (numeric !== 0)
76
+ throw new DiagnosticError(authCodes.includes(numeric) ? 'auth' : numeric === 429 ? 'rate-limit' : 'rejected', undefined, numeric);
77
+ }