cortico-world-wechat-claw 0.1.9 → 0.2.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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,24 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.0
4
+
5
+ - 更换扩展图标为新的 512 × 512 PNG,并随 npm 包发布。
6
+ - 合并微信绑定、FFmpeg 管理和 TTS 到「连接与工具」面板。FFmpeg 与 TTS 使用并排卡片,窄屏下纵向排列。TTS 设置与密钥在同一个抽屉内,通用配置按用途分组。
7
+ - 发送前将 LaTeX 公式转成 Unicode 或可读文字,并将 Markdown 列表缩进续行合并到对应条目。代码和普通金额保留。
8
+ - 兼容入站文字和语音转写的已知负载结构,补充脱敏的异常入站结构日志。
9
+ - 新增 `wechat_send_voice`,默认发送 MP3 音频文件卡片。配置页可即时启用试验性的原生语音条。音频失败时补发说明或失败提示,与文本共享回复额度。
10
+ - `wechat_send_voice` 支持转发 Core 音频附件句柄,可将其他工具生成的音频作为微信回复发送。
11
+ - TTS 面板可发现本机和局域网的大肥鱼 GPT-SoVITS,按服务单独保存令牌。可直接接收其 WAV 合成结果并转成微信音频文件。
12
+ - 新增默认关闭的 `wechat_speak`,支持 OpenAI 兼容语音合成、独立密钥和临时文件清理。合成或音频投递失败时补发原文。
13
+ - TTS 设置支持查询硅基流动的合成模型及音色,并兼容以 `/chat/completions` 结尾的服务地址。
14
+
15
+ ## 0.1.10
16
+
17
+ - 配置页增加「微信消息投递方式」,支持合批、立即投递、抢占、打断和随下一批投递。默认仍为合批,保存后对后续入站消息生效。
18
+ - 微信 SILK v3 语音通过 `silk-wasm` 转为 24 kHz、16-bit、单声道 WAV。Provider 接受 `audio/wav` 时随转写投递,转码失败或 WAV 超限时保留原始 SILK 和转写。
19
+ - 分段阈值默认和最大均为 8,按同一回复凭据累计文字、附件及说明的成功条数。接近本地 10 条上限时恢复完整原文,仍按单条 4000 字分段。剩余额度不足时在发送前拒绝整次调用。
20
+ - `ret=-2 prepare failed` 停用当时的回复凭据并报告已发条数,等待新凭据后恢复。计数和停用状态跨重启保留。
21
+
3
22
  ## 0.1.9
4
23
 
5
24
  - 入站文件先按可确认的文件头识别 PDF、音频、视频和图片容器,再用实际 MIME 查询当前 Provider;补齐 AIFF、音频 WebM、MPEG、3GP、HEIF 等扩展名,修复改名或无扩展名的媒体被误判为普通二进制而未附的问题。
package/README.md CHANGED
@@ -21,7 +21,7 @@
21
21
  | 收文件 | 只显示 `[文件 名字]` 占位 | 解密落到 `wechat-inbox/files/`,保留对方给的原文名;她读得到、改得了,也能原样发回去 |
22
22
  | 发文件 | 不支持 | `wechat_send_file`:同上,带原文件名与明文长度;同样只限工作区 |
23
23
  | 上传来源 | —— | 只限工作区+收件目录+`sendExtraDirs`;先 `realpath` 再判定,`..` 与符号链接都绕不出去 |
24
- | 语音 | 占位 | 保留服务端转写文本;原音频落到 `wechat-inbox/voices/`,Provider 支持实际编码时同时附上 |
24
+ | 语音 | 占位 | 保留服务端转写。SILK 转成 WAV 后落到 `wechat-inbox/voices/`,Provider 支持时一并附上 |
25
25
  | 长文本 | 超 4000 字被拒 | 自动切成多条发送,优先在段落与句号处断开 |
26
26
  | 出站视频 | 不支持 | 按 MIME 走视频通道,微信里显示成视频而不是附件 |
27
27
  | 入站超限 | 无区分 | 超限、缺参数、下载失败三种原因分别措辞 |
@@ -37,6 +37,8 @@
37
37
  | `wechat_send` | 回复最近一条微信消息;只能发给刚发消息的人,单条上限 4000 字 |
38
38
  | `wechat_send_image` | 把工作区里的一张图发到微信,可带一句说明;工作区外的路径直接拒绝 |
39
39
  | `wechat_send_file` | 把工作区里的一个文件发到微信,可带一句说明;同样只限工作区 |
40
+ | `wechat_send_voice` | 把工作区或微信收件目录中的 WAV、MP3、SILK v3 发成 MP3 音频文件卡片,失败时补发文字 |
41
+ | `wechat_speak` | 启用微信 TTS 后,将指定文字合成音频发到微信,失败时补发原文 |
40
42
  | `wechat_status` | 连接、账号、最近消息、错误、持有多少条会话令牌,以及工作区/收件目录/允许发送的目录 |
41
43
  | `wechat_events` | 按类型和时间查已归档的微信事件 |
42
44
 
@@ -60,7 +62,7 @@ corepack pnpm add "<本地包目录,绝对路径,例如 E:\WorkShop\...\cort
60
62
 
61
63
  ## 绑定
62
64
 
63
- 1. 打开「微信绑定」面板,点「生成二维码」。
65
+ 1. 打开「连接与工具」,在微信绑定区域点「生成二维码」。
64
66
  2. 用手机微信扫码;二维码打不开时复制面板里的链接。
65
67
  3. 手机要求输入数字时,在面板的验证码框里填写并提交。
66
68
 
@@ -68,7 +70,7 @@ corepack pnpm add "<本地包目录,绝对路径,例如 E:\WorkShop\...\cort
68
70
 
69
71
  ## 配置
70
72
 
71
- 配置段是 `worlds.wechat-claw`。
73
+ 配置段是 `worlds.wechat-claw`。配置页按「消息投递与回复」「附件收发」「图片与视频」「微信网络」分组。语音合成服务在「连接与工具」的「TTS 设置」中配置。
72
74
 
73
75
  | 键 | 默认 | 说明 |
74
76
  |---|---|---|
