@mengruo/dsh-vision-toolkit 0.0.1

package/docs/python-runtime.md

@@ -0,0 +1,89 @@
+# Configure the Python runtime
+
+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 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:
+
+```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 (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
+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`.
+
+## 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.
+
+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.

package/docs/python-runtime.zh.md

@@ -0,0 +1,89 @@
+# 配置 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，镜像不可用时回退到 GitHub 官方发布源。手动配置的值会作为一个可执行文件名或路径传入，而不是作为带参数的 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 缓存中（优先使用腾讯云 PyPI 镜像，镜像不可用时回退官方 PyPI），因此将 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` 做冒烟测试。
+
+## 更新托管 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`。
+
+只有在需要读取会话工作区和平台临时目录之外的可信输入根目录时，才配置 `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%` 这类环境变量，因此额外输入根目录必须填写真实绝对路径。

package/docs/requirements-traceability/README.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/requirements-traceability/README.md
+README.md: 5bc9040f66acef30c930203ab0fe6c55cb76773e
+README.zh.md: 53bc1f0cb498e59529ca3f915e6a5649142567ad

package/docs/requirements-traceability/README.md

@@ -0,0 +1,75 @@
+# Vision Toolkit requirements traceability
+
+English | [中文](README.zh.md)
+
+This reference maps the DSH Vision Toolkit product brief's committed P0/P1 requirements to their owning implementation, automated coverage, and runnable acceptance evidence. A row marked **Delivered** is part of the package contract; P2/P3 rows document intentional product boundaries rather than unfinished P0/P1 work.
+
+## P0 product requirements
+
+| Requirement | Status | Owning implementation | Verification |
+|---|---|---|---|
+| P0-1 Standard Profile Bundle | **Delivered** | [`package.json`](../../package.json), [`cordis.patch.yml`](../../cordis.patch.yml), [`src/index.ts`](../../src/index.ts), committed `lib/` | [`tests/package-layout.spec.ts`](../../tests/package-layout.spec.ts), [`tests/profile-install.e2e.spec.ts`](../../tests/profile-install.e2e.spec.ts), clean `--dump-config`, Web/Headless boot, disable, and removal checks |
+| P0-2 Upstream reuse | **Delivered** | [`src/version.ts`](../../src/version.ts), [`src/runtime-install.ts`](../../src/runtime-install.ts), [`scripts/upstream-manifest.mjs`](../../scripts/upstream-manifest.mjs), [`scripts/sync-upstream.mjs`](../../scripts/sync-upstream.mjs), [`vendor/agent-vision-toolkit/UPSTREAM_MANIFEST.json`](../../vendor/agent-vision-toolkit/UPSTREAM_MANIFEST.json) | [`tests/upstream.spec.ts`](../../tests/upstream.spec.ts), [`tests/runtime-install.spec.ts`](../../tests/runtime-install.spec.ts), build-time manifest verification |
+| P0-3 Native tools | **Delivered** | Independent definitions in [`src/tools.ts`](../../src/tools.ts), Agent-scoped publication in [`src/exposure.ts`](../../src/exposure.ts), shared execution in [`src/runtime.ts`](../../src/runtime.ts), upstream adapter in [`src/upstream.ts`](../../src/upstream.ts) | [`tests/tools.spec.ts`](../../tests/tools.spec.ts), [`tests/runtime.spec.ts`](../../tests/runtime.spec.ts), [`tests/upstream.spec.ts`](../../tests/upstream.spec.ts), [`tests/vision-prompt-guard.spec.ts`](../../tests/vision-prompt-guard.spec.ts), real-profile progressive calls for all five P0 tools |
+| P0-4 Configuration and Credentials | **Delivered** | [`src/config.ts`](../../src/config.ts), per-operation resolution in [`src/runtime.ts`](../../src/runtime.ts), isolated environment construction in [`src/upstream.ts`](../../src/upstream.ts) | [`tests/config.spec.ts`](../../tests/config.spec.ts), Credential/error/redaction cases in [`tests/runtime.spec.ts`](../../tests/runtime.spec.ts) and [`tests/errors.spec.ts`](../../tests/errors.spec.ts) |
+| P0-5 Skill lifecycle | **Delivered** | Readiness ordering, lifecycle abort, and global disposer in [`src/index.ts`](../../src/index.ts); per-Agent activation, restoration, and teardown in [`src/exposure.ts`](../../src/exposure.ts); bundled content in [`src/skill.ts`](../../src/skill.ts) | Agent isolation, native/direct/Code Mode activation, Session restoration, in-flight cancellation, and disposal cases in [`tests/tools.spec.ts`](../../tests/tools.spec.ts); progressive exposure plus disable/uninstall paths in [`tests/profile-install.e2e.spec.ts`](../../tests/profile-install.e2e.spec.ts) |
+| P0-6 Text-only model results | **Delivered** | JSON output schemas and pure renderers in [`src/tools.ts`](../../src/tools.ts); canonical Artifact descriptors in [`src/artifacts.ts`](../../src/artifacts.ts); schema visibility derived from durable Skill-load evidence in [`src/exposure.ts`](../../src/exposure.ts) | Tool schema/presentation assertions in [`tests/tools.spec.ts`](../../tests/tools.spec.ts), request-by-request schema and model-facing transcript assertions in [`tests/profile-install.e2e.spec.ts`](../../tests/profile-install.e2e.spec.ts) |
+| P0-7 Stable errors | **Delivered** | [`src/errors.ts`](../../src/errors.ts), boundary validation in [`src/paths.ts`](../../src/paths.ts), [`src/runtime.ts`](../../src/runtime.ts), and [`src/upstream.ts`](../../src/upstream.ts) | [`tests/errors.spec.ts`](../../tests/errors.spec.ts), [`tests/paths.spec.ts`](../../tests/paths.spec.ts), parser, timeout, cancellation, credential, and capacity cases in runtime/upstream tests |
+| P0-8 Tests and documentation | **Delivered** | Bilingual [`README.md`](../../README.md), package tests, managed runtime, example, and committed build output | `pnpm run build`, `pnpm test`, `pnpm pack --dry-run`, translation/Markdown gates, and the keyless clean-profile e2e |
+
+## P1 product requirements
+
+| Requirement | Status | Owning implementation | Verification |
+|---|---|---|---|
+| P1-1 Artifact delivery | **Delivered** | Descriptor creation in [`src/artifacts.ts`](../../src/artifacts.ts), fenced atomic paths in [`src/paths.ts`](../../src/paths.ts), signed capability delivery in [`src/artifact-access.ts`](../../src/artifact-access.ts) | [`tests/artifacts.spec.ts`](../../tests/artifacts.spec.ts), [`tests/artifact-access.spec.ts`](../../tests/artifact-access.spec.ts), Artifact-producing runtime/profile tests |
+| P1-2 Extended tools | **Delivered** | `vision_pixel_diff`, `vision_long_screenshot_ocr`, `vision_extract_foreground`, `vision_dominant_colors`, and `vision_html_screenshot` in [`src/tools.ts`](../../src/tools.ts) and [`src/runtime.ts`](../../src/runtime.ts) | P1 parser and runtime cases in [`tests/upstream.spec.ts`](../../tests/upstream.spec.ts) and [`tests/runtime.spec.ts`](../../tests/runtime.spec.ts); pixel-diff and long-OCR real-profile calls |
+| P1-3 Dedicated Web presentation | **Delivered** | Browser plugin and dedicated cards in [`src/client/index.tsx`](../../src/client/index.tsx); presentation-only capability metadata in [`src/artifact-access.ts`](../../src/artifact-access.ts) | [`tests/client.spec.ts`](../../tests/client.spec.ts), safe preview tests in [`tests/artifact-access.spec.ts`](../../tests/artifact-access.spec.ts), Web visual/console QA |
+| P1-4 Health checks | **Delivered** | Health/version runtime contracts in [`src/runtime.ts`](../../src/runtime.ts), same-origin Web actions in [`src/web.ts`](../../src/web.ts), and the Settings surface in [`src/client/index.tsx`](../../src/client/index.tsx); Settings distinguishes the lightweight authenticated `GET /models` probe from an explicit real multimodal request using the bundled diagnostic image, and these administrative diagnostics are deliberately absent from the model tool registry | Health and real-model success/failure cases in [`tests/runtime.spec.ts`](../../tests/runtime.spec.ts), explicit API/model-test behavior in [`tests/web.spec.ts`](../../tests/web.spec.ts) and [`tests/client.spec.ts`](../../tests/client.spec.ts), plus model-tool absence in [`tests/tools.spec.ts`](../../tests/tools.spec.ts) |
+| P1-5 Settings | **Delivered** | Namespace/config in [`src/config.ts`](../../src/config.ts), prepare-before-swap manager in [`src/runtime-manager.ts`](../../src/runtime-manager.ts), private same-origin route in [`src/web.ts`](../../src/web.ts), section in [`src/client/index.tsx`](../../src/client/index.tsx) | [`tests/runtime-manager.spec.ts`](../../tests/runtime-manager.spec.ts), [`tests/web.spec.ts`](../../tests/web.spec.ts), [`tests/client.spec.ts`](../../tests/client.spec.ts), clean Web-profile save/restart QA |
+| P1-6 Install and upgrade experience | **Delivered** | Bundle lifecycle in [`src/index.ts`](../../src/index.ts), content-addressed managed runtime in [`src/runtime-install.ts`](../../src/runtime-install.ts), generation manager in [`src/runtime-manager.ts`](../../src/runtime-manager.ts), and the registry/Profile-constrained Settings updater with DSH Web restart handoff in [`src/plugin-update.ts`](../../src/plugin-update.ts) | Runtime interruption/concurrency tests, frozen-lockfile rollback and runtime-readiness checks in [`tests/plugin-update.spec.ts`](../../tests/plugin-update.spec.ts), package-layout test, clean-profile lifecycle, persisted Settings and failed-candidate retention checks |
+
+## Cross-cutting requirements
+
+| Area | Contract and evidence |
+|---|---|
+| Security | [`src/paths.ts`](../../src/paths.ts) confines reads and writes by realpath; [`src/runtime.ts`](../../src/runtime.ts) decodes and limits images before upload and structurally parses trace SVG before commit; [`src/upstream.ts`](../../src/upstream.ts) marks image text/instructions as untrusted in every direct and long-OCR visual-model prompt; [`src/tools.ts`](../../src/tools.ts) and [`src/skill.ts`](../../src/skill.ts) tell the text agent to treat derived output as evidence, not commands; [`src/artifact-access.ts`](../../src/artifact-access.ts) revalidates signed files on every read and sandboxes SVG; [`src/errors.ts`](../../src/errors.ts) redacts secrets. Path, symlink, format, size, XML/doctype, prompt guard, token-forgery, file-replacement, and CSP cases are automated. |
+| Portability | Runtime and browser calls use argv vectors and Node filesystem/process APIs rather than POSIX shell composition. Managed preparation has `uv` and `venv`/pip paths; Python and Chrome discovery include platform-specific candidates. Package tests avoid machine-local dependency specifiers, and the checked-in fixture/profile flow is keyless. |
+| Performance and cancellation | [`src/runtime.ts`](../../src/runtime.ts) applies one hard deadline, propagates `AbortSignal`, bounds per-session concurrency, rejects oversized decoded images before remote I/O, deduplicates repeated inputs within one glance operation, and keeps a one-entry content/configuration-keyed cache for the last successful identical glance in each live Session. [`src/index.ts`](../../src/index.ts) aborts plugin-owned calls before unregistering tools. Timeout, caller/plugin cancellation, cache-hit/miss, semaphore, and independent-session behavior are automated. |
+| Observability | [`src/runtime.ts`](../../src/runtime.ts) logs bounded tool name, outcome, total/upstream duration, image count/bytes/pixels, cache hits, model, and error category while excluding base64, credentials, headers, and unbounded upstream output. |
+| Model-context economy | The profile-global runtime publishes one small bootstrap, while [`src/exposure.ts`](../../src/exposure.ts) mounts the ten execution schemas only in an Agent that loads `vision-skills` and hides the bootstrap afterward. Other Agents remain unchanged. Health, connection, and version diagnostics stay exclusively on the Web Settings seam and never become model tools. Unit tests cover Agent isolation and restoration; every real-profile tool flow asserts the initial and activated schema sets. |
+| Maintainability | Every tool calls one [`VisionToolkitRuntime`](../../src/runtime.ts); DSH-specific adaptation remains in [`src/tools.ts`](../../src/tools.ts), [`src/exposure.ts`](../../src/exposure.ts), [`src/index.ts`](../../src/index.ts), [`src/web.ts`](../../src/web.ts), and [`src/client/index.tsx`](../../src/client/index.tsx), while the pinned upstream remains the sole algorithm source. Runtime readiness, Skill/bootstrap publication, and Agent-scoped schemas belong to one lifecycle generation. |
+| HTML screenshot isolation | The pinned screenshot guard uses a disposable Chrome profile, `--use-mock-keychain`, and `--incognito`, removes the profile after each call, and keeps network disabled. [`tests/html-screenshot-guard.spec.ts`](../../tests/html-screenshot-guard.spec.ts) captures the actual argv and cleanup behavior. |
+| UI restoration acceptance | [`scripts/ui-restoration-example.ts`](../../scripts/ui-restoration-example.ts) performs reference → HTML render → pixel diff through the real runtime. [`examples/ui-restoration/README.md`](../../examples/ui-restoration/README.md) owns the reproducible procedure and checked-in evidence; [`tests/ui-restoration-example.spec.ts`](../../tests/ui-restoration-example.spec.ts) enforces it. |
+
+## Error and lifecycle scenarios
+
+| Scenario | Expected behavior | Evidence |
+|---|---|---|
+| Missing/invalid image, format, region, or path | Reject before upstream execution with an input, capacity, or path-safe error | [`tests/paths.spec.ts`](../../tests/paths.spec.ts), [`tests/runtime.spec.ts`](../../tests/runtime.spec.ts) |
+| Missing Credential | Local tools remain usable; remote tools plus explicit API-connection and real-model tests report a redacted configuration/service action | [`tests/runtime.spec.ts`](../../tests/runtime.spec.ts), [`tests/web.spec.ts`](../../tests/web.spec.ts) |
+| 401/403, 429, timeout, malformed output, or cancellation | Return a stable actionable category, preserve bounded diagnostics, and stop the request/subprocess | [`tests/errors.spec.ts`](../../tests/errors.spec.ts), [`tests/runtime.spec.ts`](../../tests/runtime.spec.ts), [`tests/upstream.spec.ts`](../../tests/upstream.spec.ts) |
+| Runtime unavailable during initial load | Register no Skill, activation bootstrap, or Agent-scoped tools; keep Web Settings available for repair | [`src/index.ts`](../../src/index.ts), lifecycle tests in [`tests/tools.spec.ts`](../../tests/tools.spec.ts) and [`tests/web.spec.ts`](../../tests/web.spec.ts) |
+| Runtime candidate fails during live update | Preserve the current serving generation and stored usable configuration | [`tests/runtime-manager.spec.ts`](../../tests/runtime-manager.spec.ts), [`tests/web.spec.ts`](../../tests/web.spec.ts) |
+| Concurrent Settings candidates complete out of order | The newer ticket wins; an obsolete slower candidate cannot activate | [`tests/runtime-manager.spec.ts`](../../tests/runtime-manager.spec.ts) |
+| Disable, re-enable, or uninstall | Active plugin-owned calls are cancelled, Agent-scoped tools, bootstrap, and Skill disappear and return as one lifecycle unit, and uninstall removes the bundle layer | [`tests/tools.spec.ts`](../../tests/tools.spec.ts), [`tests/profile-install.e2e.spec.ts`](../../tests/profile-install.e2e.spec.ts) |
+
+## P2 and P3 boundary
+
+| Scope | Status | Decision |
+|---|---|---|
+| P2 stable `ctx.visionToolkit` service and capability discovery | **Deferred by design** | The product brief requires at least one independent plugin consumer before stabilizing this API. `VisionToolkitRuntime` remains package-internal, so P0/P1 can evolve without creating a false compatibility promise. |
+| P2 provider ecosystem | **Deferred by design** | The package supports its pinned upstream and one configured endpoint through OpenAI Chat Completions or Anthropic Messages; it does not prebuild an unused provider registry. |
+| P3 exploratory inputs and automation | **Out of scope** | Upload/drag-and-drop, camera/video/audio/document ingestion, interactive annotations, automatic clicking, remote clusters, model routing/voting, and cross-session caches are not part of this release contract. |
+
+## Reproducible verification
+
+Run package checks from `dsh-vision-toolkit/`:
+
+```sh
+pnpm run build
+pnpm test
+pnpm run example:ui-restoration
+pnpm pack --dry-run
+```
+
+The release acceptance pass additionally runs the repository's plugin checker, installs the package into clean Web and Headless `DSH_HOME` directories, inspects `--dump-config`, exercises local and keyless mock-backed remote tool calls, verifies Settings persistence and live switching, checks dedicated Web cards with zero browser-console errors, disables/re-enables the row, and removes the package. These runtime checks complement the automated tests; they do not replace them.

