@runweave/server-linux-x64 0.1.24 → 0.1.25

package/payload/plugins/toolkit/skills/acceptance/references/gallery-contract.md

@@ -1,20 +1,38 @@
-# 图文材料数据合同 v1
+# 图文材料与验收报告数据合同
 
-## 输入
+## 输入与兼容
 
 UTF-8 JSON，拒绝重复键、未知字段、NaN 和未知版本。文件路径相对 `--input-root`；`--input` 默认 `task.json`。根目录必须已存在。ID 为 1–80 位字母、数字、`-`、`_`，首位为字母或数字。
 
+新报告使用 `schemaVersion: 2`。旧版 `schemaVersion: 1` 输入继续支持，不修改历史产物，也不根据旧页的 observed 自动推导通过结论。v1 不接受 report 或 item.summary；升级时必须按实际记录补齐报告，不能仅改版本号。
+
 | 对象   | 字段                                                                                                                               |
 | ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
-| root   | `schemaVersion: 1`、`task`、`assets: []`、`pages: []`                                                                              |
+| root   | `schemaVersion: 1/2`、`task`、`assets: []`、`pages: []`；v2 必须有 `report`                                                        |
 | task   | `id`、`title`、`scope`、`materialKind: current/historical`、`limitations: string[]`                                                |
 | asset  | 唯一 `id`、`kind: image/text`、`path`、`label`、`origin`                                                                           |
 | origin | `surface`、`capturedAt`、`sourceRef`，每项为非空字符串或 `null`                                                                    |
 | page   | 唯一 `id`、`type`、`title`、`description`、`evidenceState`、`items`、`sourceIds: string[]`；可选 `lookAt`、`limitations: string[]` |
-| item   | `assetId`、`label`；图片项必需 `alt`，可选 `crop: {x,y,width,height}`；文字项不接受 alt/crop                                       |
+| item   | `assetId`、`label`；图片项必需 `alt`，可选 `crop: {x,y,width,height}`；v2 文字项可选 `summary`，不接受 alt/crop                    |
+| report | `summary`、非空数组 `checks`                                                                                                       |
+| check  | 唯一 `id`、`title`、`expected`、`actual`、`execution`、`outcome`、`pageIds: string[]`                                              |
 
 文字必填项须为非空字符串。时间按实际采集记录填写，建议带时区 ISO 8601；不知道则 `null`。版本、设备、对象身份等条件写在 scope、description 或关联文字记录中，`sourceRef` 给其原始位置或记录标识。各素材允许不同来源，但不能因此宣称同一事件。
 
+## 验收项与首屏总览（v2）
+
+- `report.summary`：作者写的一段总体判断及关键保留条件；只总结本次真实记录，不由生成器计算“整体通过”。task.limitations 直接可见，不折叠关键边界。
+- 每项 check 对应一个可判断的用户目标。`expected` 写标准，`actual` 写操作后观察或未执行/阻塞原因。不要把“桌面 UI 检查”和“真机扫码成功”合为一项再统一标通过。
+- `execution` 为 `real`（实际执行）、`mock`（确实在 Mock/模拟环境执行）、`not-run`（没有执行）。没有证据不能凭空改称 Mock；运行端及浏览器模拟/真机的具体边界仍需写明。
+- `outcome` 为 `pass`、`fail`、`blocked`、`not-run`，是报告作者记录的**自检结果**，不代表用户验收确认。实际执行后观察到不符合标准可记 fail；无法得出结果时记 blocked 并说明原因。
+- `pageIds` 只引用本报告已有证据页且不重复，可为空。pass/fail 必须关联至少一页 observed；pass 不可引用 insufficient/not-run 的页作为支持。not-run 结果只能配 not-run 执行；未执行不能标 pass/fail。
+- 失败、阻塞、未执行项在总览中优先且默认展开；通过项显示标题及执行方式，按需展开预期、实际和证据链接。是否有图不影响缺口的可见性。
+- v2 允许 `pages: []`、`assets: []`，用于只有阻塞或未执行项的报告，不要求制造截图或无意义文字文件。v1 仍至少需要一页。
+
+校验只检查结构、引用和显式状态是否自洽，无法判定截图真假、目标是否遗漏或作者结论是否正确。报告必须覆盖本次约定的目标，包括没有执行的部分；不能仅列成功项。
+
+## 证据页与素材
+
 | type     | items 数量 | 素材 kind |
 | -------- | ---------- | --------- |
 | single   | 1          | image     |
@@ -22,63 +40,68 @@ UTF-8 JSON，拒绝重复键、未知字段、NaN 和未知版本。文件路径
 | sequence | 2–4        | image     |
 | text     | 1          | text      |
 