@@ -76,11 +78,12 @@ corepack pnpm add "<本地包目录,绝对路径,例如 E:\WorkShop\...\cort
76
78
  | `networkMode` | `inherit` | `inherit` 跟随 Coopanion 的代理;`direct` 直连;`proxy` 用 `proxyUrl` |
77
79
  | `proxyUrl` | 空 | `proxy` 模式的 HTTP/HTTPS 代理,例如 `http://127.0.0.1:7890` |
78
80
  | `forceIpv4` | `false` | `direct`/`proxy` 下强制 IPv4 |
81
+ | `inboundTrigger` | `debounce` | 微信消息投递方式。保存后对后续入站事件生效 |
79
82
  | `receiveImages` | `true` | 收图时下载并交给模型 |
80
83
  | `receiveFiles` | `true` | 收文件时下载,Provider 接受实际 MIME 时附在消息中 |
81
84
  | `receiveVideos` | `false` | 收微信视频消息时下载(体积大,默认关);原生理解也需开启 |
82
- | `receiveVoices` | `true` | 收语音时下载 |
83
- | `maxInboundMediaMb` | `20` | 单条入站媒体上限,超过只留占位;也是出站媒体的上限 |
85
+ | `receiveVoices` | `true` | 下载语音并将 SILK 转成 WAV |
86
+ | `maxInboundMediaMb` | `20` | 单条入站与出站媒体上限。转换后的 WAV 超限时保留 SILK 原件 |
84
87
  | `inboxDir` | 空 | 收件目录。留空=桌宠工作区下的 `wechat-inbox`;相对路径按工作区解析。改完要重启 |
85
88
  | `sendExtraDirs` | 空 | 额外允许发到微信的目录,一行一个(分号、逗号也行)。留空时只有工作区(与收件目录)能发 |
86
89
  | `ffmpegSource` | `auto` | 视频抽帧用哪份 ffmpeg:`auto` 先 PATH 再用面板装的那份、`path` 只用 PATH、`off` 不抽帧 |
@@ -91,8 +94,15 @@ corepack pnpm add "<本地包目录,绝对路径,例如 E:\WorkShop\...\cort
91
94
  | `ffmpegProxyUrl` | 空 | 下载 ffmpeg 用的代理;留空直连(不继承只给模型用的那条代理) |
92
95
  | `segmentEnabled` | `true` | 分段发送:一次回复拆成多条微信消息 |
93
96
  | `segmentPace` | `1` | 聊天节奏,0~10;越大停顿越久,0 不等待 |
94
- | `segmentMaxParts` | `12` | 语义段数达到此阈值就恢复完整原文,仅按 4000 字上限分条;0 不限 |
97
+ | `segmentMaxParts` | `8` | 语义段数达到此阈值就恢复完整原文,仅按 4000 字上限分条。0 使用默认值,旧配置大于 8 时按 8 执行 |
95
98
  | `segmentMaxTotalSec` | `30` | 累计等待上限,到点不再等但剩下的照常发完 |
99
+ | `nativeVoiceEnabled` | `false` | 「试用微信原生语音条」开关,保存即时生效 |
100
+ | `ttsEnabled` | `false` | 启用 `wechat_speak` |
101
+ | `ttsProtocol` | `openai` | `openai` 为 OpenAI 兼容接口,`gpt-sovits` 为大肥鱼 GPT-SoVITS 公开语音接口 |
102
+ | `ttsBaseUrl` | 空 | TTS 服务地址 |
103
+ | `ttsModel` | 空 | TTS 模型名 |
104
+ | `ttsVoice` | 空 | TTS 声音名 |
105
+ | `ttsSpeed` | `1` | TTS 语速,范围 0.25–4 |
96
106
 
97
107
  `bot_token`、同步游标和 `context_token` 都在 `<dataDir>/wechat-claw/`,不进配置、不进日志、不进事件 `meta.raw`。
98
108
  **它们在工作区外面,所以发不出去**——`wechat_send_image` / `wechat_send_file` 只接受工作区内的路径(见下)。
@@ -106,7 +116,7 @@ corepack pnpm add "<本地包目录,绝对路径,例如 E:\WorkShop\...\cort
106
116
  ├── images/ wx-image-20261108-144219.png
107
117
  ├── files/ 报告-20261108-144219.pdf ← 原文名在前,时间戳在后
108
118
  ├── videos/ wx-video-20261108-144219.mp4
109
- ├── voices/ wx-voice-20261108-144219.silk
119
+ ├── voices/ wx-voice-20261108-144219.wav
110
120
  └── .derived/ 压缩后的图、视频拼图(中间产物)