package/docs/requirements-traceability/README.zh.md

@@ -0,0 +1,75 @@
+# Vision Toolkit 需求追踪
+
+[English](README.md) | 中文
+
+本参考将 DSH Vision Toolkit 产品需求中承诺的 P0/P1 条目映射到对应实现、自动化覆盖和可运行验收证据。标记为**已交付**的条目属于软件包契约；P2/P3 条目记录有意设置的产品边界，不代表尚未完成的 P0/P1 工作。
+
+## P0 产品需求
+
+| 需求 | 状态 | 负责实现 | 验证 |
+|---|---|---|---|
+| P0-1 标准 Profile Bundle | **已交付** | [`package.json`](../../package.json)、[`cordis.patch.yml`](../../cordis.patch.yml)、[`src/index.ts`](../../src/index.ts)、已提交的 `lib/` | [`tests/package-layout.spec.ts`](../../tests/package-layout.spec.ts)、[`tests/profile-install.e2e.spec.ts`](../../tests/profile-install.e2e.spec.ts)、干净 `--dump-config`、Web/Headless 启动、禁用和移除检查 |
+| P0-2 上游复用 | **已交付** | [`src/version.ts`](../../src/version.ts)、[`src/runtime-install.ts`](../../src/runtime-install.ts)、[`scripts/upstream-manifest.mjs`](../../scripts/upstream-manifest.mjs)、[`scripts/sync-upstream.mjs`](../../scripts/sync-upstream.mjs)、[`vendor/agent-vision-toolkit/UPSTREAM_MANIFEST.json`](../../vendor/agent-vision-toolkit/UPSTREAM_MANIFEST.json) | [`tests/upstream.spec.ts`](../../tests/upstream.spec.ts)、[`tests/runtime-install.spec.ts`](../../tests/runtime-install.spec.ts)、构建时 manifest 验证 |
+| P0-3 原生工具 | **已交付** | [`src/tools.ts`](../../src/tools.ts) 中的独立定义、[`src/exposure.ts`](../../src/exposure.ts) 中的 Agent 级发布、[`src/runtime.ts`](../../src/runtime.ts) 中的共享执行、[`src/upstream.ts`](../../src/upstream.ts) 中的上游适配 | [`tests/tools.spec.ts`](../../tests/tools.spec.ts)、[`tests/runtime.spec.ts`](../../tests/runtime.spec.ts)、[`tests/upstream.spec.ts`](../../tests/upstream.spec.ts)、[`tests/vision-prompt-guard.spec.ts`](../../tests/vision-prompt-guard.spec.ts)、全部五个 P0 工具的真实 Profile 渐进调用 |
+| P0-4 配置与 Credential | **已交付** | [`src/config.ts`](../../src/config.ts)、[`src/runtime.ts`](../../src/runtime.ts) 中的逐操作解析、[`src/upstream.ts`](../../src/upstream.ts) 中的隔离环境构造 | [`tests/config.spec.ts`](../../tests/config.spec.ts)、[`tests/runtime.spec.ts`](../../tests/runtime.spec.ts) 和 [`tests/errors.spec.ts`](../../tests/errors.spec.ts) 中的 Credential/错误/脱敏用例 |
+| P0-5 skill 生命周期 | **已交付** | [`src/index.ts`](../../src/index.ts) 中的就绪顺序、生命周期中止和全局 disposer；[`src/exposure.ts`](../../src/exposure.ts) 中的逐 Agent 激活、恢复和释放；[`src/skill.ts`](../../src/skill.ts) 中的打包内容 | [`tests/tools.spec.ts`](../../tests/tools.spec.ts) 中的 Agent 隔离、原生/直接/Code Mode 激活、Session 恢复、在途取消和释放用例；[`tests/profile-install.e2e.spec.ts`](../../tests/profile-install.e2e.spec.ts) 中的渐进暴露、禁用和卸载路径 |
+| P0-6 纯文本模型结果 | **已交付** | [`src/tools.ts`](../../src/tools.ts) 中的 JSON 输出 schema 与纯渲染函数；[`src/artifacts.ts`](../../src/artifacts.ts) 中的规范产物描述；[`src/exposure.ts`](../../src/exposure.ts) 中由持久 Skill 加载证据派生的 schema 可见性 | [`tests/tools.spec.ts`](../../tests/tools.spec.ts) 中的工具 schema/展示断言、[`tests/profile-install.e2e.spec.ts`](../../tests/profile-install.e2e.spec.ts) 中逐请求的 schema 与模型可见 transcript（文本记录）断言 |
+| P0-7 稳定错误 | **已交付** | [`src/errors.ts`](../../src/errors.ts)，以及 [`src/paths.ts`](../../src/paths.ts)、[`src/runtime.ts`](../../src/runtime.ts)、[`src/upstream.ts`](../../src/upstream.ts) 中的边界验证 | [`tests/errors.spec.ts`](../../tests/errors.spec.ts)、[`tests/paths.spec.ts`](../../tests/paths.spec.ts)，以及运行时/上游测试中的解析、超时、取消、Credential 和容量用例 |
+| P0-8 测试与文档 | **已交付** | 双语 [`README.md`](../../README.md)、软件包测试、managed 运行时、示例和已提交构建产物 | `pnpm run build`、`pnpm test`、`pnpm pack --dry-run`、翻译/Markdown 门禁和无真实 Key 的干净 Profile e2e |
+
+## P1 产品需求
+
+| 需求 | 状态 | 负责实现 | 验证 |
+|---|---|---|---|
+| P1-1 产物交付 | **已交付** | [`src/artifacts.ts`](../../src/artifacts.ts) 中的产物描述创建、[`src/paths.ts`](../../src/paths.ts) 中受围栏保护的原子路径、[`src/artifact-access.ts`](../../src/artifact-access.ts) 中的签名能力交付 | [`tests/artifacts.spec.ts`](../../tests/artifacts.spec.ts)、[`tests/artifact-access.spec.ts`](../../tests/artifact-access.spec.ts)、会生成产物的运行时/Profile 测试 |
+| P1-2 扩展工具 | **已交付** | [`src/tools.ts`](../../src/tools.ts) 和 [`src/runtime.ts`](../../src/runtime.ts) 中的 `vision_pixel_diff`、`vision_long_screenshot_ocr`、`vision_extract_foreground`、`vision_dominant_colors`、`vision_html_screenshot` | [`tests/upstream.spec.ts`](../../tests/upstream.spec.ts) 和 [`tests/runtime.spec.ts`](../../tests/runtime.spec.ts) 中的 P1 解析器/运行时用例；真实 Profile pixel-diff 和长截图 OCR 调用 |
+| P1-3 专用 Web 展示 | **已交付** | [`src/client/index.tsx`](../../src/client/index.tsx) 中的浏览器插件与专用卡片；[`src/artifact-access.ts`](../../src/artifact-access.ts) 中仅供展示的能力元数据 | [`tests/client.spec.ts`](../../tests/client.spec.ts)、[`tests/artifact-access.spec.ts`](../../tests/artifact-access.spec.ts) 中的安全预览测试、Web 视觉/Console QA |
+| P1-4 健康检查 | **已交付** | [`src/runtime.ts`](../../src/runtime.ts) 中的健康检查/版本运行时契约、[`src/web.ts`](../../src/web.ts) 中的同源 Web 操作，以及 [`src/client/index.tsx`](../../src/client/index.tsx) 中的 Settings 界面；Settings 明确区分携带凭据的轻量 `GET /models` 探测与使用自带诊断图片的显式真实多模态请求，这些管理诊断能力有意不进入模型工具注册表 | [`tests/runtime.spec.ts`](../../tests/runtime.spec.ts) 中的健康检查及真实模型成功/失败用例、[`tests/web.spec.ts`](../../tests/web.spec.ts) 与 [`tests/client.spec.ts`](../../tests/client.spec.ts) 中的显式 API/模型测试行为，以及 [`tests/tools.spec.ts`](../../tests/tools.spec.ts) 中的模型工具缺席断言 |
+| P1-5 Settings | **已交付** | [`src/config.ts`](../../src/config.ts) 中的 namespace/配置、[`src/runtime-manager.ts`](../../src/runtime-manager.ts) 中的 prepare-before-swap manager、[`src/web.ts`](../../src/web.ts) 中的同源私有路由、[`src/client/index.tsx`](../../src/client/index.tsx) 中的 Settings 分区 | [`tests/runtime-manager.spec.ts`](../../tests/runtime-manager.spec.ts)、[`tests/web.spec.ts`](../../tests/web.spec.ts)、[`tests/client.spec.ts`](../../tests/client.spec.ts)、干净 Web Profile 保存/重启 QA |
+| P1-6 安装与升级体验 | **已交付** | [`src/index.ts`](../../src/index.ts) 中的 Bundle 生命周期、[`src/runtime-install.ts`](../../src/runtime-install.ts) 中的内容寻址 managed 运行时、[`src/runtime-manager.ts`](../../src/runtime-manager.ts) 中的 generation manager，以及 [`src/plugin-update.ts`](../../src/plugin-update.ts) 中按 registry/Profile 安全约束执行的 Settings 更新器和 DSH Web 重启交接 | 运行时中断/并发测试、[`tests/plugin-update.spec.ts`](../../tests/plugin-update.spec.ts) 中的 frozen-lockfile 回滚与 Runtime 就绪检查、软件包布局测试、干净 Profile 生命周期、Settings 持久化和失败候选保留检查 |
+
+## 横切需求
+
+| 领域 | 契约与证据 |
+|---|---|
+| 安全 | [`src/paths.ts`](../../src/paths.ts) 通过 realpath 限制读写范围；[`src/runtime.ts`](../../src/runtime.ts) 在上传前解码并限制图片，并在提交前结构化解析 trace SVG；[`src/upstream.ts`](../../src/upstream.ts) 在每个直接和长截图 OCR 视觉模型提示词中把图片文字/指令标记为不可信；[`src/tools.ts`](../../src/tools.ts) 和 [`src/skill.ts`](../../src/skill.ts) 要求文本 agent 只把衍生输出当作证据而非命令；[`src/artifact-access.ts`](../../src/artifact-access.ts) 每次读取都重新验证签名文件并 sandbox SVG；[`src/errors.ts`](../../src/errors.ts) 对密钥脱敏。路径、符号链接、格式、大小、XML/doctype、提示词 guard、伪造 token、文件替换和 CSP 用例均有自动化覆盖。 |
+| 可移植性 | 运行时和浏览器调用使用 argv 向量与 Node 文件系统/进程 API，不拼接 POSIX Shell。Managed 准备同时提供 `uv` 和 `venv`/pip 路径；Python 与 Chrome 探测包含平台候选。软件包测试拒绝机器本地依赖声明，已提交 fixture/Profile 流程无需真实 Key。 |
+| 性能与取消 | [`src/runtime.ts`](../../src/runtime.ts) 应用一个硬截止时间、传递 `AbortSignal`、限制每个会话的并发数、在远程 I/O 前拒绝解码后过大的图片、在一次 glance 操作中对重复输入去重，并为每个活动会话保留一条按内容/配置键控的最近成功相同 glance 缓存。[`src/index.ts`](../../src/index.ts) 会在注销工具前中止插件拥有的调用。超时、调用方/插件取消、缓存命中/未命中、信号量和独立会话行为均有自动化覆盖。 |
+| 可观察性 | [`src/runtime.ts`](../../src/runtime.ts) 记录有界的工具名、结果、总耗时/上游耗时、图片数量/字节/像素、缓存命中、模型和错误类别，同时排除 base64、Credential、鉴权头和无界上游输出。 |
+| 模型上下文经济性 | Profile 级运行时只发布一个很小的引导工具，[`src/exposure.ts`](../../src/exposure.ts) 仅为加载 `vision-skills` 的 Agent 挂载 10 个执行 schema，并在成功后隐藏引导工具。其他 Agent 不受影响。健康检查、连接测试和版本诊断只存在于 Web Settings 边界，永远不会成为模型工具。单元测试覆盖 Agent 隔离与恢复；每条真实 Profile 工具流程都会断言初始和激活后的 schema 集合。 |
+| 可维护性 | 每个工具都调用同一个 [`VisionToolkitRuntime`](../../src/runtime.ts)；DSH 专用适配保留在 [`src/tools.ts`](../../src/tools.ts)、[`src/exposure.ts`](../../src/exposure.ts)、[`src/index.ts`](../../src/index.ts)、[`src/web.ts`](../../src/web.ts) 和 [`src/client/index.tsx`](../../src/client/index.tsx)，固定上游继续作为算法唯一来源。运行时就绪、skill/引导工具发布和 Agent 级 schema 属于同一个生命周期 generation。 |
+| HTML 截图隔离 | 固定截图 guard 使用一次性 Chrome Profile、`--use-mock-keychain` 和 `--incognito`，每次调用后删除 Profile，并保持网络禁用。[`tests/html-screenshot-guard.spec.ts`](../../tests/html-screenshot-guard.spec.ts) 捕获实际 argv 与清理行为。 |
+| UI 还原验收 | [`scripts/ui-restoration-example.ts`](../../scripts/ui-restoration-example.ts) 通过真实运行时执行参考页面 → HTML 渲染 → 像素差异。[`examples/ui-restoration/README.md`](../../examples/ui-restoration/README.md) 负责可复现流程与已提交证据；[`tests/ui-restoration-example.spec.ts`](../../tests/ui-restoration-example.spec.ts) 强制执行该契约。 |
+
+## 错误与生命周期场景
+
+| 场景 | 预期行为 | 证据 |
+|---|---|---|
+| 图片缺失/无效、格式、区域或路径错误 | 在执行上游前以输入、容量或路径安全错误拒绝 | [`tests/paths.spec.ts`](../../tests/paths.spec.ts)、[`tests/runtime.spec.ts`](../../tests/runtime.spec.ts) |
+| Credential 缺失 | 本地工具保持可用；远程工具以及显式 API 连接/真实模型测试返回脱敏且可执行下一步的配置/服务结果 | [`tests/runtime.spec.ts`](../../tests/runtime.spec.ts)、[`tests/web.spec.ts`](../../tests/web.spec.ts) |
+| 401/403、429、超时、畸形输出或取消 | 返回稳定且可执行下一步的类别，保留有界诊断信息，并停止请求/子进程 | [`tests/errors.spec.ts`](../../tests/errors.spec.ts)、[`tests/runtime.spec.ts`](../../tests/runtime.spec.ts)、[`tests/upstream.spec.ts`](../../tests/upstream.spec.ts) |
+| 初始加载时运行时不可用 | 不注册 skill、激活引导工具或 Agent 级工具；保留 Web Settings 以供修复 | [`src/index.ts`](../../src/index.ts)、[`tests/tools.spec.ts`](../../tests/tools.spec.ts) 与 [`tests/web.spec.ts`](../../tests/web.spec.ts) 中的生命周期测试 |
+| 实时更新时运行时候选失败 | 保留当前服务 generation 和已存储的可用配置 | [`tests/runtime-manager.spec.ts`](../../tests/runtime-manager.spec.ts)、[`tests/web.spec.ts`](../../tests/web.spec.ts) |
+| 并发 Settings 候选乱序完成 | 较新的 ticket 获胜；较慢的陈旧候选不能激活 | [`tests/runtime-manager.spec.ts`](../../tests/runtime-manager.spec.ts) |
+| 禁用、重新启用或卸载 | 取消插件拥有的活动调用，Agent 级工具、引导工具与 skill 作为一个生命周期单元一起消失和恢复，卸载会移除 Bundle layer | [`tests/tools.spec.ts`](../../tests/tools.spec.ts)、[`tests/profile-install.e2e.spec.ts`](../../tests/profile-install.e2e.spec.ts) |
+
+## P2 与 P3 边界
+
+| 范围 | 状态 | 决策 |
+|---|---|---|
+| P2 稳定 `ctx.visionToolkit` 服务与能力发现 | **按设计推迟** | 产品需求要求至少一个独立插件消费方出现后再稳定该 API。`VisionToolkitRuntime` 保持包内部使用，使 P0/P1 可以继续演进，而不会制造虚假的兼容性承诺。 |
+| P2 提供方生态 | **按设计推迟** | 本包支持固定上游，并通过 OpenAI Chat Completions 或 Anthropic Messages 使用一个已配置端点；不会预先构建无人使用的提供方注册表。 |
+| P3 探索性输入与自动化 | **范围外** | 上传/拖拽、摄像头/视频/音频/文档输入、交互式标注、自动点击、远程集群、模型路由/投票和跨 Session 缓存不属于本版本契约。 |
+
+## 可复现验证
+
+在 `dsh-vision-toolkit/` 中运行软件包检查：
+
+```sh
+pnpm run build
+pnpm test
+pnpm run example:ui-restoration
+pnpm pack --dry-run
+```
+
+发布验收还会运行仓库插件检查器，把软件包分别安装到干净的 Web 和 Headless `DSH_HOME`，检查 `--dump-config`，执行本地工具和由无真实 Key mock 支持的远程工具调用，验证 Settings 持久化与实时切换，检查专用 Web 卡片且确保浏览器 Console 无错误，禁用/重新启用插件行，最后移除软件包。这些运行时检查补充自动化测试，不替代自动化测试。

