dsh-qqbot-buddy 1.0.0-alpha.4 → 1.0.0-alpha.5
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/README.md +11 -3
- package/docs/FEASIBILITY-seememe.md +238 -0
- package/docs/MODELS-CENTER.md +254 -0
- package/docs/PLAN-seememe-plugin.md +284 -0
- package/docs/USER-GUIDE.md +102 -5
- package/docs/images/console-dshweb-button.png +0 -0
- package/docs/images/console-models-voice.png +0 -0
- package/docs/images/console-models.png +0 -0
- package/docs/images/dshweb-3081-entry.png +0 -0
- package/docs/images/dshweb-dashboard-entry.png +0 -0
- package/docs/images/dshweb-header-entry.png +0 -0
- package/lib/console/api/index.js +2 -0
- package/lib/console/api/memories.js +66 -0
- package/lib/console/api/models.js +198 -0
- package/lib/console/api/schema.js +2 -0
- package/lib/console/static.js +8 -2
- package/lib/core/config/schema.js +44 -5
- package/lib/core/memory/collect.js +200 -12
- package/lib/core/messages/store.js +277 -0
- package/lib/core/migrations.js +65 -0
- package/lib/core/model-slots.js +78 -0
- package/lib/core/tts/adapters/bailian.js +57 -0
- package/lib/core/tts/adapters/command.js +123 -0
- package/lib/core/tts/adapters/custom.js +138 -0
- package/lib/core/tts/adapters/edge.js +287 -0
- package/lib/core/tts/adapters/mimo.js +88 -0
- package/lib/core/tts/adapters/openai.js +62 -0
- package/lib/core/tts/audio.js +312 -0
- package/lib/core/tts/edge-token.js +119 -0
- package/lib/core/tts/http.js +291 -0
- package/lib/core/tts/index.js +381 -0
- package/lib/core/tts/providers.js +559 -0
- package/lib/core/tts/store.js +134 -0
- package/lib/host/agent.js +64 -0
- package/lib/host/tools.js +28 -1
- package/lib/index.js +132 -3
- package/lib/qq/card-render.js +232 -0
- package/lib/qq/commands.js +24 -0
- package/lib/qq/forward-render.js +261 -0
- package/lib/qq/gateway.js +26 -0
- package/lib/qq/inbound.js +66 -47
- package/lib/qq/inline-image.js +7 -1
- package/lib/qq/message-cleaner.js +82 -0
- package/lib/qq/message-log.js +108 -0
- package/lib/qq/middleware.js +26 -1
- package/lib/qq/outbound.js +13 -1
- package/lib/qq/quote-render.js +115 -0
- package/lib/qq/ref-store.js +82 -0
- package/lib/qq/session-adapter.js +58 -0
- package/lib/tools/aliases.js +69 -0
- package/lib/tools/catalog.js +41 -5
- package/lib/tools/data-tools.js +8 -1
- package/lib/tools/history-tools.js +196 -0
- package/lib/tools/index.js +38 -3
- package/lib/tools/vision.js +42 -8
- package/lib/tools/voice.js +180 -0
- package/package.json +4 -11
- package/web/dist/assets/index-BghVQOsV.js +20 -0
- package/web/dist/assets/{index-BLxenMBK.css → index-CRlCVpPr.css} +1 -1
- package/web/dist/index.html +2 -2
- package/lib/client.js +0 -73
- package/web/dist/assets/index-LVHT4dpy.js +0 -20
package/README.md
CHANGED
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
|
|
17
17
|
| 模块 | 说明 |
|
|
18
18
|
| --- | --- |
|
|
19
|
-
| 独立控制台 | 随插件进程启动的 Web 管理台(默认 `127.0.0.1:6198`),token 登录、SSE 实时事件、开机即用,无需额外部署前端或数据库;与 dsh Web 双向快捷入口(控制台顶栏 → dsh Web;dsh Web
|
|
19
|
+
| 独立控制台 | 随插件进程启动的 Web 管理台(默认 `127.0.0.1:6198`),token 登录、SSE 实时事件、开机即用,无需额外部署前端或数据库;与 dsh Web 双向快捷入口(控制台顶栏 → dsh Web;dsh Web 会话头部 → QQ 控制台) |
|
|
20
20
|
| 多机器人 | 每个 bot 独立工作目录 `<workspace>/bots/<botId>`,凭据、会话、日志互不影响;同一进程可管理多个 bot |
|
|
21
21
|
| 配置档与绑定 | 三层策略:`global < bot < profile`;按 `群聊 / 私聊 / 指定 openid` 绑定不同配置档(精确 > 类型通配 > bot 通配 > 默认档),切换配置档不丢记忆 |
|
|
22
22
|
| 提示词管理 | 人设卡、人格卡、口头禅、能力边界、工具指引;控制台提供**提示词拼合预览**,按真实顺序查看每段内容与字符数 |
|
|
@@ -26,6 +26,7 @@
|
|
|
26
26
|
| 群友库 | 记录 openid/昵称/备注/画像;发言人自动注入、被 @ 的人懒加载,避免整库注入 |
|
|
27
27
|
| 表情包 / 人格卡 | 本地图片登记、emotion 标签、每日配额;人格卡可切换与独立编辑 |
|
|
28
28
|
| 图片能力 | 视觉理解(贴图描述)、生成/改图结果自动补发到 QQ,不再需要人工提醒 |
|
|
29
|
+
| 模型中心 | 同一页面按 tab 管理 **LLM / 视觉 / 语音(TTS)** 与后续模型类型插槽:LLM 路由按配置档生效;视觉可选「跟随 LLM 自带视觉(内联图片)」或独立更精细视觉模型;TTS 支持微软 Edge、小米 MiMo(含音色设计/克隆)、阿里云百炼、OpenAI 兼容、自定义 HTTP、本地命令行六类供应商,全局配置面板 + 配置档选择,可试听 |
|
|
29
30
|
| 数据自包含 | 数据目录默认 `~/.dsh-qqbot/v2`,单文件 SQLite;备份 = 拷贝数据目录 + workspace |
|
|
30
31
|
|
|
31
32
|
## 界面预览
|
|
@@ -50,6 +51,10 @@
|
|
|
50
51
|
|
|
51
52
|

|
|
52
53
|
|
|
54
|
+
**模型中心**:LLM / 视觉 / 语音(TTS)/ 更多类型插槽统一入口;TTS 供应商全局配置、支持试听
|
|
55
|
+
|
|
56
|
+

|
|
57
|
+
|
|
53
58
|
**记忆与知识库**:检索、录入与提炼
|
|
54
59
|
|
|
55
60
|

|
|
@@ -145,8 +150,11 @@ Peer 绑定 = 精确 scope(群 openid / 私聊 openid)> 类型通配(group
|
|
|
145
150
|
```
|
|
146
151
|
|
|
147
152
|
- **设置页**:查看/编辑“当前 bot 的生效值”,保存时按每个设置项的 scope 自动分流到对应层级;
|
|
148
|
-
-
|
|
149
|
-
|
|
153
|
+
- **配置档页**:编辑某个配置档的策略(人设/回复/模型/工具/记忆/知识/群友/视觉/语音/表情包),
|
|
154
|
+
并提供提示词预览;作用域绑定决定“哪个群/哪个人用哪个配置档”;
|
|
155
|
+
- **模型页**(新增):按 tab 集中管理 LLM / 视觉 / 语音(TTS)/ 更多类型插槽。TTS 的供应商与凭据是
|
|
156
|
+
全局配置(一次配好可被所有配置档复用),每个配置档再选“用哪个供应商 + 音色/风格/语速/字数上限”。
|
|
157
|
+
详见 [docs/MODELS-CENTER.md](docs/MODELS-CENTER.md) 与用户手册 §4.5。
|
|
150
158
|
|
|
151
159
|
多个 bot 共用同一份进程与数据库结构,但 bot 级配置、数据与会话完全隔离。
|
|
152
160
|
|
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
# 可行性评估:把 astrbot_plugin_fatfish_seememe 移植到 dsh-qqbot-buddy
|
|
2
|
+
|
|
3
|
+
- 上游:https://github.com/Vegra85/astrbot_plugin_fatfish_seememe (AstrBot ≥4.29,MIT,v0.4.1)
|
|
4
|
+
- 目标:dsh-qqbot-buddy v2(DSH/QQ 官方机器人插件,Node ESM + cordis)
|
|
5
|
+
- 结论:**核心可行,但须显式接受 3 项产品降级。** 纯算法层(谐音、查梗、看图提示词、注入格式)可近乎无损迁移;与 QQ 消息结构绑定的部分(取图、转发、历史回捞)受 QQ 官方 Bot API 限制必须重做。
|
|
6
|
+
- 工作量估算(**已按复核修正**):核心可用版本 **8~11 个工作日**;完整对齐原版 **15~22 个工作日**。
|
|
7
|
+
- 版本:v2,已根据**三轮独立复核**修正 **14 处勘误**(其中 3 处为致命级:注入落点、投递双路径、注入语义)。逐条见 §8。
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## 1. 上游插件在做什么
|
|
12
|
+
|
|
13
|
+
它在"机器人要回话的那一轮"抢在对话模型之前,把图先交给视觉模型看懂,按 **字 / 画面 / 梗 / 跟你 / 坑** 五项写成一段,再注入本轮请求。核心不是图生图,而是一次 **LLM 请求前的上下文注入**。
|
|
14
|
+
|
|
15
|
+
上游实际注册 **3 个钩子**(不是初版说的 1 个):
|
|
16
|
+
|
|
17
|
+
| 钩子 | 位置 | 作用 |
|
|
18
|
+
|---|---|---|
|
|
19
|
+
| `on_message` | `main.py:657` | 记录群历史、表情包计数 |
|
|
20
|
+
| `on_llm_request`(priority=50) | `main.py:948` | **主注入** |
|
|
21
|
+
| `on_llm_request`(LATE_PRIORITY) | `main.py:938` | 最后一步做防伪造 |
|
|
22
|
+
|
|
23
|
+
| 模块 | 文件 | LOC | 可搬性 |
|
|
24
|
+
|---|---|---|---|
|
|
25
|
+
| 看图提示词 + 结果解析 + 注入文本 | `seer.py` | 972 | ★★★ 纯文本逻辑,几乎照搬 |
|
|
26
|
+
| 谐音匹配(字面 + 读音 + 近音) | `puns.py` | 534 | ★★★ 纯算法,需换拼音数据源 |
|
|
27
|
+
| 查梗 cnmeme.wiki + 缓存 + 防注入 | `memes.py` | 882 | ★★★ 纯网络/文本逻辑,照搬 |
|
|
28
|
+
| 插件主流程、取图、配额、面板 | `main.py` | 2031 | ★ 深度绑定 AstrBot/OneBot |
|
|
29
|
+
| 配置项 | `_conf_schema.json` | 37 项 | ★★ 可映射到本仓库 settings |
|
|
30
|
+
|
|
31
|
+
**关键观察**:三个可搬模块合计 **103,605 字节**源码(seer 42,534 / puns 19,840 / memes 41,231),import 层**零 AstrBot 依赖**(上游 `requirements.txt` 仅一行 `pypinyin`,且 `puns.py:178-200` 有未装时的降级分支)。
|
|
32
|
+
|
|
33
|
+
其中可迁移的**提示词文本约 4KB**(`build_prompt` ≈1.5KB + `deep_rules` ≈1.3KB + 其余),谐音**词表约 3KB**。
|
|
34
|
+
|
|
35
|
+
> ⚠️ 两处修正:初版称"约 10KB 提示词",AST 实测约 **4KB 提示词 + 3KB 词表**(初版高估约 2.5 倍);但初版又忽略了"约 100KB 源码"这一事实,两个错误方向相反、恰好抵消了对工作量的误导,故工期结论不受此项影响。
|
|
36
|
+
|
|
37
|
+
> ⚠️ **可搬性要拆开看**:`memes.py` 并非全可搬——`:311-348` 实现了 AstrBot 网页搜索耦合(`WEB_TOOLS` 9 个内置工具名、`WEB_KEYS`、`web_status` 读 `provider_settings`)。应拆为:**cnmeme 路 ★★★ 可搬 / 网页搜索路 ★ 直接砍**(上游 `meme_search` 默认已关)。
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## 2. 目标侧现有能力(本仓库已具备大半底座)
|
|
42
|
+
|
|
43
|
+
| 上游需求 | dsh-qqbot-buddy v2 现状 | 位置 |
|
|
44
|
+
|---|---|---|
|
|
45
|
+
| 多模态旁路调用 | **已有** `createOneShot().generate({prompt, images})` | [lib/host/llm.js](../lib/host/llm.js) |
|
|
46
|
+
| 图片 → DSH 附件 | **已有** `saveImage` + `ImageAttachmentRef` | `ctx.get('attachments')` |
|
|
47
|
+
| 视觉工具 | **已有** `qqbot_describe_image`(含 SSRF 白名单) | [lib/tools/vision.js](../lib/tools/vision.js) |
|
|
48
|
+
| 每轮正文组装(注入落点) | **已有** `assembleAgentBody()` | [lib/qq/inbound.js:222](../lib/qq/inbound.js#L222) |
|
|
49
|
+
| 群历史缓冲 | **已有** `historyBuffer` 中间件 | [lib/qq/middleware.js](../lib/qq/middleware.js) |
|
|
50
|
+
| 引用消息解析 | **已有** `quoteRef` → `state.quote` | SDK 中间件 |
|
|
51
|
+
| 表情包存档 | **已有** `stickers` store + 控制台页 | [lib/core/stickers/store.js](../lib/core/stickers/store.js) |
|
|
52
|
+
| 设置项表单 | **已有** schema 驱动(**仅表单**) | [lib/core/config/schema.js](../lib/core/config/schema.js) |
|
|
53
|
+
| 控制台面板/统计页 | **需手写**(非 schema 生成) | 参照 `console/api/stickers.js` + `web/src/pages/StickersPage.tsx` |
|
|
54
|
+
| 测试基建 | **已有** `node --test`,437 项全绿 | `test/` |
|
|
55
|
+
|
|
56
|
+
> 🔴 **初版注入点是错的,已修正。** 初版建议在 `inbound.js:311` 与 `:392` 之间插入注入——**这会污染长期记忆**。
|
|
57
|
+
>
|
|
58
|
+
> 原因:`inbound.js:347` 有 `appendTranscript(record, '用户: ' + body)`,它在 body 组装**之后**执行,把 body **当作"用户原话"**写入转录缓冲,最终交给记忆提炼(`core/memory/collect.js:148`)。若在 311 之后注入,看图结果会被当成用户自己说的话存进长期记忆。
|
|
59
|
+
>
|
|
60
|
+
> **正确落点**:必须放进 `assembleAgentBody()` **内部**(`inbound.js:222-277`),在返回前拼接。这样注入内容只进本轮 prompt、不进转录。
|
|
61
|
+
|
|
62
|
+
### 2.0 架构级差异:上游是「结构化分段」,DSH 是「单字符串」
|
|
63
|
+
|
|
64
|
+
这是移植中**最本质的差异**,初版完全没意识到。
|
|
65
|
+
|
|
66
|
+
上游注入靠的是 AstrBot 的 **`req.extra_user_content_parts`**——一个 `TextPart` **列表**(`main.py:1159` 追加"看到了什么"、`:1168` 追加"这一轮的图"、`:1467` 追加"查到的梗")。其中 `_part(text, temp=lambda: TextPart(text).mark_as_temp())`(`main.py:145-149`)用 `mark_as_temp()` 实现**"只给这一轮看、不写进聊天记录"**——这是框架原生语义,插件不用自己管。
|
|
67
|
+
|
|
68
|
+
DSH 侧 `assembleAgentBody`(`inbound.js:276`)返回的是**一整串纯文本**,没有分段结构,也没有 temp 语义。因此:
|
|
69
|
+
|
|
70
|
+
- 上游"两段注入、一段常驻一段临时"**必须自行实现**;
|
|
71
|
+
- "只给本轮"的保证**从框架语义降级为拼接位置约定**——只要位置放对(在 `appendTranscript` 之前、且不入转录),效果等价,但更脆弱,需测试守护。
|
|
72
|
+
|
|
73
|
+
**两档语义的具体分工**(这是上游的设计核心,初版完全没建模):
|
|
74
|
+
|
|
75
|
+
| 段落 | 上游 | temp | 语义 | DSH 侧需要 |
|
|
76
|
+
|---|---|---|---|---|
|
|
77
|
+
| 看到了什么 | `main.py:1159` | `False` | **常驻**,记进聊天记录,以后聊起这张图还记得(`seer.py:251` 有意如此) | 需写入会话历史,不能只拼进 body |
|
|
78
|
+
| 这一轮的图 | `main.py:1168` | `True` | 只给本轮:梗点、是否在说你、有没有坑 | 只拼 body,不入历史 |
|
|
79
|
+
| 查到的梗 | `main.py:1467` | `True` | 只给本轮 | 只拼 body,不入历史 |
|
|
80
|
+
|
|
81
|
+
**跨轮去重**:上游在 `main.py:1004-1008` 维护"哪些图本轮已处理",避免同一张图重复注入。DSH 侧没有等价物,需自建。
|
|
82
|
+
|
|
83
|
+
> 由于 DSH 是单字符串,**"常驻 vs 临时"无法靠拼接实现**——常驻段必须真正写进会话历史(或按对话+发图人分存后每轮按需回放),这是比"拼个字符串"重得多的实现工作。
|
|
84
|
+
|
|
85
|
+
> ⚠️ 修正:初版说"比 AstrBot 改 `req.prompt` 的写法更干净"是**错的**。上游从没改 `req.prompt`——它用 `extra_user_content_parts` 追加结构化段,只在防伪造时**读取改写** `req.prompt`/`req.system_prompt`(`main.py:916-920`)。准确说法是:**两边都得自己拼,但 DSH 少了 temp 语义这层保护**。
|
|
86
|
+
|
|
87
|
+
### 2.1 必须同时覆盖两条投递路径
|
|
88
|
+
|
|
89
|
+
默认配置 `reply.mode = 'adaptive'`([schema.js:38](../lib/core/config/schema.js#L38)),此时消息**不走** `inbound.js`,而是由 [adaptive.js:362](../lib/qq/adaptive.js#L362) 调用 `assembleBody`(默认值即 `assembleAgentBody`,`adaptive.js:169`)后经 `:390` 的 `deliverInbound` 投递。
|
|
90
|
+
|
|
91
|
+
**只改 `inbound.js` 会让注入在默认模式下完全失效。** 幸运的是两处共用同一组装函数,只要把逻辑写在 `assembleAgentBody` 内部即可天然覆盖两条路径——但注意 `adaptive` 调用时**未传 `message` 之外的部分上下文**,需确认 `lastState` 里图相关字段可用。
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## 3. 逐能力判定
|
|
96
|
+
|
|
97
|
+
| 能力 | 判定 | 说明与改法 |
|
|
98
|
+
|---|---|---|
|
|
99
|
+
| 看图五要素(字/画面/梗/跟你/坑) | ✅ 直接搬 | 提示词模板原样迁成 JS 常量 |
|
|
100
|
+
| 「看到了什么」+「这一轮的图」两段注入 | ✅ 直接搬 | 接到 `assembleAgentBody` 输出前 |
|
|
101
|
+
| 防伪造(手打 `[看图看懂]` 标记) | ✅ 直接搬 | 关键在于:本仓库的 body 里用户文本与系统文本混在**同一个字符串**,必须给注入段加不可伪造边界 |
|
|
102
|
+
| 按"对话+发图人"分存看图结果 | ✅ 直接搬 | 用 SQLite 表,比上游 JSON 更稳 |
|
|
103
|
+
| 谐音梗 | ⚠️ 需换数据源 | 上游依赖 Python `pypinyin`;Node 侧改用 `pinyin-pro`(MIT,950KB,零依赖,支持多音字),117 条词表照搬 |
|
|
104
|
+
| 查梗 cnmeme.wiki | ✅ 直接搬 | **已实测接口可用**:`GET https://cnmeme.wiki/api/v1/public/memes?q=<词>&limit=5` 返回 200 与词条 JSON |
|
|
105
|
+
| 配额 / 限流 / 退避 / 缓存 TTL | ✅ 直接搬 | 逻辑纯计算 |
|
|
106
|
+
| 表情包词典 | ⚠️ 需融合 | 本仓库已有 stickers 表,应**扩列**而非新建,避免两套并行 |
|
|
107
|
+
| 一条消息几张图按位置标"第几张" | ✅ 可搬 | QQ 官方 API 单条消息图片顺序稳定 |
|
|
108
|
+
| 引用消息里的图 | ✅ 可搬 | `state.quote.attachments` 已含 URL |
|
|
109
|
+
| 「上面那张图」回捞群内最近一张 | ⚠️ 退化为缓存近似 | **QQ 官方 Bot API 无拉取群历史消息的接口**(见 3.1)。但 `historyBuffer` 已缓存未 @ 的消息,扩字段后可覆盖"机器人在场的最近窗口",做不到上游那种任意 10 分钟回捞 |
|
|
110
|
+
| 先发图后 @(2 分钟内补看) | ⚠️ 需新建下载链路 | **不是"加个字段"这么简单**:SDK 的 `HistoryEntry` 无 attachments 字段,且 `inbound.js:372` 的图片下载发生在门控**之后**。需在门控前自建旁路存储。见 §3.2 |
|
|
111
|
+
| 转发聊天记录里的图 | ❌ 不可搬(协议级) | **不只是缺 API**,官方协议本身无 forward 消息类型(MsgType 仅 0/2/3/7,无转发路由)。上游 `main.py:843-870` 走 OneBot `call_action get_forward_msg`。**不要写成"等官方开接口"** |
|
|
112
|
+
| 一条消息几张图"第几张" | ⚠️ 未验证 | SDK 只给 `attachments[]` 数组序,无位置字段。初版称"顺序稳定"**缺乏出处** |
|
|
113
|
+
| 消息里的 QQ 商城表情 | ❌ 不可搬 | 官方 Bot 协议无商城表情体系 |
|
|
114
|
+
| 群名片/昵称识别 | ⚠️ 变化 | 官方 API 只给 `senderName` |
|
|
115
|
+
|
|
116
|
+
> 上表 ❌ 的 3 项,正是"OneBot/NapCat 私有协议"与"QQ 官方开放平台 Bot API"的差异所致,不是移植工作量的产物——**任何基于官方 API 的机器人都不可能做到**。
|
|
117
|
+
|
|
118
|
+
### 3.1 关于"无历史消息接口"的确凿证据
|
|
119
|
+
|
|
120
|
+
已对 `node_modules/@tencent-connect/qqbot-nodejs/dist` 做穷尽检索:
|
|
121
|
+
|
|
122
|
+
- 全部 API 路径只有 `/v2/{groups|users}/{id}/messages`、`/v2/users/{openid}/stream_messages`、`/v2/{groups|users}/{id}/files`、`upload_prepare`、`upload_part_finish` —— **全部是"发送/上传",没有一个"读取"端点**。
|
|
123
|
+
- `MessageApi` 的公开方法只有:`sendMessage` / `sendProactiveMessage` / `sendChannelMessage` / `sendDmMessage` / `sendInputNotify` / `acknowledgeInteraction` / `recallMessage` / `getGatewayUrl` / `sendRaw` —— 无任何 list/get history。
|
|
124
|
+
- 检索 forward / history 关键字,命中的全部是自建的 `historyBuffer` 中间件(缓存**我们收到的**消息),而非向 QQ 拉取。
|
|
125
|
+
|
|
126
|
+
**推论**:插件里"看群里 10 分钟内最近一张图"这类能力,在官方 API 下只能退化为**基于我们自己缓存的图片索引**做近似——机器人没在场的时段不可知。这必须在 README 中如实声明。
|
|
127
|
+
|
|
128
|
+
### 3.2 替代方案(可挽回一半体验)
|
|
129
|
+
|
|
130
|
+
虽然拉不到历史,但 `historyBuffer` 中间件([lib/qq/middleware.js](../lib/qq/middleware.js),`limit` 默认 20,`recordOnSkip: true`)已经在缓存**未 @ 机器人**的群消息。扩展它的 `HistoryEntry`(当前字段:senderId / senderName / content / timestamp / messageId)加一个 `images` 字段,就能支撑:
|
|
131
|
+
|
|
132
|
+
- **先发图后 @(2 分钟内)**:✅ 可完整实现
|
|
133
|
+
- **「上面那张图」**:⚠️ 仅限机器人已缓存的窗口内可近似,不能像上游那样回捞任意 10 分钟历史
|
|
134
|
+
|
|
135
|
+
> ⚠️ **修正**:初版称"加一个 `images` 字段即可,约 1 天"是**低估**。实际需在频率门控之前新建一条图片下载 + 旁路存储链路(门控会丢弃未 @ 消息,而下载发生在门控之后),独立成项约 **+2~3 天**。
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## 4. 推荐架构
|
|
140
|
+
|
|
141
|
+
```
|
|
142
|
+
lib/qq/seememe/
|
|
143
|
+
index.js // 门面:decorate({ scope, peerId, msg, state, record }) → { block, hints }
|
|
144
|
+
caption.js // 看图提示词与解析(移植 seer.py)
|
|
145
|
+
puns.js // 谐音(移植 puns.py,pinyin-pro 替代 pypinyin)
|
|
146
|
+
lookup.js // 查梗 + 缓存 + 防注入(移植 memes.py)
|
|
147
|
+
store.js // SQLite:看图结果 / 表情包词条 / 查梗缓存
|
|
148
|
+
quota.js // 每小时/每日配额、时区分天
|
|
149
|
+
safety.js // 防伪造标记、注入边界
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
接入改动(**初版漏算一半,已补全**):
|
|
153
|
+
|
|
154
|
+
| # | 文件 | 改动 |
|
|
155
|
+
|---|---|---|
|
|
156
|
+
| 1 | `lib/qq/inbound.js:222-277` | **在 `assembleAgentBody` 内部**注入(不可放在其外,见 §2) |
|
|
157
|
+
| 2 | `lib/qq/adaptive.js:362` | 确认默认 adaptive 模式走同一组装器;覆盖两处调用 |
|
|
158
|
+
| 3 | `lib/core/config/schema.js` | 新增 `seememe` 配置段;**补 `vision` 段缺的"看图用哪个模型"**(现仅 3 项内联配置,无模型选择) |
|
|
159
|
+
| 4 | `lib/core/migrations.js` | 新增 **version 5**(现有已到 v4::13/:203/:218/:225)。查梗缓存**复用 `job_state`**(:206-213),词条扩 `stickers` 列,可少建表 |
|
|
160
|
+
| 5 | `lib/core/stickers/store.js` | 扩列;**注意 `stickerDayKey`(:36-37)用进程本地时区,无 Asia/Shanghai 语义,需新写时区分天** |
|
|
161
|
+
| 6 | `lib/index.js:204-206/238` | store 装配 |
|
|
162
|
+
| 7 | `lib/qq/settings.js:100-107` | 设置映射 |
|
|
163
|
+
| 8 | `lib/console/api/` + `web/src/pages/` | 面板需**手写**(非 schema 生成) |
|
|
164
|
+
| 9 | `package.json` | 新增 `pinyin-pro` |
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## 5. 分期计划
|
|
169
|
+
|
|
170
|
+
| 阶段 | 内容 | 估时 |
|
|
171
|
+
|---|---|---|
|
|
172
|
+
| P0 | 目录骨架 + 配置项 + 数据表 + `pinyin-pro` 接入 | 1 天 |
|
|
173
|
+
| P1 | 看图:提示词移植、`oneShot` 多模态调用、结果解析、body 注入、防伪造 | 2~3 天 |
|
|
174
|
+
| P2 | 谐音(词表 + 读音 + 近音) | 1 天 |
|
|
175
|
+
| P3 | 查梗(cnmeme.wiki + 缓存 TTL + 限流退避 + 防注入清洗) | 2 天 |
|
|
176
|
+
| P4 | 配额/时区分天/按对话分存(**时区需自写**) | 2 天 |
|
|
177
|
+
| P4b | 近期图索引(门控前下载 + 旁路存储,**独立立项**) | 2~3 天 |
|
|
178
|
+
| P5 | 表情包词典与现有 stickers 融合 | 2~3 天 |
|
|
179
|
+
| P6 | 控制台面板(统计 + 试一张图) | 2~3 天 |
|
|
180
|
+
| P7 | 测试(单测 + 假模型 e2e) | 2 天 |
|
|
181
|
+
|
|
182
|
+
---
|
|
183
|
+
|
|
184
|
+
## 6. 风险清单
|
|
185
|
+
|
|
186
|
+
1. **QQ 官方 API 天花板**:历史回捞、合并转发、商城表情三项做不了,需在 README 里如实说明,别照抄上游的"能看"承诺。另:上游所谓"商城表情"并非专用 API,而是靠原始消息段透传 `mface`(`main.py:460-474`),官方协议下无此消息段。
|
|
187
|
+
2. **成本风险(初版方向错,已修正)**:真正的问题**不是**"单次双调"——图片内联有模态门控(`inline-image.js:213-227`,仅当 `inputModalities` 含 `image` 时才内联),文本模型根本不会内联。真正贵的是 `inline-image.js:15-16` 明写的设计:**图片会留在会话历史里,每轮都随请求发送**——历史图被反复计费。成本开关应针对"历史图片重复发送",而非"模型看两遍"。
|
|
188
|
+
另:若 seememe 自行 `saveImage`,应与内联**共享同一 attachment**(复用 `imageHostPath`),否则同一张图存两份字节。
|
|
189
|
+
3. **注入文本伪造面(比初版认识更严重)**:不只 `[看图看懂]` 标记,现有 body 已有可伪造的固定边界——`wrapWithHistory` 的 `[Chat history begins]`/`[Current message]`(`inbound.js:207-212`)、`[Quoted message begins]`(:165),且 `:250` 的群名片 `senderName` 由用户可控。**这些现有标记本身就没有转义**,seememe 的注入边界必须一并纳入统一转义方案。
|
|
190
|
+
4. **隐私**:cnmeme.wiki 会把"像梗的词"发出去,可能是人名。必须保留上游的保守规则(电话/网址/聊天行不查)并默认只在本轮生效。
|
|
191
|
+
4b. **查梗是三级链路,不是单接口**:缓存 → cnmeme.wiki → **AstrBot 网页搜索**(`memes.py:311-348` + `main.py:1310`)。第三级强耦合 AstrBot 的 `provider_settings` 与 9 个内置搜索工具,**应直接砍掉**(上游 `meme_search` 默认就是关的)。DSH 已有 `web_fetch`/`web_search`,若要保留需重新适配,不建议放进首版。
|
|
192
|
+
4c. **双看默认开启(成本放大器)**:上游 `also_when_main_sees` **默认 True**(`main.py:1027-1035` 默认不跳过),叠加 `max_images=3` 与转发 `forward_max=6`,**最坏一轮 9 次视觉调用**。上游自己都打 warn 提示"看两遍花两份钱"(`main.py:1017-1026`)。DSH 版应**默认关闭**"主模型能看图时也另看一遍",并单列成本项。
|
|
193
|
+
5. **延迟**:回话前等看图(上游默认 30s)会拖慢响应。建议本仓库默认"超时即降级、后台补看下一轮"。
|
|
194
|
+
|
|
195
|
+
## 7. 结论
|
|
196
|
+
|
|
197
|
+
**核心可行,但须显式接受 3 项产品降级**(不出在工程量,出在 QQ 官方协议):
|
|
198
|
+
|
|
199
|
+
1. 合并转发里的图 —— 协议无此消息类型,**永久不可实现**
|
|
200
|
+
2. 群内历史图回捞 —— 无读取接口,只能退化为"机器人在场期间的本地缓存"
|
|
201
|
+
3. 商城表情 —— 协议无此体系
|
|
202
|
+
|
|
203
|
+
上游最有价值的资产是约 **100KB 源码**中与框架无关的纯文本规则(提示词模板、117 条谐音词表、查梗清洗算法),可近乎无损迁移(上游 `requirements.txt` 仅一行 `pypinyin`、且 `puns.py:178-200` 有降级分支,即为佐证)。DSH 侧的多模态、附件、SQLite、控制台基建齐备。
|
|
204
|
+
|
|
205
|
+
**但初版说成"完全可行、5~8 天"过于乐观**——注入落点、投递双路径、迁移版本、控制台手写、时区语义、附件共享这六处都会真实加时间。修正后:**核心版 8~11 天,完整版 15~22 天**。
|
|
206
|
+
|
|
207
|
+
---
|
|
208
|
+
|
|
209
|
+
## 8. 复核勘误记录
|
|
210
|
+
|
|
211
|
+
本报告经**三轮独立复核**(上游源码 / 目标仓库 / DSH+外部 API),以下错误均已被源码证实并回源核实,不是推测:
|
|
212
|
+
|
|
213
|
+
| # | 初版说法 | 事实(证据) | 影响 |
|
|
214
|
+
|---|---|---|---|
|
|
215
|
+
| 1 | 注入点在 `inbound.js:311` 与 `:392` 之间 | `:347` 的 `appendTranscript` 在其后执行,会把注入内容当**用户原话**喂给记忆提炼 | 🔴 致命:污染长期记忆 |
|
|
216
|
+
| 2 | 只改 `inbound.js` | 默认 `reply.mode=adaptive` 走 `adaptive.js:362` | 🔴 致命:默认模式下注入失效 |
|
|
217
|
+
| 3 | "比 AstrBot 改 `req.prompt` 更干净" | 上游用 `extra_user_content_parts` 结构化分段 + `mark_as_temp()`(`main.py:145-149/1159/1168`),从不写 `req.prompt` | 🔴 架构判断错:DSH 反而**少了 temp 语义** |
|
|
218
|
+
| 4 | 新增 v2 迁移 | 现有已到 v4(`migrations.js:13/203/218/225`),应为 **v5** | 迁移冲突 |
|
|
219
|
+
| 5 | "改 5 个文件" | 至少 9 处(含 `index.js`、`settings.js`、控制台前后端) | 低估 |
|
|
220
|
+
| 6 | 控制台 schema 驱动 | 仅设置表单是;**面板页需手写** | P6 低估 |
|
|
221
|
+
| 7 | 约 10KB 提示词 | AST 实测约 **4KB 提示词 + 3KB 词表**;但源码总量约 **100KB** | 两个错误方向相反,净影响小 |
|
|
222
|
+
| 8 | 双倍成本 = 模型看两遍 | 实为**历史图片每轮重发**(`inline-image.js:15-16`),且有模态门控(`:213-227`);真正放大器是 `also_when_main_sees` **默认 True** | 方向错 + 漏了成本放大器 |
|
|
223
|
+
| 9 | 配额/时区可直接搬 | `stickerDayKey`(`stickers/store.js:36-37`)用本地时区,无 Asia/Shanghai 语义 | 漏项 |
|
|
224
|
+
| 10 | "单条消息图片顺序稳定" | SDK 无位置字段,**未验证** | 不能当事实写 |
|
|
225
|
+
| 11 | `memes.py` 全可搬 ★★★ | `:311-348` 耦合 AstrBot 网页搜索,应拆:cnmeme 路 ★★★ / 搜索路 ★ 砍掉 | 工期 |
|
|
226
|
+
| 12 | "模块只绑定 main.py" | import 层零依赖成立,但 `memes.py` 有 AstrBot 耦合 | 不精确 |
|
|
227
|
+
| 13 | deliver 在 `:392` | 真正的 `deliver(...)` 在 `:393` | off-by-one |
|
|
228
|
+
| 14 | 上游只有 1 个钩子 | 实为 3 个(`main.py:657/948/938`) | 不精确 |
|
|
229
|
+
|
|
230
|
+
### 复核后的判断分歧
|
|
231
|
+
|
|
232
|
+
三份复核对工期给出的区间:**6~9 天 / 8~11 天**(核心版),本报告取偏保守的 **8~11 天**。对"70% 可 1:1 照搬"的估计,上游复核认为偏乐观,实际约 **50~60%**(因为注入语义、配额、日切、跨轮去重都要重写)。
|
|
233
|
+
|
|
234
|
+
### 尚存不确定性(不影响可行性结论)
|
|
235
|
+
|
|
236
|
+
- `mark_as_temp()` 的确切运行时语义:复核机未装 AstrBot,仅依据调用形态推断。**DSH 侧不依赖它**,需自行实现等价行为,故不影响移植。
|
|
237
|
+
- 消息内图片顺序:SDK 未暴露位置字段,需在实现时按 `attachments[]` 数组序并实测确认。
|
|
238
|
+
|
|
@@ -0,0 +1,254 @@
|
|
|
1
|
+
# 模型中心(LLM / 视觉 / 语音 TTS / 插槽)设计与实现契约
|
|
2
|
+
|
|
3
|
+
> 状态:已实现并通过独立验收(2026-11;本文件同时是多人协作的接口契约,实现完成后作为功能设计文档保留)。
|
|
4
|
+
> 关联设置:`lib/core/config/schema.js` 的 model / vision / voice 分节;数据表 `tts_providers`(migration v6)。
|
|
5
|
+
|
|
6
|
+
## 1. 目标
|
|
7
|
+
|
|
8
|
+
1. 控制台新增「模型」页(路由 `/models`),用 **tab** 组织同一类配置:
|
|
9
|
+
- `LLM`:对话模型路由(provider / model / 推理强度 / preset)
|
|
10
|
+
- `视觉`:视觉模型来源(跟随 LLM 自带视觉 = 当前内联图片;或独立更精细视觉模型)
|
|
11
|
+
- `语音(TTS)`:TTS 供应商配置面板(全局)+ 当前配置档的供应商/音色/风格选择
|
|
12
|
+
- `更多类型`:模型类型插槽(图像生成 / ASR / 向量检索…,预留扩展点)
|
|
13
|
+
2. TTS 支持多种供应商:
|
|
14
|
+
- `edge` 微软 Edge 语音(免 Key,内置 WebSocket 实现)
|
|
15
|
+
- `mimo` 小米 MiMo-V2.5-TTS(内置音色 / voicedesign / voiceclone)
|
|
16
|
+
- `bailian` 阿里云百炼 Qwen-TTS(qwen3-tts-flash / qwen-tts)
|
|
17
|
+
- `openai` OpenAI 兼容 `/audio/speech`
|
|
18
|
+
- `custom` 自定义 HTTP 接口(URL/Header/Body 模板 + 三种响应类型)
|
|
19
|
+
- `command` 本地命令行模型(piper / sherpa-onnx / edge-tts CLI 等)
|
|
20
|
+
3. 模型可通过工具 `qqbot_speak` 把文字合成语音并发到当前 QQ 会话;能力开关 `tools.capabilities.voice` 默认关。
|
|
21
|
+
4. 后续新增模型类型只改 `lib/core/model-slots.js` + settings schema,控制台自动多出 tab(前端不写死类型清单)。
|
|
22
|
+
|
|
23
|
+
## 2. 配置层级
|
|
24
|
+
|
|
25
|
+
- **全局**:TTS 供应商列表(表 `tts_providers`)+ `voice.defaultProvider`(global scope 设置项)。
|
|
26
|
+
- **配置档**:`voice.*`(是否启用、选哪个供应商、音色/风格/语速/字数上限)与 `vision.*`、`model.*`。
|
|
27
|
+
- 生效顺序沿用既有层级:defaults → global → bot → profile(binding 匹配后的配置档)。
|
|
28
|
+
|
|
29
|
+
新增设置项(`core/config/schema.js`):
|
|
30
|
+
|
|
31
|
+
| key | scope | type | default |
|
|
32
|
+
| --- | --- | --- | --- |
|
|
33
|
+
| `vision.mode` | profile | enum `llm`/`dedicated` | `llm` |
|
|
34
|
+
| `vision.provider` | profile | string | `''` |
|
|
35
|
+
| `vision.model` | profile | string | `''` |
|
|
36
|
+
| `vision.maxTokens` | profile | number | 4096 |
|
|
37
|
+
| `voice.enabled` | profile | boolean | false |
|
|
38
|
+
| `voice.provider` | profile | string | `''` |
|
|
39
|
+
| `voice.defaultProvider` | global | string | `''` |
|
|
40
|
+
| `voice.voice` | profile | string | `''` |
|
|
41
|
+
| `voice.style` | profile | string | `''` |
|
|
42
|
+
| `voice.speed` | profile | number | 1 |
|
|
43
|
+
| `voice.maxChars` | profile | number | 300 |
|
|
44
|
+
|
|
45
|
+
schema item 新增可选元数据 `optionsFrom`:`llmProviders` | `llmModels` | `ttsProviders`,
|
|
46
|
+
`schemaPayload()` 会原样透出,控制台 `SchemaForm` 据此动态拉取下拉候选。
|
|
47
|
+
|
|
48
|
+
> 实现补充(独立验收时注明):除上表外,视觉分节还落地了 `vision.inlineImages` / `vision.inlineMaxImages` /
|
|
49
|
+
> `vision.inlineMaxBytes` 三个内联图片裁剪设置项(`lib/core/config/schema.js`),用于「跟随 LLM」模式;
|
|
50
|
+
> `voice.*`、`model.*` 与上表一致。
|
|
51
|
+
|
|
52
|
+
## 3. 数据表
|
|
53
|
+
|
|
54
|
+
migration v6(已写入 `lib/core/migrations.js`):
|
|
55
|
+
|
|
56
|
+
```sql
|
|
57
|
+
CREATE TABLE tts_providers (
|
|
58
|
+
id TEXT PRIMARY KEY, name TEXT NOT NULL, kind TEXT NOT NULL,
|
|
59
|
+
enabled INTEGER NOT NULL DEFAULT 1, config TEXT NOT NULL DEFAULT '{}',
|
|
60
|
+
secret TEXT NOT NULL DEFAULT '', created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL
|
|
61
|
+
);
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
- `config` 是 **非敏感** JSON(字段由 `core/tts/providers.js` 的 kind 元数据约束)。
|
|
65
|
+
- `secret` 只写不读:读接口只返回 `hasSecret`;PATCH 时 secret 缺省/空串 = 保留原值。
|
|
66
|
+
- id 生成:`tts_` + 12 位 hex。
|
|
67
|
+
|
|
68
|
+
## 4. 供应商元数据(`lib/core/tts/providers.js`,已完成)
|
|
69
|
+
|
|
70
|
+
`TTS_KINDS[kind]`:
|
|
71
|
+
|
|
72
|
+
```js
|
|
73
|
+
{
|
|
74
|
+
id, label, short, desc,
|
|
75
|
+
needsSecret, secretLabel, secretPlaceholder, secretHelp,
|
|
76
|
+
defaultConfig, // 新建预填,同时是配置默认值
|
|
77
|
+
models: [{value,label}],// select 字段 optionsFrom:'models'
|
|
78
|
+
voices: [{value,label}],// select 字段 optionsFrom:'voices'
|
|
79
|
+
fields: [{ key,label,type:'text'|'textarea'|'select'|'number'|'json',
|
|
80
|
+
options?/optionsFrom?:'models'|'voices', required?, placeholder?, help?,
|
|
81
|
+
min?, max?, step?, maxLength? }],
|
|
82
|
+
outputFormat: 'mp3' | 'wav',
|
|
83
|
+
maxCharsPerRequest: number,
|
|
84
|
+
timeoutMs: number,
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
已导出:`TTS_KINDS`、`TTS_KIND_LIST`、`kindOf`、`publicKinds()`、`defaultConfigFor`、
|
|
89
|
+
`normalizeProviderInput(input,{existing})`、`providerView(row)`、`fieldOptions`。
|
|
90
|
+
**供应商实现只允许用这些导出,不要在别处重复声明 kind。**
|
|
91
|
+
|
|
92
|
+
## 5. Provider store(`lib/core/tts/store.js`,已实现)
|
|
93
|
+
|
|
94
|
+
```js
|
|
95
|
+
createTtsProviderStore({ db, now = Date.now })
|
|
96
|
+
list() // → 内部行(含 secret),按 created_at ASC;engine 用
|
|
97
|
+
listPublic() // → providerView[]
|
|
98
|
+
get(id) // → 内部行 | null
|
|
99
|
+
getPublic(id) // → providerView | null
|
|
100
|
+
save(input) // 新增(无 id)/更新(有 id);secret 空串=保留;→ providerView
|
|
101
|
+
remove(id) // → boolean
|
|
102
|
+
firstEnabled() // → 内部行 | null(默认供应商回退用)
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
校验/归一化全部走 `normalizeProviderInput`;错误信息可直接给用户(中文)。
|
|
106
|
+
|
|
107
|
+
## 6. TTS 引擎(`lib/core/tts/index.js`,已实现)
|
|
108
|
+
|
|
109
|
+
```js
|
|
110
|
+
createTtsEngine({ db, dataDir, logger })
|
|
111
|
+
kinds() // → publicKinds()
|
|
112
|
+
listProviders() // → providerView[]
|
|
113
|
+
getProvider(id) // → providerView | null
|
|
114
|
+
saveProvider(input) // → providerView
|
|
115
|
+
deleteProvider(id) // → boolean
|
|
116
|
+
resolveSelection({ settings }) // 纯查询:profile 设置 → { provider, providerId, voice, style, speed, maxChars } | null
|
|
117
|
+
async synthesize({
|
|
118
|
+
text, providerId?, voice?, style?, speed?, maxChars?,
|
|
119
|
+
settings?, fileNameHint?, signal?, outDir?,
|
|
120
|
+
}) // → { ok:true, providerId, kind, model, voice, format, filePath, bytes, ms, segments, truncated, text }
|
|
121
|
+
async synthesizeForSettings({ text, settings, ... }) // synthesize 的便捷封装(内部调 resolveSelection)
|
|
122
|
+
async test({ providerId, text? }) // → { ok:true, providerId, kind, model, voice, format, bytes, ms, audioBase64, mimeType }
|
|
123
|
+
audioDir() // → <dataDir>/tts-media(保证存在)
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
- 输出文件命名:`<audioDir>/<yyyyMMdd-HHmmss>-<rand>.<format>`;文件落盘后交给工具发送。
|
|
127
|
+
- 文本分段:按句号/换行切,每段 ≤ kind.maxCharsPerRequest;多段合成后 **拼接**:
|
|
128
|
+
- `wav`:解析各段 PCM data 块后重写标准 WAV 头;
|
|
129
|
+
- `mp3`:按字节顺序拼接(顺序播放可用);
|
|
130
|
+
- 如需转码/强一致,可选调用 `ffmpeg`(存在则用,不存在降级为字节拼接,不报错)。
|
|
131
|
+
- `text` 按 `maxChars`(默认 300,来自 `voice.maxChars`)截断,返回 `truncated:true`。
|
|
132
|
+
- 错误统一 `Error`,消息中文可读,带 `.code`(如 `TTS_PROVIDER_NOT_FOUND`、`TTS_DISABLED`、`TTS_CONFIG`、`TTS_UPSTREAM`、`TTS_TIMEOUT`、`TTS_EMPTY_TEXT`)。
|
|
133
|
+
- 网络:全局 `fetch`,超时用 `AbortSignal.timeout`(与调用方 signal 合并);只允许 http(s)。测试禁止真实联网。
|
|
134
|
+
|
|
135
|
+
### 适配器目录 `lib/core/tts/adapters/`
|
|
136
|
+
|
|
137
|
+
每个文件默认导出:
|
|
138
|
+
|
|
139
|
+
```js
|
|
140
|
+
export default {
|
|
141
|
+
kind: 'mimo',
|
|
142
|
+
async synthesize({ provider, text, options, outPath, signal, logger })
|
|
143
|
+
// provider: 内部行 {id,name,kind,config,secret}; options: {voice,style,speed}
|
|
144
|
+
// outPath: 完整输出路径(扩展名已按 outputFormat 决定)
|
|
145
|
+
// → { bytes, format, model, voice, meta? }
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
- `edge.js`:Microsoft Edge TTS WebSocket 协议(`wss://speech.platform.bing.com/consumer/speech/synthesize/readaloud/edge/v1`)。
|
|
150
|
+
**实测(2026-11)**:旧版 `Sec-MS-GEC` v1(sha256(ticks+token))已被服务端 403 拒绝,必须用 v2 token
|
|
151
|
+
`<CS64>-<SHA256>`("版权声明 + ticks + token" 的 CS64/SHA256 组合,算法见 `lib/core/tts/edge-token.js`,
|
|
152
|
+
移植自 MIT 许可的 MsEdgeTTS),查询参数需要 `ConnectionId=<32 hex>`、`Sec-MS-GEC-Version=2-143.0.3650.96`;
|
|
153
|
+
握手需要 Origin/UA/Cookie(muid) 等头,因此用 `ws` 包(dependency)而不是 Node 全局 WebSocket。
|
|
154
|
+
允许被环境变量 `QQBOT_EDGE_TTS_URL` 覆盖(测试/自建代理)。协议随微软策略变动时,
|
|
155
|
+
优先改 `edge-token.js`/版本常量;若彻底失效,用户可用 `command` kind 调本机 `edge-tts` CLI 兜底。
|
|
156
|
+
- `mimo.js`:`POST {baseUrl}/chat/completions`,头 `api-key: <secret>`、`Content-Type: application/json`;
|
|
157
|
+
body `{model, messages:[{role:'user',content:style}, {role:'assistant',content:text}], audio:{format:'wav', voice}}`
|
|
158
|
+
(voiceclone 时 `audio.voice = data:<mime>;base64,<样本>`);响应 `choices[0].message.audio.data` base64。
|
|
159
|
+
- `bailian.js`:`POST {baseUrl}/services/aigc/multimodal-generation/generation`,`Authorization: Bearer <secret>`;
|
|
160
|
+
body `{model, input:{text, voice, language_type}}`;响应 `output.audio.url`(下载)或 `output.audio.data` base64。
|
|
161
|
+
- `openai.js`:`POST {baseUrl}/audio/speech`,Bearer;body `{model, input:text, voice, response_format, speed, instructions?}`;
|
|
162
|
+
响应二进制音频(按 `content-type` 嗅探实际格式,写文件时统一用 outPath 扩展名)。
|
|
163
|
+
- `custom.js`:按 provider.config 渲染 URL/Header/Body;`{{text}}/{{voice}}/{{style}}/{{speed}}` 占位
|
|
164
|
+
(URL 中 URL 编码、body 模板中 JSON 字符串转义);secret 按 secretHeader/secretPrefix 注入;
|
|
165
|
+
responseType:`audio`(读字节)|`json_base64`(按 responsePath 取值 base64)|`json_url`(按 responsePath 取 URL 下载)。
|
|
166
|
+
- `command.js`:`node:child_process` 的 `spawn('/bin/sh',['-c',cmd])`,占位符 shell 单引号转义;
|
|
167
|
+
要求命令退出码 0 且 `{{output}}` 文件存在;超时 kill。
|
|
168
|
+
|
|
169
|
+
## 7. 控制台 API(`lib/console/api/models.js`,已实现)
|
|
170
|
+
|
|
171
|
+
路由表(auth 默认开启,CSRF 由 server 统一):
|
|
172
|
+
|
|
173
|
+
| method | path | 说明 |
|
|
174
|
+
| --- | --- | --- |
|
|
175
|
+
| GET | `/api/models/slots` | `{ slots, ready, planned }` ← `core/model-slots.js slotsPayload()` |
|
|
176
|
+
| GET | `/api/models/llm` | `{ providers:[{id,name}], models:[{provider,id,name,description?,inputModalities?}], warning? }`;从 `deps.rootCtx.get('llm')` 尽力读取,失败返回空 + warning |
|
|
177
|
+
| GET | `/api/models/tts/kinds` | `{ kinds: publicKinds() }` |
|
|
178
|
+
| GET | `/api/models/tts/providers` | `{ providers: providerView[], defaultProvider }`(defaultProvider 读 global 设置) |
|
|
179
|
+
| POST | `/api/models/tts/providers` | body `{name,kind,enabled?,config?,secret?}` → providerView |
|
|
180
|
+
| PATCH | `/api/models/tts/providers/:id` | 同上;secret 空串=保留 |
|
|
181
|
+
| DELETE | `/api/models/tts/providers/:id` | `{ok:true,id}` |
|
|
182
|
+
| POST | `/api/models/tts/providers/:id/test` | body `{text?}`(默认「你好,这是一条语音合成测试。」)→ `{ok, providerId, kind, model, voice, format, bytes, ms, audioBase64, mimeType}`;audioBase64 超 4MB 时省略并返回 `tooLarge:true` |
|
|
183
|
+
|
|
184
|
+
注册进 `lib/console/api/index.js`。依赖:`deps.tts`(engine,可为 null → 501)、`deps.config`、`deps.rootCtx`。
|
|
185
|
+
`lib/index.js` 装配:`runtime.tts = createTtsEngine({ db, dataDir, logger })`,并放入 `consoleDeps.tts`。
|
|
186
|
+
|
|
187
|
+
## 8. 工具 `qqbot_speak`(`lib/tools/voice.js`,已实现)
|
|
188
|
+
|
|
189
|
+
```js
|
|
190
|
+
export const SPEAK_TOOL_NAME = 'qqbot_speak';
|
|
191
|
+
export function createVoiceTools({ tts, manager, mediaSender, getSettings, config, logger })
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
- 入参:`text`(必填)、`style`(可选,覆盖配置档风格)、`voice`(可选,覆盖音色)。
|
|
195
|
+
- 流程:`getSettings()` → `tts.synthesizeForSettings({text, settings, voice, style})` →
|
|
196
|
+
`manager.findByAgent(exec.agent).replyTarget` → `mediaSender.sendVoice(target,{localPath})` → 结构化结果
|
|
197
|
+
`{ok:true, provider, voice, format, bytes, filePath, target}`。
|
|
198
|
+
- 失败:未启用 → `语音合成未启用(配置档 → 语音(TTS))`;无供应商 → 可读中文;发送失败沿用 send 的 `deliveryUnknown` 语义(原样抛)。
|
|
199
|
+
- 能力归属:`PLUGIN_TOOL_CAPABILITIES.qqbot_speak = 'voice'`;`CAPABILITY_TOOLS.voice = []`;
|
|
200
|
+
`DEFAULT_CAPABILITIES.voice = false`;`CAPABILITY_BOUNDARIES.voice` 补一句。
|
|
201
|
+
- `lib/tools/index.js` 注册(依赖 `runtime.tts` 缺失时降级不注册并 warn)。
|
|
202
|
+
- `lib/host/tools.js buildToolGuide`:可见 `qqbot_speak` 时加一条「需要朗读/发语音时用 qqbot_speak,只适合短句」。
|
|
203
|
+
|
|
204
|
+
## 9. 视觉接线(已实现)
|
|
205
|
+
|
|
206
|
+
- `lib/tools/vision.js`:`createVisionTools({ ctx, runtime, config, getSettings, logger })`;
|
|
207
|
+
每次 execute 读 `getSettings()?.vision`,provider/model/maxTokens **无条件**优先于部署 config.vision
|
|
208
|
+
(即:显式调用 `qqbot_describe_image` 时始终用配置档指定的视觉模型;`vision.mode` 只决定「当前消息图片是否内联」,
|
|
209
|
+
`dedicated` 时内联关闭、图片交给该独立模型阅读)。
|
|
210
|
+
- `lib/qq/inline-image.js`:`resolveInlinePolicy` 增加 `vision.mode === 'dedicated'` → 不内联
|
|
211
|
+
(图片仍以路径进文本,模型用 `qqbot_describe_image` 走独立视觉模型)。
|
|
212
|
+
|
|
213
|
+
## 10. 前端(已实现)
|
|
214
|
+
|
|
215
|
+
新增 `web/src/pages/ModelsPage.tsx`(路由 `/models`,nav group 配置):
|
|
216
|
+
|
|
217
|
+
- 顶部:PageHeader + 「配置档」选择器(`useApp().profiles`,默认 activeProfile);profile 级保存走
|
|
218
|
+
`api.updateProfile(profileId, {data: pathsToPatch(dirty)})`(与 ProfilesPage 同模式)。
|
|
219
|
+
- Tabs 数据来自 `GET /api/models/slots`:ready → LLM / 视觉 / 语音 tab;planned → 「更多类型」tab(插槽卡片 + 扩展点说明)。
|
|
220
|
+
- LLM tab:`SchemaForm sectionId="model"`(带动态 provider/model 下拉)+ 保存栏 + 说明卡「供应商由宿主管控」。
|
|
221
|
+
- 视觉 tab:`SchemaForm sectionId="vision"` + 两种模式的说明卡(跟随 LLM / 独立模型)+ 保存栏。
|
|
222
|
+
- 语音 tab:
|
|
223
|
+
- 配置面板(全局):「TTS 供应商」卡片列表(名称/kind/模型/音色/hasSecret/启用状态)+ 新增/编辑/删除/试听;
|
|
224
|
+
表单由 `GET /api/models/tts/kinds` 的 `fields` 通用渲染(Drawer),secret 字段单独输入且留空=保留;
|
|
225
|
+
试听调 `POST .../test`,用返回 base64 播放 `<audio>` 并显示 bytes/ms。
|
|
226
|
+
- 当前配置档选择:`SchemaForm sectionId="voice"` + 保存栏;空态提示先去全局添加供应商。
|
|
227
|
+
- 更多类型 tab:planned slots 卡片(label/desc/extend)。
|
|
228
|
+
- `SchemaForm`:支持 `optionsFrom`(ttsProviders / llmProviders / llmModels),动态拉取候选;
|
|
229
|
+
拉取失败时保留当前值为一个选项(不能丢数据)。所有页面共用,改这一处即可。
|
|
230
|
+
- `web/src/api/client.ts` + `types.ts` + `normalize.ts`:加 8 个方法/类型(见 §7)。
|
|
231
|
+
- `styles.css`:复用 panel/tabs/segmented/field/btn;新增模型页局部类(provider 卡片网格、试听条)。
|
|
232
|
+
|
|
233
|
+
## 11. 测试与验证
|
|
234
|
+
|
|
235
|
+
- `npm test`(node --test);新增测试不得联网(mock 全局 fetch / WebSocket / 子进程)。
|
|
236
|
+
- 新增:`test/tts-providers.test.js`(元数据/校验/脱敏)、`test/tts-store.test.js`、`test/tts-engine.test.js`、
|
|
237
|
+
`test/tts-adapters.test.js`(4 个 HTTP kind + custom 三种响应;edge 用本地 WebSocket 替身)、
|
|
238
|
+
`test/models-api.test.js`(console 路由 CRUD/test/slots/llm 容错)、`test/tools-voice.test.js`(qqbot_speak)。
|
|
239
|
+
- 既有测试注意:`test/tools-catalog.test.js` 断言 `CAPABILITY_TOOLS` 与 `DEFAULT_CAPABILITIES` key 一致,
|
|
240
|
+
新增 `voice` 需两边都加;`test/tools-factory.test.js` 会断言注册工具集合,需要加 `qqbot_speak`(voice 默认关,默认不注册;
|
|
241
|
+
开启 voice 后注册)。
|
|
242
|
+
- 前端:`npm --prefix web run typecheck`、`npm --prefix web run build`(产物提交到 `web/dist`)。
|
|
243
|
+
|
|
244
|
+
## 12. 兼容 / 安全
|
|
245
|
+
|
|
246
|
+
- 只新增一个依赖 `ws@^8.21.0`:Edge TTS 握手需要自定义请求头(Origin/UA/Cookie muid),
|
|
247
|
+
Node 24 的全局 WebSocket 无法设置这些头;其余全部零新依赖(本地命令用 node:child_process,
|
|
248
|
+
音频拼接纯 JS,v2 token 只用 node:crypto)。
|
|
249
|
+
- ws 在 **Edge 首次合成时才懒加载**:即使某个部署环境没有装到 ws(例如 `--local` 复制安装且
|
|
250
|
+
profile 依赖未 hoist),TTS 引擎照常装配、其余 5 类供应商照常可用,只有 Edge 供应商在调用时
|
|
251
|
+
返回可读的「需要重装插件 / 改用其他供应商」错误;不会出现整个语音能力 501 的情况。
|
|
252
|
+
- 不改变既有 LLM 路由/工具策略行为;voice 默认关闭,vision 默认跟随 LLM。
|
|
253
|
+
- secret 永不出现在 GET 响应/日志/审计 detail;错误信息截断上游响应体(≤500 字符)。
|
|
254
|
+
- 自定义 HTTP / 本地命令属于管理员显式配置的能力,文档标注风险。
|