111
121
  ```
112
122
 
@@ -136,6 +146,8 @@ corepack pnpm add "<本地包目录,绝对路径,例如 E:\WorkShop\...\cort
136
146
 
137
147
  ## 分段发送
138
148
 
149
+ `wechat_send` 在分段前转换美元符号包裹的 LaTeX 公式,并把列表项的缩进续文合并到对应标题行。公式尽量转成 Unicode,复杂命令保留可读文本。代码围栏、行内代码与普通金额保留。列表项之间的换行继续参与语义分段。
150
+
139
151
  微信里一次吐一大段不像人说话。打开分段发送后,一次回复会拆成几条,一条一条发,条与条之间停顿。
140
152
 
141
153
  **拆分只算一次**,不会拆两次:
@@ -156,7 +168,9 @@ corepack pnpm add "<本地包目录,绝对路径,例如 E:\WorkShop\...\cort
156
168
 
157
169
  **ASCII `.` 有额外保护**:单个点只在后面跟空白或位于结尾时才当句号。所以 `3.14`、`docs.nonebot.dev`、`report.2026.11.md` 不会被切坏。连续两个及以上的点按省略号保留,换行前也不会删掉;`../`、`..\` 这类路径片段不参与省略号分段。
158
170
 
159
- 语义段数**达到** `segmentMaxParts` 时取消语义分段,保留原文的换行和标点直接发送。原文超过微信单条 4000 字时仍按长度分条,每条均不超限。累计等待超过 `segmentMaxTotalSec` 后不再等待,其余消息照常发完。
171
+ 语义段数**达到** `segmentMaxParts` 时取消语义分段,保留预处理后文本的换行和标点。按语义拆出的多条消息会用尽或超出剩余额度时,同样发送预处理后的完整文本。超过微信单条 4000 字时仍按长度分条。累计等待超过 `segmentMaxTotalSec` 后,其余消息连续发送。
172
+
173
+ 扩展按复现中的 10 条为每个 `context_token` 设置本地发送上限。文字、媒体和附件说明每成功发出一条都计入同一额度,重启后保留计数。发送前会核对剩余条数,完整内容发不下时会提前拒绝这次调用。收到 `ret=-2 prepare failed` 时会停用这次使用的凭据,报告已发送条数,等对方发来带新凭据的消息再恢复回复。
160
174
 
161
175
  「聊天节奏」控制每条消息发送前的停顿,默认 1:
162
176
 
@@ -171,13 +185,29 @@ corepack pnpm add "<本地包目录,绝对路径,例如 E:\WorkShop\...\cort
171
185
 
172
186
  不想要就在配置页关掉「分段发送」。
173
187
 
188
+ ## 出站音频与 TTS
189
+
190
+ `wechat_send_voice` 接收工作区或微信收件目录内的绝对路径。默认上传 MP3 音频文件卡片(`media_type: 3`、`item.type: 4`)。已有 MP3 原样上传,WAV(单声道或立体声 PCM/浮点)与 SILK v3 在本地转成 MP3,无需 ffmpeg。消息里的 CDN 引用取自实际上传响应头 `x-encrypted-param`。
191
+
192
+ 也可用 `blob` 参数发送 Core 已保存的音频,接受 `log:`、`mem:` 句柄或 `[blob …]` 回执行。例如先调用 `sovits_speak(silent: true)`,再把回执里的音频句柄传给 `wechat_send_voice`。每次调用在 `path` 和 `blob` 中选一项,仍需可用的微信回复额度。
193
+
194
+ 打开「试用微信原生语音条」后优先将音频编码为 24 kHz、16-bit、单声道腾讯 SILK,用 `media_type: 4` 上传并发送 `type: 3` 的 `voice_item`。接口接收后的显示、播放以手机端为准。原生转码或上传失败、发送被明确拒绝时,自动改发 MP3。
195
+
196
+ 音频处理、上传或明确发送失败时,`wechat_send_voice` 补发 `fallback_text` 提供的转写或说明,留空时发送失败提示。`wechat_speak` 在合成或音频发送失败时补发原文。补发文字使用同一回复凭据和剩余额度。凭据失效、耗尽、工具取消或发送结果不确定时,工具返回失败原因。
197
+
198
+ 打开「连接与工具」里的「TTS 设置」,在同一个抽屉里填写开关、服务地址、模型、声音、语速和 API Key。普通设置与 API Key 分别保存,保存后即时生效。也可为部署设置 `WECHAT_CLAW_TTS_API_KEY`。`wechat_speak(text)` 将文字提交至该服务生成临时 MP3,走同一条音频发送路径,随后清理临时文件。
199
+
200
+ 使用硅基流动时,保存 API Key 后可点「获取模型」,列表只显示账号可见且官方文档确认支持合成的型号。选好模型再点「获取音色」,即可选择官方预置或账号中属于该模型的自定义音色。其他服务仍可手动填写。服务地址也接受末尾为 `/chat/completions` 的兼容接口地址。
201
+
202
+ 使用大肥鱼 GPT-SoVITS 时,先在服务端打开「开放本机语音接口」,再在这里点击「发现本机与局域网服务」。单项结果会直接填入配置,多项结果可从下拉框选择。按「保存设置」生效。大肥鱼默认只监听本机,其他设备需要通过局域网地址提供该公开接口。发现仅在点击按钮后检查本机及当前私有 IPv4 网段的 `9880`、`9883` 端口,也会检查已填写的本机或私网地址。自定义地址或需要令牌的服务可以手动添加,密钥按服务地址单独保存。模型与音色留空时使用服务默认值。合成通过 HTTP `/audio/speech` 返回 WAV,再转成微信音频文件,全程无需调用其他 World 工具。
203
+
174
204
  ## 视频抽帧
175
205
 
176
206
  入站文件按可确认的文件头识别 PDF、图片、音频和视频容器;无法确认时使用文件名或微信语音编码提供的类型。每次收件都调用宿主的 `modelFacts.accepts(实际 MIME)`,随当前模型、Provider 协议和输入开关变化。支持时通过事件 `blobs` 提交实际字节、MIME 与文件名;未知类型不会冒充支持的格式。
177
207
 
178
208
  可调用 `wechat_status`,传入 `{"mimes":["video/mp4","audio/wav","application/pdf"]}` 查看 `inputSupport`。`accepted` 是当前 Provider 的类型判断,`error` 表示查询失败;`receive` 是本扩展的下载开关。`lastInboundAttachments` 与事件的 `meta.media` 记录每份文件交给 Core 时的结果:`native` 为原样附件,`frames` 为视频拼图,`omitted` 为未附,原因在 `notes`。这不代表上游已经成功理解文件;字节、总请求大小等仍由 Provider 和上游校验。
179
209
 
180
- OpenCode 原生 Gemini 会将支持的音频、视频、PDF 等附件编码到请求的 `contents[].parts[].inlineData`。请先在 OpenCode 获取模型列表以更新格式声明,并确认所需输入类型未关闭。微信视频消息还需在本扩展打开「收视频」;文件通道发送的视频由「收文件」控制。微信 SILK 语音只有 Provider 接受 `audio/silk` 才会附上,普通音频支持不保证支持 SILK;服务端转写仍保留。
210
+ OpenCode 原生 Gemini 会将支持的音频、视频、PDF 等附件编码到请求的 `contents[].parts[].inlineData`。请先在 OpenCode 获取模型列表以更新格式声明,并确认所需输入类型未关闭。微信视频消息还需在本扩展打开「收视频」,文件通道发送的视频由「收文件」控制。微信 SILK 转码成功后使用 `audio/wav` 判断附件支持,服务端转写仍会投递。
181
211
 
182
212
  OpenCode Provider 必须包含 Gemini 工具回执附件保留修复:Core 将外部事件投递为工具回执,旧版转换只发送回执文字,即使 World 已提供 `blobs`,生成请求时仍会丢失媒体。仅更新本扩展不能修复 Provider 内部的这一步。
183
213
 
@@ -187,7 +217,7 @@ OpenCode Provider 必须包含 Gemini 工具回执附件保留修复:Core 将
187
217
 
188
218
  ### 装 ffmpeg
189
219
 
190
- 在「ffmpeg」面板上点「下载 ffmpeg」才会联网。启用 World、改配置、切 `ffmpegSource` 都不触发下载。
220
+ 在「连接与工具」的 FFmpeg 区域点「下载」才会联网。
191
221
 
192
222
  - 从 `ffmpeg-static` 的 GitHub Releases 下静态构建:压缩包约 27 MB,解压后约 77 MB。
193
223
  - 装在 `<dataDir>/wechat-claw/bin/`,**不改系统 PATH**——悄悄改全局环境变量会影响其他程序,卸载扩展后还会留下垃圾。
@@ -268,7 +298,7 @@ Coopanion 启动 Core 时会把系统代理写进 `HTTP_PROXY`/`HTTPS_PROXY`,
268
298
  - `direct`:扩展自己建直连,绕过代理;适合代理只给模型用的情况。
269
299
  - `proxy`:用 `proxyUrl` 指定的代理;适合必须走代理才能访问腾讯域名的情况。
270
300
 
271
- 网络设置改完要重启 Coopanion。「微信绑定」面板与 `wechat_status` 会显示当前生效的出口。
301
+ 网络设置在「配置」的「微信网络」中,修改后需重启 World。`wechat_status` 会显示当前生效的出口。
272
302
 
273
303
  ## 媒体怎么走
274
304
 
@@ -280,7 +310,7 @@ AES-128-ECB 加密 → POST 密文到微信 CDN → 从响应头 `x-encrypted-pa
280
310
  落到 `<工作区>/wechat-inbox/{images,files,videos,voices}/`(原文名 + 时间戳)→ 路径写进事件正文 →
