dsh-chatbot-tools 0.2.0 → 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 CHANGED
@@ -3,6 +3,16 @@
3
3
  本文件记录本插件的所有重要变更。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/),
4
4
  版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
5
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
+
6
16
  ## [0.2.0] - 2026-11-18
7
17
 
8
18
  首个公开发布版本。
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,12 +1,13 @@
1
1
  # dsh-chatbot-tools
2
2
 
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)
3
+ [English](README-en.md) · [简体中文](README.md)
6
4
 
7
- 补齐 **DeepSeek Chatbot(官方 chat-demo + build_a_chatbot 套件)有、DSH 缺**的能力。
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
8
 
9
- 中文 | [English](#english)
9
+ > 补齐 **DeepSeek Chatbot(官方 chat-demo + build_a_chatbot 套件)有、DSH 缺**的能力:
10
+ > 内容安全(含 3 条服务端互斥约束的守卫)、联网/图片搜索、OCR、TTS、ASR、文档上传。
10
11
 
11
12
  | 能力 | Chatbot | DSH 原生 | 本插件 |
12
13
  |---|---|---|---|
@@ -197,54 +198,3 @@ dsh plugin --profile desktop add link:C:/Users/Admin/dsh-chatbot-tools
197
198
 
198
199
  MIT © 2026 deepseekv41flash
199
200
 
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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-chatbot-tools",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "把 DeepSeek Chatbot 的能力带进 DeepSeek Harness:内容安全、联网/图片搜索、OCR、TTS、ASR、文档上传",
5
5
  "type": "module",
6
6
  "main": "./lib/index.js",
@@ -14,6 +14,7 @@
14
14
  "cordis.patch.yml",
15
15
  "client.js",
16
16
  "README.md",
17
+ "README-en.md",
17
18
  "CHANGELOG.md",
18
19
  "LICENSE",
19
20
  "docs"