package/examples/ui-restoration/README.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/examples/ui-restoration/README.md
+README.md: 62aca8723a7f92e47d6803a553882e709fc870f5
+README.zh.md: 94b6ca7b43816d533d44a31d1fc853a23f63b3dd

package/examples/ui-restoration/README.md

@@ -0,0 +1,70 @@
+# UI restoration example
+
+English | [中文](README.zh.md)
+
+This example is a deterministic, keyless proof that DSH Vision Toolkit can close a local UI-restoration loop through its real runtime. It renders a reference page, an intentionally inaccurate first implementation, and the final implementation with `vision_html_screenshot`; it then evaluates both candidates with `vision_pixel_diff` and enforces numeric acceptance thresholds.
+
+## Flow
+
+1. `tests/fixtures/ui-restoration-reference.html` is copied into a temporary workspace as the reference source.
+2. `initial.html` and `implementation.html` are copied into the same workspace.
+3. The runtime renders all three local files at `1200 × 720` and scale `1` through the pinned Chrome-family adapter.
+4. The runtime compares the initial and final screenshots against the reference with an `8 × 8` grid and six ranked regions.
+5. Check mode verifies the committed evidence; write mode replaces it only after the initial and final thresholds pass.
+
+The runner uses the package's `VisionToolkitRuntime` and `UpstreamAdapter`, not a separate screenshot or image-diff implementation. It requires Python with Pillow and NumPy plus Chrome, Chromium, or Edge; it does not require a vision-service Credential.
+
+## Inputs and evidence
+
+| Path | Role |
+|---|---|
+| `initial.html` | Deliberately inaccurate reconstruction used to prove the comparison detects meaningful drift |
+| `implementation.html` | Final reconstruction expected to match the reference |
+| `assets/reference.png` | Browser-rendered reference image |
+| `assets/initial.png` | Browser-rendered initial reconstruction |
+| `assets/initial-heatmap.png` | Pixel-difference heatmap for the initial reconstruction |
+| `assets/initial-report.json` | Portable initial comparison report with relative image paths |
+| `assets/implementation.png` | Browser-rendered final reconstruction |
+| `assets/final-heatmap.png` | Pixel-difference heatmap for the final reconstruction |
+| `assets/final-report.json` | Portable final comparison report with relative image paths |
+| `assets/metrics.json` | Stable viewport and acceptance metrics used by check mode |
+
+![Reference](assets/reference.png)
+
+![Initial reconstruction](assets/initial.png)
+
+![Final reconstruction](assets/implementation.png)
+
+## Run
+
+From `dsh-vision-toolkit/`:
+
+```sh
+npm run example:ui-restoration
+```
+
+The command prints a structured result and exits non-zero when the environment, checked-in assets, or thresholds do not match the contract. The committed metrics are:
+
+```json
+{
+  "initialDifferencePct": 6.04,
+  "finalDifferencePct": 0,
+  "initialWorstRegions": 6,
+  "finalWorstRegions": 0
+}
+```
+
+The initial comparison must remain at least `1%` different so the example cannot pass with two equivalent fixtures. The final comparison must remain at or below `0.02%`, and the committed evidence currently records an exact `0%` difference.
+
+## Refresh evidence
+
+Run write mode only when intentionally changing the reference, reconstruction, viewport, renderer contract, or expected artifacts:
+
+```sh
+npm run example:ui-restoration:write
+npm run example:ui-restoration
+```
+
+Write mode renders into a temporary workspace, validates the thresholds, copies the approved PNGs and reports into `assets/`, rewrites report paths to portable relative paths, and updates `metrics.json`. The following check-mode run is the required confirmation that the committed package can reproduce the refreshed evidence.
+
+The automated regression test is `tests/ui-restoration-example.spec.ts`; the macOS Chrome keychain/profile isolation contract is independently covered by `tests/html-screenshot-guard.spec.ts`.

