@zzclub/pipeline 0.10.1 → 0.10.2

package/README.md

@@ -418,6 +418,7 @@ src/
 | `republish` | Publish a completed task to an additional account or platform |
 | `imgx` | Run bundled imgx renderer subcommands |
 | `wechat-export` | Render markdown to WeChat HTML with bundled preview styles |
+| `wechat-preview` | Local singleton server to preview exported WeChat HTML |
 | `cos-upload` | Upload a local image to configured COS CDN |
 | `config` | Read or update pipeline config |
 | `doctor` | Inspect resolved paths and provider health |
@@ -630,6 +631,47 @@ bun run src/cli.ts wechat-export \
 `--preview-shell-out` 生成最终发布 HTML 的精确预览：预览页直接嵌入 `--out`
 中的内联样式片段，不再加载 Milkdown 编辑器或复制浏览器 bundle。
 
+默认会将导出结果登记到本地 **单例预览服务**（`http://127.0.0.1:18765`），可在浏览器
+侧栏切换多篇产物，无需发到微信草稿箱。服务未启动时会自动拉起；失败导出也会登记并展示
+`error_kind` / timeout / Chrome stderr 等调试信息。
+
+```bash
+# 显式启动预览服务（全局只允许一个实例；重复启动会复用）
+bun run src/cli.ts wechat-preview serve --open
+
+# 导出并打开该条目
+bun run src/cli.ts wechat-export \
+  --markdown /abs/path/body.md \
+  --out /tmp/article.html \
+  --account default \
+  --open
+
+# 调试中间产物
+bun run src/cli.ts wechat-export \
+  --markdown /abs/path/body.md \
+  --out /tmp/article.html \
+  --debug-dir /tmp/wx-debug \
+  --timeout-ms 20000
+
+# 关闭预览登记
+bun run src/cli.ts wechat-export ... --no-preview
+```
+
+| 子命令 | 说明 |
+| --- | --- |
+| `wechat-preview serve` | 启动/复用单例服务 |
+| `wechat-preview status` | 是否在运行 |
+| `wechat-preview open` | 打开 dashboard |
+| `wechat-preview list` | 列出条目 |
+| `wechat-preview clear` | 清空条目 |
+
+环境变量：`ZZHUB_WECHAT_PREVIEW_PORT`（默认 18765）、`ZZHUB_WECHAT_PREVIEW_HOST`、
+`ZZHUB_WECHAT_PREVIEW_DIR`（锁与条目落盘目录）。发布草稿时默认也会登记一条
+`[publish] ...` 预览；设 `ZZHUB_WECHAT_PREVIEW_ON_PUBLISH=0` 可关闭。
+
+源码（CSS/browser 入口）新于 dist 时会自动尝试 rebuild；失败则回退已有 bundle 并标记
+`bundle_stale`。手动重建：`bun run build:wechat-preview`。
+
 #### 自定义 CSS
 
 可以通过账号配置或 CLI 覆盖内置样式：
@@ -854,7 +896,7 @@ bun run src/cli.ts init ... --note-id NOTE_ID
 - 构建命令：`bun run build:wechat-preview`
 - `wechat-export` 和微信草稿发布使用同一份最终内联 HTML
 
-`src/wechat-preview/browser/editor-export.css` 会通过 Vite 以 raw CSS 打入浏览器
+`@zzclub/milkdown-article-style`（`article.css`）会通过 Vite 以 raw CSS 打入浏览器
 bundle。修改该 CSS 或浏览器 renderer 后必须执行：
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zzclub/pipeline",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "type": "module",
   "bin": {
     "zzp": "./src/cli.ts",
@@ -25,6 +25,7 @@
   },
   "dependencies": {
     "@chenglou/pretext": "^0.0.5",
+    "@zzclub/milkdown-article-style": "0.1.1",
     "image-size": "^2.0.2",
     "pngjs": "^7.0.0",
     "zod": "^4.4.2"

package/src/adapter-types.ts

@@ -143,6 +143,12 @@ export interface MarkdownRenderInput {
     editorVars?: Record<string, string>;
     exportTheme?: Record<string, string>;
   };
+
+  /** Chrome virtual-time-budget in ms */
+  timeoutMs?: number;
+
+  /** Write intermediate artifacts for debugging */
+  debugDir?: string;
 }
 
 /**
@@ -164,6 +170,21 @@ export interface MarkdownRenderOutput {
 
   /** Path to preview shell HTML (if generated) */
   previewShellPath?: string;
