deepseek-harness-intelligent-ui 0.2.3 → 0.2.4

package/README.zh-CN.md

@@ -11,7 +11,7 @@
 [![OS](https://img.shields.io/badge/OS-Windows%20%7C%20Linux%20%7C%20macOS-a78bfa)](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/main/docs/compatibility.md)
 [![License: MIT](https://img.shields.io/badge/license-MIT-97a1c9)](LICENSE)
 
-[演示](#-演示) · [快速开始](#-快速开始) · [如何选择](#-agent-如何选择呈现方式) · [沙箱组件](#-沙箱组件ui_render_widget) · [安全](#-安全模型) · [配置](#%EF%B8%8F-配置) · [开发](#-开发与验证)
+[演示](#-演示) · [质量](#-真实模型质量基线) · [快速开始](#-快速开始) · [如何选择](#-agent-如何选择呈现方式) · [沙箱组件](#-沙箱组件ui_render_widget) · [安全](#-安全模型) · [配置](#%EF%B8%8F-配置) · [开发](#-开发与验证)
 
 </div>
 
@@ -72,36 +72,60 @@ JSON 还在生成，组件就已出现。实时组件在**同一个** iframe 中
 
 ## 🎬 演示
 
-![DeepSeek Harness Intelligent UI 演示](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/v0.2.1/docs/assets/demo.gif)
+### 真实 DeepSeek 模型，端到端
 
-🎥 **高清视频（H.264，约 2 分钟）：** [docs/assets/demo.mp4](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/v0.2.1/docs/assets/demo.mp4)
+https://github.com/user-attachments/assets/e4eb0adc-659e-4c80-b473-449aa42ca00f
+
+<details>
+<summary><b>🎞️ GIF 精选片段</b>（适用于无法播放视频的页面，如 npm）</summary>
+<br>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/main/docs/assets/real-model/demo.gif" alt="真实 deepseek-flash 模型在 DSH Web 中的表现，由鲸鱼娘解说：表单回传、带滑块的阻尼振动 Plot、用 ui_patch 两轮原位修改图表" width="100%">
+</p>
+
+</details>
+
+<img align="right" width="120" src="https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/main/scripts/eval/demo/assets/whale/greet.webp" alt="担任演示解说的 DeepSeek 鲸鱼娘">
+
+🎥 **完整视频（H.264，2 分 27 秒，9.5 MB）：** [docs/assets/real-model/demo.mp4](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/main/docs/assets/real-model/demo.mp4)。视频覆盖全部 11 个浏览器用例，每一章都停在真实结果上：纯文本、图表、数据表、表单回传、Plot、Three.js 与「让模型修复」、停止 → 重新生成、两轮原位修改、Fast 3G、CDN 不可达、手机宽度。由 DeepSeek 鲸鱼娘解说，立绘来自 [dsh-whale-musume](https://github.com/Sutera-Diffusus/dsh-whale-musume)（MIT，见[致谢](#致谢)）。
 
 > [!NOTE]
-> 演示视频录自真实的 DSH Web 0.2.0-rc.1，装好本插件后由 `npm run e2e:all -- --record` 自动驱动。背后的模型是 `scripts/e2e/` 中的**脚本化 mock**（当时没有 API Key），回答内容是预设的。画面中的流式渲染、交互、双向通信、持久化和隔离，都是插件在 DSH 中真实运行的结果。
+> 2026-10-16 由 `npm run eval:real -- --stage browser --record` 录制，`npm run eval:demo` 剪辑合成。每张卡片都是真实 **`deepseek-flash`** 模型在装有本插件的真实 **DSH Web 0.2.0-rc.1** 里当场生成的。没有任何脚本回放，**失败也原样保留**：每章标题卡都标出 ✓ 或 ✗，解说会说明哪里出了问题。模型生成期间视频加速播放，右下角秒表显示真实耗时。评测结果见[真实模型质量基线](#-真实模型质量基线)。
+
+| 多系列柱状图：**✗**（调用中途被截断） | `ui_patch` 两轮原位修改：✓ |
+|:---:|:---:|
+| ![图表](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/main/docs/assets/real-model/chart.png) | ![原位修改](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/main/docs/assets/real-model/patched.png) |
+| *图表内容正确，但卡片显示「生成已中断」：还有组件没生成完* | *「改成折线图」→「加上小程序 30/45/60/80」：同一张卡片，第 3 版，数值准确* |
+| **提交表单 → 模型使用提交的值：✓** | **阻尼振动 `Plot`，滑块实时重绘：✓** |
+| ![表单回传](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/main/docs/assets/real-model/form-followup.png) | ![Plot](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/main/docs/assets/real-model/plot.png) |
+| *提交的 全国 / 4 / 乐观 生成了季度预测* | *y = A·e^(−γt)·cos(ωt) 及包络线；拖动滑块不调用模型* |
+| **Three.js：✗，再由「让模型修复」修好** | **中途停止 → 重新生成：✓** |
+| ![Three.js 修复后](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/main/docs/assets/real-model/three-repaired.png) | ![重新生成](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/main/docs/assets/real-model/regenerated.png) |
+| *首次生成报错 `view is not defined`；修复后球心 (0,0,R)，带坐标轴* | *中断的卡片保留静态预览，「重新生成」得到完整场景* |
+| **Fast 3G、禁用缓存：✓** | **CDN 不可达：✓（按设计降级）** |
+| ![弱网络](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/main/docs/assets/real-model/weak-network.png) | ![无网络](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/main/docs/assets/real-model/offline.png) |
+| *three.js 加载变慢，但仍正常渲染* | *失败直接显示在卡片上，对话不受影响* |
+| **手机宽度（390 px）：✓** | **可排序数据表：✗（5 分钟内没出表）** |
+| ![移动端](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/main/docs/assets/real-model/mobile.png) | ![数据表](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/main/docs/assets/real-model/table.png) |
+| *无溢出，指标与图表都能放下* | *Agent 把时间都花在上网查车型参数上* |
 
 <details>
-<summary><b>📸 截图集</b>（看板、Three.js、公式、表单、流式预览、深色主题、手机、刷新）</summary>
+<summary><b>🧪 脚本化模型演示</b>（插件管线 E2E：深色主题、刷新恢复、沙箱隔离）</summary>
 <br>
 
-| 看板流式出现并定稿 | Three.js 组件：R 滑块、旋转、缩放 |
-|:---:|:---:|
-| ![看板](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/v0.2.1/docs/assets/screenshots/3-dashboard.png) | ![球面](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/v0.2.1/docs/assets/screenshots/7-widget-rotated.png) |
-| *指标卡、栅格、标签页、带悬停提示的堆叠柱状图、可排序表格、时间线、表单* | *用 `UI.three()` 绘制 `x²+y²+z²=2Rz`，拖动滑块在本地即时改变曲面* |
+![DeepSeek Harness Intelligent UI 脚本化模型演示](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/v0.2.1/docs/assets/demo.gif)
 
-| 公式、实时函数图像、Mermaid | 表单 → Agent → 新界面 |
-|:---:|:---:|
-| ![数学](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/v0.2.1/docs/assets/screenshots/9-math.png) | ![表单](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/v0.2.1/docs/assets/screenshots/4-form-sent.png) |
+🎥 [docs/assets/demo.mp4](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/v0.2.1/docs/assets/demo.mp4)。由 `npm run e2e:all -- --record` 录制，背后是 `scripts/e2e/` 中的**脚本化 mock**，回答内容是预设的。它展示的是插件管线（流式、渲染、双向通信、持久化、隔离），不代表真实模型的表现。
 
-| 流式预览（同一个 iframe 直接定稿） | 生成中途停止 |
+| 看板流式出现并定稿 | Three.js 组件：R 滑块、旋转、缩放 |
 |:---:|:---:|
-| ![预览](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/v0.2.1/docs/assets/screenshots/5-widget-preview.png) | ![停止](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/v0.2.1/docs/assets/screenshots/10-stopped.png) |
+| ![看板](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/v0.2.1/docs/assets/screenshots/3-dashboard.png) | ![球面](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/v0.2.1/docs/assets/screenshots/7-widget-rotated.png) |
 
 | 深色主题 | 手机宽度（深色） | 刷新后恢复 |
 |:---:|:---:|:---:|
 | ![深色](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/v0.2.1/docs/assets/screenshots/11b-dark-widget.png) | ![移动端](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/v0.2.1/docs/assets/screenshots/12-mobile-dark.png) | ![刷新](https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/v0.2.1/docs/assets/screenshots/14-reload.png) |
 
-**在 GitHub 内联播放：** 把 `docs/assets/demo.mp4` 拖进 GitHub 的评论或 Release 编辑框，再把生成的 `https://github.com/user-attachments/assets/…` 链接单独一行粘贴到这里。GitHub 只对上传的附件内联播放视频，不支持仓库内的文件。
-
 </details>
 
 ## 🚀 快速开始
@@ -125,7 +149,7 @@ npx deepseek-harness-intelligent-ui doctor             # 只诊断，不做修
 |---|---|
 | 升级 | `dsh plugin --profile web add deepseek-harness-intelligent-ui@latest` |
 | 试用预发布版（仅在存在 `next` 标签时） | `dsh plugin --profile web add deepseek-harness-intelligent-ui@next` |
-| 固定版本 | `dsh plugin --profile web add deepseek-harness-intelligent-ui@0.2.3` |
+| 固定版本 | `dsh plugin --profile web add deepseek-harness-intelligent-ui@0.2.4` |
 | 卸载 | `dsh plugin --profile web remove deepseek-harness-intelligent-ui`（或 `npx deepseek-harness-intelligent-ui uninstall`） |
 | 从源码目录安装 | `dsh plugin --profile web add file:/path/to/deepseek-harness-intelligent-ui` |
 
@@ -168,6 +192,7 @@ CI 每天定时在 Windows、Linux、macOS 上跑完整矩阵，DSH 一发新版
 | 工具 | 适用场景 | 渲染方式 |
 |---|---|---|
 | `ui_render` | 结构化回答 | 固定目录中的原生 React 组件，随 JSON 流式渐进渲染 |
+| `ui_patch` | 修改之前显示的界面 | 对该界面做组件级操作，未改动的组件保留交互状态（[详情](#-原位增量更新ui_patch)） |
 | `ui_render_widget` | 自定义可视化、三维、模拟、小应用 | 不透明源沙箱 iframe 中的 HTML/CSS/JS：先 CSS，再实时 morph HTML，最后执行 JS，全程**一个** iframe |
 
 ## 🧩 组件目录（`ui_render`）
@@ -189,6 +214,18 @@ CI 每天定时在 Windows、Linux、macOS 上跑完整矩阵，DSH 一发新版
 
 **`Math` 与 `Mermaid` 的渲染：** 两者在与组件相同的沙箱中，从 CDN 白名单加载 KaTeX 或 Mermaid。第三方代码不在 DSH 页面中运行，宿主包体积保持在约 127 KB。CDN 不可用时，显示源码文本。
 
+## 🔁 原位增量更新（`ui_patch`）
+
+用户要求修改之前显示的界面时（例如“把柱状图换成折线图，其余不变”），Agent 按组件 id 打补丁，不必重新发送整棵组件树。
+
+- **标识：** 每次 `ui_render` 的结果都会告诉模型该界面的 `uiId`（即其调用 id）和版本号 1。每次补丁被接受后，结果会给出新版本号和组件的 `id:类型` 概览。
+- **操作：** `setProps`（合并属性，`unset` 删除属性）、`replaceNode`（保留 id，替换类型、属性或子节点）、`insertChild`（在容器下插入新组件）、`removeNode`。操作按顺序执行，**要么全部生效，要么全部不生效**。生成的新版本还要通过与全新 `ui_render` 相同的完整校验（类型、属性、引用、成环、深度、规模、Tabs 标签数）。
+- **并发：** `baseVersion` 为必填项。基于旧版本的补丁会作为过期请求被拒绝，并告知当前版本，模型据此重新生成补丁后重试。补丁始终独占执行、不会并行，因此版本构成一条有序链。
+- **作用范围：** Host 不保存任何状态，而是重放本会话自己的历史（先是被接受的 render，再是被接受的 patch）来重建当前版本，所以补丁只能作用于同一会话中的界面。未知 id、其他会话的界面，以及因上下文压缩而不可见的界面都会被拒绝，此时模型改用 `ui_render`。
+- **交互状态：** 组件 id 在各版本间保持不变，交互状态按 `uiId` + 组件 id 保存。补丁未替换的组件都会保留表格排序、选中的标签页、表单输入、已提交锁定和 `Plot` 滑块位置。被 `replaceNode` 替换的组件状态重置；要重置任意组件，换一个新 id 即可。补丁新增的表单字段使用默认值。
+- **显示：** 补丁在流式生成或执行时，卡片只显示一行“正在更新界面…”，上一版本保持可用，绝不会出现改了一半的界面。成功后，新版本显示在新回复下方，旧副本收起为“已更新为第 N 版”。被拒绝、失败或中断的补丁不会改动上一版本。完整快照保存在持久化的工具结果元数据中，刷新页面后显示的就是最新版本。
+- **沙箱组件**（`ui_render_widget`）暂不支持打补丁：Agent 会重新渲染它，重新渲染时 `UI.state` 依然保留。
+
 ## 🪟 沙箱组件（`ui_render_widget`）
 
 <img src="https://raw.githubusercontent.com/dreamfarer-space/deepseek-harness-intelligent-ui/main/docs/assets/readme/widget-streaming.zh.svg" alt="组件字段按顺序流式到达：先显示占位，再实时 morph 预览，最后在同一个 iframe 中定稿并执行代码" width="100%">
@@ -222,7 +259,7 @@ CI 每天定时在 Windows、Linux、macOS 上跑完整矩阵，DSH 一发新版
 - **显示位置：**
   - 回合进行中，UI 在工具调用处内联显示。从准备、执行到结果，始终是同一个组件实例，交互状态不会丢。
   - 回合结束后，插件通过 `conversation.chat.turnTail` 把 UI **重新显示在回复下方**，内联处改为一行提示。
-- **按工具调用保存的交互状态：** 当前标签页、表格排序、表单值、已提交锁定、Plot 滑块、组件控件值、`UI.state`、iframe 高度。这些状态保存在内存和 `localStorage` 中（有容量上限），移到回复下方或刷新页面后都会恢复。UI 本身则从持久化的会话日志重建。
+- **按界面保存的交互状态**（以工具调用为单位，打过补丁的各版本共用原 `ui_render` 调用的状态）：当前标签页、表格排序、表单值、已提交锁定、Plot 滑块、组件控件值、`UI.state`、iframe 高度。这些状态保存在内存和 `localStorage` 中（有容量上限），移到回复下方或刷新页面后都会恢复。UI 本身则从持久化的会话日志重建。
 - **中途停止：**
   - 已进入会话日志的调用：保留已完成的部分（组件的静态预览，或已生成的组件），并显示提示和“重新生成”按钮。
   - 参数仍在流式输出时就被停止的调用：DSH 会整体丢弃它。插件会暂存已生成的内容，同样在被停止的回合下方显示。
@@ -251,7 +288,7 @@ CI 每天定时在 Windows、Linux、macOS 上跑完整矩阵，DSH 一发新版
 
 | 配置项 | 默认值 | 含义 |
 |---|---|---|
-| `enableCatalog` | `true` | 注册 `ui_render` |
+| `enableCatalog` | `true` | 注册 `ui_render` 和 `ui_patch` |
 | `enableWidget` | `true` | 注册 `ui_render_widget` |
 | `injectGuidance` | `true` | 注入“何时使用 UI”的系统提示 |
 | `cdnAllowlist` | esm.sh、jsdelivr、unpkg | 组件（以及 Math/Mermaid）可加载资源的来源 |
@@ -268,11 +305,12 @@ npm install
 npm run build
 npm test                      # 单元/组件测试（含 DSH 兼容性检查与安装器 CLI）
 npm run typecheck
-npm run e2e:all               # 构建 → 安装到临时 DSH 目录 → mock 模型 + 真实 DSH Web → 24 项浏览器检查
+npm run e2e:all               # 构建 → 安装到临时 DSH 目录 → mock 模型 + 真实 DSH Web → 30 项浏览器检查
 npm run e2e:all -- --record   # 同时重新录制 docs/assets/demo.mp4 / demo.gif（需要 ffmpeg）
 npm run e2e:all -- --spec ./deepseek-harness-intelligent-ui-<版本>.tgz   # 改为对 npm pack 打出的包做 E2E
 npm run smoke -- --spec ./deepseek-harness-intelligent-ui-<版本>.tgz     # 安装冒烟测试（不需要浏览器）
 npm run docs:art              # 重新生成 docs/assets/readme/ 下的 README 动画插图
+npm run eval:real             # 真实模型质量基线（需要 DEEPSEEK_API_KEY），见下文
 ```
 
 E2E 可以在 Windows、Linux、macOS 上运行。它会按平台自动查找 Chrome（可用 `CHROME_PATH` 指定），`DSH_BIN` 可指定其他 `dsh` 可执行文件。检查项见 `scripts/e2e/browser.mjs`，最近一次报告在 [`docs/e2e-report.json`](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/v0.2.1/docs/e2e-report.json)。GitHub Actions 会在三个系统上，针对每个受支持的 DSH 版本跑完全部测试。
@@ -296,32 +334,102 @@ E2E 可以在 Windows、Linux、macOS 上运行。它会按平台自动查找 Ch
 
 </details>
 
-<details>
-<summary><b>🤖 真实模型评测</b></summary>
-<br>
+## 📊 真实模型质量基线
 
-API 测试套件覆盖 15 个提示词，检查模型路由、工具参数格式，以及部分指定组件和数据。它**不会在浏览器中执行模型生成的组件**，也不验证数据事实、视觉质量、物理正确性或交互行为。独立浏览器 E2E 使用脚本化模型回复。
+工具调用的参数能解析，不等于用户真正拿到了可用、正确的界面。`npm run eval:real` 把三层结果**分开**统计，任何一层通过都不能代替另一层：
 
-仓库保留的[历史报告](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/v0.2.1/docs/real-model-eval-report.json)来自旧判分器，其中 15/15 不能作为当前通过率：B3 没有 Chart，却被判为通过。报告已标注此问题；其他用例需在新规则下重新运行，不能据此继续宣称全量通过。
+| 层 | 证明什么 | 最新 · 2026-10-16 · `deepseek-flash` |
+| --- | --- | :---: |
+| **Mock E2E** | 渲染、流式、交互、持久化与隔离（模型回答是**脚本化**的） | **30 / 30** |
+| **真实模型 · API** | 模型选对工具、**首次**就给出合法参数、渲染出的界面包含所要求的组件和数据。模型看到的是插件真实的工具与引导，并执行工具自身的 `execute()`（含 `ui_patch`） | **30 / 32**（94%） |
+| **真实模型 · 浏览器** | 模型生成的界面在真实 DSH Web + Chrome 中真正可用：能渲染、能交互、经得起停止/恢复和弱网，控制台无错误 | 自动化 **9 / 11**<br>人工复核后 **8 / 11** |
 
-新版要求组件可从根节点到达，B2 必须有可排序表格，B3 必须有四季度多系列柱状图，B4 表单必须有滑块和复选框，原生 C2 Plot 必须有参数滑块。多轮测试会校验所有工具调用并逐个回复，要求后续内容包含提交的 APAC、4 个季度和乐观情景，并核对三个型号的屏幕尺寸及原表格数据。这些自动断言不代表完整质量评估。
+| 耗时（真实模型） | p50 | p95 |
+| --- | ---: | ---: |
+| 首次出现可见预览（浏览器） | 7.6 s | 70.2 s |
+| 界面生成完成（浏览器） | 11.8 s | 73.4 s |
+| 流结束后的浏览器端执行（组件代码、从 CDN 加载 three.js） | 26 ms | 2.9 s |
+| 单次模型 API 调用 | 2.4 s | 75.7 s |
 
-运行前设置环境变量 `DEEPSEEK_API_KEY`，不再读取固定路径的凭据文件：
+长尾来自体积较大的 Three.js 组件：模型要先写出 10–20 KB 代码，预览才会开始。
+
+**本次评测发现的问题。** 以下都是模型与 Agent 的真实行为，不是评测噪声，每一条都对应[完整报告](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/main/docs/real-model-eval.md)中失败或被标注的用例：
+
+- **工具调用中途被截断（R-chart）：** 图表本身渲染正确，但这一轮在还有组件流式生成时就结束了。插件正确地把卡片降级为「生成已中断，以下为已完成的部分」，并提供「重新生成」。自动化内容检查通过了，但人工复核判为失败；现在新增的检查会让任何留下中断卡片的用例失败。
+- **Agent 去查资料而不是出界面（R-table）：** DSH 的 Agent 把 5 分钟预算全花在上网查车型参数上（20 步，约 130 万 token），始终没有渲染出表格。
+- **Three.js 作用域错误：** 两次录制，出现同一类错误的两种形式：本次是 `view is not defined`，上次是 `THREE is not defined`，都是组件代码在作用域之外使用了变量。卡片上标出「1 个脚本错误」，两次都是用户点击 **「让模型修复」** 后得到了正常场景。
+- **首次参数无效（API）：** 嵌套 `props` 漏写右花括号（D2，两轮都出现），以及组件 id 重复（B1）。插件会拒绝这些调用，模型重试后能改对，但用户会短暂看到一张被拒绝的卡片，所以这些用例算作失败。
+- **界面之外的 Agent 行为：** DSH 的 Agent 可能先搜索工作区、先反问用户，或派子智能体查资料。浏览器阶段会像真实用户一样回答反问（选推荐项），并等待界面本身出现，而不只是等这一轮结束。
+
+<details>
+<summary><b>▶️ 如何运行</b></summary>
+<br>
+
+把密钥放进环境变量。不会读取任何凭据文件；如果报告里仍含有密钥，运行会拒绝写出报告。
 
 ```sh
-export DEEPSEEK_API_KEY='<你的密钥>'
-node scripts/run-real-model-suite.mjs all   # 可选 A、B、C、D 或 all
+export DEEPSEEK_API_KEY='<your-key>'          # PowerShell：$env:DEEPSEEK_API_KEY = '<your-key>'
+npm run eval:real                              # Mock E2E + API + 浏览器；任何失败都以退出码 1 结束
+npm run eval:real -- --repeat 3                # 每个 API 用例跑 3 次 → 单用例成功率与 p50/p95
+npm run eval:real -- --record && npm run eval:demo   # 同时录制并剪辑演示视频
+npm run eval:gallery                           # 把 README 截图统一排版为 1200×750
 ```
 
-```powershell
-$env:DEEPSEEK_API_KEY = '<你的密钥>'
-node scripts/run-real-model-suite.mjs all
-```
+| 选项 | 作用 |
+| --- | --- |
+| `--stage mock,api,browser` | 只运行部分层（默认 `all`）。仍可用 `A`/`B`/`C`/`D` 选择 API 类别。 |
+| `--only B3,R-chart` | 只运行这些用例。 |
+| `--keep-other-layers` | 保留本次没有运行的层（配合 `--only` 时保留其他用例），各自保留原来的日期。 |
+| `--append` | 配合 `--only`：把重跑结果作为额外样本加入，绝不用一次侥幸成功覆盖失败。 |
+| `--rescore` | 用当前断言、基于已保存的对话记录重新判定上一次 API 运行，不调用模型。 |
+| `DEEPSEEK_EVAL_MODEL` | 模型 id（默认 `deepseek-flash`）。 |
 
-每次仅将本次用例写入 `docs/real-model-eval-report.json`，分类运行不混入旧结果。断言或 API 请求失败时返回退出码 1；类别错误或密钥缺失会在改写报告前退出。请勿将密钥提交到 git。
+GitHub 上的 **Real-model eval** 工作流可按需手动触发，使用仓库密钥 `DEEPSEEK_API_KEY` 运行同一条命令，并上传报告和截图。用 `deepseek-flash` 完整跑一遍约花费 ¥1.5。
 
 </details>
 
+<details>
+<summary><b>🔬 每个用例检查什么</b></summary>
+<br>
+
+**API 阶段**（`scripts/eval/api-stage.mjs`，16 个用例，断言 v3）。每条要求单独成为一项检查，报告会写明具体是*哪一条*失败：
+
+- **纯文本（A1–A4）：** 不调用任何界面工具，给出有内容的回答。
+- **图表与数据表（B1–B3、B5）：**
+  - 按含义识别的指标卡（收入、活跃用户（含月活/MAU）、转化率、客单价）；
+  - 包含全部五个所需列的可排序表格；
+  - **含 Q1–Q4、且同时有线上与线下两个系列的柱状图**（2026-10-10 那份 B3 回答只有表单、没有图表，现作为测试夹具保留，必须判为失败）；
+  - 至少 4 个里程碑的时间线（`Timeline`，或包含 4 个以上按序年份的 Mermaid 图）。
+- **表单（B4、D1）：** 包含滑块、复选框和下拉选择。D1 按浏览器的方式提交表单，并要求后续回答使用提交的区域、季度数和情景。
+- **数学 Plot（C2）：** 三个滑块，*每个滑块都出现在表达式中*，函数形状为 `exp(…)·sin/cos(…)`。
+- **Three.js 与组件（C1、C3、C4）：** 使用 `UI.three()`/`import("three")`，有动画、光照、启动/暂停和参数控件。
+- **多轮修改：** D2 新增一列，每款机型的值都正确，旧值全部保留。D3 连续修改两次（柱状 → 折线，再按准确数值加入第三个系列，原系列不变）。是否用 `ui_patch` 原位修改也会记录。
+
+每个用例都记录：工具选择、首次 Schema 是否有效与是否恢复、每次调用的 API 耗时、API 返回的模型 id 与 `system_fingerprint`，以及提示词哈希。
+
+**浏览器阶段**（`scripts/eval/browser-stage.mjs`，11 个用例，每个都在新会话中运行）：
+
+- **纯文本：** 不创建任何卡片。
+- **图表：** 有图例、Q1–Q4、至少 8 根柱子，本地悬停提示。
+- **数据表：** 点击表头重新排序，不调用模型。
+- **表单：** 用真实鼠标和键盘填写并提交；后续回答必须提到提交的值；表单随后锁定。
+- **Plot：** 拖动滑块会重绘曲线。
+- **Three.js：** 画布**确实绘制了内容而非空白**（像素统计），拖动会改变画面，且没有组件脚本错误。失败时会尝试「让模型修复」并报告结果。
+- **停止/恢复：** 中途停止 → 静态预览、提示和「重新生成」→ 完整场景。
+- **两轮原位修改：** 只有一张活跃卡片，第 3 版，折线图，第三个系列。
+- **弱网络：** Fast 3G，禁用缓存。
+- **无网络：** 屏蔽 CDN；失败必须显示在卡片上，DSH 页面不能有未捕获错误，对话必须能继续。
+- **手机宽度（390 px）：** 无溢出；指标网格最多 2 列。
+
+每个用例还会记录控制台错误，并区分宿主页面和组件 iframe。额度用尽等 DSH 运行失败记为*基础设施*错误，不计入模型成功率。
+
+自动化检查无法评判视觉质量，所以报告还附有对每张截图的**抽样人工复核**。
+
+</details>
+
+> [!IMPORTANT]
+> [2026-10-10 的报告](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/main/docs/history/2026-10-10-real-model-eval-report.json)（15/15）只是**历史快照**，不是通过率。它出自一个只检查 API 的旧判分器：B3 没有渲染出图表却被判为通过，而且没有保存重新判分所需的参数。当前结果见 [`docs/real-model-eval.md`](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/main/docs/real-model-eval.md)（可读版）和 [`docs/real-model-eval-report.json`](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/blob/main/docs/real-model-eval-report.json)。
+
 ## 已知限制
 
 - 沙箱组件、`Math` 和 `Mermaid` 需要能访问 CDN 白名单。离线时，`Math` 和 `Mermaid` 退回显示源码，`UI.three` 会报告脚本错误。
@@ -331,3 +439,5 @@ node scripts/run-real-model-suite.mjs all
 ## 致谢
 
 概念、流式组件协议和部分提示词来自 [CopilotKit/OpenIntelligentUI](https://github.com/CopilotKit/OpenIntelligentUI)（MIT 许可）。本项目采用 MIT 许可。
+
+**演示视频中的鲸鱼娘。** 担任视频解说的 DeepSeek 鲸鱼娘（共 26 个姿态）来自 [Sutera-Diffusus/dsh-whale-musume](https://github.com/Sutera-Diffusus/dsh-whale-musume)（MIT © Sutera-Diffusus，立绘作者 [@SuteraWu](https://github.com/SuteraWu)）。原始文件及其许可证见 [`scripts/eval/demo/assets/whale/`](https://github.com/dreamfarer-space/deepseek-harness-intelligent-ui/tree/main/scripts/eval/demo/assets/whale)，不包含在 npm 包中。

package/THIRD_PARTY_NOTICES.md

@@ -23,3 +23,11 @@ Copyright (c) Big Sky Software. Permission to use, copy, modify, and/or distribu
 ## React — MIT License
 
 React is provided at runtime by the DSH Web shell. It is not bundled.
+
+## dsh-whale-musume whale-girl illustrations (demo video only) — MIT License
+
+https://github.com/Sutera-Diffusus/dsh-whale-musume
+
+26 unmodified illustrations in `scripts/eval/demo/assets/whale/` narrate the demo video and GIF in `docs/assets/real-model/`. They are not included in the npm package. The full licence text is in `scripts/eval/demo/assets/whale/LICENSE`.
+
+Copyright (c) 2026 Sutera-Diffusus. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, subject to the condition that the above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.