package/examples/ui-restoration/README.zh.md

@@ -0,0 +1,70 @@
+# UI 还原示例
+
+[English](README.md) | 中文
+
+本示例以确定性、无真实 Key 的方式证明 DSH Vision Toolkit 可以通过真实运行时闭环完成本地 UI 还原。它先用 `vision_html_screenshot` 渲染参考页面、故意不准确的初版实现和最终实现，再用 `vision_pixel_diff` 评估两个候选结果，并执行数值验收阈值。
+
+## 流程
+
+1. 将 `tests/fixtures/ui-restoration-reference.html` 复制到临时工作区，作为参考源文件。
+2. 将 `initial.html` 和 `implementation.html` 复制到同一工作区。
+3. 运行时通过固定 Chrome 系适配器，以 `1200 × 720`、缩放 `1` 渲染 3 个本地文件。
+4. 运行时使用 `8 × 8` 网格和 6 个排序区域，将初版和最终截图分别与参考图比较。
+5. Check 模式验证已提交证据；write 模式只在初版和最终阈值都通过后替换证据。
+
+Runner 使用本包的 `VisionToolkitRuntime` 和 `UpstreamAdapter`，不会另行实现截图或图片差异算法。它需要带 Pillow、NumPy 的 Python，以及 Chrome、Chromium 或 Edge；不需要视觉服务 Credential。
+
+## 输入与证据
+
+| 路径 | 作用 |
+|---|---|
+| `initial.html` | 故意不准确的还原结果，用于证明比较流程能检测有意义的偏差 |
+| `implementation.html` | 预期与参考页面匹配的最终还原结果 |
+| `assets/reference.png` | 浏览器渲染的参考图 |
+| `assets/initial.png` | 浏览器渲染的初版结果 |
+| `assets/initial-heatmap.png` | 初版结果的像素差异热力图 |
+| `assets/initial-report.json` | 使用相对图片路径的可移植初版比较报告 |
+| `assets/implementation.png` | 浏览器渲染的最终结果 |
+| `assets/final-heatmap.png` | 最终结果的像素差异热力图 |
+| `assets/final-report.json` | 使用相对图片路径的可移植最终比较报告 |
+| `assets/metrics.json` | Check 模式使用的稳定视口和验收指标 |
+
+![Reference](assets/reference.png)
+
+![Initial reconstruction](assets/initial.png)
+
+![Final reconstruction](assets/implementation.png)
+
+## 运行
+
+在 `dsh-vision-toolkit/` 中执行：
+
+```sh
+npm run example:ui-restoration
+```
+
+该命令会输出结构化结果；环境、已提交资源或阈值不符合契约时以非零状态退出。已提交指标如下：
+
+```json
+{
+  "initialDifferencePct": 6.04,
+  "finalDifferencePct": 0,
+  "initialWorstRegions": 6,
+  "finalWorstRegions": 0
+}
+```
+
+初版差异必须保持在 `1%` 以上，避免两个等价 fixture 让示例失去检测意义。最终差异必须不高于 `0.02%`；当前已提交证据记录精确的 `0%` 差异。
+
+## 刷新证据
+
+只有有意修改参考页面、还原页面、视口、渲染器契约或预期产物时，才运行 write 模式：
+
+```sh
+npm run example:ui-restoration:write
+npm run example:ui-restoration
+```
+
+Write 模式会在临时工作区中渲染，验证阈值，把通过验收的 PNG 和报告复制到 `assets/`，将报告路径改写为可移植相对路径，并更新 `metrics.json`。随后必须执行 check 模式，确认已提交软件包可以复现刷新后的证据。
+
+自动回归测试位于 `tests/ui-restoration-example.spec.ts`；macOS Chrome 钥匙串/Profile 隔离契约由 `tests/html-screenshot-guard.spec.ts` 独立覆盖。

