dsh-vision-tool

怎么使用

1. 安装

方式 A：作为 dsh 插件从 GitHub 安装

在目标 dsh 环境里执行（ 换成你的 profile 名）：

dsh plugin --profile 
 add github:YJLTF/dsh-vision-tool

与 dsh 官方打包安装文档一致，有三点注意：

• 构建授权：git 安装拉取的是源码而非构建产物，装完会由包内的 prepare 脚本构建出 lib/index.js。pnpm ≥ 10 默认拒绝为 git 依赖运行 prepare，首次 add 会失败——按 dsh 的提示，在 profile 的 pnpm-workspace.yaml 里放行后重试：

  allowBuilds:
    dsh-vision-tool: true
  

• 安全与钉版本：放行构建即允许该包代码在安装期于你机器上执行，请只对可信的包放行；建议钉住 commit：

  dsh plugin --profile 
  

add github:YJLTF/dsh-vision-tool#

- **层激活**：本包已声明 `dsh.bundle`（`cordis.patch.yml` + 挂载清单），`dsh plugin add` 安装后会自动作为 profile 层激活，无需手工改 patch 文件；若安装时日志出现 `declares no dsh.bundle — installed as a plain dependency` 警告，说明装到的是旧版本，请更新后重装。

#### 方式 B：从源码构建并挂载

```sh
git clone https://github.com/YJLTF/dsh-vision-tool
cd dsh-vision-tool
pnpm install
pnpm build      # tsdown（lib/index.js）+ tsc --emitDeclarationOnly（lib/types）+ 客户端 bundle（lib/client.js）
pnpm typecheck  # Host 类型检查（typecheck:client 为浏览器半侧）

然后在 dsh 的 profile（例如 cordis.patch.yml）中以挂载任意树外插件 bundle 的方式挂载 lib/index.js。

两种方式产出的 Host 半侧完全相同；客户端 bundle（lib/client.js）由 scripts/build-client.mjs 在本仓库内独立构建，随 pnpm build / prepare 一并产出。

2. 配置（settings → 命名空间 vision）

字段	类型	默认值	含义
enabled	boolean	true	总开关。关闭后指导不注入，两个识图工具都会拒绝执行。
visionProvider	string	''	小参数多模态模型的提供方路由（从 dsh 已配置模型中选）。
visionModel	string	''	小参数多模态模型的精确模型 id。
visionSystemPrompt	string	内置	视觉模型每次调用遵循的系统提示词。
maxTokens	number	2048	视觉调用最大输出 token 数（256–8192）。
guidanceInjection	boolean	true	是否为纯文本模型注入识图指导。
overrides	{model, modality}[]	[]	按模型显式声明模态；优先级高于适配器元数据（退避依据）。

推荐在 dsh web 端顶部 「插件」按钮 → 插件管理 → 已安装 → vision-tool 详情页的 "识图代理" 卡片中配置：卡片为暂存式编辑——改动后点 保存 一次写回（立即生效、无需重启），放弃 丢弃草稿。识图模型从下拉里选（列表即 dsh 已配置的全部模型，可用"刷新列表"重读），下方文本框同步显示当前选择；overrides 声明也可在卡片里增删。最小可用配置就是 provider / model 两项——任一为空时，understand_image 会报错提示"未配置视觉模型"，指导也不会注入。

必须的前置条件：所选的视觉模型要在 dsh 的模型配置（settings.yaml 的 provider models 列表）里声明图片输入能力，否则引擎会把发往视觉模型的请求中的图片字节一并投影掉——视觉模型只会看到一个 sha256: 占位符，无法真正识图：

llm-pi-ai:
  providers:
    
:
      models:
        - id: 
          input: [text, image]   # 关键：声明后引擎才放行图片字节

同理，overrides 中把某个模型标记为 image 也能达到同样效果（并触发本插件对该模型退避）。

3. 运行时行为

配置完成后，在会话里直接贴图提问即可：纯文本主模型收到的图片是一个文本占位符，系统提示中的指导会告诉它占位符背后的图片可以检查——它会自主调用：

{ "prompt": "结合当前任务与对话的具体问题" }

（省略 path 时检查会话中最近的一张图；多图场景模型可先调 list_conversation_images 挑选。）工具返回视觉模型的文本回答，主模型据此继续推理。若你的主模型本身支持图片输入，装不装这个插件没有区别——准入不拦、指导不注入、消息不改写。

2. 配置（settings → 命名空间 vision）

字段	类型	默认值	含义
enabled	boolean	true	总开关。关闭后指导不注入，两个识图工具都会拒绝执行。
visionProvider	string	''	小参数多模态模型的提供方路由（从 dsh 已配置模型中选）。
visionModel	string	''	小参数多模态模型的精确模型 id。
visionSystemPrompt	string	内置	视觉模型每次调用遵循的系统提示词。
maxTokens	number	2048	视觉调用最大输出 token 数（256–8192）。
guidanceInjection	boolean	true	是否为纯文本模型注入识图指导。
overrides	{model, modality}[]	[]	按模型显式声明模态；优先级高于适配器元数据（退避依据）。

推荐在 dsh web 端顶部 「插件」按钮 → 插件管理 → 已安装 → vision-tool 详情页的 "识图代理" 卡片中配置：卡片为暂存式编辑——改动后点 保存 一次写回（立即生效、无需重启），放弃 丢弃草稿。识图模型从下拉里选（列表即 dsh 已配置的全部模型，可用"刷新列表"重读），下方文本框同步显示当前选择；overrides 声明也可在卡片里增删。最小可用配置就是 provider / model 两项——任一为空时，understand_image 会报错提示"未配置视觉模型"，指导也不会注入。

必须的前置条件：所选的视觉模型要在 dsh 的模型配置（settings.yaml 的 provider models 列表）里声明图片输入能力，否则引擎会把发往视觉模型的请求中的图片字节一并投影掉——视觉模型只会看到一个 sha256: 占位符，无法真正识图：

llm-pi-ai:
  providers:
    
:
      models:
        - id: 
          input: [text, image]   # 关键：声明后引擎才放行图片字节

同理，overrides 中把某个模型标记为 image 也能达到同样效果（并触发本插件对该模型退避）。