dsh-chatbot-tools 0.0.0-stage → 0.2.1

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,62 @@
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.1] - 2026-11-18
7
+
8
+ 纯文档补丁,让 npm 页面与仓库保持一致。
9
+
10
+ ### 变更
11
+
12
+ - README 顶部对齐本账号其他插件格式:语言切换行 + listed / npm / license 三枚徽章 + 引用块摘要。
13
+ - 英文版拆到独立的 `README-en.md`(原先内联在 `README.md` 底部),两份互加语言切换链接。
14
+ - `package.json` 的 `files` 增加 `README-en.md`。
15
+
16
+ ## [0.2.0] - 2026-11-18
17
+
18
+ 首个公开发布版本。
19
+
20
+ ### 新增
21
+
22
+ - **内容安全**:通过 `deepseekLlmApiExtensions` 注册 `safety_check`,可在设置页调
23
+ `safetyMode`(`off` / `observe` / `enforce`)与 `safetyLevel`(`high` / `low`)。
24
+ 实测发现服务端会对整个请求施加 **3 条排他约束**,每条都实现为守卫并配单元测试:
25
+ - `non-text-tool-result` —— 历史中 `tool_result` 含图片等非文本块时跳过注入;
26
+ - `defer-loading-guard` —— 请求含 `defer_loading` 工具声明时跳过注入;
27
+ - `thinking-off` / `purpose-skip` —— 非思考模式与内部辅助请求跳过注入。
28
+ - `chatbot_search`:联网搜索,返回带站点、发布时间、权威度的**结构化来源**,便于正文引用。
29
+ - `chatbot_image_search`:图片搜索(按图片找相似图片与出处)。
30
+ - `chatbot_ocr`:PDF / Word / PPT / 图片文字识别,按页返回;支持纯文本与逐页版面两种模式。
31
+ - `chatbot_upload_document`:把本地文档上传到 DeepSeek Files API,拿回 `file_id`;
32
+ 支持 `text_recognition` / `rich_layout_recognition` / `user_data` 三种用途。
33
+ - `chatbot_tts`:语音合成,落盘返回音频路径;支持音色、格式与自定义术语表 `ttsTermMap`。
34
+ - `chatbot_asr`:语音转文字。
35
+ - `chatbot_doctor`:自检凭证通道、当前生效配置与守卫状态。
36
+ - **界面集成**:助手消息下方新增「朗读」按钮(client slot
37
+ `conversation.chat.assistant-actions`);语音输入通过官方 `speechToText` 接缝注册
38
+ `deepseek-asr` 提供方,复用官方麦克风 UI。
39
+ - **拒答兜底**:`llm/stream` 拦截服务端拒答,转成可读提示而不是让适配器抛错。
40
+
41
+ ### 修复
42
+
43
+ - 行内代码在朗读时被整段丢弃 —— 改为在客户端拼装可朗读文本后再送服务端。
44
+ - 英文术语(`Markdown` 等)在中英混排时被念错 —— 引入 `ttsTermMap` 术语表;
45
+ 短键(≤2 字符 ASCII,如 `AI`、`Go`)改用整词匹配,避免撞进 `OPENAI`、`Golang`。
46
+
47
+ ### 文档
48
+
49
+ - `docs/verification-2026-11-17.md`:逐项实测记录(含守卫端到端验证)。
50
+ - `docs/incident-2026-11-17-safety-check-defer-loading.md`:`defer_loading` 互斥事故。
51
+ - `docs/incident-2026-11-17-tool-result-image.md`:`tool_result` 非文本互斥事故。
52
+ - `docs/feedback-safety-check-exclusivity.md`:三条服务端约束的反馈报告。
53
+ - `docs/feedback-tts-code-switch.md`:TTS 中英混排发音问题的反馈报告。
54
+
55
+ ### 已知不覆盖
56
+
57
+ 见 README「不覆盖的能力及原因」一节:阅读链接、深度思考搜索、用户元信息标记、
58
+ 协议级 citations / 来源卡,以及文档 `file_id` 的对话引用路径尚未实测。
59
+
60
+ ## [0.1.1] 及更早
61
+
62
+ 内部迭代版本,未公开发布,无独立变更记录。
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-en.md ADDED
@@ -0,0 +1,199 @@
1
+ # dsh-chatbot-tools
2
+
3
+ [English](README-en.md) · [简体中文](README.md)
4
+
5
+ [![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/deepseekv41flash/dsh-chatbot-tools)
6
+ [![npm](https://img.shields.io/npm/v/dsh-chatbot-tools.svg)](https://www.npmjs.com/package/dsh-chatbot-tools)
7
+ [![license](https://img.shields.io/npm/l/dsh-chatbot-tools.svg)](./LICENSE)
8
+
9
+ > Brings the **DeepSeek Chatbot** capabilities that DSH lacks into
10
+ > [DeepSeek Harness](https://github.com/deepseek-ai): content safety (with guards for three
11
+ > server-side exclusive constraints), web & image search, OCR, TTS, ASR, document upload.
12
+
13
+ | Capability | Chatbot | DSH native | This plugin |
14
+ |---|---|---|---|
15
+ | Content safety (`safety_check`) | ✅ request-level | ❌ none | ✅ injection with 3 guards (configurable) |
16
+ | Image search | ✅ server tool | ❌ none (Search API doesn't support it) | ✅ `chatbot_image_search` |
17
+ | Structured sources (site / date / authority) | ✅ `web_search_result` | partial (plain-text Sources) | ✅ `chatbot_search` |
18
+ | Refusal surfacing | ✅ handled in the UI | ❌ adapter throws | ✅ `llm/stream` fallback |
19
+ | Document OCR | ✅ `/v1/tools/ocr` | partial (via skills / local libs) | ✅ `chatbot_ocr` |
20
+ | Document upload (Files API) | ✅ file input | ❌ none | ✅ `chatbot_upload_document` → `file_id` |
21
+ | Speech-to-text | ✅ `/v1/tools/asr` | ❌ none built in | ✅ `chatbot_asr` + official voice-input UI |
22
+ | Text-to-speech | ✅ `/v1/tools/tts` | ❌ none built in | ✅ `chatbot_tts` + per-message 🔊 button |
23
+
24
+ ## Not covered, and why
25
+
26
+ This plugin does **not** aim for 1:1 parity with Chatbot. The following are deliberately
27
+ out of scope:
28
+
29
+ | Capability | Why not |
30
+ |---|---|
31
+ | **Read URL** (`deepseek_read_url`) | DSH already ships `web_fetch`; wrapping it again as a server tool is duplication. |
32
+ | **Deep search** (`deep_search`: search → open_page → find_in_page) | Chatbot-app-level orchestration. DSH's "search tool + thinking mode" already gets close. |
33
+ | **User metadata tagging** | An app-level feature (injecting a user profile into the system prompt). DSH has its own system context and agent presets; duplicating it would fight them. |
34
+ | **Protocol-level citations / source cards** | **Deliberately skipped.** Rendering the server's streaming `citations` / `citations_delta` blocks requires a custom LLM adapter — far more cost than value. Structured sources (site, publish date, authority) are returned with the tool result instead, and the model cites them in prose. |
35
+ | **Session titles** | DSH already generates titles natively. |
36
+ | **Referencing an uploaded `file_id` inside a conversation** | `chatbot_upload_document` uploads to the Files API and returns a `file_id`, but **the path that references it as a `document` block in a conversation has not been verified end-to-end**, so it is not counted as verified. The upload itself works. |
37
+
38
+ ## Development & hot reload (do not use injectors)
39
+
40
+ `dsh-dev-hotreload` is installed on this machine: **saving the source hot-swaps it**, no restart
41
+ needed. Do not call `dev_inject_plugin` / `dev_reload_package` — both have caused hung tool calls
42
+ on this machine (2026-11-04 `dev_reload_package` hung for an hour; 2026-11-17 `dev_inject_plugin`
43
+ triggered the `defer_loading` 400 incident).
44
+
45
+ Criteria (check both):
46
+
47
+ 1. `%TEMP%/dsh-dev-hotreload.log` shows `change: lib\index.js` and `ticked cordis.patch.yml`;
48
+ 2. `~/.dsh/logs/chatbot-tools-safety.ndjson` gets a new `{"event":"applied:<BUILD_TAG>:safety=..."}`.
49
+
50
+ `BUILD_TAG` lives at the top of `lib/index.js` and is bumped on every change.
51
+
52
+ > ⚠️ **Hot reload only works for changes inside function bodies.** Changing an `import`,
53
+ > adding/removing an export, or editing a module-level `const` (including `BUILD_TAG` itself)
54
+ > makes `reload_dsh` report `needs full restart` — a DSH restart is required.
55
+
56
+ ## Install
57
+
58
+ ```bash
59
+ dsh plugin --profile <profile> add dsh-chatbot-tools
60
+ ```
61
+
62
+ For local development, link it:
63
+
64
+ ```bash
65
+ dsh plugin --profile desktop add link:C:/Users/Admin/dsh-chatbot-tools
66
+ ```
67
+
68
+ Do **not** rely on runtime injection alone: an anonymous loader entry has no package identity,
69
+ won't show up on the Plugins page, and won't be discovered by `dsh-dev-hotreload`.
70
+
71
+ > Check: `plugin_manager list_bundles` must show `dsh-chatbot-tools`
72
+ > (`availability:"profile"`, `installed:true`).
73
+
74
+ ## Configuration
75
+
76
+ Override in the profile patch `config` (a patch row **replaces** the bundle config, it does not merge):
77
+
78
+ | Key | Default | Meaning |
79
+ |---|---|---|
80
+ | `apiKey` | empty | Platform API key. **Required for TTS/ASR**; Search/OCR can use account login |
81
+ | `apiKeyRef` | `DEEPSEEK_API_KEY` | Key name in the host credential service |
82
+ | `safetyMode` | `enforce` | `off` / `observe` (log only) / `enforce` (inject `safety_check`) |
83
+ | `safetyLevel` | `high` | `high` / `low` |
84
+ | `safetyGuardDeferLoading` | `true` | **Keep on**: skip injection when the request has `defer_loading` |
85
+ | `safetySkipPurposes` | `['title','session-title']` | Skip internal requests to save cost |
86
+ | `safetyLog` | `true` | Write `~/.dsh/logs/chatbot-tools-safety.ndjson` |
87
+ | `model` / `maxTokens` / `maxUses` | `deepseek-flash` / `1024` / `1` | Auxiliary calls and image-search server tool |
88
+ | `serverTool` | `deepseek_web_search` | Server tool used by image search |
89
+ | `maxImageBytes` | `4194304` | Image size limit |
90
+ | `searchCount` | `8` | Default result count for `chatbot_search` |
91
+ | `ocrPurpose` / `ocrMaxChars` | `text_recognition` / `8000` | OCR mode and output cap |
92
+ | `documentPurpose` | `text_recognition` | Default document upload purpose (`user_data` is not parsed and not billed) |
93
+ | `ttsVoice` / `ttsFormat` / `ttsOutDir` / `ttsMaxChars` | `stella` / `wav` / empty (`~/.dsh/chatbot-tools/out`) / `10000` | TTS parameters |
94
+ | `ttsFilterMarkdown` | `true` | Strip Markdown server-side before speaking. **Code blocks are never spoken** — server behaviour, unrelated to this switch |
95
+ | `ttsTermMap` | `{}` | Replacement map applied before speaking, JSON string, e.g. `{"Markdown":"马克当文档"}` |
96
+ | `apiBaseURL` / `messagesBaseURL` / `apiVersion` | official | Change for a self-hosted gateway |
97
+
98
+ Every field is marked `.volatile()`, so the host renders a settings form under
99
+ **Settings → Plugins → dsh-chatbot-tools** and changes take effect immediately.
100
+ Credential order: settings `apiKey` → `DEEPSEEK_API_KEY` env var → **host credential service** →
101
+ DeepSeek account login.
102
+
103
+ ## UI integration (speech)
104
+
105
+ ### Input: reusing the official voice-input UI
106
+
107
+ The official implementation splits speech input into three layers; this plugin only supplies the bottom one:
108
+
109
+ | Layer | Package |
110
+ |---|---|
111
+ | Service + provider registry | `@deepseek-ai/dsh-experimental-speech-to-text` |
112
+ | Remote controller | `@deepseek-ai/dsh-experimental-api-speech-to-text` |
113
+ | Microphone UI | `@deepseek-ai/dsh-experimental-client-ui-voice-input` |
114
+
115
+ `lib/speech.js` wraps `/v1/tools/asr` as a `SpeechProvider` (id `deepseek-asr`) and registers it
116
+ into `ctx.speechToText`. The official microphone UI lists and uses it — **no custom recording UI needed**.
117
+
118
+ Requires `@deepseek-ai/dsh-experimental-voice-input-bundle` in `dsh.profile.bundles` and
119
+ `defaultProvider: deepseek-asr` on the `speech-to-text` entry. **One restart** is needed for that
120
+ bundle's rows to load.
121
+
122
+ ### Output: the speak button
123
+
124
+ - `client.js` registers a 🔊 button into the official `conversation.chat.assistant-actions` slot.
125
+ - A click sends only `sessionId` + `messageId` to the host `GET /chatbot-voice/tts`; the host pulls
126
+ that assistant message from the session log, calls TTS, and streams back `audio/wav`.
127
+ - Benefit: the client never needs to understand the chat snapshot, and long text never goes into a URL.
128
+
129
+ > Measured: the desktop renderer reaches that route over `dsh-app://app` (streamed, never written to
130
+ > disk). External `curl` gets 403 (non-app peers are rejected), so it cannot be used to verify.
131
+ > Each playback appends a `tts-ok:chars=..:bytes=..:ms=..` line to `~/.dsh/logs/chatbot-tools-safety.ndjson`.
132
+
133
+ ## Tools
134
+
135
+ - `chatbot_search(query, count?)` — Search API, returns sources with site/date/authority.
136
+ - `chatbot_image_search(path, query?)` — local image → server image search, returns `image_url` and source pages.
137
+ - `chatbot_ocr(path, purpose?)` — PDF/Word/PPT/image → per-page text.
138
+ - `chatbot_upload_document(path, purpose?)` — local document → Files API `file_id` (≤32 MiB / ≤100 MiB for parse modes).
139
+ - `chatbot_asr(path)` — 16-bit PCM WAV / Ogg Opus → text (≤120 s, ≤8 MiB).
140
+ - `chatbot_tts(text, voice?, format?)` — text → audio file, returns the path.
141
+ - `chatbot_doctor(live?)` — self-check: build tag, current settings, credential channel.
142
+
143
+ ## Cost
144
+
145
+ - `chatbot_search`: Search API, billed per successful request (¥5 / 1000, same as DSH's built-in search).
146
+ - `chatbot_image_search`: one full model turn + one server-tool call; `maxUses:1` caps it.
147
+ - `safety_check`: moderation tokens count as output tokens (`usage.output_tokens_details.safety_tokens`).
148
+ - OCR: ¥1.5 / 1000 pages (successful pages).
149
+ - Document upload: `user_data` is not parsed and not billed; parse modes are billed per page.
150
+ - ASR: ¥0.39–0.78 per hour of audio (per second).
151
+ - TTS: ¥1.5–3 / 10,000 characters (a CJK character counts as 2).
152
+
153
+ ## Verified / not verified
154
+
155
+ See `docs/verification-2026-11-17.md`. Summary:
156
+
157
+ - ✅ `safety_check` + normal tools → 200 (**thinking mode only**; a fresh session logs `decision:"enforce"`)
158
+ - ✅ Non-thinking mode skipped automatically (measured: the same combination returns 400, so the guard checks `thinkingEnabled` first)
159
+ - ✅ Requests with `defer_loading` skip injection (guard hits measured, no 400)
160
+ - ✅ Requests with an image `tool_result` skip injection (**verified end-to-end**: the guard hit for that one request, the next request returned to `enforce`, session stayed alive)
161
+ - ✅ Image search: 15 results with `image_url`
162
+ - ✅ Search: 3 structured sources
163
+ - ✅ OCR / TTS / ASR / document upload each verified live
164
+ - ✅ Uninstall: tools vanish immediately, registry cleared, junction removed (verification doc §7)
165
+ - ✅ Shows up on the Plugins page after bundle install (`installed:true`)
166
+ - ✅ Unit tests: `npm test` → 21 + 18 checks green
167
+ - ⚠️ Refusal handling is **unit-tested only** (6 cases): we do not craft violating input on purpose
168
+ - ⚠️ If a real refusal comes back as HTTP 400 `Content Exists Risk`, the middleware does not intercept it and it surfaces as a normal error
169
+ - ⚠️ The document `file_id` reference path is unverified (see "Not covered")
170
+
171
+ ## Server-side constraints (none of them documented)
172
+
173
+ Once `deepseekLlmApiExtensions.register('safety_check')` injects `safety_check`, the server enforces
174
+ exclusivity over the **whole request**. Any violation returns a 400 that **cannot be recovered by
175
+ retrying**, because the offending history is already persisted. Every constraint is guarded:
176
+
177
+ | # | Constraint | Guard |
178
+ |---|---|---|
179
+ | 1 | No `defer_loading: true` tool declarations in the request | `defer-loading-guard` |
180
+ | 2 | No non-thinking mode (`thinking: disabled`, including title generation) | `thinking-off` / `purpose-skip` |
181
+ | 3 | `tool_result` history must be text-only (an image block is enough to fail) | `non-text-tool-result` |
182
+
183
+ Guard order: `mode-off` → `purpose-skip` → `thinking-off` → `non-text-tool-result` → `defer-loading-guard` → `observe` → `enforce`.
184
+
185
+ None of the four mutually exclusive fields (`deepseek_web_search` / `deepseek_read_url` /
186
+ `safety_check` / `title`) is injected by DSH core — the audit field `serverFields` is an empty array
187
+ on every `enforce` request. So any third-party plugin using `safety_check` inherits all three guards
188
+ as its own responsibility. Full evidence in `docs/incident-2026-11-17-*.md`.
189
+
190
+ ## Gotchas
191
+
192
+ 1. **One race right after a hot reload**: the first request following a reload may report `unknown tool "chatbot_xxx"` because the new fiber's registration races the old fiber's disposal in the same tick. Retrying once fixes it; a restart avoids it.
193
+ 2. **Never let the tool set change mid-session while `safety_check` is injected**: see `docs/incident-2026-11-17-safety-check-defer-loading.md`. The guards cover this, but turning them off reproduces it.
194
+ 3. `request.body.tools` is where tools live in the extension contract; `request.tools` is a documentation typo.
195
+ 4. **A patch row replaces the bundle config wholesale**, it does not merge key by key — keep `cordis.patch.yml` and the profile patch in sync when adding/removing keys.
196
+
197
+ ## License
198
+
199
+ MIT © 2026 deepseekv41flash
package/README.md CHANGED
@@ -1,3 +1,200 @@
1
- # Temporary Holding Version
1
+ # dsh-chatbot-tools
2
+
3
+ [English](README-en.md) · [简体中文](README.md)
4
+
5
+ [![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/deepseekv41flash/dsh-chatbot-tools)
6
+ [![npm](https://img.shields.io/npm/v/dsh-chatbot-tools.svg)](https://www.npmjs.com/package/dsh-chatbot-tools)
7
+ [![license](https://img.shields.io/npm/l/dsh-chatbot-tools.svg)](./LICENSE)
8
+
9
+ > 补齐 **DeepSeek Chatbot(官方 chat-demo + build_a_chatbot 套件)有、DSH 缺**的能力:
10
+ > 内容安全(含 3 条服务端互斥约束的守卫)、联网/图片搜索、OCR、TTS、ASR、文档上传。
11
+
12
+ | 能力 | Chatbot | DSH 原生 | 本插件 |
13
+ |---|---|---|---|
14
+ | 内容安全 `safety_check` | ✅ 请求级 | ❌ 无 | ✅ 带 3 条守卫的注入(设置页可调) |
15
+ | 图片搜索 | ✅ 服务端工具 | ❌ 无(Search API 明确不支持) | ✅ `chatbot_image_search` |
16
+ | 结构化来源(站点/时间/权威度) | ✅ `web_search_result` | 部分(纯文本 Sources) | ✅ `chatbot_search` |
17
+ | 拒答(refusal)可读提示 | ✅ 前端处理 | ❌ 适配器抛错 | ✅ `llm/stream` 兜底 |
18
+ | 文档识别 OCR | ✅ `/v1/tools/ocr` | 部分(靠技能/本地库) | ✅ `chatbot_ocr` |
19
+ | 文档上传(Files API) | ✅ 文件输入 | ❌ 无 | ✅ `chatbot_upload_document`(拿 `file_id`) |
20
+ | 语音识别 ASR | ✅ `/v1/tools/asr` | ❌ 无内置 | ✅ `chatbot_asr` + 官方语音输入 UI |
21
+ | 语音合成 TTS | ✅ `/v1/tools/tts` | ❌ 无内置 | ✅ `chatbot_tts` + 消息朗读按钮 |
22
+
23
+ ## 不覆盖的能力及原因
24
+
25
+ 本插件**不追求 1:1 覆盖 Chatbot**。以下能力有意不做,或认为不该由本插件承担:
26
+
27
+ | 能力 | 为什么不覆盖 |
28
+ |---|---|
29
+ | **阅读链接**(`deepseek_read_url`) | DSH 原生 `web_fetch` 已覆盖该能力;再包一层服务端工具属于重复实现。 |
30
+ | **深度思考搜索**(`deep_search`:search → open_page → find_in_page) | Chatbot 应用层的组合式编排;DSH 的「搜索工具 + 思考模式」已能达成相近效果,强行复刻收益低。 |
31
+ | **用户元信息标记** | Chatbot 应用层特性(把用户画像塞进系统提示);DSH 有自己的 system context 与 agent preset 机制,重复注入会打架。 |
32
+ | **协议级 citations / 来源卡** | **有意不做**。服务端 `citations` / `citations_delta` 流式块需要自定义 LLM adapter 才能完整渲染,成本远高于收益;本插件改为「结构化来源」(站点、发布时间、权威度)随工具结果返回,模型在正文里自行引用。 |
33
+ | **会话标题** | DSH 原生已有标题生成,不需要插件介入。 |
34
+ | **文档 `file_id` 的对话引用** | `chatbot_upload_document` 已能把文档上传到 Files API 并返回 `file_id`,但**「把 `file_id` 作为 document 块引用进对话」这条链路尚未实测**,因此不计入「已验证」。上传本身可用。 |
35
+
36
+ ## 开发与热重载(不要用注入器)
37
+
38
+ 本机已装 `dsh-dev-hotreload`(`Pxczxn/dsh-dev-hotreload`):**保存源码即热替换**,无需重启,也不要调用
39
+ `dev_inject_plugin` / `dev_reload_package`——这两个工具在本机有过「工具调用永不返回、会话卡住」的记录
40
+ (2026-11-04 `dev_reload_package` 卡住一小时;2026-11-17 `dev_inject_plugin` 触发 `defer_loading` 400 事故)。
41
+
42
+ 工作流:
43
+
44
+ ```bash
45
+ # 只改文件,然后等约 1 秒
46
+ # 保存 → 防抖 400ms → tick profile/cordis.patch.yml → dsh-hmr 重组合 → 新 fiber
47
+ ```
48
+
49
+ 判据(两层都要看):
50
+
51
+ 1. `%TEMP%/dsh-dev-hotreload.log` 出现 `change: lib\index.js` 与 `ticked cordis.patch.yml`;
52
+ 2. `~/.dsh/logs/chatbot-tools-safety.ndjson` 出现新的 `{"event":"applied:<BUILD_TAG>:safety=..."}`。
53
+
54
+ `BUILD_TAG` 在 `lib/index.js` 顶部,每次改动递增,用来确认跑的是新代码。
55
+
56
+ > ⚠️ **热重载只对函数体改动有效**。改 `import` / 增删导出 / 改模块级 `const`(包括 `BUILD_TAG` 本身)
57
+ > 都会让 `reload_dsh` 回报 `needs full restart`——必须重启 DSH 才生效。
58
+
59
+ ## 安装
60
+
61
+ ```bash
62
+ dsh plugin --profile <profile> add dsh-chatbot-tools
63
+ ```
64
+
65
+ 本地开发用 link:
66
+
67
+ ```bash
68
+ dsh plugin --profile desktop add link:C:/Users/Admin/dsh-chatbot-tools
69
+ ```
70
+
71
+ **不要**只用运行时注入:匿名 loader entry 没有包身份,不会出现在「插件」页,也不会被
72
+ `dsh-dev-hotreload` 按 profile 依赖自动发现。
73
+
74
+ > 判据:`plugin_manager list_bundles` 里能看到 `dsh-chatbot-tools`
75
+ > (`availability:"profile"`、`installed:true`)才算装好。
76
+
77
+ ## 配置
78
+
79
+ 在 profile patch 的 `config` 覆盖(整行替换,不深合并):
80
+
81
+ | 键 | 默认 | 说明 |
82
+ |---|---|---|
83
+ | `apiKey` | 空 | 平台 API Key。**TTS/ASR 必需**;Search/OCR 可用账号登录。明文存 patch,建议改用宿主凭据 |
84
+ | `apiKeyRef` | `DEEPSEEK_API_KEY` | 宿主凭据服务里的 key 名;DSH 设置里存过的 Key 就在这里 |
85
+ | `safetyMode` | `enforce` | `off` / `observe`(只记录)/ `enforce`(注入 `safety_check`) |
86
+ | `safetyLevel` | `high` | `high` / `low` |
87
+ | `safetyGuardDeferLoading` | `true` | **保持开启**:请求带 `defer_loading` 时跳过注入(事故守卫) |
88
+ | `safetySkipPurposes` | `['title','session-title']` | 内部请求不注入,省费用 |
89
+ | `safetyLog` | `true` | 记 `~/.dsh/logs/chatbot-tools-safety.ndjson`(只记工具形态) |
90
+ | `model` / `maxTokens` / `maxUses` | `deepseek-flash` / `1024` / `1` | 辅助调用与图片搜索的服务端工具参数 |
91
+ | `serverTool` | `deepseek_web_search` | 图片搜索用的服务端工具名 |
92
+ | `maxImageBytes` | `4194304` | 图片大小上限 |
93
+ | `searchCount` | `8` | `chatbot_search` 默认条数 |
94
+ | `ocrPurpose` / `ocrMaxChars` | `text_recognition` / `8000` | OCR 模式与返回上限 |
95
+ | `documentPurpose` | `text_recognition` | 文档上传默认用途(`user_data` 不解析不计费) |
96
+ | `ttsVoice` / `ttsFormat` / `ttsOutDir` / `ttsMaxChars` | `stella` / `wav` / 空(`~/.dsh/chatbot-tools/out`)/ `10000` | 朗读参数 |
97
+ | `ttsFilterMarkdown` | `true` | 朗读前由服务端去掉 Markdown。**代码块不会被朗读**,这是服务端行为,与本开关无关 |
98
+ | `ttsTermMap` | `{}` | 朗读前的中文替换表,JSON 字符串,如 `{"Markdown":"马克当文档"}` |
99
+ | `apiBaseURL` / `messagesBaseURL` / `apiVersion` | 官方地址 | 自建网关时改这里 |
100
+
101
+ **全部可在「设置 → 插件 → dsh-chatbot-tools」里改**:每个字段都标了 `.volatile()`,宿主据此生成表单,
102
+ 改完立即生效(volatile 写进运行中的引用),不需要重载插件。凭证解析顺序:
103
+ `设置里的 apiKey` → `DEEPSEEK_API_KEY` 环境变量 → **宿主凭据服务**(DSH 设置里存过的 Key)→ DeepSeek 账号登录。
104
+
105
+ ## 界面集成(语音)
106
+
107
+ ### 输入:官方语音输入 UI 复用
108
+
109
+ 官方把语音输入拆成三层,本插件只补最底下那层:
110
+
111
+ | 层 | 包 | 说明 |
112
+ |---|---|---|
113
+ | 服务 + provider 注册表 | `@deepseek-ai/dsh-experimental-speech-to-text` | 官方可选 bundle 提供 |
114
+ | Remote 控制器 | `@deepseek-ai/dsh-experimental-api-speech-to-text` | 客户端调用它 |
115
+ | 麦克风 UI | `@deepseek-ai/dsh-experimental-client-ui-voice-input` | 波形、音色/语种选择 |
116
+
117
+ 本插件新增 `lib/speech.js`:把 `/v1/tools/asr` 包成 `SpeechProvider`(id `deepseek-asr`),
118
+ 注册进 `ctx.speechToText`。官方麦克风 UI 会直接列出并使用它,**不需要自己写录音界面**。
119
+
120
+ 启用方式:profile 的 `dsh.profile.bundles` 需含 `@deepseek-ai/dsh-experimental-voice-input-bundle`,
121
+ 语音服务条目 `speech-to-text` 的 `defaultProvider` 设为 `deepseek-asr`。**需重启一次**让该 bundle 的行加载。
122
+
123
+ ### 输出:朗读按钮
124
+
125
+ - 客户端 `client.js` 注册到官方声明的 `conversation.chat.assistant-actions`(每条最终回答的动作行),
126
+ id `chatbot-tts`,显示 🔊。
127
+ - 点击只把 `sessionId` + `messageId` 发给宿主 `GET /chatbot-voice/tts`;
128
+ 宿主从会话日志取出该条 assistant 消息正文,调 TTS 后直接返回 `audio/wav`,页面播放。
129
+ - 好处:客户端不需要理解 Chat 快照结构,长文本也不进 URL。
130
+
131
+ > 实测:桌面渲染进程经 `dsh-app://app` 传输访问该路由正常(播放时流式返回、不落盘);
132
+ > 外部 `curl` 会 403(非应用 peer 被拒),不能用它验证。每次朗读会写一条
133
+ > `tts-ok:chars=..:bytes=..:ms=..` 审计日志到 `~/.dsh/logs/chatbot-tools-safety.ndjson`。
134
+
135
+ ## 工具
136
+
137
+ - `chatbot_search(query, count?)` — Search API,返回带站点/发布时间/权威度的来源。
138
+ - `chatbot_image_search(path, query?)` — 本地图片 → 服务端图片搜索,返回 `image_url` 缩略图与来源页。
139
+ - `chatbot_ocr(path, purpose?)` — PDF/Word/PPT/图片 → 按页文字。
140
+ - `chatbot_upload_document(path, purpose?)` — 本地文档 → Files API `file_id`(≤32 MiB / 解析类 ≤100 MiB)。
141
+ - `chatbot_asr(path)` — 16-bit PCM WAV / Ogg Opus → 文字(≤120s,≤8 MiB)。
142
+ - `chatbot_tts(text, voice?, format?)` — 文本 → 语音文件,返回落盘路径。
143
+ - `chatbot_doctor(live?)` — 自检:构建标记、当前设置、凭证通道;`live:true` 时双模式验证 `safety_check`。
144
+
145
+ ## 成本
146
+
147
+ - `chatbot_search`:Search API 按成功请求计费(¥5 / 1000 次,与 DSH 内置 search 同价)。
148
+ - `chatbot_image_search`:一次完整模型回合 + 1 次服务端工具调用;`maxUses:1` 即上限。
149
+ - `safety_check`:审核 token 计入输出 token(`usage.output_tokens_details.safety_tokens`)。
150
+ - OCR:¥1.5 / 1000 页(按成功页数)。
151
+ - 文档上传:`user_data` 不解析、不计费;`text_recognition` / `rich_layout_recognition` 按页计费。
152
+ - ASR:¥0.39–0.78 / 小时音频(按秒计)。
153
+ - TTS:¥1.5–3 / 10,000 字符(汉字算 2 字符)。
154
+
155
+ ## 已验证 / 未验证
156
+
157
+ 见 `docs/verification-2026-11-17.md`。摘要:
158
+
159
+ - ✅ `safety_check` + 普通工具 200(**仅思考模式**;新会话实测 `decision:"enforce"`)
160
+ - ✅ 非思考模式自动跳过(实测 `thinking=disabled` 同组合 400,故守卫先判 `thinkingEnabled`)
161
+ - ✅ `defer_loading` 请求自动跳过注入(多条请求实测守卫命中,无 400)
162
+ - ✅ 图片 `tool_result` 请求自动跳过注入(**端到端实测**:守卫命中当次请求,下一请求恢复 `enforce`,会话存活)
163
+ - ✅ 图片搜索 15 条结果(含 `image_url`)
164
+ - ✅ 搜索 3 条结构化来源
165
+ - ✅ OCR / TTS / ASR / 文档上传各自实测通过
166
+ - ✅ 卸载:工具立即消失、registry 清空、junction 删除(详见验证文档 §7)
167
+ - ✅ 插件页可见:bundle 安装后 `list_bundles` 出现且 `installed:true`
168
+ - ✅ 单元测试:`npm test` → 21 + 18 项全绿
169
+ - ⚠️ refusal(拒答)**只做了单元测试**(6 例通过):未主动构造违规输入,属策略边界
170
+ - ⚠️ 若真实拒答以 HTTP 400 `Content Exists Risk` 返回,中间件不拦截,表现为普通错误
171
+ - ⚠️ 文档 `file_id` 的对话引用链路未实测(见「不覆盖」表)
172
+
173
+ ## 服务端约束(都不是文档写明的)
174
+
175
+ `deepseekLlmApiExtensions.register('safety_check')` 一旦注入,服务端就会对**整个请求**施加排他性校验。
176
+ 踩中任何一条都返回 400,而且**历史已持久化后无法重试自救**。本插件为每条都实现了守卫:
177
+
178
+ | # | 约束 | 守卫 |
179
+ |---|---|---|
180
+ | 1 | 请求体内不能有 `defer_loading: true` 的工具声明 | `defer-loading-guard` |
181
+ | 2 | 不能在非思考模式(`thinking: disabled`,含标题生成等辅助请求) | `thinking-off` / `purpose-skip` |
182
+ | 3 | 历史里 `tool_result` 只能纯文本(含图片即拒) | `non-text-tool-result` |
183
+
184
+ 守卫优先级:`mode-off` → `purpose-skip` → `thinking-off` → `non-text-tool-result` → `defer-loading-guard` → `observe` → `enforce`。
185
+
186
+ 三条互斥字段 `deepseek_web_search` / `deepseek_read_url` / `safety_check` / `title` 里,**没有一个**是 DSH 核心注入的
187
+ (审计字段 `serverFields` 在每次 `enforce` 请求上都是空数组)。所以第三方插件只要用 `safety_check`,
188
+ 就必须自己承担上面三条的全部守卫义务。完整证据见 `docs/incident-2026-11-17-*.md`。
189
+
190
+ ## 踩坑
191
+
192
+ 1. **热重载后有一步竞态**:重载返回 OK 后,紧接着的一次请求可能报 `unknown tool "chatbot_xxx"`。原因:新 fiber 注册与旧 fiber 释放在同一 tick 竞争。重试一次即恢复;要彻底避免就重启。
193
+ 2. **绝不要在 `safety_check` 注入期间让会话发生工具集变更**:见 `docs/incident-2026-11-17-safety-check-defer-loading.md`。本插件的守卫已覆盖该场景,但守卫本身被关掉时会重演。
194
+ 3. `request.body.tools` 才是扩展契约里工具所在位置;`request.tools` 是文档笔误。
195
+ 4. **patch 行是整体替换 bundle config**,不是逐键合并——加/删配置键时 `cordis.patch.yml` 与 profile patch 要两边一起对。
196
+
197
+ ## 许可
198
+
199
+ MIT © 2026 deepseekv41flash
2
200
 
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.
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