281
311
  模型接受该 MIME 时字节作为附件随事件到达。
282
312
 
283
- 能力查询使用 WorldHost 的 `modelFacts.accepts(mime)`,每条消息读取当前 Provider,不按模型名字猜能力。文件通道里的图片、音乐、视频和 Provider 接受的文档也会附上。图片仍经过体积、尺寸和数量限制;语音使用消息声明的实际编码,不把 MP3 误标成 SILK。不支持的编码或文件、读取失败与图片超限都会取消该附件,并把原因写进正文供桌宠告知用户。
313
+ 能力查询使用 WorldHost 的 `modelFacts.accepts(mime)`,每条消息读取当前 Provider,不按模型名字猜能力。文件通道里的图片、音乐、视频和 Provider 接受的文档也会附上。图片仍经过体积、尺寸和数量限制,语音按落盘后的实际 MIME 判断是否附上。不支持的编码或文件、读取失败与图片超限都会取消该附件,并把原因写进正文供桌宠告知用户。
284
314
 
285
315
  附件由 Core 和 Provider 转成上游请求。Provider 的 MIME 声明与请求实现必须同时支持该格式;上游拒绝请求时由 Core 显示具体错误,World 不在后台另发模型请求或重试。仅上游模型增加能力、Provider 仍声明只收图片时,原生音视频不会启用。
286
316
 
@@ -288,7 +318,15 @@ AES-128-ECB 加密 → POST 密文到微信 CDN → 从响应头 `x-encrypted-pa
288
318
 
289
319
  最近消息徽章按部署时区显示,例如 `11/16 16:37`。时间保存在部署数据目录的 `wechat-claw/status.json`,重启后恢复;旧版没有该文件时从当前绑定用户的归档事件恢复。解绑会清除状态。
290
320
 
291
- 长轮询的 35 秒是请求等待上限,有消息时由服务端提前返回,并非固定每 35 秒收一次。入站事件使用 `debounce`,本地 Cortico 默认静默等待 2.5 秒合批,连续来消息时最长 15 秒;实际值取决于部署的 `batching` 配置。Core 正在调用模型或工具时还要等待相应的轮次边界。
321
+ 长轮询的 35 秒是请求等待上限,有消息时由服务端提前返回。默认「合并后投递」由 Core 的 `batching` 配置控制,本地 Cortico 默认静默等待 2.5 秒,连续收到消息时合批最长等待 15 秒。可在配置页的「微信消息投递方式」下拉框修改,保存后无需重启 World。
322
+
323
+ | 投递方式 | 配置值 | 行为 |
324
+ |---|---|---|
325
+ | 合并后投递(默认) | `debounce` | 短暂等待,将连续消息合成一批 |
326
+ | 立即投递 | `flush` | 立即放行积压,当前轮继续运行 |
327
+ | 抢占尚未输出的回复 | `preempt` | 立即投递,可取消尚无外部输出且未在执行工具的模型轮 |
328
+ | 打断当前轮 | `interrupt` | 立即投递并停止当前轮,已发出的回复保留 |
329
+ | 随下一批投递 | `piggyback` | 消息入队,等其他事件唤醒 |
292
330
 
293
331
  媒体下载、压缩和视频抽帧在入站处理里依次执行,处理结束后才继续轮询,较大媒体会拖慢后续消息。原生视频路径跳过抽帧,减少这部分处理。`wechat_status.lastInboundTiming`、事件 `meta.timing` 与「微信入站消息已处理」日志分别提供:
294
332
 
@@ -297,6 +335,8 @@ AES-128-ECB 加密 → POST 密文到微信 CDN → 从响应头 `x-encrypted-pa
297
335
  - `queueMs`:同一批消息在本地开始处理前的排队时间。
298
336
  - `processingMs`:保存状态、下载和准备附件所用的时间,不含 Core 合批与模型响应。
299
337
 
338
+ 排查微信听写消息时,先查看「收到 N 条微信消息」。异常结构会额外输出「未识别的微信入站结构」,包含跳过原因、类型、已知字段的数据形状和未知字段数量。日志省略消息正文、账号、下载引用和令牌。枚举缺失或未知时,会尝试从已有 `text_item.text` 或 `voice_item.text` 读取文字。
339
+
300
340
  正文里的图片尺寸读自落盘文件本身(JPEG 的 SOF 段、PNG 的 IHDR 等)。微信消息里的
