@anionex/dsh-vision-toolkit 0.1.35 → 0.1.37

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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/README.md
-README.md: 5083c3bc9c77ab79eed171c5fbdeb428df274f77
-README.zh.md: 979935b0fad2fcdeccf290372dcb5b12176a2ecf
+README.md: f38885c9ef8b326808f9a43c8433e9e6a5c929db
+README.zh.md: 06e3133487ea5465a8c81e04a1a98308217c8432

package/README.md

@@ -30,6 +30,8 @@
 
 > **Original work:** The system and division of responsibilities behind these visual tools, together with the `vision-skills` Skill, were personally created and continuously refined by the author through long-term real-world use and repeated iteration.
 
+> If this project helps you or gives you some inspiration, feel free to star 🌟 & fork.
+
 ## Highlights
 
 - **Paste an image and ask directly.** In DSH Web, pasting an image switches the text-only model to its `(Vision Toolkit)` variant automatically — no manual path copying or model changes. Native thumbnails, session history, and workspace paths stay intact; Web can preview artifacts.
@@ -62,8 +64,8 @@ dsh plugin --profile web add @anionex/dsh-vision-toolkit
 
 <table>
 <tr>
-<td width="220"><a href="https://aihubmix.com/?aff=5wj6sgx8"><img src="assets/logo_aihubmix.png" alt="AIHubMix" height="48"></a></td>
-<td>Thanks to <a href="https://aihubmix.com/?aff=5wj6sgx8">AIHubMix</a> for sponsoring this project! AIHubMix is a stable, high-concurrency AI model API gateway that connects Claude, GPT, Gemini, DeepSeek, and other mainstream models through a single API key, compatible with multiple protocols, with <b>free model options</b> available. Users in China can use it via the <a href="https://inferera.com/?aff=5wj6sgx8">China entry</a>, and users abroad via the <a href="https://aihubmix.com/?aff=5wj6sgx8">Global entry</a>.</td>
+<td width="220"><a href="https://inferera.com/?aff=5wj6sgx8"><img src="assets/logo_aihubmix.png" alt="AIHubMix" height="48"></a></td>
+<td>Thanks to <a href="https://inferera.com/?aff=5wj6sgx8">AIHubMix</a> for sponsoring this project! AIHubMix is a stable, high-concurrency AI model API gateway that connects Claude, GPT, Gemini, DeepSeek, and other mainstream models through a single API key, compatible with multiple protocols, with <b>free model options</b> available. Use the <a href="https://inferera.com/?aff=5wj6sgx8">Inferera entry</a> to sign up.</td>
 </tr>
 </table>
 
@@ -84,10 +86,10 @@ dsh plugin --profile web add @anionex/dsh-vision-toolkit
 
 ## Recent updates
 
+- **2026-08-20 · AIHubMix setup guide:** Added a screenshot-based guide for getting an API key through the Inferera entry and using the free Gemini 3.7 Flash vision model; Settings now links directly to this guide.
 - **2026-08-19 · Transparent routing by default:** The model selector keeps one entry per model with the original name, and image input (paste, history, `read_image`) works without manually switching to a `(Vision Toolkit)` variant. Disable “Transparent variant routing” in advanced settings → image input to restore the explicit entries.
 - **2026-08-16 · Windows Python:** Added Microsoft Store Python support, fixing first-time isolated-runtime setup failures for affected Windows users.
 - **2026-08-17 · Free vision upgrade:** Switched the built-in no-key service to Gemini 3.7 Flash and fixed Qwen/Gemini bounding-box coordinate order.
-- **2026-08-16 · Better free vision:** Switched the built-in no-key service to Groq Qwen3.6, improving image understanding without adding setup steps.
 - **2026-08-16 · Image paste:** Text-only routes now switch to a `(Vision Toolkit)` variant and keep a workspace path, fixing blocked pastes and images that could not be reused later.
 - **2026-08-16 · More shared capacity:** Expanded the free service capacity to reduce peak-time `429` responses.
 - **2026-08-16 · Real model test:** Added a full image-request test in Settings, fixing the false confidence caused by a successful `/models` request to a model that still cannot process images.
