@runweave/server-linux-x64 0.1.7 → 0.1.9

package/payload/plugins/toolkit/hooks/runweave-task-supervision.cjs

@@ -0,0 +1,167 @@
+/* global AbortSignal, fetch, module, process, require, URL */
+/* eslint-disable @typescript-eslint/no-require-imports */
+const { spawnSync } = require("node:child_process");
+const os = require("node:os");
+const path = require("node:path");
+const { extractUserPrompt } = require("./runweave-hook-payload.cjs");
+async function requestSupervision({
+  source,
+  stateEndpoint,
+  threadId,
+  terminalPanelId,
+  terminalSessionId,
+  normalizedEvent,
+  token,
+  payload,
+  hookStartedAt,
+  debug = () => {},
+}) {
+  if (
+    source === "codex" &&
+    stateEndpoint &&
+    threadId &&
+    terminalPanelId &&
+    process.env.RUNWEAVE_TERMINAL_AGENT_OPERATION_ID &&
+    [
+      "sessionstart",
+      "userpromptsubmit",
+      "interrupt",
+      "stop",
+      "permissionrequest",
+      "pretooluse",
+      "posttooluse",
+    ].includes(normalizedEvent)
+  ) {
+    const supervisionEndpoint = new URL(
+      "/internal/task-supervision",
+      stateEndpoint,
+    ).toString();
+    const version = !["sessionstart", "userpromptsubmit", "stop"].includes(
+      normalizedEvent,
+    )
+      ? null
+      : spawnSync(
+          process.env.RUNWEAVE_CODEX_EXECUTABLE ||
+            process.env.RUNWEAVE_CODEX_BINARY ||
+            "codex",
+          ["--version"],
+          {
+            encoding: "utf8",
+            timeout: 500,
+            maxBuffer: 1024,
+          },
+        );
+    const event = {
+      sessionstart: "SessionStart",
+      userpromptsubmit: "UserPromptSubmit",
+      interrupt: "Interrupt",
+      stop: "Stop",
+      permissionrequest: "PermissionRequest",
+      pretooluse: "PreToolUse",
+      posttooluse: "PostToolUse",
+    }[normalizedEvent];
+    try {
+      const response = await fetch(supervisionEndpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Runweave-Hook-Token": token,
+        },
+        signal: AbortSignal.timeout(
+          normalizedEvent === "stop"
+            ? Math.max(1, hookStartedAt + 110000 - Date.now())
+            : 700,
+        ),
+        body: JSON.stringify({
+          target: {
+            terminalSessionId,
+            panelId: terminalPanelId,
+            threadId,
+            executorGeneration:
+              process.env.RUNWEAVE_TERMINAL_AGENT_OPERATION_ID,
+          },
+          event,
+          ...(typeof payload.tool_name === "string"
+            ? { toolName: payload.tool_name }
+            : {}),
+          hookVersion: 1,
+          codexVersion: String(version?.stdout || "").trim(),
+          ...(process.env.RUNWEAVE_CODEX_CONFIG_ARGS
+            ? {
+                executionConfig: {
+                  binary:
+                    process.env.RUNWEAVE_CODEX_EXECUTABLE ||
+                    process.env.RUNWEAVE_CODEX_BINARY ||
+                    "codex",
+                  home:
+                    process.env.CODEX_HOME || path.join(os.homedir(), ".codex"),
+                  cwd: process.cwd(),
+                  args: JSON.parse(process.env.RUNWEAVE_CODEX_CONFIG_ARGS),
+                },
+              }
+            : {}),
+          ...(typeof payload.model === "string"
+            ? { executionModel: payload.model }
+            : {}),
+          rawTurnId: payload.turn_id || undefined,
+          ...(normalizedEvent === "stop" &&
+          typeof payload.last_assistant_message === "string"
+            ? { reply: payload.last_assistant_message }
+            : {}),
+          ...(normalizedEvent === "userpromptsubmit"
+            ? { prompt: extractUserPrompt(payload) }
+            : {}),
+          deadline:
+            hookStartedAt + (normalizedEvent === "stop" ? 110000 : 1500),
+        }),
+      });
+      debug("task supervision hook response", {
+        event,
+        status: response.status,
+        version: String(version?.stdout || "").trim(),
+      });
+      if (response.ok)
+        return { result: await response.json(), endpoint: supervisionEndpoint };
+    } catch (error) {
+      debug("task supervision hook unavailable", {
+        event,
+        error: error instanceof Error ? error.name : "unknown",
+      });
+      /* Allow native stop on unavailable supervision; never paste late input. */
+    }
+    // Interrupt has a native 3-second ceiling. It only invalidates decisions.
+  }
+  return null;
+}
+async function writeContinuation(offer, token) {
+  const supervision = offer?.result;
+  if (
+    supervision?.action !== "request-continuation" ||
+    !offer.endpoint ||
+    Date.now() >= supervision.deadline - 1000
+  )
+    return;
+  try {
+    const response = await fetch(`${offer.endpoint}/validate`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Runweave-Hook-Token": token,
+      },
+      signal: AbortSignal.timeout(700),
+      body: JSON.stringify({
+        watchId: supervision.watchId,
+        decisionId: supervision.decisionId,
+        revision: supervision.revision,
+      }),
+    });
+    const result = response.ok ? await response.json() : null;
+    if (result?.valid && Date.now() < supervision.deadline - 500)
+      process.stdout.write(
+        JSON.stringify({ decision: "block", reason: supervision.reason }),
+      );
+  } catch {
+    /* Keep uncertain offers reserved; never replay. */
+  }
+}
+module.exports = { requestSupervision, writeContinuation };

