Skip to content
Back to search

dsh-deepseek-vision

Vision-language gateway plugin for DeepSeek Harness - paste an image, DeepSeek sees text

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/siegfly--dsh-deepseek-vision/badge.svg)](/listings/siegfly--dsh-deepseek-vision)

HTML

<a href="/listings/siegfly--dsh-deepseek-vision"><img src="/api/listings/siegfly--dsh-deepseek-vision/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

安装走**官方 bundle 机制**:本包在 `package.json` 声明 `dsh.bundle.patch`(指向包内 `cordis.patch.yml`),`dsh plugin add` 把包链接进 profile 并把包名对账进 profile manifest 的 `dsh.profile.bundles` 层栈,loader 启动时按层挂载——**不需要手工往 `cordis.patch.yml` 加任何行**(旧版本加过的受管块会在下次安装/卸载时自动迁移移除)。

四种 spec 任选(日常推荐 git 形式,锁 commit):

dsh plugin --profile web add github:siegfly/dsh-deepseek-vision#<sha>       # git(推荐),锁 commit
dsh plugin --profile web add dsh-deepseek-vision@0.1.7             # npm(已发布 0.1.7,显式锁版本)
dsh plugin --profile web add file:<本仓库路径>                        # 本地目录(开发)
dsh plugin --profile web add ./dsh-deepseek-vision-0.1.7.tgz              # tarball(npm pack 产物)

headless 同理:`dsh plugin --profile headless add dsh-deepseek-vision`(客户端卡片只在 web 生效)。验证 bundle 层已挂载:`dsh --profile web --dump-config | grep llm-vl-gateway`。 卸载与安装一一对应:`dsh plugin --profile <name> remove dsh-deepseek-vision`。

无 CLI 的机器用等价复刻(需 Node 22.19+ 或 24+、PATH 里有 `pnpm`;init 布局 → 目标机 重建 → 兼容门禁 → pnpm add → bundles 对账):

pnpm install        # 只装 devDeps(typescript/vitest),不会装 @deepseek-ai/*
pnpm install-profile          # 或 node scripts/install-profile.mjs [profile] [dshHome]

