@mengruo/dsh-vision-toolkit 0.0.1

package/assets/skill/references/restore-structure.md

@@ -0,0 +1,45 @@
+# Turning a visual diagram into structured code
+
+**When to use**: the task is converting a sketch, flowchart, architecture
+diagram, or whiteboard into Mermaid, Graphviz, JSON, or another structured
+representation. The goal is semantic and topological fidelity, not matching
+the source renderer pixel for pixel.
+
+## Steps
+
+1. Run one full-image `vision_glance` pass for the diagram type, reading
+   direction, major groups, and visual conventions.
+2. Use `vision_detect` for the initial node and label inventory. Refine dense
+   groups by passing each group's box as `region`.
+3. Use OCR for labels. Preserve visible spelling, punctuation, and
+   abbreviations verbatim; write `[unreadable]` instead of guessing.
+4. Locate ambiguous arrows, connectors, legends, and group boundaries with
+   `vision_ground` and targeted `vision_glance` calls using `region`.
+5. Build an explicit intermediate inventory before writing the output:
+   nodes, labels, groups, edges, directions, and edge labels.
+6. Generate the Mermaid, Graphviz, or requested structure from that inventory.
+
+## Verify structure, not pixels
+
+Render the result, inventory it again, and compare these facts with the
+reference:
+
+- node count and label set
+- group membership and nesting
+- edge list and direction
+- edge labels and branch conditions
+- start/end or input/output roles
+
+Pixel differences are expected because the target renderer chooses its own
+fonts, spacing, and routing. A missing node or reversed arrow is a failure even
+when the two images look broadly similar; a different curve or gap is not a
+failure when the structure is correct.
+
+## Boundaries
+
+- Do not tidy labels, expand abbreviations, or silently repair wording unless
+  the user asks for editorial cleanup.
+- Do not infer an edge from proximity alone. If its endpoint or direction is
+  unclear, zoom into the connector and mark unresolved facts explicitly.
+- If the user wants a visual SVG copy rather than structured code, follow
+  `restore-graphic.md` instead.

package/assets/skill/references/restore-ui.md