301
341
  `thumb_width` / `thumb_height` 是缩略图尺寸,普遍只有 210 像素宽,和真图差一个数量级,
302
342
  所以不用它。
@@ -307,7 +347,7 @@ AES-128-ECB 加密 → POST 密文到微信 CDN → 从响应头 `x-encrypted-pa
307
347
  - 只能回复,不能主动发起会话。回复需要对方最近一条消息的 `context_token`,约 24 小时后失效。
308
348
  - **只能发工作区里的文件**。要发外面的素材,先把目录写进 `sendExtraDirs`,或把文件复制进工作区。
309
349
  - 单条文本上限 4000 字;更长的回复由扩展自动分条,断行优先落在段落与句号上。
310
- - 微信语音通常是 SILK 编码,本扩展只落盘不解码;转写用服务端给的 `voice_item.text`,Provider 支持实际编码时附上原音频。没有转写且不支持该编码时,模型无法听到语音内容。
350
+ - 微信 SILK v3 语音通过 `silk-wasm` 转成 24 kHz、16-bit、单声道 WAV,无需 ffmpeg。解码失败或 WAV 超过单条媒体上限时,保存原始 `.silk`。转写来自微信的 `voice_item.text`,Provider 接受落盘音频的 MIME 时一并附上。
311
351
  - Provider 不接受原生视频时,抽帧需要 ffmpeg;没有可用 ffmpeg 时不抽帧,正文会写明。不做本地音频转写。
312
352
  - 微信 ClawBot 是腾讯面向 OpenClaw 的官方通道,不是面向任意第三方 agent 的公开 SDK。条款、灰度范围、额度与接口都可能变化;发布前请核对当前条款。这个扩展不是腾讯或 Coopanion 的官方扩展。
313
353
 
@@ -318,7 +358,7 @@ corepack pnpm install
318
358
  corepack pnpm typecheck
319
359
  corepack pnpm exec tsc -p tsconfig.web.json --noEmit
320
360
  corepack pnpm test
321
- corepack pnpm build # 打 dist/webui.js
361
+ corepack pnpm build # 构建 WebUI 的 JS 和 CSS
322
362
  ```
323
363
 
324
364
  测试用本机真端口的假 iLink 服务端,覆盖请求形状、uint64 ID 无损解析、AES 往返、
@@ -362,7 +402,7 @@ cortico-world-wechat-claw/
362
402
  │ └── webui/
363
403
  │ ├── client.ts # 面板入口(绑定 + ffmpeg)
364
404
  │ └── ffmpeg.ts # ffmpeg 下载面板
365
- ├── dist/webui.js # 面板产物
405
+ ├── dist/ # 面板脚本和样式
366
406
  ├── scripts/build-webui.mjs
367
407
  └── tests/
368
408
  ├── paths.test.ts # 工作区探测、文件名清理、发送边界