package/payload/plugins/toolkit/hooks.json

@@ -0,0 +1,108 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh -c 'for root in \"${RUNWEAVE_TOOLKIT_PLUGIN_ROOT:-}\" \"__PLUGIN_DIR__\" . \"${CODEX_PLUGIN_ROOT:-}\" \"$HOME/.codex/plugins/cache/runweave/toolkit/latest\" \"$HOME/.codex/plugins/cache/runweave/toolkit\"/* \"${CLAUDE_PLUGIN_ROOT:-}\"; do if [ -n \"$root\" ] && [ -f \"$root/hooks/runweave-hook-dispatch.cjs\" ]; then exec node \"$root/hooks/runweave-hook-dispatch.cjs\"; fi; done; exit 0'",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh -c 'for root in \"${RUNWEAVE_TOOLKIT_PLUGIN_ROOT:-}\" \"__PLUGIN_DIR__\" . \"${CODEX_PLUGIN_ROOT:-}\" \"$HOME/.codex/plugins/cache/runweave/toolkit/latest\" \"$HOME/.codex/plugins/cache/runweave/toolkit\"/* \"${CLAUDE_PLUGIN_ROOT:-}\"; do if [ -n \"$root\" ] && [ -f \"$root/hooks/runweave-hook-dispatch.cjs\" ]; then exec node \"$root/hooks/runweave-hook-dispatch.cjs\"; fi; done; exit 0'",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh -c 'for root in \"${RUNWEAVE_TOOLKIT_PLUGIN_ROOT:-}\" \"__PLUGIN_DIR__\" . \"${CODEX_PLUGIN_ROOT:-}\" \"$HOME/.codex/plugins/cache/runweave/toolkit/latest\" \"$HOME/.codex/plugins/cache/runweave/toolkit\"/* \"${CLAUDE_PLUGIN_ROOT:-}\"; do if [ -n \"$root\" ] && [ -f \"$root/hooks/runweave-hook-dispatch.cjs\" ]; then exec node \"$root/hooks/runweave-hook-dispatch.cjs\"; fi; done; exit 0'",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh -c 'for root in \"${RUNWEAVE_TOOLKIT_PLUGIN_ROOT:-}\" \"__PLUGIN_DIR__\" . \"${CODEX_PLUGIN_ROOT:-}\" \"$HOME/.codex/plugins/cache/runweave/toolkit/latest\" \"$HOME/.codex/plugins/cache/runweave/toolkit\"/* \"${CLAUDE_PLUGIN_ROOT:-}\"; do if [ -n \"$root\" ] && [ -f \"$root/hooks/runweave-hook-dispatch.cjs\" ]; then exec node \"$root/hooks/runweave-hook-dispatch.cjs\"; fi; done; exit 0'",
+            "timeout": 120
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh -c 'for root in \"${RUNWEAVE_TOOLKIT_PLUGIN_ROOT:-}\" \"__PLUGIN_DIR__\" . \"${CODEX_PLUGIN_ROOT:-}\" \"$HOME/.codex/plugins/cache/runweave/toolkit/latest\" \"$HOME/.codex/plugins/cache/runweave/toolkit\"/* \"${CLAUDE_PLUGIN_ROOT:-}\"; do if [ -n \"$root\" ] && [ -f \"$root/hooks/runweave-hook-dispatch.cjs\" ]; then exec node \"$root/hooks/runweave-hook-dispatch.cjs\"; fi; done; exit 0'",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh -c 'for root in \"${RUNWEAVE_TOOLKIT_PLUGIN_ROOT:-}\" \"__PLUGIN_DIR__\" . \"${CODEX_PLUGIN_ROOT:-}\" \"$HOME/.codex/plugins/cache/runweave/toolkit/latest\" \"$HOME/.codex/plugins/cache/runweave/toolkit\"/* \"${CLAUDE_PLUGIN_ROOT:-}\"; do if [ -n \"$root\" ] && [ -f \"$root/hooks/runweave-hook-dispatch.cjs\" ]; then exec node \"$root/hooks/runweave-hook-dispatch.cjs\"; fi; done; exit 0'",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "permission_prompt|idle_prompt",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh -c 'for root in \"${RUNWEAVE_TOOLKIT_PLUGIN_ROOT:-}\" \"__PLUGIN_DIR__\" . \"${CODEX_PLUGIN_ROOT:-}\" \"$HOME/.codex/plugins/cache/runweave/toolkit/latest\" \"$HOME/.codex/plugins/cache/runweave/toolkit\"/* \"${CLAUDE_PLUGIN_ROOT:-}\"; do if [ -n \"$root\" ] && [ -f \"$root/hooks/runweave-hook-dispatch.cjs\" ]; then exec node \"$root/hooks/runweave-hook-dispatch.cjs\"; fi; done; exit 0'",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Interrupt": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh -c 'for root in \"${RUNWEAVE_TOOLKIT_PLUGIN_ROOT:-}\" \"__PLUGIN_DIR__\" . \"${CODEX_PLUGIN_ROOT:-}\" \"$HOME/.codex/plugins/cache/runweave/toolkit/latest\" \"$HOME/.codex/plugins/cache/runweave/toolkit\"/* \"${CLAUDE_PLUGIN_ROOT:-}\"; do if [ -n \"$root\" ] && [ -f \"$root/hooks/runweave-hook-dispatch.cjs\" ]; then exec node \"$root/hooks/runweave-hook-dispatch.cjs\"; fi; done; exit 0'",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "PermissionRequest": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh -c 'for root in \"${RUNWEAVE_TOOLKIT_PLUGIN_ROOT:-}\" \"__PLUGIN_DIR__\" . \"${CODEX_PLUGIN_ROOT:-}\" \"$HOME/.codex/plugins/cache/runweave/toolkit/latest\" \"$HOME/.codex/plugins/cache/runweave/toolkit\"/* \"${CLAUDE_PLUGIN_ROOT:-}\"; do if [ -n \"$root\" ] && [ -f \"$root/hooks/runweave-hook-dispatch.cjs\" ]; then exec node \"$root/hooks/runweave-hook-dispatch.cjs\"; fi; done; exit 0'",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/payload/plugins/toolkit/skills/acceptance/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: acceptance
+description: 为当前改动生成适合手机查看的验收材料，默认图文，需要连续过程时制作视频，统一真实采集、来源说明、预览和检查。用户要求验收材料、手机看效果、截图说明、验收视频或录屏证据时使用；普通开发和测试不默认制作材料。
+---
+
+# 验收材料
+
+用户只需提出“给我本次改动的手机验收材料”。Agent 从判断问题出发选择形式，固定脚本负责图册、录制和视频制作。成功生成材料、完成业务验收、用户确认提交是独立事实。
+
+脚本相对本 `SKILL.md` 定位。`SKILL` 为本目录绝对路径，`RUN` 为本次独立产物目录；Runweave 通常使用 `artifacts/verification-runs/<唯一任务目录>/`。只读取本次材料及用户明确引用的历史，不自动检索其他任务。
+
+## 选择形式与证据
+
+- **默认图文**：布局、设置、静态结果、少量前后变化。CLI/后台结果可直接作为文字页，不硬配截图。
+- **按需视频**：连续交互、状态流转、等待或恢复过程是判断重点。先复用真实原片；需要补录时采集本次实际操作。
+- **组合**：视频说明过程，图文补充小字号细节、结果或来源。只补有帮助的内容，不为凑套装生成两份。
+- **原始录屏**：用户只要求取证或保存验证过程时，交付原片与采集元数据；不要求 OpenScreen、不增加字幕剪辑。普通“跑测试/浏览器检查”不自动升级为录屏。
+
+先说明本次要展示的变化、运行端与关键操作，沿用已授权范围继续；不重复请求批准故事板。复用已有素材前核对对象、版本、来源和时间，历史示例必须标明历史。离散截图不是连续录像，模拟器、浏览器模拟、已安装 App 与真机结论分开。
+
+需要补素材时：Web/Electron 使用 `toolkit:playwright-cli` 选择正确 Profile、Dev Session 或隔离页面；iOS 使用 `toolkit:agent-device`。操作 Runweave Dev Session 生命周期时使用其专属技能。不为整理材料启动无关环境，不覆盖用户页面，不在截图或原片中录入凭据和无关通知。
+
+## 按形式生成
+
+只读取当前形式的引用，所有浏览器连续帧采集统一使用 `capture.py`：
+
+- **图文**：读[取景与配文](references/gallery-copy.md)和[图文输入合同](references/gallery-contract.md)，准备 `gallery.json` 与显式列出的真实素材。
+- **视频**：读[视频输入与制作](references/video.md)，准备 `video.json`，Agent 只填原片、字幕和放大区间，不重写渲染程序。
+- **需浏览器补录或仅原始录屏**：读[唯一采集流程](references/capture.md)。原生窗口可使用已连接 OpenScreen 的窗口录制工具，先核对权限和目标；不以整个桌面或替代页面冒充目标录屏。
+
+```bash
+# 图文：无需 OpenScreen 或 ffmpeg。
+python3 "$SKILL/scripts/gallery.py" validate --input-root "$RUN" --input gallery.json
+python3 "$SKILL/scripts/gallery.py" build --input-root "$RUN" --input gallery.json --output "$RUN/gallery"
+
+# 视频：仅选择视频制作时检查这些依赖。
+python3 "$SKILL/scripts/video.py" doctor
+python3 "$SKILL/scripts/video.py" validate --input "$RUN/video.json"
+python3 "$SKILL/scripts/video.py" build --input "$RUN/video.json" --output "$RUN/video"
+```
+
+生成器拒绝覆盖成果。图文携带固定阅读器、原图/原文和来源；视频保留原片引用与哈希、独立 OpenScreen 工程/checkpoint、主片、手机压缩版与关键帧。渲染错误、采集错误或结果未知时保留本次证据并如实说明，不以旧文件或空输出代替，不自动重放结果未知的写操作。
+
+## 统一检查与手机入口
+
+读[预览与检查](references/delivery.md)。先看实际产物，再提供入口：
+
+- 图文检查逐页解码、翻页、目录、刷新定位、展开返回，以及原图/原文页内查看和实际尺寸；在桌面及手机窄屏核对阅读、遮挡和横向溢出。
+- 视频检查完整解码、每段字幕、放大区域及取景；在手机竖屏与横屏观察真实画面，并通过实际播放器控制条完成播放、暂停、继续、进度跳转和重新打开。精确抽帧不等于触摸验证。
+- 浏览器模拟明确记录引擎、尺寸和范围；iPhone 的 Safari/AVPlayer、全屏/旋转和阅读距离需要真机单独确认。未执行就保留缺口，不能由浏览器截图补成真机通过。
+
+有 Runweave 连接时，图文和视频共用一个文件票据入口：
+
+```bash
+python3 "$SKILL/scripts/preview.py" \
+  --file "$RUN/gallery/index.html" --project-id <当前实际项目ID> \
+  --profile local --viewer-base-url <手机实际可访问的Backend地址> \
+  --output "$RUN/gallery-links-01.json"
+# 视频将 --file 换为 "$RUN/video/review.mp4"，并使用新的输出 JSON。
+```
+
+该步骤核对服务身份、匿名读取和文件字节，不创建公开服务，也不证明手机网络已可达。`127.0.0.1` 和 Mac 文件路径不能当作手机链接；局域网、外网转发和物理手机分别核对。没有适用入口时如实给出本地产物与缺失条件，不擅自改路由、认证或建立隧道。每个链接说明到期时间，续期生成新的链接文件。
+
+## 交付、清理与迭代
+
+最终说明本次改了什么、材料覆盖什么、实际检查结果和未验证部分。给可打开的入口、观看步骤、网络/主机前提，以及正常查看是否需要人在 Mac 操作。按需附 1–3 张能反映实际效果的截图；视频小字看不清时补图文或原图。
+
+只停止本任务创建的采集、MCP、浏览器或本地预览服务，保留用户运行环境、原片及工程。材料不自动判定用户验收通过，不自动提交、上传、发消息或完成待办。随记任务使用 `toolkit:suiji`，只追加成功最终成果，完成状态独立授权。
+
+后续可复现的问题在本目录修正默认值、脚本或对应引用，验证真实输出后同步安装 Toolkit。`acceptance-gallery`、`acceptance-video` 和 `recorded-browser-mcp-verification` 仅保留显式兼容转发，不维护第二套规则或实现；新请求统一使用本入口。

