@hybridlabor-api/aos 4.6.5 → 4.7.0

package/skills/global_config/editable-design/references/replay-contract.md

@@ -0,0 +1,169 @@
+# Agent design replay contract
+
+Read this only when recording, generating, or diagnosing a poster Replay.
+The Replay is a deterministic view of the actual run, not a second design task.
+
+## Seven story stages
+
+Production may use more steps, but the viewer always groups evidence into:
+
+1. Input — the user's original request and supplied attachments.
+2. Reference — the exact enhanced art-direction prompt and its generated image.
+3. Plan — composition notes, zones, asset topology, and slot geometry.
+4. Assets — each shipping prompt paired with its imported result.
+5. HTML — real source code and the rendered poster.
+6. Review — concrete findings, changes, and rerender outcomes.
+7. Layers — the verified editor or standalone exploded view and contract counts.
+
+Canvas choice, font checks, cleanup, imports, and command logs remain in
+`.trace`; they are metadata inside these stages rather than separate story nodes.
+
+## Evidence files
+
+- `brief.md` — the original user request verbatim. Include attachment paths, but
+  do not copy ambient UI state, system instructions, or hidden context into it.
+- `reference/composition-prompt.md` — the exact prompt sent to the image model
+  for the non-shipping art-direction reference.
+- `reference/composition-reference.png` — the generated reference image.
+- `design-plan.md` — the single integrated decision for live wording,
+  hierarchy, asset topology, regions, layer order, palette, typography, and
+  geometry.
+- `asset-plan.json` — asset IDs, target rectangles, topology, prompt IDs, and
+  dependencies when more than one shipping asset is used.
+- `prompts.md` — exact shipping prompts. Every `##` heading used by an asset
+  must equal that asset's `prompt` value in `asset-plan.json`.
+- `assets/*` — imported shipping results. Prefer an asset filename stem equal to
+  its `id` in `asset-plan.json`.
+- `index.html` and `out/poster.png` — source and current render.
+- `render-review.md` — the agent's real visual review, not a retrospective
+  marketing explanation.
+- `editor.html` and `layers.html` — editable and standalone exploded results.
+
+Record each file under its existing trace step as soon as it becomes stable.
+Do not write generic sections such as “why this was done” or “what this node is
+doing”. The viewer exposes the agent's actual prompt, plan, code, findings,
+changes, and outputs.
+
+## Review format
+
+Use one section per real review pass when more than one pass occurs:
+
+```markdown
+# Render review
+
+## Pass 01
+
+### Findings
+- Concrete visible defect.
+
+### Changes
+- Concrete edit applied to address it.
+
+### Result
+- What the rerender confirmed.
+
+### Optimization
+- The one highest-impact enhancement applied, or `none` when the approved
+  render already preserves scanning, recall, and reference fidelity.
+```
+
+Do not invent a pass merely to make the Replay look active. A clean first render
+may have one review section with no defects and `Optimization: none`. Keep all
+real review and optimization activity in this one file, then record the
+consolidated `render-review.md` once under `P16_read_render` after the final
+render.
+
+## Generation
+
+After the poster, editor, and exploded behavior pass verification:
+
+```bash
+node scripts/build-replay.mjs .
+node scripts/verify-replay.mjs replay/index.html
+```
+
+For a project created before the Replay runtime was added, call the equivalent
+scripts from the installed `poster-building` skill and pass the project path.
+Do not rerun the project initializer over an existing poster.
+
+The builder emits `replay/index.html`, `data.js`, CSS, JS, and local icons. It
+embeds text evidence in `data.js`, so opening the result over `file://` does not
+depend on `fetch`. Media paths remain relative to the poster project.
+
+The fixed viewer keeps three persistent phase controls visible: 理解与规划
+(01—03), 生成与构建 (04—05), and 观察与修正 (06—07). Those controls live in
+the scalable canvas world rather than in a fixed screen-space overlay, so fit
+view cannot stack them over evidence nodes. Each phase card uses a 210 × 210px
+world-space footprint with a 56px icon and a 19px label, so the controls remain
+legible after fit-view scaling. A plain open finishes on the clean
+overview with no stage detail expanded. An explicit `?stage=` query remains a
+supported deep link, and closing a detail removes that query. Flow-arrow markers
+use user-space sizing so their heads remain visually bounded when stroke widths
+change.
+
+The Design Plan, final rendered PNG, and editable layer animation share the same
+right-column x-position. The generated reference is centered in the open space
+between the Visual Reference and Design Plan stages. A single straight dashed
+blue connector runs from stage 02, behind the centered reference, and into stage
+03; no solid blue route loops above the image. The render lightbox loads the
+original PNG directly and aspect-fits it within the available viewport; it must
+show the full image without cropping or substituting a partial viewport capture.
+
+The viewer has three motion states. On load it reconstructs the complete path
+in 4.7 seconds: canvas settle, rapid node placement, ordered line drawing,
+one phase pulse, final-output settle, and completion-light activation. The
+detail panel stays fully hidden until this reconstruction completes. The
+finished overview then uses no moving dashes; its first main pulse appears after
+about 0.4 seconds and its first repair pulse after about 1.1 seconds, followed by
+clearly visible energy packets on main paths every 1.8–3 seconds and repair paths
+every 2.6–4 seconds, with at most two packets alive at once. Ambient packets
+cross their paths in about 1.15 seconds. The playback control pauses ambient
+motion and runs stronger
+600–800ms causal pulses while synchronizing node focus, artifacts, and the
+detail panel. Ambient motion pauses when the document is hidden or the canvas is
+zoomed below 0.20 scale. `prefers-reduced-motion` disables all three motion
+layers without hiding evidence.
+
+The main-canvas Assets previews also use a quiet gallery cycle only in the
+finished overview: each visible card brightens, rises 2–3px, gains a slightly
+stronger shadow, and scales its image to 1.015 for about 700ms. After all visible
+cards have been featured once, the gallery rests for a random 4–6 seconds. This
+cycle pauses with ambient motion and never competes with formal playback.
+
+The Assets detail begins with a compact visual overview of every recorded
+shipping result before its Prompt/result accordions. The main canvas uses a
+2540×1780 world: the Assets node shows only a short Prompt summary and balances
+with the surrounding stage cards. Up to four shipping results appear beside it.
+Exactly one result expands across the entire former 2×2 footprint and uses one
+short dashed connector. Two to four results use the 2×2 matrix, with one
+connector per visible result and no connector branches for empty slots. Every
+result remains available in the detail overview.
+Design Plan uses recorded rectangles when all slots provide valid geometry. If
+the plan records semantic asset slots but no rectangles, the viewer lays those
+real slots out as a compact matrix with their IDs and recorded roles; it never
+stacks them into an apparently blank placeholder. If no slots were recorded at
+all, it states that evidence is missing rather than inventing a composition.
+The generated reference sits centered between the Visual Reference and Design
+Plan stages at a slightly smaller scale, with their dashed connector visually
+entering and leaving the image. The final render and layer output use large cards
+in the right output column.
+The 反馈修正 label sits on the green observation path, while the red return
+path remains the visible repair loop. This keeps evidence readable without
+placing an artifact between flow nodes or over their connectors.
+
+When the layer output is `layers.html`, Replay embeds its live HTML animation,
+not a GIF and not its `?motion=0` screenshot state. Do not load its iframe at
+page startup: start it when the intro reaches the Layers output, and restart it
+whenever formal playback reaches Layers or the user opens that stage. This keeps
+the layer motion synchronized with the surrounding Replay instead of letting it
+finish behind the 4.7-second intro. The lightbox reloads it on every open.
+
+The stage detail panel is a wide, independently scrolling surface; wheel input
+inside it never changes canvas zoom. Clicking the reference or final-render
+artifact opens an image lightbox instead of stage details. Clicking the layer
+artifact opens a large live-HTML lightbox and reloads it so its animation starts
+from the beginning on every open.
+
+The builder may derive ordering, time, canvas size, layer counts, and asset
+pairings from recorded files. It must never reconstruct a missing prompt or
+decision from memory. Missing evidence stays visibly missing.