package/examples/ui-restoration/assets/final-report.json

@@ -0,0 +1,83 @@
+{
+  "schemaVersion": 1,
+  "sourceTool": "vision_pixel_diff",
+  "original": {
+    "path": "assets/reference.png",
+    "bytes": 137315,
+    "width": 1200,
+    "height": 720,
+    "format": "png"
+  },
+  "rebuilt": {
+    "path": "assets/implementation.png",
+    "bytes": 137315,
+    "width": 1200,
+    "height": 720,
+    "format": "png"
+  },
+  "scaled": false,
+  "overallDifferencePct": 0,
+  "grid": 8,
+  "worstRegions": [
+    {
+      "index": 1,
+      "differencePct": 0,
+      "box": {
+        "x1": 1050,
+        "y1": 630,
+        "x2": 1200,
+        "y2": 720
+      }
+    },
+    {
+      "index": 2,
+      "differencePct": 0,
+      "box": {
+        "x1": 1050,
+        "y1": 540,
+        "x2": 1200,
+        "y2": 630
+      }
+    },
+    {
+      "index": 3,
+      "differencePct": 0,
+      "box": {
+        "x1": 1050,
+        "y1": 450,
+        "x2": 1200,
+        "y2": 540
+      }
+    },
+    {
+      "index": 4,
+      "differencePct": 0,
+      "box": {
+        "x1": 1050,
+        "y1": 360,
+        "x2": 1200,
+        "y2": 450
+      }
+    },
+    {
+      "index": 5,
+      "differencePct": 0,
+      "box": {
+        "x1": 1050,
+        "y1": 270,
+        "x2": 1200,
+        "y2": 360
+      }
+    },
+    {
+      "index": 6,
+      "differencePct": 0,
+      "box": {
+        "x1": 1050,
+        "y1": 180,
+        "x2": 1200,
+        "y2": 270
+      }
+    }
+  ]
+}