package/payload/plugins/toolkit/skills/acceptance/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "验收材料"
+  short_description: "根据本次改动选择图文或视频，生成适合手机查看的真实验收材料"
+  default_prompt: "使用 $acceptance，给我本次改动的手机验收材料，说明已验证范围和查看方式，等我确认后再提交代码。"

package/payload/plugins/toolkit/skills/acceptance/references/capture.md

@@ -0,0 +1,38 @@
+# 浏览器采集
+
+用户只要录屏证据时，交付本流程的 `recording.mp4` 与 `capture.json`、帧和动作记录，不依赖 OpenScreen，也不追加字幕剪辑。需要连续操作视频时复用同一流程采集原片，再交给视频制作。
+
+先按 `toolkit:playwright-cli` 选择正确的实际页面并完成准备工作。已有页面不可用隔离浏览器冒充；独立预览页才使用隔离浏览器。采集只包住最终需要展示的操作，不重新执行整段开发过程。
+
+把操作写为 `actions.js`：一个 `async (page, clock) => { ... }` 表达式，无 `import`、`require`、`export`。`clock.now()` 返回相对录制起点的秒数，可记录实际动作和观察。使用本次页面里观察到的 locator；下面只是动作记录格式：
+
+```javascript
+async (page, clock) => {
+  const steps = [];
+  // 在此使用当前页面观察到的 locator 执行本任务的操作，并验证结果。
+  // 每步可记录 {atSeconds: clock.now(), action: '实际动作', observed: '实际观察'}。
+  return steps;
+};
+```
+
+这不是可直接执行的验收案例，必须填入当前任务的真实动作后再采集。避免录入密码、通知或连接凭据。
+
+```bash
+python3 "$SKILL/scripts/capture.py" prepare \
+  --actions "$RUN/actions.js" --output "$RUN/capture" --fps 4
+
+# 复用已按 Playwright Skill 选择的自有/已附着会话。
+# 采集元数据可能包含目标 URL；限制本次输出文件权限。
+umask 077
+pnpm exec playwright cli -s="$SESSION" --raw run-code \
+  --filename="$RUN/capture/run-code.js" > "$RUN/capture/capture.json"
+
+python3 "$SKILL/scripts/capture.py" encode \
+  --input "$RUN/capture/capture.json" --output "$RUN/recording.mp4"
+```
+
+`prepare` 只生成包装器，不启动浏览器或执行动作；可加 `--clip x,y,width,height` 使用已观察的 viewport 区域。`--fps` 为采样上限，默认 4，不是恒定实际采集频率。包装器并发采集 PNG，记录每张截图的真实相对请求时间；`encode` 使用实际间隔和总时长编码，而不是简单按帧数除以 4 计算。帧采样、截图耗时及 30 FPS 编码的舍入不适合精确性能或流畅度结论。
+
+操作/截图失败时包装器抛错；CLI 错误不是合法采集数据，`encode` 必须拒绝。保留截图用于诊断，不能把未返回成功采集记录的帧当成完整录屏。脚本拒绝覆盖现有目录、原片和时间轴文件。若操作需要高帧率、系统弹窗或原生窗口，改用适当的实际录屏来源，并记录来源差异。
+
+包装器自动记录开始/结束 URL、标题与 viewport，绑定到执行动作的同一个 page。Profile、target 或 Dev Session 身份通过当前任务的解析/附着回执保留，不能由截图猜测。动作需要的项目或终端应属于本次真实工作区；不为凑录屏新建空项目或复制代码冒充当前任务。