package/skills/global_config/editable-design/scripts/_browser.mjs

@@ -0,0 +1,247 @@
+/**
+ * _browser.mjs —— 编辑、固化、拆解与验收脚本共用的 headless 浏览器封装
+ *
+ * 为什么必须用真浏览器：图层坐标只能由布局引擎算出。jsdom / cheerio
+ * 没有布局引擎，getBoundingClientRect() 恒返回 0，纯文本方案不可行。
+ */
+import { existsSync, mkdtempSync, rmSync, readFileSync, writeFileSync, copyFileSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+
+const ASSETS = resolve(dirname(fileURLToPath(import.meta.url)), '../assets/editor');
+const ASSET_FILES = ['layer-editor.css', 'layer-editor.js'];
+const TAGS = '  <link rel="stylesheet" href="layer-editor.css">\n'
+           + '  <script src="layer-editor.js" defer></script>\n';
+
+/**
+ * 临时把编辑器接到一张海报上，用于离线驱动。
+ * 临时 HTML 必须放在海报同目录，否则 assets/ 之类的相对路径会失效。
+ * cleanup() 会移除临时文件，并将项目原有的编辑器资产逐字节还原。
+ * 验收不得把技能内置运行时永久覆盖到已经完成的项目里。
+ */
+export function wireTemp(src, name = '_hf_tmp.html') {
+  const dir = dirname(src);
+  const tmp = join(dir, name);
+  const originalAssets = new Map(ASSET_FILES.map((f) => {
+    const target = join(dir, f);
+    return [f, existsSync(target) ? readFileSync(target) : null];
+  }));
+  const html = readFileSync(src, 'utf8');
+  if (!/<\/head>/i.test(html)) throw new Error('这份 HTML 没有 </head>，无法注入编辑器');
+
+  for (const f of ASSET_FILES) copyFileSync(join(ASSETS, f), join(dir, f));
+  writeFileSync(tmp, html.includes('layer-editor.js') ? html : html.replace(/<\/head>/i, TAGS + '</head>'));
+
+  return {
+    file: tmp,
+    cleanup() {
+      try { unlinkSync(tmp); } catch { /* 已不存在 */ }
+      for (const f of ASSET_FILES) {
+        const target = join(dir, f);
+        const original = originalAssets.get(f);
+        if (original) writeFileSync(target, original);
+        else { try { unlinkSync(target); } catch { /* 已不存在 */ } }
+      }
+    },
+  };
+}
+
+let puppeteer;
+try {
+  puppeteer = (await import('puppeteer-core')).default;
+} catch {
+  console.error('缺少依赖 puppeteer-core。请先执行：');
+  console.error('  cd "' + dirname(fileURLToPath(import.meta.url)) + '" && npm install');
+  process.exit(2);
+}
+
+const CHROME_CANDIDATES = [
+  process.env.EDITABLE_DESIGN_BROWSER,
+  process.env.PUPPETEER_EXECUTABLE_PATH,
+  process.env.POSTER_BROWSER,
+  process.env.CHROME_PATH,
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+  '/usr/bin/google-chrome',
+  '/usr/bin/chromium-browser',
+  '/usr/bin/chromium',
+].filter(Boolean);
+
+function findChrome() {
+  let hit = CHROME_CANDIDATES.find((p) => existsSync(p));
+  if (!hit) {
+    for (const name of ['chromium', 'google-chrome', 'chrome']) {
+      try {
+        const found = execFileSync('which', [name], { encoding: 'utf8' }).trim();
+        if (found && existsSync(found)) { hit = found; break; }
+      } catch { /* try the next name */ }
+    }
+  }
+  if (!hit) {
+    console.error('找不到 Chrome。请设置 EDITABLE_DESIGN_BROWSER 指向浏览器可执行文件。');
+    process.exit(2);
+  }
+  return hit;
+}
+
+export async function launch() {
+  // 每次用全新的临时 profile：既避开用户已开着的 Chrome 实例
+  // （否则会卡在 "Timed out waiting for the WS endpoint URL"），
+  // 也保证 localStorage 干净，草稿不会干扰固化结果。
+  const profile = mkdtempSync(join(tmpdir(), 'layer-editor-'));
+  const args = [
+    '--allow-file-access-from-files',
+    '--font-render-hinting=none',
+    '--disable-gpu',
+    `--user-data-dir=${profile}`,
+  ];
+  if (process.env.EDITABLE_DESIGN_NO_SANDBOX === '1') args.push('--no-sandbox');
+  const browser = await puppeteer.launch({
+    executablePath: findChrome(),
+    headless: true,
+    args,
+  });
+  const origClose = browser.close.bind(browser);
+  browser.close = async () => {
+    await origClose();
+    try { rmSync(profile, { recursive: true, force: true }); } catch { /* 清理失败无妨 */ }
+  };
+  return browser;
+}
+
+/**
+ * 加载一个本地 HTML 文件并等到可以安全测量为止。
+ * waitEditor=true 时额外等编辑器初始化完成（data-hf-ready）。
+ */
+export async function open(browser, file, { width = 1600, height = 1200, waitEditor = false } = {}) {
+  const page = await browser.newPage();
+  await page.setViewport({ width, height, deviceScaleFactor: 1 });
+  const errors = [];
+  page.on('pageerror', (e) => errors.push(String(e)));
+  page.on('console', (m) => { if (m.type() === 'error') errors.push('console: ' + m.text()); });
+
+  await page.goto('file://' + resolve(file), { waitUntil: 'networkidle0' });
+  if (waitEditor) await page.waitForSelector('html[data-hf-ready]', { timeout: 20000 });
+  // 字体与图片决定文字块尺寸和图层高度，量之前必须落地
+  await page.evaluate(() => document.fonts.ready);
+  await page.evaluate(() => Promise.all(
+    [...document.images].filter((i) => !i.complete).map((i) => new Promise((r) => {
+      i.addEventListener('load', r, { once: true });
+      i.addEventListener('error', r, { once: true });
+    })),
+  ));
+  await new Promise((r) => setTimeout(r, 350));
+  return { page, errors };
+}
+
+/** 读出每个 data-layer-id 图层相对画布的位置与尺寸（换算掉画布缩放） */
+export function probe(page) {
+  return page.evaluate(() => {
+    const cv = document.querySelector('[data-canvas-width]') || document.querySelector('.poster-canvas');
+    if (!cv) return null;
+    const c = cv.getBoundingClientRect();
+    const scale = c.width / (+cv.dataset.canvasWidth || cv.offsetWidth);
+    const out = {};
+    for (const el of cv.querySelectorAll('[data-layer-id]')) {
+      const r = el.getBoundingClientRect();
+      out[el.dataset.layerId] = {
+        left: +((r.left - c.left) / scale).toFixed(1),
+        top: +((r.top - c.top) / scale).toFixed(1),
+        width: +(r.width / scale).toFixed(1),
+        height: +(r.height / scale).toFixed(1),
+      };
+    }
+    return out;
+  });
+}
+
+/** 逐图层比对两次测量，返回最大偏差与超差清单 */
+export function diff(a, b, tol = 1) {
+  const ids = [...new Set([...Object.keys(a || {}), ...Object.keys(b || {})])];
+  const rows = [];
+  let worst = 0;
+  for (const id of ids) {
+    if (!a?.[id] || !b?.[id]) { rows.push({ id, missing: true }); continue; }
+    const d = Math.max(Math.abs(a[id].left - b[id].left), Math.abs(a[id].top - b[id].top));
+    worst = Math.max(worst, d);
+    rows.push({ id, a: a[id], b: b[id], d: +d.toFixed(2), fail: d > tol });
+  }
+  return { worst: +worst.toFixed(2), rows, ok: rows.every((r) => !r.fail && !r.missing) };
+}
+
+/**
+ * 对两个页面中的画布做真实像素比对。
+ *
+ * 几何一致只能证明图层框没有移动，无法发现上下文选择器失效、背景消失、
+ * 伪元素丢失或绘制顺序改变。这里直接截取元素并交给浏览器解码 PNG，避免
+ * 再引入 sharp/pngjs 等依赖。perChannelTolerance 用于忽略极轻微的抗锯齿噪声。
+ */
+export async function pixelDiff(pageA, selectorA, pageB, selectorB, { perChannelTolerance = 2 } = {}) {
+  const elA = await pageA.$(selectorA);
+  const elB = await pageB.$(selectorB);
+  if (!elA || !elB) return { ok: false, reason: '找不到待比较画布' };
+  const capture = async (page, el) => {
+    const box = await el.boundingBox();
+    if (!box) throw new Error('待比较画布不可见');
+    // ElementHandle.screenshot() 会先尝试滚动元素到可见区。对于高于
+    // 普通视口的竖版海报，某些 Chrome 版本会在这一步长时间等待。
+    // 画布已被安置在足够大的视口中，直接按 bounding box 裁剪更稳定。
+    return page.screenshot({
+      type: 'png', omitBackground: true, captureBeyondViewport: true,
+      clip: { x: box.x, y: box.y, width: box.width, height: box.height },
+    });
+  };
+  // Puppeteer 会用同一把截图锁保护 BrowserContext，必须顺序执行。
+  const pngA = await capture(pageA, elA);
+  const pngB = await capture(pageB, elB);
+  if (Buffer.compare(pngA, pngB) === 0) {
+    return { ok: true, width: 0, height: 0, changed: 0, changedRatio: 0, meanAbs: 0, exact: true };
+  }
+  return pageA.evaluate(async ({ a, b, tolerance }) => {
+    const load = (base64) => new Promise((resolve, reject) => {
+      const img = new Image();
+      img.onload = () => resolve(img);
+      img.onerror = () => reject(new Error('PNG 解码失败'));
+      img.src = `data:image/png;base64,${base64}`;
+    });
+    const [imgA, imgB] = await Promise.all([load(a), load(b)]);
+    if (imgA.naturalWidth !== imgB.naturalWidth || imgA.naturalHeight !== imgB.naturalHeight) {
+      return {
+        ok: false, reason: '尺寸不一致',
+        a: [imgA.naturalWidth, imgA.naturalHeight], b: [imgB.naturalWidth, imgB.naturalHeight],
+      };
+    }
+    const width = imgA.naturalWidth, height = imgA.naturalHeight;
+    const cv = document.createElement('canvas');
+    cv.width = width; cv.height = height;
+    const ctx = cv.getContext('2d', { willReadFrequently: true });
+    ctx.clearRect(0, 0, width, height); ctx.drawImage(imgA, 0, 0);
+    const aData = ctx.getImageData(0, 0, width, height).data;
+    ctx.clearRect(0, 0, width, height); ctx.drawImage(imgB, 0, 0);
+    const bData = ctx.getImageData(0, 0, width, height).data;
+    let changed = 0, totalAbs = 0, worst = 0;
+    for (let i = 0; i < aData.length; i += 4) {
+      const dr = Math.abs(aData[i] - bData[i]);
+      const dg = Math.abs(aData[i + 1] - bData[i + 1]);
+      const db = Math.abs(aData[i + 2] - bData[i + 2]);
+      const da = Math.abs(aData[i + 3] - bData[i + 3]);
+      const local = Math.max(dr, dg, db, da);
+      if (local > tolerance) changed++;
+      totalAbs += dr + dg + db + da;
+      if (local > worst) worst = local;
+    }
+    const pixels = width * height;
+    return {
+      ok: true, width, height, changed,
+      changedRatio: changed / pixels,
+      meanAbs: totalAbs / (pixels * 4), worst, exact: false,
+    };
+  }, {
+    a: Buffer.from(pngA).toString('base64'),
+    b: Buffer.from(pngB).toString('base64'),
+    tolerance: perChannelTolerance,
+  });
+}

package/skills/global_config/editable-design/scripts/bake.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * bake.mjs —— 离线布局固化
+ *
+ *   node bake.mjs <海报 index.html> [--in-place]
+ *
+ * 把文档流布局改写成纯绝对定位，视觉零变化。产物此后天然可拖，
+ * 打开编辑器时不再需要现场固化（也就不再依赖字体每次都加载成功）。
+ *
+ * 默认输出 <base>.absolute.html；--in-place 直接覆盖原文件。
+ * 验收：所有图层坐标偏差必须 ≤1px，否则不落盘并退出 1。
+ */
+import { writeFileSync, existsSync, unlinkSync } from 'node:fs';
+import { dirname, join, resolve, basename, extname } from 'node:path';
+import { launch, open, probe, diff, wireTemp } from './_browser.mjs';
+
+const file = process.argv[2];
+const inPlace = process.argv.includes('--in-place');
+if (!file || !existsSync(resolve(file))) {
+  console.error('用法: node bake.mjs <海报 index.html> [--in-place]');
+  process.exit(2);
+}
+
+const src = resolve(file);
+const dir = dirname(src);
+const out = inPlace ? src : join(dir, `${basename(src, extname(src))}.absolute.html`);
+
+let wired;
+try {
+  wired = wireTemp(src, '_hf_bake.html');
+} catch (err) {
+  console.error('❌ ' + err.message);
+  process.exit(1);
+}
+
+const browser = await launch();
+let code = 0;
+try {
+  // 1. 原始海报作为基准
+  const { page: p0, errors: e0 } = await open(browser, src);
+  const before = await probe(p0);
+  if (!before || !Object.keys(before).length) {
+    console.error('❌ 原始海报里没有 data-layer-id 图层，先跑 check-contract.mjs');
+    code = 1;
+  } else {
+    if (e0.length) console.warn('⚠️  原始海报有报错:', e0.join('; '));
+
+    // 2. 挂上编辑器跑固化，取导出结果
+    const { page: p1, errors: e1 } = await open(browser, wired.file, { waitEditor: true });
+    const baked = await p1.evaluate(() => window.__layerEditor.fullHTML());
+    if (e1.length) console.warn('⚠️  固化过程有报错:', e1.join('; '));
+
+    // 3. 先写到临时位置验证，通过了才落到最终路径
+    const probeFile = join(dir, '_hf_bake_out.html');
+    writeFileSync(probeFile, baked);
+    const { page: p2, errors: e2 } = await open(browser, probeFile);
+    const after = await probe(p2);
+    const d = diff(before, after, 1);
+    try { unlinkSync(probeFile); } catch {}
+
+    console.log(`\n固化 · ${basename(src)}\n`);
+    console.log(' 图层'.padEnd(24) + '原始 left,top'.padEnd(20) + '固化后 left,top'.padEnd(20) + '偏差');
+    for (const r of d.rows) {
+      if (r.missing) { console.log(` ${r.id.padEnd(23)}缺失`); continue; }
+      console.log(` ${r.id.padEnd(23)}${`${r.a.left}, ${r.a.top}`.padEnd(20)}${`${r.b.left}, ${r.b.top}`.padEnd(20)}${r.d}${r.fail ? '  ❌' : ''}`);
+    }
+    console.log(`\n 最大偏差 ${d.worst}px　图层 ${d.rows.length} 个　产物 ${(baked.length / 1024).toFixed(1)}KB`);
+
+    const clean = !/hf-|layer-editor/.test(baked);
+    if (!clean) console.log(' ⚠️  产物中检测到编辑器残留');
+    if (e2.length) console.log(' ⚠️  产物加载有报错:', e2.join('; '));
+
+    if (d.ok && clean) {
+      writeFileSync(out, baked);
+      console.log(`\n✅ 视觉零偏差，已写入 ${out}\n`);
+    } else {
+      console.log('\n❌ 未通过验收，产物已丢弃。');
+      console.log('   偏差不为 0 通常意味着：契约未满足（先跑 check-contract.mjs），');
+      console.log('   或存在固化规则未覆盖的布局（float / sticky / 伪元素撑高 / writing-mode）。\n');
+      code = 1;
+    }
+  }
+} finally {
+  wired.cleanup();
+  await browser.close();
+}
+process.exit(code);