@runweave/server-linux-x64 0.1.8 → 0.1.10

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

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""Prepare a Playwright CLI capture wrapper; encode real timestamped frames."""
+import argparse
+import json
+from pathlib import Path
+import sys
+sys.dont_write_bytecode = True
+from common import duration, number, probe, run, write_json
+
+
+def prepare(args):
+    action = args.actions.read_text().strip().rstrip(';')
+    if '=>' not in action or not action.startswith('async'):
+        raise ValueError('actions must contain one async arrow function, not a module')
+    number(args.fps, 1, 10, 'fps')
+    clip = None
+    if args.clip:
+        values = [float(x) for x in args.clip.split(',')]
+        if len(values) != 4 or min(values[:2]) < 0 or min(values[2:]) <= 0:
+            raise ValueError('clip must be x,y,width,height with positive dimensions')
+        for index, value in enumerate(values):
+            number(value, 0 if index < 2 else 0.001, 100000, 'clip coordinate')
+        clip = dict(zip(('x', 'y', 'width', 'height'), values))
+    out = args.output.resolve()
+    out.mkdir(parents=True, exist_ok=False)
+    (out / 'frames').mkdir()
+    write_json(out / 'capture-plan.json', {'actions': str(args.actions.resolve()), 'maxFps': args.fps,
+                                          'clip': clip, 'requires': 'repository-pinned playwright cli run-code'})
+    # This expression is evaluated by the existing Playwright CLI page, never launches a browser itself.
+    code = '''async page => {
+  const perform = ACTION;
+  const frames = [];
+  const startPage = {url: await page.url(), title: await page.title(), viewport: page.viewportSize()};
+  const captureStartedAt = Date.now();
+  const clock = {now: () => (Date.now() - captureStartedAt) / 1000};
+  let running = true;
+  let captureError;
+  const shot = async () => {
+    const atSeconds = frames.length ? clock.now() : 0;
+    const path = FRAME_ROOT + '/' + String(frames.length).padStart(6, '0') + '.png';
+    await page.screenshot({path, fullPage: false, ...CLIP});
+    frames.push({path, atSeconds});
+  };
+  await shot();
+  const recorder = (async () => {
+    try {
+      while (running) {
+        await page.waitForTimeout(INTERVAL);
+        if (running) await shot();
+      }
+    } catch (error) {captureError = error; running = false;}
+  })();
+  let result;
+  try {result = await perform(page, clock);}
+  finally {running = false; await recorder;}
+  if (captureError) throw captureError;
+  await shot();
+  return {schemaVersion: 1, captureMethod: 'playwright-viewport-screenshot-loop',
+    startedAt: new Date(captureStartedAt).toISOString(), endedAt: new Date().toISOString(),
+    durationSeconds: clock.now(), viewport: page.viewportSize(), startPage,
+    endPage: {url: await page.url(), title: await page.title(), viewport: page.viewportSize()}, clip: CLIP_VALUE,
+    maxFps: FPS_VALUE, frames, actions: result ?? null,
+    limitation: 'Sampled screenshots, not high-FPS animation or latency evidence'};
+}'''
+    # Replace unique markers before injecting the task's actual action code.
+    for key, value in [('FRAME_ROOT', json.dumps(str(out / 'frames'))),
+                       ('CLIP_VALUE', json.dumps(clip)), ('CLIP', json.dumps({'clip': clip} if clip else {})),
+                       ('INTERVAL', str(1000 / args.fps)), ('FPS_VALUE', str(args.fps))]:
+        code = code.replace(key, value)
+    code = code.replace('ACTION', '(' + action + ')')
+    (out / 'run-code.js').write_text(code)
+    print(json.dumps({'script': str(out / 'run-code.js'), 'maxFps': args.fps,
+                      'next': 'Run with owned playwright cli session; save --raw result as capture.json'}))
+
+
+def encode(args):
+    data = json.loads(args.input.read_text())
+    if data.get('schemaVersion') != 1 or data.get('captureMethod') != 'playwright-viewport-screenshot-loop':
+        raise ValueError('Expected successful capture.py result, not CLI errors or a snapshot')
+    total = number(data.get('durationSeconds'), 0.001, 86400, 'durationSeconds')
+    frames = data.get('frames', [])
+    if len(frames) < 2:
+        raise ValueError('At least two captured frames are required')
+    if args.output.exists():
+        raise FileExistsError('Refusing to overwrite an existing recording')
+    times, paths = [], []
+    for frame in frames:
+        at = number(frame.get('atSeconds'), 0, total, 'frame.atSeconds')
+        if times and at <= times[-1]:
+            raise ValueError('Frame timestamps must increase strictly')
+        path = (args.input.resolve().parent / frame['path']).resolve(strict=True)
+        if not path.is_file():
+            raise ValueError('Frame path must be a file')
+        times.append(at)
+        paths.append(path)
+    if times[0] != 0:
+        raise ValueError('First frame must start at zero')
+    concat = args.output.with_suffix('.ffconcat')
+    lines = ['ffconcat version 1.0']
+    for i, path in enumerate(paths):
+        quoted = str(path).replace("'", "'\\''")
+        end = times[i + 1] if i + 1 < len(times) else total
+        lines.extend([f"file '{quoted}'", f'duration {max(end - times[i], 1 / 30):.6f}'])
+    lines.append("file '" + str(paths[-1]).replace("'", "'\\''") + "'")
+    with concat.open('x') as f:
+        f.write('\n'.join(lines) + '\n')
+    run(['ffmpeg', '-hide_banner', '-loglevel', 'error', '-n', '-safe', '0', '-i', str(concat),
+         '-t', str(total), '-vf', 'pad=ceil(iw/2)*2:ceil(ih/2)*2,format=yuv420p', '-r', '30',
+         '-c:v', 'libx264', '-preset', 'fast', '-crf', '20', '-movflags', '+faststart', str(args.output)])
+    actual = duration(probe(args.output))
+    if abs(actual - total) > 0.1:
+        raise ValueError('Encoded duration does not match captured duration')
+    print(json.dumps({'recording': str(args.output.resolve()), 'durationSeconds': actual,
+                      'capturedFrames': len(frames), 'timing': 'measured frame timestamps, rounded to 30 FPS'}))
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest='command', required=True)
+    make = sub.add_parser('prepare', help='Wrap real actions without starting a browser')
+    make.add_argument('--actions', type=Path, required=True)
+    make.add_argument('--output', type=Path, required=True)
+    make.add_argument('--fps', type=float, default=4)
+    make.add_argument('--clip', help='Observed viewport region: x,y,width,height')
+    movie = sub.add_parser('encode', help='Encode successful CLI capture result, preserving frame timing')
+    movie.add_argument('--input', type=Path, required=True)
+    movie.add_argument('--output', type=Path, required=True)
+    args = parser.parse_args()
+    prepare(args) if args.command == 'prepare' else encode(args)
+
+
+if __name__ == '__main__':
+    try:
+        main()
+    except Exception as error:
+        print(json.dumps({'error': str(error)}, ensure_ascii=False), file=sys.stderr)
+        sys.exit(1)

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

@@ -0,0 +1,63 @@
+"""Shared local media and preview helpers; no optional dependencies at import time."""
+import hashlib
+import json
+import math
+import os
+import subprocess
+import urllib.parse
+import urllib.request
+
+def write_json(path, value, private=False):
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600 if private else 0o666)
+    with os.fdopen(fd, 'w', encoding='utf-8') as f:
+        json.dump(value, f, ensure_ascii=False, indent=2)
+        f.write('\n')
+
+def run(command):
+    return subprocess.run(command, check=True, capture_output=True, text=True).stdout
+
+def probe(path):
+    return json.loads(run(['ffprobe', '-v', 'error', '-show_streams',
+                           '-show_format', '-of', 'json', str(path)]))
+
+def duration(info):
+    value = float(info['format']['duration'])
+    if not math.isfinite(value) or value <= 0:
+        raise ValueError('Video duration must be finite and positive')
+    if not any(s['codec_type'] == 'video' for s in info['streams']):
+        raise ValueError('No video stream')
+    return value
+
+def digest(path):
+    h = hashlib.sha256()
+    with path.open('rb') as f:
+        for chunk in iter(lambda: f.read(1024 * 1024), b''):
+            h.update(chunk)
+    return h.hexdigest()
+
+def number(value, low, high, label):
+    if (isinstance(value, bool) or not isinstance(value, (int, float)) or
+            not math.isfinite(value) or not low <= value <= high):
+        raise ValueError(f'{label} must be a finite number in [{low}, {high}]')
+    return value
+
+def text(value, label):
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f'{label} must be nonempty text')
+    return value
+
+def http(url, headers=None, body=None, method=None):
+    request = urllib.request.Request(url, data=body, headers=headers or {}, method=method)
+    # Never forward an API token or preview capability through redirects.
+    class NoRedirect(urllib.request.HTTPRedirectHandler):
+        def redirect_request(self, req, fp, code, msg, hdrs, newurl):
+            return None
+    with urllib.request.build_opener(NoRedirect).open(request, timeout=20) as response:
+        return response.status, response.headers, response.read()
+
+def base_url(value):
+    parsed = urllib.parse.urlsplit(value)
+    if (parsed.scheme not in ('http', 'https') or not parsed.netloc or parsed.username or
+            parsed.password or parsed.query or parsed.fragment):
+        raise ValueError('Expected HTTP(S) base URL without credentials/query/fragment')
+    return value.rstrip('/')

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

@@ -0,0 +1,353 @@
+#!/usr/bin/env python3
+"""Build portable, local evidence galleries. Python 3.9+; no third-party packages."""
+import argparse
+import copy
+import hashlib
+import html
+import json
+import os
+from pathlib import Path, PurePosixPath
+import re
+import shutil
+import struct
+import sys
+import tempfile
+import zlib
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import unquote, urlsplit
+
+TEMPLATE_VERSION = '1.1.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
+MAX_TEXT = 2 * 1024 * 1024
+
+
+class Invalid(ValueError):
+    pass
+
+
+def require(ok, where, message):
+    if not ok:
+        raise Invalid(f'{where}: {message}')
+
+
+def fields(value, where, required, optional=()):
+    require(isinstance(value, dict), where, '需要对象')
+    missing = set(required) - value.keys()
+    unknown = value.keys() - set(required) - set(optional)
+    require(not missing, where, f'缺少字段 {sorted(missing)}')
+    require(not unknown, where, f'未知字段 {sorted(unknown)}')
+
+
+def string(value, where, nullable=False):
+    if value is None and nullable:
+        return
+    require(isinstance(value, str) and bool(value.strip()), where, '需要非空字符串')
+
+
+def strings(value, where):
+    require(isinstance(value, list), where, '需要字符串数组')
+    for i, item in enumerate(value):
+        string(item, f'{where}[{i}]')
+
+
+def identifier(value, where):
+    require(isinstance(value, str) and ID.fullmatch(value), where, 'ID 仅支持字母、数字、-、_，长度 1–80')
+
+
+def local_file(root, relative):
+    string(relative, 'path')
+    parts = PurePosixPath(relative).parts
+    require(not relative.startswith('/') and '\\' not in relative and ':' not in relative
+            and '..' not in parts, relative, '需要根目录内的相对路径')
+    target = (root / relative).resolve(strict=True)
+    require(target.is_relative_to(root) and target.is_file(), relative, '文件不存在或超出素材目录')
+    return target
+
+
+def read_file(path, limit):
+    require(path.stat().st_size <= limit, path.name, f'超过 {limit} 字节限制')
+    with path.open('rb') as stream:
+        data = stream.read(limit + 1)
+    require(len(data) <= limit, path.name, '读取时文件超过大小限制')
+    return data
+
+
+def image_info(data, suffix, where):
+    """Check container structure and dimensions; browser acceptance verifies decoding."""
+    if suffix == '.png':
+        require(data.startswith(b'\x89PNG\r\n\x1a\n'), where, '不是 PNG')
+        pos, size, has_data, ended = 8, None, False, False
+        while pos + 12 <= len(data):
+            length = struct.unpack('>I', data[pos:pos + 4])[0]
+            chunk = data[pos + 4:pos + 8]
+            end = pos + 8 + length
+            require(end + 4 <= len(data), where, 'PNG chunk 被截断')
+            require(zlib.crc32(data[pos + 4:end]) & 0xffffffff == struct.unpack('>I', data[end:end + 4])[0], where, 'PNG CRC 错误')
+            if pos == 8:
+                require(chunk == b'IHDR' and length == 13, where, '缺少 PNG IHDR')
+                size = struct.unpack('>II', data[pos + 8:pos + 16])
+            has_data |= chunk == b'IDAT'
+            pos = end + 4
+            if chunk == b'IEND':
+                require(length == 0 and pos == len(data), where, 'PNG 结束块不合法')
+                ended = True
+                break
+        require(ended and has_data, where, 'PNG 缺少数据或结束块')
+    else:
+        require(data.startswith(b'\xff\xd8') and data.endswith(b'\xff\xd9'), where, '不是完整 JPEG')
+        pos, size = 2, None
+        while pos < len(data) - 2:
+            require(data[pos] == 255, where, 'JPEG marker 不合法')
+            while pos < len(data) and data[pos] == 255:
+                pos += 1
+            require(pos < len(data), where, 'JPEG 被截断')
+            marker = data[pos]
+            pos += 1
+            if marker in (0xda, 0xd9):
+                break
+            if marker == 1 or 0xd0 <= marker <= 0xd7:
+                continue
+            require(pos + 2 <= len(data), where, 'JPEG 被截断')
+            length = struct.unpack('>H', data[pos:pos + 2])[0]
+            require(length >= 2 and pos + length <= len(data), where, 'JPEG segment 被截断')
+            if marker in (0xc0, 0xc1, 0xc2):
+                require(length >= 8, where, 'JPEG SOF 不合法')
+                height, width = struct.unpack('>HH', data[pos + 3:pos + 7])
+                size = (width, height)
+            pos += length
+        require(size is not None, where, '不支持的 JPEG 编码或缺少尺寸')
+    require(size and all(0 < n <= 32768 for n in size), where, '图片尺寸不合法或超出 32768px')
+    return dict(width=size[0], height=size[1])
+
+
+def parse_json(data):
+    def pairs(items):
+        result = {}
+        for key, value in items:
+            require(key not in result, key, '重复 JSON 字段')
+            result[key] = value
+        return result
+    return json.loads(data.decode('utf-8'), object_pairs_hook=pairs,
+                      parse_constant=lambda value: (_ for _ in ()).throw(Invalid(f'非法 JSON 数字 {value}')))
+
+
+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')
+    meta = task['task']
+    fields(meta, 'task', ['id', 'title', 'scope', 'materialKind', 'limitations'])
+    identifier(meta['id'], 'task.id')
+    for key in ('title', 'scope'):
+        string(meta[key], f'task.{key}')
+    require(meta['materialKind'] in ('current', 'historical'), 'task.materialKind', '需要 current/historical')
+    strings(meta['limitations'], 'task.limitations')
+    require(isinstance(task['assets'], list), 'assets', '需要数组')
+    assets, payloads, image_sizes = {}, {}, {}
+    for i, asset in enumerate(task['assets']):
+        where = f'assets[{i}]'
+        fields(asset, where, ['id', 'kind', 'path', 'label', 'origin'])
+        identifier(asset['id'], where + '.id')
+        require(asset['id'] not in assets, where, '重复素材 ID')
+        require(asset['kind'] in ('image', 'text'), where, 'kind 需要 image/text')
+        string(asset['label'], where + '.label')
+        fields(asset['origin'], where + '.origin', ['surface', 'capturedAt', 'sourceRef'])
+        for key, value in asset['origin'].items():
+            string(value, where + '.origin.' + key, nullable=True)
+        source = local_file(root, asset['path'])
+        suffix = source.suffix.lower()
+        data = read_file(source, MAX_FILE if asset['kind'] == 'image' else MAX_TEXT)
+        if asset['kind'] == 'image':
+            require(suffix in ('.png', '.jpg', '.jpeg'), where, '图片仅支持 PNG/JPEG')
+            image_sizes[asset['id']] = image_info(data, suffix, where)
+        else:
+            require(suffix in ('.txt', '.md', '.json'), where, '文字仅支持 TXT/MD/JSON')
+            data.decode('utf-8')
+            if suffix == '.json':
+                parse_json(data)
+        assets[asset['id']] = asset
+        payloads[asset['id']] = (data, suffix)
+    require(isinstance(task['pages'], list) and len(task['pages']) > 0, 'pages', '至少需要一页')
+    seen = set()
+    for i, page in enumerate(task['pages']):
+        where = f'pages[{i}]'
+        fields(page, where, ['id', 'type', 'title', 'description', 'evidenceState', 'items', 'sourceIds'], ['lookAt', 'limitations'])
+        identifier(page['id'], where + '.id')
+        require(page['id'] not in seen, where, '重复页 ID')
+        seen.add(page['id'])
+        for key in ('title', 'description', 'lookAt'):
+            if key in page:
+                string(page[key], where + '.' + key)
+        strings(page.get('limitations', []), where + '.limitations')
+        require(page['evidenceState'] in ('observed', 'insufficient', 'not-run'), where, '未知 evidenceState')
+        require(isinstance(page['type'], str) and page['type'] in ('single', 'compare', 'sequence', 'text'), where, '未知页型')
+        items = page['items']
+        require(isinstance(items, list), where, 'items 需要数组')
+        low, high = {'single': (1, 1), 'compare': (2, 2), 'sequence': (2, 4), 'text': (1, 1)}[page['type']]
+        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'])
+            string(item['assetId'], iw + '.assetId')
+            string(item['label'], iw + '.label')
+            require(item['assetId'] in assets, iw, '素材 ID 不存在')
+            asset = assets[item['assetId']]
+            kind = 'text' if page['type'] == 'text' else 'image'
+            require(asset['kind'] == kind, iw, '素材类型与页型不匹配')
+            if kind == 'image':
+                string(item.get('alt'), iw + '.alt')
+            else:
+                require('crop' not in item and 'alt' not in item, iw, '文字项不接受 crop/alt')
+            if 'crop' in item:
+                crop = item['crop']
+                fields(crop, iw + '.crop', ['x', 'y', 'width', 'height'])
+                require(all(type(v) is int for v in crop.values()), iw, '取景参数必须为整数')
+                size = image_sizes[item['assetId']]
+                require(crop['x'] >= 0 and crop['y'] >= 0 and crop['width'] > 0 and crop['height'] > 0
+                        and crop['x'] + crop['width'] <= size['width']
+                        and crop['y'] + crop['height'] <= size['height'], iw, '取景超出原图或尺寸不合法')
+                require(payloads[item['assetId']][1] == '.png', iw, 'JPEG 取景请先重新采集 PNG；避免 EXIF 方向歧义')
+        strings(page['sourceIds'], where + '.sourceIds')
+        for source_id in page['sourceIds']:
+            require(source_id in assets and assets[source_id]['kind'] == 'text', where, 'sourceIds 只能引用存在的文字素材')
+    return task, payloads, image_sizes, hashlib.sha256(raw).hexdigest()
+
+
+def dump(path, value):
+    path.write_text(json.dumps(value, ensure_ascii=False, indent=2) + '\n', encoding='utf-8')
+
+
+def build(loaded, output):
+    task, payloads, sizes, input_hash = loaded
+    output = output.absolute()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    # Serializes concurrent builds of the same target without replacing old evidence.
+    lock = output.parent / ('.' + output.name + '.gallery-lock')
+    fd = os.open(lock, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    os.close(fd)
+    stage = None
+    try:
+        require(not output.exists() and not output.is_symlink(), 'output', '目标已存在，请使用新目录')
+        stage = Path(tempfile.mkdtemp(prefix='.gallery-', dir=output.parent))
+        (stage / 'assets').mkdir()
+        snapshot = copy.deepcopy(task)
+        display = copy.deepcopy(task)
+        manifest = {'schemaVersion': 1, 'templateVersion': TEMPLATE_VERSION,
+                    'inputSha256': input_hash, 'assets': []}
+        for index, asset in enumerate(snapshot['assets']):
+            data, suffix = payloads[asset['id']]
+            # Numeric prefixes also keep distinct IDs safe on case-insensitive disks.
+            relative = f'assets/{index + 1:04d}-{asset["id"]}{suffix}'
+            (stage / relative).write_bytes(data)
+            digest = hashlib.sha256(data).hexdigest()
+            asset['path'] = relative
+            shown = display['assets'][index]
+            shown['path'] = relative
+            shown.update(sizes.get(asset['id'], {}))
+            if asset['kind'] == 'text':
+                shown['text'] = data.decode('utf-8')
+            manifest['assets'].append({'id': asset['id'], 'path': relative, 'sha256': digest})
+        display['templateVersion'] = TEMPLATE_VERSION
+        embedded = json.dumps(display, ensure_ascii=False).replace('&', '\\u0026').replace('<', '\\u003c').replace('>', '\\u003e')
+        template = (TEMPLATES / 'reader.html').read_text(encoding='utf-8')
+        # Split once so placeholders in user-supplied titles cannot be interpreted.
+        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'):
+            shutil.copyfile(TEMPLATES / name, stage / name)
+        dump(stage / 'task.json', snapshot)
+        dump(stage / 'manifest.json', manifest)
+        require(not output.exists() and not output.is_symlink(), 'output', '目标已存在')
+        stage.rename(output)
+        stage = None
+    finally:
+        if stage is not None:
+            shutil.rmtree(stage)
+        lock.unlink()
+    return {'output': str(output), 'index': str(output / 'index.html'), 'pages': len(task['pages'])}
+
+
+def serve(directory, port):
+    root = directory.resolve(strict=True)
+    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':
+        allowed.add('viewer.css')
+    allowed.update(asset['path'] for asset in manifest['assets'])
+    for relative in allowed:
+        local_file(root, relative)
+    mime = {'.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8',
+            '.css': 'text/css; charset=utf-8', '.png': 'image/png', '.jpg': 'image/jpeg',
+            '.jpeg': 'image/jpeg', '.json': 'application/json; charset=utf-8'}
+
+    class Handler(BaseHTTPRequestHandler):
+        def do_GET(self):
+            self.send_file(False)
+
+        def do_HEAD(self):
+            self.send_file(True)
+
+        def send_file(self, head):
+            relative = unquote(urlsplit(self.path).path).removeprefix('/') or 'index.html'
+            try:
+                require(relative in allowed, relative, '不在成果清单内')
+                target = local_file(root, relative)
+                data = read_file(target, MAX_FILE * 8)
+            except (Invalid, OSError, ValueError):
+                self.send_error(404, 'Not found')
+                return
+            self.send_response(200)
+            self.send_header('Content-Type', mime.get(target.suffix.lower(), 'text/plain; charset=utf-8'))
+            self.send_header('Content-Length', str(len(data)))
+            self.send_header('X-Content-Type-Options', 'nosniff')
+            self.send_header('Cache-Control', 'no-store')
+            self.send_header('Referrer-Policy', 'no-referrer')
+            self.end_headers()
+            if not head:
+                self.wfile.write(data)
+
+        def log_message(self, *_args):
+            pass
+
+    with ThreadingHTTPServer(('127.0.0.1', port), Handler) as server:
+        print(json.dumps({'url': f'http://127.0.0.1:{server.server_port}/', 'pid': os.getpid(),
+                          'directory': str(root), 'stop': '前台按 Ctrl-C；后台停止前核对 PID 与完整命令'}, ensure_ascii=False), flush=True)
+        try:
+            server.serve_forever()
+        except KeyboardInterrupt:
+            pass
+
+
+def main():
+    parser = argparse.ArgumentParser(description='本地图文验收阅读器：validate / build / serve')
+    sub = parser.add_subparsers(dest='command', required=True)
+    for name in ('validate', 'build'):
+        command = sub.add_parser(name)
+        command.add_argument('--input-root', type=Path, required=True)
+        command.add_argument('--input', default='task.json')
+        if name == 'build':
+            command.add_argument('--output', 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)
+    args = parser.parse_args()
+    try:
+        if args.command == 'serve':
+            require(0 <= args.port <= 65535, 'port', '端口范围 0–65535')
+            serve(args.directory, args.port)
+            return
+        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'])}
+        print(json.dumps(result, ensure_ascii=False))
+    except (Invalid, OSError, ValueError, KeyError, TypeError) as error:
+        print(f'gallery: {error}', file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

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

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""Issue scoped Runweave preview links for HTML galleries or MP4 videos."""
+import argparse
+from datetime import datetime, timedelta, timezone
+import json
+import os
+from pathlib import Path
+import sys
+import urllib.parse
+sys.dont_write_bytecode = True
+from common import base_url, http, write_json
+
+
+def configure_parser(parser, default_kind='auto'):
+    parser.add_argument('--file', '--video', dest='file', type=Path, required=True,
+                        help='Local HTML or MP4; --video is a legacy alias')
+    parser.add_argument('--kind', choices=['auto', 'html', 'video'], default=default_kind)
+    parser.add_argument('--project-id', required=True)
+    parser.add_argument('--viewer-base-url', required=True)
+    parser.add_argument('--profile', default='local')
+    parser.add_argument('--settings', type=Path, default=Path.home() / '.runweave/settings.yaml')
+    parser.add_argument('--token-env', help='Name of an existing API-token environment variable')
+    parser.add_argument('--backend', help='Configured Backend URL; required with --token-env')
+    parser.add_argument('--output', type=Path, required=True)
+
+
+def preview(args):
+    file = args.file.resolve(strict=True)
+    if not file.is_file():
+        raise ValueError('Preview input must be a regular file')
+    kind = args.kind
+    if kind == 'auto':
+        kind = 'html' if file.suffix.lower() in ('.html', '.htm') else 'video'
+    if ((kind == 'html' and file.suffix.lower() not in ('.html', '.htm')) or
+            (kind == 'video' and file.suffix.lower() != '.mp4')):
+        raise ValueError('Expected HTML or MP4 input matching preview kind')
+    if args.output.exists() or args.output.is_symlink():
+        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')
+    if args.token_env:
+        if not args.backend:
+            raise ValueError('--token-env requires --backend')
+        token = os.environ[args.token_env]
+        local = base_url(args.backend)
+    else:
+        if args.settings.stat().st_mode & 0o077:
+            raise ValueError('Connection settings must be private (0600)')
+        try:
+            import yaml
+        except ImportError as error:
+            raise ValueError('Profile preview requires PyYAML; use --token-env with --backend otherwise') from error
+        config = yaml.safe_load(args.settings.read_text())['cli']['profiles'][args.profile]
+        token = config['accessToken']
+        local = base_url(config['baseUrl'])
+    viewer = base_url(args.viewer_base_url)
+    identity = json.loads(http(local + '/health')[2]).get('serviceInstanceId')
+    if not identity or json.loads(http(viewer + '/health')[2]).get('serviceInstanceId') != identity:
+        raise ValueError('Viewer and configured Backend service identities differ')
+    payload = json.dumps({'path': str(file)}).encode()
+    _, _, body = http(local + '/api/terminal/project/' + urllib.parse.quote(args.project_id, safe='') +
+                      '/preview/' + kind + '-ticket', {'Authorization': 'Bearer ' + token,
+                      'Content-Type': 'application/json'}, payload, 'POST')
+    ticket = json.loads(body)
+    path = ticket['path']
+    if not path.startswith('/' + kind + '-preview/') or urllib.parse.urlsplit(path).netloc:
+        raise ValueError('Unexpected preview-ticket path')
+    url = viewer + path
+    status, headers, _ = http(url, method='HEAD')
+    mime = 'text/html' if kind == 'html' else 'video/mp4'
+    if (status != 200 or headers.get('Content-Type', '').split(';')[0] != mime or
+            int(headers.get('Content-Length', '-1')) != file.stat().st_size):
+        raise ValueError('Anonymous preview HEAD does not match local input')
+    now = datetime.now(timezone.utc)
+    expires = int(ticket['expiresIn'])
+    receipt = {'url': url, 'file': str(file), 'kind': kind, 'backendServiceInstanceId': identity,
+               'viewerBaseUrl': viewer, 'issuedAt': now.isoformat(), 'expiresIn': expires,
+               'expiresAt': (now + timedelta(seconds=expires)).isoformat(), 'headStatus': 200,
+               'physicalPhoneReachability': 'not-verified',
+               'hostPrerequisites': ['Mac awake', 'Backend running', 'viewer route reachable', 'ticket valid']}
+    if kind == 'video':
+        status, headers, content = http(url, headers={'Range': 'bytes=0-1023'})
+        with file.open('rb') as f:
+            expected = f.read(1024)
+        if status != 206 or content != expected or headers.get('Accept-Ranges') != 'bytes':
+            raise ValueError('Anonymous Range request did not match local bytes')
+        receipt.update(video=str(file), rangeStatus=206, rangeMatchesLocal=True)
+    else:
+        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,
+                       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))
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    configure_parser(parser)
+    preview(parser.parse_args())
+
+
+if __name__ == '__main__':
+    try:
+        main()
+    except Exception as error:
+        print(json.dumps({'error': str(error), 'automaticRetry': False}, ensure_ascii=False), file=sys.stderr)
+        sys.exit(1)