-`pages` 至少一项；数组顺序为阅读顺序。页面 ID 用于 `#page=<id>`，修改描述时保留 ID。
+页面数组顺序为证据阅读顺序。页面 ID 用于 `#page=<id>`，修改描述时保留 ID。
+
+`evidenceState` 为 `observed`（有观察材料）、`insufficient`（证据不足）、`not-run`（未执行），不含业务通过/失败判定。后两项的具体缺口写在正文或 limitations 中。observed 同样可以记录失败，不能根据页数计算通过率。
 
-`evidenceState` 为 `observed`（有观察材料）、`insufficient`（证据不足）、`not-run`（未执行），不含业务通过/失败判定。后两项的具体缺口应写在正文或 limitations 中；未执行又没有截图时用真实文字说明页，不造图。
+v2 文字项的 `summary` 是面向用户的简短摘要，按正常正文排版；原始文字不被替换或截断，点击“打开原文”即可核对。不填 summary 时仍显示完整等宽原文。来源区只列出处和打开入口，不重复铺开全文。所有文本均为纯文本，不解析 Markdown/HTML。
 
-`sourceIds` 只引用 text 素材，可为空。PNG/JPEG 图片最大 32 MiB、宽高各最多 32768px；文字 TXT/MD/JSON 及输入 JSON 最大 2 MiB。JSON 素材也要求合法 JSON。PNG 校验结构和 CRC；JPEG 检查容器与常用 SOF 尺寸，完整解码由浏览器验证。若图片打不开，不能只依据 validate 成功交付。
+`sourceIds` 只引用 text 素材，可为空。PNG/JPEG 图片最大 32 MiB、宽高各最多 32768px；文字 TXT/MD/JSON 及输入 JSON 最大 2 MiB。JSON 素材也要求合法 JSON。PNG 校验结构和 CRC；JPEG 检查容器与常用 SOF 尺寸，完整解码由浏览器验证。素材上限不等于 Runweave 交付上限，见下文预检。
 
 `crop` 为原 PNG 整数像素坐标，x/y 非负、width/height 为正且完整位于原图内。JPEG 仅允许完整展示，避免 EXIF 方向与坐标歧义。原图不被重采样或写回。
 
 ## 最小可执行输入
 
-在同一输入目录准备真实的 `observation.txt`，再保存如下 `task.json`；把示例内容改成当前任务事实后执行。
+以下示例明确表示没有执行；保存为 `task.json` 即可生成无素材的范围说明报告。使用时将目标、标准和原因改为本次事实。补充真实证据之后才能改结果，不要复制示例冒充完成验收。
 
 ```json
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "task": {
     "id": "current-task",
-    "title": "当前任务的核对结果",
-    "scope": "说明本次核对范围与环境",
+    "title": "当前任务验收报告",
+    "scope": "填写本次版本、环境与目标范围",
     "materialKind": "current",
-    "limitations": []
+    "limitations": ["尚未连接目标设备，不能确认真机行为。"]
   },
-  "assets": [
-    {
-      "id": "observation",
-      "kind": "text",
-      "path": "observation.txt",
-      "label": "实际观察记录",
-      "origin": { "surface": "CLI", "capturedAt": null, "sourceRef": null }
-    }
-  ],
-  "pages": [
-    {
-      "id": "result",
-      "type": "text",
-      "title": "本次实际观察到了什么",
-      "description": "交代操作条件、实际动作与观察，不超过原始记录的证据范围。",
-      "evidenceState": "observed",
-      "items": [{ "assetId": "observation", "label": "结果原文" }],
-      "sourceIds": []
-    }
-  ]
+  "report": {
+    "summary": "真机路径尚未执行，本报告不作通过结论。",
+    "checks": [
+      {
+        "id": "phone-flow",
+        "title": "手机完成目标操作",
+        "expected": "在目标真机完成操作并核对保存后的状态。",
+        "actual": "未连接目标设备，没有执行此路径。",
+        "execution": "not-run",
+        "outcome": "blocked",
+        "pageIds": []
+      }
+    ]
+  },
+  "assets": [],
+  "pages": []
 }
 ```
 
-## 原始素材查看
-
-正文图片、标题旁的原图/原文和来源链接都在阅读器内部打开，不依赖弹窗或页面跳转。图片可切换实际尺寸并滚动；关闭后保持原来的页码和焦点。原图与原文文件仍单独保留，复制成果目录后可直接使用。Backend 的 HTML 预览沙箱与真机阅读仍须通过实际入口核对，不能仅凭本地打开推断。
+有真实记录时按上方 asset/page 合同补充素材。文字项示例为 `{"assetId":"observation","label":"执行记录","summary":"填写该记录支持的实际观察与限制。"}`；check.pageIds 引用对应页的 id，而不是素材 id。
 
