一句话定位

为 DSH 的极简模式追加按需视觉能力：把图片和文档变成本地缓存文件，把视觉调用说明写进折叠上下文，让 Agent 在保留极简模式原有工具面和 system prompt 的前提下，根据需要通过 Bash 调用视觉模型。

核心能力

• 注册名为「视觉辅助模式」的 Agent 预设，保持 persistent-bash 和 str_replace_editor 两个原始工具
• 在拖入图片时自动纠正方向、把长边限制在 1600 px、压平成 JPEG（mozjpeg q85），并落到本地缓存
• 在拖入 PDF/Word/PPT 时原样保存为本地文件，文件路径以折叠上下文形式进入 Agent
• 提供 dsh-vision CLI 与 5 个内置任务：custom、slide_review、figure_semantics、caption_grounding、flowchart_extract
• 在「设置 → Vision」里集中保存 API 地址、视觉模型 ID 与 API Key，支持 OpenAI Chat Completions 和 Gemini 两种协议
• 自带 dsh-vision-doctor 脚本，检查启动器、预设文件、CLI 路径是否齐全

技术实现

• 语言: JavaScript（ES Modules，type: "module"）
• 关键依赖: sharp（图像归一化与压缩）、@deepseek-ai/schemastery（设置 Schema）、js-yaml（读取 settings.yaml 和凭据）
• 架构模式: 服务端 Cordis 插件注入 webServer / settings / credentials，注册 4 个 HTTP 路由；客户端在 web 端注入 slots / conversation / sessions，通过 agent/pre-step 钩子向首轮消息追加折叠上下文，视觉调用通过 Bash 子进程完成
• 入口文件: src/index.js（服务端）、src/client.js（浏览器端）、src/cli.js（dsh-vision 命令）、src/injector.js（agent/pre-step 钩子）

适用场景

DSH 用户在极简模式下需要识别图片或读取 PDF/PPT 时使用：把图片拖进对话框，本插件会把图片落到本地缓存，把路径塞进折叠上下文；Agent 看到需要视觉证据时，会通过 Bash 调用 dsh-vision analyze 触发视觉模型，整条链路不污染极简模式的 system prompt，也不引入新的常驻工具。适合需要按需补足视觉能力、又不想破坏极简模式上下文的场景。

前置依赖与兼容性

安装方式

dsh plugin --profile web add dsh-tool-vision

配置项

VISION_API_KEY 环境变量优先级最高，会覆盖从凭据文件读取的 Key；本地未配置 Key 时，只要 API 地址指向 localhost / 127.0.0.1 也会放行，便于本地推理服务。

常见问题

Q: 装好之后是不是就能直接用？

A: 不能，必须先在「设置 → Vision」里填入 API 协议、API 地址、视觉模型 ID 和 API Key 才会生效；点击「测试连接」只会发一条最小文本请求，并不会真正上传图片。

Q: 都支持哪些图片和文档？

A: 图片支持 PNG、JPEG、WebP、GIF，文档支持 PDF、DOC、DOCX、PPT、PPTX。文档本身不会被送到视觉接口，Agent 需要先用 Bash 把它转成图片再传给 dsh-vision。

Q: 一次最多传几张图？

A: 单次 dsh-vision analyze 最多接受 4 张图片，单张不超过 20 MB；文档单文件上限 100 MB。

Q: 上传后图片和文档存在哪里，会被上传到云端吗？

A: 文件落到本地 $DSH_HOME/cache/dsh-tool-vision/ 缓存目录；只有 Agent 显式调用 dsh-vision analyze 并指定图片时，图片才会送到已配置的视觉服务，文档始终只在本地处理。

Q: 跟 DSH 自带的视觉能力有什么区别？

A: 本插件不会注册新的聊天模型，也不会改写极简模式的 system prompt，而是把视觉说明和附件路径作为折叠上下文注入，让 Agent 通过 Bash 触发视觉模型。原有的 persistent-bash 和 str_replace_editor 工具保持不变。

Q: Windows PowerShell 能直接跑吗？

A: 当前版本不支持。已在 Ubuntu 与 WSL2 下测试通过，Windows 用户需要在 WSL2 内安装并运行 DSH 与本插件，原生 Windows PowerShell 支持即将推出。

Q: 安装后怎么判断环境是否正常？