package/payload/plugins/toolkit/skills/acceptance/references/delivery.md

@@ -0,0 +1,54 @@
+# 预览与检查
+
+图文、视频和原片共用此处的访问与证据边界。优先使用任务已有的附件或经过验证的预览通道；材料默认留在本地，不自动上传或发布。
+
+## 图文检查
+
+逐页核对图片实际解码、配文、来源、取景及原图字节。检查翻页、目录、刷新定位、展开/返回分页，桌面与约 390–402px 手机窄屏的阅读和横向溢出。
+
+阅读器的原图、原文和来源素材在页内对话框打开，支持图片“实际尺寸/适应屏幕”、滚动、关闭、Escape 和回到原焦点。要通过实际交付入口检查这些操作；本地正常不等于 Backend 预览沙箱里正常。原图保持原始字节，取景只影响正文显示，不修改原片或原图。文字页可直接复制内容，不必截成终端长图。
+
+## 视频与原片检查
+
+固定制作脚本会完整解码并抽取关键帧，Agent 仍需查看每段字幕、放大区间及转场：不能遮住关键反馈、裁掉目标、文字出画或放大到模糊。原始录屏则核对目标页面、动作记录、采样时序和结尾状态，不要求字幕或编辑效果。
+
+独立视频链接按 `toolkit:playwright-cli` 使用隔离会话，清除继承的 CDP/remote endpoint，不覆盖用户业务页面；已有运行界面采集继续使用其正确 Profile/Session。记录引擎、viewport、DPR 和触摸参数，Chrome 的 iPhone 设备参数不能称作 Safari。
+
+在竖屏约 390–402px 宽及对应横屏中：
+
+1. 打开实际交付链接，确认加载视频而非登录页或错误文本。
+2. 使用当前截图中观察到的播放器控制条，实际播放、暂停、继续、跳转，确认 seek 已完成且帧已显示，再重新打开。
+3. 看字幕与局部细节是否足以支持本次判断，播放器控制条出现时是否遮挡；小字仍不可读时缩小取景、补局部图文或保留缺口。
+4. 按任务范围检查全屏、旋转。精确取样可以设置 `video.currentTime`，但这不能证明触摸进度条已通过。Chrome 自动播放不能外推到 iPhone。
+
+## Runweave 预览
+
+`preview.py` 专用于已配置 Runweave Backend 的 HTML 或 MP4 文件。它不创建公开文件服务，不转移文件到另一台服务器：传入文件必须存在于对应 Backend 机器，项目身份与路径须符合服务端检查。当前 HTML 接口限入口 1 MiB、同目录单个资源 5 MiB；视频使用独立 Range 入口，不把 MP4 塞进 HTML 静态资源通道。
+
+```bash
+python3 "$SKILL/scripts/preview.py" \
+  --file "$RUN/gallery/index.html" --project-id <实际项目ID> \
+  --profile local --viewer-base-url <手机实际可访问的Backend地址> \
+  --output "$RUN/gallery-links-01.json"
+
+python3 "$SKILL/scripts/preview.py" \
+  --file "$RUN/video/review.mp4" --project-id <实际项目ID> \
+  --profile local --viewer-base-url <手机实际可访问的Backend地址> \
+  --output "$RUN/video-links-01.json"
+```
+
+默认读取 `~/.runweave/settings.yaml` 中 `cli.profiles.<profile>` 的 `baseUrl/accessToken`，要求 0600 权限，需 PyYAML。没有该连接时不遍历凭据或读取应用密码。已有 API token 环境变量可用 `--token-env RUNWEAVE_PREVIEW_TOKEN --backend <已配置地址>`，参数只传变量名称，不传 token 值。
+
+脚本只向配置中的 Backend 发送 Bearer，先核对 viewer `/health` 的服务身份，再匿名核对 HEAD、类型、长度。视频检查 Range 206 与本地字节一致；HTML 检查 GET 与本地字节一致，其脚本、样式和图片还须实际打开核对。拒绝重定向，避免转发凭据或预览权限；新票据保存到新的 0600 JSON。读取 `url/expiresAt` 用于交付，不将链接 JSON、连接文件或素材提交 Git。
+
+票据不是永久链接；文件变化可能使旧票据失效。材料定稿后再生成，过期后换新输出文件续期。旧 `video.py preview --video ...` 仍转发到这套实现，不维护独立逻辑。
+
+Mac 文件路径与 `127.0.0.1` 只能用于本机；局域网入口依赖手机可达、Mac 唤醒与 Backend 运行。Agent 从同一机器访问自己的 LAN 地址不等于跨设备验证。远程转发可能只放行健康检查而不放行 `/html-preview/`、`/video-preview/`，以实际匿名读取为准；缺路由就说明，不擅自改网关、认证或新建隧道。
+
+## 真机与最终记录
+
+需要真机时沿用 `toolkit:agent-device` 的已保存目标和独立会话；核对手机实际网络打开、阅读、播放/拖动、旋转/全屏和重新打开。保存分享只在用户要求时验证。真机不可控时保留模拟结论与明确缺口，不换设备冒充目标手机。
+
+在任务产物目录另存 `review-check.json`，仅记录实际执行的检查：产物形式、运行环境与来源、每项动作和观察、证据路径、阅读判断、链接期限和访问前提，以及真机状态。未执行项用 `not-run`，不让生成器填充“验收通过”。
+
+`macActionsWhileViewing` 只在观察完整查看流程后填写次数，否则为 `null`。0 仅表示该流程没有要求人在 Mac 点击；Mac 保持在线、后台运行、网络恢复和链接续期仍是访问条件。

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