+
+  /** Wall-clock render duration */
+  durationMs?: number;
+
+  /** Whether the browser bundle was rebuilt during this render */
+  bundleRebuilt?: boolean;
+
+  /** Whether the browser bundle was stale before render */
+  bundleStale?: boolean;
+
+  /** Debug directory if requested */
+  debugDir?: string;
+
+  /** Semantic HTML from Milkdown before WeChat finalize (when available) */
+  semanticHtml?: string;
 }
 
 export interface MarkdownRenderPlugin {

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

@@ -51,6 +51,8 @@ export const builtinMarkdownRenderer: MarkdownRenderPlugin = {
       previewShellOutPath: input.previewShellOutPath,
       customCss: input.customCss,
       themeOverrides: input.themeOverrides,
+      timeoutMs: input.timeoutMs,
+      debugDir: input.debugDir ?? undefined,
     });
 
     return {
@@ -59,6 +61,11 @@ export const builtinMarkdownRenderer: MarkdownRenderPlugin = {
       account: result.account,
       previewStyle: result.previewStyle,
       previewShellPath: result.previewShellPath,
+      durationMs: result.durationMs,
+      bundleRebuilt: result.bundleRebuilt,
+      bundleStale: result.bundleStale,
+      debugDir: result.debugDir,
+      semanticHtml: result.semanticHtml,
     };
   },
 };

package/src/cli.ts

@@ -3,6 +3,7 @@
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
+import { getDailyLogPath, runWithCommandLog } from "./logger";
 import { formatUsage, getCommandRegistry } from "./plugins";
 
 const COMMANDS = getCommandRegistry();
@@ -36,10 +37,13 @@ async function main() {
   }
 
   try {
-    await command.handler(args.slice(1));
+    await runWithCommandLog(cmd, args.slice(1), async () => {
+      await command.handler(args.slice(1));
+    });
   } 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);
   }
 }

package/src/commands/ingest-handoff.ts

@@ -6,16 +6,12 @@ import { loadConfig, resolveWorkspacePaths, resolveWorkspaceRoot } from "../conf
 import { printResult } from "../output";
 import { resolveFullRoute } from "../routes";
 import {
-  defaultArtifacts,
   defaultContentReview,
-  defaultImages,
-  defaultMetadata,
-  defaultPhase,
-  defaultPublish,
   defaultState,
   generateRunId,
   getRunStatePath,
   readResolvedState,
+  resetDerivedState,
   writeState,
   type ContentForm,
   type HandoffAuthoringPolicy,
@@ -302,22 +298,6 @@ function routesEqual(a: WorkflowState["route"], b: WorkflowState["route"]): bool
   );
 }
 
