dsh-plugin-local-vision

DeepSeek Harness 本地视觉插件：通过 LM Studio 的 OpenAI 兼容端点调用本地视觉模型（默认 qwen3-vl-8b-instruct-abliterated-v2.0）描述图片/截图。

• 🖼️ 全本地：图片不出机器，无云端 API、无费用、无隐私外泄
• ⚡ 零依赖后端：默认用 Node 原生 fetch 直连，不需要 Python/Pillow/httpx
• 🐍 可选 Python 后端：配置 pythonPath 后自动委托 scripts/vision-describe.py（带缩放/压缩，适合超大截图）
• 🔍 友好报错：LM Studio 未运行 / API key 错误 / 图片超限 / 超时，都有中文提示

前置条件

1. LM Studio 已启动，且本地端口 1234 可访问
2. LM Studio 开发者模式已开启（Settings → Developer），拿到 sk-lm-... 的 API key
3. 已加载一个视觉模型（如 Qwen3-VL 系列），记下精确的模型 ID（API 用 ID，不是显示名）
4. （可选）先跑一次探针验证连通性：

LMSTUDIO_API_KEY=sk-lm-xxxx node scripts/vision-probe.mjs "C:\path\to\image.png"
# 输出 HTTP 200 即通

安装

npm install dsh-plugin-local-vision

在 agent preset 的 agent.cordis.yml 里加一行（该行只向宿主 tools 注册表注册工具、不发布服务，不需要 isolate realm，与官方 tool-web 行同理）：

- id: tool-local-vision
  name: dsh-plugin-local-vision
  config:
    baseUrl: http://127.0.0.1:1234
    model: qwen3-vl-8b
    # timeoutMs: 600000
    # maxBytes: 10485760
    # pythonPath: 留空则用 Node 后端；填解释器绝对路径则用 Python 后端
    # apiKey: 建议不写这里，走环境变量 LMSTUDIO_API_KEY

配置

插件配置优先级：config 字段 > 环境变量 > 默认值。

config 字段	环境变量	默认值	说明
baseUrl	LMSTUDIO_BASE_URL	http://127.0.0.1:1234	LM Studio 地址，不带 /v1
apiKey	LMSTUDIO_API_KEY	空	开发者模式 key；别写进 cordis.yml
model	LMSTUDIO_VISION_MODEL	qwen3-vl-8b-instruct-abliterated-v2.0	精确模型 ID
timeoutMs	—	600000	请求超时（本地 VL 推理慢）
maxBytes	—	10485760	Node 后端图片大小上限（10MB）
pythonPath	LMSTUDIO_VISION_PYTHON	空	非空则用 Python 后端（带缩放压缩）

工具：vision_describe

模型可直接调用，参数：

参数	必填	说明
imagePath	✅	图片绝对路径（jpg/png/webp/bmp）
prompt	—	自定义描述要求，缺省为详细中文描述
maxTokens	—	生成上限，默认 1200

返回模型生成的文字描述；出错时返回带原因的中文错误（HTTP 状态码 → 排查提示）。

从旧 local-vision skill 迁移

旧方案是 ~/.dsh/skills/local-vision/SKILL.md（让 agent 自己拼命令跑 python）。本插件的工具版更稳：

• agent 不再需要拼解释器路径/引号（踩坑点，见下文文档）
• 不用在 SKILL.md 里硬编码 API key 与 venv 绝对路径
• 装好插件后，可保留也可删除旧 skill；两者并存时 agent 优先走工具

常见问题

见 docs/local-model-pitfalls.md——完整记录了我们接入本地模型时踩过的所有坑（端口/API key/模型 ID/代理拦截/图片过大/引号地狱/Anthropic 与 OpenAI 工具协议差异等），附"症状→原因→解法"速查表。

License

MIT