@anionex/dsh-vision-toolkit 0.1.25 → 0.1.26

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: b382c30dbb2676077ac95aaf67db7f809bc6fc15
-README.zh.md: a3504f000fa8baa161b2855f5cdf71b9584125f4
+README.md: f590f56c6253c25a8066445419c1ec490936b8e8
+README.zh.md: 7896e4d8121c59bfd7e0c03942c9d1936716bd06

package/README.md

@@ -274,7 +274,79 @@ For a trusted internal endpoint that uses a self-signed certificate or MITM prox
 - Node.js `^22.19.0` or `>=24.0.0`.
 - Python 3.11+; the plugin prepares an isolated environment by default.
 - Only `vision_html_screenshot` requires Chrome, Chromium, or Edge.
-- Inputs must be PNG, JPEG, GIF, or WebP files in the session workspace or an explicitly allowed directory.
+- Inputs must be PNG, JPEG, GIF, or WebP files in the session workspace, the platform temporary directory, or an explicitly allowed directory.
+
+### Configure the Python runtime
+
+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. Without an override, the plugin tries `python3` then `python` on macOS/Linux, and `python`, `py -3`, then `python3` on Windows. 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:
+
+```yaml
+- id: vision-toolkit
+  config:
+    runtime:
+      # macOS/Linux system Python
+      python: python3
+      # Or a project-local environment:
+      # python: /absolute/path/to/project/.venv/bin/python
+      # Windows venv (forward slashes also work in YAML):
+      # python: C:/Users/you/project/.venv/Scripts/python.exe
+      # Windows launcher, when its default Python is 3.11+:
+      # 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:
+
+```sh
+python3 --version                         # must report 3.11 or newer
+uv venv .venv --python 3.13
+```
+
+For `runtime.mode: external`, install the locked dependencies using the `runtime/requirements.lock` from the **DSH Vision Toolkit plugin** checkout, then point `runtime.agentVisionToolkitPath` at a separate exact `agent-vision-toolkit` snapshot. The packaged `vendor/agent-vision-toolkit` directory is such a snapshot when it has not been modified:
+
+```sh
+uv pip install --python .venv/bin/python \
+  -r /absolute/path/to/dsh-vision-toolkit/runtime/requirements.lock
+```
+
+```yaml
+- id: vision-toolkit
+  config:
+    runtime:
+      mode: external
+      python: /absolute/path/to/dsh-vision-toolkit/.venv/bin/python
+      agentVisionToolkitPath: /absolute/path/to/dsh-vision-toolkit/vendor/agent-vision-toolkit
+```
+
+On Windows, use `py -3 --version` for the version check and `.venv\Scripts\python.exe` plus `runtime\requirements.lock` in the corresponding commands:
+
+```powershell
+py -3 --version                         # must report 3.11 or newer
+uv venv .venv --python 3.13
+# External mode only; use the plugin checkout's absolute lockfile path:
+uv pip install --python .venv\Scripts\python.exe -r C:\absolute\path\to\dsh-vision-toolkit\runtime\requirements.lock
+```
+
+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`.
+
+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.
+
+Use `allowedDirs` only for additional trusted input roots outside the workspace and platform temporary directory:
+
+```yaml
+- id: vision-toolkit
+  config:
+    allowedDirs:
+      # macOS/Linux example
+      - /srv/vision-inputs
+      # Windows example (use this instead on Windows)
+      # - D:/vision-inputs
+```
+
+`allowedDirs` is an input allowlist, not the managed runtime cache. The managed runtime keeps its own files under `$DSH_HOME/cache/dsh-vision-toolkit` (or `~/.dsh/cache/dsh-vision-toolkit` when `DSH_HOME` is unset); that directory does not need to be added. Environment-variable forms such as `$env:TEMP` and `%TEMP%` are not expanded inside `allowedDirs`, so configure extra roots with real absolute paths.
 
 <details>
 <summary><strong>Install, upgrade, disable, and uninstall</strong></summary>

package/README.zh.md

@@ -277,7 +277,79 @@ API Key:  https://agent-vision.anionex.me（自动填写）
 - Node.js `^22.19.0` 或 `>=24.0.0`。
 - Python 3.11+；插件默认自动创建隔离环境。
 - 只有 `vision_html_screenshot` 需要 Chrome、Chromium 或 Edge。