-## 输出与错误
+## 交付预检、输出与错误
 
-`validate` 返回 JSON `{valid, pages, assets}`，不写文件。`build` 返回 `{output, index, pages}`。成功退出 0；输入、文件或运行错误退出 1，命令参数错误退出 2，stderr 给出字段或文件原因。`serve` 前台长驻，第一行返回 `{url,pid,directory,stop}`；Ctrl-C 正常停止。
+- `validate` 返回 `{valid, pages, assets}`，只验证输入，不写文件；不证明可通过 Backend 交付。
+- `build` 默认 `--target runweave`，生成临时成果后按 Runweave 的 HTML 1 MiB、单资源 5 MiB 上限检查完整清单。不可交付则退出 1 并指出文件，最终目录不落盘；不读取凭据或申请票据。
+- 明确需要离线大文件时使用 `build --target portable`。仍保留原素材并返回 `deliveryCheck`，其中 ready:false 表示不能通过当前 Runweave 入口，不能当作已交付成功。
+- `build` 返回 `{output, index, pages, target, deliveryCheck}`。`deliveryCheck` 含 `target`、`ready`、`filesChecked`、`issues`；本地通过不证明资源解码、浏览器加载或手机可达。
+- 已生成报告可运行 `gallery.py preflight --directory <成果目录>`，输出本地检查 JSON，ready 为 false 时退出 1。详细入口与票据流程见 [预览与检查](delivery.md)。
+- 成功退出 0；输入、文件或运行错误退出 1，命令参数错误退出 2，stderr 给出原因。`serve` 前台长驻，第一行返回 `{url,pid,directory,stop}`；Ctrl-C 正常停止。
 
-输出文件：`index.html`、`reader.css`、`viewer.css`、`reader.js`、`task.json`、`manifest.json` 与 `assets/`。正文及关联文字内嵌进页面，不依赖 fetch 或外网；原始文字与图片也单独保留。task.json 保持输入合同，path 改为成果内相对路径。manifest 保存 schemaVersion、templateVersion、原始输入摘要及复制素材 SHA-256。
+输出文件：`index.html`、`reader.css`、`report.css`、`viewer.css`、`reader.js`、`task.json`、`manifest.json` 与 `assets/`。文字内嵌进页面，不依赖 fetch 或外网；原始文字与图片也单独保留。task.json 保持输入合同，path 改为成果内相对路径。manifest 保存 schemaVersion、templateVersion、原始输入摘要及复制素材 SHA-256。
 
 生成失败不留下最终目录，已有输出拒绝覆盖。生成器用同目标的临时锁串行化生成；进程被强杀可能留下 `.gallery-lock` 和 `.gallery-*`，核对没有相同目标构建在运行后，才清理这些本次临时文件或换新输出目录。不要删除旧成果绕过覆盖检查。
 
-未知版本拒绝；不自动迁移。每份报告带模板副本，后续升级不改变旧报告。生成器只处理显式列出的素材，不自动爬取来源、执行命令或读整个历史。
+每份报告带模板副本，后续升级不改变旧报告。生成器只处理显式列出的素材，不自动爬取来源、执行命令或读整个历史。
+
+## 原始素材查看与本地服务
+
+正文图片、标题旁的原图/原文和来源链接都在阅读器内部打开，不依赖弹窗或页面跳转。图片可切换实际尺寸并滚动；关闭后保持原来的页码和焦点。原图与原文文件仍单独保留，复制成果目录后可直接使用。Backend 的 HTML 预览沙箱与真机阅读仍须通过实际入口核对，不能仅凭本地打开推断。
 
 `serve` 只绑定 `127.0.0.1`，只允许清单中的文件，不开放目录列表和写接口；根目录越界及符号链接逃逸均拒绝。素材路径不接受绝对路径、`..`、反斜线、冒号或远程 URL。页面文本转义显示，不支持任务传入 HTML。输入输出根目录应由当前用户控制，不将此本机工具部署为多用户公共服务。

package/payload/plugins/toolkit/skills/acceptance/references/gallery-copy.md

@@ -21,6 +21,14 @@
 
 对照前核对目标、运行端、版本、尺寸与条件；不同条件必须说明。有结果图但没有前图时退回单图，不能生成假前图。需要真实运动或闪烁证据的任务不以截图模板替代原采集方式。
 