这是唯一在目标机重建的安装路径:`install-profile` 先用目标机自己的 dsh 类型重新构建 插件并通过 `check-compat.mjs` 门禁,再装入 profile(见[版本对齐](#版本对齐))。 两条路径都做下面两件事:

- 把 `dsh-deepseek-vision` 链接进 profile 的 node_modules(运行时 `@deepseek-ai/*` 依赖经 官方 healed fallback 解析到**同一个** dsh 安装,共享同一个 cordis 实例,无双实例问题); - 把 `dsh-deepseek-vision` 对账进 `dsh.profile.bundles`——loader 按层挂载包内 `cordis.patch.yml` 的 insert 行(注册路由 + 设置段); - 首次安装时如 profile 布局缺失,按官方 `initProfile` 语义补齐(manifest + 空用户 patch 层 + `pnpm-workspace.yaml`),**已存在的文件从不改动**。

装完**重启一次 `dsh web`**(bundles 层栈变化 + 客户端模块扫描按包名缓存)。

> 本仓库是独立 git 仓库,与 deepseek-harness 官方仓库没有任何 git 关系 > (无 fork / 子模块 / 远程关联);官方 checkout 零改动。

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 355 lines
  1. # dsh-deepseek-vision
  2. [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)
  3. [![](https://img.shields.io/badge/release-v0.1.7-5B4CF0?style=flat-square)](./CHANGELOG.md)
  4. [![](https://img.shields.io/badge/verified-121%20tests-2EA44F?style=flat-square)](./tests)
  5. [![](https://img.shields.io/badge/coverage-97%25-brightgreen?style=flat-square)](./vitest.config.ts)
  6. [![](https://img.shields.io/badge/license-MIT-0B7285?style=flat-square)](./LICENSE)
  7. [![](https://img.shields.io/badge/Node.js-%5E22.19%20%7C%20%3E%3D24-339933?style=flat-square&logo=nodedotjs&logoColor=white)](./package.json)
  8. [![](https://img.shields.io/badge/DSH-Web%20%2B%20Headless-5B4CF0?style=flat-square)](./cordis.patch.yml)
  9. **安装:** `dsh plugin --profile web add dsh-deepseek-vision`
  10. **dsh-deepseek-vision 是给 DeepSeek Harness 的视觉语言网关插件。** 纯文本的 DeepSeek 编程模型
  11. 通过一个"网关"provider 路由获得贴图能力:默认 `native-first`,目录声明支持 image 的模型
  12. 图片直通原生视觉端点;其余模型先由可配置的视觉模型
  13. (默认 Qwen-VL)逐字描述成文字,再交给 DeepSeek 继续写代码。官方仓库零改动、跨机器
  14. 安装不锁官方版本。同类方案里它是**最薄的桥**:不注入 agent 工具、不经过第三方中转、
  15. 不依赖本地模型。
  16. [English](README.en.md) | [中文](README.md)
  17. ## 目录
  18. - [亮点](#亮点)
  19. - [为什么选它](#为什么选它)
  20. - [快速开始](#快速开始)
  21. - [效果](#效果)
  22. - [工作原理](#工作原理)
  23. - [配置](#配置)
  24. - [使用](#使用)
  25. - [安装](#安装)
  26. - [版本对齐](#版本对齐)
  27. - [开发](#开发)
  28. - [边界与注意](#边界与注意)
  29. - [FAQ](#faq)
  30. - [许可](#许可)
  31. ## 亮点
  32. - **贴图即用,不用换模型:** 注册独立路由 `deepseek-vision`(显示名 *DeepSeek + Vision*),
  33. 真实声明 `inputModalities: ['text','image']`——聊天窗贴图、`tool-fs read_image`、浏览器
  34. 截图、MCP 工具返回的图片、ACP 客户端内联图片全部放行。
  35. - **同代图片只描述一次:** 按“完整 VL 配置代际 + attachmentId”进程内 LRU 缓存,重试、上下文压缩、后续轮次
  36. 复用同一份描述,不重复计费。
  37. - **会话不变量保持:** 原始图片仍持久化进 session log,历史 / 回放 / 重构不受影响。
  38. - **官方机制安装:** bundle 声明 + `dsh plugin add`,四种 spec(npm / git / 目录 / tarball)、
  39. web 与 headless 双 profile,与官方插件完全同一路径。
  40. - **换 VL 模型零改码:** 端点 / 模型 / 提示词 / 密钥全在设置卡片,兼容任意
  41. OpenAI 风格 `/chat/completions` 网关(DashScope、vLLM、OpenRouter、LM Studio…)。
  42. - **失败语义明确:** 默认 fail-closed,稳定错误码(`AUTH` / `TIMEOUT` / `TRANSPORT` /
  43. `IMAGE_TOO_LARGE`…),或 `placeholder` 降级为文字占位继续。
  44. - **跨版本不锁死:** 发布版不锁定官方 dsh 版本。无 CLI 复刻路径(`pnpm
  45. install-profile`)在目标机用**自己的** dsh 重建,构建成功即兼容证明,装前分级
  46. 提示、绝不静默失败;官方 CLI 路径(`dsh plugin add`)直接安装发布产物,不在
  47. 目标机重建——运行时依赖经 healed fallback 解析,但兼容性未经目标机验证
  48. (见[版本对齐](#版本对齐))。
  49. ## 为什么选它
  50. dsh 视觉插件生态在官方 harness 发布后的几十小时内密集涌现,机制与取舍各不相同。本插件的
  51. 立场是一句话:**最薄的桥**——只加一条 provider 路由,其余什么都别加。
  52. - **不注入 agent 工具**:不新增 `vision_describe` / `analyze_image` 之类的工具,agent
  53. 的行为面不变,贴图走的就是"贴图"这条原路;
  54. - **不经过第三方中转**:没有匿名回退端点、没有代理服务器、没有磁盘答案缓存——图片
  55. 只经过**你自己配置的 VL 端点**(你的 key、你的端点、你的数据);
  56. - **不依赖本地模型**:无 Python / MLX / llama.cpp / Ollama 要求,装上即用;
  57. - **与官方插件同一发布质量**:官方 bundle 机制安装、装前兼容门禁、构建锚点章、
  58. 121 个测试 / 97% 覆盖率、双语文档。
  59. | 维度 | 本插件 | 工具型(如 [dsh-vision-any](https://github.com/tianmingwan/dsh-vision-any)、[dsh-vision](https://github.com/linenxi-ctrl/dsh-vision)) | 路由型(如 [dsh-vision-router](https://github.com/ysr666/dsh-vision-router)) | 代理型(如 [dsh-vision-proxy](https://github.com/Flyvhidbwo/dsh-vision-proxy)) | 本地管线型(如 [DeepSeek-Harness-Vision-Tools](https://github.com/tonyd2wild/DeepSeek-Harness-Vision-Tools)) |
  60. | --- | --- | --- | --- | --- | --- |
  61. | 机制 | provider 网关路由 | 注入 agent 工具 | 工具 + 多供应商路由 | 透明代理路由 | Python 本地 VLM 管线 |
  62. | 图片数据流 | 只经你自己的 VL 端点 | 你自己的 API | 含第三方匿名回退 | 自有端点 + 回退链 | 本地模型,不出网 |
  63. | 换 VL 模型 | 设置卡片,零改码 | 配置文件 | 配置文件 | 配置 + 自动探测 Ollama | 换本地模型 |
  64. | 答案/描述缓存 | 进程内 LRU(仅描述) | — | 内容哈希答案缓存 | SHA-256 缓存 | — |
  65. | 失败语义 | fail-closed + 稳定错误码 | — | — | 超时保护 | — |
  66. | 发布链路 | 官方 bundle 机制 + 兼容门禁 + 锚点章 | — | — | — | 非 bundle |
  67. > 上表只列方向性差异,各项目仍在快速迭代;选型时请以各项目最新 README 为准。
  68. ## 快速开始
  69. 前置:`dsh` CLI 已可用并启动过一次、PATH 里有 `pnpm`(`dsh plugin` 命令经 pnpm 安装插件)。
  70. **第一步:新机器装 `dsh`(一次性,二选一)。** `dsh` 是官方 CLI(npm 包
  71. `@deepseek-ai/dsh`):
  72. ```sh
  73. npm install -g @deepseek-ai/dsh # 推荐:dsh 永久进入 PATH,之后命令直接敲
  74. # 或(官方一行启动方式):
  75. npx @deepseek-ai/dsh web # 不装全局:CLI 只在 npx 缓存里运行,不会进 PATH
  76. ```
  77. > ⚠️ 用 `npx` 方式时 `dsh` **不会**进入 PATH——新开终端直接敲 `dsh` 会报
  78. > "command not found"。要么全局安装,要么所有命令都带 `npx @deepseek-ai/dsh` 前缀。
  79. **第二步:安装**(git 形式,锁 commit,推荐):
  80. ```sh
  81. dsh plugin --profile web add github:siegfly/dsh-deepseek-vision#<sha>
  82. # 没装全局、走 npx 时:
  83. npx @deepseek-ai/dsh plugin --profile web add github:siegfly/dsh-deepseek-vision#<sha>
  84. ```
  85. 已发布的 npm 版(0.1.7)同样可用:把 spec 换成 `dsh-deepseek-vision@0.1.7`
  86. (显式锁版本——pnpm 11 默认对发布不足 24h 的新版本设年龄门槛,裸 spec 在
  87. 0.1.7 发布 24h 内会暂时解析到旧版 0.1.5)。
  88. **部署使用:** 重启一次 `dsh web` → Models 页选 **DeepSeek + Vision** → 设置 → 插件 →
  89. 插件配置里填 VL 密钥 → 聊天窗贴图,发消息。
  90. **卸载:**
  91. ```sh
  92. dsh plugin --profile web remove dsh-deepseek-vision
  93. ```
  94. headless profile、其他 spec 形式(git / 目录 / tarball)、无 CLI 的机器——见[安装](#安装)。
  95. ## 效果
  96. 聊天窗里选中 **DeepSeek + Vision** provider 之后:
  97. | ![模型选择器里的 DeepSeek + Vision provider](./docs/images/provider-picker.png) | ![聊天窗贴图,图片被描述后发送给 DeepSeek](./docs/images/chat.png) |
  98. | :---: | :---: |
  99. - **粘贴 / 拖入图片** → 按所选模型分流:目录声明支持 image 的模型(官方默认目录里的
  100. `deepseek-v4-flash-vision-exp`)**图片直通原生**,直接走 DeepSeek 官方视觉端点;
  101. 纯文本 / 未列目录的模型则由配置好的视觉模型先描述成文字(逐字提取代码、报错、
  102. 日志、UI 文案,并描述布局);
  103. - 描述文字替代图片发给 DeepSeek → 你继续用 DeepSeek 写代码,同时获得图片理解能力;
  104. - 每张图片只描述一次,重试 / 压缩 / 后续轮次都复用同一份描述,不重复计费;
  105. - session 日志仍然持久化原始图片,历史 / 回放 / 重构不变量不受影响。
  106. ## 工作原理
  107. ```mermaid
  108. flowchart LR
  109. User["聊天窗贴图 / read_image / 截图 / MCP / ACP"] --> Gate["deepseek-vision 路由:inputModalities = text + image"]
  110. Gate --> Persist["apiproxy prompt RPC → ImageBlock 持久化进 session log"]
  111. Persist --> Decide{"DeepSeek 目录声明该模型支持 image?"}
  112. Decide -- "是(官方视觉模型)" --> Native["yield* super.stream():父类原生序列化图片,直通 DeepSeek 视觉端点"]
  113. Decide -- "否(纯文本 / 未列目录)" --> Bridge["ImageBridge:改写图片块(含 tool-result 嵌套)"]
  114. VL["可配置 VL 模型(默认 qwen3-vl-flash,OpenAI 兼容端点)"] --> Bridge
  115. Cache["attachmentId → 描述 LRU 缓存"] --> Bridge
  116. Bridge --> Stream["yield* super.stream():原生 DeepSeek wire 继续流式"]
  117. ```
  118. 为什么是"网关适配器"而不是中间件:DSH 有两道硬门槛——`prompt` / `selectModel` RPC 按
  119. `inputModalities` 拒绝不含 `image` 的模型(纯 `llm/stream` 中间件拦不到),llm-deepseek
  120. 序列化器对 text-only 模型的 image block 抛 `UNSUPPORTED_CONTENT`。本插件注册新的
  121. provider 路由,继承官方导出的 `DeepSeekAdapter`:`stream()` 先按**父类目录**判断所选
  122. 模型——目录声明 image 能力的(官方 rc.2 默认发布 `deepseek-v4-flash-vision-exp`)原样
  123. 直通,由父类原生序列化图片;纯文本与未列目录的模型才把图片块经 VL 模型改写为文本,
  124. 再走原汁原味的 DeepSeek wire。reasoning efforts / context 窗口 / 默认 maxTokens /
  125. retry policy 全部从父类继承。
  126. ## 配置
  127. 全部可省略(走默认值)。两个 key 都支持 credential-ref(环境变量名)。已挂载 dsh 的
  128. `credentials` 服务时,其解析结果(即使未配置)具有权威性;只有服务缺席才直接读取启动环境。
  129. 官方 `credentials-local` 的优先级是:**进程环境变量(最高、只读)→ GUI 管理的
  130. `.credentials.yaml` → `.env` 回退**。因此 Web Models 页写入的凭据可用,而本次进程显式
  131. 导出的 key 始终优先且不能在 GUI 内修改:
  132. | 路径 | 默认值 | 说明 |
  133. | --- | --- | --- |
  134. | `provider` | `deepseek-vision` | 注册的路由 id(避开 `deepseek-official`) |
  135. | `displayName` | `DeepSeek + Vision` | 模型选择器里的名字 |
  136. | `mode` | `native-first` | `native-first` = 原生视觉优先、文本模型回退;`always-describe` = 始终转描述;`disabled` = 完全退回官方 DSH 行为 |
  137. | `deepseek.*` | — | 与官方 `llm-deepseek` 段完全同构(apiKeyEnv / baseURL / thinking / reasoningEffort / maxTokens / models / retryPolicy…) |
  138. | `deepseek.apiKeyEnv` | `DEEPSEEK_API_KEY` | DeepSeek key |
  139. | `vl.apiKeyEnv` | `QWEN_VL_API_KEY` | VL 模型 key |
  140. | `vl.baseURL` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | 任意 OpenAI 兼容 `/chat/completions` 网关 |
  141. | `vl.model` | `qwen3-vl-flash` | VL 模型 id(贴图 OCR 型描述性价比最高;复杂视觉推理可换 `qwen-vl-max`) |
  142. | `vl.describePrompt` | 详述 + 逐字提取的英文提示词 | 图片描述指令 |
  143. | `vl.timeoutMs` | `120000` | 单次描述请求硬超时 |
  144. | `vl.maxTokens` | `2048` | 单张图片描述的最大输出 token |
  145. | `vl.maxPixels` | `4194304` | DSH 在发送 VL 前进行确定性缩放的总像素上限 |
  146. | `vl.maxBytes` | `5000000` | DSH 在发送 VL 前进行确定性编码的目标字节数 |
  147. | `vl.maxCacheEntries` | `64` | 进程内描述缓存容量(LRU) |
  148. | `vl.onFailure` | `fail` | `fail` = 描述失败整个请求失败;`placeholder` = 降级为文字占位继续 |
  149. `llm-vl-gateway` 也是一个 settings namespace,三个编辑入口:**设置 → 插件 → 插件配置**
  150. 的"DeepSeek + Vision(视觉语言桥接)"卡片(`vl.*` 全字段 + VL 密钥)、Web Models 页
  151. (`deepseek.*` 子段由可配置 provider 目录接管)、`settings.yaml`(两个子段都可写)。
  152. 卡片与 DSH 原生插件一致默认收起;折叠不会丢失草稿,保存成功后自动收起。
  153. ![插件设置卡片](./docs/images/plugin-settings.png)
  154. `provider` / `displayName` 是注册期事实,修改即时生效(adapter 路由 + 可配置 provider
  155. 目录原子重注册,不需重启);改成已被占用的路由 id 时两个注册表保留旧值并记日志。
  156. patch 行内配置示例(全部可选):
  157. ```yaml
  158. - insert:
  159. - id: llm-vl-gateway
  160. name: dsh-deepseek-vision
  161. config:
  162. deepseek:
  163. reasoningEffort: high
  164. mode: native-first
  165. vl:
  166. apiKeyEnv: DASHSCOPE_API_KEY
  167. model: qwen3-vl-flash
  168. ```
  169. ## 使用
  170. 1. 设置两个 key:**设置 → 插件 → 插件配置 → "DeepSeek + Vision(视觉语言桥接)"**
  171. 卡片里填 VL 密钥(写入凭据存储,不出现在任何响应/设置里);DeepSeek key 沿用现有凭据;
  172. 2. Models 页选择 provider **DeepSeek + Vision**(会话内切换即持久化为默认);
  173. 3. 聊天窗贴图,发消息——图片自动被描述,DeepSeek 看到的是文字。
  174. 设置卡片是本插件的**客户端面**(`dsh.client`):以官方解耦插件的方式注册进
  175. `settings.plugin.item` 槽位,编辑 `llm-vl-gateway.vl` 段,与官方内置卡片(终端 /
  176. Agent 循环 / 网页搜索)同机制、同交互(暂存草稿、覆盖状态显示、保存时整体写入)。
  177. ## 安装
  178. 安装走**官方 bundle 机制**:本包在 `package.json` 声明 `dsh.bundle.patch`(指向包内
  179. `cordis.patch.yml`),`dsh plugin add` 把包链接进 profile 并把包名对账进 profile
  180. manifest 的 `dsh.profile.bundles` 层栈,loader 启动时按层挂载——**不需要手工往
  181. `cordis.patch.yml` 加任何行**(旧版本加过的受管块会在下次安装/卸载时自动迁移移除)。
  182. 四种 spec 任选(日常推荐 git 形式,锁 commit):
  183. ```sh
  184. dsh plugin --profile web add github:siegfly/dsh-deepseek-vision#<sha> # git(推荐),锁 commit
  185. dsh plugin --profile web add dsh-deepseek-vision@0.1.7 # npm(已发布 0.1.7,显式锁版本)
  186. dsh plugin --profile web add file:<本仓库路径> # 本地目录(开发)
  187. dsh plugin --profile web add ./dsh-deepseek-vision-0.1.7.tgz # tarball(npm pack 产物)
  188. ```
  189. headless 同理:`dsh plugin --profile headless add dsh-deepseek-vision`(客户端卡片只在
  190. web 生效)。验证 bundle 层已挂载:`dsh --profile web --dump-config | grep llm-vl-gateway`。
  191. 卸载与安装一一对应:`dsh plugin --profile <name> remove dsh-deepseek-vision`。
  192. 无 CLI 的机器用等价复刻(需 Node 22.19+ 或 24+、PATH 里有 `pnpm`;init 布局 → 目标机
  193. 重建 → 兼容门禁 → pnpm add → bundles 对账):
  194. ```powershell
  195. pnpm install # 只装 devDeps(typescript/vitest),不会装 @deepseek-ai/*
  196. pnpm install-profile # 或 node scripts/install-profile.mjs [profile] [dshHome]
  197. ```
  198. 这是唯一在目标机重建的安装路径:`install-profile` 先用目标机自己的 dsh 类型重新构建
  199. 插件并通过 `check-compat.mjs` 门禁,再装入 profile(见[版本对齐](#版本对齐))。
  200. 两条路径都做下面两件事:
  201. - 把 `dsh-deepseek-vision` 链接进 profile 的 node_modules(运行时 `@deepseek-ai/*` 依赖经
  202. 官方 healed fallback 解析到**同一个** dsh 安装,共享同一个 cordis 实例,无双实例问题);
  203. - 把 `dsh-deepseek-vision` 对账进 `dsh.profile.bundles`——loader 按层挂载包内
  204. `cordis.patch.yml` 的 insert 行(注册路由 + 设置段);
  205. - 首次安装时如 profile 布局缺失,按官方 `initProfile` 语义补齐(manifest + 空用户
  206. patch 层 + `pnpm-workspace.yaml`),**已存在的文件从不改动**。
  207. 装完**重启一次 `dsh web`**(bundles 层栈变化 + 客户端模块扫描按包名缓存)。
  208. > 本仓库是独立 git 仓库,与 deepseek-harness 官方仓库没有任何 git 关系
  209. > (无 fork / 子模块 / 远程关联);官方 checkout 零改动。
  210. ## 版本对齐
  211. 两条安装路径的兼容性策略不同:
  212. - **官方 CLI 路径**(`dsh plugin add`,npm / git / tarball):直接安装发布产物——
  213. npm 包在作者发布时构建,git 形式使用提交的 `lib/`,tarball 是作者打包的产物,
  214. **都不在目标机重建,也没有兼容门禁**。运行时 `@deepseek-ai/*` 依赖从目标机自己的
  215. dsh 安装解析(healed fallback);若目标机官方 dsh 的 API 与本插件编译产物不匹配,
  216. 安装不会提前失败,问题会在启动或调用时显现。装前请自行确认目标 dsh 与
  217. `dshCompat.anchorVersion` 声明的代际大致一致。
  218. - **无 CLI 复刻路径**(`pnpm install-profile`):安装前**先在目标机用目标机自己的
  219. dsh 类型重新构建**插件,再跑 `check-compat.mjs` 分级门禁。只有这条路径提供
  220. “构建成功即兼容证明”:
  221. > 无 CLI 复刻路径下,发布版不锁定任何官方版本——目标机器用比锚点更新(或更旧)的
  222. > 官方 dsh 都可以安装;构建成功本身就是兼容性证明。若新官方版改了本插件用到的 API,
  223. > 构建会自然失败并给出明确的 tsc 错误,那时才需要发新版适配。**作者无需跟随官方每次
  224. > 升级重新发布。**
  225. - `dshCompat.anchorVersion` 只声明提交的 `lib/` 的**构建出处**(出处声明,不是安装
  226. 许可);`pnpm build` 写入的 `lib/build-anchor.json` 让出处无法撒谎。
  227. - `node scripts/check-compat.mjs [dshHome]` 安装前对目标机分级:完全一致 = exit 0;
  228. **任何不一致 = exit 1 提示并放行**;残缺发布 / 复刻漂移 = 拒绝(有环境变量强制开关)。
  229. 该检查**只在 `install-profile` 里运行**,官方 CLI 路径不会调用它。
  230. 完整策略、退出码分级与发版触发条件:[docs/VERSIONING.md](docs/VERSIONING.md)。
  231. ## 开发
  232. ```powershell
  233. pnpm test # vitest
  234. pnpm build # tsc(宿主面 + 客户端面)+ tsdown 浏览器 bundle
  235. ```
  236. - `scripts/harness-paths.mjs` 是仓库唯一的解析缝:`$DSH_CHECKOUT` → 仓库根
  237. `harness-paths.json`(gitignored)→ 本机已安装 dsh 的 healed fallback。
  238. - 纯 npm 机器上 2 个客户端测试套件自行跳过(npm 只发布浏览器闭包里的客户端运行时);
  239. 有官方源码 checkout 的机器跑全量。
  240. - 产物里的 `@deepseek-ai/*` 导入保持裸说明符,运行时走 profile fallback。
  241. 细节:[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)。贡献指南:[CONTRIBUTING.md](CONTRIBUTING.md);
  242. 安全漏洞报告:[SECURITY.md](SECURITY.md)。
  243. ## 边界与注意
  244. - **compaction**:默认继承会话 provider(即网关路由),按会话模型分流——目录声明
  245. image 的模型(官方视觉模型)图片直通原生;文本模型图片被改写且命中缓存。若把压缩
  246. 策略显式 pin 到 `deepseek-official` 且历史含图,会按原逻辑 `UNSUPPORTED_CONTENT` 失败。
  247. - **卸载后的含图会话**:卸载插件后,含图历史会话无法切回文本模型(官方 `selectModel`
  248. 按 `inputModalities` 准入拒绝,属预期行为,不是数据损坏);新会话不受影响,重装即恢复。
  249. - **VL 失败语义**:默认 fail-closed——描述失败(如 key 失效)整个请求以稳定错误码
  250. (`AUTH` / `TIMEOUT` / `TRANSPORT`…)终止,不静默丢图;`onFailure: placeholder` 可降级。
  251. - **图片投影与上限**:先按部署准入上限 fast-fail,再通过新版 DSH 的
  252. `readImageRequest` 公共 seam 按 `vl.maxPixels` / `vl.maxBytes` 确定性缩放和编码;描述输出另由
  253. `vl.maxTokens` 限制。供应商仍可能有更低上限,请同时留意其文档。
  254. - **新版 DSH 下的定位**:插件不再是“所有图片能力”的必装件,而是文本模型的可选兼容层。
  255. 只使用原生视觉模型时可设 `mode: disabled` 或卸载;需要让 DeepSeek 文本/推理模型读取图片、
  256. 强制统一 OCR 描述,或使用独立 VL 供应商时,它仍提供官方原生路径没有替代的能力。
  257. - **缓存不是持久存储**:描述只保存在当前进程内;重启后可从持久化附件重新描述,但不会复用
  258. 上一进程的描述结果。
  259. - 描述文本会占用 DeepSeek 的 context(每图几百 token,仅首次计费)。
  260. - 新版 DSH 的 `imageRequestPricing` 是同步接口,首次描述生成前无法精确知道其文本 token;
  261. 当前上下文预检仍会低估这部分占用,实际输出由 `vl.maxTokens` 硬限制。
  262. ## FAQ
  263. **新机器上 `dsh` 命令不存在 / 报 command not found?** 先装官方 CLI:
  264. `npm install -g @deepseek-ai/dsh`(一次性,之后 `dsh` 永久在 PATH)。如果平时用
  265. `npx @deepseek-ai/dsh web` 启动(官方一行方式),CLI 只在 npx 缓存里运行、**不会进
  266. PATH**,装插件时要用 npx 前缀:`npx @deepseek-ai/dsh plugin --profile web add
  267. dsh-deepseek-vision`——插件本身装在 profile 里,与 CLI 从哪来无关,装一次永久有效。
  268. **安装需要关心 Node 版本吗?** 官方 CLI 路径(`dsh plugin add`)不需要;只有无 CLI 的
  269. 复刻脚本需要 Node 22.19+ / 24+ 和 PATH 里的 `pnpm`。
  270. **`#<sha>` 是什么?** git spec 形式的占位符——替换成具体 commit 哈希可锁死精确代码快照;
  271. 不加 `#<sha>` 则安装默认分支最新提交。
  272. **支持 CLI(headless)吗?** 支持。网关路由在两个 profile 行为一致;设置卡片是 web
  273. 专属,headless 用 `settings.yaml` 配置。
  274. **卸载后,含图历史会话选不了模型?** 属预期行为:官方 `selectModel` 按
  275. `inputModalities` 拒绝文本模型接入含图会话。新会话不受影响,重装即恢复。
  276. **为什么图片不直接发给 DeepSeek?** 现在有两种路径:DeepSeek 目录声明支持 image 的
  277. 模型(官方 `deepseek-v4-flash-vision-exp`)图片**已经**直通原生、不走插件。其余纯文本
  278. 模型官方接口会拒绝 `image_url`,所以先由 VL 模型描述成文字再转发——不换模型、不丢信息。
  279. ## 许可
  280. [MIT](./LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.