@zzclub/pipeline 0.11.0 → 0.12.0

package/README.md

@@ -866,6 +866,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.12.0",
   "type": "module",
   "bin": {
     "zzp": "./src/cli.ts",

package/src/adapter-types.ts

@@ -9,6 +9,7 @@
  */
 
 import type { RenderAsset, RoutePrimary, WorkflowState } from "./state";
+import type { MonitorProgress } from "./monitor/types";
 
 // ── Doctor check ──────────────────────────────────────────────────
 
@@ -26,6 +27,8 @@ export interface PipelinePluginDoctorCheck {
  * to runRenderArticleCli and runRenderCardCli via CLI argv.
  */
 export interface ImageRenderInput {
+  /** 可选进度通知，旧插件可忽略。 */
+  onProgress?: (progress: MonitorProgress) => void;
   /** Workflow state providing context (route, metadata, etc.) */
   state: WorkflowState;
 
@@ -117,6 +120,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.ts

@@ -138,6 +138,7 @@ async function renderCover(
   outputDir: string,
   visualParams: AccountVisualParams | null,
   highlightWords: string[],
+  onProgress?: ImageRenderInput["onProgress"],
 ): Promise<RenderAsset> {
   const coverOut = join(outputDir, "cover.png");
   const route = template === "wechat-cover-split" ? "wechat-article" : "wechat-newspic";
@@ -152,12 +153,12 @@ async function renderCover(
     }
     cmdParts.push("--highlight-words", highlightWords.join(","));
     cmdParts.push("--out", coverOut);
-    runRenderCardCli(cmdParts);
+    runRenderCardCli(cmdParts, onProgress);
   } else {
     const cmdParts = ["--template", "poster-3-4", "--text", title];
     appendPosterVisualArgs(cmdParts, visualParams, highlightWords);
     cmdParts.push("--out", coverOut);
-    runRenderCardCli(cmdParts);
+    runRenderCardCli(cmdParts, onProgress);
   }
 
   return { kind: "cover", route: route as RenderAsset["route"], path: coverOut };
@@ -231,7 +232,7 @@ async function renderLongformPages(
 
   let result: RenderArticleResult;
   try {
-    result = runRenderArticleCli(pageParts);
+    result = runRenderArticleCli(pageParts, input.onProgress);
   } finally {
     if (!keepTempFiles) {
       await rm(tempDir, { recursive: true, force: true });
@@ -309,7 +310,7 @@ export const builtinImageRenderer: ImageRenderPlugin = {
 
     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);
       return { assets: [cover], pageCount: 1, pages: [{ page: 1, imageCount: 0, imageSources: [] }] };
     }
 
@@ -339,13 +340,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);
       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);
 
     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/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.ts

@@ -38,6 +38,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 +49,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) {
@@ -182,7 +184,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 +198,14 @@ 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" &&
@@ -212,6 +215,7 @@ Options:
     : [];
 
   const renderResult = await imageRenderer.render({
+    onProgress: reportProgress,
     state,
     bodyText: cleanBody,
     outputDir,

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/imgx/render-article.ts

@@ -29,6 +29,8 @@ import {
 } from "./runtime";
 import { layoutNextLineRange, prepareWithSegments } from "./pretext-adapter";
 import { ensurePretextRuntime } from "./pretext-runtime";
+import { notifyProgress } from "../monitor/recorder";
+import type { MonitorProgress } from "../monitor/types";
 
 const DEFAULT_CONTENT_WIDTH = getLongformGeometry(getLongformTheme("paper-sage")).contentWidth;
 
@@ -1170,7 +1172,8 @@ function renderPage(params: {
   });
 }
 
-export function runRenderArticleCli(argv: string[]): RenderArticleResult {
+export function runRenderArticleCli(argv: string[], onProgress?: (progress: MonitorProgress) => void): RenderArticleResult {
+  notifyProgress(onProgress, { stage: "render.layout", message: "正在计算分页" });
   const parsed = parseArgs(argv);
   const title = getArg(parsed, "title");
   if (title.length === 0) throw new Error("需要 --title");
@@ -1312,6 +1315,7 @@ export function runRenderArticleCli(argv: string[]): RenderArticleResult {
   };
 
   if (outPath.length > 0) {
+    notifyProgress(onProgress, { stage: "render.pages", current: 0, total: 1, unit: "pages" });
     const requestedPage = pageNum > 0 ? pageNum : 1;
     const page = pages[Math.max(0, Math.min(requestedPage - 1, pages.length - 1))]!;
     const total = pageTotal > 0 ? pageTotal : pages.length;
@@ -1328,6 +1332,7 @@ export function runRenderArticleCli(argv: string[]): RenderArticleResult {
       highlightWords,
     });
     printSaved(outPath);
+    notifyProgress(onProgress, { stage: "render.pages", current: 1, total: 1, unit: "pages" });
     return result;
   }
 
@@ -1336,6 +1341,7 @@ export function runRenderArticleCli(argv: string[]): RenderArticleResult {
     throw new Error("需要 --out (单页模式) 或 --out-dir (批量模式)");
   }
   for (let index = 0; index < pages.length; index++) {
+    notifyProgress(onProgress, { stage: "render.pages", message: `正在渲染第 ${index + 1} 页`, current: index, total: pages.length, unit: "pages" });
     const pageOut = join(outDir, `article-${String(index + 1).padStart(2, "0")}.png`);
     // DEBUG: dump layout coordinates
     const dbgPage = pages[index]!;
@@ -1355,6 +1361,7 @@ export function runRenderArticleCli(argv: string[]): RenderArticleResult {
       highlightWords,
     });
     printSaved(pageOut);
+    notifyProgress(onProgress, { stage: "render.pages", current: index + 1, total: pages.length, unit: "pages" });
   }
   return result;
 }

package/src/imgx/render-card.ts

@@ -19,6 +19,8 @@ import {
   screenshotHtml,
   TEMPLATES_DIR,
 } from "./runtime";
+import { notifyProgress } from "../monitor/recorder";
+import type { MonitorProgress } from "../monitor/types";
 
 const SIZE_MAP: Record<string, { width: number; height: number }> = {
   "poster-3-4": { width: 900, height: 1200 },
@@ -100,7 +102,8 @@ function splitWechatTitle(text: string): { line1: string; line2: string } {
   };
 }
 
-export function runRenderCardCli(argv: string[]): void {
+export function runRenderCardCli(argv: string[], onProgress?: (progress: MonitorProgress) => void): void {
+  notifyProgress(onProgress, { stage: "render.cover", message: "正在生成封面", current: 0, total: 1, unit: "pages" });
   const parsed = parseArgs(argv);
   const template = getArg(parsed, "template", "poster-3-4");
   const outPath = requireArg(parsed, "out");
@@ -209,6 +212,7 @@ export function runRenderCardCli(argv: string[]): void {
     });
     rmSync(rawPath, { force: true });
     printSaved(outPath);
+    notifyProgress(onProgress, { stage: "render.cover", current: 1, total: 1, unit: "pages" });
     return;
   }
 
@@ -221,6 +225,7 @@ export function runRenderCardCli(argv: string[]): void {
     virtualTimeBudgetMs: usesPretext ? PRETEXT_SCREENSHOT_VIRTUAL_TIME_BUDGET_MS : undefined,
   });
   printSaved(outPath);
+  notifyProgress(onProgress, { stage: "render.cover", current: 1, total: 1, unit: "pages" });
 }
 
 if (import.meta.main) {

package/src/imgx/runtime.ts

@@ -407,7 +407,7 @@ export function resolveInputPath(path: string): string {
 }
 
 export function printSaved(outPath: string): void {
-  console.log(`✅ Saved to ${outPath}`);
+  console.error(`✅ Saved to ${outPath}`);
 }
 
 export function readImageSize(path: string): { width: number; height: number } | null {

package/src/logger.test.ts

@@ -1,4 +1,4 @@
-import { afterEach, describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -6,9 +6,13 @@ import { getDailyLogPath, getLogDir, runWithCommandLog } from "./logger";
 
 describe("pipeline daily logger", () => {
   const previousLogDir = process.env.ZZHUB_PIPELINE_LOG_DIR;
+  const previousMonitor = process.env.ZZHUB_PIPELINE_MONITOR;
+  beforeEach(() => { process.env.ZZHUB_PIPELINE_MONITOR = "0"; });
   let tempDir: string | null = null;
 
   afterEach(() => {
+    if (previousMonitor === undefined) delete process.env.ZZHUB_PIPELINE_MONITOR;
+    else process.env.ZZHUB_PIPELINE_MONITOR = previousMonitor;
     if (previousLogDir === undefined) {
       delete process.env.ZZHUB_PIPELINE_LOG_DIR;
     } else {
@@ -20,6 +24,29 @@ describe("pipeline daily logger", () => {
     }
   });
 
+  test("logs returned business failures as FAIL without throwing or exiting the host", async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "zzhub-pipeline-log-"));
+    process.env.ZZHUB_PIPELINE_LOG_DIR = tempDir;
+    const outcome = await runWithCommandLog("publish", [], async () => ({ status: "failed", errors: [{ code: "PUBLISH_FAILED", message: "upload failed" }] }));
+    expect(outcome.status).toBe("failed");
+    expect(readFileSync(getDailyLogPath(), "utf8")).toContain("=== FAIL command=publish");
+  });
+
+  test("an explicit nonzero exit code cannot be logged as success", async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "zzhub-pipeline-log-"));
+    process.env.ZZHUB_PIPELINE_LOG_DIR = tempDir;
+    // Bun 需要显式恢复 0；写回 undefined 不会清除已经设置的退出码。
+    const previousCode = process.exitCode ?? 0;
+    try {
+      const outcome = await runWithCommandLog("legacy", [], async () => {
+        process.exitCode = 1;
+        return { status: "success" };
+      });
+      expect(outcome.status).toBe("failed");
+      expect(readFileSync(getDailyLogPath(), "utf8")).toContain("=== FAIL command=legacy");
+    } finally { process.exitCode = previousCode; }
+  });
+
   test("writes command start/ok markers and console output to the daily log", async () => {
     tempDir = mkdtempSync(join(tmpdir(), "zzhub-pipeline-log-"));
     process.env.ZZHUB_PIPELINE_LOG_DIR = tempDir;