@openbrt/weclawbotctl 0.1.17 → 0.1.19

package/README.md

@@ -86,6 +86,13 @@ value contains the same `preview.pages[].path` list. The agent owns delivering
 that preview to the user. The optional automatic preview hook is off by default
 and exists only for legacy experiments.
 
+The purpose of sending the preview is not just proof that MQTT worked. The
+preview is the feedback surface that lets the user's agent learn the user's
+reading habits, layout taste, density tolerance, font preferences, and page
+rhythm over time. Treat "send to screen" as a two-part delivery: the device is
+updated, and the user receives the same effect image in the current chat unless
+the agent reports a concrete preview-delivery failure.
+
 To clear the current note, use the firmware clear command:
 
 ```bash
@@ -297,7 +304,9 @@ Before publishing, agents should inspect or otherwise self-evaluate the rendered
 pages against the user's preferences and their own learned standards when their
 runtime supports it. Regenerate the document if the bitmap does not satisfy those
 standards. After a successful publish, send the preview PNGs to the user through
-the current chat/media channel so the user can see the effect.
+the current chat/media channel so the user can see the effect and correct the
+agent's choices. Carry those corrections forward instead of resetting local
+style memory on plugin upgrades.
 
 ```bash
 weclawbotctl preview /path/to/screen-document.json

package/bin/weclawbotctl.mjs

@@ -10,6 +10,7 @@ import process from "node:process";
 import { validateActivity } from "../lib/activity.mjs";
 import { validateScreenDocument } from "../lib/direct-control.mjs";
 import { normalizeCredentials, publishControl, publishControlAndWaitStatus, testConnection } from "../lib/mqtt-control.mjs";
+import { createPreviewArtifactDir, writePreviewManifest } from "../lib/preview-manifest.mjs";
 import { writeScreenDocumentPreviewFiles } from "../lib/screen-preview.mjs";
 
 const DEFAULT_ENDPOINT = "https://weclawbot.link/byoa";
@@ -212,6 +213,7 @@ async function commandScreen(values) {
     timeout: 12,
     preview: true,
     "preview-dir": "",
+    "preview-manifest": true,
     scale: 2,
   });
   const file = String(options._[0] || "").trim();