@@ -0,0 +1,84 @@
+# 图文材料数据合同 v1
+
+## 输入
+
+UTF-8 JSON，拒绝重复键、未知字段、NaN 和未知版本。文件路径相对 `--input-root`；`--input` 默认 `task.json`。根目录必须已存在。ID 为 1–80 位字母、数字、`-`、`_`，首位为字母或数字。
+
+| 对象   | 字段                                                                                                                               |
+| ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| root   | `schemaVersion: 1`、`task`、`assets: []`、`pages: []`                                                                              |
+| 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                                       |
+
+文字必填项须为非空字符串。时间按实际采集记录填写，建议带时区 ISO 8601；不知道则 `null`。版本、设备、对象身份等条件写在 scope、description 或关联文字记录中，`sourceRef` 给其原始位置或记录标识。各素材允许不同来源，但不能因此宣称同一事件。
+
+| type     | items 数量 | 素材 kind |
+| -------- | ---------- | --------- |
+| single   | 1          | image     |
+| compare  | 2          | image     |
+| sequence | 2–4        | image     |
+| text     | 1          | text      |
+
+`pages` 至少一项；数组顺序为阅读顺序。页面 ID 用于 `#page=<id>`，修改描述时保留 ID。
+
+`evidenceState` 为 `observed`（有观察材料）、`insufficient`（证据不足）、`not-run`（未执行），不含业务通过/失败判定。后两项的具体缺口应写在正文或 limitations 中；未执行又没有截图时用真实文字说明页，不造图。
+
+`sourceIds` 只引用 text 素材，可为空。PNG/JPEG 图片最大 32 MiB、宽高各最多 32768px；文字 TXT/MD/JSON 及输入 JSON 最大 2 MiB。JSON 素材也要求合法 JSON。PNG 校验结构和 CRC；JPEG 检查容器与常用 SOF 尺寸，完整解码由浏览器验证。若图片打不开，不能只依据 validate 成功交付。
+
+`crop` 为原 PNG 整数像素坐标，x/y 非负、width/height 为正且完整位于原图内。JPEG 仅允许完整展示，避免 EXIF 方向与坐标歧义。原图不被重采样或写回。
+
+## 最小可执行输入
+
+在同一输入目录准备真实的 `observation.txt`，再保存如下 `task.json`；把示例内容改成当前任务事实后执行。
+
+```json
+{
+  "schemaVersion": 1,
+  "task": {
+    "id": "current-task",
+    "title": "当前任务的核对结果",
+    "scope": "说明本次核对范围与环境",
+    "materialKind": "current",
+    "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": []
+    }
+  ]
+}
+```
+
+## 原始素材查看
+
+正文图片、标题旁的原图/原文和来源链接都在阅读器内部打开，不依赖弹窗或页面跳转。图片可切换实际尺寸并滚动；关闭后保持原来的页码和焦点。原图与原文文件仍单独保留，复制成果目录后可直接使用。Backend 的 HTML 预览沙箱与真机阅读仍须通过实际入口核对，不能仅凭本地打开推断。
+
+## 输出与错误
+
+`validate` 返回 JSON `{valid, pages, assets}`，不写文件。`build` 返回 `{output, index, pages}`。成功退出 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。
+
+生成失败不留下最终目录，已有输出拒绝覆盖。生成器用同目标的临时锁串行化生成；进程被强杀可能留下 `.gallery-lock` 和 `.gallery-*`，核对没有相同目标构建在运行后，才清理这些本次临时文件或换新输出目录。不要删除旧成果绕过覆盖检查。
+
+未知版本拒绝；不自动迁移。每份报告带模板副本，后续升级不改变旧报告。生成器只处理显式列出的素材，不自动爬取来源、执行命令或读整个历史。
+
+`serve` 只绑定 `127.0.0.1`，只允许清单中的文件，不开放目录列表和写接口；根目录越界及符号链接逃逸均拒绝。素材路径不接受绝对路径、`..`、反斜线、冒号或远程 URL。页面文本转义显示，不支持任务传入 HTML。输入输出根目录应由当前用户控制，不将此本机工具部署为多用户公共服务。

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