+## 验收总览与正文
+
+新报告先填写 report.summary：本次验证到什么程度、哪些结论受限。逐项列用户目标、预期、实际与对应证据，未执行和阻塞也必须列出。通过结论只适用于明确执行的范围；桌面 UI、浏览器模拟和真机路径分别判断。真实/Mock 是执行条件，不是证据缺失的代称。
+
+总览优先呈现失败、阻塞、未执行；不以“是否有截图”决定重要性。代码变更清单和技术实现按需作为辅助材料，不占据用户验收主线。不要把 Agent 自检记录写成用户已确认。
+
+文字页可用 item.summary 写面向用户的简短摘要；原始日志保留在素材与原文查看器中，不在摘要、正文、来源区反复粘贴全文。不根据文件后缀猜测总结，不改写或截断原始证据。
+
 ## 文案如何写
 
 标题说明本页要核对的结果；建议 12–24 个中文字。正文以 1–2 句交代“条件、动作、实际观察”，建议 40–100 字。软长度目标不覆盖准确性要求。

package/payload/plugins/toolkit/skills/acceptance/scripts/delivery_check.py

@@ -0,0 +1,151 @@
+"""Local checks for generated galleries; no credentials, network or HTML crawling."""
+import json
+from pathlib import Path
+import re
+import stat
+
+# Keep the delivery limits aligned with backend/src/terminal/preview/html-preview.ts.
+MAX_HTML_BYTES = 1024 * 1024
+MAX_RESOURCE_BYTES = 5 * 1024 * 1024
+MAX_MANIFEST_BYTES = 2 * 1024 * 1024
+_TEMPLATE_VERSIONS = ('1.0.0', '1.1.0', '1.2.0')
+_SHA256 = re.compile(r'[0-9a-fA-F]{64}')
+
+
+def check_gallery(directory: Path) -> dict:
+    """Check only fixed files and explicit manifest assets, counting unique paths.
+
+    ready means these local files meet delivery limits, not that a browser loaded
+    their contents or a phone can reach the Backend. Empty asset lists are valid.
+    """
+    result = {'target': 'runweave-html', 'ready': False, 'filesChecked': 0, 'issues': []}
+
+    def issue(path, reason, **details):
+        result['issues'].append({'path': path, 'reason': reason, **details})
+
+    try:
+        root = directory.resolve(strict=True)
+        if not root.is_dir():
+            raise ValueError('Gallery root must be a directory')
+    except (OSError, RuntimeError, ValueError) as error:
+        issue(str(directory), str(error))
+        return result
+
+    checked = {}
+
+    def inspect(relative, limit):
+        if relative in checked:
+            return checked[relative]
+        checked[relative] = None
+        result['filesChecked'] += 1
+        if (not relative or '\\' in relative or '\x00' in relative or
+                any(part in ('', '.', '..') for part in relative.split('/'))):
+            issue(relative, 'Invalid relative file path; directory escapes are not allowed')
+            return None
+        try:
+            resolved = (root / relative).resolve(strict=True)
+            if not resolved.is_relative_to(root):
+                issue(relative, 'File or symlink escapes the gallery directory')
+                return None
+            info = resolved.stat()
+            if not stat.S_ISREG(info.st_mode):
+                issue(relative, 'Expected a regular file')
+                return None
+            if info.st_size > limit:
+                issue(relative, 'File exceeds local delivery size limit',
+                      bytes=info.st_size, limitBytes=limit)
+                return None
+        except (OSError, RuntimeError, ValueError) as error:
+            issue(relative, 'Missing or inaccessible file: ' + str(error))
+            return None
+        checked[relative] = resolved
+        return resolved
+
+    for name in ('index.html', 'reader.css', 'reader.js', 'task.json', 'manifest.json'):
+        limit = (MAX_HTML_BYTES if name == 'index.html' else
+                 MAX_MANIFEST_BYTES if name == 'manifest.json' else MAX_RESOURCE_BYTES)
+        inspect(name, limit)
+    manifest_path = checked['manifest.json']
+    if manifest_path is None:
+        return result
+
+    def unique_object(pairs):
+        obj = {}
+        for key, value in pairs:
+            if key in obj:
+                raise ValueError('Duplicate JSON key: ' + key)
+            obj[key] = value
+        return obj
+
+    def reject_constant(value):
+        raise ValueError('Invalid JSON constant: ' + value)
+
+    try:
+        # Bound the read as well as the stat, even if the file changed meanwhile.
+        with manifest_path.open('rb') as stream:
+            data = stream.read(MAX_MANIFEST_BYTES + 1)
+        if len(data) > MAX_MANIFEST_BYTES:
+            issue('manifest.json', 'Manifest exceeds local parsing limit',
+                  bytes=len(data), limitBytes=MAX_MANIFEST_BYTES)
+            return result
+        manifest = json.loads(data.decode('utf-8'), object_pairs_hook=unique_object,
+                              parse_constant=reject_constant)
+    except (OSError, ValueError, RecursionError) as error:
+        issue('manifest.json', 'Invalid or unreadable manifest JSON: ' + str(error))
+        return result
+    if not isinstance(manifest, dict):
+        issue('manifest.json', 'Manifest must be an object')
+        return result
+    if type(manifest.get('schemaVersion')) is not int or manifest['schemaVersion'] != 1:
+        issue('manifest.json', 'Expected manifest schemaVersion 1')
+    version = manifest.get('templateVersion')
+    if version not in _TEMPLATE_VERSIONS:
+        issue('manifest.json', 'Unsupported or missing templateVersion')
+    if version in ('1.1.0', '1.2.0'):
+        inspect('viewer.css', MAX_RESOURCE_BYTES)
+    if version == '1.2.0':
+        inspect('report.css', MAX_RESOURCE_BYTES)
+    if not isinstance(manifest.get('inputSha256'), str) or not _SHA256.fullmatch(manifest['inputSha256']):
+        issue('manifest.json', 'inputSha256 must be a SHA-256 hex string')
+    assets = manifest.get('assets')
+    if not isinstance(assets, list):
+        issue('manifest.json', 'assets must be an array (it may be empty)')
+        return result
+    ids, paths = set(), set()
+    for index, asset in enumerate(assets):
+        location = f'manifest.json assets[{index}]'
+        if not isinstance(asset, dict):
+            issue('manifest.json', location + ' must be an object')
+            continue
+        asset_id = asset.get('id')
+        if not isinstance(asset_id, str) or not asset_id.strip():
+            issue('manifest.json', location + '.id must be a nonempty string')
+        elif asset_id in ids:
+            issue('manifest.json', location + '.id is duplicated')
+        else:
+            ids.add(asset_id)
+        if not isinstance(asset.get('sha256'), str) or not _SHA256.fullmatch(asset['sha256']):
+            issue('manifest.json', location + '.sha256 must be a SHA-256 hex string')
+        relative = asset.get('path')
+        if not isinstance(relative, str) or not relative:
+            issue('manifest.json', location + '.path must be a nonempty relative path')
+            continue
+        if relative in paths:
+            issue(relative, 'Duplicate manifest asset path')
+        paths.add(relative)
+        inspect(relative, MAX_RESOURCE_BYTES)
+    result['ready'] = not result['issues']
+    return result
+
+
+def require_ready(result: dict) -> None:
+    """Stop delivery on failed local checks and identify the affected files."""
+    if result.get('ready') is True:
+        return
+    details = []
+    for item in result.get('issues', []):
+        description = f'{item["path"]}: {item["reason"]}'
+        if 'bytes' in item and 'limitBytes' in item:
+            description += f' ({item["bytes"]} bytes; limit {item["limitBytes"]} bytes)'
+        details.append(description)
+    raise ValueError('Runweave HTML local preflight failed: ' + ('; '.join(details) or 'not ready'))

