@zzclub/pipeline 0.11.0 → 0.13.0

package/src/commands/init.ts

@@ -28,6 +28,7 @@ import { parseArgs, requireArg, optionalArg, flagArg } from "../args";
 import { printResult, renderInit } from "../output";
 import { loadConfig, resolveWorkspaceRoot } from "../config";
 import { resolveFullRoute } from "../routes";
+import { resolveCoverTheme } from "../schema/cover-theme";
 import {
   parseAccountName,
   parseContentForm,
@@ -60,6 +61,7 @@ Options:
   --account          Explicit account override (optional)
   --newspic-render-spec-file  JSON file for newspic pagination / page-image intent (optional)
   --style-hint       e.g. fact_report (optional)
+  --cover-theme      Cover theme ID (optional)
   --requires-research  Flag
   --requires-style     Flag
   --requires-render    Flag
@@ -76,11 +78,13 @@ Options:
   const intentText = optionalArg(parsed, "intent-text") ?? "";
   const accountOverride = optionalArg(parsed, "account");
   const styleHint = optionalArg(parsed, "style-hint") ?? null;
+  const coverTheme = parsed["cover-theme"] === undefined ? null : requireArg(parsed, "cover-theme", "cover theme ID").trim();
   const newspicRenderSpecFile = optionalArg(parsed, "newspic-render-spec-file");
   const existingDraftMediaId = optionalArg(parsed, "existing-draft-media-id") ?? null;
   const noteId = optionalArg(parsed, "note-id") ?? null;
   const config = loadConfig();
   const workspace = resolveWorkspaceRoot(optionalArg(parsed, "workspace"), config);
+  if (coverTheme !== null) resolveCoverTheme(config.render.cover, "poster-3-4", accountOverride, coverTheme);
 
   const defaultAccount = parseAccountName(accountOverride ?? "default");
   const parsedTargets = parsePublishTargets(targetsRaw, {
@@ -126,6 +130,7 @@ Options:
     intent_text: intentText || null,
     explicit_constraints: [],
     style_hint: styleHint,
+    cover_theme: coverTheme,
     newspic_render: newspicRender,
     requires: {
       research: flagArg(parsed, "requires-research"),

package/src/commands/monitor.ts

@@ -0,0 +1,21 @@
+import { parseArgs } from "../args";
+import { printHelp, printResult } from "../output";
+import { monitorHealth, readMonitorDescriptor, startMonitor, stopMonitor } from "../monitor/client";
+import { serveMonitor } from "../monitor/server";
+
+/** 服务管理不进入业务日志，防止描述文件令牌被日志复制。 */
+export async function monitor(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+  const action = (JSON.parse(String(parsed._)) as string[])[0] || "status";
+  if (parsed.help) { printHelp("Usage: zzp monitor start | serve | status | stop\nLocal HTTP/SSE monitoring; business commands run independently."); return; }
+  if (action === "start") { printResult(await startMonitor()); return; }
+  if (action === "serve") { const server = await serveMonitor(); printResult(server?.descriptor || await startMonitor()); return; }
+  if (action === "stop") { printResult({ stopped: await stopMonitor() }); return; }
+  if (action === "status") {
+    const descriptor = readMonitorDescriptor();
+    const running = !!descriptor && await monitorHealth(descriptor);
+    printResult({ running, ...(running ? { url: descriptor.url, instance_id: descriptor.instance_id, version: 1 } : {}) });
+    return;
+  }
+  throw new Error(`Unknown monitor action: ${action}`);
+}

package/src/commands/prepare-finalize.ts

@@ -32,6 +32,7 @@ import {
   getCanonicalStatePath,
 } from "../state";
 import { loadTaskState } from "../task-manager";
+import { reportProgress } from "../monitor/recorder";
 import {
   extractHighlightWords,
   buildFrontmatter,
@@ -330,6 +331,7 @@ Options:
   });
 
   // Write post.md
+  reportProgress({ stage: "prepare.save", message: "保存文章和工作流状态" });
   const postContent = `${frontmatter}\n\n${removePageMarkers(body)}`;
   const postPath = join(assetPath, "post.md");
   const postTempPath = `${postPath}.${process.pid}.${crypto.randomUUID()}.tmp`;

package/src/commands/prepare.ts

@@ -35,6 +35,7 @@ import {
   writeState,
 } from "../state";
 import { loadTaskState } from "../task-manager";
+import { reportProgress } from "../monitor/recorder";
 import { resolveFullRoute } from "../routes";
 import { resolveAuthoring, hasStyleRequest } from "../profiles";
 import { parseAccountName, parseRoutePrimary } from "../publish-targets";
@@ -200,6 +201,7 @@ Options:
   state.intent.requires.publish = state.intent.task_kind === "publish";
 
   // ── Step 2: Author select ──
+  reportProgress({ stage: "prepare.author", message: "确定写作规则" });
   const styleRequest =
     isStyleRequest || hasStyleRequest(intentText);
 
@@ -219,6 +221,7 @@ Options:
   // In the current workflow, Writer/Style already own the LLM rewrite.
   // Prepare records the authoring snapshot, then always formats the final body.
   const bodyFormatted = formatArticle(cleanBody);
+  reportProgress({ stage: "prepare.metadata", message: "整理文章元信息" });
 
   // ── Step 4: Asset meta ──
   // Determine title

package/src/commands/publish.ts

@@ -34,8 +34,9 @@ import {
   upsertPublishResult,
 } from "../providers/publish-core";
 import { loadTaskState } from "../task-manager";
+import { publishOutcome, type CommandOutcome } from "../command-outcome";
 
-export async function publish(args: string[]): Promise<void> {
+export async function publish(args: string[]): Promise<void | CommandOutcome> {
   const parsed = parseArgs(args);
 
   if (parsed.help) {
@@ -119,7 +120,7 @@ Options:
       dry_run: true,
       ...(errors.length > 0 ? { errors } : {}),
     }, renderPublish);
-    return;
+    return publishOutcome(results, true);
   }
 
   // Check if all targets are done
@@ -151,6 +152,8 @@ Options:
     output.errors = errors;
   }
   printResult(output, renderPublish);
+  return publishOutcome(state.publish.results.filter((result) => targets.some((target) =>
+    target.route === result.route && target.account === result.account)), results.length === 0);
   } finally {
     await releaseOperationLock();
   }

package/src/commands/render-theme.test.ts

@@ -0,0 +1,115 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { mkdtemp, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { loadConfig, normalizeConfig, saveConfig } from "../config";
+import { defaultState, readState, writeState } from "../state";
+import { resolveFullRoute } from "../routes";
+import { init } from "./init";
+import { ingestHandoff } from "./ingest-handoff";
+import { render } from "./render";
+import { configCommand } from "./config";
+
+let workspace: string;
+let previousConfig: string | undefined;
+let output: ReturnType<typeof spyOn>;
+beforeEach(async () => {
+  workspace = await mkdtemp(join(tmpdir(), "zzhub-cover-contract-"));
+  previousConfig = process.env.ZZHUB_PIPELINE_CONFIG;
+  process.env.ZZHUB_PIPELINE_CONFIG = join(workspace, "config.json");
+  saveConfig(normalizeConfig({}));
+  output = spyOn(console, "log").mockImplementation(() => {});
+});
+afterEach(async () => {
+  output.mockRestore();
+  if (previousConfig === undefined) delete process.env.ZZHUB_PIPELINE_CONFIG;
+  else process.env.ZZHUB_PIPELINE_CONFIG = previousConfig;
+  await rm(workspace, { recursive: true, force: true });
+});
+
+async function preparedTask() {
+  const assetPath = join(workspace, "posts", "2026-09-07-cover");
+  await mkdir(assetPath, { recursive: true });
+  await writeFile(join(assetPath, "post.md"), "完整正文保持不变。", "utf8");
+  const state = defaultState();
+  state.run_id = "cover-contract";
+  state.workspace_root = workspace;
+  state.asset_path = assetPath;
+  state.state_path = join(assetPath, "workflow-state.json");
+  state.route = resolveFullRoute("发公众号文章", { account: "default", contentForm: "article", targets: ["wechat"] });
+  state.intent.intent_text = "发公众号文章";
+  state.intent.content_form = "article";
+  state.intent.targets = ["wechat"];
+  state.intent.cover_theme = "business";
+  state.metadata = { ...state.metadata, title: "完整标题：保留副标题", slug: "cover", date: "2026-09-07" };
+  state.content_review.status = "passed";
+  state.phase.prepare.status = "done";
+  await writeState(state.state_path, state);
+  return state;
+}
+
+describe("cover CLI contract", () => {
+  test("init persists the selected theme and rejects unknown themes", async () => {
+    const args = ["--workspace", workspace, "--task-kind", "publish", "--content-form", "article", "--targets", "wechat", "--content-origin", "user"];
+    await init([...args, "--cover-theme", "business"]);
+    const runs = join(workspace, ".zzhub-media", "runs");
+    const file = (await readdir(runs)).find(name => name.endsWith(".json"))!;
+    expect((await readState(join(runs, file))).intent.cover_theme).toBe("business");
+    await expect(init([...args, "--cover-theme", "missing"])).rejects.toThrow("主题不存在");
+  });
+
+  test("a theme-only handoff retains reviewed content and reenters render", async () => {
+    const state = await preparedTask();
+    state.phase.current = "done";
+    state.phase.render.status = "done";
+    state.mode = "done";
+    await writeState(state.state_path, state);
+    const handoff = join(workspace, "handoff.json");
+    await writeFile(handoff, JSON.stringify({ workflow_handoff: { mode: "resume", state_path: state.state_path, cover_theme: "technology" } }));
+    await ingestHandoff(["--file", handoff, "--workspace", workspace]);
+    const result = await readState(state.state_path);
+    expect(result.intent.cover_theme).toBe("technology");
+    expect(result.asset_path).toBe(state.asset_path);
+    expect(result.content_review.status).toBe("passed");
+    expect(result.phase.prepare.status).toBe("done");
+    expect(result.phase.current).toBe("render");
+    expect(await readFile(join(state.asset_path, "post.md"), "utf8")).toBe("完整正文保持不变。");
+  });
+
+  test("render forwards the latest theme to an existing plugin and command choice wins", async () => {
+    const state = await preparedTask();
+    const pluginPath = join(workspace, "plugin.mjs");
+    await writeFile(pluginPath, 'import {writeFile} from "node:fs/promises"; import {join} from "node:path"; export default {name:"contract-probe",async render(input){await writeFile(join(input.state.asset_path,"received.json"),JSON.stringify(input));const path=join(input.state.asset_path,"cover.png");await writeFile(path,"stub");return {assets:[{kind:"cover",route:input.route,path}],pageCount:1,pages:[]}}};');
+    const config = loadConfig();
+    config.plugins.imageRenderer = pluginPath;
+    config.render.cover.themes.business!.typography.title.fontSize = 101;
+    config.render.cover.themes.business!.colors.accent = "#123789";
+    config.render.branding.logo = "https://example.com/custom-logo.png";
+    config.render.branding.footerText = "公众号：自定义名称";
+    saveConfig(config);
+    await render(["--state", state.state_path]);
+    let received = JSON.parse(await readFile(join(state.asset_path, "received.json"), "utf8"));
+    expect(received.coverTheme.id).toBe("business");
+    expect(received.coverTheme.typography.title.fontSize).toBe(88);
+    expect(received.coverTheme.colors.accent).toBe("#123789");
+    expect(received.title).toBe(state.metadata.title);
+    expect(received.accountVisualParams.footer).toBe("公众号：自定义名称");
+    expect(received.accountVisualParams.fallbackIcon).toBe("https://example.com/custom-logo.png");
+    await render(["--state", state.state_path, "--cover-theme", "minimal"]);
+    received = JSON.parse(await readFile(join(state.asset_path, "received.json"), "utf8"));
+    expect(received.coverTheme.id).toBe("minimal");
+    expect((await readState(state.state_path)).intent.cover_theme).toBe("minimal");
+    expect((await readState(state.state_path)).images.plan.cover_theme).toBe("minimal");
+  });
+
+  test("config import merges one theme and schema works even with a broken config file", async () => {
+    const path = join(workspace, "import.json");
+    await writeFile(path, JSON.stringify({ render: { cover: { themes: { business: { colors: { accent: "#135790" } } } } } }));
+    await configCommand(["--import", path]);
+    expect(loadConfig().render.cover.themes.business!.colors.accent).toBe("#135790");
+    expect(Object.keys(loadConfig().render.cover.themes)).toHaveLength(10);
+    await writeFile(process.env.ZZHUB_PIPELINE_CONFIG!, "invalid json");
+    await configCommand(["--schema", "--key", "render.cover"]);
+    expect(output.mock.calls.at(-1)?.[0]).toContain('"defaultTheme"');
+  });
+});

package/src/commands/render.ts

@@ -20,12 +20,15 @@ import { join } from "path";
 import { parseArgs, requireArg, flagArg } from "../args";
 import { printResult, renderRender } from "../output";
 import { loadConfig } from "../config";
+import { resolveRenderBranding } from "../render-branding";
+import { resolveCoverTheme } from "../schema/cover-theme";
 import { resolveImageRenderer } from "../adapter-loader";
 import {
   acquireStateOperationLock,
   defaultBodyInputs,
   normalizeNewspicRenderSpec,
   readResolvedState,
+  reenterRender,
   validateForPhase,
   writeState,
   type NewspicRenderSpec,
@@ -38,6 +41,8 @@ import {
 } from "../text";
 import { getLongformTheme } from "../routes";
 import { collectNewspicRequiredMarkers } from "../workflow-materials";
+import type { CommandOutcome } from "../command-outcome";
+import { reportProgress } from "../monitor/recorder";
 
 function getNewspicRenderSpec(state: WorkflowState): NewspicRenderSpec {
   const spec = normalizeNewspicRenderSpec(state.intent.newspic_render);
@@ -47,7 +52,7 @@ function getNewspicRenderSpec(state: WorkflowState): NewspicRenderSpec {
   };
 }
 
-export async function render(args: string[]): Promise<void> {
+export async function render(args: string[]): Promise<void | CommandOutcome> {
   const parsed = parseArgs(args);
 
   if (parsed.help) {
@@ -57,6 +62,7 @@ Usage: zzhub-pipeline render [options]
 Options:
   --state        Path to state JSON (required)
   --skip-render  Plan only, don't invoke renderer (optional)
+  --cover-theme  Cover theme ID; saves the task choice (optional)
 `.trim());
     return;
   }
@@ -86,6 +92,20 @@ Options:
   // ── Image Plan ──────────────────────────────────────────────────
 
   const routePrimary = state.route.primary;
+  const config = loadConfig();
+  const requestedTheme = parsed["cover-theme"] === undefined ? undefined : requireArg(parsed, "cover-theme", "cover theme ID").trim();
+  const coverTheme = routePrimary === "blog" ? undefined : resolveCoverTheme(
+    config.render.cover,
+    routePrimary === "wechat-article" ? "wechat-cover-split" : "poster-3-4",
+    state.route.account,
+    requestedTheme ?? state.intent.cover_theme,
+  );
+  if (requestedTheme !== undefined && requestedTheme !== state.intent.cover_theme) {
+    if (!coverTheme) throw new Error("blog 路由不需要封面主题");
+    state.intent.cover_theme = requestedTheme;
+    reenterRender(state);
+    await writeState(statePath, state);
+  }
 
   if (routePrimary === "blog") {
     // Blog doesn't need images by default
@@ -141,6 +161,7 @@ Options:
     template,
     cover_template: coverTemplate,
     cover_title: coverTitle,
+    cover_theme: coverTheme?.id ?? null,
     output_dir: outputDir,
     preview_required: false,
     status: "planned",
@@ -182,7 +203,7 @@ Options:
         message: `Waiting for ${markers.length} body image(s)`,
         phase: state.phase.current,
       }, renderRender);
-      return;
+      return { status: "waiting" };
     }
   } else if (state.images.body_inputs.scope === "newspic-longform") {
     state.images.body_inputs = defaultBodyInputs();
@@ -196,13 +217,13 @@ Options:
       skip_render: true,
       phase: state.phase.current,
     }, renderRender);
-    return;
+    return { status: "skipped" };
   }
 
   // ── Invoke image renderer adapter ───────────────────────────────
 
-  const config = loadConfig();
   const imageRenderer = await resolveImageRenderer(config);
+  reportProgress({ stage: "render.adapter", message: "开始生成图片" });
 
   const bodyImages = (
     state.images.body_inputs.scope === "newspic-longform" &&
@@ -211,7 +232,10 @@ Options:
     ? state.images.body_inputs.received
     : [];
 
+  const branding = resolveRenderBranding(config, state.route.account);
   const renderResult = await imageRenderer.render({
+    coverTheme,
+    onProgress: reportProgress,
     state,
     bodyText: cleanBody,
     outputDir,
@@ -227,14 +251,12 @@ Options:
     bodyImages,
     minPages: newspicRenderSpec.min_pages,
     maxPages: newspicRenderSpec.max_pages,
-    accountVisualParams: state.route.account_visual_params
-      ? {
-          footer: state.route.account_visual_params.footer,
-          bg: state.route.account_visual_params.bg,
-          highlight: state.route.account_visual_params.highlight,
-          fallbackIcon: state.route.account_visual_params.fallback_icon,
-        }
-      : undefined,
+    accountVisualParams: {
+      footer: branding.footerText,
+      bg: state.route.account_visual_params?.bg,
+      highlight: state.route.account_visual_params?.highlight,
+      fallbackIcon: branding.logo,
+    },
     theme: routePrimary === "wechat-newspic" ? getLongformTheme(state.route.account) : undefined,
     template,
   });

package/src/commands/republish.ts

@@ -36,8 +36,9 @@ import {
   upsertPublishResult,
 } from "../providers/publish-core";
 import { loadTaskState } from "../task-manager";
+import { publishOutcome, type CommandOutcome } from "../command-outcome";
 
-export async function republish(args: string[]): Promise<void> {
+export async function republish(args: string[]): Promise<void | CommandOutcome> {
   const parsed = parseArgs(args);
 
   if (parsed.help) {
@@ -182,6 +183,8 @@ Examples:
     output.errors = errors;
   }
   printResult(output);
+  return publishOutcome(dryRun ? results : state.publish.results.filter((result) => newTargets.some((target) =>
+    target.route === result.route && target.account === result.account)), dryRun || results.length === 0);
   } finally {
     await releaseOperationLock();
   }

package/src/commands/sync-blog.ts

@@ -8,8 +8,9 @@ import {
 } from "../state";
 import { loadTaskState } from "../task-manager";
 import { publishBlogRoute } from "../providers/blog";
+import { publishOutcome, type CommandOutcome } from "../command-outcome";
 
-export async function syncBlog(args: string[]): Promise<void> {
+export async function syncBlog(args: string[]): Promise<void | CommandOutcome> {
   const parsed = parseArgs(args);
 
   if (parsed.help) {
@@ -50,7 +51,7 @@ Options:
 
   if (dryRun) {
     printResult({ ...result, mode: state.mode }, renderSyncBlog);
-    return;
+    return publishOutcome([result], true);
   }
 
   // Write result back to state
@@ -67,6 +68,7 @@ Options:
     ...result,
     mode: finalState.mode,
   }, renderSyncBlog);
+  return publishOutcome([result]);
   } finally {
     await releaseOperationLock();
   }

package/src/commands/wechat-export.ts

@@ -2,6 +2,8 @@ import { spawn } from "child_process";
 import { resolve } from "path";
 import { flagArg, optionalArg, parseArgs, requireArg } from "../args";
 import { printResult, renderWechatExport } from "../output";
+import { commandError, type CommandOutcome } from "../command-outcome";
+import { reportProgress } from "../monitor/recorder";
 import { loadConfig, resolveConfigRelativePath } from "../config";
 import { resolveMarkdownRenderer } from "../adapter-loader";
 import { WechatExportError } from "../wechat-preview";
@@ -54,7 +56,7 @@ async function openUrl(url: string): Promise<void> {
   }
 }
 
-export async function wechatExport(args: string[]): Promise<void> {
+export async function wechatExport(args: string[]): Promise<void | CommandOutcome> {
   const parsed = parseArgs(args);
 
   if (parsed.help) {
@@ -114,6 +116,7 @@ ${CSS_DEMO}
 
   try {
     const result = await markdownRenderer.render({
+      onProgress: reportProgress,
       markdownPath,
       outPath,
       account,
@@ -154,6 +157,7 @@ ${CSS_DEMO}
         if (open && preview_url) await openUrl(preview_url);
       } else {
         preview_register_error = reg.error;
+        console.warn(`微信预览登记失败：${reg.error || "未知原因"}`);
       }
     }
 
@@ -197,8 +201,7 @@ ${CSS_DEMO}
           renderWechatExport,
         );
         if (open && reg.preview_url) await openUrl(reg.preview_url);
-        process.exitCode = 1;
-        return;
+        return { status: "failed", errors: [commandError(error, error.kind)] };
       }
     }
     throw error;

package/src/config.ts

@@ -10,6 +10,7 @@ import {
 import { homedir, platform } from "os";
 import { dirname, isAbsolute, join, resolve } from "path";
 import { PipelineConfigSchema } from "./schema/config";
+import { mergeCoverSettings } from "./schema/cover-theme";
 
 import type {
   PipelineConfig,
@@ -196,6 +197,7 @@ export function normalizeConfig(value: unknown, legacyValue?: unknown): Pipeline
     cos: mergedCos,
     plugins: mergedPlugins,
     imgx: mergedImgx,
+    render: mergeCoverSettings(legacy.render ?? {}, source.render ?? {}),
   });
 }
 
@@ -403,6 +405,9 @@ export function setConfigValue(
 ): PipelineConfig {
   const next = JSON.parse(JSON.stringify(config)) as PipelineConfig;
   const segments = key.split(".").filter(Boolean);
+  if (segments.some((segment) => ["__proto__", "constructor", "prototype"].includes(segment))) {
+    throw new Error("invalid config key");
+  }
   if (segments.length === 0) {
     throw new Error("config key cannot be empty");
   }

package/src/cover-theme-presets.json

@@ -0,0 +1,59 @@
+{
+  "business": {
+    "name": "商务", "description": "浅灰与深蓝，左对齐标题与细线",
+    "colors": { "text": "#13243A", "accent": "#2457A7", "muted": "#586A80" },
+    "background": { "fill": { "type": "solid", "color": "#F1F5F9" } },
+    "decoration": { "pattern": "lines", "color": "#2457A7", "opacity": 0.18 }
+  },
+  "technology": {
+    "name": "科技", "description": "深蓝渐变与青色网格",
+    "colors": { "text": "#EAF4FF", "accent": "#67E8F9", "muted": "#A6BDD8" },
+    "background": { "fill": { "type": "linear", "angle": 135, "stops": [{ "color": "#0B1027", "offset": 0 }, { "color": "#182B5B", "offset": 100 }] } },
+    "decoration": { "pattern": "grid", "color": "#67E8F9", "opacity": 0.1, "size": 48 }
+  },
+  "minimal": {
+    "name": "简约", "description": "白底黑字，宽留白",
+    "colors": { "text": "#18181B", "accent": "#52525B", "muted": "#71717A" },
+    "background": { "fill": { "type": "solid", "color": "#FFFFFF" } },
+    "layout": { "safeArea": { "left": 108, "right": 108, "top": 108, "bottom": 72 } }
+  },
+  "solid": {
+    "name": "纯色", "description": "钴蓝与白色大字，黄色强调",
+    "colors": { "text": "#FFFFFF", "accent": "#FFE08A", "muted": "#D9E1FF" },
+    "background": { "fill": { "type": "solid", "color": "#3155D9" } },
+    "layout": { "textAlign": "center" }
+  },
+  "cute": {
+    "name": "可爱", "description": "粉黄渐变、手写字与轻盈圆点",
+    "typography": { "title": { "fontFamily": "LXGWWenKai", "fontWeight": 700 }, "subtitle": { "fontFamily": "LXGWWenKai", "fontSize": 56, "minFontSize": 40, "fontWeight": 400, "lineHeight": 1.4 } },
+    "colors": { "text": "#623C47", "accent": "#D64B78", "muted": "#856675" },
+    "background": { "fill": { "type": "linear", "angle": 150, "stops": [{ "color": "#FFF1F4", "offset": 0 }, { "color": "#FFF6DF", "offset": 100 }] } },
+    "decoration": { "pattern": "dots", "color": "#E4658C", "opacity": 0.12, "size": 58 },
+    "layout": { "textAlign": "center" }
+  },
+  "serious": {
+    "name": "严肃", "description": "米白纸面、墨色宋体与暗红强调",
+    "typography": { "title": { "fontFamily": "LXGWNeoZhiSongPlus", "fontWeight": 700 } },
+    "colors": { "text": "#202020", "accent": "#8A302B", "muted": "#655E54" },
+    "background": { "fill": { "type": "solid", "color": "#F3F0E8" } },
+    "decoration": { "pattern": "lines", "color": "#8A302B", "opacity": 0.18 }
+  },
+  "abstract": {
+    "name": "抽象", "description": "淡紫与冰蓝，边缘错位圆环",
+    "colors": { "text": "#302456", "accent": "#7653D5", "muted": "#695A87" },
+    "background": { "fill": { "type": "radial", "position": { "x": 20, "y": 10 }, "stops": [{ "color": "#EEE6FF", "offset": 0 }, { "color": "#E1F2FF", "offset": 100 }] } },
+    "decoration": { "pattern": "rings", "color": "#7653D5", "opacity": 0.16, "size": 180 }
+  },
+  "entertainment": {
+    "name": "娱乐", "description": "明黄底色、深紫大字与粉色几何装饰",
+    "colors": { "text": "#241341", "accent": "#B52D74", "muted": "#62532B" },
+    "background": { "fill": { "type": "solid", "color": "#FFF06A" } },
+    "decoration": { "pattern": "burst", "color": "#ED4F9A", "opacity": 0.32, "size": 144 }
+  },
+  "fresh-sage": { "name": "清新绿", "description": "早早集市原有绿色配色" },
+  "soft-rose": {
+    "name": "柔和粉", "description": "古一账号原有粉色配色",
+    "colors": { "text": "#1A1A1A", "accent": "#CA6093", "muted": "#795C6D" },
+    "background": { "fill": { "type": "solid", "color": "#FAF5F8" } }
+  }
+}

package/src/imgx/assets/browser/cover.css

@@ -0,0 +1,25 @@
+* { box-sizing: border-box; }
+html, body { margin: 0; }
+.cover { width: var(--width); height: var(--height); position: relative; overflow: hidden; background: var(--background); color: var(--text); }
+.layer { position: absolute; inset: 0; width: 100%; height: 100%; pointer-events: none; }
+.pattern { opacity: var(--decoration-opacity); }
+.pattern-lines { border-top: 2px solid var(--decoration); border-bottom: 2px solid var(--decoration); inset: 24px; width: auto; height: auto; }
+.pattern-grid { background-image: linear-gradient(var(--decoration) 1px, transparent 1px), linear-gradient(90deg, var(--decoration) 1px, transparent 1px); background-size: var(--decoration-size) var(--decoration-size); }
+.pattern-dots { background-image: radial-gradient(circle, var(--decoration) 2px, transparent 3px); background-size: var(--decoration-size) var(--decoration-size); }
+.pattern-rings { background: repeating-radial-gradient(circle at 105% 8%, transparent 0, transparent calc(var(--decoration-size) - 3px), var(--decoration) calc(var(--decoration-size) - 2px), var(--decoration) var(--decoration-size)); }
+.pattern-burst { background: repeating-conic-gradient(from 15deg at 105% -5%, var(--decoration) 0deg 8deg, transparent 8deg 28deg); mask-image: radial-gradient(circle at 100% 0, black 0, transparent 65%); }
+.copy { position: absolute; inset: 0 auto 0 0; width: var(--copy-width); }
+.text-area { position: absolute; top: var(--top); right: var(--right); bottom: calc(var(--bottom) + 80px); left: var(--left); display: flex; flex-direction: column; justify-content: var(--vertical); text-align: var(--align); }
+.text-stack { flex: 0 0 auto; width: 100%; }
+.title, .subtitle { margin: 0; white-space: pre-wrap; text-wrap: balance; overflow-wrap: anywhere; }
+.title { font-family: var(--title-font), sans-serif; font-size: var(--title-size); font-weight: var(--title-weight); line-height: var(--title-leading); letter-spacing: var(--title-tracking); }
+.subtitle { margin-top: var(--block-gap); font-family: var(--subtitle-font), serif; font-size: var(--subtitle-size); font-weight: var(--subtitle-weight); line-height: var(--subtitle-leading); letter-spacing: var(--subtitle-tracking); }
+.subtitle:empty { display: none; }
+.highlight { color: var(--accent); }
+.signature { position: absolute; left: var(--left); right: var(--right); bottom: var(--bottom); display: flex; align-items: center; gap: 12px; color: var(--muted); }
+.signature span { min-width: 0; overflow-wrap: anywhere; font-family: var(--footer-font), sans-serif; font-size: var(--footer-size); font-weight: var(--footer-weight); line-height: var(--footer-leading); letter-spacing: var(--footer-tracking); }
+.signature img { flex: 0 0 auto; width: 36px; height: 36px; border-radius: 50%; object-fit: contain; }
+.logo-panel { display: none; }
+.cover-banner .signature img { display: none; }
+.cover-banner .logo-panel { display: flex; position: absolute; right: 0; top: 0; width: 400px; height: 400px; align-items: center; justify-content: center; }
+.logo-panel img { width: 216px; height: 216px; border-radius: 40px; object-fit: contain; }

package/src/imgx/assets/browser/cover.js

@@ -0,0 +1,40 @@
+// 字号测量和最终成图都使用同一个 DOM，避免二次换行偏差。
+window.__zzhubRenderReady = (async function fitCover() {
+  try {
+    const config = JSON.parse(document.getElementById("cover-config").textContent);
+    const cover = document.querySelector(".cover");
+    const area = document.querySelector(".text-area");
+    const stack = document.querySelector(".text-stack");
+    const signature = document.querySelector(".signature");
+    const title = document.querySelector(".title");
+    const subtitle = document.querySelector(".subtitle");
+    // 大型 CJK 字体必须加载完成，不能用回退字体计算字号。
+    await Promise.all(Object.values(config.typography).map(font => document.fonts.load(`${font.fontWeight} ${font.fontSize}px "${font.fontFamily}"`)));
+    await document.fonts.ready;
+    await Promise.all([...document.images].map(image => image.decode()));
+    area.style.bottom = `${config.layout.safeArea.bottom + signature.getBoundingClientRect().height + 32}px`;
+    if (area.clientWidth <= 0 || area.clientHeight <= 0) throw new Error("封面安全区无法容纳文字和署名");
+    function fit(ratio) {
+      for (const role of ["title", "subtitle"]) {
+        const font = config.typography[role];
+        cover.style.setProperty(`--${role}-size`, `${font.minFontSize + (font.fontSize - font.minFontSize) * ratio}px`);
+      }
+      return stack.getBoundingClientRect().height <= area.clientHeight + 0.5
+        && title.scrollWidth <= title.clientWidth + 1
+        && subtitle.scrollWidth <= subtitle.clientWidth + 1;
+    }
+    if (!fit(0)) throw new Error("完整标题在最小字号下仍超出安全区，请缩短标题或调整主题字号、安全区");
+    let low = 0;
+    let high = 1;
+    for (let iteration = 0; iteration < 12; iteration++) {
+      const middle = (low + high) / 2;
+      if (fit(middle)) low = middle;
+      else high = middle;
+    }
+    fit(low);
+    document.documentElement.dataset.coverStatus = "ready";
+  } catch (error) {
+    document.documentElement.dataset.coverStatus = "error";
+    document.documentElement.dataset.coverError = encodeURIComponent(error instanceof Error ? error.message : String(error));
+  }
+})();