dsh-external-toolbox 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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 dsh-external-toolbox contributors
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,190 @@
1
- # Temporary Holding Version
1
+ # dsh-external-toolbox(外部工具箱)
2
+
3
+ 在任意 Windows 程序里选中一段文字 → 光标旁浮出一小条工具条 → 就地翻译,或把原文引用进 DSH 输入框继续提问。
4
+ 不限于翻译:后续的取词类动作也会挂在这条工具条上。
5
+
6
+ ## 用法
7
+
8
+ - **不用快捷键**:鼠标拖选 / 双击选词 / Ctrl+A / Shift+方向键选中后,约 0.2 秒弹出小工具条。
9
+ - 小工具条只有「翻译 / 提问 / 关闭」。点「翻译」才弹出完整卡片(原文 + 译文 + 复制译文),此时请求才真正发给模型,省 token。
10
+ - **Esc** 关闭卡片 / 工具条 / 语言菜单(由低级键盘钩子截获,不会传给下面的程序)。
11
+ - 兜底热键 **Ctrl+Alt+Q**(自动弹卡失灵时用)。
12
+ - 「提问」会把选区以引用块预填进 DSH 的 composer,并把 DSH 窗口唤到前台。
13
+
14
+ ## 语言
15
+
16
+ - 默认 **AUTO**:中日韩文本译成英文,其余(英文/西文/数字)译成中文。
17
+ - 卡片右上角下拉框可固定目标语言:AUTO / ZH / EN / JA / KO / ES / FR / DE / RU / PT / IT;切换后已有译文会立刻重译。
18
+
19
+ ## 组成
20
+
21
+ | 文件 | 作用 |
22
+ | --- | --- |
23
+ | `lib/index.js` | host 半边:注册 `/toolbox/latest`、`/toolbox/translate`、`/toolbox/beat`,拉起 helper 子进程 |
24
+ | `lib/client.js` | 浏览器半边:轮询 latest,把选区填进 composer |
25
+ | `helper/capture.ps1` | PowerShell 助手:全局鼠标/键盘钩子、UIA 取词、浮窗 UI、激活 DSH |
26
+ | `locale/*.json` | 插件市场里显示的标题与描述 |
27
+ | `icon.png` | 插件图标 |
28
+
29
+ ## 改代码时注意
30
+
31
+ - `helper/capture.ps1` **必须保持纯 ASCII**(中文一律用码点:`U 0x5212, 0x8BCD`),否则 PowerShell 5.1 会按 GBK 解析而报语法错。
32
+ - 改完 helper 要同时校验两层:`[Parser]::ParseFile($path)` 与 `ParseInput($here-string body)`。
33
+ - 改 C# 块后跑一次 `-ActivateTest`,否则只在运行时暴露编译错误。
34
+ - 临时测试脚本一律用 ASCII 路径 `D:\Document\deepseek-harness\dsh-select-translate\...`(中文路径在 ASCII 编码保存时会被写成 `????`)。
35
+ ## "Ask" opens a new session
2
36
 
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.
37
+ The browser half looks up the client service `uiWorkspace` (registered by
38
+ `@deepseek-ai/dsh-client-ui-workspace`, the same object the sidebar's
39
+ `session.new` shortcut calls) and invokes `startSession()`. The quote is then
40
+ written into the composer of whatever session the seat re-mounts for.
41
+
42
+ If that service is missing (other DSH builds), the client falls back to
43
+ `history.pushState` on a `/session...` route and, failing that, writes into the
44
+ current session's composer. `client apply uiWorkspace=startSession ...` lines in
45
+ `%TEMP%\dsh-external-toolbox-host.log` show what the probe found at startup.
46
+ ## Actions
47
+
48
+ The pill offers `翻译` / `解释` / `提问`; the card repeats the three plus a copy
49
+ button, and the header's language menu picks the target language.
50
+
51
+ Both text actions hit the same host handler:
52
+
53
+ ```
54
+ GET /toolbox/run?id=<captureId>&task=translate|explain&to=<lang>
55
+ ```
56
+
57
+ `/toolbox/translate` is kept for older helpers and always means `task=translate`.
58
+ `to=auto` means "translate into the opposite language" for `translate`, and
59
+ "explain in Chinese" for `explain` (an explanation is for the reader, not for a
60
+ language pair). The host answers `{ ok, task, target, auto, text }`.
61
+ ## Vocabulary book
62
+
63
+ `收藏` on the card appends the pair to
64
+
65
+ ```
66
+ %APPDATA%\dsh-external-toolbox\vocab.jsonl one JSON object per line
67
+ %APPDATA%\dsh-external-toolbox\生词本.md readable mirror, rebuilt on every save
68
+ ```
69
+
70
+ The helper forwards it as a `{"type":"vocab", word, translation, lang, task}` line
71
+ on stdout; the host writes the files. The same book is readable over HTTP:
72
+
73
+ ```
74
+ GET /toolbox/vocab -> { ok, count, file, entries }
75
+ GET /toolbox/vocab?word=&translation=&lang= -> { ok, count } (saves one pair)
76
+ ```
77
+
78
+ Saving the same word twice within a minute is treated as a double click and
79
+ ignored.
80
+
81
+ ## Reading the translation aloud
82
+
83
+ The host half is not involved: after a successful `translate` the helper speaks
84
+ the result with `System.Speech`. It picks a `zh-` or `en-` voice when the machine
85
+ has one and stays silent otherwise (`explain` never speaks). Pass `-NoSpeak` to
86
+ the helper for tests.
87
+ ## Reviewing (spaced repetition)
88
+
89
+ `生词` on the pill (and in the card header) opens the review window: it shows one
90
+ word, you recall the meaning yourself, `看答案` reveals it, then grade it
91
+ `忘了 / 模糊 / 记得`. The word is written back with its next due date.
92
+
93
+ ```
94
+ GET /toolbox/review -> next due card
95
+ GET /toolbox/review?word=<w>&grade=again|hard|good -> grade it, next card
96
+ ```
97
+
98
+ Scheduling keeps three numbers per word (`interval` days, `ease`, `reps`):
99
+
100
+ | grade | next due | effect |
101
+ | --- | --- | --- |
102
+ | `again` | +10 minutes | `reps = 0`, `ease - 0.2` |
103
+ | `hard` | +1 day | `ease - 0.15` |
104
+ | `good` | `reps = 1 → 1d`, `2 → 3d`, else `interval × ease` (max 120d) | `reps + 1` |
105
+
106
+ Only words whose `due` has passed come up; when nothing is due the window says
107
+ so and shows the total. The JSONL stays append-only (the latest record per word
108
+ wins), so the file remains diff-able and the Markdown mirror is always the
109
+ freshest view.
110
+ ### Richer entries
111
+
112
+ Saving a word takes the translation the card already has, then asks the model for
113
+ a compact dictionary entry in the background and appends it to the same record:
114
+
115
+ ```
116
+ 词性: n.
117
+ 释义: 意外发现美好事物的运气; 机缘巧合
118
+ 例句: Meeting her was pure serendipity.
119
+ 译文: 遇见她纯属机缘巧合。
120
+ 搭配: serendipitous (adj.); by serendipity
121
+ ```
122
+
123
+ The review window shows that when you reveal the answer, the Markdown mirror
124
+ gets one section per word, and words saved before this existed are backfilled the
125
+ first time they come up in review. No model selected means no detail — the card
126
+ just keeps the plain translation.
127
+
128
+ The `文件` button opens the Markdown with notepad: `.md` has no default handler on
129
+ many machines, and a silent failure there looked like "the file cannot be opened".
130
+ ### Picking single words out of a sentence
131
+
132
+ Select a word inside the source pane and press `收藏`: the helper sends that word
133
+ with the full sentence as `context`, so the entry is about the word *as used
134
+ there*. With no selection it saves the whole capture, as before.
135
+
136
+ The review window shows the sentence under the word and its `▶` reads the word
137
+ plus the example line from the enriched entry, so a card is one click away from
138
+ being heard.
139
+ ## Speaking
140
+
141
+ The `▶` next to each pane, and the one next to the word in the review window,
142
+ speak the text. Windows' built-in SAPI voices (Huihui / Zira) sound robotic, so
143
+ speech goes through the Edge neural endpoint instead:
144
+
145
+ ```
146
+ node pkg/tools/say.mjs --text-file <in.txt> <out.mp3> [voice]
147
+ ```
148
+
149
+ `msedge-tts` is a normal dependency of this package (no API key needed); the
150
+ helper writes the text to a temp file, runs that script, and plays the mp3 with
151
+ WPF's `MediaPlayer`. Voices: `zh-CN-XiaoxiaoNeural` for Chinese,
152
+ `en-US-AriaNeural` for everything else. If node, the module, or the network is
153
+ missing, it falls back to SAPI and says nothing about it — a silent failure to
154
+ speak should never block the card.
155
+
156
+ In the review window the example sentence is only read **after** you reveal the
157
+ answer: hearing it early would give the meaning away.
158
+ ### Why the terminal never sees ^C
159
+
160
+ When UIA cannot report a selection, the helper falls back to copying: it clears
161
+ the clipboard, sends Ctrl+C, and reads the result back. In a terminal Ctrl+C is
162
+ an interrupt, so that fallback painted `^C` into the user's shell — and since a
163
+ copy can never succeed there, every gesture retried it.
164
+
165
+ Two guards now apply before any clipboard poke:
166
+
167
+ 1. `Test-KeyboardSurface` — true for console windows (`ConsoleWindowClass`,
168
+ `CASCADIA_HOSTING_WINDOW_CLASS`, mintty), terminal processes (`WindowsTerminal`,
169
+ `conhost`, `cmd`, `powershell`, `pwsh`, `bash`, `wsl`, `wt`), and for the
170
+ `xterm-helper-textarea` that xterm.js focuses inside VS Code / VS Code forks.
171
+ Selection capture simply gives up there rather than interrupting the shell.
172
+ 2. A 3 second cooldown (`$script:clipBlockedUntil`) after a failed copy, so the
173
+ gesture retries do not fire another Ctrl+C.
174
+
175
+ `-SurfaceTest` prints what the guard sees for the window in front:
176
+
177
+ ```
178
+ {"proc":"Doubao","class":"Chrome_WidgetWin_1","console":false,"keyboard":false,...}
179
+ ```
180
+ ### Copying
181
+
182
+ The pill's `复制` puts the captured selection on the clipboard and closes the
183
+ pill — useful when the text lives in an app that copies awkwardly, and the only
184
+ way to get it out is to paste it somewhere else.
185
+
186
+ Inside a terminal the copy chord changes: `Ctrl+C` is an interrupt there, so the
187
+ helper sends `Ctrl+Insert` instead (a copy binding that never reaches the shell).
188
+ When the terminal hides its selection from UI Automation and that chord still
189
+ produces nothing, capture gives up and the 3 second cooldown keeps further
190
+ gestures from poking the shell.
@@ -0,0 +1,9 @@
1
+ # dsh-external-toolbox bundle patch: inserts this plugin into a profile's roster.
2
+ #
3
+ # The row addresses the plugin by PACKAGE NAME: the node half (exports ".")
4
+ # runs in the host process and owns the global hotkey helper plus the
5
+ # /toolbox/latest route; the `dsh.client` declaration in package.json makes
6
+ # the browser half (exports "./client") load as /plugins/dsh-external-toolbox/client.js.
7
+ - insert:
8
+ - id: dsh-external-toolbox
9
+ name: 'dsh-external-toolbox'