package/payload/plugins/toolkit/skills/acceptance/scripts/gallery.py

@@ -16,7 +16,10 @@ import zlib
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from urllib.parse import unquote, urlsplit
 
-TEMPLATE_VERSION = '1.1.0'
+sys.dont_write_bytecode = True
+from delivery_check import check_gallery, require_ready
+
+TEMPLATE_VERSION = '1.2.0'
 TEMPLATES = Path(__file__).resolve().parent.parent / 'templates'
 ID = re.compile(r'^[a-zA-Z0-9][a-zA-Z0-9_-]{0,79}$')
 MAX_FILE = 32 * 1024 * 1024
@@ -136,8 +139,10 @@ def parse_json(data):
 def load_task(root, input_name):
     raw = read_file(local_file(root, input_name), MAX_TEXT)
     task = parse_json(raw)
-    fields(task, 'root', ['schemaVersion', 'task', 'assets', 'pages'])
-    require(type(task['schemaVersion']) is int and task['schemaVersion'] == 1, 'schemaVersion', '仅支持版本 1')
+    require(isinstance(task, dict), 'root', '需要对象')
+    version = task.get('schemaVersion')
+    require(type(version) is int and version in (1, 2), 'schemaVersion', '仅支持版本 1/2')
+    fields(task, 'root', ['schemaVersion', 'task', 'assets', 'pages'] + (['report'] if version == 2 else []))
     meta = task['task']
     fields(meta, 'task', ['id', 'title', 'scope', 'materialKind', 'limitations'])
     identifier(meta['id'], 'task.id')
