@zzclub/pipeline 0.12.0 → 0.13.0

package/README.md

@@ -747,6 +747,8 @@ bun run src/cli.ts init ... --note-id NOTE_ID
 
 ## imgx 渲染子系统
 
+封面支持 `render.cover` 配置、十套主题、背景图与透明边框，以及供 App 使用的 JSON Schema 和预览输出。详见 [封面主题与图片排版](docs/render-themes.md)，可直接导入 [配置示例](examples/cover-themes.json)。
+
 - 基于 Chrome headless 和 `@napi-rs/canvas`
 - 模板包括 `longform-3-4`（newspic 长文）、`poster-3-4`（单页卡片）和 `wechat-cover-split`（文章封面）
 - 主题包括 `paper-sage`（默认账号）和 `linen-news`（`ancientone` 账号）
@@ -853,7 +855,7 @@ bun install --global .
 运行时依赖检查：
 - `@napi-rs/canvas` — 图片渲染需要，懒加载，缺失时提示安装命令
 - Chrome — HTML 导出需要，缺失时提示安装命令
-- CJK 字体 — npm 模式下自动从 CDN 下载到 `~/.config/zzhub-pipeline/fonts/`
+- CJK 字体 — 随 CLI 附带，生成图片时按需读取本地文件，不触发网络下载；封面也支持本机字体名称
 
 ## 发布提供者
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zzclub/pipeline",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "type": "module",
   "bin": {
     "zzp": "./src/cli.ts",
@@ -24,7 +24,7 @@
     "release:major": "changelogen --release --major --push"
   },
   "dependencies": {
-    "@chenglou/pretext": "^0.0.5",
+    "@chenglou/pretext": "0.0.8",
     "@zzclub/milkdown-article-style": "0.1.1",
     "image-size": "^2.0.2",
     "pngjs": "^7.0.0",

package/src/adapter-types.ts

@@ -10,6 +10,7 @@
 
 import type { RenderAsset, RoutePrimary, WorkflowState } from "./state";
 import type { MonitorProgress } from "./monitor/types";
+import type { ResolvedCoverTheme } from "./schema/cover-theme";
 
 // ── Doctor check ──────────────────────────────────────────────────
 
@@ -27,6 +28,8 @@ export interface PipelinePluginDoctorCheck {
  * to runRenderArticleCli and runRenderCardCli via CLI argv.
  */
 export interface ImageRenderInput {
+  /** 已解析的封面主题；旧插件可忽略。 */
+  coverTheme?: ResolvedCoverTheme;
   /** 可选进度通知，旧插件可忽略。 */
   onProgress?: (progress: MonitorProgress) => void;
   /** Workflow state providing context (route, metadata, etc.) */

package/src/adapters/builtin-image-renderer.test.ts

@@ -0,0 +1,32 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { defaultState, normalizeNewspicRenderSpec } from "../state";
+import { builtinImageRenderer } from "./builtin-image-renderer";
+
+test("multi mode without page specs renders body pages and excludes stale files", async () => {
+  const workspace = await mkdtemp(join(tmpdir(), "zzhub-auto-pages-"));
+  const previous = process.env.TEST_RENDER_CARD_STUB;
+  process.env.TEST_RENDER_CARD_STUB = "1";
+  try {
+    const outputDir = join(workspace, "images");
+    await mkdir(outputDir);
+    await writeFile(join(outputDir, "article-99.png"), "previous output");
+    const state = defaultState();
+    state.run_id = "auto-pages";
+    state.workspace_root = workspace;
+    state.route.primary = "wechat-newspic";
+    state.intent.newspic_render = normalizeNewspicRenderSpec({ pagination_mode: "multi", min_pages: 2, target_fill_ratio: 0.8 });
+    const result = await builtinImageRenderer.render({ state, route: "wechat-newspic", outputDir, title: "完整标题：副标题", bodyText: "正文应该舒适易读，不需要手工指定每一页。".repeat(24) });
+    expect(result.pageCount).toBeGreaterThanOrEqual(2);
+    expect(result.assets.filter(asset => asset.kind === "page")).toHaveLength(result.pageCount);
+    expect(result.assets.every(asset => !asset.path.endsWith("article-99.png"))).toBe(true);
+    expect((await readFile(result.assets.find(asset => asset.kind === "page")!.path)).subarray(1, 4).toString()).toBe("PNG");
+    expect(await readFile(join(outputDir, "article-99.png"), "utf8")).toBe("previous output");
+  } finally {
+    if (previous === undefined) delete process.env.TEST_RENDER_CARD_STUB;
+    else process.env.TEST_RENDER_CARD_STUB = previous;
+    await rm(workspace, { recursive: true, force: true });
+  }
+}, 30_000);

package/src/adapters/builtin-image-renderer.ts

@@ -5,7 +5,7 @@
  * when no user-provided plugin is configured.
  */
 
-import { mkdir, readdir, rm, rmdir, writeFile } from "fs/promises";
+import { mkdir, rm, rmdir, writeFile } from "fs/promises";
 import { join } from "path";
 
 import { runRenderArticleCli, runRenderCardCli } from "../imgx";
@@ -17,13 +17,15 @@ import {
   generateCoverTitle,
 } from "../text";
 import { getLongformTheme } from "../routes";
-import { resolveWorkspacePaths } from "../config";
+import { loadConfig, resolveWorkspacePaths } from "../config";
+import { resolveRenderBranding } from "../render-branding";
 import type {
   ImageRenderPlugin,
   ImageRenderInput,
   ImageRenderOutput,
   PipelinePluginDoctorCheck,
 } from "../adapter-types";
+import { normalizeNewspicRenderSpec } from "../state";
 import type {
   NewspicRenderSpec,
   RenderAsset,
@@ -32,20 +34,6 @@ import type {
 
 // ── Helpers ──────────────────────────────────────────────────────
 
-function appendPosterVisualArgs(
-  cmdParts: string[],
-  visualParams: AccountVisualParams | null,
-  highlightWords: string[],
-): void {
-  if (visualParams) {
-    cmdParts.push("--highlight", visualParams.highlight);
-    cmdParts.push("--bg", visualParams.bg);
-    cmdParts.push("--footer", visualParams.footer);
-    cmdParts.push("--fallback-icon", visualParams.fallback_icon);
-  }
-  cmdParts.push("--highlight-words", highlightWords.join(","));
-}
-
 type ResolvedPageImageSpecFile = {
   default_image_layout: string;
   target_fill_ratio: number;
@@ -139,29 +127,18 @@ async function renderCover(
   visualParams: AccountVisualParams | null,
   highlightWords: string[],
   onProgress?: ImageRenderInput["onProgress"],
+  coverTheme?: ImageRenderInput["coverTheme"],
 ): Promise<RenderAsset> {
   const coverOut = join(outputDir, "cover.png");
   const route = template === "wechat-cover-split" ? "wechat-article" : "wechat-newspic";
-
-  if (template === "wechat-cover-split") {
-    const cmdParts = ["--template", "wechat-cover-split", "--text", title];
-    if (visualParams) {
-      cmdParts.push("--highlight", visualParams.highlight);
-      cmdParts.push("--bg", visualParams.bg);
-      cmdParts.push("--footer", visualParams.footer);
-      cmdParts.push("--fallback-icon", visualParams.fallback_icon);
-    }
-    cmdParts.push("--highlight-words", highlightWords.join(","));
-    cmdParts.push("--out", coverOut);
-    runRenderCardCli(cmdParts, onProgress);
-  } else {
-    const cmdParts = ["--template", "poster-3-4", "--text", title];
-    appendPosterVisualArgs(cmdParts, visualParams, highlightWords);
-    cmdParts.push("--out", coverOut);
-    runRenderCardCli(cmdParts, onProgress);
+  const args = ["--template", template, "--text", title, "--out", coverOut, "--highlight-words", highlightWords.join(",")];
+  if (visualParams) {
+    args.push("--footer", visualParams.footer, "--fallback-icon", visualParams.fallback_icon);
+    // 旧直接调用仍支持账号配色；已选主题使用自己的颜色。
+    if (!coverTheme) args.push("--bg", visualParams.bg, "--highlight", visualParams.highlight);
   }
-
-  return { kind: "cover", route: route as RenderAsset["route"], path: coverOut };
+  await runRenderCardCli(args, onProgress, coverTheme);
+  return { kind: "cover", route, path: coverOut };
 }
 
 async function renderLongformPages(
@@ -197,6 +174,7 @@ async function renderLongformPages(
     "--text-file", tempBodyPath,
     "--out-dir", outputDir,
     "--theme", theme,
+    "--target-fill-ratio", String(newspicRenderSpec.target_fill_ratio),
   ];
 
   if (newspicRenderSpec.min_pages > 1) {
@@ -205,10 +183,9 @@ async function renderLongformPages(
   if (newspicRenderSpec.max_pages > 0) {
     pageParts.push("--max-pages", String(newspicRenderSpec.max_pages));
   }
+  if (newspicRenderSpec.require_image_every_page) pageParts.push("--require-image-every-page");
 
-  if (vp?.footer) {
-    pageParts.push("--footer", vp.footer);
-  }
+  if (vp) pageParts.push("--footer", vp.footer, "--icon", vp.fallback_icon);
 
   const highlightWords = input.state.route.highlight_words ?? [];
   if (highlightWords.length > 0) {
@@ -232,7 +209,7 @@ async function renderLongformPages(
 
   let result: RenderArticleResult;
   try {
-    result = runRenderArticleCli(pageParts, input.onProgress);
+    result = await runRenderArticleCli(pageParts, input.onProgress);
   } finally {
     if (!keepTempFiles) {
       await rm(tempDir, { recursive: true, force: true });
@@ -245,20 +222,13 @@ async function renderLongformPages(
     throw new Error(`newspic render constraints not satisfied: ${errors.join("; ")}`);
   }
 
-  // Discover generated page files
-  const files = await readdir(outputDir);
-  const pageFiles = files.filter((f) => /^article-\d+\.png$/.test(f)).sort();
-
-  const assets: RenderAsset[] = [];
-  for (let i = 0; i < pageFiles.length; i++) {
-    assets.push({
-      kind: "page",
-      route: "wechat-newspic",
-      index: i + 1,
-      path: join(outputDir, pageFiles[i]),
-    });
-  }
-
+  // 仅返回本次实际生成的页，目录中的旧页不参与结果。
+  const assets: RenderAsset[] = result.pages.map(page => ({
+    kind: "page",
+    route: "wechat-newspic",
+    index: page.page,
+    path: join(outputDir, "article-" + String(page.page).padStart(2, "0") + ".png"),
+  }));
   return { assets, pageCount: result.pageCount, pages: result.pages };
 }
 
@@ -266,7 +236,7 @@ async function renderLongformPages(
 
 export const builtinImageRenderer: ImageRenderPlugin = {
   name: "builtin-imgx",
-  version: "1.0.0",
+  version: "1.1.0",
 
   async doctor(): Promise<PipelinePluginDoctorCheck[]> {
     const checks: PipelinePluginDoctorCheck[] = [];
@@ -297,20 +267,19 @@ export const builtinImageRenderer: ImageRenderPlugin = {
     // Normalize visual params: adapter input uses camelCase, state uses snake_case
     const adapterVp = input.accountVisualParams;
     const stateVp = state.route.account_visual_params;
-    const vp: AccountVisualParams | null = adapterVp
-      ? {
-          footer: adapterVp.footer ?? "",
-          bg: adapterVp.bg ?? "",
-          highlight: adapterVp.highlight ?? "",
-          fallback_icon: adapterVp.fallbackIcon ?? "",
-        }
-      : stateVp;
+    const branding = resolveRenderBranding(loadConfig(), state.route.account);
+    const vp: AccountVisualParams = {
+      footer: adapterVp?.footer ?? branding.footerText,
+      bg: adapterVp?.bg ?? stateVp?.bg ?? "",
+      highlight: adapterVp?.highlight ?? stateVp?.highlight ?? "",
+      fallback_icon: adapterVp?.fallbackIcon ?? branding.logo,
+    };
 
     await mkdir(outputDir, { recursive: true });
 
     if (route === "wechat-article") {
       // Article: cover only (wechat-cover-split)
-      const cover = await renderCover("wechat-cover-split", title, outputDir, vp, highlightWords, input.onProgress);
+      const cover = await renderCover("wechat-cover-split", title, outputDir, vp, highlightWords, input.onProgress, input.coverTheme);
       return { assets: [cover], pageCount: 1, pages: [{ page: 1, imageCount: 0, imageSources: [] }] };
     }
 
@@ -319,20 +288,19 @@ export const builtinImageRenderer: ImageRenderPlugin = {
     }
 
     // wechat-newspic: determine short vs long
+    const savedSpec = normalizeNewspicRenderSpec(state.intent.newspic_render);
     const newspicRenderSpec: NewspicRenderSpec = {
-      pagination_mode: input.pageSpecs && input.pageSpecs.length > 0 ? "multi" : "single",
-      min_pages: input.minPages ?? 1,
-      max_pages: input.maxPages ?? 0,
-      require_image_every_page: false,
-      default_image_layout: "staggered",
-      target_fill_ratio: 0.8,
-      page_specs: (input.pageSpecs ?? []).map((ps) => ({
+      ...savedSpec,
+      pagination_mode: input.template === "longform-3-4" ? "multi" : input.template === "poster-3-4" ? "single" : savedSpec.pagination_mode,
+      min_pages: input.minPages ?? savedSpec.min_pages,
+      max_pages: input.maxPages ?? savedSpec.max_pages,
+      page_specs: input.pageSpecs?.map(ps => ({
         page: ps.page,
         image_markers: ps.imageMarkers ?? [],
         image_layout: ps.imageLayout ?? null,
         target_fill_ratio: ps.targetFillRatio ?? null,
         note: ps.note ?? null,
-      })),
+      })) ?? savedSpec.page_specs,
     };
 
     const isLong = newspicRenderSpec.pagination_mode === "multi";
@@ -340,13 +308,13 @@ export const builtinImageRenderer: ImageRenderPlugin = {
     if (!isLong) {
       // Short: single poster cover
       const coverTitle = generateCoverTitle(title);
-      const cover = await renderCover("poster-3-4", coverTitle, outputDir, vp, highlightWords, input.onProgress);
+      const cover = await renderCover("poster-3-4", coverTitle, outputDir, vp, highlightWords, input.onProgress, input.coverTheme);
       return { assets: [cover], pageCount: 1, pages: [{ page: 1, imageCount: 0, imageSources: [] }] };
     }
 
     // Long: cover + article pages
     const coverTitle = generateCoverTitle(title);
-    const cover = await renderCover("poster-3-4", coverTitle, outputDir, vp, highlightWords, input.onProgress);
+    const cover = await renderCover("poster-3-4", coverTitle, outputDir, vp, highlightWords, input.onProgress, input.coverTheme);
 
     const bodyImages = input.bodyImages ?? [];
     const pageResult = await renderLongformPages(input, outputDir, newspicRenderSpec, bodyImages, vp);

package/src/commands/config.ts

@@ -1,4 +1,7 @@
 import { readFileSync } from "fs";
+import { z } from "zod";
+import { CoverConfigSchema, mergeCoverSettings } from "../schema/cover-theme";
+import { RenderBrandingSchema, RenderConfigSchema } from "../schema/config";
 import { parseArgs, optionalArg, flagArg } from "../args";
 import { printResult, renderConfig } from "../output";
 import {
@@ -29,6 +32,7 @@ Options:
   --json       Force JSON output for scalar reads
   --export     Print full config as JSON (secrets redacted; use --raw to show all)
   --import     Path to a JSON file to merge into current config
+  --schema     Print JSON Schema (--key render | render.cover | render.branding)
   --raw        Show secrets unredacted (use with --export)
 
 Examples:
@@ -39,6 +43,14 @@ Examples:
     return;
   }
 
+  // schema 查询不依赖配置文件是否可用，便于 App 修复配置。
+  if (flagArg(parsed, "schema")) {
+    const schemas: Record<string, z.ZodType> = { render: RenderConfigSchema, "render.cover": CoverConfigSchema, "render.branding": RenderBrandingSchema };
+    const schema = schemas[optionalArg(parsed, "key") ?? ""];
+    if (!schema) throw new Error("--schema requires --key render | render.cover | render.branding");
+    printResult(z.toJSONSchema(schema), data => JSON.stringify(data, null, 2));
+    return;
+  }
   const config = loadConfig();
 
   // --export
@@ -95,6 +107,7 @@ Examples:
         ...(isPlainObject(importedObj.plugins) ? importedObj.plugins : {}),
       },
       imgx: { ...config.imgx, ...(isPlainObject(importedObj.imgx) ? importedObj.imgx : {}) },
+      render: mergeCoverSettings(config.render, importedObj.render ?? {}),
     };
     // Soft-fill known account display names + Zod defaults / strip unknowns
     const merged = normalizeConfig(raw);
@@ -118,7 +131,7 @@ Examples:
     const currentValue = getConfigValue(config, key);
     const redactedValue = redactConfigValue(key, currentValue);
     if (forceJson || typeof currentValue !== "string") {
-      printResult({ key, value: redactedValue }, renderConfig);
+      printResult({ key, value: redactedValue }, forceJson ? data => JSON.stringify(data, null, 2) : renderConfig);
       return;
     }
     printResult(String(redactedValue), renderConfig);

package/src/commands/imgx.ts

@@ -6,7 +6,7 @@ import {
 } from "../imgx";
 import { ensureFonts } from "../runtime-paths";
 
-type ImgxHandler = (args: string[]) => void;
+type ImgxHandler = (args: string[]) => unknown;
 
 const IMGX_COMMANDS: Record<string, ImgxHandler> = {
   "render-article": runRenderArticleCli,
@@ -28,9 +28,9 @@ export async function imgxCommand(args: string[]): Promise<void> {
     throw new Error(`Unknown imgx subcommand: ${subcommand}`);
   }
 
-  await ensureFonts();
+  if (subcommand !== "render-card" && subcommand !== "render-article") await ensureFonts();
   try {
-    handler(args.slice(1));
+    await handler(args.slice(1));
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     if (msg.includes("@napi-rs/canvas") || msg.includes("Cannot find package")) {

package/src/commands/ingest-handoff.ts

@@ -5,6 +5,7 @@ import { parseArgs, optionalArg, requireArg } from "../args";
 import { loadConfig, resolveWorkspacePaths, resolveWorkspaceRoot } from "../config";
 import { printResult } from "../output";
 import { resolveFullRoute } from "../routes";
+import { resolveCoverTheme } from "../schema/cover-theme";
 import {
   defaultContentReview,
   defaultState,
@@ -12,6 +13,7 @@ import {
   getRunStatePath,
   readResolvedState,
   resetDerivedState,
+  reenterRender,
   writeState,
   type ContentForm,
   type HandoffAuthoringPolicy,
@@ -23,6 +25,7 @@ import {
 import { findTask, getTaskByStatePath } from "../task-manager";
 
 interface PublishHandoffInput {
+  cover_theme?: string | null;
   content_form: ContentForm;
   body_path: string;
   target_account: string;
@@ -34,6 +37,7 @@ interface PublishHandoffInput {
 type WorkflowHandoffMode = "new" | "resume";
 
 interface WorkflowHandoffInput {
+  cover_theme?: string | null;
   mode?: WorkflowHandoffMode;
   state_path?: string;
   run_id?: string;
@@ -50,6 +54,7 @@ interface WorkflowHandoffInput {
 }
 
 interface ResolvedWorkflowHandoff {
+  cover_theme?: string | null;
   source: "publish_handoff" | "workflow_handoff";
   mode: WorkflowHandoffMode;
   state_path?: string;
@@ -162,6 +167,7 @@ function parsePublishHandoff(raw: unknown): ResolvedWorkflowHandoff {
 
   return {
     source: "publish_handoff",
+    cover_theme: input.cover_theme === null ? null : cleanString(input.cover_theme, "publish_handoff.cover_theme"),
     mode: "new",
     content_form: contentForm,
     body_path: bodyPath,
@@ -193,6 +199,7 @@ function parseWorkflowHandoff(raw: unknown): ResolvedWorkflowHandoff {
       : "new");
   const handoff: ResolvedWorkflowHandoff = {
     source: "workflow_handoff",
+    cover_theme: input.cover_theme === null ? null : cleanString(input.cover_theme, "workflow_handoff.cover_theme"),
     mode,
     state_path: cleanString(input.state_path, "workflow_handoff.state_path"),
     run_id: cleanString(input.run_id, "workflow_handoff.run_id"),
@@ -319,6 +326,11 @@ async function applyHandoffToState(
 ): Promise<void> {
   const targets: Target[] = state.intent.targets.length > 0 ? state.intent.targets : ["wechat"];
   let restartFromPrepare = false;
+  const themeChanged = handoff.cover_theme !== undefined && handoff.cover_theme !== state.intent.cover_theme;
+  if (themeChanged) {
+    resolveCoverTheme(loadConfig().render.cover, "poster-3-4", handoff.target_account ?? state.route.account, handoff.cover_theme);
+    state.intent.cover_theme = handoff.cover_theme ?? null;
+  }
 
   const nextContentForm = handoff.content_form ?? state.intent.content_form;
   if (handoff.content_form && handoff.content_form !== state.intent.content_form) {
@@ -409,6 +421,9 @@ async function applyHandoffToState(
 
   if (restartFromPrepare) {
     resetDerivedState(state);
+  } else if (themeChanged && state.asset_path && state.content_review.status === "passed") {
+    // 仅更换主题时保留正文、审核和 prepare 产物。
+    reenterRender(state);
   }
 
   if (state.handoff.review_policy === "trust_user" && state.source_body_path) {

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/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"');
+  });
+});