package/assets/icon.png CHANGED
Binary file
package/describe.json CHANGED
@@ -2,15 +2,14 @@
2
2
  "tools": [
3
3
  {
4
4
  "name": "wechat_send",
5
- "description": "Send a WeChat reply to the person whose inbound message arrived most recently. The channel is one-to-one and reply-only: a context token from that message must still be valid. Text longer than 4000 characters is split into consecutive messages, so write the whole reply at once.",
5
+ "description": "Reply to the bound WeChat user. Send the full reply in one call; text over 4000 characters is split automatically.",
6
6
  "parameters": {
7
7
  "type": "object",
8
8
  "additionalProperties": false,
9
9
  "properties": {
10
10
  "text": {
11
11
  "type": "string",
12
- "minLength": 1,
13
- "description": "Reply text."
12
+ "minLength": 1
14
13
  }
15
14
  },
16
15
  "required": [
@@ -21,24 +20,24 @@
21
20
  "speak"
22
21
  ],
23
22
  "summary": {
24
- "zh": "回复最近一条微信消息;只能发给刚发消息的人。",
25
- "en": "Reply to the latest WeChat message; sends only to the person who just wrote."
23
+ "zh": "回复绑定的微信用户。",
24
+ "en": "Reply to the bound WeChat user."
26
25
  }
27
26
  },
28
27
  {
29
28
  "name": "wechat_send_image",
30
- "description": "Send a picture to the person whose inbound message arrived most recently. Takes an absolute local file path inside the pet workspace (or the configured inbox); paths outside it are refused, so move a file into the workspace first. The file is uploaded to the WeChat CDN and delivered as a picture. A path whose content is not an image is delivered as a file instead, and the receipt says so. Optional caption is sent as a separate text message first.",
29
+ "description": "Reply with a local image.",
31
30
  "parameters": {
32
31
  "type": "object",
33
32
  "additionalProperties": false,
34
33
  "properties": {
35
34
  "path": {
36
35
  "type": "string",
37
- "description": "Absolute path of a local picture file inside the workspace."
36
+ "description": "Absolute image path in an allowed directory."
38
37
  },
39
38
  "caption": {
40
39
  "type": "string",
41
- "description": "Optional text sent before the picture."
40
+ "description": "Separate text sent before the image."
42
41
  }
43
42
  },
44
43
  "required": [
@@ -55,18 +54,18 @@
55
54
  },
56
55
  {
57
56
  "name": "wechat_send_file",
58
- "description": "Send a file attachment to the person whose inbound message arrived most recently. Takes an absolute local file path inside the pet workspace (or the configured inbox); paths outside it are refused, so move a file into the workspace first. The file is uploaded to the WeChat CDN and delivered as a downloadable file. Video files are delivered as videos, not as attachments. Optional caption is sent as a separate text message first.",
57
+ "description": "Reply with a local file. Videos and images use their native media types.",
59
58
  "parameters": {
60
59
  "type": "object",
61
60
  "additionalProperties": false,
62
61
  "properties": {
63
62
  "path": {
64
63
  "type": "string",
65
- "description": "Absolute path of a local file inside the workspace."
64
+ "description": "Absolute file path in an allowed directory."
66
65
  },
67
66
  "caption": {
68
67
  "type": "string",
69
- "description": "Optional text sent before the file."
68
+ "description": "Separate text sent before the file."
70
69
  }
71
70
  },
72
71
  "required": [
@@ -81,9 +80,78 @@
81
80
  "en": "Send a local file to WeChat."
82
81
  }
83
82
  },
83
+ {
84
+ "name": "wechat_send_voice",
85
+ "description": "Reply with audio from a local path or a host blob. Sends MP3 by default.",
86
+ "parameters": {
87
+ "type": "object",
88
+ "additionalProperties": false,
89
+ "properties": {
90
+ "path": {
91
+ "type": "string",
92
+ "minLength": 1,
93
+ "description": "Absolute WAV, MP3 or SILK v3 path in the workspace or inbox."
94
+ },
95
+ "blob": {
96
+ "type": "string",
97
+ "minLength": 1,
98
+ "description": "Audio log:/mem: handle or its [blob ...] receipt line."
99
+ },
100
+ "fallback_text": {
101
+ "type": "string",
102
+ "maxLength": 4096,
103
+ "description": "Text to send on audio failure. Defaults to a failure notice."
104
+ }
105
+ },
106
+ "oneOf": [
107
+ {
108
+ "required": [
109
+ "path"
110
+ ]
111
+ },
112
+ {
113
+ "required": [
114
+ "blob"
115
+ ]
116
+ }
117
+ ]
118
+ },
119
+ "tags": [
120
+ "speak"
121
+ ],
122
+ "summary": {
123
+ "zh": "发送本地音频或宿主音频附件,默认发 MP3 文件卡片。",
124
+ "en": "Send local audio or a host audio blob, as an MP3 attachment by default."
125
+ }
126
+ },
127
+ {
128
+ "name": "wechat_speak",
129
+ "description": "With TTS enabled, reply with synthesized speech. Falls back to the original text on audio failure.",
130
+ "parameters": {
131
+ "type": "object",
132
+ "additionalProperties": false,
133
+ "properties": {
134
+ "text": {
135
+ "type": "string",
136
+ "minLength": 1,
137
+ "maxLength": 4096
138
+ }
139
+ },
140
+ "required": [
141
+ "text"
142
+ ]
143
+ },
144
+ "tags": [
145
+ "speak"
146
+ ],
147
+ "summary": {
148
+ "zh": "启用 TTS 时,将文字合成后发到微信,音频失败时补发原文。",
149
+ "en": "When TTS is enabled, synthesize and send audio to WeChat, with the original text as a fallback."
150
+ }
151
+ },
84
152
  {
85
153
  "name": "wechat_status",
86
- "description": "Report the WeChat ClawBot connection: bound account, whether the long poll is connected, the last inbound message time, the last error and how many context tokens are held. Also reports live model input support, receive switches and the last attachment delivery results. Pass mimes to check specific file types against the active Provider.",
154
+ "description": "Check WeChat connection, allowed send paths, active Provider input support and recent attachment results.",
87
155
  "parameters": {
88
156
  "type": "object",
89
157
  "additionalProperties": false,
@@ -95,7 +163,7 @@
95
163
  "type": "string",
96
164
  "minLength": 1
97
165
  },
98
- "description": "Optional exact MIME types, such as audio/wav, video/mp4 or application/pdf."
166
+ "description": "Exact MIME types to check, e.g. audio/wav or application/pdf."
99
167
  }
100
168
  }
101
169
  },
@@ -104,32 +172,32 @@
104
172
  "snapshot"
105
173
  ],
106
174
  "summary": {
107
- "zh": "查看微信连接、账号、最近消息与错误。",
108
- "en": "Show the WeChat connection, account, last message and errors."
175
+ "zh": "查看连接、附件状态与模型输入能力。",
176
+ "en": "Check connection, attachments and model input support."
109
177
  }
110
178
  },
111
179
  {
112
180
  "name": "wechat_events",
113
- "description": "Read archived WeChat events by kind and time. kind accepts * as a wildcard. Raw payloads never include context tokens.",
181
+ "description": "Read archived WeChat messages.",
114
182
  "parameters": {
115
183
  "type": "object",
116
184
  "additionalProperties": false,
117
185
  "properties": {
118
186
  "kind": {
119
187
  "type": "string",
120
- "description": "Event kind or glob, for example message/private."
188
+ "description": "Event kind or * glob, e.g. message/private."
121
189
  },
122
190
  "since": {
123
191
  "type": "string",
124
- "description": "ISO 8601 lower bound, inclusive."
192
+ "description": "Inclusive ISO 8601 start."
125
193
  },
126
194
  "until": {
127
195
  "type": "string",
128
- "description": "ISO 8601 upper bound, inclusive."
196
+ "description": "Inclusive ISO 8601 end."
129
197
  },
130
198
  "limit": {
131
199
  "type": "integer",
132
- "description": "Maximum events to return, 1-100, default 30."
200
+ "description": "Up to 100 messages, default 30."
133
201
  }
134
202
  }
135
203
  },
@@ -146,8 +214,8 @@
146
214
  {
147
215
  "type": "wechat-claw.message",
148
216
  "description": {
149
- "zh": "一条微信私聊消息;媒体路径写在正文里,Provider 支持的图片、音频、视频和文件作为附件到达。不支持原生视频时尝试抽帧,附件未提供的原因写在正文里。",
150
- "en": "A WeChat 1:1 message with local media paths. Images, audio, video and files arrive as attachments when accepted by the Provider. Video falls back to frames; unavailable attachments include a reason."
217
+ "zh": "一条微信私聊消息。默认合并后投递,投递方式可在配置页修改。正文包含媒体路径,Provider 支持的文件随消息附上。不支持原生视频时尝试抽帧。",
218
+ "en": "A WeChat 1:1 message. Incoming messages are batched by default, and delivery can be configured. The message includes local media paths and attaches files accepted by the Provider. Video falls back to frames."
151
219
  },
152
220
  "trigger": "debounce"
153
221
  },
@@ -164,7 +232,7 @@
164
232
  "key": "worlds.wechat-claw.envPrompt",
165
233
  "title": "微信 ClawBot · 环境提示词",
166
234
  "role": "envPrompt",
167
- "content": "微信 ClawBot 是一条一对一私聊通道,接在微信里,只能回复刚发消息的那个人。\n\n## 手边的状态\n\n{{wechat.state | (微信还没接上。)}}\n{{wechat.account | (还没有绑定的微信号。)}}\n{{wechat.lastMessageAt | (还没有收到过微信消息。)}}\n{{wechat.lastError | (最近没有连接错误。)}}\n\n## 收到的东西在哪\n\n对方发来的图片、文件、视频、语音都落在你的工作区里:\n\n```\n{{wechat.inbox | (收件目录还没解析出来。)}}\n```\n\n它下面按类型分成 `images/`、`files/`、`videos/`、`voices/`,文件名保留对方给的原文名,后面接一个本地时间戳。\n这些文件就是普通文件——**读得到、改得了、也发得回去**。想让对方看到改过之后的版本,改完直接\n用 `wechat_send_file` 发那个路径就行。\n\n## 什么时候用\n\n微信里来人说话时,会收到一条 `wechat-claw.message`,正文以 `[微信 时间 发送者]` 开头,媒体路径就写在里面。要回话就用 `wechat_send`;图片用 `wechat_send_image`,其他文件用 `wechat_send_file`,两者都接本机绝对路径。\n\n- 对方发来图片时,图片会作为附件一起到达,路径也写在正文里。看不到附件时,按路径自行读取。\n 正文说「图片未附:体积…/尺寸…/超出数量上限」时,那张图是真的没交给你,**不要猜图里有什么**。\n- 对方发来文件时,路径写在正文里;当前 Provider 支持的图片、音乐、视频和文档会同时作为附件到达,需要本地内容时按路径读。\n- 对方发来视频时,当前 Provider 支持原生视频就直接附上视频;不支持时保留抽帧方式,把几帧**拼成一张图**附上,\n 正文写明布局(如「2列×2行,从左上到右下按时间顺序」)、原视频分辨率与每格尺寸。\n 按这个顺序理解画面;每格都很小,别去描述看不清的细节。正文说「视频帧未抽取」就是真的没看过。\n- 对方发来语音时,正文保留微信服务端转写;Provider 接受实际音频格式时也会附上语音。微信语音通常是 SILK,原生音频能力不保证支持此编码。没有转写也没有可用附件时,不能猜说了什么。\n- 正文写明附件未附、下载失败或抽帧失败时,告诉对方具体原因;不要声称已听过或看过未提供的内容。模型请求被上游拒绝时,以 Core 报告的错误为准。\n- 想确认当前输入能力时,用 `wechat_status` 的 `mimes` 查询具体 MIME;它还报告接收开关和最近附件交给 Core 的结果。能力为真但没有附件时,检查是否未下载、超限或读取失败,不能把磁盘路径当作已发送的附件。\n\n## 能发什么\n\n只有你工作区里的文件能发到微信:\n\n```\n{{wechat.workspace | (工作区路径还没解析出来。)}}\n```\n\n收件目录在工作区里,所以收来的东西发得回去。工作区外面的路径会被直接拒绝——这不是故障,是边界:\n你的配置、密钥和这台机器的其他文件不在工作区的管辖范围内,不该被随手上传出去。\n\n要把工作区外的东西发出去,先把它复制进工作区(例如收件目录),再发复制之后那份。\n被拒绝时回执会列出允许的目录,照着调整路径就行,不要换个写法绕过它。\n\n## 约束\n\n这条通道只能回复最近发消息的人,不能主动找人,也不能发到别处。`wechat_send` 的回执会写明发给了谁。\n\n一条文本最多 4000 字,超出的部分会自动接着发成下一条,不必自己切。断行位置优先落在段落和句号上。\n\n## 分段发送\n\n这一段决定你说话的样子,值得花心思。\n\n打开分段发送时,你写的东西会被拆成好几条微信消息,一条一条发出去,条与条之间会停顿,让对方看着像你还在打字。\n\n拆的顺序按一次算,不会拆两次:\n\n- 你写了换行,就只按换行拆;换行会消失,段内不再按标点拆。紧挨换行的段尾句号也会被去掉,段内的句号留着。\n- 没写换行但有句号,就只按句号拆,句号会消失。\n- 都没写,但有 `!?…~` 或 `......` 这样的省略号,就按它们拆;连续符号只在整串末尾切一次,`~♡`、`……`、`!!!` 和尾随 emoji 都完整留着,换行前也保留省略号。\n- 都没有,就整条发出去。\n\n所以换行是你的节奏工具:**想让对方连看几行、想顿一下再说下一句,就写换行**。反过来,一句话里硬写换行会被拆成好几个气泡,看着像结巴。\n\n中文句号会被删掉,因为在微信里带句号显得生硬、像在写公文。这就是聊天里很少见句号的原因。别为了排版写句号。\n\n分段与间隔都是对方在配置页设的,你看不到也不必猜;照平时的习惯说话就行。\n\n语义段数达到配置阈值时,会恢复完整原文直接发送;超过 4000 字仍按微信上限分条。停顿按字数和「聊天节奏」计算,短句与断句失效的特长段直接发送。\n\n对方的 `context_token` 会过期。回复被拒并提示没有可用 token 时,等对方再说一句再回,不要反复重试。\n\n这里发出的一切都会真的进到对方的微信里。不确定要不要发的时候,先问清楚。\n"
235
+ "content": "微信私聊({{wechat.state | 状态未知}})。入站事件为 `wechat-claw.message`,正文以 `[微信 …]` 开头。\n工作区:`{{wechat.workspace | 未知}}`。收件目录:`{{wechat.inbox | 未知}}`。\n\n- 用微信发送工具回复绑定用户,需有效的入站回复凭据。文字、媒体和说明共用额度,凭据失效或额度用尽时等对方再发消息。只补发未发出的内容,回执确认已补发的文字勿重发。\n- `wechat_send` 启用语义分段时,按换行、句号、语气标点的优先级择一切分,连续标点成组保留。\n- 发送本地文件用允许目录内的绝对路径。图片和文件可用工作区、收件目录或配置放行的目录。外发意图不明确时先确认。\n- 转发工具生成的音频时,将回执的句柄填入 `wechat_send_voice` 的 `blob`。\n- 正文提供本地媒体路径。以实际收到的附件、可读文件或微信语音转写为依据,按标注顺序看视频帧。缺少内容时说明已知原因,勿猜测;用 `wechat_status` 查输入能力和附件状态。\n"
168
236
  }
169
237
  ]