@@ -170,7 +175,8 @@ def load_task(root, input_name):
                 parse_json(data)
         assets[asset['id']] = asset
         payloads[asset['id']] = (data, suffix)
-    require(isinstance(task['pages'], list) and len(task['pages']) > 0, 'pages', '至少需要一页')
+    require(isinstance(task['pages'], list), 'pages', '需要数组')
+    require(version == 2 or len(task['pages']) > 0, 'pages', '版本 1 至少需要一页')
     seen = set()
     for i, page in enumerate(task['pages']):
         where = f'pages[{i}]'
@@ -190,7 +196,7 @@ def load_task(root, input_name):
         require(low <= len(items) <= high, where, f'当前页型需要 {low}–{high} 个素材项')
         for j, item in enumerate(items):
             iw = where + f'.items[{j}]'
-            fields(item, iw, ['assetId', 'label'], ['alt', 'crop'])
+            fields(item, iw, ['assetId', 'label'], ['alt', 'crop'] + (['summary'] if version == 2 else []))
             string(item['assetId'], iw + '.assetId')
             string(item['label'], iw + '.label')
             require(item['assetId'] in assets, iw, '素材 ID 不存在')
@@ -201,6 +207,9 @@ def load_task(root, input_name):
                 string(item.get('alt'), iw + '.alt')
             else:
                 require('crop' not in item and 'alt' not in item, iw, '文字项不接受 crop/alt')
+            if 'summary' in item:
+                require(kind == 'text', iw, 'summary 仅用于文字素材摘要')
+                string(item['summary'], iw + '.summary')
             if 'crop' in item:
                 crop = item['crop']
                 fields(crop, iw + '.crop', ['x', 'y', 'width', 'height'])
@@ -213,14 +222,47 @@ def load_task(root, input_name):
         strings(page['sourceIds'], where + '.sourceIds')
         for source_id in page['sourceIds']:
             require(source_id in assets and assets[source_id]['kind'] == 'text', where, 'sourceIds 只能引用存在的文字素材')
+    if version == 2:
+        validate_report(task['report'], task['pages'])
     return task, payloads, image_sizes, hashlib.sha256(raw).hexdigest()
 
 
+def validate_report(report, pages):
+    fields(report, 'report', ['summary', 'checks'])
+    string(report['summary'], 'report.summary')
+    require(isinstance(report['checks'], list) and report['checks'], 'report.checks', '至少需要一项验收目标')
+    by_id = {page['id']: page for page in pages}
+    seen = set()
+    for i, check in enumerate(report['checks']):
+        where = f'report.checks[{i}]'
+        fields(check, where, ['id', 'title', 'expected', 'actual', 'execution', 'outcome', 'pageIds'])
+        identifier(check['id'], where + '.id')
+        require(check['id'] not in seen, where, '重复验收项 ID')
+        seen.add(check['id'])
+        for key in ('title', 'expected', 'actual'):
+            string(check[key], where + '.' + key)
+        execution, outcome = check['execution'], check['outcome']
+        require(execution in ('real', 'mock', 'not-run'), where, 'execution 需要 real/mock/not-run')
+        require(outcome in ('pass', 'fail', 'blocked', 'not-run'), where, 'outcome 需要 pass/fail/blocked/not-run')
+        strings(check['pageIds'], where + '.pageIds')
+        require(len(set(check['pageIds'])) == len(check['pageIds']), where, '重复证据页 ID')
+        require(all(id_ in by_id for id_ in check['pageIds']), where, '证据页 ID 不存在')
+        if outcome == 'not-run':
+            require(execution == 'not-run', where, '未执行结果不能声明已实际执行或 Mock 执行')
+        if execution == 'not-run':
+            require(outcome in ('not-run', 'blocked'), where, '未执行不能声明通过或失败')
+        if outcome in ('pass', 'fail'):
+            evidence = [by_id[id_]['evidenceState'] for id_ in check['pageIds']]
+            require('observed' in evidence, where, '通过或失败需要关联实际观察的证据页')
+            if outcome == 'pass':
+                require(all(state == 'observed' for state in evidence), where, '证据不足或未执行的页不能支持通过结论')
+
+
 def dump(path, value):
     path.write_text(json.dumps(value, ensure_ascii=False, indent=2) + '\n', encoding='utf-8')
 
 
-def build(loaded, output):
+def build(loaded, output, target='runweave'):
     task, payloads, sizes, input_hash = loaded
     output = output.absolute()
     output.parent.mkdir(parents=True, exist_ok=True)