@@ -178,7 +180,7 @@ For the full Desktop install, update, and troubleshooting walkthrough, see [Inst
 
 Restart a running Web Profile, then open **Settings → Vision Toolkit**. The free provider is already configured; run **Test vision model** to confirm it is reachable.
 
-The first start prepares an isolated runtime: the plugin prefers a system Python 3.11+; when none is found, it downloads a hash-verified standalone Python (about 35 MB) from a pinned release source on first use. A normal installation does not require an `agent-vision-toolkit` source checkout or a local path setting.
+The first start prepares an isolated runtime: the plugin prefers a system Python 3.11+; when none is found, it downloads a hash-verified standalone Python (about 35 MB) from the domestic mirror (`dsh-vision-python-bootstrap-1317715800.cos.ap-guangzhou.myqcloud.com`) on first use, falling back to the GitHub release when the mirror is unreachable. The locked runtime dependencies (Pillow, NumPy, vtracer) are installed from the Tencent Cloud PyPI mirror (`mirrors.cloud.tencent.com/pypi/simple`) first and fall back to the official PyPI index. A normal installation does not require an `agent-vision-toolkit` source checkout or a local path setting.
 
 ### 3. Paste an image and describe the outcome you want
 
@@ -283,7 +285,7 @@ Existing clients that still send `api_key="free"` remain compatible.
 
 For higher quotas, private endpoints, or another model, change the provider in **Settings → Vision Toolkit** and store the API key as a DSH Credential. Settings stores the Credential reference and never reads the saved secret back into the browser.
 
-**Step-by-step Groq tutorial:** [Get a free Groq API key and use Qwen3.6-27B for image understanding](docs/groq-qwen3.6-vision.md). It includes screenshots for account/API-key setup, the exact Vision Toolkit settings, and working cURL and Python examples.
+**Step-by-step AIHubMix tutorial:** [Get an AIHubMix API key and use free Gemini 3.7 Flash for vision](docs/aihubmix-gemini-vision.md). It includes screenshots for account/API-key setup, the exact Vision Toolkit settings, free-model selection, and troubleshooting.
 
 You can also configure a Profile patch:
 
@@ -303,7 +305,7 @@ For a trusted internal endpoint that uses a self-signed certificate or MITM prox
 
 ### Configure the Python runtime
 
-Most users never need to configure the Python runtime: the plugin prefers a system Python 3.11+ and otherwise downloads a pinned standalone Python automatically.
+Most users never need to configure the Python runtime: the plugin prefers a system Python 3.11+ and otherwise downloads a pinned standalone Python automatically from the domestic mirror, falling back to GitHub when the mirror is unreachable.
 
 For advanced setups — overriding `runtime.python`, using `runtime.mode: external`, verifying the runtime, or allowing additional input directories — see [Python runtime configuration](docs/python-runtime.md).
 
@@ -316,7 +318,7 @@ For advanced setups — overriding `runtime.python`, using `runtime.mode: extern
 | The free service returns 429 | Wait for the `Retry-After` interval, or switch to your own endpoint when you need stable higher volume |
 | The image exceeds a size or pixel limit | Crop or resize it first; the error identifies whether bytes or decoded pixels caused the rejection |
 | A custom Credential is missing | Enter the API key in **Settings → Vision Toolkit** and confirm the Credential name matches the provider configuration |
-| First-time runtime setup fails | The standalone-Python download needs network and disk access. Check connectivity or package-cache access, or install Python 3.11+ / configure `runtime.python` in Settings, then retry the model test |
+| First-time runtime setup fails | The standalone-Python download needs network and disk access (domestic mirror first, GitHub fallback). Check connectivity or package-cache access, or install Python 3.11+ / configure `runtime.python` in Settings, then retry the model test |
 | Chrome is not found | Install Chrome, Chromium, or Edge. Only HTML screenshot rendering is unavailable; the other tools still work |
 | DSH Desktop says `dsh` is not recognized, or its built-in marketplace install fails | Open **DSH Terminal** from the tray, run `dsh plugin --profile desktop add @anionex/dsh-vision-toolkit`, then restart DSH Desktop. The Desktop 2.0.1 marketplace has known install issues, so the terminal command is the reliable path for now |
 | An artifact cannot be previewed | Use **Open file** or the workspace path in the result. Preview URLs exist only while the Web route is available |

package/README.zh.md

@@ -29,6 +29,8 @@
 
 > **原创声明：** 这套视觉工具的体系和划分方式，以及 `vision-skills` Skill，均由作者个人原创并持续打磨，相关工具、方法和工作流来自长期的真实使用与反复迭代。
 
+> 如果这个项目对你有帮助，或给了你一些灵感，欢迎 Star 🌟 & Fork。
+
 ## 亮点
 
 - **粘贴图片，直接提问。** 在 DSH Web 里粘贴图片，文本模型会自动切换到看图模式变体，不需要手动复制路径或更换模型。图片保留原生缩略图、会话记录和工作区路径；Web 可以预览产物。
@@ -61,8 +63,8 @@ dsh plugin --profile web add @anionex/dsh-vision-toolkit
 
 <table>
 <tr>
-<td width="220"><a href="https://aihubmix.com/?aff=5wj6sgx8"><img src="assets/logo_aihubmix.png" alt="AIHubMix" height="48"></a></td>
-<td>感谢 <a href="https://aihubmix.com/?aff=5wj6sgx8">AIHubMix</a> 赞助本项目！AIHubMix 是稳定、高并发的 AI 大模型 API 聚合平台，一个 API Key 即可接入 Claude、GPT、Gemini、DeepSeek 等主流模型，兼容多种协议，并提供<b>免费模型选择</b>。国内用户请通过<a href="https://inferera.com/?aff=5wj6sgx8">国内入口</a>使用，海外用户请通过<a href="https://aihubmix.com/?aff=5wj6sgx8">海外入口</a>使用。</td>
+<td width="220"><a href="https://inferera.com/?aff=5wj6sgx8"><img src="assets/logo_aihubmix.png" alt="AIHubMix" height="48"></a></td>
+<td>感谢 <a href="https://inferera.com/?aff=5wj6sgx8">AIHubMix</a> 赞助本项目！AIHubMix 是稳定、高并发的 AI 大模型 API 聚合平台，一个 API Key 即可接入 Claude、GPT、Gemini、DeepSeek 等主流模型，兼容多种协议，并提供<b>免费模型选择</b>。注册时请使用 <a href="https://inferera.com/?aff=5wj6sgx8">Inferera 入口</a>。</td>
 </tr>
 </table>
 
@@ -83,10 +85,10 @@ dsh plugin --profile web add @anionex/dsh-vision-toolkit
 
 ## 最近更新
 
+- **2026-08-20 · AIHubMix 申请教程：** 新增通过 Inferera 入口申请 API Key、使用免费 Gemini 3.7 Flash 视觉模型的图文教程，并在视觉工具设置中直接提供入口。
 - **2026-08-19 · 透明变体路由默认开启：** 模型选择器默认只显示每个模型一项并保留原模型名，粘贴图片、历史图片和内置 `read_image` 工具都能直接使用，不再需要手动切换到 `(Vision Toolkit)` 变体；如需恢复显式条目，可在 设置 → 高级设置 → 图片输入 关闭“透明变体路由”。
 - **2026-08-16 · Windows Python：** 支持 Microsoft Store Python，解决 Windows 用户首次创建隔离环境失败的问题。
 - **2026-08-17 · 免费视觉升级：** 默认模型切换到 Gemini 3.7 Flash，并修复 Qwen/Gemini 检测框坐标顺序错位的问题。
-- **2026-08-16 · 免费视觉升级：** 默认模型切换到 Groq Qwen3.6，解决免 Key 方案看图效果不足的问题。
 - **2026-08-16 · 图片粘贴：** 文本模型自动切换到 `(Vision Toolkit)` 变体并保留工作区路径，解决粘贴图片被拦截或后续无法复用的问题。
 - **2026-08-16 · 共享容量：** 扩大免费服务容量，减少高峰期出现 `429` 的情况。
 - **2026-08-16 · 真实模型测试：** Settings 新增完整图片请求测试，解决 `/models` 可访问却不能证明模型真的会看图的问题。
@@ -178,7 +180,7 @@ dsh plugin --profile desktop add @anionex/dsh-vision-toolkit
 
 重启正在运行的 Web Profile，打开 **设置 → 视觉工具**。默认免费服务已经配置好；你可以直接运行**测试视觉模型**确认连接。
 
-首次启动会自动准备隔离运行环境：插件优先使用系统已有的 Python 3.11+；如果系统没有，会自动从固定发布源下载一个带完整性校验的托管 Python（约 35MB，仅首次需要网络）。普通安装不需要下载 `agent-vision-toolkit` 源码，也不需要设置本地路径。
+首次启动会自动准备隔离运行环境：插件优先使用系统已有的 Python 3.11+；如果系统没有，会自动从国内镜像（`dsh-vision-python-bootstrap-1317715800.cos.ap-guangzhou.myqcloud.com`）下载一个带完整性校验的托管 Python（约 35MB，仅首次需要网络），镜像不可用时自动回退到 GitHub 官方发布源。锁定依赖（Pillow、NumPy、vtracer）会优先从腾讯云 PyPI 镜像（`mirrors.cloud.tencent.com/pypi/simple`）安装，镜像不可用时回退到官方 PyPI。普通安装不需要下载 `agent-vision-toolkit` 源码，也不需要设置本地路径。
 
 ### 3. 粘贴图片，直接说你要做什么
 
@@ -281,7 +283,7 @@ API Key:  https://agent-vision.anionex.me（自动填写）
 
 如果你需要更高额度、私有端点或其他模型，可以在 **设置 → 视觉工具** 中修改提供方，并把 API Key 保存为 DSH Credential。Settings 只保存 Credential 引用，不会回显密钥。
 
-**Groq 图文教程：** [免费获取 Groq API Key，并调用 Qwen3.6-27B 识图](docs/groq-qwen3.6-vision.zh.md)。教程包含账号与 API Key 获取截图、Vision Toolkit 的准确配置，以及可直接使用的 cURL 和 Python 示例。
+**AIHubMix 图文教程：** [申请 AIHubMix API Key，并用免费 Gemini 3.7 Flash 识图](docs/aihubmix-gemini-vision.zh.md)。教程包含账号与 API Key 获取截图、Vision Toolkit 的准确配置、免费模型选择和常见问题排查。
 
 也可以在 Profile patch 中配置：
 
@@ -301,7 +303,7 @@ API Key:  https://agent-vision.anionex.me（自动填写）
 
 ### 配置 Python 运行时
 
-大多数用户无需配置 Python 运行时：插件会优先使用系统 Python 3.11+，找不到时自动下载固定版本的托管 Python。
+大多数用户无需配置 Python 运行时：插件会优先使用系统 Python 3.11+，找不到时自动从国内镜像下载固定版本的托管 Python；国内镜像不可用时回退到 GitHub 官方发布源。
 
 需要覆盖 `runtime.python`、使用 `runtime.mode: external`、验证运行时，或允许读取其他目录时，请参阅 [Python 运行时配置](docs/python-runtime.zh.md)。
 
@@ -314,7 +316,7 @@ API Key:  https://agent-vision.anionex.me（自动填写）
 | 免费服务提示 429 | 按错误中的 `Retry-After` 等待后重试；如果需要稳定高额度，切换到自己的视觉端点 |
 | 图片过大或像素超限 | 先裁剪或缩放图片；错误会明确显示是字节还是像素限制 |
 | 自定义 Credential 缺失 | 在 **设置 → 视觉工具** 填写 API Key，并确认 Credential 名称与配置一致 |
-| 首次运行时准备失败 | 自动下载托管 Python 需要网络和磁盘权限；失败时检查网络或包缓存，也可以安装 Python 3.11+ 或在 Settings 中配置 `runtime.python`，然后重新测试 |
+| 首次运行时准备失败 | 自动下载托管 Python 需要网络和磁盘权限（默认先走国内镜像，失败时回退 GitHub）；失败时检查网络或包缓存，也可以安装 Python 3.11+ 或在 Settings 中配置 `runtime.python`，然后重新测试 |
 | 找不到 Chrome | 安装 Chrome、Chromium 或 Edge；只有 HTML 截图不可用，其他工具不受影响 |
 | DSH Desktop 提示找不到 `dsh` 命令，或内置插件市场安装失败 | 从托盘打开 **DSH 终端**，运行 `dsh plugin --profile desktop add @anionex/dsh-vision-toolkit`，再重启 DSH Desktop。桌面版 2.0.1 的内置市场存在已知安装问题，当前请优先使用终端安装 |
 | 产物无法预览 | 使用“打开文件”或结果中的工作区路径；预览 URL 只在 Web 路由可用时存在 |

package/assets/python-bootstrap.json

@@ -2,6 +2,7 @@
   "schemaVersion": 1,
   "pythonVersion": "3.13.15",
   "buildTag": "20260814",
+  "mirrorBaseUrl": "https://dsh-vision-python-bootstrap-1317715800.cos.ap-guangzhou.myqcloud.com",
   "artifacts": {
     "darwin-arm64": {
       "url": "https://github.com/astral-sh/python-build-standalone/releases/download/20260814/cpython-3.13.15+20260814-aarch64-apple-darwin-install_only_stripped.tar.gz",

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)

package/docs/python-runtime.md

@@ -1,10 +1,10 @@
 # Configure the Python runtime
 
-By default the plugin picks a system Python 3.11+, or downloads a standalone Python when none is found; most users never need to configure this section. The rest is for advanced setups where automatic discovery fails, a specific interpreter is required, or an external runtime is used.
+By default the plugin picks a system Python 3.11+, or downloads a standalone Python from the domestic mirror (`dsh-vision-python-bootstrap-1317715800.cos.ap-guangzhou.myqcloud.com`) when none is found, falling back to the GitHub release when the mirror is unreachable; most users never need to configure this section. The rest is for advanced setups where automatic discovery fails, a specific interpreter is required, or an external runtime is used.
 
 The packaged `managed` runtime creates its own isolated virtual environment. `runtime.python` selects the Python executable used to bootstrap or refresh that environment; it does not replace the managed environment with the interpreter's global site-packages. Set it when automatic discovery fails or when several Python installations exist. The override is also used by `runtime.mode: external`.
 
-Python 3.11 or newer is required; the automatically downloaded standalone Python is 3.13.15 and, like a system interpreter, is only used to bootstrap the isolated environment. Without an override, the plugin tries `python3` then `python` on macOS/Linux, and `python`, `py -3`, then `python3` on Windows, before falling back to the standalone download. A configured value is passed as one executable name or path, not as a shell command with arguments, so use `py` (not `py -3`) for the Windows launcher; use an absolute path when you need a specific version.
+Python 3.11 or newer is required; the automatically downloaded standalone Python is 3.13.15 and, like a system interpreter, is only used to bootstrap the isolated environment. Without an override, the plugin tries `python3` then `python` on macOS/Linux, and `python`, `py -3`, then `python3` on Windows, before falling back to the domestic-mirror standalone download (GitHub release as a secondary fallback). A configured value is passed as one executable name or path, not as a shell command with arguments, so use `py` (not `py -3`) for the Windows launcher; use an absolute path when you need a specific version.
 
 Configure it in the Profile patch:
 
@@ -22,7 +22,7 @@ Configure it in the Profile patch:
       # python: py
 ```
 
-For a managed runtime, create the project-local interpreter and point `runtime.python` at it. The plugin installs the locked dependencies into its own managed cache, so installing the lockfile into this bootstrap environment is optional:
+For a managed runtime, create the project-local interpreter and point `runtime.python` at it. The plugin installs the locked dependencies into its own managed cache (Tencent Cloud PyPI mirror first, official PyPI as fallback), so installing the lockfile into this bootstrap environment is optional:
 
 ```sh
 python3 --version                         # must report 3.11 or newer
@@ -56,6 +56,20 @@ uv pip install --python .venv\Scripts\python.exe -r C:\absolute\path\to\dsh-visi
 
 Point `runtime.python` at the same interpreter, save the Profile patch, and restart the Web Profile. Then open **Settings → Vision Toolkit**: the Runtime panel should show the resolved interpreter and Python version, and **Run health check** plus **Test vision model** should complete without the Python-version error. A final smoke test is to place a PNG/JPEG in the session workspace and call `vision_glance`.
 
+## Updating the standalone Python mirror
+
+The standalone Python is pinned in `assets/python-bootstrap.json` and mirrored at `https://dsh-vision-python-bootstrap-1317715800.cos.ap-guangzhou.myqcloud.com` (Tencent Cloud COS, `ap-guangzhou`). When upgrading the Python build, sync the mirror with:
+
+```sh
+node scripts/python-bootstrap.mjs --write   # fetch the latest GitHub release manifest
+node scripts/python-bootstrap-mirror.mjs    # download and sha256-verify every platform archive
+# run the coscmd publish command printed by the script to push .python-bootstrap-dist/<buildTag>/
+```
+
+After pushing, verify each mirror URL returns `206`/`200` and that `Content-Length` matches the `size` field in the manifest.
+
+The mirror bucket is public-read; archives live at `https://dsh-vision-python-bootstrap-1317715800.cos.ap-guangzhou.myqcloud.com/<buildTag>/`.
+
 ## Allowed input directories
 
 The path fence automatically allows the session workspace and the platform temporary directory. On macOS/Linux the temporary root is `/tmp`. On Windows it is `TEMP`, then `TMP`, with the operating-system fallback if neither is set; model-generated `/tmp/...` paths are translated to that Windows directory before the normal realpath fence runs. No `allowedDirs` entry is needed for these platform temporary paths.

package/docs/python-runtime.zh.md

@@ -1,10 +1,10 @@
 # 配置 Python 运行时
 
-默认情况下插件会自动选择系统 Python 3.11+，找不到时下载托管 Python，普通用户无需配置本节。以下内容供自动发现失败、需要固定版本或使用外部运行时的高级场景参考。
+默认情况下插件会自动选择系统 Python 3.11+，找不到时从国内镜像（`dsh-vision-python-bootstrap-1317715800.cos.ap-guangzhou.myqcloud.com`）下载托管 Python，镜像不可用时自动回退到 GitHub 官方发布源，普通用户无需配置本节。以下内容供自动发现失败、需要固定版本或使用外部运行时的高级场景参考。
 
 打包的 `managed` 运行时会创建自己的隔离虚拟环境。`runtime.python` 指定的是引导或刷新该环境时使用的 Python 解释器，并不会把 managed 运行时替换成系统解释器的全局 site-packages。当自动发现失败或机器上有多个 Python 时，应设置这个选项；`runtime.mode: external` 也使用该覆盖值。
 
-要求 Python 3.11 或更高版本；自动下载的托管 Python 为 3.13.15，与系统 Python 一样只用于引导隔离环境。不设置覆盖值时，插件在 macOS/Linux 上依次尝试 `python3`、`python`，在 Windows 上依次尝试 `python`、`py -3`、`python3`，全部不可用时会自动下载托管 Python。手动配置的值会作为一个可执行文件名或路径传入，而不是作为带参数的 Shell 命令，因此 Windows 启动器应填写 `py`（不要填写 `py -3`）；需要固定版本时，请填写绝对路径。
+要求 Python 3.11 或更高版本；自动下载的托管 Python 为 3.13.15，与系统 Python 一样只用于引导隔离环境。不设置覆盖值时，插件在 macOS/Linux 上依次尝试 `python3`、`python`，在 Windows 上依次尝试 `python`、`py -3`、`python3`，全部不可用时会自动从国内镜像下载托管 Python，镜像不可用时回退到 GitHub 官方发布源。手动配置的值会作为一个可执行文件名或路径传入，而不是作为带参数的 Shell 命令，因此 Windows 启动器应填写 `py`（不要填写 `py -3`）；需要固定版本时，请填写绝对路径。
 
 在 Profile patch 中配置：
 
@@ -22,7 +22,7 @@
       # python: py
 ```
 
-对于 managed 运行时，创建项目内解释器并将 `runtime.python` 指向它即可。插件会把锁定依赖安装到自己的 managed 缓存中，因此将 lockfile 安装到这个引导环境是可选的：
+对于 managed 运行时，创建项目内解释器并将 `runtime.python` 指向它即可。插件会把锁定依赖安装到自己的 managed 缓存中（优先使用腾讯云 PyPI 镜像，镜像不可用时回退官方 PyPI），因此将 lockfile 安装到这个引导环境是可选的：
 
 ```sh
 python3 --version                         # 必须是 3.11 或更高
@@ -56,6 +56,20 @@ uv pip install --python .venv\Scripts\python.exe -r C:\absolute\path\to\dsh-visi
 
 把 `runtime.python` 指向同一个解释器，保存 Profile patch 后重启 Web Profile。然后打开 **设置 → 视觉工具**：运行时面板应显示实际使用的解释器和 Python 版本；点击 **运行健康检查** 和 **测试视觉模型**，确认不再出现 Python 版本错误。最后可将一张 PNG/JPEG 放入会话工作区并调用 `vision_glance` 做冒烟测试。
 
+## 更新托管 Python 镜像
+
+托管 Python 由 `assets/python-bootstrap.json` 固定版本和国内镜像（`https://dsh-vision-python-bootstrap-1317715800.cos.ap-guangzhou.myqcloud.com`，腾讯云 COS `ap-guangzhou`）共同维护。升级 Python 构建后按以下步骤同步镜像：
+
+```sh
+node scripts/python-bootstrap.mjs --write   # 从 GitHub 拉取最新清单并写回 manifest
+node scripts/python-bootstrap-mirror.mjs    # 下载全部平台压缩包并校验 sha256
+# 执行脚本最后打印的 coscmd 发布命令，把 .python-bootstrap-dist/<buildTag>/ 推到 COS 桶
+```
+
+推送后逐个验证镜像 URL 返回 `206`/`200` 且 `Content-Length` 与 manifest 中的 `size` 一致。
+
+镜像桶为公有读；归档地址为 `https://dsh-vision-python-bootstrap-1317715800.cos.ap-guangzhou.myqcloud.com/<buildTag>/`。
+
 ## 允许读取的输入目录
 
 路径围栏会自动允许会话工作区和平台临时目录。macOS/Linux 的临时目录根路径是 `/tmp`。Windows 依次读取 `TEMP`、`TMP`，两者都未设置时使用操作系统回退值；模型生成的 `/tmp/...` 路径会先映射到该 Windows 临时目录，再执行常规 realpath 路径围栏检查。这些平台临时路径无需加入 `allowedDirs`。