@zzclub/pipeline 0.11.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 附带，生成图片时按需读取本地文件，不触发网络下载；封面也支持本机字体名称
 
 ## 发布提供者
 
@@ -866,6 +868,13 @@ bun install --global .
 
 Markdown → WeChat HTML 转换通过插件系统完成（默认使用内置 `builtin-wechat-preview` 适配器）。
 
+## 本机多任务监控
+
+`zzp monitor start` 按需启动共享 HTTP/SSE 服务，`monitor status` 查看状态，`monitor stop` 只停止监控。
+CLI 独立记录执行和错误，GUI 可同时订阅多个任务。新版业务失败会退出 1，调用方仍应读取失败响应和最新任务状态。
+
+详见 [监控接口与退出码迁移](docs/monitor.md)。
+
 ## 测试与验证
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zzclub/pipeline",
-  "version": "0.11.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

@@ -9,6 +9,8 @@
  */
 
 import type { RenderAsset, RoutePrimary, WorkflowState } from "./state";
+import type { MonitorProgress } from "./monitor/types";
+import type { ResolvedCoverTheme } from "./schema/cover-theme";
 
 // ── Doctor check ──────────────────────────────────────────────────
 
@@ -26,6 +28,10 @@ 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.) */
   state: WorkflowState;
 
@@ -117,6 +123,8 @@ export interface ImageRenderPlugin {
  * Maps to ExportMarkdownToWechatHtmlInput from wechat-preview.
  */
 export interface MarkdownRenderInput {
+  /** 可选进度通知，旧插件可忽略。 */
+  onProgress?: (progress: MonitorProgress) => void;
   /** Path to the markdown source file */
   markdownPath: string;
 

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;
@@ -138,29 +126,19 @@ async function renderCover(
   outputDir: string,
   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);
-  } else {
-    const cmdParts = ["--template", "poster-3-4", "--text", title];
-    appendPosterVisualArgs(cmdParts, visualParams, highlightWords);
-    cmdParts.push("--out", coverOut);
-    runRenderCardCli(cmdParts);
+  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(
@@ -196,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) {
@@ -204,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) {
@@ -231,7 +209,7 @@ async function renderLongformPages(
 
   let result: RenderArticleResult;
   try {
-    result = runRenderArticleCli(pageParts);
+    result = await runRenderArticleCli(pageParts, input.onProgress);
   } finally {
     if (!keepTempFiles) {
       await rm(tempDir, { recursive: true, force: true });
@@ -244,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 };
 }
 
@@ -265,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[] = [];
@@ -296,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);
+      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: [] }] };
     }
 
@@ -318,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";
@@ -339,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);
+      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);
+    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/adapters/builtin-markdown-renderer.ts

@@ -7,6 +7,7 @@
 
 import { exportMarkdownToWechatHtml } from "../wechat-preview";
 import { findChrome } from "../imgx/runtime";