@@ -257,10 +299,13 @@ def build(loaded, output):
         before, after = template.split('@@DATA@@')
         before = before.replace('@@TITLE@@', html.escape(task['task']['title']))
         (stage / 'index.html').write_text(before + embedded + after, encoding='utf-8')
-        for name in ('reader.css', 'reader.js', 'viewer.css'):
+        for name in ('reader.css', 'reader.js', 'viewer.css', 'report.css'):
             shutil.copyfile(TEMPLATES / name, stage / name)
         dump(stage / 'task.json', snapshot)
         dump(stage / 'manifest.json', manifest)
+        delivery = check_gallery(stage)
+        if target == 'runweave':
+            require_ready(delivery)
         require(not output.exists() and not output.is_symlink(), 'output', '目标已存在')
         stage.rename(output)
         stage = None
@@ -268,7 +313,8 @@ def build(loaded, output):
         if stage is not None:
             shutil.rmtree(stage)
         lock.unlink()
-    return {'output': str(output), 'index': str(output / 'index.html'), 'pages': len(task['pages'])}
+    return {'output': str(output), 'index': str(output / 'index.html'), 'pages': len(task['pages']),
+            'target': target, 'deliveryCheck': delivery}
 
 
 def serve(directory, port):
@@ -276,8 +322,10 @@ def serve(directory, port):
     manifest = parse_json(read_file(root / 'manifest.json', MAX_TEXT))
     require(manifest.get('schemaVersion') == 1 and isinstance(manifest.get('assets'), list), 'directory', '不是生成的成果目录')
     allowed = {'index.html', 'reader.css', 'reader.js', 'task.json', 'manifest.json'}
-    if manifest.get('templateVersion') == '1.1.0':
+    if manifest.get('templateVersion') in ('1.1.0', TEMPLATE_VERSION):
         allowed.add('viewer.css')
+    if manifest.get('templateVersion') == TEMPLATE_VERSION:
+        allowed.add('report.css')
     allowed.update(asset['path'] for asset in manifest['assets'])
     for relative in allowed:
         local_file(root, relative)
@@ -324,7 +372,7 @@ def serve(directory, port):
 
 
 def main():
-    parser = argparse.ArgumentParser(description='本地图文验收阅读器：validate / build / serve')
+    parser = argparse.ArgumentParser(description='本地图文验收阅读器：validate / build / preflight / serve')
     sub = parser.add_subparsers(dest='command', required=True)
     for name in ('validate', 'build'):
         command = sub.add_parser(name)
@@ -332,6 +380,10 @@ def main():
         command.add_argument('--input', default='task.json')
         if name == 'build':
             command.add_argument('--output', type=Path, required=True)
+            command.add_argument('--target', choices=('runweave', 'portable'), default='runweave',
+                                 help='默认按 Runweave 预览限额预检；portable 只生成离线成果并报告限制')
+    command = sub.add_parser('preflight')
+    command.add_argument('--directory', type=Path, required=True)
     command = sub.add_parser('serve')
     command.add_argument('--directory', type=Path, required=True)
     command.add_argument('--port', type=int, default=0)
@@ -341,8 +393,12 @@ def main():
             require(0 <= args.port <= 65535, 'port', '端口范围 0–65535')
             serve(args.directory, args.port)
             return
+        if args.command == 'preflight':
+            result = check_gallery(args.directory)
+            print(json.dumps(result, ensure_ascii=False))
+            sys.exit(0 if result['ready'] else 1)
         loaded = load_task(args.input_root.resolve(strict=True), args.input)
-        result = build(loaded, args.output) if args.command == 'build' else {'valid': True, 'pages': len(loaded[0]['pages']), 'assets': len(loaded[0]['assets'])}
+        result = build(loaded, args.output, args.target) if args.command == 'build' else {'valid': True, 'pages': len(loaded[0]['pages']), 'assets': len(loaded[0]['assets'])}
         print(json.dumps(result, ensure_ascii=False))
     except (Invalid, OSError, ValueError, KeyError, TypeError) as error:
         print(f'gallery: {error}', file=sys.stderr)

package/payload/plugins/toolkit/skills/acceptance/scripts/preview.py

@@ -9,6 +9,7 @@ import sys
 import urllib.parse
 sys.dont_write_bytecode = True
 from common import base_url, http, write_json
+from delivery_check import MAX_HTML_BYTES, check_gallery, require_ready
 
 
 def configure_parser(parser, default_kind='auto'):
@@ -25,7 +26,8 @@ def configure_parser(parser, default_kind='auto'):
 
 
 def preview(args):
