dsh-chatbot-tools 0.0.0-stage → 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 ADDED
@@ -0,0 +1,52 @@
1
+ # Changelog
2
+
3
+ 本文件记录本插件的所有重要变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/),
4
+ 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
5
+
6
+ ## [0.2.0] - 2026-11-18
7
+
8
+ 首个公开发布版本。
9
+
10
+ ### 新增
11
+
12
+ - **内容安全**:通过 `deepseekLlmApiExtensions` 注册 `safety_check`,可在设置页调
13
+ `safetyMode`(`off` / `observe` / `enforce`)与 `safetyLevel`(`high` / `low`)。
14
+ 实测发现服务端会对整个请求施加 **3 条排他约束**,每条都实现为守卫并配单元测试:
15
+ - `non-text-tool-result` —— 历史中 `tool_result` 含图片等非文本块时跳过注入;
16
+ - `defer-loading-guard` —— 请求含 `defer_loading` 工具声明时跳过注入;
17
+ - `thinking-off` / `purpose-skip` —— 非思考模式与内部辅助请求跳过注入。
18
+ - `chatbot_search`:联网搜索,返回带站点、发布时间、权威度的**结构化来源**,便于正文引用。
19
+ - `chatbot_image_search`:图片搜索(按图片找相似图片与出处)。
20
+ - `chatbot_ocr`:PDF / Word / PPT / 图片文字识别,按页返回;支持纯文本与逐页版面两种模式。
21
+ - `chatbot_upload_document`:把本地文档上传到 DeepSeek Files API,拿回 `file_id`;
22
+ 支持 `text_recognition` / `rich_layout_recognition` / `user_data` 三种用途。
23
+ - `chatbot_tts`:语音合成,落盘返回音频路径;支持音色、格式与自定义术语表 `ttsTermMap`。
24
+ - `chatbot_asr`:语音转文字。
25
+ - `chatbot_doctor`:自检凭证通道、当前生效配置与守卫状态。
26
+ - **界面集成**:助手消息下方新增「朗读」按钮(client slot
27
+ `conversation.chat.assistant-actions`);语音输入通过官方 `speechToText` 接缝注册
28
+ `deepseek-asr` 提供方,复用官方麦克风 UI。
29
+ - **拒答兜底**:`llm/stream` 拦截服务端拒答,转成可读提示而不是让适配器抛错。
30
+
31
+ ### 修复
32
+
33
+ - 行内代码在朗读时被整段丢弃 —— 改为在客户端拼装可朗读文本后再送服务端。
34
+ - 英文术语(`Markdown` 等)在中英混排时被念错 —— 引入 `ttsTermMap` 术语表;
35
+ 短键(≤2 字符 ASCII,如 `AI`、`Go`)改用整词匹配,避免撞进 `OPENAI`、`Golang`。
36
+
37
+ ### 文档
38
+
39
+ - `docs/verification-2026-11-17.md`:逐项实测记录(含守卫端到端验证)。
40
+ - `docs/incident-2026-11-17-safety-check-defer-loading.md`:`defer_loading` 互斥事故。
41
+ - `docs/incident-2026-11-17-tool-result-image.md`:`tool_result` 非文本互斥事故。
42
+ - `docs/feedback-safety-check-exclusivity.md`:三条服务端约束的反馈报告。
43
+ - `docs/feedback-tts-code-switch.md`:TTS 中英混排发音问题的反馈报告。
44
+
45
+ ### 已知不覆盖
46
+
47
+ 见 README「不覆盖的能力及原因」一节:阅读链接、深度思考搜索、用户元信息标记、
48
+ 协议级 citations / 来源卡,以及文档 `file_id` 的对话引用路径尚未实测。
49
+
50
+ ## [0.1.1] 及更早
51
+
52
+ 内部迭代版本,未公开发布,无独立变更记录。
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 deepseekv41flash
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,250 @@
1
- # Temporary Holding Version
1
+ # dsh-chatbot-tools
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm version](https://img.shields.io/npm/v/dsh-chatbot-tools.svg)](https://www.npmjs.com/package/dsh-chatbot-tools)
4
+ [![license](https://img.shields.io/npm/l/dsh-chatbot-tools.svg)](LICENSE)
5
+ [![node](https://img.shields.io/node/v/dsh-chatbot-tools.svg)](package.json)
6
+
7
+ 补齐 **DeepSeek Chatbot(官方 chat-demo + build_a_chatbot 套件)有、DSH 缺**的能力。
8
+
9
+ 中文 | [English](#english)
10
+
11
+ | 能力 | Chatbot | DSH 原生 | 本插件 |
12
+ |---|---|---|---|
13
+ | 内容安全 `safety_check` | ✅ 请求级 | ❌ 无 | ✅ 带 3 条守卫的注入(设置页可调) |
14
+ | 图片搜索 | ✅ 服务端工具 | ❌ 无(Search API 明确不支持) | ✅ `chatbot_image_search` |
15
+ | 结构化来源(站点/时间/权威度) | ✅ `web_search_result` | 部分(纯文本 Sources) | ✅ `chatbot_search` |
16
+ | 拒答(refusal)可读提示 | ✅ 前端处理 | ❌ 适配器抛错 | ✅ `llm/stream` 兜底 |
17
+ | 文档识别 OCR | ✅ `/v1/tools/ocr` | 部分(靠技能/本地库) | ✅ `chatbot_ocr` |
18
+ | 文档上传(Files API) | ✅ 文件输入 | ❌ 无 | ✅ `chatbot_upload_document`(拿 `file_id`) |
19
+ | 语音识别 ASR | ✅ `/v1/tools/asr` | ❌ 无内置 | ✅ `chatbot_asr` + 官方语音输入 UI |
20
+ | 语音合成 TTS | ✅ `/v1/tools/tts` | ❌ 无内置 | ✅ `chatbot_tts` + 消息朗读按钮 |
21
+
22
+ ## 不覆盖的能力及原因
23
+
24
+ 本插件**不追求 1:1 覆盖 Chatbot**。以下能力有意不做,或认为不该由本插件承担:
25
+
26
+ | 能力 | 为什么不覆盖 |
27
+ |---|---|
28
+ | **阅读链接**(`deepseek_read_url`) | DSH 原生 `web_fetch` 已覆盖该能力;再包一层服务端工具属于重复实现。 |
29
+ | **深度思考搜索**(`deep_search`:search → open_page → find_in_page) | Chatbot 应用层的组合式编排;DSH 的「搜索工具 + 思考模式」已能达成相近效果,强行复刻收益低。 |
30
+ | **用户元信息标记** | Chatbot 应用层特性(把用户画像塞进系统提示);DSH 有自己的 system context 与 agent preset 机制,重复注入会打架。 |
31
+ | **协议级 citations / 来源卡** | **有意不做**。服务端 `citations` / `citations_delta` 流式块需要自定义 LLM adapter 才能完整渲染,成本远高于收益;本插件改为「结构化来源」(站点、发布时间、权威度)随工具结果返回,模型在正文里自行引用。 |
32
+ | **会话标题** | DSH 原生已有标题生成,不需要插件介入。 |
33
+ | **文档 `file_id` 的对话引用** | `chatbot_upload_document` 已能把文档上传到 Files API 并返回 `file_id`,但**「把 `file_id` 作为 document 块引用进对话」这条链路尚未实测**,因此不计入「已验证」。上传本身可用。 |
34
+
35
+ ## 开发与热重载(不要用注入器)
36
+
37
+ 本机已装 `dsh-dev-hotreload`(`Pxczxn/dsh-dev-hotreload`):**保存源码即热替换**,无需重启,也不要调用
38
+ `dev_inject_plugin` / `dev_reload_package`——这两个工具在本机有过「工具调用永不返回、会话卡住」的记录
39
+ (2026-11-04 `dev_reload_package` 卡住一小时;2026-11-17 `dev_inject_plugin` 触发 `defer_loading` 400 事故)。
40
+
41
+ 工作流:
42
+
43
+ ```bash
44
+ # 只改文件,然后等约 1 秒
45
+ # 保存 → 防抖 400ms → tick profile/cordis.patch.yml → dsh-hmr 重组合 → 新 fiber
46
+ ```
47
+
48
+ 判据(两层都要看):
49
+
50
+ 1. `%TEMP%/dsh-dev-hotreload.log` 出现 `change: lib\index.js` 与 `ticked cordis.patch.yml`;
51
+ 2. `~/.dsh/logs/chatbot-tools-safety.ndjson` 出现新的 `{"event":"applied:<BUILD_TAG>:safety=..."}`。
52
+
53
+ `BUILD_TAG` 在 `lib/index.js` 顶部,每次改动递增,用来确认跑的是新代码。
54
+
55
+ > ⚠️ **热重载只对函数体改动有效**。改 `import` / 增删导出 / 改模块级 `const`(包括 `BUILD_TAG` 本身)
56
+ > 都会让 `reload_dsh` 回报 `needs full restart`——必须重启 DSH 才生效。
57
+
58
+ ## 安装
59
+
60
+ ```bash
61
+ dsh plugin --profile <profile> add dsh-chatbot-tools
62
+ ```
63
+
64
+ 本地开发用 link:
65
+
66
+ ```bash
67
+ dsh plugin --profile desktop add link:C:/Users/Admin/dsh-chatbot-tools
68
+ ```
69
+
70
+ **不要**只用运行时注入:匿名 loader entry 没有包身份,不会出现在「插件」页,也不会被
71
+ `dsh-dev-hotreload` 按 profile 依赖自动发现。
72
+
73
+ > 判据:`plugin_manager list_bundles` 里能看到 `dsh-chatbot-tools`
74
+ > (`availability:"profile"`、`installed:true`)才算装好。
75
+
76
+ ## 配置
77
+
78
+ 在 profile patch 的 `config` 覆盖(整行替换,不深合并):
79
+
80
+ | 键 | 默认 | 说明 |
81
+ |---|---|---|
82
+ | `apiKey` | 空 | 平台 API Key。**TTS/ASR 必需**;Search/OCR 可用账号登录。明文存 patch,建议改用宿主凭据 |
83
+ | `apiKeyRef` | `DEEPSEEK_API_KEY` | 宿主凭据服务里的 key 名;DSH 设置里存过的 Key 就在这里 |
84
+ | `safetyMode` | `enforce` | `off` / `observe`(只记录)/ `enforce`(注入 `safety_check`) |
85
+ | `safetyLevel` | `high` | `high` / `low` |
86
+ | `safetyGuardDeferLoading` | `true` | **保持开启**:请求带 `defer_loading` 时跳过注入(事故守卫) |
87
+ | `safetySkipPurposes` | `['title','session-title']` | 内部请求不注入,省费用 |
88
+ | `safetyLog` | `true` | 记 `~/.dsh/logs/chatbot-tools-safety.ndjson`(只记工具形态) |
89
+ | `model` / `maxTokens` / `maxUses` | `deepseek-flash` / `1024` / `1` | 辅助调用与图片搜索的服务端工具参数 |
90
+ | `serverTool` | `deepseek_web_search` | 图片搜索用的服务端工具名 |
91
+ | `maxImageBytes` | `4194304` | 图片大小上限 |
92
+ | `searchCount` | `8` | `chatbot_search` 默认条数 |
93
+ | `ocrPurpose` / `ocrMaxChars` | `text_recognition` / `8000` | OCR 模式与返回上限 |
94
+ | `documentPurpose` | `text_recognition` | 文档上传默认用途(`user_data` 不解析不计费) |
95
+ | `ttsVoice` / `ttsFormat` / `ttsOutDir` / `ttsMaxChars` | `stella` / `wav` / 空(`~/.dsh/chatbot-tools/out`)/ `10000` | 朗读参数 |
96
+ | `ttsFilterMarkdown` | `true` | 朗读前由服务端去掉 Markdown。**代码块不会被朗读**,这是服务端行为,与本开关无关 |
97
+ | `ttsTermMap` | `{}` | 朗读前的中文替换表,JSON 字符串,如 `{"Markdown":"马克当文档"}` |
98
+ | `apiBaseURL` / `messagesBaseURL` / `apiVersion` | 官方地址 | 自建网关时改这里 |
99
+
100
+ **全部可在「设置 → 插件 → dsh-chatbot-tools」里改**:每个字段都标了 `.volatile()`,宿主据此生成表单,
101
+ 改完立即生效(volatile 写进运行中的引用),不需要重载插件。凭证解析顺序:
102
+ `设置里的 apiKey` → `DEEPSEEK_API_KEY` 环境变量 → **宿主凭据服务**(DSH 设置里存过的 Key)→ DeepSeek 账号登录。
103
+
104
+ ## 界面集成(语音)
105
+
106
+ ### 输入:官方语音输入 UI 复用
107
+
108
+ 官方把语音输入拆成三层,本插件只补最底下那层:
109
+
110
+ | 层 | 包 | 说明 |
111
+ |---|---|---|
112
+ | 服务 + provider 注册表 | `@deepseek-ai/dsh-experimental-speech-to-text` | 官方可选 bundle 提供 |
113
+ | Remote 控制器 | `@deepseek-ai/dsh-experimental-api-speech-to-text` | 客户端调用它 |
114
+ | 麦克风 UI | `@deepseek-ai/dsh-experimental-client-ui-voice-input` | 波形、音色/语种选择 |
115
+
116
+ 本插件新增 `lib/speech.js`:把 `/v1/tools/asr` 包成 `SpeechProvider`(id `deepseek-asr`),
117
+ 注册进 `ctx.speechToText`。官方麦克风 UI 会直接列出并使用它,**不需要自己写录音界面**。
118
+
119
+ 启用方式:profile 的 `dsh.profile.bundles` 需含 `@deepseek-ai/dsh-experimental-voice-input-bundle`,
120
+ 语音服务条目 `speech-to-text` 的 `defaultProvider` 设为 `deepseek-asr`。**需重启一次**让该 bundle 的行加载。
121
+
122
+ ### 输出:朗读按钮
123
+
124
+ - 客户端 `client.js` 注册到官方声明的 `conversation.chat.assistant-actions`(每条最终回答的动作行),
125
+ id `chatbot-tts`,显示 🔊。
126
+ - 点击只把 `sessionId` + `messageId` 发给宿主 `GET /chatbot-voice/tts`;
127
+ 宿主从会话日志取出该条 assistant 消息正文,调 TTS 后直接返回 `audio/wav`,页面播放。
128
+ - 好处:客户端不需要理解 Chat 快照结构,长文本也不进 URL。
129
+
130
+ > 实测:桌面渲染进程经 `dsh-app://app` 传输访问该路由正常(播放时流式返回、不落盘);
131
+ > 外部 `curl` 会 403(非应用 peer 被拒),不能用它验证。每次朗读会写一条
132
+ > `tts-ok:chars=..:bytes=..:ms=..` 审计日志到 `~/.dsh/logs/chatbot-tools-safety.ndjson`。
133
+
134
+ ## 工具
135
+
136
+ - `chatbot_search(query, count?)` — Search API,返回带站点/发布时间/权威度的来源。
137
+ - `chatbot_image_search(path, query?)` — 本地图片 → 服务端图片搜索,返回 `image_url` 缩略图与来源页。
138
+ - `chatbot_ocr(path, purpose?)` — PDF/Word/PPT/图片 → 按页文字。
139
+ - `chatbot_upload_document(path, purpose?)` — 本地文档 → Files API `file_id`(≤32 MiB / 解析类 ≤100 MiB)。
140
+ - `chatbot_asr(path)` — 16-bit PCM WAV / Ogg Opus → 文字(≤120s,≤8 MiB)。
141
+ - `chatbot_tts(text, voice?, format?)` — 文本 → 语音文件,返回落盘路径。
142
+ - `chatbot_doctor(live?)` — 自检:构建标记、当前设置、凭证通道;`live:true` 时双模式验证 `safety_check`。
143
+
144
+ ## 成本
145
+
146
+ - `chatbot_search`:Search API 按成功请求计费(¥5 / 1000 次,与 DSH 内置 search 同价)。
147
+ - `chatbot_image_search`:一次完整模型回合 + 1 次服务端工具调用;`maxUses:1` 即上限。
148
+ - `safety_check`:审核 token 计入输出 token(`usage.output_tokens_details.safety_tokens`)。
149
+ - OCR:¥1.5 / 1000 页(按成功页数)。
150
+ - 文档上传:`user_data` 不解析、不计费;`text_recognition` / `rich_layout_recognition` 按页计费。
151
+ - ASR:¥0.39–0.78 / 小时音频(按秒计)。
152
+ - TTS:¥1.5–3 / 10,000 字符(汉字算 2 字符)。
153
+
154
+ ## 已验证 / 未验证
155
+
156
+ 见 `docs/verification-2026-11-17.md`。摘要:
157
+
158
+ - ✅ `safety_check` + 普通工具 200(**仅思考模式**;新会话实测 `decision:"enforce"`)
159
+ - ✅ 非思考模式自动跳过(实测 `thinking=disabled` 同组合 400,故守卫先判 `thinkingEnabled`)
160
+ - ✅ `defer_loading` 请求自动跳过注入(多条请求实测守卫命中,无 400)
161
+ - ✅ 图片 `tool_result` 请求自动跳过注入(**端到端实测**:守卫命中当次请求,下一请求恢复 `enforce`,会话存活)
162
+ - ✅ 图片搜索 15 条结果(含 `image_url`)
163
+ - ✅ 搜索 3 条结构化来源
164
+ - ✅ OCR / TTS / ASR / 文档上传各自实测通过
165
+ - ✅ 卸载:工具立即消失、registry 清空、junction 删除(详见验证文档 §7)
166
+ - ✅ 插件页可见:bundle 安装后 `list_bundles` 出现且 `installed:true`
167
+ - ✅ 单元测试:`npm test` → 21 + 18 项全绿
168
+ - ⚠️ refusal(拒答)**只做了单元测试**(6 例通过):未主动构造违规输入,属策略边界
169
+ - ⚠️ 若真实拒答以 HTTP 400 `Content Exists Risk` 返回,中间件不拦截,表现为普通错误
170
+ - ⚠️ 文档 `file_id` 的对话引用链路未实测(见「不覆盖」表)
171
+
172
+ ## 服务端约束(都不是文档写明的)
173
+
174
+ `deepseekLlmApiExtensions.register('safety_check')` 一旦注入,服务端就会对**整个请求**施加排他性校验。
175
+ 踩中任何一条都返回 400,而且**历史已持久化后无法重试自救**。本插件为每条都实现了守卫:
176
+
177
+ | # | 约束 | 守卫 |
178
+ |---|---|---|
179
+ | 1 | 请求体内不能有 `defer_loading: true` 的工具声明 | `defer-loading-guard` |
180
+ | 2 | 不能在非思考模式(`thinking: disabled`,含标题生成等辅助请求) | `thinking-off` / `purpose-skip` |
181
+ | 3 | 历史里 `tool_result` 只能纯文本(含图片即拒) | `non-text-tool-result` |
182
+
183
+ 守卫优先级:`mode-off` → `purpose-skip` → `thinking-off` → `non-text-tool-result` → `defer-loading-guard` → `observe` → `enforce`。
184
+
185
+ 三条互斥字段 `deepseek_web_search` / `deepseek_read_url` / `safety_check` / `title` 里,**没有一个**是 DSH 核心注入的
186
+ (审计字段 `serverFields` 在每次 `enforce` 请求上都是空数组)。所以第三方插件只要用 `safety_check`,
187
+ 就必须自己承担上面三条的全部守卫义务。完整证据见 `docs/incident-2026-11-17-*.md`。
188
+
189
+ ## 踩坑
190
+
191
+ 1. **热重载后有一步竞态**:重载返回 OK 后,紧接着的一次请求可能报 `unknown tool "chatbot_xxx"`。原因:新 fiber 注册与旧 fiber 释放在同一 tick 竞争。重试一次即恢复;要彻底避免就重启。
192
+ 2. **绝不要在 `safety_check` 注入期间让会话发生工具集变更**:见 `docs/incident-2026-11-17-safety-check-defer-loading.md`。本插件的守卫已覆盖该场景,但守卫本身被关掉时会重演。
193
+ 3. `request.body.tools` 才是扩展契约里工具所在位置;`request.tools` 是文档笔误。
194
+ 4. **patch 行是整体替换 bundle config**,不是逐键合并——加/删配置键时 `cordis.patch.yml` 与 profile patch 要两边一起对。
195
+
196
+ ## 许可
197
+
198
+ MIT © 2026 deepseekv41flash
199
+
200
+ ---
201
+
202
+ ## English
203
+
204
+ A [DeepSeek Harness](https://github.com/deepseek-ai) plugin that brings **DeepSeek Chatbot**
205
+ capabilities missing from DSH.
206
+
207
+ | Capability | Provided as |
208
+ |---|---|
209
+ | Content safety (`safety_check`) | Request-level injection, **3 exclusive-constraint guards**, configurable in Settings |
210
+ | Web search with structured sources | `chatbot_search` (site, publish date, authority) |
211
+ | Image search | `chatbot_image_search` |
212
+ | Document OCR | `chatbot_ocr` (per-page text) |
213
+ | Document upload (Files API) | `chatbot_upload_document` → `file_id` |
214
+ | Speech-to-text | `chatbot_asr` + official voice-input UI |
215
+ | Text-to-speech | `chatbot_tts` + per-message 🔊 button |
216
+ | Refusal surfacing | `llm/stream` middleware |
217
+
218
+ ### Not covered (by design)
219
+
220
+ - **Read URL** — DSH already ships `web_fetch`.
221
+ - **Deep search** (search → open_page → find_in_page) — Chatbot-app-level orchestration; DSH's search + thinking mode is close enough.
222
+ - **User metadata tagging** — app-level feature that would fight DSH's own system context / agent presets.
223
+ - **Protocol-level citations / source cards** — deliberately skipped: rendering server `citations_delta` blocks needs a custom LLM adapter, not worth it. Structured sources are returned instead.
224
+ - **Session titles** — DSH has native title generation.
225
+ - **Referencing an uploaded `file_id` inside a conversation** — upload works; the reference path is not yet verified end-to-end.
226
+
227
+ ### Install
228
+
229
+ ```bash
230
+ dsh plugin --profile <profile> add dsh-chatbot-tools
231
+ ```
232
+
233
+ TTS/ASR require a platform API key. Credential order: settings `apiKey` → `DEEPSEEK_API_KEY`
234
+ env var → DSH credential service → DeepSeek account login.
235
+
236
+ ### The three server-side constraints
237
+
238
+ Injecting `safety_check` makes the server enforce exclusivity over the **whole request**.
239
+ Each violation is a hard 400 that **cannot be recovered by retrying**, because the offending
240
+ history is already persisted. Every constraint is guarded here:
241
+
242
+ 1. No `defer_loading: true` tool declarations may be present → `defer-loading-guard`
243
+ 2. No non-thinking mode (`thinking: disabled`, incl. title-generation requests) → `thinking-off`
244
+ 3. `tool_result` blocks must be text-only → `non-text-tool-result`
245
+
246
+ Guard order: `mode-off` → `purpose-skip` → `thinking-off` → `non-text-tool-result` → `defer-loading-guard` → `observe` → `enforce`.
247
+
248
+ ### License
249
+
250
+ MIT © 2026 deepseekv41flash
package/client.js ADDED
@@ -0,0 +1,83 @@
1
+ /**
2
+ * 客户端半边:在每条最终回答的动作行里加一个「朗读」按钮。
3
+ *
4
+ * 数据流刻意不经过客户端取正文:按钮只把 sessionId + messageId 发给宿主,
5
+ * 宿主从会话日志里取出该条 assistant 消息的文本,再调 DeepSeek TTS 返回音频。
6
+ * 这样客户端不需要了解 Chat 快照结构,也不会把长文本塞进 URL。
7
+ */
8
+ window.__ModuleLoader__.load({
9
+ id: 'dsh-chatbot-tools',
10
+ factory(require) {
11
+ const React = require('react')
12
+ const h = React.createElement
13
+
14
+ function SpeakButton(props) {
15
+ const [state, setState] = React.useState('idle')
16
+ const audioRef = React.useRef(null)
17
+ const stop = () => {
18
+ const audio = audioRef.current
19
+ if (audio) {
20
+ audio.pause()
21
+ audioRef.current = null
22
+ }
23
+ setState('idle')
24
+ }
25
+ const speak = async () => {
26
+ if (state === 'playing') {
27
+ stop()
28
+ return
29
+ }
30
+ setState('loading')
31
+ try {
32
+ const url = `/chatbot-voice/tts?sessionId=${encodeURIComponent(String(props.sessionId ?? ''))}`
33
+ + `&messageId=${encodeURIComponent(String(props.messageId ?? ''))}`
34
+ const response = await fetch(url, { headers: { accept: 'audio/*' } })
35
+ if (!response.ok) throw new Error((await response.text()).slice(0, 200) || `HTTP ${response.status}`)
36
+ const blob = await response.blob()
37
+ const audio = new Audio(URL.createObjectURL(blob))
38
+ audioRef.current = audio
39
+ audio.onended = () => {
40
+ URL.revokeObjectURL(audio.src)
41
+ audioRef.current = null
42
+ setState('idle')
43
+ }
44
+ await audio.play()
45
+ setState('playing')
46
+ } catch (error) {
47
+ setState('idle')
48
+ console.warn('[dsh-chatbot-tools] 朗读失败:', error)
49
+ }
50
+ }
51
+ const label = state === 'loading' ? '…' : state === 'playing' ? '■' : '🔊'
52
+ const title = state === 'playing' ? '停止朗读' : '朗读这条回答(DeepSeek TTS)'
53
+ return h('button', {
54
+ type: 'button',
55
+ onClick: speak,
56
+ disabled: state === 'loading',
57
+ title,
58
+ 'aria-label': title,
59
+ style: {
60
+ background: 'transparent',
61
+ border: 'none',
62
+ padding: '0 4px',
63
+ cursor: state === 'loading' ? 'progress' : 'pointer',
64
+ color: 'inherit',
65
+ opacity: 0.75,
66
+ fontSize: '13px',
67
+ lineHeight: 1,
68
+ },
69
+ }, label)
70
+ }
71
+
72
+ return {
73
+ inject: ['slots'],
74
+ apply(ctx) {
75
+ ctx.slots.inject('conversation.chat.assistant-actions', () => ctx.slots.register({
76
+ name: 'conversation.chat.assistant-actions',
77
+ id: 'chatbot-tts',
78
+ order: 12,
79
+ }, SpeakButton))
80
+ },
81
+ }
82
+ },
83
+ })
@@ -0,0 +1,20 @@
1
+ # dsh-chatbot-tools — bundle patch 层。
2
+ # 有这一层,插件才有「包身份」:会出现在 设置 → 插件 列表里,可被插件管理器
3
+ # 识别、启停与升级;只靠运行时 loader.create 注入的匿名 entry 不会出现在那里。
4
+ - insert:
5
+ - id: dsh-chatbot-tools
6
+ name: 'dsh-chatbot-tools'
7
+ inject:
8
+ - tools
9
+ config:
10
+ # 内容安全三态:off / observe / enforce
11
+ safetyMode: enforce
12
+ safetyLevel: high
13
+ safetyGuardDeferLoading: true
14
+ safetySkipPurposes:
15
+ - title
16
+ - session-title
17
+ safetyLog: true
18
+ model: deepseek-flash
19
+ serverTool: deepseek_web_search
20
+ maxUses: 1
@@ -0,0 +1,82 @@
1
+ # 反馈报告(续):内容安全工具 `safety_check` 的 3 条隐藏互斥,以及 400 后会话不可恢复
2
+
3
+ | 项 | 值 |
4
+ |---|---|
5
+ | 接口 | `POST https://api.deepseek.com/anthropic/v1/messages`(Messages,Anthropic 兼容) |
6
+ | 相关字段 | `safety_check` / `deepseek_web_search` / `deepseek_read_url` / `title` |
7
+ | 发现时间 | 2026-11-17 |
8
+ | 前置反馈 | 同日的 TTS 中英混排发音问题(`docs/feedback-tts-code-switch.md`) |
9
+ | 严重度 | 高:一次踩中即**永久作废整个会话**,重试无法恢复 |
10
+
11
+ ## 0. 背景
12
+
13
+ Messages 文档里 `safety_check`、`deepseek_web_search`、`deepseek_read_url`、`title` 是并列的
14
+ 服务端扩展工具。实测发现:**这四个字段里只要出现任意一个,服务端就会对整个请求施加若干排他性
15
+ 校验**,而文档没有写明这些校验的存在。
16
+
17
+ 我们是一个第三方客户端(DeepSeek Harness 插件),接了 `safety_check` 做内容安全。三条约束
18
+ 全部踩了一遍,每条都是 400 硬失败,因此逐条记录下来。
19
+
20
+ ## 1. 约束一:请求体内不能含 `defer_loading: true` 的工具声明
21
+
22
+ **场景**:多轮会话进行到中途,客户端新增了一个工具。为了不破坏已缓存的提示前缀,客户端把新增
23
+ 工具声明为 `defer_loading: true`(Anthropic 官方语义,文档有写)。
24
+
25
+ **结果**:只要同时注入 `safety_check`,请求即被拒。
26
+
27
+ **问题**:这一类失败没有可读的错误文本(相比下面两条),定位成本最高。
28
+
29
+ ## 2. 约束二:不能在非思考模式
30
+
31
+ **场景**:`thinking: {"type": "disabled"}`,或客户端发起的辅助性请求(例如生成会话标题,
32
+ 本身不该消耗思考预算)。
33
+
34
+ **结果**:同上,被拒。
35
+
36
+ ## 3. 约束三:历史里的 `tool_result` 只能包含纯文本
37
+
38
+ **错误信息(原文)**:
39
+
40
+ ```
41
+ messages.94: only text content is supported in `tool_result` blocks with
42
+ `deepseek_web_search`, `deepseek_read_url`, `safety_check` or `title` yet
43
+ (request_id: a0e61cba-94f6-4592-8bf7-5a58ff1856f0)
44
+ ```
45
+
46
+ **最小复现**:
47
+
48
+ 1. 开启 `safety_check`,正常多轮对话若干轮;
49
+ 2. 模型调用一个返回图片的工具(我们的 `read_image`),历史中留下一个 `tool_result`,
50
+ 其 `content` 是数组,含 `{"type": "image", ...}` 块;
51
+ 3. 该轮之后,**每一次**请求都返回上面这个 400,且 `messages.94` 恒定不变。
52
+
53
+ **为什么这条最严重**:错误指向的是**历史**而不是当前请求。历史一旦持久化就删不掉,
54
+ 所以客户端「重试」永远失败——会话被永久写死,用户只能新开会话,上下文全丢。
55
+ 错误信息里的 "yet" 暗示这是未实现而非不支持,但当前行为是硬拒绝且不降级。
56
+
57
+ ## 4. 建议
58
+
59
+ 1. **文档补一节**:明确列出这四个字段会开启哪些排他校验(至少上面三条),以及
60
+ 「一个请求里只能有一个服务端扩展字段」这类结构性约束是否存在;
61
+ 2. **错误信息指向根因**:现在三种情况报错各不相同,但都不说是哪条约束被违反。
62
+ 约束一甚至没有明确文本。建议统一为可机器识别的 `error.code` + 具体约束名;
63
+ 3. **约束三改为降级而非拒绝**:例如该轮自动降级为「不带 `safety_check` 发送」并返回警告,
64
+ 或允许 `tool_result` 内文本与图片混排。哪怕只是警告,也远好过一个会话被写死;
65
+ 4. 如果这些校验是刻意的安全设计,也请在文档里说明原因,好让第三方客户端知道
66
+ **接 `safety_check` 需要自建多少守卫**——我们目前实现的是三条守卫 + 21 项回归检查。
67
+
68
+ ## 5. 我们的处理(仅作说明,无需回复)
69
+
70
+ 三条约束已在客户端侧全部实现为守卫,命中任一条就自动跳过本次 `safety_check` 注入,
71
+ 保证请求不被拒、会话不被写死;每条都配了单元测试。排序为:
72
+ `mode-off` → `purpose-skip` → `thinking-off` → `non-text-tool-result` → `defer-loading-guard`
73
+ → `observe` → `enforce`。
74
+
75
+ 另外验证到:约束一的 `defer_loading` 标记会随历史重写(compaction)或进程重启自动消失,
76
+ 所以它是可自愈的;约束三则完全不可自愈。
77
+
78
+ ---
79
+
80
+ 附:本报告的完整证据链见
81
+ - `docs/incident-2026-11-17-safety-check-defer-loading.md`(约束一、二)
82
+ - `docs/incident-2026-11-17-tool-result-image.md`(约束三,含 request_id 与宿主日志)
@@ -0,0 +1,108 @@
1
+ # 反馈报告:TTS 在中英混排(中文句子里夹英文术语)时发音错误
2
+
3
+ | 项 | 值 |
4
+ |---|---|
5
+ | 接口 | `POST https://api.deepseek.com/v1/tools/tts`(WebSocket 同路径同样受影响) |
6
+ | 发现时间 | 2026-11-17 |
7
+ | 音色 | `stella`(默认女声),`format: wav`,`filter_markdown: false` |
8
+ | 影响 | 编程/技术类文本中英混排极常见(如 Markdown、API、prompt、token),朗读时英文词被念错或消失 |
9
+ | 严重度 | 中高:内容可听懂,但关键术语失真,影响可用性 |
10
+
11
+ ## 1. 现象
12
+
13
+ 中文句子里夹英文术语时,英文词有三种表现:
14
+
15
+ 1. **整段/短文本被误判语种**:单独朗读 `Markdown` 时,语种被判成韩语,合成音频送 ASR 转写回来是韩文 `핑가바`;
16
+ 2. **被汉语音系同化**:`我们讨论一下 Markdown。` → ASR 回写 `我们讨论一下Mardeano。`;
17
+ 3. **中段有中文锚点时正常**:`这个 Markdown 语法很好用。` → 正常。
18
+
19
+ ## 2. 最小复现(5 组,TTS → ASR 回写)
20
+
21
+ 方法:对同一文本调用 `/v1/tools/tts`,把返回的 wav 再送 `/v1/tools/asr`,比较回写文本。
22
+
23
+ | # | 输入文本 | 音频 | ASR 回写 | 判定 |
24
+ |---|---|---|---|---|
25
+ | 1 | `Markdown` | 46,124 B (~0.96 s) | `핑가바` | ❌ 误判为韩语 |
26
+ | 2 | `我们讨论一下 Markdown。` | 80,684 B (~1.68 s) | `我们讨论一下Mardeano。` | ❌ 被同化 |
27
+ | 3 | `我们讨论一下 Markdown 的用法。` | 90,284 B | `我们讨论一下 Markdown 的用法。` | ✅ |
28
+ | 4 | `这个 Markdown 语法很好用。` | 94,124 B | `这个 Markdown 语法很好用。` | ✅ |
29
+ | 5 | `We use Markdown to format documents.` | 115,244 B | 原样正确 | ✅ |
30
+
31
+ 结论:判定是**按整段文本**做的,不是逐词;英文词处于句尾或缺少中文锚点时最容易出错。
32
+
33
+ ## 3. 期望与实际
34
+
35
+ - 期望:中文句中夹带的英文术语按英文发音(或至少可预期地读成中文音译),不出现韩语/失真读音;
36
+ - 实际:语种判定与 G2P 在 code-switch 场景不稳定,且没有参数可以干预。
37
+
38
+ ## 4. 建议的改进(任一即可)
39
+
40
+ 1. **加一个 `language` 参数**(如 `zh` / `en` / `auto`),让调用方锁定主语言;
41
+ 2. **加逐词/逐段的语言标注能力**(如 SSML 的 `<lang>`,或 `segments: [{text, lang}]`);
42
+ 3. **加自定义读音/术语表**(如 `pronunciations: {"Markdown": "马克当"}`),或在 text 中支持拼音/音标标注;
43
+ 4. 退一步:在文档里明确「避免让英文词落在句尾、可加中文锚点」这一限制,并说明不支持 prompt。
44
+
45
+ ## 5. 当前客户端侧的规避(供参考)
46
+
47
+ 调用方只能在朗读前改写文本:把易错英文术语替换成读音稳定的说法(如 `Markdown → 马克当`)。
48
+ 这既增加维护成本,也无法覆盖未登记的术语——这正是希望能由服务端参数解决的原因。
49
+
50
+ ## 6. 附件
51
+
52
+ 音频样本(本机路径,发送时请替换为实际附件):
53
+
54
+ ```
55
+ %USERPROFILE%\.dsh\chatbot-tools\out\tts-1794923335105.wav # 用例 2
56
+ %USERPROFILE%\.dsh\chatbot-tools\out\tts-1794923354795.wav # 用例 1(Markdown 单词)
57
+ %USERPROFILE%\.dsh\chatbot-tools\out\tts-1794923355920.wav # 用例 4
58
+ ```
59
+
60
+ ---
61
+
62
+ ## English summary
63
+
64
+ **Issue**: `/v1/tools/tts` mispronounces English terms embedded in Chinese text (a very common
65
+ pattern in coding/technical content).
66
+
67
+ **Evidence** (TTS → ASR round-trip, voice `stella`, `filter_markdown: false`, 2026-11-17):
68
+
69
+ | Input | ASR transcript | Verdict |
70
+ |---|---|---|
71
+ | `Markdown` (alone) | `핑가바` (Korean) | wrong language detected |
72
+ | `我们讨论一下 Markdown。` | `我们讨论一下Mardeano。` | assimilated by Chinese phonology |
73
+ | `我们讨论一下 Markdown 的用法。` | unchanged | OK |
74
+ | `这个 Markdown 语法很好用。` | unchanged | OK |
75
+ | `We use Markdown to format documents.` | unchanged | OK |
76
+
77
+ **Root cause (inferred)**: language is auto-detected per whole text; there is no `language`
78
+ parameter, no per-segment language tagging, no pronunciation lexicon, and no prompt field.
79
+
80
+ **Requested**: (1) a `language` parameter; or (2) per-segment/per-word language tags (SSML-like);
81
+ or (3) a custom pronunciation map; and at minimum a documented workaround.
82
+
83
+ **Impact**: Chinese technical read-aloud loses or distorts key terms; clients must maintain
84
+ term-substitution tables as a workaround.
85
+
86
+ ## 投递记录
87
+
88
+ | 时间 | 动作 | 结果 |
89
+ |---|---|---|
90
+ | 2026-11-17 22:38 | 用 `dsh-email`(Outlook / monkey321478965@outlook.com)调用 `email_send` 发往 `api-service@deepseek.com` | ❌ 被拒:「发信未获批准……当前会话处于 Full Access(审批策略 never,不会弹框)」 |
91
+ | 2026-11-17 22:38 | 改为 `email_draft` 保存本地草稿,含 3 段音频附件 | ✅ 草稿 `20ef976b-ce96-4802-9d4a-777648a51912` |
92
+
93
+ **待办**:在「设置 → 邮件 → 草稿」预览并手动发送;或把会话权限切到会弹确认的模式后由 agent 重发。
94
+
95
+ **踩坑**:Full Access(审批策略 never)下 `dsh-email` 会拒绝需要人工确认的发信,不会弹框;
96
+ 这是插件与权限策略的交互结果,不是账号或网络问题。草稿路径不触发该限制。
97
+
98
+ | 时间 | 动作 | 结果 |
99
+ |---|---|---|
100
+ | 2026-11-17 22:41 | 切到会弹确认的权限模式后重发 `email_send` | ✅ 已送达,messageId `<4c29cbd1-c2fe-1edc-f589-2d41f8c123fa@outlook.com>`,服务器 250 OK |
101
+
102
+ ### 附件
103
+
104
+ ```
105
+ %USERPROFILE%\.dsh\chatbot-tools\out\tts-1794923354795.wav # 用例 1:Markdown 单念 → 韩文
106
+ %USERPROFILE%\.dsh\chatbot-tools\out\tts-1794923335105.wav # 用例 2:句尾 → Mardeano
107
+ %USERPROFILE%\.dsh\chatbot-tools\out\tts-1794923355920.wav # 用例 4:中段对照(正常)
108
+ ```