dsh-deepseek-tools 0.0.0-stage → 0.1.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/README.md CHANGED
@@ -1,3 +1,48 @@
1
- # Temporary Holding Version
1
+ # dsh-deepseek-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
+ DSH Web 插件,提供 DeepSeek 的语音合成、语音识别、OCR 和文件解析,并在输入框旁加一个语音按钮。
4
+
5
+ 包名 `dsh-deepseek-tools`,版本 0.1.0,要求 DSH `>=0.2.2-rc.3 <0.3.0`。
6
+
7
+ ## 四个工具
8
+
9
+ | 工具 | 用途 | 返回 |
10
+ | --- | --- | --- |
11
+ | `deepseek_tts` | 文本合成语音 | 工作区里的 wav 或 pcm 文件路径 |
12
+ | `deepseek_asr` | 音频转文字 | 转写文本和时长 |
13
+ | `deepseek_ocr` | PDF、Office 文档、图片取字 | 按页合并的文本 |
14
+ | `deepseek_file_parse` | 上传文件到 DeepSeek Files API | `file_id` |
15
+
16
+ 参数、上限、示例见 [docs/tools.md](docs/tools.md)。
17
+
18
+ ## 语音按钮
19
+
20
+ 按钮注册在 `conversation.input.activity`,位于输入区的工具条,模型选择器旁边。`asrEnabled` 关掉后按钮不渲染。
21
+
22
+ 点一下开始录音,再点一下停止。录满 120 秒会自动停,音频超过 8 MiB 不会上传。转写结果插到输入框光标处;如果转写期间草稿被改过,输入框旁会多出一个“插入”按钮,由你决定放不放。浏览器需要麦克风权限。
23
+
24
+ ## 设置页
25
+
26
+ 入口是“设置 → DeepSeek 工具”。页面上有 API key、Base URL、四个工具开关和专业模式。API key 存进 DSH credentials,不写进插件 config;没配 key 时工具会报错。专业模式打开后才出现音色、格式、purpose、超时这些参数。
27
+
28
+ 字段和默认值见 [docs/configuration.md](docs/configuration.md)。
29
+
30
+ ## 安装
31
+
32
+ 在 Plugins 页安装并启用,重启 DSH。命令行安装要多一步:`dsh plugin --profile web add dsh-deepseek-tools` 只加依赖,还要把包名写进 profile 的 `dsh.profile.bundles`。
33
+
34
+ 步骤和卸载见 [docs/install.md](docs/install.md)。
35
+
36
+ ## 配置
37
+
38
+ Base URL 默认 `https://api.deepseek.com`,API key 默认使用的 credentials 名字是 `DEEPSEEK_API_KEY`。四个工具默认开启,专业模式默认关闭。
39
+
40
+ ## 平台与版本
41
+
42
+ 设置页和语音按钮只在 DSH Web 里出现。工具由 host 执行,Windows、Linux、macOS 通用,不依赖固定安装路径。
43
+
44
+ ## 已知限制
45
+
46
+ `deepseek_file_parse` 只上传文件并返回 `file_id`,不返回解析文本,也不会把文件注入当前对话;要看文字用 `deepseek_ocr`。OCR 文本超过 `maxChars`(默认 50000)会截断,`text` 末尾有截断标记。
47
+
48
+ 插件按 DeepSeek 官方协议发请求。`baseURL` 可以换成代理地址,路径和字段不会跟着变。语音按钮需要 DSH Web 和麦克风权限,TUI 里没有这个按钮。
@@ -0,0 +1,13 @@
1
+ - insert:
2
+ - id: deepseek-speech-to-text
3
+ name: '@deepseek-ai/dsh-experimental-speech-to-text'
4
+ config:
5
+ defaultProvider: deepseek
6
+ language: auto
7
+ - id: deepseek-speech-api
8
+ name: '@deepseek-ai/dsh-experimental-api-speech-to-text'
9
+ config:
10
+ maxAudioBytes: 8388608
11
+ maxDurationSeconds: 120
12
+ - id: dsh-deepseek-tools
13
+ name: dsh-deepseek-tools
@@ -0,0 +1,62 @@
1
+ # 配置
2
+
3
+ 入口是“设置 → DeepSeek 工具”。页面底部有“保存”和“放弃更改”两个按钮,没改过东西时都是灰的。保存后配置写进 profile,插件按新配置重新应用,通常不用重启。
4
+
5
+ ## 基本字段
6
+
7
+ | 字段 | 默认值 | 说明 |
8
+ | --- | --- | --- |
9
+ | API key | 空 | 密码输入框。内容写入 DSH credentials,不进 config。 |
10
+ | Base URL | `https://api.deepseek.com` | 只接受 http 或 https,结尾的斜杠会去掉。 |
11
+ | 语音合成(TTS) | 开 | 控制 `deepseek_tts` 是否注册。 |
12
+ | 语音识别(ASR) | 开 | 控制 `deepseek_asr` 是否注册,同时决定语音按钮显不显示。 |
13
+ | OCR | 开 | 控制 `deepseek_ocr` 是否注册。 |
14
+ | 文件解析 | 开 | 控制 `deepseek_file_parse` 是否注册。 |
15
+
16
+ 关掉的工具不会出现在工具列表里。语音按钮由客户端读 `asrEnabled`,关掉后立即隐藏。
17
+
18
+ Base URL 可以改成代理或网关地址。插件只在它后面拼 `/v1/tools/tts`、`/v1/tools/asr`、`/v1/tools/ocr` 和 `/files`,代理要按这些路径转发。
19
+
20
+ ## 专业模式
21
+
22
+ 专业模式默认关闭,勾选框下面有一行提示:
23
+
24
+ > 适合正在调试的开发者,普通用户请谨慎勾选
25
+
26
+ 关闭时只看到 API key、Base URL、四个工具开关和专业模式勾选框。打开后才出现 `apiKeyEnv`、`ttsVoiceId`、`ttsFormat`、`ttsFilterMarkdown`、`ocrPurpose`、`filePurpose`、`timeoutSeconds`。
27
+
28
+ ## API key 与密钥环境变量
29
+
30
+ API key 输入框只在点“保存”时写入 DSH credentials,名字取 `apiKeyEnv` 的值。config 里没有密钥字段,profile 的配置文件里不会出现明文。
31
+
32
+ `apiKeyEnv` 默认 `DEEPSEEK_API_KEY`,首字符必须是字母或下划线,后面可以跟字母、数字、下划线。改这个值等于换一个 credentials 名字:页面上的“已配置/未配置”会按新名字重新查,之前存的 key 不会跟着搬过去,需要重新填一次。
33
+
34
+ 没配 key 时,设置页显示“未配置”,工具调用会报 `DeepSeek API key is not configured (<名字>)`,后面还跟着一句去设置页添加的提示。
35
+
36
+ ## 专业参数
37
+
38
+ | 字段 | 默认值 | 说明 |
39
+ | --- | --- | --- |
40
+ | `apiKeyEnv` | `DEEPSEEK_API_KEY` | credentials 里的名字。 |
41
+ | `ttsVoiceId` | `stella` | 另一个可选值是 `tide`。 |
42
+ | `ttsFormat` | `wav` | `pcm` 是裸流,24 kHz、16-bit、单声道,没有文件头。 |
43
+ | `ttsFilterMarkdown` | 开 | 合成前去掉 Markdown 标记。 |
44
+ | `ocrPurpose` | `text_recognition` | 另一个值是 `rich_layout_recognition`,保留版面标记。 |
45
+ | `filePurpose` | `user_data` | 另外两个值是 `text_recognition` 和 `rich_layout_recognition`,按 OCR 计费。 |
46
+ | `timeoutSeconds` | `180` | 范围 5 到 600,单次 HTTP 请求的超时。 |
47
+
48
+ 工具调用时传的参数会覆盖这里的默认值。例如 `deepseek_tts` 传了 `voiceId`,就用传进来的那个。
49
+
50
+ ## 超时
51
+
52
+ `timeoutSeconds` 卡的是单次 HTTP 请求。工具本身还有 300 秒的执行上限,哪个先到算哪个。把它调到 300 以上没有意义,工具到 300 秒就结束了。
53
+
54
+ ## TTS 音色与格式
55
+
56
+ `stella` 是默认音色,`tide` 是另一个可选音色。`wav` 能直接播放;`pcm` 是裸音频流,播放器普遍不认,得自己加头,或者用 `ffplay -f s16le -ar 24000 -ac 1 out.pcm` 打开。
57
+
58
+ ## OCR 与文件 purpose
59
+
60
+ `text_recognition` 只取文字。`rich_layout_recognition` 会在结果里保留 `<|ref|>` 和 `<|box|>` 标记,适合要还原版面的场景。
61
+
62
+ 文件解析的 `user_data` 适合文本、Markdown、CSV、JSON、代码、XLSX、EPUB 这类文件,上限 32 MiB。文件解析选两个 OCR purpose 时,上限是 100 MiB。
@@ -0,0 +1,39 @@
1
+ # 安装
2
+
3
+ ## 方式一:Plugins 页
4
+
5
+ 在 DSH Web 的 Plugins 页安装并启用 `dsh-deepseek-tools`,然后重启 DSH。profile 里的 bundle 条目由页面处理,不用手改。
6
+
7
+ ## 方式二:CLI
8
+
9
+ ```bash
10
+ dsh plugin --profile web add dsh-deepseek-tools
11
+ ```
12
+
13
+ 这步只装依赖,不会把插件加进 bundle 列表。还要编辑 `$DSH_HOME/profiles/web/package.json`,在 `dsh.profile.bundles` 数组末尾加一项 `"dsh-deepseek-tools"`,和前面的条目用逗号隔开。原有条目不要动,改完重启 DSH。
14
+
15
+ ## 为什么要带两个语音包
16
+
17
+ 依赖里有 `@deepseek-ai/dsh-experimental-speech-to-text` 和 `@deepseek-ai/dsh-experimental-api-speech-to-text`。前者提供 `speechToText` 服务,后者提供浏览器侧的 remote,语音按钮用 `ctx.remote.speech.transcribe` 把录音交给 host。
18
+
19
+ 插件的 `cordis.patch.yml` 在启动时插入这两个服务,配置为 `defaultProvider: deepseek`、`language: auto`、`maxAudioBytes: 8388608`、`maxDurationSeconds: 120`。插件自己注册 id 为 `deepseek` 的 provider,语音按钮通过 DSH 的语音服务转写。
20
+
21
+ 两个包都是 experimental,版本固定在 `0.2.2-rc.3`。`@deepseek-ai/cordis`、`@deepseek-ai/dsh-credentials`、`@deepseek-ai/dsh-fs`、`@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-working-directory` 是 peer 依赖,由 host 提供,插件不自带。
22
+
23
+ ## 重启与热更新
24
+
25
+ bundle patch 在启动时应用。安装、升级、卸载之后都要重启 DSH,否则工具和设置页不会出现。
26
+
27
+ 设置页里保存的配置不用重启,保存后插件按新配置重新应用。如果界面没跟上,刷新页面。
28
+
29
+ 客户端代码在页面加载时取。插件升级后要刷新页面,拿到的才是新代码。开发时如果 DSH checkout 里跑着 `pnpm run dev:web`,客户端插件的改动可以热更新;从 npm 安装的版本只有刷新页面这一条路。
30
+
31
+ ## 卸载
32
+
33
+ 在 Plugins 页停用并移除。用 CLI 的话,先从 `dsh.profile.bundles` 里删掉 `dsh-deepseek-tools`,重启 DSH,再移除包:
34
+
35
+ ```bash
36
+ dsh plugin --profile web remove dsh-deepseek-tools
37
+ ```
38
+
39
+ 已保存的 API key 在 DSH credentials 里,卸载不会删掉它。插件没有删除 key 的入口。
package/docs/tools.md ADDED
@@ -0,0 +1,104 @@
1
+ # 工具参考
2
+
3
+ 四个工具都由 host 注册,路径参数相对会话工作目录解析。文件超过上限时直接报错,不会截断上传。工具单次执行最多 300 秒,HTTP 请求还受设置页 `timeoutSeconds` 限制。
4
+
5
+ ## deepseek_tts
6
+
7
+ 把文本合成语音,写到工作区。
8
+
9
+ | 参数 | 类型 | 必填 | 说明 |
10
+ | --- | --- | --- | --- |
11
+ | `text` | string | 是 | 要合成的文本,上限 10000 个计费字符。 |
12
+ | `path` | string | 否 | 输出路径,相对工作目录。默认 `deepseek-tts-<时间戳>.wav` 或 `.pcm`。 |
13
+ | `voiceId` | string | 否 | `stella` 或 `tide`,默认取设置页。 |
14
+ | `format` | string | 否 | `wav` 或 `pcm`,默认取设置页。 |
15
+ | `filterMarkdown` | boolean | 否 | 合成前去掉 Markdown,默认取设置页。 |
16
+
17
+ 请求走 `POST /v1/tools/tts`,JSON 体里是 `text`、`voice_id`、`format`、`filter_markdown`。整个 JSON 体不能超过 64 KiB,超了会提示缩短文本或关掉 Markdown 过滤。返回 `{ path, format, bytes }`,`path` 是 host 上的实际路径。
18
+
19
+ `pcm` 输出是 24 kHz、16-bit、单声道的裸流,没有 WAV 头。
20
+
21
+ 示例:
22
+
23
+ ```json
24
+ {
25
+ "text": "第一段测试语音,用来检查音色。",
26
+ "voiceId": "stella",
27
+ "format": "wav",
28
+ "path": "audio/intro.wav"
29
+ }
30
+ ```
31
+
32
+ ## deepseek_asr
33
+
34
+ 把音频文件转成文字。
35
+
36
+ | 参数 | 类型 | 必填 | 说明 |
37
+ | --- | --- | --- | --- |
38
+ | `path` | string | 是 | 音频路径,相对工作目录。 |
39
+ | `language` | string | 否 | 不会发给服务端,服务端自动识别语言。 |
40
+
41
+ 请求走 `POST /v1/tools/asr`,multipart 上传。支持 16-bit PCM 的 WAV(采样率 8k、16k、22.05k、24k、32k、44.1k、48k)和 Ogg Opus。文件不超过 8 MiB,时长不超过 120 秒。
42
+
43
+ 返回 `{ text, durationMs }`。服务端不返回时长时,结果里没有 `durationMs`。
44
+
45
+ 示例:
46
+
47
+ ```json
48
+ { "path": "recordings/meeting.ogg" }
49
+ ```
50
+
51
+ ## deepseek_ocr
52
+
53
+ 从文档或图片里取字。
54
+
55
+ | 参数 | 类型 | 必填 | 说明 |
56
+ | --- | --- | --- | --- |
57
+ | `path` | string | 是 | 文件路径,相对工作目录。 |
58
+ | `purpose` | string | 否 | `text_recognition` 或 `rich_layout_recognition`,默认取设置页。 |
59
+ | `maxChars` | integer | 否 | 返回文本上限,默认 50000,允许 1000 到 500000。 |
60
+
61
+ 请求走 `POST /v1/tools/ocr`,multipart 上传,`purpose` 放在 `file` 前面。支持 PDF、DOC、DOCX、PPT、PPTX、PNG、JPEG、WebP、GIF、BMP、TIFF,文件不超过 100 MiB,页数不超过 1000。
62
+
63
+ 返回 `pageCount`、`text`、`truncated`、`pages`,有时还带 `id`。`text` 按页拼接,页与页之间是 `--- page N ---`,N 从 1 开始。超长时截到 `maxChars`,末尾带 `[truncated after <maxChars> characters]`,同时 `truncated` 为 `true`。`pages` 里每页有 `index`、`finishReason`、`chars`。
64
+
65
+ 选 `rich_layout_recognition` 时,文本里会保留 `<|ref|>` 和 `<|box|>` 标记。
66
+
67
+ 示例:
68
+
69
+ ```json
70
+ {
71
+ "path": "papers/report.pdf",
72
+ "purpose": "rich_layout_recognition",
73
+ "maxChars": 20000
74
+ }
75
+ ```
76
+
77
+ ## deepseek_file_parse
78
+
79
+ 把文件传到 DeepSeek Files API,拿一个 `file_id`。
80
+
81
+ | 参数 | 类型 | 必填 | 说明 |
82
+ | --- | --- | --- | --- |
83
+ | `path` | string | 是 | 文件路径,相对工作目录。 |
84
+ | `purpose` | string | 否 | `user_data`、`text_recognition` 或 `rich_layout_recognition`,默认取设置页。 |
85
+
86
+ 请求走 `POST /files`,multipart 上传,`purpose` 放在 `file` 前面。`user_data` 适合文本、Markdown、CSV、JSON、代码、XLSX、EPUB,上限 32 MiB;另外两个 purpose 上限 100 MiB。返回 `{ fileId, filename, bytes, purpose }`。
87
+
88
+ 这个工具只上传,不返回解析文本,也不能下载原文件或解析结果。要在对话里引用,得自己把下面这段放进请求:
89
+
90
+ ```json
91
+ {"type":"document","source":{"type":"file","file_id":"<fileId>"}}
92
+ ```
93
+
94
+ 工具不会自动注入。想直接看文本,用 `deepseek_ocr`。
95
+
96
+ 示例:
97
+
98
+ ```json
99
+ { "path": "data/notes.xlsx" }
100
+ ```
101
+
102
+ ## 常见错误
103
+
104
+ 缺 key 时返回 `DeepSeek API key is not configured (<名字>)`,去设置页补上。文件过大、格式不对、超时,都会以错误文本返回,带上 HTTP 状态和 DeepSeek 的 `error.message`。
package/lib/api.js ADDED
@@ -0,0 +1,119 @@
1
+ import fs from 'node:fs/promises'
2
+ import path from 'node:path'
3
+ import { credentialRef } from '@deepseek-ai/dsh-credentials'
4
+
5
+ export const DEEPSEEK_DEFAULT_BASE_URL = 'https://api.deepseek.com'
6
+ export const DEEPSEEK_DEFAULT_KEY_ENV = 'DEEPSEEK_API_KEY'
7
+
8
+ export function baseURL(config) {
9
+ const value = (config.baseURL || DEEPSEEK_DEFAULT_BASE_URL).trim().replace(/\/+$/, '')
10
+ let url
11
+ try {
12
+ url = new URL(value)
13
+ } catch {
14
+ throw new Error(`Invalid DeepSeek base URL: ${value}`)
15
+ }
16
+ if (url.protocol !== 'https:' && url.protocol !== 'http:') {
17
+ throw new Error(`DeepSeek base URL must use http or https: ${value}`)
18
+ }
19
+ return value
20
+ }
21
+
22
+ export function keyEnv(config) {
23
+ return (config.apiKeyEnv || DEEPSEEK_DEFAULT_KEY_ENV).trim()
24
+ }
25
+
26
+ export async function resolveApiKey(ctx, config) {
27
+ const ref = keyEnv(config)
28
+ let resolved
29
+ try {
30
+ resolved = await ctx.credentials.resolve(credentialRef(ref))
31
+ } catch (error) {
32
+ throw new Error(`Cannot read credential ${ref}: ${error instanceof Error ? error.message : String(error)}`)
33
+ }
34
+ if (!resolved?.value) {
35
+ throw new Error(`DeepSeek API key is not configured (${ref}). Add it in Settings > DeepSeek Tools.`)
36
+ }
37
+ return resolved.value
38
+ }
39
+
40
+ export function requestSignal(signal, timeoutMs) {
41
+ const timeout = AbortSignal.timeout(Math.max(1, timeoutMs))
42
+ return signal === undefined ? timeout : AbortSignal.any([signal, timeout])
43
+ }
44
+
45
+ export async function responseError(response) {
46
+ let text = ''
47
+ try {
48
+ text = await response.text()
49
+ } catch {
50
+ return `DeepSeek HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ''}`
51
+ }
52
+ let detail = text.trim()
53
+ try {
54
+ const parsed = JSON.parse(text)
55
+ detail = parsed?.error?.message || parsed?.message || detail
56
+ } catch {
57
+ // Plain text or an incomplete response; keep the body excerpt.
58
+ }
59
+ if (detail.length > 800) detail = `${detail.slice(0, 800)}…`
60
+ return `DeepSeek HTTP ${response.status}${response.statusText ? ` ${response.statusText}` : ''}${detail ? `: ${detail}` : ''}`
61
+ }
62
+
63
+ export async function request(ctx, config, route, init, signal) {
64
+ const key = await resolveApiKey(ctx, config)
65
+ const url = `${baseURL(config)}${route}`
66
+ const response = await fetch(url, {
67
+ ...init,
68
+ headers: {
69
+ ...(init?.body instanceof FormData ? {} : { 'content-type': 'application/json' }),
70
+ authorization: `Bearer ${key}`,
71
+ ...init?.headers,
72
+ },
73
+ signal: requestSignal(signal, (config.timeoutSeconds || 180) * 1000),
74
+ })
75
+ if (!response.ok) throw new Error(await responseError(response))
76
+ return response
77
+ }
78
+
79
+ export async function requestJson(ctx, config, route, body, signal) {
80
+ const response = await request(ctx, config, route, {
81
+ method: 'POST',
82
+ body: JSON.stringify(body),
83
+ }, signal)
84
+ return response.json()
85
+ }
86
+
87
+ export async function upload(ctx, config, route, { purpose, bytes, filename, mime }, signal) {
88
+ const form = new FormData()
89
+ // The Files API requires purpose before file; keeping that order everywhere
90
+ // costs nothing and keeps multipart handling consistent.
91
+ if (purpose !== undefined) form.append('purpose', purpose)
92
+ form.append('file', new Blob([bytes], { type: mime || 'application/octet-stream' }), filename)
93
+ const response = await request(ctx, config, route, { method: 'POST', body: form }, signal)
94
+ return response
95
+ }
96
+
97
+ export async function resolveWorkspaceFile(ctx, exec, requested, maxBytes) {
98
+ const cwd = exec.agent === undefined
99
+ ? undefined
100
+ : await ctx.workingDirectory.ensure(exec.agent, exec.signal)
101
+ const target = await ctx.fs.resolve(requested, { cwd, signal: exec.signal })
102
+ const bytes = await ctx.fs.readBytes(target, exec.signal, maxBytes + 1)
103
+ if (bytes.byteLength > maxBytes) {
104
+ throw new Error(`File is larger than the ${Math.round(maxBytes / 1024 / 1024)} MiB limit: ${requested}`)
105
+ }
106
+ const hostPath = ctx.fs.processPath(target)
107
+ return { bytes, hostPath, filename: path.basename(hostPath) }
108
+ }
109
+
110
+ export async function writeWorkspaceFile(ctx, exec, requested, bytes) {
111
+ const cwd = exec.agent === undefined
112
+ ? undefined
113
+ : await ctx.workingDirectory.ensure(exec.agent, exec.signal)
114
+ const target = await ctx.fs.resolve(requested, { cwd, signal: exec.signal })
115
+ const hostPath = ctx.fs.processPath(target)
116
+ await fs.mkdir(path.dirname(hostPath), { recursive: true })
117
+ await fs.writeFile(hostPath, bytes, { signal: exec.signal })
118
+ return hostPath
119
+ }