-- 图片需为 PNG、JPEG、GIF 或 WebP，并位于会话工作区或明确允许的目录中。
+- 图片需为 PNG、JPEG、GIF 或 WebP，并位于会话工作区、平台临时目录或明确允许的目录中。
+
+### 配置 Python 运行时
+
+打包的 `managed` 运行时会创建自己的隔离虚拟环境。`runtime.python` 指定的是引导或刷新该环境时使用的 Python 解释器，并不会把 managed 运行时替换成系统解释器的全局 site-packages。当自动发现失败或机器上有多个 Python 时，应设置这个选项；`runtime.mode: external` 也使用该覆盖值。
+
+要求 Python 3.11 或更高版本。不设置覆盖值时，插件在 macOS/Linux 上依次尝试 `python3`、`python`，在 Windows 上依次尝试 `python`、`py -3`、`python3`。手动配置的值会作为一个可执行文件名或路径传入，而不是作为带参数的 Shell 命令，因此 Windows 启动器应填写 `py`（不要填写 `py -3`）；需要固定版本时，请填写绝对路径。
+
+在 Profile patch 中配置：
+
+```yaml
+- id: vision-toolkit
+  config:
+    runtime:
+      # macOS/Linux 系统 Python
+      python: python3
+      # 或使用项目内虚拟环境：
+      # python: /absolute/path/to/project/.venv/bin/python
+      # Windows 虚拟环境（YAML 中也可以使用正斜杠）：
+      # python: C:/Users/you/project/.venv/Scripts/python.exe
+      # Windows 启动器；其默认 Python 必须是 3.11+：
+      # python: py
+```
+
+对于 managed 运行时，创建项目内解释器并将 `runtime.python` 指向它即可。插件会把锁定依赖安装到自己的 managed 缓存中，因此将 lockfile 安装到这个引导环境是可选的：
+
+```sh
+python3 --version                         # 必须是 3.11 或更高
+uv venv .venv --python 3.13
+```
+
+对于 `runtime.mode: external`，请使用 **DSH Vision Toolkit 插件** checkout 中的 `runtime/requirements.lock` 安装锁定依赖，再把 `runtime.agentVisionToolkitPath` 指向另一个准确的 `agent-vision-toolkit` 快照。未被修改的打包目录 `vendor/agent-vision-toolkit` 就是这样的快照：
+
+```sh
+uv pip install --python .venv/bin/python \
+  -r /absolute/path/to/dsh-vision-toolkit/runtime/requirements.lock
+```
+
+```yaml
+- id: vision-toolkit
+  config:
+    runtime:
+      mode: external
+      python: /absolute/path/to/dsh-vision-toolkit/.venv/bin/python
+      agentVisionToolkitPath: /absolute/path/to/dsh-vision-toolkit/vendor/agent-vision-toolkit
+```
+
+Windows 请使用 `py -3 --version` 检查版本，并在对应命令中使用 `.venv\Scripts\python.exe` 和 `runtime\requirements.lock`：
+
+```powershell
+py -3 --version                         # 必须是 3.11 或更高
+uv venv .venv --python 3.13
+# 仅 external 模式需要；请使用插件 checkout 中 lockfile 的绝对路径：
+uv pip install --python .venv\Scripts\python.exe -r C:\absolute\path\to\dsh-vision-toolkit\runtime\requirements.lock
+```
+
+把 `runtime.python` 指向同一个解释器，保存 Profile patch 后重启 Web Profile。然后打开 **设置 → 视觉工具**：运行时面板应显示实际使用的解释器和 Python 版本；点击 **运行健康检查** 和 **测试视觉模型**，确认不再出现 Python 版本错误。最后可将一张 PNG/JPEG 放入会话工作区并调用 `vision_glance` 做冒烟测试。
+
+路径围栏会自动允许会话工作区和平台临时目录。macOS/Linux 的临时目录根路径是 `/tmp`。Windows 依次读取 `TEMP`、`TMP`，两者都未设置时使用操作系统回退值；模型生成的 `/tmp/...` 路径会先映射到该 Windows 临时目录，再执行常规 realpath 路径围栏检查。这些平台临时路径无需加入 `allowedDirs`。
+
+只有在需要读取会话工作区和平台临时目录之外的可信输入根目录时，才配置 `allowedDirs`：
+
+```yaml
+- id: vision-toolkit
+  config:
+    allowedDirs:
+      # macOS/Linux 示例
+      - /srv/vision-inputs
+      # Windows 示例（Windows 上改用这一项）
+      # - D:/vision-inputs
+```
+
+`allowedDirs` 是输入目录白名单，不是 managed 运行时缓存目录。managed 运行时自己的文件位于 `$DSH_HOME/cache/dsh-vision-toolkit`（未设置 `DSH_HOME` 时是 `~/.dsh/cache/dsh-vision-toolkit`），无需加入白名单。`allowedDirs` 内不会展开 `$env:TEMP` 或 `%TEMP%` 这类环境变量，因此额外输入根目录必须填写真实绝对路径。
 
 <details>
 <summary><strong>安装、升级、禁用和卸载</strong></summary>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anionex/dsh-vision-toolkit",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "description": "DeepSeek Harness-native integration for agent-vision-toolkit: image Q&A, OCR, grounding, UI restoration, pixel diff, Artifacts, and Web UI.",
   "keywords": [
     "deepseek",