@@ -0,0 +1,34 @@
+# 取景与配文
+
+## 问题决定素材
+
+| 要判断什么       | 最少材料                               | 容易误读的地方                               |
+| ---------------- | -------------------------------------- | -------------------------------------------- |
+| 布局、控件可见性 | 目标区域及所属区域的定位锚点           | 切掉上下文后看不出位置；大块空白压缩关键文字 |
+| 遮挡、安全区     | 遮挡物、目标及相关边缘同时入画         | 只截可见部分，无法判断是否仍被覆盖           |
+| 状态变化         | 同一对象的前后图，说明改变了哪些条件   | 不同窗口或宽度不能直接当作修复前后           |
+| 多步流程         | 入口、关键分支、结果，2–4 张关键图     | 离散截图不证明连续动作或实际时长             |
+| 保存、重启、恢复 | 可见结果与真实事件、身份或状态核对记录 | 成功提示或终点图不证明持久化                 |
+| CLI、API 或后台  | 可复制的真实结果文字与来源             | 不需要截成很长的终端图片                     |
+
+页数由问题决定，不用“必须三张”一类数量目标驱动采集。需要判断重复稳定性时保留尝试条件和次数；没有这类证据就保留缺口。
+
+## 截图如何放
+
+原始图片保持字节不变。`crop` 仅设置阅读器显示窗口，完整原图仍可打开。第一版只允许 PNG 取景，JPEG 可完整展示；JPEG 的 EXIF 方向可能与像素坐标不一致，需要取景时在原界面重新采集 PNG，不修改或补画原图。
+
+在实际阅读尺寸检查关键文字。太小则缩小取景范围或拆页；不要为了整齐强行把所有图片压进相同尺寸。竖屏原图保持比例；宽图对照在手机上上下排列。图外“看这里”应指向可辨认的具体对象，不重复描述整张图。
+
+对照前核对目标、运行端、版本、尺寸与条件；不同条件必须说明。有结果图但没有前图时退回单图，不能生成假前图。需要真实运动或闪烁证据的任务不以截图模板替代原采集方式。
+
+## 文案如何写
+
+标题说明本页要核对的结果；建议 12–24 个中文字。正文以 1–2 句交代“条件、动作、实际观察”，建议 40–100 字。软长度目标不覆盖准确性要求。
+
+- 历史关注区案例：写“A 已从关注区移出，但仍在下方项目列表中”；不写“A 被删除”。到期 fixture 不等于真实等待一小时。
+- 历史配置案例：只有配置截图就写“当前显示四角色配置”；有受控重启、接口和文件哈希记录才可以写“重启后仍保留”，并链接相关记录。
+- 历史跨端案例：两端显示相同状态可比较表达；没有匹配终端和事件身份时，不写“同一任务同步成功”。
+
+`observed` 只表示有观察材料，观察到的也可能是失败；不要将它渲染或措辞为业务通过。`insufficient`、`not-run` 配合本页具体缺口。通用环境边界放任务说明，直接影响本页判断的缺口放本页正文或 limitations。
+
+截图事实、记录事实和推断要可区分。文案校对时对照原图和来源逐页检查；生成器不会替 Agent 判断结论真假。不要复制凭据、环境变量全集或无关日志。

