dsh-vision-skill

让 DSH 里任何模型（包括 DeepSeek 这类纯文本模型）都能识别图片。装上即用：纯文本模型发图不再被拒，图片自动转成"本地路径"交给视觉 API 识别。

Give every model in DeepSeek Harness (DSH) — including text-only ones like DeepSeek — the ability to see images. Install and use: image messages to text-only models are no longer rejected; images are delivered as local paths and recognized through an OpenAI-compatible vision API.

⚠️ 诚实声明 / Honest disclaimer：本项目的"宿主补丁"是对 DSH 核心包（rc.6）的 mod 式修改，不是官方扩展点。DSH 升级后锚点可能失效（表现为脚本输出 MISS），届时插件只告警、绝不硬改文件，请按故障排查处理。 The host patch here is a mod of DSH core packages (rc.6), not an official extension point. After DSH upgrades the anchors may stop matching (the script then reports MISS); the plugin only warns and never force-edits files. See Troubleshooting.

特性 / Features

• ✅ 纯文本模型（DeepSeek 等）发送图片不再被"当前模型不支持图片"拦截
• ✅ 识图自动降级：模型先试原生 read_image，失败自动走 vision.js（OpenAI 兼容视觉 API）
• ✅ 多模态模型（GLM、MiMo 等）行为完全不变，图片照常直传
• ✅ 无密钥入库、无个人路径：所有路径运行时推导，API Key 走环境变量
• ✅ 幂等补丁引擎：可安全重复执行，每次自动 node --check 自校验

工作原理 / How it works

两层设计 / Two layers:

1. 技能层 / Skills：注册两个技能——
   • claude-vision-skill：识图指令（条件判断：先 read_image，失败走 vision.js）；
   • vision-patch：补丁检修技能（模型可手动运行幂等补丁脚本）。
2. 宿主补丁层 / Host patch：插件启动时自动对 $DSH_HOME/profiles/*/node_modules/@deepseek-ai 下的 5 个核心包做精确锚点修改：
   • dsh-host-apiproxy：移除"纯文本模型 + 图片"的两处拒绝（发送时 / 切换模型时）；
   • dsh-llm-pi-ai / dsh-llm-deepseek：把 image 块降级渲染为带本地路径的文本，而不是抛 UNSUPPORTED_CONTENT；
   • dsh-attachment / dsh-attachment-local：新增 pathOf() 暴露附件真实存储路径。

补丁以幂等 + 安全失败为原则：锚点不匹配（版本变化）时只记录 MISS 告警，绝不改动文件。

安装 / Install

方式一：npm 插件（推荐 / Recommended）

# 1. 安装到 web profile
dsh plugin --profile web add dsh-vision-skill

# 2. 在 <$DSH_HOME>/profiles/web/cordis.patch.yml 追加：
#    - insert:
#        - id: vision
#          name: dsh-vision-skill

# 3. 重启两次（第一次启动写入补丁，第二次生效）
dsh web --port 3080

为什么两次重启？插件启动时把补丁写入磁盘，但本进程的核心包已在启动早期加载；第二次重启才真正加载补丁后的代码。首次安装后需要两步：重启 → 重启。之后每次正常启动都自动自检。 Why two restarts? The plugin writes the patch to disk at boot, but the core packages were already loaded earlier in that boot; only the next boot loads the patched code. Install flow: restart → restart. Every later boot self-checks automatically.

方式二：免安装技能（不想要插件 / No-plugin route）

把 skills/ 下的两个目录拷到 DSH 技能目录，再手动执行一次 vision-patch 技能即可：

cp -r skills/vision           <DSH_HOME>/skills/claude-vision-skill
cp -r skills/vision-patch     <DSH_HOME>/skills/vision-patch
# 然后对模型说："执行 vision-patch"

配置 / Configuration

优先读环境变量，其次读 vision.js 同目录的 .env（参考 .env.example）：

变量	说明
DASHSCOPE_API_KEY	必填，OpenAI 兼容视觉 API 的 Key
DASHSCOPE_BASE_URL	默认 https://opencode.ai/zen/go/v1（OpenCode Go）
VISION_MODEL	默认 mimo-v2.5（原生多模态）
VISION_MAX_TOKENS	默认 2048

Windows 示例：setx DASHSCOPE_API_KEY sk-xxx（重启终端生效）；macOS/Linux：export DASHSCOPE_API_KEY=sk-xxx（写入 shell 配置）。

兼容性 / Compatibility

• 实测环境：DSH 0.1.0-rc.6、Node ≥ 20、Windows / macOS（剪贴板辅助脚本双平台）。
• 补丁锚点针对 rc.6 的源码形态；其他版本可能出现 MISS——插件只告警不硬改，把日志发到 Issue 即可。
• 限制 / Limitations：
  • 子智能体会话暂不支持图片（DSH 原有设计，本插件不改变）；
  • 纯文本模型收到的历史图片显示为 [image attachment ...] 占位文本；
  • 补丁覆盖 $DSH_HOME/profiles 下所有含核心包的 profile。

安全 / Security

• 本仓库不含任何 API Key；vision.js 只从环境变量 / .env 读取。
• 请勿提交 .env（已在 .gitignore 中）。
• 若怀疑 Key 泄露，请立即到对应平台吊销并更换。

故障排查 / Troubleshooting

• 补丁脚本输出 MISS：说明当前 DSH 版本与实测版本不一致。把完整输出贴到本仓库 Issues。
• 发送图片仍被拒：运行 vision-patch 技能手动重试，检查日志。
• vision.js 报"请设置 DASHSCOPE_API_KEY"：未配置密钥，见配置。
• 沙箱拒绝写入（EPERM）：补丁需要 full-access（danger-full-access）授权。

开发 / Development

npm test                 # 补丁引擎 + 插件注册的单元测试
node skills/vision-patch/patch-vision.js   # 手动执行补丁（幂等）

致谢与许可 / Attribution & License

• vision.js 与剪贴板辅助脚本派生自 asuojun/claude-vision-skill（上游未声明许可证，请以 fork 方式引用并保留署名）。
• 本仓库新增部分（补丁引擎、插件、技能说明重写、格式嗅探改进）以 MIT 许可发布，见 LICENSE。

---

注意 / Note：本项目为社区自制扩展，与 DeepSeek / DSH 官方无关联。This is a community extension and is not affiliated with DeepSeek or the DSH project.