@@ -229,9 +231,10 @@ async function commandScreen(values) {
   if (!validation.ok) {
     throw new Error(`Invalid screen document: ${validation.errors.join("; ")}`);
   }
+  const previewOutputDir = options["preview-dir"] || (options["preview-manifest"] ? await createPreviewArtifactDir(document.id || "screen") : "");
   const preview = options.preview
     ? await writeScreenDocumentPreviewFiles(document, {
-      outputDir: options["preview-dir"] || "",
+      outputDir: previewOutputDir,
       scale: Number(options.scale) || 2,
     })
     : { available: false, pages: [] };
@@ -250,6 +253,14 @@ async function commandScreen(values) {
     if (delivery.status.kind !== "applied") {
       throw new Error(`Device rejected screen document: ${delivery.status.detail || "unknown"}`);
     }
+    const manifest = options["preview-manifest"]
+      ? await writePreviewManifest({
+        document,
+        preview,
+        source: "weclawbotctl_screen",
+        status: { applied: true, mqtt_status: delivery.status },
+      })
+      : null;
     console.log(JSON.stringify({
       ok: true,
       published: true,
@@ -260,11 +271,20 @@ async function commandScreen(values) {
       warnings: validation.warnings,
       layout_guidance: validation.layout_guidance,
       preview,
+      preview_manifest: previewManifestSummary(manifest),
       status: delivery.status,
     }));
     return;
   }
   await publishControl(credentials, control);
+  const manifest = options["preview-manifest"]
+    ? await writePreviewManifest({
+      document,
+      preview,
+      source: "weclawbotctl_screen",
+      status: { applied: null },
+    })
+    : null;
   console.log(JSON.stringify({
     ok: true,
     published: true,
@@ -275,6 +295,7 @@ async function commandScreen(values) {
     warnings: validation.warnings,
     layout_guidance: validation.layout_guidance,
     preview,
+    preview_manifest: previewManifestSummary(manifest),
   }));
 }
 
@@ -767,6 +788,15 @@ function clearStatusDetail(target) {
   return target === "idle_photo" ? "clear_idle_photo" : "clear_note";
 }
 
+function previewManifestSummary(manifest) {
+  if (!manifest) return null;
+  return {
+    id: manifest.id,
+    path: manifest.path,
+    pages: manifest.preview?.pages?.length || 0,
+  };
+}
+
 function shellValue(value) {
   return `'${String(value).replaceAll("'", "'\\''")}'`;
 }
@@ -785,7 +815,7 @@ function usage() {
   weclawbotctl thinking [--ttl seconds] [--id correlation-id]
   weclawbotctl idle [--id correlation-id]
   weclawbotctl preview <document.json> [--output-dir dir] [--scale 1..4]
-  weclawbotctl screen <document.json> [--force] [--no-wait] [--timeout seconds] [--preview-dir dir] [--no-preview]
+  weclawbotctl screen <document.json> [--force] [--no-wait] [--timeout seconds] [--preview-dir dir] [--no-preview] [--no-preview-manifest]
   weclawbotctl clear [--target note|idle_photo] [--no-wait] [--timeout seconds]
   weclawbotctl openclaw install [--spec @openbrt/weclawbotctl] [--bin /path/to/openclaw] [--force=false]
   weclawbotctl openclaw doctor [--gateway=false] [--bin /path/to/openclaw] [--json]`);

package/index.mjs

@@ -10,11 +10,13 @@ import { validateActivity } from "./lib/activity.mjs";
 import { validateScreenDocument } from "./lib/direct-control.mjs";
 import { normalizeCredentials, publishControl, publishControlAndWaitStatus, testConnection } from "./lib/mqtt-control.mjs";
 import { collectCommandStrings, extractScreenDocumentPathFromExecParams, normalizeDeliveryContext } from "./lib/openclaw-preview.mjs";
+import { createPreviewArtifactDir, listRecentPreviewManifests, markPreviewManifest, writePreviewManifest } from "./lib/preview-manifest.mjs";
 import { renderScreenDocumentPreviewPages, writeScreenDocumentPreviewFiles } from "./lib/screen-preview.mjs";
 
 const DEFAULT_CREDENTIALS_PATH = path.join(os.homedir(), ".config", "weclawbot", "agent-mqtt.json");
 const SCREEN_PROMPT_PATTERN = /weclawbot|weclaw|微笺|桌宠|墨水屏|电子墨水|屏上|上屏|发到屏|推到屏|放到屏|显示到屏|发送到屏|清屏|清理屏幕|屏幕/iu;
 const activeRunActivities = new Map();
+const activePreviewWindows = new Map();
 
 // The long-running curator bridge remains a separate service. These tools keep
 // the local agent path explicit: validate first, then publish only with the
@@ -136,12 +138,21 @@ const pluginEntry = defineToolPlugin({
           document: outbound,
         };
         const credentials = await requireCredentials(credentials_path);
-        const preview = await writeScreenDocumentPreviewFiles(outbound, { outputDir: preview_output_dir || "" });
+        const previewDir = preview_output_dir || await createPreviewArtifactDir(outbound.id || "screen");
+        const preview = await writeScreenDocumentPreviewFiles(outbound, { outputDir: previewDir });
         if (wait_status !== false) {
           const delivery = await publishControlAndWaitStatus(credentials, control, {
             expectedDetail: outbound.id,
             timeoutMs: Math.max(1, Number(timeout_seconds) || 12) * 1000,
           });
+          const manifest = delivery.status.kind === "applied"
+            ? await writePreviewManifest({
+              document: outbound,
+              preview,
+              source: "openclaw_tool",
+              status: { applied: true, mqtt_status: delivery.status },
+            })
+            : null;
           return {
             ok: delivery.status.kind === "applied",
             published: true,
@@ -153,10 +164,17 @@ const pluginEntry = defineToolPlugin({
             warnings: validation.warnings,
             layout_guidance: validation.layout_guidance,
             preview,
+            preview_manifest: previewManifestSummary(manifest),
             status: delivery.status,
           };
         }
         await publishControl(credentials, control);
+        const manifest = await writePreviewManifest({
+          document: outbound,
+          preview,
+          source: "openclaw_tool",
+          status: { applied: null },
+        });
         return {
           ok: true,
           published: true,
@@ -167,6 +185,7 @@ const pluginEntry = defineToolPlugin({
           warnings: validation.warnings,
           layout_guidance: validation.layout_guidance,
           preview,
+          preview_manifest: previewManifestSummary(manifest),
         };
       },
     }),
@@ -228,11 +247,11 @@ function registerOpenClawHooks(api) {
     return { outcome: "pass" };
   }, { timeoutMs: 5_000 });
   api.on("before_agent_finalize", async (event, ctx) => {
-    await finishHookActivity(api, event, ctx);
+    await finishHookActivity(api, event, ctx, { final: false });
     return { action: "continue" };
   }, { timeoutMs: 5_000 });
   api.on("agent_end", async (event, ctx) => {
-    await finishHookActivity(api, event, ctx);
+    await finishHookActivity(api, event, ctx, { final: true });
   }, { timeoutMs: 5_000 });
   api.on("after_tool_call", async (event, ctx) => {
     await attachScreenPreview(api, event, ctx);
@@ -241,10 +260,14 @@ function registerOpenClawHooks(api) {
 
 async function startHookActivity(api, event, ctx) {
   try {
-    if (api.pluginConfig?.auto_activity === false) return;
     if (!shouldAutoActivity(event, ctx)) return;
     const key = hookActivityKey(event, ctx);
-    if (!key || activeRunActivities.has(key)) return;
+    if (!key) return;
+    if (!activePreviewWindows.has(key)) {
+      activePreviewWindows.set(key, { startedAt: Date.now() });
+    }
+    if (api.pluginConfig?.auto_activity === false) return;
+    if (activeRunActivities.has(key)) return;
     const correlationId = `openclaw-${sanitizeId(ctx?.runId || key).slice(0, 72)}`;
     await publishControl(await requireCredentials(), {
       schema: "weclawbot.control.v1",
@@ -264,10 +287,20 @@ async function startHookActivity(api, event, ctx) {
   }
 }
 
-async function finishHookActivity(api, event, ctx) {
+async function finishHookActivity(api, event, ctx, options = {}) {
+  const key = hookActivityKey(event, ctx);
+  if (!key) return;
+  const previewWindow = activePreviewWindows.get(key);
+  if (previewWindow) {
+    try {
+      await attachRecentPreviewManifests(api, event, ctx, previewWindow);
+    } catch (error) {
+      api.logger?.warn?.(`weclawbot preview manifest hook failed: ${errorMessage(error)}`);
+    } finally {
+      if (options.final) activePreviewWindows.delete(key);
+    }
+  }
   try {
-    const key = hookActivityKey(event, ctx);
-    if (!key) return;
     const active = activeRunActivities.get(key);
     if (!active) return;
     activeRunActivities.delete(key);
@@ -287,6 +320,53 @@ async function finishHookActivity(api, event, ctx) {
   }
 }
 
+async function attachRecentPreviewManifests(api, event, ctx, previewWindow) {
+  if (api.pluginConfig?.auto_preview === false) return 0;
+  if (event?.error) return 0;
+  const sessionKey = resolveHookSessionKey(event, ctx);
+  if (!sessionKey) {
+    logPreviewSkip(api, event, "missing sessionKey for manifest delivery");
+    return 0;
+  }
+  const manifests = await listRecentPreviewManifests({
+    sinceMs: Math.max(0, Number(previewWindow?.startedAt) || Date.now() - 60_000),
+    untilMs: Date.now() + 10_000,
+    limit: 5,
+  });
+  let delivered = 0;
+  for (const manifest of manifests) {
+    const result = await attachPreviewManifest(api, manifest, { ...ctx, sessionKey });
+    if (result?.ok) {
+      delivered += result.count || 1;
+      await markPreviewManifest(manifest.path, {
+        delivered_at: new Date().toISOString(),
+        delivered_session_key: sessionKey,
+        delivered_channel: result.channel,
+      });
+    } else {
+      await markPreviewManifest(manifest.path, {
+        last_delivery_error_at: new Date().toISOString(),
+        last_delivery_error: result?.error || "unknown error",
+      });
+      api.logger?.warn?.(`weclawbot preview manifest delivery failed: ${result?.error || "unknown error"}`);
+    }
+  }
+  return delivered;
+}
+
+async function attachPreviewManifest(api, manifest, ctx) {
+  const pages = Array.isArray(manifest.preview?.pages) ? manifest.preview.pages : [];
+  const files = pages
+    .map((page) => ({ path: String(page.path || "") }))
+    .filter((file) => file.path);
+  if (files.length === 0) return { ok: false, error: "manifest has no preview files" };
+  const documentId = manifest.document?.id || "screen";
+  const pageLabel = `${files.length} page${files.length === 1 ? "" : "s"}`;
+  const caption = `WeClawBot screen preview: ${documentId} (${pageLabel}, ${manifest.source || "manifest"})`;
+  const dir = manifest.preview?.output_dir || path.dirname(files[0].path);
+  return deliverPreviewFiles(api, { ctx, files, caption, dir });
+}
+
 async function attachScreenPreview(api, event, ctx) {
   try {
     if (api.pluginConfig?.auto_preview !== true) return;
@@ -343,12 +423,22 @@ async function attachPreviewForDocument(api, document, ctx, source) {
     }
     const pageLabel = `${previewPages.length} page${previewPages.length === 1 ? "" : "s"}`;
     const caption = `WeClawBot screen preview: ${document.id || "screen"} (${pageLabel}, ${source})`;
+    const result = await deliverPreviewFiles(api, { ctx, files, caption, dir });
+    if (!result?.ok) {
+      api.logger?.warn?.(`weclawbot preview delivery failed: ${result?.error || "unknown error"}`);
+    } else {
+      api.logger?.info?.(`weclawbot preview attached: ${result.channel} count=${result.count}`);
+    }
+    scheduleRemove(dir);
+}
+
+async function deliverPreviewFiles(api, params) {
     let attached = false;
     if (typeof api.session?.workflow?.sendSessionAttachment === "function") {
       const result = await api.session.workflow.sendSessionAttachment({
-        sessionKey: ctx.sessionKey,
-        files,
-        text: caption,
+        sessionKey: params.ctx.sessionKey,
+        files: params.files,
+        text: params.caption,
         maxBytes: 2_000_000,
         captionFormat: "plain",
         channelHints: { telegram: { forceDocumentMime: "image/png" } },
@@ -362,20 +452,19 @@ async function attachPreviewForDocument(api, document, ctx, source) {
     }
     if (!attached) {
       const result = await sendPreviewViaOutboundAdapter(api, {
-        ctx,
-        files,
-        document,
-        source,
-        caption,
-        dir,
+        ctx: params.ctx,
+        files: params.files,
+        caption: params.caption,
+        dir: params.dir,
       });
       if (!result?.ok) {
-        api.logger?.warn?.(`weclawbot preview outbound fallback failed: ${result?.error || "unknown error"}`);
+        return result;
       } else {
         api.logger?.info?.(`weclawbot preview attached via outbound adapter: ${result.channel} count=${result.count}`);
+        return result;
       }
     }
-    scheduleRemove(dir);
+    return { ok: true, channel: "session-workflow", count: params.files.length };
 }
 
 async function sendPreviewViaOutboundAdapter(api, params) {
@@ -502,6 +591,15 @@ function clearStatusDetail(target) {
   return target === "idle_photo" ? "clear_idle_photo" : "clear_note";
 }
 
+function previewManifestSummary(manifest) {
+  if (!manifest) return null;
+  return {
+    id: manifest.id,
+    path: manifest.path,
+    pages: manifest.preview?.pages?.length || 0,
+  };
+}
+
 function sanitizeId(value) {
   return String(value || crypto.randomUUID()).replace(/[^a-zA-Z0-9_.-]/gu, "_");
 }

package/lib/preview-manifest.mjs

@@ -0,0 +1,133 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+const MANIFEST_SCHEMA = "weclawbot.preview_manifest.v1";
+
+export async function defaultPreviewManifestRoot() {
+  const override = expandPath(process.env.WECLAWBOT_PREVIEW_SPOOL_DIR || "");
+  if (override) return override;
+
+  const stateDir = expandPath(process.env.OPENCLAW_STATE_DIR || "");
+  if (stateDir) return path.join(stateDir, "media", "outbound", "weclawbot-preview");
+
+  const openClawOutbound = path.join(os.homedir(), ".openclaw", "media", "outbound");
+  if (await isDirectory(openClawOutbound)) return path.join(openClawOutbound, "weclawbot-preview");
+
+  return path.join(os.homedir(), ".cache", "weclawbot", "openclaw-preview");
+}
+
+export async function createPreviewArtifactDir(documentId = "screen") {
+  const root = await defaultPreviewManifestRoot();
+  const now = new Date();
+  const stamp = now.toISOString().replace(/[:.]/gu, "-");
+  const dir = path.join(root, "files", `${stamp}-${process.pid}-${safeFilename(documentId)}`);
+  await fs.mkdir(dir, { recursive: true });
+  return dir;
+}
+
+export async function writePreviewManifest({ document, preview, source = "unknown", status = {}, createdAtMs = Date.now() }) {
+  if (!preview?.available || !Array.isArray(preview.pages) || preview.pages.length === 0) return null;
+  const root = await defaultPreviewManifestRoot();
+  const dir = path.join(root, "manifests");
+  await fs.mkdir(dir, { recursive: true });
+
+  const id = `preview_${crypto.randomUUID()}`;
+  const createdAt = new Date(createdAtMs).toISOString();
+  const manifest = {
+    schema: MANIFEST_SCHEMA,
+    id,
+    created_at: createdAt,
+    created_ms: createdAtMs,
+    source,
+    document: {
+      id: String(document?.id || "screen"),
+      pages: Array.isArray(document?.pages) ? document.pages.length : preview.pages.length,
+    },
+    status,
+    preview: {
+      available: true,
+      output_dir: preview.output_dir || path.dirname(preview.pages[0]?.path || ""),
+      pages: preview.pages.map((page) => ({
+        index: Number(page.index) || 0,
+        path: String(page.path || ""),
+        width: Number(page.width) || 0,
+        height: Number(page.height) || 0,
+        scale: Number(page.scale) || 1,
+        bytes: Number(page.bytes) || 0,
+        sha256: String(page.sha256 || ""),
+        mime_type: page.mime_type || "image/png",
+      })),
+    },
+  };
+
+  const file = path.join(dir, `${createdAtMs}-${safeFilename(document?.id || source)}-${id}.json`);
+  await fs.writeFile(file, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+  return { ...manifest, path: file, root };
+}
+
+export async function listRecentPreviewManifests(options = {}) {
+  const root = await defaultPreviewManifestRoot();
+  const dir = path.join(root, "manifests");
+  const sinceMs = Number(options.sinceMs) || 0;
+  const untilMs = Number(options.untilMs) || Date.now() + 10_000;
+  const limit = Math.max(1, Number(options.limit) || 8);
+  let entries = [];
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+
+  const manifests = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+    const file = path.join(dir, entry.name);
+    let stat;
+    let manifest;
+    try {
+      stat = await fs.stat(file);
+      if (stat.mtimeMs < sinceMs - 10_000 || stat.mtimeMs > untilMs + 10_000) continue;
+      manifest = JSON.parse(await fs.readFile(file, "utf8"));
+    } catch {
+      continue;
+    }
+    if (manifest?.schema !== MANIFEST_SCHEMA) continue;
+    if (manifest.delivered_at || manifest.consumed_at) continue;
+    const createdMs = Number(manifest.created_ms) || Date.parse(manifest.created_at || "") || stat.mtimeMs;
+    if (createdMs < sinceMs || createdMs > untilMs) continue;
+    const pages = Array.isArray(manifest.preview?.pages) ? manifest.preview.pages : [];
+    if (pages.length === 0) continue;
+    manifests.push({ ...manifest, created_ms: createdMs, path: file, root });
+  }
+
+  return manifests
+    .sort((a, b) => a.created_ms - b.created_ms)
+    .slice(0, limit);
+}
+
+export async function markPreviewManifest(file, patch) {
+  const payload = JSON.parse(await fs.readFile(file, "utf8"));
+  const updated = { ...payload, ...patch };
+  await fs.writeFile(file, `${JSON.stringify(updated, null, 2)}\n`, { mode: 0o600 });
+  return updated;
+}
+
+async function isDirectory(file) {
+  try {
+    return (await fs.stat(file)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function expandPath(value) {
+  const raw = String(value || "").trim();
+  return raw.startsWith("~/") ? path.join(os.homedir(), raw.slice(2)) : raw;
+}
+
+function safeFilename(value) {
+  return String(value || "screen").replace(/[^a-zA-Z0-9_.-]/gu, "_").slice(0, 80) || "screen";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openbrt/weclawbotctl",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "WeClawBot pairing and screen-control CLI for local AI agents.",
   "type": "module",
   "license": "MIT",
@@ -43,11 +43,12 @@
     "./activity": "./lib/activity.mjs",
     "./direct-control": "./lib/direct-control.mjs",
     "./mqtt-control": "./lib/mqtt-control.mjs",
+    "./preview-manifest": "./lib/preview-manifest.mjs",
     "./screen-preview": "./lib/screen-preview.mjs",
     "./package.json": "./package.json"
   },
   "scripts": {
-    "check": "node --check index.mjs && node --check lib/openclaw-preview.mjs && node --check bin/weclawbot-openclaw-bridge.mjs && node --check bin/weclawbot-byoa-bind.mjs && node --check bin/weclawbotctl.mjs && node --test test/direct-control.test.mjs test/activity.test.mjs test/screen-preview.test.mjs test/openclaw-preview-hook.test.mjs"
+    "check": "node --check index.mjs && node --check lib/openclaw-preview.mjs && node --check lib/preview-manifest.mjs && node --check bin/weclawbot-openclaw-bridge.mjs && node --check bin/weclawbot-byoa-bind.mjs && node --check bin/weclawbotctl.mjs && node --test test/direct-control.test.mjs test/activity.test.mjs test/screen-preview.test.mjs test/preview-manifest.test.mjs test/openclaw-preview-hook.test.mjs"
   },
   "dependencies": {
     "mqtt": "^5.10.4",

package/skills/weclawbot-curator/SKILL.md

@@ -58,7 +58,10 @@ OpenClaw Telegram/UI sessions, prefer `weclawbot_publish_screen_document`: its
 result includes `preview.pages[].path` PNG files for the exact mono1 pages. The
 agent must inspect those preview files when possible, then send the preview PNGs
 back to the user through its normal chat/media channel before or alongside the
-"已上屏" reply. If the agent used CLI instead, run `weclawbotctl preview <doc>`
+"已上屏" reply. This preview is not decoration and not merely proof of delivery:
+it is the feedback surface that lets the user and agent steadily converge on the
+user's reading habits, layout taste, density tolerance, font preferences, and
+page rhythm. If the agent used CLI instead, run `weclawbotctl preview <doc>`
 before publishing, or read the `preview` field emitted by `weclawbotctl screen`.
 Do not use OpenClaw Canvas for requests that
 mention WeClawBot, the physical screen, or “屏上”; Canvas is an OpenClaw UI
@@ -92,9 +95,12 @@ inspect images. Judge the preview against the user's preferences and the agent's
 own learned standards: legibility, margins, crowding, page count, and continuity
 across pages. If the preview does not satisfy those standards, regenerate the
 pages before publishing. After a successful publish, include the preview PNG in
-the user-visible response so the user can see what was sent. This review and
-proof loop belongs in the agent/tool layer; do not expect firmware to fix
-typography, show chat previews, or split pages after the pixels arrive.
+the user-visible response so the user can see what was sent and correct the
+agent's choices. Treat explicit comments, repeated corrections, clear requests,
+manual page changes, and acceptance without complaint as signals for future
+layout decisions. This review and feedback loop belongs in the agent/tool layer;
+do not expect firmware to fix typography, show chat previews, or split pages
+after the pixels arrive.
 
 `weclawbotctl screen` and `weclawbot_publish_screen_document` wait for the
 device status topic by default. Treat only `applied` as success. If the device

package/test/preview-manifest.test.mjs

@@ -0,0 +1,60 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  createPreviewArtifactDir,
+  listRecentPreviewManifests,
+  markPreviewManifest,
+  writePreviewManifest,
+} from "../lib/preview-manifest.mjs";
+import { writeScreenDocumentPreviewFiles } from "../lib/screen-preview.mjs";
+
+const root = await fs.mkdtemp(path.join(os.tmpdir(), "weclawbot-preview-manifest-test-"));
+process.env.WECLAWBOT_PREVIEW_SPOOL_DIR = root;
+
+const width = 8;
+const height = 8;
+const stride = 1;
+const bytes = Buffer.alloc(stride * height, 0x00);
+for (let y = 0; y < height; y += 1) bytes[y * stride] = 0x80;
+
+const document = {
+  schema: "weclawbot.screen_document.v1",
+  id: "manifest-test",
+  pages: [{
+    format: "mono1",
+    width,
+    height,
+    stride,
+    data_b64: bytes.toString("base64"),
+  }],
+};
+
+const artifactDir = await createPreviewArtifactDir(document.id);
+assert.ok(artifactDir.startsWith(root));
+
+const preview = await writeScreenDocumentPreviewFiles(document, { outputDir: artifactDir });
+const manifest = await writePreviewManifest({
+  document,
+  preview,
+  source: "test",
+  status: { applied: true },
+});
+
+assert.ok(manifest.path.startsWith(root));
+assert.equal(manifest.preview.pages.length, 1);
+
+const recent = await listRecentPreviewManifests({ sinceMs: Date.now() - 10_000 });
+assert.equal(recent.length, 1);
+assert.equal(recent[0].id, manifest.id);
+
+await markPreviewManifest(manifest.path, { delivered_at: new Date().toISOString() });
+const afterDelivery = await listRecentPreviewManifests({ sinceMs: Date.now() - 10_000 });
+assert.equal(afterDelivery.length, 0);
+
+delete process.env.WECLAWBOT_PREVIEW_SPOOL_DIR;
+await fs.rm(root, { recursive: true, force: true });
+
+console.log("preview-manifest spool: ok");

package/workspace/AGENTS.md

@@ -48,7 +48,11 @@ the tool returns `preview.pages[].path` PNG files for the exact pages. Inspect
 those preview images when possible, and send them back to the user through the
 normal chat/media channel before or alongside the success reply. If using CLI,
 run `weclawbotctl preview <document.json>` before publishing, or read the
-`preview` field emitted by `weclawbotctl screen`.
+`preview` field emitted by `weclawbotctl screen`. The preview is the user's
+feedback surface: use it to learn their reading habits, preferred density,
+layout taste, font choices, and page rhythm over time. Do not treat "上屏" as
+complete until the physical screen is updated and the user can see the same
+effect in chat, or you have clearly reported why the preview could not be sent.
 
 The firmware receives pixels. Do not send raw text to firmware, and do not
 answer that direct delivery is unavailable before checking the local