-    file = args.file.resolve(strict=True)
+    requested = args.file.absolute()
+    file = requested.resolve(strict=True)
     if not file.is_file():
         raise ValueError('Preview input must be a regular file')
     kind = args.kind
@@ -38,6 +40,23 @@ def preview(args):
         raise FileExistsError('Use a new output path for each preview ticket')
     if not args.output.parent.is_dir():
         raise ValueError('Preview output parent must already exist')
+    local_check = None
+    if kind == 'html':
+        manifest = requested.parent / 'manifest.json'
+        if requested.name == 'index.html' and (manifest.exists() or manifest.is_symlink()):
+            local_check = check_gallery(requested.parent)
+            local_check['scope'] = 'gallery-fixed-files-and-manifest-assets'
+        else:
+            size = file.stat().st_size
+            issues = []
+            if size > MAX_HTML_BYTES:
+                issues.append({'path': str(requested), 'reason': 'HTML entry exceeds preview size limit',
+                               'bytes': size, 'limitBytes': MAX_HTML_BYTES})
+            local_check = {'target': 'runweave-html', 'ready': not issues, 'filesChecked': 1,
+                           'issues': issues, 'scope': 'html-entry-only',
+                           'resources': 'not-checked; arbitrary HTML resources are not inspected'}
+        # Fail locally before accessing credentials or contacting either Backend URL.
+        require_ready(local_check)
     if args.token_env:
         if not args.backend:
             raise ValueError('--token-env requires --backend')
@@ -89,7 +108,7 @@ def preview(args):
         status, _, content = http(url)
         if status != 200 or content != file.read_bytes():
             raise ValueError('Anonymous HTML GET did not match local bytes')
-        receipt.update(htmlStatus=200, htmlMatchesLocal=True,
+        receipt.update(htmlStatus=200, htmlMatchesLocal=True, localPreflight=local_check,
                        resources='not-verified; check styles/scripts/images in a real browser')
     write_json(args.output, receipt, private=True)
     print(json.dumps({k: v for k, v in receipt.items() if k != 'url'}, ensure_ascii=False))

package/payload/plugins/toolkit/skills/acceptance/templates/reader.css

@@ -128,14 +128,6 @@ ul {
   margin-top: 8px;
   max-width: 960px;
 }
-.masthead details {
-  font-size: 13px;
-  color: var(--muted);
-  margin-top: 10px;
-}
-.masthead details ul {
-  margin: 6px 0;
-}
 .workspace {
   max-width: 1400px;
   margin: auto;
@@ -361,11 +353,6 @@ figcaption a {
 .source-item p {
   margin-top: 4px;
 }
-.source-item pre {
-  margin-top: 8px;
-  max-height: 32vh;
-  font-size: 12px;
-}
 .navigation {
   position: fixed;
   bottom: 0;
@@ -516,7 +503,7 @@ figcaption a {
   }
   .text-evidence {
     padding: 12px;
-    font-size: 12px;
+    font-size: 14px;
   }
   .notice {
     bottom: 82px;

package/payload/plugins/toolkit/skills/acceptance/templates/reader.html

@@ -7,6 +7,7 @@
     <link rel="icon" href="data:," />
     <title>@@TITLE@@</title>
     <link rel="stylesheet" href="reader.css" />
+    <link rel="stylesheet" href="report.css" />
     <link rel="stylesheet" href="viewer.css" />
     <script id="gallery-data" type="application/json">
       @@DATA@@
@@ -25,13 +26,31 @@
         <button id="expand" type="button" aria-pressed="false">展开全部</button>
       </div>
       <p id="task-scope"></p>
-      <details id="task-limits" hidden>
-        <summary>本次材料的范围</summary>
-        <ul></ul>
-      </details>
     </header>
+    <section
+      id="report-overview"
+      class="report-overview"
+      aria-labelledby="report-heading"
+    >
+      <h2 id="report-heading" tabindex="-1">验收总览</h2>
+      <p id="report-summary" class="description"></p>
+      <section
+        id="task-limits"
+        class="limits"
+        aria-label="本次范围与限制"
+        hidden
+      >
+        <h3>本次范围与限制</h3>
+        <ul></ul>
+      </section>
+      <p class="report-note">
+        以下为报告作者记录的自检结果，不代表用户已确认验收。有观察材料不等于通过。
+      </p>
+      <ul id="report-checks" class="report-checks"></ul>
+    </section>
     <div class="workspace">
       <aside class="directory">
+        <button id="back-overview" type="button">返回验收总览</button>
         <details id="directory-details" open>
           <summary>阅读目录</summary>
           <nav aria-label="页面目录" id="directory"></nav>