@mengruo/dsh-vision-toolkit 0.0.1

package/docs/dsh-desktop-install.md

@@ -0,0 +1,67 @@
+# Installing and Updating dsh-vision-toolkit in DSH Desktop
+
+This guide explains how to install, verify, and update `dsh-vision-toolkit` in **DSH Desktop**.
+
+> Why a separate guide? DSH Desktop bundles its own `dsh` CLI but intentionally does **not** add it to the system PATH. Running `dsh` in a system shell (PowerShell, cmd, or the macOS Terminal) reports "command not found" by design — this is not a plugin issue. Always use the **DSH Terminal** opened from the desktop tray.
+
+## 1. Open the DSH Terminal
+
+1. Find the **DSH Desktop** icon in the system tray (bottom-right on Windows, top-right menu bar on macOS).
+2. **Right-click** the icon and choose **Open DSH Terminal**.
+3. Verify the environment in the opened terminal:
+
+```sh
+dsh --version
+```
+
+If the version prints, the terminal environment is ready. If the command is not found, make sure the app is v2.0+ and try fully quitting and relaunching DSH Desktop first.
+
+## 2. Install the plugin
+
+Run the following command in the **DSH Terminal**:
+
+```sh
+dsh plugin --profile desktop add @mengruo/dsh-vision-toolkit@0.1.34
+```
+
+Notes:
+
+- `--profile desktop` targets the default `desktop` profile; replace `desktop` with `web` to install into a `web` profile.
+- **Pin an exact version** (currently `0.1.34`). The DSH 1024Store marketplace catalog lags behind npm, so a one-click marketplace install can land on an older version; an explicit version guarantees the latest release.
+- If the active profile is already the target profile, you can omit `--profile desktop` and run `dsh plugin add @mengruo/dsh-vision-toolkit@0.1.34` directly.
+
+## 3. Restart and verify
+
+1. **Fully quit DSH Desktop**: right-click the tray icon → **Quit** (closing the window only hides it).
+2. Reopen DSH Desktop.
+3. Open **Settings → Vision Toolkit** and click **Test vision model** to confirm the built-in free vision service works.
+4. Paste an image into the conversation and ask directly, or invoke `/vision-skills` for the full vision workflow.
+
+## 4. Update to a new version
+
+1. Check the latest version on the [npm page](https://www.npmjs.com/package/@mengruo/dsh-vision-toolkit).
+2. In the **DSH Terminal**, rerun the install command with the new version:
+
+```sh
+dsh plugin --profile desktop add @mengruo/dsh-vision-toolkit@<new-version>
+```
+
+3. **Fully quit and reopen DSH Desktop** so the new version takes effect.
+
+If you installed without pinning an exact version, the official `dsh plugin update` command also works; with a pinned version such as `@0.1.34`, use the explicit-version command above.
+
+## Troubleshooting
+
+| Problem | What to do |
+| --- | --- |
+| `dsh` is not recognized in a system shell | Expected. Open **DSH Terminal** from the tray instead of using system PowerShell/cmd/Terminal |
+| No Open DSH Terminal in the tray menu | Make sure the app is v2.0+; this entry exists only in v2 and later |
+| The built-in marketplace fails with "cannot confirm the operation result" | DSH Desktop 2.0.1 has known marketplace install issues; use the DSH Terminal command in this guide instead |
+| Plugin does not show up after install | Confirm the command targeted the right profile and **fully quit and restart** DSH Desktop |
+| Want to install into the web profile | Replace `desktop` with `web` in the command, then restart DSH Desktop and switch to the web profile |
+
+## Links
+
+- [Project website](https://agent-vision.anionex.me)
+- [npm package](https://www.npmjs.com/package/@mengruo/dsh-vision-toolkit)
+- [DSH Desktop user guide](https://github.com/anywhere-labs/deepseek-harness-desktop/blob/master/docs/user-guide.en.md)

package/docs/dsh-desktop-install.zh.md

@@ -0,0 +1,67 @@
+# DSH Desktop 安装与更新指南
+
+本指南说明如何在 **DSH Desktop（桌面版）** 中安装、验证和更新 `dsh-vision-toolkit`。
+
+> 为什么需要单独一份指南？DSH Desktop 自带 `dsh` 命令行，但**不会写入系统 PATH**。在系统终端（PowerShell、cmd、macOS 终端）里运行 `dsh` 会提示找不到命令，这是桌面版的设计行为，不是插件问题。请始终使用桌面版托盘提供的 **DSH 终端**。
+
+## 1. 打开 DSH 终端
+
+1. 找到系统托盘中的 **DSH Desktop** 图标（Windows 在右下角，macOS 在右上角菜单栏）。
+2. **右键**图标，选择 **Open DSH Terminal**（或 **打开 DSH 终端**）。
+3. 打开的终端里先确认环境可用：
+
+```sh
+dsh --version
+```
+
+能看到版本号就说明终端环境正常。如果提示找不到命令，请确认应用版本是 v2.0+，并完全退出桌面版后重新打开再试。
+
+## 2. 安装插件
+
+在 **DSH 终端** 中运行以下命令：
+
+```sh
+dsh plugin --profile desktop add @mengruo/dsh-vision-toolkit@0.1.34
+```
+
+几点说明：
+
+- `--profile desktop` 表示安装到桌面版默认的 `desktop` Profile；想装到 `web` Profile 时把 `desktop` 换成 `web`。
+- **建议带精确版本号**（当前为 `0.1.34`）。DSH 1024Store 插件市场的目录数据有滞后，市场里一键安装可能装到旧版本；显式写版本号能确保装到最新版。
+- 如果当前激活的 Profile 就是要装的 Profile，也可以省略 `--profile desktop`，直接运行 `dsh plugin add @mengruo/dsh-vision-toolkit@0.1.34`。
+
+## 3. 重启并验证
+
+1. **完全退出 DSH Desktop**：托盘右键 → **退出**（关闭窗口只是隐藏，不算退出）。
+2. 重新打开 DSH Desktop。
+3. 进入 **设置 → 视觉工具**，点击 **测试视觉模型**，确认默认免费视觉服务可用。
+4. 在会话中**粘贴一张图片直接提问**，或调用 `/vision-skills` 使用完整视觉工作流。
+
+## 4. 更新到新版本
+
+1. 在 [npm 页面](https://www.npmjs.com/package/@mengruo/dsh-vision-toolkit) 查看最新版本号。
+2. 在 **DSH 终端** 中，把安装命令里的版本号换成新版本后重新执行：
+
+```sh
+dsh plugin --profile desktop add @mengruo/dsh-vision-toolkit@<新版本号>
+```
+
+3. 再次**完全退出并重启 DSH Desktop**，新版本才会生效。
+
+如果当初安装时没有锁定精确版本，也可以使用官方更新命令 `dsh plugin update`，但精确版本安装（`@0.1.34` 这种写法）下请使用上面的显式版本号方式升级。
+
+## 常见问题
+
+| 问题 | 处理方式 |
+| --- | --- |
+| 系统终端里找不到 `dsh` 命令 | 正常。请从托盘打开 **DSH 终端**，不要用系统 PowerShell/cmd/终端 |
+| 托盘菜单里没有 Open DSH Terminal | 确认应用是 v2.0+ 版本；v2 才开始提供该入口 |
+| 内置插件市场安装失败，提示“无法确认操作结果” | DSH Desktop 2.0.1 的市场安装链路有已知问题，请改用本文的 DSH 终端命令安装 |
+| 装完插件没生效 | 确认命令装到了正确的 Profile，并**完全退出后重启**桌面版 |
+| 想装到 web Profile | 把命令中的 `desktop` 换成 `web`，重启桌面版后到 web Profile 使用 |
+
+## 相关链接
+
+- [项目主页](https://agent-vision.anionex.me)
+- [npm 包](https://www.npmjs.com/package/@mengruo/dsh-vision-toolkit)
+- [DSH Desktop 用户指南](https://github.com/anywhere-labs/deepseek-harness-desktop/blob/master/docs/user-guide.md)

package/docs/groq-qwen3.6-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/groq-qwen3.6-vision.md
+groq-qwen3.6-vision.md: 04907539da37edae3d9866007221403e8239516c
+groq-qwen3.6-vision.zh.md: 6fe5a22695efc3d90b937510b293c2e717cc6fd7

package/docs/groq-qwen3.6-vision.md

@@ -0,0 +1,236 @@
+# Get a free Groq API key and use Qwen3.6-27B for vision
+
+**English** | [中文](groq-qwen3.6-vision.zh.md)
+
+This guide covers two tasks:
+
+1. Sign up for the GroqCloud Free Plan and create a Groq API key.
+2. Use `qwen/qwen3.6-27b` to analyze images through DSH Vision Toolkit or ordinary code.
+
+> As of August 17, 2026, Groq lists Qwen3.6-27B as a Preview model with text and image input. Free Plan traffic is rate-limited and the limits can change; use the current [Groq Rate Limits](https://console.groq.com/docs/rate-limits) and [Qwen3.6-27B model page](https://console.groq.com/docs/model/qwen/qwen3.6-27b) as the source of truth.
+
+## 1. Create a free GroqCloud account
+
+Open the [GroqCloud Console](https://console.groq.com/). You can sign up or log in with Google, GitHub, SSO, or email.
+
+<p align="center">
+  <img src="assets/groq-console-home.png" width="92%" alt="GroqCloud Console sign-up and login page" />
+</p>
+
+The Free Plan is enough to complete this tutorial without purchasing paid capacity. It is not unlimited; the API returns `429 Too Many Requests` when the current quota is exhausted.
+
+As of August 17, 2026, the official Free Plan table lists Qwen3.6-27B at `30 RPM` (requests per minute), `1K RPD` (requests per day), `8K TPM` (tokens per minute), and `200K TPD` (tokens per day). Your organization's effective limits are shown on the Limits page in Groq Console.
+
+## 2. Create and save an API key
+
+After logging in, open **API Keys** in the top navigation or go directly to [Groq API Keys](https://console.groq.com/keys). When logged out, the page first shows this login prompt:
+
+<p align="center">
+  <img src="assets/groq-console-keys-login.png" width="92%" alt="Groq API Keys page asking the user to log in" />
+</p>
+
+On the API Keys page:
+
+1. Click **Create API Key**.
+2. Enter a recognizable name such as `dsh-vision-toolkit`.
+3. Confirm the creation.
+4. Copy the key beginning with `gsk_` immediately, then save it in a password manager or a DSH Credential.
+
+Groq's official Quickstart likewise starts with creating an API key and placing it in an environment variable:
+
+<p align="center">
+  <img src="assets/groq-docs-quickstart.png" width="88%" alt="Groq Quickstart instructions for creating and setting an API key" />
+</p>
+
+The complete API key is normally shown only once. Do not put it in a README, chat transcript, screenshot, Git commit, or frontend code.
+
+### Set the key in a terminal
+
+macOS / Linux:
+
+```sh
+export GROQ_API_KEY="gsk_your_key_here"
+```
+
+Windows PowerShell, for the current window:
+
+```powershell
+$env:GROQ_API_KEY = "gsk_your_key_here"
+```
+
+Confirm that the variable exists without printing the secret:
+
+```sh
+test -n "$GROQ_API_KEY" && echo "GROQ_API_KEY is set"
+```
+
+## 3. Confirm the model ID and vision support
+
+Use this exact model ID in Groq API requests:
+
+```text
+qwen/qwen3.6-27b
+```
+
+Do not shorten it to `qwen3.6-27b`, `Qwen3.6-27B`, or `27b`. The model page shows both image input and the Vision capability:
+
+<p align="center">
+  <img src="assets/groq-docs-qwen3.6.png" width="92%" alt="Groq Qwen3.6-27B model page showing image input and Vision capability" />
+</p>
+
+The Groq model page lists these main image limits:
+
+| Item | Limit |
+|---|---:|
+| Individual image file | 20 MB |
+| Images in one request | Up to 3 |
+
+Groq's general vision guide currently says that up to five images can be processed, while the Qwen3.6-27B model page says three. This guide follows the stricter model-specific limit to avoid rejected requests.
+
+<p align="center">
+  <img src="assets/groq-docs-vision.png" width="88%" alt="Groq Images and Vision documentation showing model limits and an image request example" />
+</p>
+
+## 4. Use it in DSH Vision Toolkit
+
+If this plugin is already installed, this is the shortest path.
+
+1. Open **Settings → Vision Toolkit** in DSH Web.
+2. Enter these values under Vision service:
+
+| Field | Value |
+|---|---|
+| API protocol | `OpenAI Chat Completions` |
+| Base URL | `https://api.groq.com/openai/v1` |
+| Model | `qwen/qwen3.6-27b` |
+| API key | Paste the newly created `gsk_...` key |
+
+3. Click **Save and apply**. The key is stored in DSH Credentials and its full value is not displayed again in Settings.
+4. Click **Test vision model**. This sends the plugin's bundled diagnostic image and verifies a real multimodal request rather than only checking `/models` connectivity.
+5. After the test succeeds, paste an image into a new or existing session and ask a focused question, for example:
+
+```text
+Inspect this screenshot. Transcribe the complete error first, then explain the most likely cause.
+```
+
+The same provider can be configured in a Profile patch. Keep the key in a DSH Credential or environment variable rather than writing it into YAML:
+
+```yaml
+- id: vision-toolkit
+  config:
+    provider:
+      protocol: openai
+      baseUrl: https://api.groq.com/openai/v1
+      model: qwen/qwen3.6-27b
+      credential: GROQ_API_KEY
+```
+
+## 5. Analyze a remote image with cURL
+
+The following request uses Groq's OpenAI Chat Completions-compatible endpoint. Replace the example URL with your own publicly accessible image URL:
+
+```sh
+curl https://api.groq.com/openai/v1/chat/completions \
+  -H "Authorization: Bearer $GROQ_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "qwen/qwen3.6-27b",
+    "messages": [{
+      "role": "user",
+      "content": [
+        {"type": "text", "text": "Describe the main content of this image and transcribe all visible text."},
+        {"type": "image_url", "image_url": {
+          "url": "https://upload.wikimedia.org/wikipedia/commons/f/f2/LPU-v1-die.jpg"
+        }}
+      ]
+    }],
+    "temperature": 0.2,
+    "max_completion_tokens": 1024
+  }'
+```
+
+The model's answer is returned at `choices[0].message.content`.
+
+## 6. Analyze a local image with Python
+
+This example reads a local image and converts it to a Base64 Data URL. Use `uv` to install the Groq SDK temporarily without modifying system Python:
+
+```python
+# recognize.py
+import base64
+import mimetypes
+from pathlib import Path
+
+from groq import Groq
+
+image_path = Path("screenshot.png")
+mime_type = mimetypes.guess_type(image_path.name)[0] or "image/png"
+image_base64 = base64.b64encode(image_path.read_bytes()).decode("ascii")
+data_url = f"data:{mime_type};base64,{image_base64}"
+
+client = Groq()  # Reads GROQ_API_KEY automatically.
+response = client.chat.completions.create(
+    model="qwen/qwen3.6-27b",
+    messages=[{
+        "role": "user",
+        "content": [
+            {"type": "text", "text": "Analyze this screenshot: run OCR first, then identify the most important anomaly."},
+            {"type": "image_url", "image_url": {"url": data_url}},
+        ],
+    }],
+    temperature=0.2,
+    max_completion_tokens=1024,
+)
+
+print(response.choices[0].message.content)
+```
+
+Run it with:
+
+```sh
+uv run --with groq python recognize.py
+```
+
+Base64 makes the request larger than the original file. If the request approaches the 20 MB limit, resize or compress the image first, or use an HTTPS image URL that the model can access.
+
+## 7. Troubleshooting
+
+### `401 Invalid API Key`
+
+- Confirm that the entire `gsk_...` key was copied.
+- Do not include extra spaces, literal quote characters, or line breaks in the environment variable.
+- If the key was exposed publicly, delete it and create a replacement.
+
+### `404` or `model not found`
+
+- The model ID must be `qwen/qwen3.6-27b`.
+- The model is currently in Preview. If Groq changes its availability, check the official model page and the models currently shown in Groq Console.
+
+### `413` or an oversized image error
+
+- Base64 input has a lower size limit than URL input; resize or compress the image.
+- Do not place too many images in one request; the Qwen3.6-27B model page currently limits a request to three images.
+
+### `429 Too Many Requests`
+
+- The Free Plan has reached a per-minute, token, or daily limit.
+- Inspect the rate-limit response headers and retry after capacity resets.
+
+### The model describes the image but misses the task
+
+Make the request specific, for example:
+
+```text
+Do not give a generic description. Complete only these three tasks:
+1. Transcribe the text inside the red error box exactly;
+2. Report the error box's approximate location in the original image;
+3. Infer the most likely cause from the surrounding interface.
+```
+
+## Official references
+
+- [Groq Quickstart](https://console.groq.com/docs/quickstart)
+- [Groq API Keys](https://console.groq.com/keys)
+- [Qwen3.6-27B model page](https://console.groq.com/docs/model/qwen/qwen3.6-27b)
+- [Groq Images and Vision](https://console.groq.com/docs/vision)
+- [Groq Rate Limits](https://console.groq.com/docs/rate-limits)

package/docs/groq-qwen3.6-vision.zh.md

@@ -0,0 +1,236 @@
+# 免费获取 Groq API Key，并用 Qwen3.6-27B 识图
+
+[English](groq-qwen3.6-vision.md) | **中文**
+
+这篇教程完成两件事：
+
+1. 注册 GroqCloud 的 Free Plan，并创建一个 Groq API Key。
+2. 在 DSH Vision Toolkit 或普通代码中调用 `qwen/qwen3.6-27b` 分析图片。
+
+> 截至 2026-08-17，Groq 官方模型页将 Qwen3.6-27B 标记为 Preview，支持文本和图片输入。Free Plan 有速率和每日额度限制，具体数值可能调整，请以 [Groq Rate Limits](https://console.groq.com/docs/rate-limits) 和 [Qwen3.6-27B 模型页](https://console.groq.com/docs/model/qwen/qwen3.6-27b) 为准。
+
+## 1. 注册免费的 GroqCloud 账号
+
+打开 [GroqCloud Console](https://console.groq.com/)。可以使用 Google、GitHub、SSO 或邮箱注册/登录。
+
+<p align="center">
+  <img src="assets/groq-console-home.png" width="92%" alt="GroqCloud Console 登录和注册页面" />
+</p>
+
+完成注册后即可先使用 Free Plan，不需要为本教程购买付费额度。免费额度不是无限量服务；超出当前限制时，接口会返回 `429 Too Many Requests`。
+
+截至 2026-08-17，官方 Free Plan 表中 Qwen3.6-27B 的基础限制为 `30 RPM`（每分钟请求数）、`1K RPD`（每日请求数）、`8K TPM`（每分钟 Token 数）和 `200K TPD`（每日 Token 数）。账号的实际限制以 Groq Console 的 Limits 页面为准。
+
+## 2. 创建并保存 API Key
+
+登录后打开顶部的 **API Keys**，或直接访问 [Groq API Keys](https://console.groq.com/keys)。未登录时会先看到下面的登录页面：
+
+<p align="center">
+  <img src="assets/groq-console-keys-login.png" width="92%" alt="Groq API Keys 页面要求登录" />
+</p>
+
+在 API Keys 页面中：
+
+1. 点击 **Create API Key**。
+2. 给密钥填写一个容易辨认的名称，例如 `dsh-vision-toolkit`。
+3. 确认创建。
+4. 立即复制以 `gsk_` 开头的密钥，并保存到密码管理器或 DSH Credential 中。
+
+Groq 官方 Quickstart 也把“创建 API Key”和“通过环境变量保存密钥”放在最前面：
+
+<p align="center">
+  <img src="assets/groq-docs-quickstart.png" width="88%" alt="Groq Quickstart 中创建和设置 API Key 的说明" />
+</p>
+
+API Key 通常只在创建后完整显示一次。不要把它粘贴到 README、聊天记录、截图、Git 提交或前端代码中。
+
+### 在终端中设置密钥
+
+macOS / Linux：
+
+```sh
+export GROQ_API_KEY="gsk_your_key_here"
+```
+
+Windows PowerShell（只对当前窗口生效）：
+
+```powershell
+$env:GROQ_API_KEY = "gsk_your_key_here"
+```
+
+确认变量已经存在，但不要打印完整密钥：
+
+```sh
+test -n "$GROQ_API_KEY" && echo "GROQ_API_KEY is set"
+```
+
+## 3. 确认模型名和视觉能力
+
+Groq API 中必须使用完整模型 ID：
+
+```text
+qwen/qwen3.6-27b
+```
+
+不要写成 `qwen3.6-27b`、`Qwen3.6-27B` 或只写 `27b`。模型页会同时显示图片输入和 Vision 能力：
+
+<p align="center">
+  <img src="assets/groq-docs-qwen3.6.png" width="92%" alt="Groq Qwen3.6-27B 模型页显示文本和图片输入及 Vision 能力" />
+</p>
+
+Groq 模型页列出的主要图片限制是：
+
+| 项目 | 限制 |
+|---|---:|
+| 单个图片文件 | 最大 20 MB |
+| 单次请求图片数 | 最多 3 张 |
+
+Groq 的通用视觉文档当前写的是最多 5 张图片，但 Qwen3.6-27B 的模型专页写的是最多 3 张。这里按模型专页的更严格限制执行，避免请求被拒绝。
+
+<p align="center">
+  <img src="assets/groq-docs-vision.png" width="88%" alt="Groq Images and Vision 文档中的模型、限制和图片调用示例" />
+</p>
+
+## 4. 在 DSH Vision Toolkit 中使用
+
+如果已经安装本插件，这是最短路径。
+
+1. 打开 DSH Web 的 **设置 → 视觉工具**。
+2. 在“视觉服务”中填写：
+
+| 字段 | 值 |
+|---|---|
+| API 协议 | `OpenAI Chat Completions` |
+| 服务地址 | `https://api.groq.com/openai/v1` |
+| 模型名称 | `qwen/qwen3.6-27b` |
+| API 密钥 | 粘贴刚创建的 `gsk_...` 密钥 |
+
+3. 点击 **保存并应用**。密钥会保存到 DSH Credentials，设置页面以后不会回显完整内容。
+4. 点击 **测试视觉模型**。这个按钮会发送插件自带的诊断图片，验证的是真实多模态请求，而不只是 `/models` 连通性。
+5. 测试成功后，新建或继续一个会话，粘贴图片并直接提问，例如：
+
+```text
+看一下这张截图，先完整抄出报错信息，再解释最可能的原因。
+```
+
+也可以在 Profile patch 中配置相同的提供方。密钥本身仍应由 DSH Credential 或环境变量提供，不要写进 YAML：
+
+```yaml
+- id: vision-toolkit
+  config:
+    provider:
+      protocol: openai
+      baseUrl: https://api.groq.com/openai/v1
+      model: qwen/qwen3.6-27b
+      credential: GROQ_API_KEY
+```
+
+## 5. 用 cURL 直接识别网络图片
+
+下面的请求使用 Groq 的 OpenAI Chat Completions 兼容接口。把示例图片 URL 换成你自己的公开图片地址：
+
+```sh
+curl https://api.groq.com/openai/v1/chat/completions \
+  -H "Authorization: Bearer $GROQ_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "qwen/qwen3.6-27b",
+    "messages": [{
+      "role": "user",
+      "content": [
+        {"type": "text", "text": "请描述图片中的主要内容，并逐字抄出可见文字。"},
+        {"type": "image_url", "image_url": {
+          "url": "https://upload.wikimedia.org/wikipedia/commons/f/f2/LPU-v1-die.jpg"
+        }}
+      ]
+    }],
+    "temperature": 0.2,
+    "max_completion_tokens": 1024
+  }'
+```
+
+成功后，模型回答位于 `choices[0].message.content`。
+
+## 6. 用 Python 识别本地图片
+
+下面的例子读取本地图片并转换成 Base64 Data URL。推荐使用 `uv` 临时安装 Groq SDK，不污染系统 Python：
+
+```python
+# recognize.py
+import base64
+import mimetypes
+from pathlib import Path
+
+from groq import Groq
+
+image_path = Path("screenshot.png")
+mime_type = mimetypes.guess_type(image_path.name)[0] or "image/png"
+image_base64 = base64.b64encode(image_path.read_bytes()).decode("ascii")
+data_url = f"data:{mime_type};base64,{image_base64}"
+
+client = Groq()  # 自动读取 GROQ_API_KEY
+response = client.chat.completions.create(
+    model="qwen/qwen3.6-27b",
+    messages=[{
+        "role": "user",
+        "content": [
+            {"type": "text", "text": "分析这张截图：先做 OCR，再指出最重要的异常。"},
+            {"type": "image_url", "image_url": {"url": data_url}},
+        ],
+    }],
+    temperature=0.2,
+    max_completion_tokens=1024,
+)
+
+print(response.choices[0].message.content)
+```
+
+运行：
+
+```sh
+uv run --with groq python recognize.py
+```
+
+Base64 会让请求体积比原文件更大。如果请求接近 20 MB 上限，请先缩小或压缩图片，或者改用模型能够访问的 HTTPS 图片 URL。
+
+## 7. 常见问题
+
+### `401 Invalid API Key`
+
+- 确认复制的是完整的 `gsk_...` 密钥。
+- 环境变量中不要包含多余空格、引号内容或换行。
+- 如果密钥曾经出现在公开位置，删除旧密钥并重新创建。
+
+### `404` 或 `model not found`
+
+- 模型名必须是 `qwen/qwen3.6-27b`。
+- 该模型目前属于 Preview；如果 Groq 后续调整可用性，请查看官方模型页和 Groq Console 中当前可选模型。
+
+### `413` 或图片过大
+
+- Base64 图片限制比 URL 图片严格；先缩小尺寸或压缩质量。
+- 不要把大量图片塞进一个请求；按 Qwen3.6-27B 模型专页的限制，单次最多 3 张。
+
+### `429 Too Many Requests`
+
+- Free Plan 已达到分钟、Token 或每日限制。
+- 查看响应头中的速率限制信息，等待额度恢复后重试。
+
+### 模型只描述图片，没有回答重点
+
+把任务写具体，例如：
+
+```text
+不要泛泛描述。请只完成三件事：
+1. 逐字抄出红色错误框里的文字；
+2. 返回错误框在原图中的大致位置；
+3. 根据界面上下文判断最可能的原因。
+```
+
+## 官方资料
+
+- [Groq Quickstart](https://console.groq.com/docs/quickstart)
+- [Groq API Keys](https://console.groq.com/keys)
+- [Qwen3.6-27B 模型页](https://console.groq.com/docs/model/qwen/qwen3.6-27b)
+- [Groq Images and Vision](https://console.groq.com/docs/vision)
+- [Groq Rate Limits](https://console.groq.com/docs/rate-limits)

package/docs/python-runtime.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/python-runtime.md
+python-runtime.md: d2071e9ffbffe97d44c5708193e24ee3eabb50b1
+python-runtime.zh.md: 0ef2e984b564b5436424fbca70262e0b9c59aed9