（可选）配置 agent 工具平面：让模型能自己截图 + 识图

node ~/.dsh/profiles/web/node_modules/@linenxi-ctrl/dsh-vision/install.mjs

安装后**无需手动改任何配置文件**：`package.json` 的 `dsh.bundle.patch` 声明会被 DSH 自动 reconcile 进 profile 的 `dsh.profile.bundles`，`cordis.patch.yml` 即成为该 profile 的一个 bundle layer。

### 方式二：手动 / 离线（无需 pnpm，小白友好）

从 [Releases](https://github.com/linenxi-ctrl/dsh-vision/releases) 下载 zip 解压：

1. Windows 双击 `install.bat`，macOS/Linux 运行 `bash install.sh`——**无需预装 Node.js**：脚本检测不到时会自动从国内镜像（npmmirror / 华为云 / 腾讯云）下载免安装版（无需管理员权限）；
2. 脚本会自动：复制英文副本、复制进每个 profile 的 `node_modules`、在 `cordis.patch.yml` 加 vision 行、创建 agent preset `vision`（复制随附 standard 并加入识图工具）并设为默认；
3. **重启 DSH**（关闭后重新 `dsh web`）。

> 实测要点（DSH 0.1.0-rc.6）：host + client 插件（`cordis.patch.yml`）的 `name` 必须用「包名」，插件须在 profile 的 `node_modules` 下；agent 工具插件（preset）的 `name` 支持绝对路径（自动转 `file://`）；agent preset 不能叫 `standard`（会被随附 standard 遮蔽）。

## 配置

点页面右下角鲸鱼按钮，或直接编辑 `$DSH_HOME/settings.yaml` 中的 `vision` 段：

| 字段 | 默认值 | 说明 |
|---|---|---|
| `apiBase` | `https://api.openai.com/v1` | 识图模型地址（按所选协议填到基础路径即可） |
| `apiKey` | 空 | API 密钥（secret，不回显） |
| `model` | `gpt-4o-mini` | 模型名称 |
| `protocol` | `auto` | 协议：`auto` / `openai-chat` / `openai-responses` / `anthropic` / `gemini` / `custom` |
| `prompt` | 见下 | 识图提示词（skill），可自定义 |
| `proxy` | 空 | 可选 HTTP 代理，如 `http://127.0.0.1:65532` |
| `timeoutMs` | `60000` | 单次识图超时（毫秒） |
| `requestTemplate` | 空 | 仅 `custom`：请求体 JSON 模板 |
| `responsePath` | 空 | 仅 `custom`：响应文本取路径，如 `choices.0.message.content` |

默认识图提示词：

> 你是一名专业的图像识别助手。请仔细观察用户提供的图片……（详细描述 + 逐字转录文字 + 截图场景重点描述）

## 使用

- **发送图片识图**：打开一个会话后，点右下角鲸鱼按钮 → 面板点「📤 发送图片」选图。识别期间右上角显示「外挂模型正在识图当中」，完成后自动把识别文本发回当前会话。
- **模型自主识图**：直接对模型说「看看我现在屏幕上的报错」，模型会调用 `screenshot` 截图、再调用 `recognize_image` 识图并继续。

## API 协议自动适配

`protocol` 默认 `auto`，按 `apiBase` 自动识别；也可手动指定：

| 协议 | 识别条件 / 用法 | 请求要点 | 响应取文本 |
|---|---|---|---|
| `openai-chat` | 默认；`apiBase` 填到 `/v1` | `POST /chat/completions`，`image_url` 内嵌 data URL | `choices[0].message.content` |
| `openai-responses` | `apiBase` 含 `/responses` | `POST /responses`，`input_image` | `output[].content[].text` |
| `anthropic` | `apiBase` 含 `anthropic` | `POST /v1/messages`，`x-api-key` 头，`source.base64` | `content[].text` |
| `gemini` | `apiBase` 含 `gemini`/`generativelanguage`/`googleapis` | `POST /models/{model}:generateContent`，`inline_data`，`x-goog-api-key` 头 | `candidates[0].content.parts[].text` |
| `custom` | 手动指定 | 按 `requestTemplate` 构造 | 按 `responsePath` 取路径 |

### custom 模板协议

`custom` 用于适配上述四种之外的长尾接口：

- **`requestTemplate`**：请求体 JSON 模板。占位符**必须裸写（不带引号）**，替换时会自动补上 JSON 引号。支持的占位符：
  - `{{model}}` → 模型名
  - `{{prompt}}` → 识图提示词
  - `{{image}}` → 图片纯 base64（不含 data: 前缀）
  - `{{dataUrl}}` → 完整 `data:image/...;base64,...`
  - `{{mime}}` → 图片 MIME 类型

  示例（等价于 OpenAI Chat）：
  ```json
  {"model":{{model}},"messages":[{"role":"user","content":[{"type":"text","text":{{prompt}}},{"type":"image_url","image_url":{"url":{{dataUrl}}}}]}]}

• responsePath：从响应 JSON 取文本的点号路径（数字为数组下标），如 choices.0.message.content、data.text、result.0.content。
• 鉴权默认走 Authorization: Bearer （apiKey 为空则不携带）；需要特殊鉴权头的接口暂不支持，可提 issue 扩展。

提示：占位符若误加了引号（写成 "{{image}}"），替换后会得到 ""base64"" 导致 JSON 非法。请保持裸写。

故障排查

现象	处理
识图失败：HTTP 401/403	apiKey 未填或填错，去面板重新保存密钥
识图失败：HTTP 404	apiBase 拼错或与协议不匹配；确认填到基础路径（如 OpenAI 填到 /v1，Anthropic 填 https://api.anthropic.com，Gemini 填到 /v1beta）
识图失败：结果为空	协议识别不对时手动指定 protocol；custom 协议检查 responsePath 是否正确
外网直连不通	在 proxy 填 http://127.0.0.1:65532（或你自己的代理）
点「发送图片」没反应	确认已打开一个会话；确认右下角有鲸鱼按钮（client 插件已挂载）
模型不调用识图工具	确认 tool.js 已加进 preset 的 agent.cordis.yml，且该会话使用该 preset
截图失败	Windows 下需 PowerShell 可用（System.Drawing）；macOS 用 screencapture；Linux 需 ImageMagick import

配置

点页面右下角鲸鱼按钮，或直接编辑 $DSH_HOME/settings.yaml 中的 vision 段：

字段	默认值	说明
apiBase	https://api.openai.com/v1	识图模型地址（按所选协议填到基础路径即可）
apiKey	空	API 密钥（secret，不回显）
model	gpt-4o-mini	模型名称
protocol	auto	协议：auto / openai-chat / openai-responses / anthropic / gemini / custom
prompt	见下	识图提示词（skill），可自定义
proxy	空	可选 HTTP 代理，如 http://127.0.0.1:65532
timeoutMs	60000	单次识图超时（毫秒）
requestTemplate	空	仅 custom：请求体 JSON 模板
responsePath	空	仅 custom：响应文本取路径，如 choices.0.message.content

默认识图提示词：

你是一名专业的图像识别助手。请仔细观察用户提供的图片……（详细描述 + 逐字转录文字 + 截图场景重点描述）

使用

• 发送图片识图：打开一个会话后，点右下角鲸鱼按钮 → 面板点「📤 发送图片」选图。识别期间右上角显示「外挂模型正在识图当中」，完成后自动把识别文本发回当前会话。
• 模型自主识图：直接对模型说「看看我现在屏幕上的报错」，模型会调用 screenshot 截图、再调用 recognize_image 识图并继续。