vision-tool：DSH 视觉对话评审插件

为纯文本主模型提供对话式界面视觉评审的 DeepSeek Harness (dsh) 插件：围绕具体任务（如美化 HTML）对页面截图进行针对性评审与追问，返回自由文本的专业意见，供主模型据此修改代码。视觉后端为任意 OpenAI 兼容多模态端点（如 agnes-2.5-flash），零运行时依赖（仅 Node 内置能力）。

工具

| 工具 | 作用 | 参数 | |---|---|---| | vision_review | 首次评审：按六项默认维度全面评估（风格一致性、配色、间距对齐、视觉层级、可读性、组件一致性），模型有权自主增加评审维度 | path（必填）、focus（可选）、dimensions（可选） | | vision_ask | 对话式追问：结合前一轮结论深入询问具体问题 | path（必填）、question（必填）、context（可选） |

多轮对话为无状态设计：历史由主模型在会话中自然累积，通过 vision_ask 的 context 参数传递。

设计原则

所有读取操作均在当前会话内完成：插件只注册读取工具，不创建新对话、不管理会话分组、不依赖 workspace 服务。

官方安装指令（npm 插件市场）

npx -y @deepseek-ai/dsh plugin --profile web add @evan-williams/vision-tool

安装后重启 dsh 进程生效：

npx -y @deepseek-ai/dsh web

视觉后端配置

插件按以下优先级解析 OpenAI 兼容后端（任一即可）：

1. ~/.modlens/config.json（与 modlens 共享的配置）：

{
  "providers": {
    "openai": {
      "baseUrl": "https://apihub.agnes-ai.cn/v1",
      "apiKey": "sk-...",
      "model": "agnes-2.5-flash"
    }
  }
}

2. 环境变量 OPENAI_BASE_URL / OPENAI_API_KEY（model 缺省为 agnes-2.5-flash）。

模型必须支持图像输入（多模态）；深度思考（chat_template_kwargs.enable_thinking）已默认开启。

使用示例（美化 HTML 迭代闭环）

1. 将页面截图提供给主模型（粘贴图片或给出路径）。
2. 主模型调用 vision_review（可带 focus，如"配色和谐度"）获得评审清单。
3. 主模型修改代码；如需澄清，调用 vision_ask 追问（如"哪个按钮颜色最刺眼，具体怎么调"）。
4. 重新截图，再次评审对比，直至满意。

技术要点

• 端点：POST {baseUrl}/chat/completions（OpenAI 兼容，依据 agnes-2.5-flash API 文档）。
• Thinking 模式：chat_template_kwargs: { enable_thinking: true }。
• max_tokens: 8192（显式传入，避免服务端默认值导致评审截断）、temperature: 0.3。
• 本地图片转 data URL（25 MB 上限）；http(s) URL 原样传递。
• API key 在错误信息中脱敏。

已知问题与修复记录

2026-08-14：工具 schema 非法导致消息机制崩溃（已修复）

根因：工具定义中 parameters 误用了 defineTool() 的扁平输入格式（required: true 内联、顶层无 type）。raw 注册（不经 defineTool 转换）时，上游收到顶层 type: null 的非法 schema，抛出 Invalid schema for function 'vision_ask'，中断消息机制。

修复：parameters 改为标准 JSON Schema 形态 { type: 'object', properties: {...}, required: [...] }（vision_review 必填 path，vision_ask 必填 path 与 question），与 modlens read_image 的注册形态一致；同时为每个工具注册包 try/catch，注册失败仅记录日志、不使插件 fiber 崩溃。

验证：node test/plugin-load.js 按 cordis loader 方式（file:// 动态 import）加载模块并模拟 ctx.tools.register，确认两个工具均以合法 JSON Schema 注册。

开发

vision-tool/
├── package.json       # type: module
├── src/index.js       # 插件入口（工具注册）
├── lib/config.js      # modlens 配置读取
├── lib/agnes.js       # API 请求封装
├── lib/prompts.js     # 评审提示词模板
├── test/smoke.js      # 端到端冒烟测试
└── test/plugin-load.js # 插件加载与工具 schema 验证

冒烟测试（不经插件宿主，直接调用 lib 层）：

node test/smoke.js <截图路径>                      # 首次评审
node test/smoke.js <截图路径> --ask "哪个按钮颜色最刺眼"   # 追问
node test/smoke.js <截图路径> --focus "配色和谐度"        # 带关注点评审
node test/plugin-load.js                            # 插件加载与 schema 验证