+import { notifyProgress } from "../monitor/recorder";
 import type {
   MarkdownRenderPlugin,
   MarkdownRenderInput,
@@ -43,6 +44,7 @@ export const builtinMarkdownRenderer: MarkdownRenderPlugin = {
   },
 
   async render(input: MarkdownRenderInput): Promise<MarkdownRenderOutput> {
+    notifyProgress(input.onProgress, { stage: "render.html", message: "正在导出微信 HTML" });
     const result = await exportMarkdownToWechatHtml({
       markdownPath: input.markdownPath,
       outPath: input.outPath,
@@ -54,6 +56,7 @@ export const builtinMarkdownRenderer: MarkdownRenderPlugin = {
       timeoutMs: input.timeoutMs,
       debugDir: input.debugDir ?? undefined,
     });
+    notifyProgress(input.onProgress, { stage: "render.html", message: "微信 HTML 导出完成", current: 1, total: 1, unit: "files" });
 
     return {
       html: result.html,

package/src/cli.ts

@@ -5,6 +5,7 @@ import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 import { getDailyLogPath, runWithCommandLog } from "./logger";
 import { formatUsage, getCommandRegistry } from "./plugins";
+import { outcomeExitCode } from "./command-outcome";
 
 const COMMANDS = getCommandRegistry();
 
@@ -37,14 +38,19 @@ async function main() {
   }
 
   try {
-    await runWithCommandLog(cmd, args.slice(1), async () => {
-      await command.handler(args.slice(1));
-    });
+    // monitor 输出包含本机认证令牌，不能经过日志复制或监控自身。
+    const outcome = cmd === "monitor"
+      ? await command.handler(args.slice(1))
+      : await runWithCommandLog(cmd, args.slice(1), () => command.handler(args.slice(1)));
+    if (outcome) {
+      process.exitCode = outcomeExitCode(outcome);
+      for (const error of outcome.errors ?? []) console.error(`[zzhub-pipeline ${cmd}] ${error.code}: ${error.message}`);
+    }
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.error(`[zzhub-pipeline ${cmd}] Error: ${msg}`);
     console.error(`[zzhub-pipeline ${cmd}] Full log: ${getDailyLogPath()}`);
-    process.exit(1);
+    process.exitCode = 1;
   }
 }
 

package/src/command-outcome.ts

@@ -0,0 +1,50 @@
+import type { PublishResult } from "./state";
+
+/** 同一次执行共用的业务结果，独立于工作流是否完成。 */
+export interface CommandOutcome {
+  status: "success" | "skipped" | "waiting" | "partial_failure" | "failed";
+  errors?: CommandError[];
+}
+
+/** 可供终端和监控展示的错误，不推测可重试性。 */
+export interface CommandError {
+  code: string;
+  message: string;
+  stage?: string;
+  route?: string;
+  account?: string;
+  cause?: string;
+}
+
+/** 保留已有错误码和堆栈，未知异常使用统一兜底。 */
+export function commandError(error: unknown, code = "COMMAND_FAILED"): CommandError {
+  return {
+    code: error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : code,
+    message: error instanceof Error ? error.message : String(error),
+    ...(error instanceof Error && error.stack ? { cause: error.stack } : {}),
+  };
+}
+
+/** 出口只使用 0/1；等待输入和幂等跳过都是正常完成命令。 */
+export function outcomeExitCode(outcome: CommandOutcome): number {
+  return outcome.status === "failed" || outcome.status === "partial_failure" ? 1 : 0;
+}
+
+/** 仅汇总本次请求目标，避免历史失败污染新的追加发布。 */
+export function publishOutcome(results: PublishResult[], skipped = false): CommandOutcome {
+  const failures = results.filter((result) => result.status === "failed");
+  if (failures.length) {
+    return {
+      status: results.some((result) => result.status === "success") ? "partial_failure" : "failed",
+      errors: failures.map((result) => ({
+        code: "PUBLISH_TARGET_FAILED",
+        message: result.detail || "发布失败，provider 未提供原因",
+        stage: "publish",
+        route: result.route,
+        account: result.account,
+      })),
+    };
+  }
+  if (results.some((result) => result.status === "handoff")) return { status: "waiting" };
+  return { status: skipped || !results.length || results.every((result) => result.status === "skipped") ? "skipped" : "success" };
+}

package/src/commands/abandon.ts

@@ -17,6 +17,7 @@ import { parseArgs, optionalArg } from "../args";
 import { printResult, renderAbandon } from "../output";
 import { filterActiveTasks, getTaskByStatePath, listTasks, type ListedTask } from "../task-manager";
 import { updateState } from "../state";
+import type { CommandOutcome } from "../command-outcome";
 
 // ── Result type ───────────────────────────────────────────────────────────────
 
@@ -146,7 +147,7 @@ async function runInteractive(items: ListedTask[]): Promise<ListedTask[]> {
 
 // ── Command entry point ───────────────────────────────────────────────────────
 
-export async function abandon(args: string[]): Promise<void> {
+export async function abandon(args: string[]): Promise<void | CommandOutcome> {
   const parsed = parseArgs(args);
 
   if (parsed.help) {
@@ -184,7 +185,7 @@ Options:
     }
     const result = await abandonTask(task);
     printResult([result], renderAbandon);
-    return;
+    return abandonOutcome([result]);
   }
 
   // ── Interactive: TTY checkbox ─────────────────────────────────────────────
@@ -199,4 +200,14 @@ Options:
 
   const results = await Promise.all(chosen.map(abandonTask));
   printResult(results, renderAbandon);
+  return abandonOutcome(results);
+}
+
+/** 批量操作保留成功项，失败项决定本次执行结果。 */
+function abandonOutcome(results: AbandonResult[]): CommandOutcome {
+  const failed = results.filter((result) => !result.ok);
+  return {
+    status: failed.length ? (failed.length < results.length ? "partial_failure" : "failed") : "success",
+    errors: failed.map((result) => ({ code: "ABANDON_FAILED", message: result.error || "放弃任务失败" })),
+  };
 }

package/src/commands/checkpoint.ts

@@ -15,8 +15,9 @@ import { getTaskByStatePath } from "../task-manager";
 import { parseTaskViewMode, renderTaskStatusMarkdown } from "../task-views";
 import type { PhaseName } from "../state";
 import { validateForPhase } from "../state";
+import type { CommandOutcome } from "../command-outcome";
 
-export async function checkpoint(args: string[]): Promise<void> {
+export async function checkpoint(args: string[]): Promise<void | CommandOutcome> {
   const parsed = parseArgs(args);
 
   if (parsed.help) {
@@ -61,6 +62,6 @@ Options:
   }
 
   if (errors.length > 0) {
-    process.exit(1);
+    return { status: "failed", errors: errors.map((error) => ({ code: "CHECKPOINT_FAILED", message: `${error.field}: ${error.message}`, stage: phase })) };
   }
 }

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) {