A: 运行 dsh-vision-doctor（包内自带），会检查 profile 安装包、启动器、Node 运行时、CLI 路径和预设文件是否齐全；任意一项异常会打印 ERROR 行并以非零状态退出。

上手难度

入门 — 用户只需要在「设置 → Vision」填三个字段就能用，CLI 默认参数也是按视觉问答设计；进阶用户可以调整任务模板和预设细节。

已知问题与限制

• 不支持原生 Windows PowerShell，Windows 用户必须在 WSL2 内运行（README.md:49）
• 视觉请求的默认超时为 120 秒，部分慢响应模型可能需要更长等待时间（src/providers.js:71 / src/config.js:13）
• 图片最大 20 MB、文档最大 100 MB，超出后上传会被直接拒绝（src/upload-api.js:8 / src/file-upload-api.js:7）
• 视觉能力只在「视觉辅助模式」预设下生效，其它预设不会自动注入折叠上下文（src/client.js:67-70）
• OpenAI Chat Completions 协议下如果网关拒绝 response_format: json_object，插件会自动去掉该字段重试一次（src/providers.js:97-99）

dsh-minimal-vision

保持极简模式的上下文边界，同时获得按需视觉能力

中文 · English

🎬 介绍视频：[开源] DSH 极简模式视觉插件 👀 轻量化+干净

该视觉插件不是新的聊天模型，也不是第三个常驻工具。它只在需要时，通过隐藏上下文和 Bash 进入 Agent 工作流。

为什么基于极简模式？

极简模式的优势不只是工具少，更重要的是首轮请求拥有干净、稳定的 system prompt 和工具面。测试中观察到要触发 DS 的灰测行为水平依赖这个起点；额外 system prompt、聊天工具或视觉模型注册都可能改变它。

本插件不改写极简模式的 system prompt，也不注册新的聊天模型。视觉说明、图片路径和文档路径作为一条默认折叠的 context 与用户消息一起进入，原有两个工具保持不变，在尽量保留极简模式行为的同时提供识图能力。

🧭 工作流程

1. 用户在 vision-assist 模式中拖入图片或文档。
2. 图片由 sharp 自动纠正方向、铺平透明背景，并将长边限制为 1600 px；PDF、DOC、DOCX、PPT、PPTX 原样保存。
3. 插件把本地附件路径放入隐藏 context，用户消息气泡保持干净。
4. Agent 自行判断如何用 Bash 读取或导出文档，并在需要视觉证据时调用视觉模型。

支持 PNG、JPEG、WebP、GIF、PDF、DOC、DOCX、PPT 和 PPTX；一次最多处理 4 张图片。“测试连接”只发送最小纯文本请求，不上传附件。Vision 配置独立存在，不会出现在聊天模型列表。

附件在发送时写入 $DSH_HOME/cache/dsh-tool-vision/ 本地缓存，隐藏 context 只包含本地路径。文档本身不会直接发送到视觉接口；只有 Agent 调用 dsh-vision 时指定的图片才会发送给已配置的视觉服务。

📦 安装

⚠️ 兼容性提示：当前版本暂未适配原生 Windows PowerShell，仅支持 Bash 环境；已在 Ubuntu 和 WSL2 下通过测试。Windows 用户请暂时在 WSL2 内安装并运行 DSH 与本插件，原生 Windows PowerShell 支持即将推出。

git clone https://github.com/Flora233333/dsh-minimal-vision.git
cd dsh-minimal-vision
npm install
dsh plugin --profile web add .
dsh web

启动后选择“视觉辅助模式”，并在“设置 -> Vision”中完成配置。

配置

插件没有写死服务商地址。CLI 每次读取 $DSH_HOME/settings.yaml 和 $DSH_HOME/.credentials.yaml；环境变量 VISION_API_KEY 优先级更高。

手动调用

"${DSH_HOME:-$HOME/.dsh}/bin/dsh-vision" \
  analyze --task custom --instructions "描述图中可见内容" -- /path/to/image.png

内置任务：custom、slide_review、figure_semantics、caption_grounding、flowchart_extract。PPT/PPTX/PDF 需要先由 Agent 导出为图片。

开发

npm install
npm run check
npm test

请勿提交 node_modules/、.playwright-cli/、.env 或任何 DSH 凭据文件。