package/payload/plugins/toolkit/skills/acceptance/references/video.md

@@ -0,0 +1,52 @@
+# 视频输入与制作
+
+## 生成
+
+只在需要编辑视频时运行 `video.py doctor`。制作依赖 Python 3.9+、ffmpeg/ffprobe 和本机 OpenScreen；已装软件只核对缺失项，不自动改全局 MCP 配置或关闭用户应用。首次安装核对[官方发布](https://github.com/getopenscreen/openscreen/releases)的平台、版本、校验值与签名，沿用已有授权。
+
+`video.py build --input <video.json> --output <新目录>` 直接调用 OpenScreen stdio MCP，不要求当前 Agent 热加载 MCP 工具。每次新建自己的工程/checkpoint，固定字幕与缩放、720p/30 FPS 导出，再压缩为静音 H.264 fast-start MP4，完整解码并抽帧。输出包含 `review.mp4`、主片、工程文档、输入、来源哈希、调用记录与制作 manifest。`rendered` 仅表示制作成功，不表示业务验收或手机通过；实际检查另按[交付规则](delivery.md)记录。
+
+## 已有原片
+
+把当前任务的原片放在独立产物目录，或引用已存在的绝对路径。不要移动、覆盖历史证据。`video.json` 的相对路径相对于它自身所在目录解析，不依赖调用脚本时的工作目录。
+
+```json
+{
+  "schemaVersion": 1,
+  "title": "文件预览的操作变化",
+  "video": "recording.mp4",
+  "source": {
+    "surface": "installed-stable-web",
+    "description": "本次实际打开的版本、对象和操作范围",
+    "captureMethod": "playwright-viewport-screenshot-loop",
+    "evidence": "capture.json"
+  },
+  "callouts": [
+    { "start": 0, "end": 4.5, "text": "先看操作结果" },
+    { "start": 4.6, "end": 9, "text": "再核对关键变化" }
+  ],
+  "zooms": [
+    { "start": 5.5, "end": 8, "scale": 1.5, "focus": { "x": 0.58, "y": 0.35 } }
+  ],
+  "captionStyle": { "fontSize": 64, "x": 50, "y": 74 },
+  "sampleTimes": [2, 7]
+}
+```
+
+示例时间需要按真实操作替换，不是固定业务步骤。字段：
+
+- `schemaVersion` 固定为 1；`title`、`video`、`source.surface/description/captureMethod` 必填。来源是 Agent 记录的事实，脚本不能独立证明它；用当前任务的 manifest、采集记录或版本回执复核。可在 `source` 中增加 `historical`、设备和证据路径。
+- `callouts` 与 `zooms` 可省略或为空；各自按时间排序、不重叠，`0 <= start < end <= 原片时长`。原片不剪切、不加速，因此时间与原片一致。
+- 字幕用简短、事实性的中文说明动作或结果。不要把“通过”“已修复”写入尚未实际核对的片段。
+- `scale` 使用 OpenScreen 六档缩放：`1.25 / 1.5 / 1.8 / 2.2 / 3.5 / 5`。脚本映射到 MCP 的 `depth`；`depth` 是档位，不是倍率。2.1.2 的 MCP 会给 `depth` 填默认值，直接传 `customScale` 可能被判为同时传入两种缩放参数；固定脚本用已验证的档位调用。
+- `focus.x/y` 为原片中的 0–1 坐标；先看原片，再确定要展示的区域。不能只放大鼠标而裁掉反馈。
+- `captionStyle` 仅支持字号和中心位置，默认 `64/50/74`，字号按 OpenScreen 的 1080p 设计尺寸定义；720p 导出会缩放。播放器覆盖区依设备而异，必须检查最终画面。
+- `sampleTimes` 是最终 MP4 的抽帧时间，必须在结束前至少 0.05 秒。未提供时取每个字幕和放大区间中点；不限制关键帧数量，但不需要逐帧给 Agent 看整段视频。
+
+制作依赖：Python 3.9+ 标准库、`ffmpeg`、`ffprobe`、OpenScreen 的 MCP。macOS 默认可执行文件为 `/Applications/Openscreen.app/Contents/MacOS/Openscreen`；其他安装位置用 `video.py --openscreen <绝对路径> doctor/build ...`。脚本不会安装软件或修改全局 MCP 配置。
+
+## OpenScreen 调用依据
+
+固定脚本在本机 2.1.2 上验证，启动时读取实际 `initialize/tools/list`。工具 schema 与版本保存在产物中；工具缺失、编辑拒绝或超时均停止，不自动重试写操作，不直接改 OpenScreen 工程文件。
+
+官方入口：[CLI](https://getopenscreen.com/docs/cli/)、[Agent 接口](https://getopenscreen.com/docs/ai-editing/)。版本升级后先对真实原片运行 `doctor/build`，检查工程、渲染与关键帧，再调整调用合同。此技能未复制或捆绑 OpenScreen 本体。