@zzclub/pipeline 0.10.1 → 0.11.0

package/README.md

@@ -410,7 +410,7 @@ src/
 | `review` | Update content review status |
 | `abandon` | Mark one or more tasks as abandoned |
 
-`ops` 组，12 个命令：
+`ops` 组，11 个命令：
 
 | 命令 | 说明 |
 | --- | --- |
@@ -418,14 +418,13 @@ 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 |
 | `hermes-metrics` | Show Hermes execution metrics per task |
 | `wx-drafts` | List or get drafts from WeChat draft box |
 | `wx-draft-delete` | Delete a draft from WeChat draft box |
-| `topic` | 选题管理（添加、列表、更新、排期、复盘、放弃） |
-| `analytics` | 发布数据录入和分析 |
 
 ## 常用命令
 
@@ -520,75 +519,6 @@ bun run src/cli.ts reset --state {state_path} --mode full         # 完全放弃
 
 每种模式均会设置 `redo_hint`，确保 Agent 恢复时知道从哪个子步骤开始。
 
-### 选题管理
-
-使用 `topic` 命令管理内容选题的完整生命周期：
-
-```bash
-# 添加选题
-bun run src/cli.ts topic add \
-  --workspace {workspace} \
-  --title "AI 工具推荐" \
-  --priority high \
-  --tags "AI,工具"
-
-# 列出选题
-bun run src/cli.ts topic list --workspace {workspace}
-bun run src/cli.ts topic list --workspace {workspace} --status backlog --priority high
-
-# 更新选题（AI 评估）
-bun run src/cli.ts topic update \
-  --workspace {workspace} \
-  --topic {topic_id} \
-  --ai-score 85 \
-  --ai-reason "基于热点趋势和受众匹配度"
-
-# 排期
-bun run src/cli.ts topic schedule \
-  --workspace {workspace} \
-  --topic {topic_id} \
-  --scheduled-date 2026-06-15 \
-  --target-account default
-
-# 复盘（发布后）
-bun run src/cli.ts topic retro \
-  --workspace {workspace} \
-  --topic {topic_id} \
-  --performance good \
-  --lessons "标题悬念效果好" \
-  --metrics-snapshot '{"reads": 1500, "likes": 45}'
-
-# 放弃选题
-bun run src/cli.ts topic abandon \
-  --workspace {workspace} \
-  --topic {topic_id} \
-  --reason "话题过时"
-```
-
-选题状态流转：`backlog` → `evaluating` → `scheduled` → `in_progress` → `published`（或 `abandoned`）
-
-### 数据分析
-
-使用 `analytics` 命令录入和分析发布后的数据：
-
-```bash
-# 录入发布数据
-bun run src/cli.ts analytics record \
-  --state {workspace}/posts/{date-slug}/workflow-state.json \
-  --reads 1500 \
-  --likes 45 \
-  --favorites 23 \
-  --shares 12 \
-  --comments 8 \
-  --notes "标题效果好，转化率高"
-
-# 列出历史数据
-bun run src/cli.ts analytics list --workspace {workspace}
-bun run src/cli.ts analytics list --workspace {workspace} --days 30 --sort reads
-```
-
-数据存储在 `{workspace}/zzhub.db`（SQLite 数据库），支持复杂查询和统计分析。
-
 ### Blog 同步
 
 ```bash
@@ -630,6 +560,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 +825,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.11.0",
   "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/config.ts

@@ -5,13 +5,17 @@ import {
   configSummary,
   getConfigValue,
   loadConfig,
-  PipelineConfigSchema,
+  normalizeConfig,
   redactConfig,
   redactConfigValue,
   saveConfig,
   setConfigValue,
 } from "../config";
 
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 export async function configCommand(args: string[]): Promise<void> {
   const parsed = parseArgs(args);
 
@@ -26,6 +30,11 @@ Options:
   --export     Print full config as JSON (secrets redacted; use --raw to show all)
   --import     Path to a JSON file to merge into current config
   --raw        Show secrets unredacted (use with --export)
+
+Examples:
+  zzhub-pipeline config --key wx.defaultAccount
+  zzhub-pipeline config --key wx.accounts.default.name --value "大号（早早集市）"
+  zzhub-pipeline config --export
 `.trim());
     return;
   }
@@ -50,27 +59,45 @@ Options:
       throw new Error(`Failed to read import file: ${err instanceof Error ? err.message : String(err)}`);
     }
 
-    // Merge: existing values win, imported fills gaps
-    const importedObj = (typeof imported === "object" && imported !== null ? imported : {}) as Record<string, unknown>;
-    const mergedWx = {
-      ...config.wx,
-      ...(importedObj.wx as Record<string, unknown> ?? {}),
-      accounts: {
-        ...config.wx.accounts,
-        ...((importedObj.wx as Record<string, unknown>)?.accounts as Record<string, unknown> ?? {}),
-      },
-    };
+    // Merge: top-level shallow; wx.accounts deep-merge per key so partial imports
+    // keep existing fields (e.g. display `name`) unless overridden.
+    const importedObj = isPlainObject(imported) ? imported : {};
+    const importedWx = isPlainObject(importedObj.wx) ? importedObj.wx : {};
+    const importedAccounts = isPlainObject(importedWx.accounts) ? importedWx.accounts : {};
+    const mergedAccounts: Record<string, unknown> = { ...config.wx.accounts };
+    for (const [key, value] of Object.entries(importedAccounts)) {
+      const accountKey = key.trim();
+      if (!accountKey) continue;
+      const existing = isPlainObject(mergedAccounts[accountKey])
+        ? mergedAccounts[accountKey]
+        : {};
+      const incoming = isPlainObject(value) ? value : {};
+      mergedAccounts[accountKey] = { ...existing, ...incoming };
+    }
     const raw = {
-      paths: { ...config.paths, ...(importedObj.paths ?? {}) },
-      services: { ...config.services, ...(importedObj.services ?? {}) },
-      commands: { ...config.commands, ...(importedObj.commands ?? {}) },
-      wx: mergedWx,
-      cos: { ...config.cos, ...(importedObj.cos ?? {}) },
-      plugins: { ...config.plugins, ...(importedObj.plugins ?? {}) },
-      imgx: { ...config.imgx, ...(importedObj.imgx ?? {}) },
+      paths: { ...config.paths, ...(isPlainObject(importedObj.paths) ? importedObj.paths : {}) },
+      services: {
+        ...config.services,
+        ...(isPlainObject(importedObj.services) ? importedObj.services : {}),
+      },
+      commands: {
+        ...config.commands,
+        ...(isPlainObject(importedObj.commands) ? importedObj.commands : {}),
+      },
+      wx: {
+        ...config.wx,
+        ...importedWx,
+        accounts: mergedAccounts,
+      },
+      cos: { ...config.cos, ...(isPlainObject(importedObj.cos) ? importedObj.cos : {}) },
+      plugins: {
+        ...config.plugins,
+        ...(isPlainObject(importedObj.plugins) ? importedObj.plugins : {}),
+      },
+      imgx: { ...config.imgx, ...(isPlainObject(importedObj.imgx) ? importedObj.imgx : {}) },
     };
-    // Validate through Zod schema — strips unknown fields, applies defaults
-    const merged = PipelineConfigSchema.parse(raw);
+    // Soft-fill known account display names + Zod defaults / strip unknowns
+    const merged = normalizeConfig(raw);
 
     saveConfig(merged);
     printResult(configSummary(merged), renderConfig);

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;