170
238
  }
@@ -0,0 +1,161 @@
1
+ /* src/webui/webui.css */
2
+ .wechat-claw-console > h3 {
3
+ margin-bottom: 10px;
4
+ }
5
+ .wechat-claw-console .wcc-binding-row {
6
+ display: flex;
7
+ flex-wrap: wrap;
8
+ align-items: center;
9
+ justify-content: space-between;
10
+ gap: 12px 20px;
11
+ padding: 14px 16px;
12
+ background: var(--sheet-2);
13
+ border: 1px solid var(--line);
14
+ border-radius: var(--radius-md, 10px);
15
+ }
16
+ .wechat-claw-console .wcc-binding-row > .actionbar {
17
+ flex-wrap: wrap;
18
+ margin: 0;
19
+ padding: 0;
20
+ border: 0;
21
+ }
22
+ .wechat-claw-console .wcc-binding-facts {
23
+ display: grid;
24
+ gap: 6px;
25
+ min-width: 0;
26
+ }
27
+ .wechat-claw-console .wcc-identity {
28
+ display: flex;
29
+ flex-wrap: wrap;
30
+ align-items: center;
31
+ gap: 6px 10px;
32
+ }
33
+ .wechat-claw-console .wcc-account {
34
+ font-weight: 600;
35
+ }
36
+ .wechat-claw-console .wcc-detail {
37
+ color: var(--ink-soft);
38
+ font-size: 0.86rem;
39
+ line-height: 1.5;
40
+ overflow-wrap: anywhere;
41
+ }
42
+ .wechat-claw-console .qrbox {
43
+ margin-block: 16px 10px;
44
+ }
45
+ .wechat-claw-console .qrbox .qr {
46
+ width: min(240px, 100%);
47
+ height: auto;
48
+ }
49
+ .wechat-claw-console .wcc-services {
50
+ display: grid;
51
+ grid-template-columns: repeat(auto-fit, minmax(min(100%, 19rem), 1fr));
52
+ gap: 16px;
53
+ margin-top: 16px;
54
+ }
55
+ .wechat-claw-console .wcc-service {
56
+ display: flex;
57
+ flex-direction: column;
58
+ gap: 8px;
59
+ min-width: 0;
60
+ padding: 16px;
61
+ background: var(--sheet-2);
62
+ border: 1px solid var(--line);
63
+ border-radius: var(--radius-md, 10px);
64
+ overflow-wrap: anywhere;
65
+ }
66
+ .wechat-claw-console .wcc-service .sectionhead {
67
+ margin: 0;
68
+ padding: 0;
69
+ border: 0;
70
+ }
71
+ .wechat-claw-console .wcc-service .sectionhead h4 {
72
+ margin: 0;
73
+ color: var(--ink);
74
+ font-size: 0.96rem;
75
+ font-weight: 600;
76
+ }
77
+ .wechat-claw-console .wcc-service .msgline {
78
+ margin: 0;
79
+ }
80
+ .wechat-claw-console .wcc-service > .actionbar {
81
+ flex-wrap: wrap;
82
+ justify-content: flex-start;
83
+ margin: auto 0 0;
84
+ padding-top: 8px;
85
+ border: 0;
86
+ }
87
+ .wechat-claw-console .wcc-service .btn.primary,
88
+ .wcc-tts-drawer .btn.primary {
89
+ color: var(--on-accent, #fff);
90
+ }
91
+ .wechat-claw-console .wcc-progress {
92
+ width: 100%;
93
+ height: 6px;
94
+ accent-color: var(--accent);
95
+ }
96
+ .wechat-claw-console .wcc-tts-off:not(.bad) {
97
+ color: var(--ink-soft);
98
+ }
99
+ .wcc-tts-drawer,
100
+ .wcc-tts-form,
101
+ .wcc-tts-service,
102
+ .wcc-tts-key {
103
+ display: grid;
104
+ gap: 14px;
105
+ }
106
+ .wcc-tts-fields {
107
+ display: grid;
108
+ grid-template-columns: repeat(auto-fit, minmax(min(100%, 10.5rem), 1fr));
109
+ align-items: start;
110
+ gap: 12px;
111
+ }
112
+ .wcc-tts-lookup {
113
+ display: grid;
114
+ gap: 6px;
115
+ min-width: 0;
116
+ }
117
+ .wcc-tts-lookup > .btn {
118
+ justify-self: start;
119
+ color: var(--ink);
120
+ border-color: var(--line-2);
121
+ }
122
+ .wcc-tts-lookup > .btn:hover {
123
+ border-color: var(--line-strong);
124
+ }
125
+ .wcc-tts-lookup > .msgline:empty {
126
+ display: none;
127
+ }
128
+ .wcc-tts-key {
129
+ margin-top: 4px;
130
+ padding-top: 16px;
131
+ border-top: 1px solid var(--line);
132
+ gap: 6px;
133
+ }
134
+ .wcc-tts-key > .rowbar {
135
+ align-items: flex-end;
136
+ }
137
+ .wcc-tts-key > .rowbar > label {
138
+ flex: 1 1 13rem;
139
+ }
140
+ .wcc-tts-drawer label {
141
+ min-width: 0;
142
+ }
143
+ .wcc-tts-drawer input.field,
144
+ .wcc-tts-drawer select.field {
145
+ width: 100%;
146
+ min-width: 0;
147
+ }
148
+ .wcc-tts-drawer .msgline {
149
+ margin: 0;
150
+ }
151
+ .wcc-tts-discovery-actions {
152
+ flex-wrap: wrap;
153
+ }
154
+ .wcc-tts-service .msgline:empty {
155
+ display: none;
156
+ }
157
+ .wcc-tts-discovery-actions > select.field {
158
+ width: auto;
159
+ flex: 1 1 13rem;
160
+ min-width: 0;
161
+ }