setup-vision-helper

配置视觉助手（借眼睛）

目标：让纯文本主模型（如 deepseek）在遇到图片时，自动通过一个视觉子 agent（vision-helper）"借眼睛"；而当主模型本身支持视觉时，直接用主模型自己的眼睛，不调用子 agent。配置一次，之后切换主模型无需任何操作。

意图判断（先做）

本 skill 只会在两个明确表述下被触发，直接映射即可：

• 用户说"帮我配置视觉助手" → 走下方「执行步骤」配置流程。
• 用户说"删除视觉助手" / "卸载视觉助手" / "移除视觉助手" → 走下方「删除视觉助手」流程。
• 若触发了但用户表述与上述不符（例如只说了一半或加了奇怪内容）→ 先向用户确认意图，不要自行展开。

删除视觉助手

当用户意图是删除/卸载视觉助手时：

1. 确认：先向用户确认"将删除 vision-helper 子 agent 和 AGENTS.md 中的路由规则，是否继续？"（删除不可逆）。
2. 删除子 agent：删除 <主目录>/.zcode/agents/vision-helper.md（若存在）。
3. 移除路由规则：从 <主目录>/.zcode/AGENTS.md 中删除"图片处理（视觉助手）"小节（含 vision-helper 关键字的部分）。若删除后文件为空，可保留空文件或删掉文件，向用户说明。
4. provider 配置默认不动：不要修改 config.json——补的 image 模态（以及已有的 apiFormat，如有）是该模型本身的正确配置（若它同时被当主模型用，删了反而会坏）。仅当用户明确要求回滚 config 时，才逐项询问要回滚哪一项。
5. 报告：列出删除了什么、保留了什么（config 未动），提示重启 ZCode 后子 agent 才会从列表中消失。

重要原则（违反会出错）

1. 不要用 modalities.input 过滤模型。ZCode 自定义模型的 modalities 字段经常滞后于真实能力（例如 qwen3-vl-flash 字段里只有 text，但实际支持图片）。候选清单列出所有已启用模型，让用户自己拍板哪个是"眼睛"。不要加提示、不要排除任何模型，只做清晰罗列。
2. 不要向用户索要 API Key。key 应该由用户在 ZCode 设置里自行添加，本 skill 只复用已配置的 provider。
3. 不要修改主模型选择，不要改动除"眼睛"以外的任何 provider/model 配置。
4. 所有文件操作都用文件工具完成，并在结束时自检（文件存在、JSON 合法）。

执行步骤

1. 定位配置文件

• 解析用户主目录：$HOME（macOS/Linux）或 %USERPROFILE%（Windows），兜底 os.homedir()。
• 主配置文件：<主目录>/.zcode/v2/config.json。若不存在，搜索 <主目录>/.zcode/ 下其他含 provider 键的 json（如 config.json、cli/config.json），并告知用户实际使用的位置。
• 读取 provider 对象。

2. 列出候选"眼睛"

• 收集所有 enabled（未显式禁用）的 provider 及其 models。
• 不加任何提示/注释，用编号列表清晰展示，格式：

  [1] qwen3-vl-flash  @ qwen3-vl-flash（deepseek的眼睛）
  [2] deepseek-v4-flash  @ deepseek
  ...
  请回复编号选择"眼睛"模型（或直接输入模型 id）。
  

3. 等待用户选择

• 用户回复编号 → 解析为对应模型；用户直接输入 id → 用之。
• 如果用户选择的是不在列表中的模型 id，允许，但提醒确认该模型已配置且可用。

4. 执行配置

a. 给眼睛模型补齐 image 模态（尽力而为，失败不中断）：

• 在 provider.<该provider键>.models.<模型id>.modalities.input 中，若不含 "image"，补上（["text","image"]，保留原有其他值）。
• 若写入失败（如文件只读、被占用），警告用户可跳过——因为部分客户端不按该字段门控，补字段只是让 UI 与未来逻辑保持一致。
• 不要改动该模型的其他字段，不要改动其他任何模型。

b. 创建视觉子 agent（文件：<主目录>/.zcode/agents/vision-helper.md）：

---
name: vision-helper
description: 看图并描述图片内容、回答与图片有关的问题。当主模型无法直接看到图像时使用。
model: custom:<眼睛模型所属 provider 的键>:<眼睛模型 id>
tools: [Read]
---

你是视觉助手。使用 Read 工具读取用户提供的图片文件路径，详细描述图片内容，
并回答主 agent 提出的关于这张图片的问题。最后用文字总结返回。

• model 字段必须用 custom:<provider键>:<模型id> 格式（与"设置 → Subagents"界面生成的一致，provider 键即 config.json 中该 provider 的 key，例如 custom:8b29396f-xxxx:qwen3-vl-flash）。不要用裸模型 id（会被当作默认 provider），也不要用手写斜杠格式。
• 若该文件已存在且 model 与本次选择不同 → 先问用户"当前眼睛是 X，要换成 Y 吗？"，确认后覆盖。
• 若已存在且相同 → 跳过，提示已配置。
• 提示用户：也可以直接在"设置 → Subagents"界面创建（Model 选眼睛模型），效果等同。