-function resetDerivedState(state: WorkflowState): void {
-  state.mode = "active";
-  state.phase = defaultPhase();
-  state.asset_path = "";
-  state.formatted_body_path = null;
-  state.metadata = {
-    ...defaultMetadata(),
-    title: state.metadata.title,
-  };
-  state.artifacts = defaultArtifacts();
-  state.images = defaultImages();
-  state.publish = defaultPublish();
-  state.content_review = defaultContentReview();
-  state.redo_hint = null;
-}
-
 async function resolveExistingStatePath(
   workspaceRoot: string,
   handoff: ResolvedWorkflowHandoff,

package/src/commands/prepare-finalize.ts

@@ -31,6 +31,7 @@ import {
   writeState,
   getCanonicalStatePath,
 } from "../state";
+import { loadTaskState } from "../task-manager";
 import {
   extractHighlightWords,
   buildFrontmatter,
@@ -195,7 +196,7 @@ Options:
   const initialResolved = await readResolvedState(requestedStatePath);
   const releaseOperationLock = await acquireStateOperationLock(initialResolved.path);
   try {
-  const resolved = await readResolvedState(initialResolved.path);
+  const resolved = await loadTaskState(initialResolved.path);
   const statePath = resolved.path;
   const state = resolved.state;
   if (state.content_review.status !== "passed") {

package/src/commands/prepare.ts

@@ -31,10 +31,10 @@ import { printResult, renderPrepare } from "../output";
 import { resolveWorkspacePaths } from "../config";
 import {
   defaultBodyInputs,
-  readResolvedState,
   reenterPrepare,
   writeState,
 } from "../state";
+import { loadTaskState } from "../task-manager";
 import { resolveFullRoute } from "../routes";
 import { resolveAuthoring, hasStyleRequest } from "../profiles";
 import { parseAccountName, parseRoutePrimary } from "../publish-targets";
@@ -131,7 +131,7 @@ Options:
     : undefined;
 
   // Read state and body
-  const resolved = await readResolvedState(requestedStatePath);
+  const resolved = await loadTaskState(requestedStatePath);
   const statePath = resolved.path;
   const state = resolved.state;
   const intentTextOverride = optionalArg(parsed, "intent-text");
@@ -144,9 +144,18 @@ Options:
   }
   const bodyRaw = await readFile(resolvedBodyPath, "utf-8");
   const cleanBody = stripFrontmatter(bodyRaw);
+  const incomingBody = Boolean(bodyPath);
+  // A newly supplied body satisfies a pending writer/style revision. Clearing
+  // these hints prevents status from looping back to revise-content after the
+  // body has already been handed in via prepare --body. (format/asset-meta/
+  // channel-route hints are cleared below after prepare runs their steps.)
+  const effectiveRedoHint = incomingBody &&
+      (state.redo_hint === "writer" || state.redo_hint === "style")
+    ? null
+    : state.redo_hint;
   reenterPrepare(state, {
-    redoHint: state.redo_hint,
-    resetReview: Boolean(bodyPath),
+    redoHint: effectiveRedoHint,
+    resetReview: incomingBody,
   });
   if (bodyPath && state.handoff.review_policy === "trust_user") {
     state.content_review = { status: "passed", feedback: null };
@@ -180,16 +189,15 @@ Options:
     state.route.highlight_words = highlightWordsOverride;
   }
 
-  // Re-derive requires.render and requires.publish based on resolved route.
-  // requires.research is intentional (set at init from user request), not touched here.
-  // Same for render/publish: if the orchestrator set them at init, keep that value.
-  // wechat-article always needs render regardless.
-  state.intent.requires.render =
-    state.intent.requires.render ||
-    route.primary === "wechat-article";
-  state.intent.requires.publish =
-    state.intent.requires.publish ||
-    state.intent.task_kind === "publish";
+  // Re-derive requires.render and requires.publish deterministically from the
+  // resolved route/task kind rather than OR-accumulating: a flag set true for a
+  // previous route must not linger after the route changes (e.g. switching a
+  // task to blog-only would otherwise keep requires.render=true forever).
+  // requires.research is intentional (set at init from the user request) and is
+  // intentionally not recomputed here.
+  const allRoutes = [route.primary, ...route.extras];
+  state.intent.requires.render = allRoutes.some((r) => r !== "blog");
+  state.intent.requires.publish = state.intent.task_kind === "publish";
 
   // ── Step 2: Author select ──
   const styleRequest =

package/src/commands/publish.ts

@@ -33,7 +33,7 @@ import {
   executePublishTargets,
   upsertPublishResult,
 } from "../providers/publish-core";
-import { reconcileStateArtifacts } from "../workflow-materials";
+import { loadTaskState } from "../task-manager";
 
 export async function publish(args: string[]): Promise<void> {
   const parsed = parseArgs(args);
@@ -60,10 +60,9 @@ Options:
   const initialResolved = await readResolvedState(requestedStatePath);
   const releaseOperationLock = await acquireStateOperationLock(initialResolved.path);
   try {
-  const resolved = await readResolvedState(initialResolved.path);
+  const resolved = await loadTaskState(initialResolved.path);
   const statePath = resolved.path;
   const state = resolved.state;
-  await reconcileStateArtifacts(state);
   const config = loadConfig();
   const workspacePaths = resolveWorkspacePaths(state.workspace_root, config);
 

package/src/commands/reconcile.ts

@@ -1,8 +1,7 @@
 import { parseArgs, requireArg } from "../args";
 import { printResult, renderTaskShape } from "../output";
-import { readResolvedState, writeState } from "../state";
-import { getTaskByStatePath } from "../task-manager";
-import { reconcileStateArtifacts } from "../workflow-materials";
+import { writeState } from "../state";
+import { getTaskByStatePath, loadTaskState } from "../task-manager";
 
 export async function reconcile(args: string[]): Promise<void> {
   const parsed = parseArgs(args);
@@ -18,10 +17,9 @@ Options:
   }
 
   const requestedStatePath = requireArg(parsed, "state", "state JSON path");
-  const resolved = await readResolvedState(requestedStatePath);
+  const resolved = await loadTaskState(requestedStatePath);
   const statePath = resolved.path;
   const state = resolved.state;
-  await reconcileStateArtifacts(state);
   await writeState(statePath, state);
 
   const task = await getTaskByStatePath(statePath);

package/src/commands/render.ts

@@ -31,6 +31,7 @@ import {
   type NewspicRenderSpec,
   type WorkflowState,
 } from "../state";
+import { loadTaskState } from "../task-manager";
 import {
   stripFrontmatter,
   generateCoverTitle,
@@ -66,7 +67,7 @@ Options:
   const initialResolved = await readResolvedState(requestedStatePath);
   const releaseOperationLock = await acquireStateOperationLock(initialResolved.path);
   try {
-  const resolved = await readResolvedState(initialResolved.path);
+  const resolved = await loadTaskState(initialResolved.path);
   const statePath = resolved.path;
   const state = resolved.state;
 

package/src/commands/republish.ts

@@ -35,7 +35,7 @@ import {
   executePublishTargets,
   upsertPublishResult,
 } from "../providers/publish-core";
-import { reconcileStateArtifacts } from "../workflow-materials";
+import { loadTaskState } from "../task-manager";
 
 export async function republish(args: string[]): Promise<void> {
   const parsed = parseArgs(args);
@@ -75,10 +75,9 @@ Examples:
   const initialResolved = await readResolvedState(requestedStatePath);
   const releaseOperationLock = await acquireStateOperationLock(initialResolved.path);
   try {
-  const resolved = await readResolvedState(initialResolved.path);
+  const resolved = await loadTaskState(initialResolved.path);
   const statePath = resolved.path;
   const state = resolved.state;
-  await reconcileStateArtifacts(state);
   const config = loadConfig();
   const workspacePaths = resolveWorkspacePaths(state.workspace_root, config);
 

package/src/commands/reset.ts

@@ -22,6 +22,7 @@
 import { parseArgs, requireArg } from "../args";
 import { printResult, renderReset } from "../output";
 import {
+  acquireStateOperationLock,
   defaultContentReview,
   readResolvedState,
   reenterPrepare,
@@ -29,6 +30,7 @@ import {
   reenterRender,
   writeState,
 } from "../state";
+import { loadTaskState } from "../task-manager";
 
 type ResetMode =
   | "content"
@@ -84,7 +86,10 @@ Modes:
     );
   }
 
-  const resolved = await readResolvedState(requestedStatePath);
+  const initialResolved = await readResolvedState(requestedStatePath);
+  const releaseOperationLock = await acquireStateOperationLock(initialResolved.path);
+  try {
+  const resolved = await loadTaskState(initialResolved.path);
   const statePath = resolved.path;
   const state = resolved.state;
 
@@ -149,4 +154,7 @@ Modes:
   };
 
   printResult(output, renderReset);
+  } finally {
+    await releaseOperationLock();
+  }
 }

package/src/commands/review.ts

@@ -17,7 +17,8 @@
 
 import { parseArgs, requireArg, optionalArg } from "../args";
 import { printResult, renderReview } from "../output";
-import { readResolvedState, writeState, type ContentReviewStatus } from "../state";
+import { writeState, type ContentReviewStatus } from "../state";
+import { loadTaskState } from "../task-manager";
 
 const VALID_STATUSES: ContentReviewStatus[] = [
   "passed",
@@ -59,7 +60,7 @@ Statuses:
     );
   }
 
-  const resolved = await readResolvedState(requestedStatePath);
+  const resolved = await loadTaskState(requestedStatePath);
   const statePath = resolved.path;
   const state = resolved.state;
 

package/src/commands/sync-blog.ts

@@ -6,6 +6,7 @@ import {
   readResolvedState,
   updateState,
 } from "../state";
+import { loadTaskState } from "../task-manager";
 import { publishBlogRoute } from "../providers/blog";
 
 export async function syncBlog(args: string[]): Promise<void> {
@@ -31,7 +32,7 @@ Options:
   const initialResolved = await readResolvedState(requestedStatePath);
   const releaseOperationLock = await acquireStateOperationLock(initialResolved.path);
   try {
-  const resolved = await readResolvedState(initialResolved.path);
+  const resolved = await loadTaskState(initialResolved.path);
   const statePath = resolved.path;
   const state = resolved.state;
 

package/src/commands/wechat-export.ts

@@ -1,8 +1,11 @@
+import { spawn } from "child_process";
 import { resolve } from "path";
-import { optionalArg, parseArgs, requireArg } from "../args";
+import { flagArg, optionalArg, parseArgs, requireArg } from "../args";
 import { printResult, renderWechatExport } from "../output";
 import { loadConfig, resolveConfigRelativePath } from "../config";
 import { resolveMarkdownRenderer } from "../adapter-loader";
+import { WechatExportError } from "../wechat-preview";
+import { registerPreviewEntry } from "../wechat-preview/server";
 
 const CSS_DEMO = `
 Custom CSS is cascaded after the built-in theme and converted to conservative
@@ -36,6 +39,21 @@ export function resolveWechatExportCustomCss(
     : resolveConfigRelativePath(accountCustomCss, configPath);
 }
 
+async function openUrl(url: string): Promise<void> {
+  const opener =
+    process.platform === "darwin"
+      ? "open"
+      : process.platform === "win32"
+        ? "cmd"
+        : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    spawn(opener, args, { detached: true, stdio: "ignore" }).unref();
+  } catch {
+    // non-fatal
+  }
+}
+
 export async function wechatExport(args: string[]): Promise<void> {
   const parsed = parseArgs(args);
 
@@ -50,6 +68,12 @@ Options:
   --title              Page title for the render shell (optional)
   --preview-shell-out  Path to exact final-HTML preview (optional)
   --custom-css         CSS override path; replaces account customCss (optional)
+  --timeout-ms         Chrome virtual-time-budget in ms (default: 15000)
+  --debug-dir          Write intermediate artifacts for debugging (optional)
+  --preview            Register result with local preview server (default: true)
+  --no-preview         Do not register with preview server
+  --preview-auto-start Auto-start preview server if needed (default: true)
+  --open               Open preview URL in browser after export
 
 ${CSS_DEMO}
 `.trim());
@@ -62,6 +86,21 @@ ${CSS_DEMO}
   const title = optionalArg(parsed, "title");
   const previewShellOutPath = optionalArg(parsed, "preview-shell-out");
   const cliCustomCss = optionalArg(parsed, "custom-css");
+  const timeoutRaw = optionalArg(parsed, "timeout-ms");
+  const timeoutMs = timeoutRaw ? Number(timeoutRaw) : undefined;
+  const debugDir = optionalArg(parsed, "debug-dir");
+  const noPreview = flagArg(parsed, "no-preview");
+  // Default true unless --no-preview or --preview=false
+  const previewExplicit = parsed.preview;
+  const preview =
+    !noPreview &&
+    previewExplicit !== false &&
+    previewExplicit !== "false";
+  const previewAutoStartExplicit = parsed["preview-auto-start"];
+  const previewAutoStart =
+    previewAutoStartExplicit !== false &&
+    previewAutoStartExplicit !== "false";
+  const open = flagArg(parsed, "open");
 
   const config = loadConfig();
   const wxAccount = config.wx.accounts[account] ?? config.wx.accounts[config.wx.defaultAccount];
@@ -70,15 +109,98 @@ ${CSS_DEMO}
     wxAccount?.customCss,
   );
   const markdownRenderer = await resolveMarkdownRenderer(config);
-  const result = await markdownRenderer.render({
-    markdownPath,
-    outPath,
-    account,
-    title,
-    previewShellOutPath,
-    customCss,
-    themeOverrides: wxAccount?.theme,
-  });
-
-  printResult(result, renderWechatExport);
+
+  const displayTitle = title ?? "Wechat Preview Export";
+
+  try {
+    const result = await markdownRenderer.render({
+      markdownPath,
+      outPath,
+      account,
+      title,
+      previewShellOutPath,
+      customCss,
+      themeOverrides: wxAccount?.theme,
+      timeoutMs: timeoutMs !== undefined && Number.isFinite(timeoutMs) ? timeoutMs : undefined,
+      debugDir: debugDir ? resolve(process.cwd(), debugDir) : undefined,
+    });
+
+    let preview_url: string | undefined;
+    let preview_dashboard_url: string | undefined;
+    let preview_register_error: string | undefined;
+
+    if (preview) {
+      const reg = await registerPreviewEntry(
+        {
+          title: displayTitle,
+          account: result.account,
+          status: "success",
+          duration_ms: result.durationMs ?? 0,
+          markdown_path: resolve(process.cwd(), markdownPath),
+          html_path: result.htmlPath,
+          preview_style: result.previewStyle,
+          html: result.html,
+          debug: {
+            bundle_rebuilt: result.bundleRebuilt,
+            bundle_stale: result.bundleStale,
+            debug_dir: result.debugDir,
+          },
+        },
+        { autoStart: previewAutoStart },
+      );
+      if (reg.ok) {
+        preview_url = reg.preview_url;
+        preview_dashboard_url = reg.dashboard_url;
+        if (open && preview_url) await openUrl(preview_url);
+      } else {
+        preview_register_error = reg.error;
+      }
+    }
+
+    // Keep semanticHtml out of default CLI output (large); it still lands in --debug-dir.
+    const { semanticHtml: _semanticHtml, ...resultRest } = result;
+    printResult(
+      {
+        ...resultRest,
+        preview_url,
+        preview_dashboard_url,
+        preview_register_error,
+      },
+      renderWechatExport,
+    );
+  } catch (error) {
+    if (preview && error instanceof WechatExportError) {
+      const reg = await registerPreviewEntry(
+        {
+          title: error.title ?? displayTitle,
+          account: error.account,
+          status: "failed",
+          duration_ms: error.durationMs,
+          markdown_path: error.markdownPath,
+          error: error.message,
+          error_kind: error.kind,
+          debug: error.debug,
+        },
+        { autoStart: previewAutoStart },
+      );
+      if (reg.ok) {
+        printResult(
+          {
+            ok: false,
+            error: error.message,
+            error_kind: error.kind,
+            duration_ms: error.durationMs,
+            debug: error.debug,
+            preview_url: reg.preview_url,
+            preview_dashboard_url: reg.dashboard_url,
+          },
+          renderWechatExport,
+        );
+        if (open && reg.preview_url) await openUrl(reg.preview_url);
+        process.exitCode = 1;
+        return;
+      }
+    }
+    throw error;
+  }
 }