@@ -0,0 +1,202 @@
+# Rebuilding a UI from a reference image
+
+**When to use**: the task is turning a screenshot or design image into a
+page, component, or application UI in HTML/CSS or the project's existing
+frontend stack. Checking an existing implementation against its reference is
+the same workflow entered at Verify. For an isolated icon, logo, or
+illustration, read `restore-graphic.md`; for Mermaid, Graphviz, or another
+structured diagram, read `restore-structure.md`.
+
+## Choose the restore mode
+
+- Use **fast restore mode** when the user asks for a quick, rough,
+  approximate, prototype, or first-pass reconstruction, explicitly values
+  speed over fidelity, or the reference image itself shows a floating
+  speed-intent control such as "快速还原为 HTML" / "快速生成" / "quick
+  restore" overlay. Its target is a recognizable screenshot in about
+  three minutes when the project already runs.
+- Use the **standard restore workflow** below when the user asks for close,
+  precise, pixel-level, or production-ready alignment, or does not opt into a
+  faster approximation.
+
+## Fast restore mode: first screenshot in about three minutes
+
+Fast mode preserves the page's hierarchy, major regions, visible text, and
+primary state. It deliberately approximates fine spacing, exact colors,
+typography, shadows, decorative details, and icon geometry.
+
+### Hard limits
+
+1. Inspect the existing frontend stack, component library, icon set, source
+   assets, and design tokens before writing code, but stop searching as soon as
+   a usable local primitive is found.
+2. Run one full-image `vision_detect` pass. Treat its boxes as layout estimates
+   and do not start a region-by-region inventory.
+3. After that `vision_detect` pass, use at most **six sequential image-inspection
+   rounds** through `view_image` (or the host's equivalent built-in viewer) and
+   `vision_glance`. Each round may launch up to three independent calls
+   concurrently, so the hard ceiling is 18 calls across six rounds. Batch unrelated regions
+   or questions into the same round instead of waiting for each result before
+   starting the next call. Normally one or two rounds are enough.
+4. Do not use `vision_trace`, foreground extraction, repeated color sampling,
+   iterative `vision_pixel_diff` work, or hand-written SVG in fast mode. Those
+   are fidelity tools and will consume the delivery window. Icons and decorative
+   marks stay library-based or screenshot-backed; never hand-write SVG code.
+
+### Build the approximation
+
+1. Implement the largest layout regions first, then visible text, primary
+   controls, and the most important state. Ignore details that are only visible
+   when zoomed in.
+2. Reuse the project's existing components and CSS tokens. If its frontend or
+   icon library contains a reasonably similar component or icon, use it
+   directly instead of recreating the reference. Never hand-write SVG in fast
+   mode: use an approximate library icon, or extract the original pixels as a
+   screenshot-backed asset.
+3. Use nearby existing palette tokens or visually similar CSS values. Exact
+   sampled hex values, gradients, subtle borders, and shadow opacity are out of
+   scope unless one of them defines the whole composition.
+4. Keep text and controls native, selectable, and interactive. Fast mode relaxes
+   visual fidelity, not basic UI behavior.
+
+### Render once, fix once, deliver
+
+1. Render the target viewport with `vision_html_screenshot` or the project's
+   existing browser setup.
+2. Inspect the screenshot once. If there is an obvious structural failure such
+   as a missing major region, broken wrapping, or a wildly wrong scale, make
+   one focused correction and render once more.
+3. Deliver the screenshot. Stop instead of spending the remaining time on
+   small color, icon, font, shadow, radius, or spacing differences.
+
+A practical time box is roughly 30 seconds for project inspection plus
+`vision_detect`, 90 seconds for implementation, and the remaining minute for startup,
+rendering, one correction, and screenshot delivery. Dependency installation or
+a project that does not already run may extend that target; do not compensate
+by silently switching back to a long precision loop.
+
+## Standard restore workflow
+
+### Core strategy: code-native UI plus screenshot-backed visuals
+
+Do not choose one reconstruction mode for the whole page. Classify each
+element separately. Most finished pages should combine both kinds:
+
+| Kind | Build it this way | Typical examples |
+|---|---|---|
+| **Code-native component** | Reuse the project's component library or build it with semantic HTML, CSS, and simple SVG primitives | layout, text, buttons, inputs, cards, tabs, dividers, backgrounds, simple geometric badges |
+| **Screenshot-backed visual** | Extract the original pixels, remove the background when needed, and place the result as an image asset | logos, proprietary icons, illustrations, decorative artwork, textures, complex static marks |
+
+Use this decision order for every element:
+
+1. **Reuse an existing component or source asset from the project.** Search
+   before recreating anything.
+2. **Use a code-native component** when the element contains text, accepts
+   input, changes state, must respond to layout, or is simple to express with
+   the project's normal primitives.
+3. **Use a screenshot-backed visual** when it is static, visually distinctive,
+   expensive to redraw, and no source asset exists.
+4. Rebuild a vector only when the user requires SVG/editability, the visual
+   must scale beyond the screenshot resolution, or extraction cannot isolate
+   it cleanly. Follow `restore-graphic.md` for that branch.
+
+Never flatten text, controls, or a large layout block into a screenshot. Never
+redraw extractable brand artwork merely to make the implementation look more
+"native". For a complex widget, keep the shell, text, and interaction native;
+use an extracted image only for its static decorative layer.
+
+## Steps
+
+### 1. Preserve the reference and inspect the target project
+
+If the reference is in a temporary path, copy it to durable work storage
+before the first tool call. Inspect the existing stack, component library,
+fonts, icons, images, and design tokens before writing replacements.
+
+### 2. Establish the coordinate system
+
+Record the reference image dimensions and the target viewport. Screenshots may
+be HiDPI: `vision_detect`, `vision_ground`, and `vision_crop` report image
+pixels, while CSS uses logical pixels. Derive the scale from the actual image and viewport dimensions;
+do not assume a fixed 2x ratio.
+
+### 3. Inventory the UI outside-in
+
+1. Run one full-image `vision_detect` pass for the initial element list and
+   boxes.
+2. Call `vision_detect` with `region` on dense layout blocks; a full-screen pass
+   is only a scaffold.
+3. Use `vision_glance` for hierarchy, component type, visual state, and styling.
+4. Use OCR for visible text and `vision_ground` for a specific element that
+   remains ambiguous.
+
+Treat model boxes as approximate handles. Use them to organize the page, but
+do not mistake their final few pixels for measured boundaries.
+
+### 4. Classify before implementing
+
+Make a short element list with one of these decisions: reuse existing source,
+code-native, screenshot-backed, or hybrid. This prevents two costly mistakes:
+rebuilding complex artwork from scratch and turning functional UI into static
+image patches.
+
+### 5. Extract screenshot-backed visuals
+
+Use a padded crop only to inspect and center the target. Before foreground
+extraction, tighten the final region to the visual's own ink; adjacent text or
+rules inside the region can become foreground components too.
+
+```json
+{"image":"shot.png","region":"X1,Y1,X2,Y2","scale":4,"output":"icon4x.png"}
+{"image":"<icon4x-artifact-path>","output":"icon.clean.png"}
+{"image":"shot.png","region":"X1,Y1,X2,Y2","output":"icon.png"}
+{"image":"shot.png","region":"X1,Y1,X2,Y2","mode":"dark","output":"logo.png"}
+```
+
+Inspect the transparent result before use. Confirm that the whole visual is
+present, no neighboring text or border leaked in, and the alpha edge remains
+clean. When extracting several assets, inspect them together in a contact
+sheet instead of checking them from filenames alone.
+
+### 6. Implement the native frame
+
+- Follow the project's existing framework and component patterns.
+- Build content, interaction, responsive layout, borders, shadows, and simple
+  shapes natively.
+- Use `vision_dominant_colors` for important background, text, and accent
+  values; use `vision_glance` to name a color, not to invent its numeric value.
+- Place extracted assets with explicit logical dimensions. Preserve their
+  aspect ratio and avoid baking surrounding whitespace into the asset.
+- Match structure and proportions before tuning small spacing.
+
+## Verify and converge by impact
+
+For an existing implementation, start here.
+
+1. Render at the same logical viewport with `vision_html_screenshot` or the
+   project's browser test setup.
+2. Compare the render and reference at the same dimensions. Inspect them side
+   by side; use `vision_pixel_diff` to locate differences that are hard to
+   spot or explain.
+3. Fix material discrepancies: missing or wrong content, incorrect hierarchy,
+   broken wrapping, visibly wrong alignment or scale, wrong component state,
+   distorted assets, and clearly different primary colors.
+4. Re-render after a meaningful fix. Continue while the comparison exposes a
+   user-visible defect; stop when the remaining difference is font
+   rasterization, antialiasing, subpixel placement, or another imperceptible
+   rendering detail.
+
+`vision_pixel_diff` is a locator, not the acceptance target. Do not keep iterating only
+to lower its aggregate percentage, and do not promise zero-difference output
+from a screenshot without a separately scoped browser, font, viewport, and
+rendering environment.
+
+## Boundaries
+
+- Do not ship a screenshot of the whole page as the implementation.
+- Do not use screenshot-backed text or controls that must remain selectable,
+  accessible, interactive, localized, or responsive.
+- Do not stretch an extracted bitmap beyond the resolution supported by the
+  reference. Obtain a source asset or rebuild a vector when it must scale.
+- Always compare against the original reference, never only against an earlier
+  version of your own render.

package/assets/upstream/README.md

@@ -0,0 +1,18 @@
+# Upstream reference images
+
+These files are README-sized derivatives of official [`Anionex/agent-vision-toolkit`](https://github.com/Anionex/agent-vision-toolkit) reference assets. They document upstream use cases; this DSH integration does not claim to have rerun or reproduced those results.
+
+The source files exist at the packaged runtime pin [`c27d1a300962b553c0884993c575cd3e819465ce`](https://github.com/Anionex/agent-vision-toolkit/tree/c27d1a300962b553c0884993c575cd3e819465ce) and were confirmed byte-identical in upstream commit [`7eafd51e7e62bd14f72627c69f2c11601c508f88`](https://github.com/Anionex/agent-vision-toolkit/tree/7eafd51e7e62bd14f72627c69f2c11601c508f88) on August 11, 2026.
+
+| Local derivative | Upstream source |
+|---|---|
+| `infographic-reference.webp` | `assets/infographic-restore-reference.png` |
+| `infographic-result.webp` | `assets/infographic-restore-result.png` |
+| `ui-sketch.webp` | `assets/ui-restore-sketch.png` |
+| `ui-result.webp` | `assets/ui-restore-result.png` |
+| `focus-hint-comparison-1.webp` | `assets/focus-hint-comparison-1.png` |
+| `focus-hint-comparison-2.webp` | `assets/focus-hint-comparison-2.png` |
+| `ui-fast-restore-reference.webp` | `assets/ui-fast-restore-reference.png` |
+| `ui-fast-restore-result.webp` | `assets/ui-fast-restore-result.png` |
+
+Each derivative preserves the complete frame, limits the longest edge to 1200 pixels, removes metadata, and uses WebP quality 90 for repository delivery. The originals and visual algorithms remain covered by the upstream [MIT License](https://github.com/Anionex/agent-vision-toolkit/blob/c27d1a300962b553c0884993c575cd3e819465ce/LICENSE).

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# dsh-vision-toolkit bundle patch: mounts the plugin into a profile layer stack.
+# Runtime defaults live at the plugin's config boundary. Users override them in
+# their profile patch row with the same id.
+- insert:
+    - id: vision-toolkit
+      name: '@mengruo/dsh-vision-toolkit'

package/docs/aihubmix-gemini-vision.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write dsh-vision-toolkit/docs/aihubmix-gemini-vision.md
+aihubmix-gemini-vision.md: c2958163461843045fc4547e56fbaae78d1b9f72
+aihubmix-gemini-vision.zh.md: dd2ba9246bb921f4986cacfd28e31aaeec4903e3

package/docs/aihubmix-gemini-vision.md

@@ -0,0 +1,138 @@
+# Get an AIHubMix API key and use free Gemini 3.7 Flash for vision
+
+**English** | [中文](aihubmix-gemini-vision.zh.md)
+
+This tutorial completes three tasks:
+
+1. Create an AIHubMix account.
+2. Create and safely store an AIHubMix API key.
+3. Use the free `gemini-3.7-flash-free` model for image analysis in DSH Vision Toolkit.
+
+> As of August 20, 2026, the AIHubMix model page lists `gemini-3.7-flash-free` as a free trial model with image input. Free capacity is limited, may return `429`, and is not guaranteed for production workloads; use the paid `gemini-3.7-flash` route when reliability is required. Models, pricing, and availability can change, so check the [AIHubMix model page](https://aihubmix.com/model/gemini-3.7-flash-free) for current details.
+
+## 1. Open the signup entry and register
+
+Open the [Inferera signup entry](https://inferera.com/?aff=5wj6sgx8), which redirects to AIHubMix, then select **Sign up** in the upper-right corner or **Get API Key** on the page.
+
+This URL includes the project's referral parameter. You can instead open [Inferera](https://inferera.com/) directly if you prefer not to use a referral link.
+
+<p align="center">
+  <img src="assets/aihubmix-home.png" width="92%" alt="AIHubMix homepage and signup entry" />
+</p>
+
+The signup page supports GitHub, Google, and email. For email signup, enter an email address and password, accept the terms, and complete any verification requested by the page.
+
+<p align="center">
+  <img src="assets/aihubmix-sign-up.png" width="92%" alt="AIHubMix account signup page" />
+</p>
+
+## 2. Create an API key
+
+After signing in, open **Developer → API Keys** in the console sidebar, or go directly to [AIHubMix API Keys](https://console.aihubmix.com/token). The page shows two endpoint hosts:
+
+- Default: `https://aihubmix.com`
+- Preferred: `https://api.inferera.com`
+
+This guide uses the preferred `https://api.inferera.com/v1` endpoint in Vision Toolkit. If that endpoint does not work from your network, use `https://aihubmix.com/v1` instead.
+
+<p align="center">
+  <img src="assets/aihubmix-api-keys.png" width="88%" alt="AIHubMix API Keys page with default and preferred base URLs and the Create API key button" />
+</p>
+
+Select **Create API key**, then:
+
+1. Enter a recognizable name such as `dsh-vision-toolkit`.
+2. For an initial trial, turn off unlimited quota and set a small quota, expiration date, model range, or IP restriction so a later paid-model mistake cannot spend without a limit.
+3. Select **Submit** to create the key.
+4. Copy the complete `sk-...` value immediately and store it in a password manager or DSH Credential.
+
+<p align="center">
+  <img src="assets/aihubmix-create-key.png" width="56%" alt="AIHubMix Create API key form" />
+</p>
+
+Do not place the complete key in a README, chat transcript, screenshot, Git commit, browser frontend, or public log. Delete and replace a key immediately if it becomes public.
+
+## 3. Select the free vision model
+
+Use this exact model ID:
+
+```text
+gemini-3.7-flash-free
+```
+
+The model page lists it as free and shows text, image, audio, video, and PDF input. Vision Toolkit uses its image input and text output.
+
+<p align="center">
+  <img src="assets/aihubmix-free-vision-model.png" width="92%" alt="AIHubMix Gemini 3.7 Flash free model page showing image input" />
+</p>
+
+The free route is for trials and can return `429 Too Many Requests` when capacity is exhausted. For reliable usage, switch the model to `gemini-3.7-flash` and ensure the account has sufficient credit. Optional capabilities such as web search or cache storage may have separate charges; ordinary Vision Toolkit image analysis does not enable them.
+
+## 4. Configure DSH Vision Toolkit
+
+1. Open **Settings → Vision** in DSH Web.
+2. Enter these values under the vision service:
+
+| Field | Value |
+|---|---|
+| API protocol | `OpenAI Chat Completions` |
+| Base URL | `https://api.inferera.com/v1` |
+| Model | `gemini-3.7-flash-free` |
+| API key | Paste the newly created `sk-...` key |
+
+3. Expand **Advanced settings** and change **Credential name** to `AIHUBMIX_API_KEY` instead of reusing the built-in free provider's credential name.
+4. Select **Save and apply**. The key is stored in DSH Credentials and is not displayed again in full.
+5. Select **Test vision model**. This action sends the bundled diagnostic image and verifies a real multimodal request; **Test API connection**, which only queries `/models`, is not a substitute.
+6. After the test succeeds, paste an image into a session and ask a concrete question, for example:
+
+```text
+Transcribe the error in this screenshot exactly, then explain the most likely cause and the repair steps.
+```
+
+The same provider can be stored in a Profile patch. Keep the key value in DSH Credentials rather than YAML:
+
+```yaml
+- id: vision-toolkit
+  config:
+    provider:
+      protocol: openai
+      baseUrl: https://api.inferera.com/v1
+      model: gemini-3.7-flash-free
+      credential: AIHUBMIX_API_KEY
+```
+
+## 5. Troubleshooting
+
+### `401` or `Unauthorized`
+
+- Confirm that you pasted the complete `sk-...` value, not the key name or a masked fragment.
+- Remove extra spaces, line breaks, or an `AIHUBMIX_API_KEY=` prefix from the value.
+- Delete and replace a key that has appeared in a public location.
+
+### `402`, insufficient credit, or an unavailable model
+
+- The free trial route must use the full `gemini-3.7-flash-free` model ID.
+- If you switch to `gemini-3.7-flash` or another paid model, add credit from **Credits** in the console.
+- Model availability changes; check the current AIHubMix model page and console.
+
+### `404` or `model not found`
+
+- Use exactly `gemini-3.7-flash-free`.
+- Do not send the display name `Gemini 3.7 Flash (free)` as the API model ID.
+
+### `429 Too Many Requests`
+
+- Free-model capacity is limited. Wait and retry, or lower concurrency and request frequency.
+- Switch to `gemini-3.7-flash` when stable production service is required.
+
+### Connection timeout or unreachable endpoint
+
+- Start with this guide's `https://api.inferera.com/v1` endpoint.
+- If it is unavailable, switch to `https://aihubmix.com/v1` and rerun **Test vision model**.
+
+## Official resources
+
+- [Inferera signup entry](https://inferera.com/?aff=5wj6sgx8)
+- [AIHubMix API Keys](https://console.aihubmix.com/token)
+- [AIHubMix documentation](https://docs.aihubmix.com/en)
+- [Gemini 3.7 Flash (free) model page](https://aihubmix.com/model/gemini-3.7-flash-free)

package/docs/aihubmix-gemini-vision.zh.md

@@ -0,0 +1,138 @@
+# 申请 AIHubMix API Key，并用免费 Gemini 3.7 Flash 识图
+
+[English](aihubmix-gemini-vision.md) | **中文**
+
+这篇教程完成三件事：
+
+1. 注册 AIHubMix 账号。
+2. 创建并安全保存一个 AIHubMix API Key。
+3. 在 DSH Vision Toolkit 中使用免费的 `gemini-3.7-flash-free` 分析图片。
+
+> 截至 2026-08-20，AIHubMix 模型页把 `gemini-3.7-flash-free` 标为支持图像输入的免费试用模型。免费资源有限，可能返回 `429`，不保证生产环境稳定性；生产用途应切换到正式模型 `gemini-3.7-flash`。模型、价格和可用性可能调整，请以 [AIHubMix 模型页](https://aihubmix.com/model/gemini-3.7-flash-free) 为准。
+
+## 1. 打开申请入口并注册
+
+打开 [Inferera 国内申请入口](https://inferera.com/?aff=5wj6sgx8)，页面会跳转到 AIHubMix；点击右上角 **注册**，也可以点击页面中的 **立即体验**。
+
+这个入口带有本项目的推荐参数；如果不想使用推荐链接，也可以直接访问 [Inferera](https://inferera.com/)。
+
+<p align="center">
+  <img src="assets/aihubmix-home.png" width="92%" alt="AIHubMix 中文首页与注册入口" />
+</p>
+
+注册页支持 GitHub、Google 或邮箱。使用邮箱时，填写邮箱和密码、同意服务条款，然后按页面提示完成验证。
+
+<p align="center">
+  <img src="assets/aihubmix-sign-up.png" width="92%" alt="AIHubMix 中文注册页面" />
+</p>
+
+## 2. 创建 API Key
+
+登录后进入控制台左侧的 **开发 → API Keys**，或直接打开 [AIHubMix API Keys](https://console.aihubmix.com/token)。页面会同时显示两个接口地址：
+
+- 默认地址：`https://aihubmix.com`
+- 优选地址：`https://api.inferera.com`
+
+本教程在 Vision Toolkit 中使用优选地址 `https://api.inferera.com/v1`。如果该地址在你的网络中不可用，可以改用 `https://aihubmix.com/v1`。
+
+<p align="center">
+  <img src="assets/aihubmix-api-keys.png" width="88%" alt="AIHubMix API Keys 页面中的默认地址、优选地址和 Create API key 按钮" />
+</p>
+
+点击 **创建 Key**（英文界面显示 **Create API key**），然后：
+
+1. 在 **名称** 中填写容易辨认的名称，例如 `dsh-vision-toolkit`。
+2. 首次试用建议关闭无限额度，并设置小额上限、过期时间、模型范围或 IP 限制，避免以后误用付费模型时产生无上限费用。
+3. 点击 **提交** 创建密钥。
+4. 立即复制完整的 `sk-...` 密钥，并保存到密码管理器或 DSH Credential 中。
+
+<p align="center">
+  <img src="assets/aihubmix-create-key.png" width="56%" alt="AIHubMix Create API key 表单" />
+</p>
+
+不要把完整 API Key 放进 README、聊天记录、截图、Git 提交、浏览器前端代码或公开日志。密钥泄露后应立即删除旧 Key 并重新创建。
+
+## 3. 选择免费的视觉模型
+
+本教程使用准确模型 ID：
+
+```text
+gemini-3.7-flash-free
+```
+
+模型页将它标为免费，并列出文本、图像、音频、视频和 PDF 输入能力。Vision Toolkit 使用其中的图像输入和文本输出。
+
+<p align="center">
+  <img src="assets/aihubmix-free-vision-model.png" width="92%" alt="AIHubMix Gemini 3.7 Flash free 模型页显示图像输入能力" />
+</p>
+
+免费版本只适合试用，资源紧张时可能返回 `429 Too Many Requests`。需要稳定调用时，把模型改为 `gemini-3.7-flash`，并确认账户余额足够。模型页列出的联网搜索、缓存等可选能力可能单独计费；Vision Toolkit 的普通图片分析不会主动启用这些能力。
+
+## 4. 在 DSH Vision Toolkit 中使用
+
+1. 打开 DSH Web 的 **设置 → 视觉工具**。
+2. 在“在线视觉服务”中填写：
+
+| 字段 | 值 |
+|---|---|
+| API 协议 | `OpenAI Chat Completions` |
+| API 地址 | `https://api.inferera.com/v1` |
+| 模型名称 | `gemini-3.7-flash-free` |
+| API 密钥 | 粘贴刚创建的 `sk-...` 密钥 |
+
+3. 展开 **高级设置**，把 **凭据名称** 改为 `AIHUBMIX_API_KEY`，避免继续使用内置免费服务的凭据名称。
+4. 点击 **保存设置**。密钥会写入 DSH Credentials，页面以后不会回显完整内容。
+5. 点击 **测试视觉模型**。这个测试会发送插件自带的诊断图片，验证真实多模态请求；只测试 `/models` 的 **测试 API 连接** 不能代替它。
+6. 测试成功后，在会话中粘贴图片并直接提问，例如：
+
+```text
+请先逐字抄出截图中的报错，再判断最可能的原因和修复步骤。
+```
+
+也可以在 Profile patch 中保存相同配置。密钥值仍应保存在 DSH Credential 中，不要写入 YAML：
+
+```yaml
+- id: vision-toolkit
+  config:
+    provider:
+      protocol: openai
+      baseUrl: https://api.inferera.com/v1
+      model: gemini-3.7-flash-free
+      credential: AIHUBMIX_API_KEY
+```
+
+## 5. 常见问题
+
+### `401` 或 `Unauthorized`
+
+- 确认粘贴的是完整的 `sk-...` 密钥，而不是 Key 名称或被遮盖后的片段。
+- 粘贴的密钥值中不要包含多余空格、换行或 `AIHUBMIX_API_KEY=` 前缀。
+- 如果密钥曾经公开，删除旧 Key 并重新创建。
+
+### `402`、余额不足或模型不可用
+
+- 免费试用模型应使用完整 ID `gemini-3.7-flash-free`。
+- 如果改用 `gemini-3.7-flash` 或其他付费模型，请在控制台的 **余额充值** 中补充余额。
+- 模型可用性会变化，请以 AIHubMix 当前模型页和控制台为准。
+
+### `404` 或 `model not found`
+
+- 模型名必须准确写成 `gemini-3.7-flash-free`。
+- 不要把显示名称 `Gemini 3.7 Flash (free)` 当作 API 模型 ID。
+
+### `429 Too Many Requests`
+
+- 免费模型资源有限，等待后重试，或降低并发和调用频率。
+- 需要稳定生产调用时切换到 `gemini-3.7-flash`。
+
+### 连接超时或无法访问
+
+- 先使用本教程推荐的 `https://api.inferera.com/v1`。
+- 如果该地址不可用，改为 `https://aihubmix.com/v1` 后重新执行 **测试视觉模型**。
+
+## 官方资料
+
+- [Inferera 国内申请入口](https://inferera.com/?aff=5wj6sgx8)
+- [AIHubMix API Keys](https://console.aihubmix.com/token)
+- [AIHubMix 中文文档](https://docs.aihubmix.com/cn)
+- [Gemini 3.7 Flash (free) 模型页](https://aihubmix.com/model/gemini-3.7-flash-free)