@zzclub/pipeline 0.9.1 → 0.10.1

package/README.md

@@ -38,12 +38,13 @@ bun install --global .
 
 这是一个状态机模型，输入是任务意图、正文、图片、路由和发布要求，输出是可恢复的工作流状态、渲染产物和发布结果。
 
-当前只有两条主工作流路由：
+当前有三条主工作流路由：
 
 - `wechat-article` — 公众号文章草稿（HTML）
 - `wechat-newspic` — 公众号图片消息（PNG 卡片/图集）
+- `blog` — 将 Markdown 同步到配置的博客项目并执行发布命令
 
-`blog` 只做事后同步（`sync-blog`），不参与主工作流分支，但同步结果会写回 `workflow-state.json` 的 `publish.results`。
+`blog` 参与统一的 `prepare → publish` 工作流；作为唯一目标时跳过 render。`sync-blog` 继续保留为事后同步命令，两种路径都会把结果写回 `workflow-state.json` 的 `publish.results`。
 
 状态文件分两类：
 
@@ -374,7 +375,7 @@ src/
   wechat-preview/         # 微信文章 HTML 预览，Milkdown + 主题
     index.ts
     themes.ts
-    wechat-formatter.ts
+    wechat-renderer.ts     # 元素 renderer 注册表、CSS 内联和微信安全清理
     frontmatter-handler.ts
     browser/
       editor-export.ts
@@ -409,11 +410,12 @@ src/
 | `review` | Update content review status |
 | `abandon` | Mark one or more tasks as abandoned |
 
-`ops` 组，11 个命令：
+`ops` 组，12 个命令：
 
 | 命令 | 说明 |
 | --- | --- |
 | `sync-blog` | Copy post.md to blog repo, publish, and record result in state JSON |
+| `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 |
 | `cos-upload` | Upload a local image to configured COS CDN |
@@ -618,9 +620,57 @@ bun run src/cli.ts hermes-metrics --workspace /abs/workspace
 ### 微信 HTML 预览导出
 
 ```bash
-bun run src/cli.ts wechat-export --body /abs/path/body.md --account default
+bun run src/cli.ts wechat-export \
+  --markdown /abs/path/body.md \
+  --out /abs/path/article.html \
+  --account default \
+  --preview-shell-out /abs/path/article-preview.html
 ```
 
+`--preview-shell-out` 生成最终发布 HTML 的精确预览：预览页直接嵌入 `--out`
+中的内联样式片段，不再加载 Milkdown 编辑器或复制浏览器 bundle。
+
+#### 自定义 CSS
+
+可以通过账号配置或 CLI 覆盖内置样式：
+
+```json
+{
+  "wx": {
+    "accounts": {
+      "default": {
+        "customCss": "./themes/default-wechat.css"
+      }
+    }
+  }
+}
+```
+
+```bash
+bun run src/cli.ts wechat-export \
+  --markdown /abs/path/body.md \
+  --out /abs/path/article.html \
+  --custom-css ./local-wechat.css
+```
+
+样式优先级固定为：内置排版 CSS → 账号主题令牌 → 账号 `customCss`。传入
+`--custom-css` 时，它会替代账号 `customCss`。CLI 相对路径按当前工作目录解析，
+配置中的相对路径按 `config.json` 所在目录解析。
+
+推荐使用语义标签或稳定节点钩子：
+
+```css
+.milkdown .editor p { line-height: 1.9; }
+.milkdown .editor h2 { color: #a94473; }
+.milkdown .editor [data-wechat-node="inline-code"] { background: #f7eef2; }
+.milkdown .editor [data-wechat-node="image-caption"] { font-size: 13px; }
+```
+
+`.milkdown .editor` 只是 CSS 内联阶段的兼容包装；最终 HTML 会移除 `class` 和
+`data-wechat-node`。外部 CSS 支持变量、层叠和常规选择器，随后由 Juice 解析为
+内联样式。最终片段只保留微信稳定标签、图片/链接/表格必要属性和保守 CSS；
+脚本、事件属性、外部 `<style>`、未解析变量、`flex`/`grid`、定位和伪元素都会被移除。
+
 ### COS 图片上传
 
 ```bash
@@ -796,10 +846,23 @@ bun run src/cli.ts init ... --note-id NOTE_ID
 
 ## wechat-preview 子系统
 
-- 基于 Milkdown 的 markdown 到微信 HTML 转换
-- 支持多主题
+- 基于 Milkdown core + CommonMark/GFM 生成语义 HTML，不读取 Crepe/CodeMirror 可视 DOM
+- 固定管线：Markdown → Milkdown HTML → 元素 renderer prepare → Juice 内联 → renderer finalize → 微信白名单清理
+- 元素 renderer 覆盖段落/标题、强调、行内代码、代码块、引用、图片标题、链接脚注、列表、表格、分隔线和页脚
+- 内置默认采用“静默编辑”：深色标题、低装饰引用和中性行内代码，品牌色只用于链接等识别点
+- `default` 与 `ancientone` 共用排版骨架，只通过主题令牌切换品牌色、字体栈和页脚
 - 构建命令：`bun run build:wechat-preview`
-- `wechat-export` 会直接使用这套预览样式
+- `wechat-export` 和微信草稿发布使用同一份最终内联 HTML
+
+`src/wechat-preview/browser/editor-export.css` 会通过 Vite 以 raw CSS 打入浏览器
+bundle。修改该 CSS 或浏览器 renderer 后必须执行：
+
+```bash
+bun run build:wechat-preview
+bun install --global .
+```
+
+全局 `zzp` 使用编译产物；只修改源码而不重新全局安装不会更新全局命令。
 
 ## 插件系统
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zzclub/pipeline",
-  "version": "0.9.1",
+  "version": "0.10.1",
   "type": "module",
   "bin": {
     "zzp": "./src/cli.ts",
@@ -34,12 +34,11 @@
     "cos-nodejs-sdk-v5": "^2.15.4"
   },
   "devDependencies": {
-    "@milkdown/crepe": "^7.18.0",
-    "@milkdown/plugin-listener": "^7.18.0",
-    "@milkdown/utils": "^7.18.0",
+    "@milkdown/kit": "^7.18.0",
     "@types/bun": "latest",
     "@types/pngjs": "^6.0.5",
     "changelogen": "^0.6.2",
+    "juice": "11.1.1",
     "typescript": "^5.7.0",
     "vite": "^7.1.10"
   }

package/src/adapter-loader.ts

@@ -7,6 +7,8 @@
  */
 
 import type { PipelineConfig } from "./schema/config";
+import { isAbsolute, resolve } from "path";
+import { pathToFileURL } from "url";
 import type {
   ImageRenderPlugin,
   MarkdownRenderPlugin,
@@ -49,7 +51,10 @@ function validateMarkdownRenderPlugin(plugin: unknown, specifier: string): Markd
 
 async function importPlugin(specifier: string): Promise<unknown> {
   try {
-    const mod = await import(specifier);
+    const importSpecifier = specifier.startsWith(".") || isAbsolute(specifier)
+      ? pathToFileURL(resolve(specifier)).href
+      : specifier;
+    const mod = await import(importSpecifier);
     // Support both default exports and named `plugin` exports
     return mod.default ?? mod.plugin ?? mod;
   } catch (err) {

package/src/commands/analytics.test.ts

@@ -123,11 +123,12 @@ describe("analytics commands", () => {
 
     test("filters by days", async () => {
       const statePath = join(workspace, "state.json");
+      const today = new Date().toISOString().slice(0, 10);
       await writeFile(statePath, JSON.stringify({
         run_id: "run_001",
-        metadata: { title: "Article", date: "2026-06-11" },
+        metadata: { title: "Article", date: today },
         route: { primary: "wechat-article" },
-        publish: { results: { wechat: { status: "success", published_at: "2026-06-11T10:00:00Z" } } },
+        publish: { results: { wechat: { status: "success", published_at: `${today}T10:00:00Z` } } },
       }));
 
       await recordAnalytics({ statePath, reads: 1000 });

package/src/commands/analytics.ts

@@ -1,5 +1,5 @@
 import { readFile } from "fs/promises";
-import { dirname } from "path";
+import { dirname, isAbsolute, resolve } from "path";
 import { ensureDb } from "../db";
 import { AnalyticsSchema, type Analytics } from "../schema/analytics";
 import { parseArgs, requireArg, optionalArg } from "../args";
@@ -26,10 +26,27 @@ function resolveWorkspace(statePath: string): string {
 export async function recordAnalytics(
   input: RecordAnalyticsInput,
 ): Promise<Analytics> {
-  const stateContent = await readFile(input.statePath, "utf-8");
-  const state = JSON.parse(stateContent);
+  const requestedPath = resolve(input.statePath);
+  let statePath = requestedPath;
+  let state = JSON.parse(await readFile(statePath, "utf-8"));
+  if (typeof state.state_path === "string" && state.state_path.trim()) {
+    const candidatePath = isAbsolute(state.state_path)
+      ? resolve(state.state_path)
+      : resolve(dirname(statePath), state.state_path);
+    if (candidatePath !== statePath) {
+      try {
+        state = JSON.parse(await readFile(candidatePath, "utf-8"));
+        statePath = candidatePath;
+      } catch (error) {
+        const code = error instanceof Error && "code" in error
+          ? String((error as NodeJS.ErrnoException).code)
+          : "";
+        if (code !== "ENOENT") throw error;
+      }
+    }
+  }
 
-  const workspace = resolveWorkspace(input.statePath);
+  const workspace = state.workspace_root || resolveWorkspace(statePath);
   const db = ensureDb(workspace);
 
   try {

package/src/commands/attach-body-images.ts

@@ -2,7 +2,13 @@ import { readFile } from "fs/promises";
 
 import { parseArgs, optionalArg, requireArg } from "../args";
 import { printResult, renderTaskShape } from "../output";
-import { readState, writeState, type BodyInputReceived } from "../state";
+import {
+  readResolvedState,
+  reenterPublish,
+  reenterRender,
+  writeState,
+  type BodyInputReceived,
+} from "../state";
 import { getTaskByStatePath } from "../task-manager";
 import { reconcileStateArtifacts } from "../workflow-materials";
 
@@ -52,12 +58,15 @@ Options:
     return;
   }
 
-  const statePath = requireArg(parsed, "state", "state JSON path");
+  const requestedStatePath = requireArg(parsed, "state", "state JSON path");
   const imagesFile = requireArg(parsed, "images-file", "JSON file with marker/path data");
   const scope = optionalArg(parsed, "scope");
   const layout = optionalArg(parsed, "layout");
 
-  const state = await readState(statePath);
+  const resolved = await readResolvedState(requestedStatePath);
+  const statePath = resolved.path;
+  const state = resolved.state;
+  const prepareWasDone = state.phase.prepare.status === "done";
   const raw = JSON.parse(await readFile(imagesFile, "utf-8")) as unknown;
   const incoming = parseReceivedImages(raw);
   const merged = new Map(state.images.body_inputs.received.map((item) => [item.marker, item.path]));
@@ -74,6 +83,17 @@ Options:
   }
 
   await reconcileStateArtifacts(state);
+  if (prepareWasDone && state.images.body_inputs.scope === "newspic-longform") {
+    reenterRender(state);
+  } else if (
+    prepareWasDone &&
+    state.images.body_inputs.scope === "article" &&
+    (state.phase.current === "publish" ||
+      state.phase.current === "done" ||
+      state.phase.publish.status === "done")
+  ) {
+    reenterPublish(state);
+  }
   await writeState(statePath, state);
 
   const task = await getTaskByStatePath(statePath);

package/src/commands/attach-body.ts

@@ -4,7 +4,7 @@ import { extname, join, resolve } from "path";
 import { parseArgs, optionalArg, requireArg } from "../args";
 import { printResult, renderTaskShape } from "../output";
 import { resolveWorkspacePaths } from "../config";
-import { readState, writeState } from "../state";
+import { readResolvedState, reenterPrepare, writeState } from "../state";
 import { getTaskByStatePath } from "../task-manager";
 import { reconcileStateArtifacts } from "../workflow-materials";
 
@@ -48,7 +48,7 @@ Options:
     return;
   }
 
-  const statePath = requireArg(parsed, "state", "state JSON path");
+  const requestedStatePath = requireArg(parsed, "state", "state JSON path");
   const bodyPath = optionalArg(parsed, "body");
   const bodyText = optionalArg(parsed, "body-text");
   if (!bodyPath && bodyText === undefined) {
@@ -58,13 +58,22 @@ Options:
     throw new Error("Use either --body or --body-text, not both");
   }
 
-  const state = await readState(statePath);
+  const resolved = await readResolvedState(requestedStatePath);
+  const statePath = resolved.path;
+  const state = resolved.state;
   state.source_body_path = await stageManagedBodyFile(
     state.workspace_root,
     state.run_id,
     bodyPath ?? null,
     bodyText ?? null,
   );
+  reenterPrepare(state, {
+    clearFormattedBody: true,
+    resetReview: true,
+  });
+  if (state.handoff.review_policy === "trust_user") {
+    state.content_review = { status: "passed", feedback: null };
+  }
   await reconcileStateArtifacts(state);
   await writeState(statePath, state);
 

package/src/commands/attach-newspic-spec.ts

@@ -2,7 +2,12 @@ import { readFile } from "fs/promises";
 
 import { parseArgs, requireArg } from "../args";
 import { printResult, renderTaskShape } from "../output";
-import { normalizeNewspicRenderSpec, readState, writeState } from "../state";
+import {
+  normalizeNewspicRenderSpec,
+  readResolvedState,
+  reenterRender,
+  writeState,
+} from "../state";
 import { getTaskByStatePath } from "../task-manager";
 import { reconcileStateArtifacts } from "../workflow-materials";
 
@@ -20,13 +25,19 @@ Options:
     return;
   }
 
-  const statePath = requireArg(parsed, "state", "state JSON path");
+  const requestedStatePath = requireArg(parsed, "state", "state JSON path");
   const specPath = requireArg(parsed, "file", "newspic render spec file");
 
-  const state = await readState(statePath);
+  const resolved = await readResolvedState(requestedStatePath);
+  const statePath = resolved.path;
+  const state = resolved.state;
+  const prepareWasDone = state.phase.prepare.status === "done";
   const spec = JSON.parse(await readFile(specPath, "utf-8")) as unknown;
   state.intent.newspic_render = normalizeNewspicRenderSpec(spec);
   await reconcileStateArtifacts(state);
+  if (prepareWasDone) {
+    reenterRender(state);
+  }
   await writeState(statePath, state);
 
   const task = await getTaskByStatePath(statePath);

package/src/commands/config.ts

@@ -67,6 +67,7 @@ Options:
       wx: mergedWx,
       cos: { ...config.cos, ...(importedObj.cos ?? {}) },
       plugins: { ...config.plugins, ...(importedObj.plugins ?? {}) },
+      imgx: { ...config.imgx, ...(importedObj.imgx ?? {}) },
     };
     // Validate through Zod schema — strips unknown fields, applies defaults
     const merged = PipelineConfigSchema.parse(raw);

package/src/commands/ingest-handoff.ts

@@ -15,7 +15,7 @@ import {
   defaultState,
   generateRunId,
   getRunStatePath,
-  readState,
+  readResolvedState,
   writeState,
   type ContentForm,
   type HandoffAuthoringPolicy,
@@ -473,10 +473,16 @@ Options:
     handoff.mode === "resume"
       ? await resolveExistingStatePath(workspace, handoff)
       : getRunStatePath(workspace, generateRunId());
-  const state =
-    handoff.mode === "resume"
-      ? await readState(statePath)
-      : buildNewState(workspace, statePath, statePath.split("/").pop()?.replace(/\.json$/, "") ?? generateRunId());
+  const resolvedExisting = handoff.mode === "resume"
+    ? await readResolvedState(statePath)
+    : null;
+  const effectiveStatePath = resolvedExisting?.path ?? statePath;
+  const state = resolvedExisting?.state ??
+    buildNewState(
+      workspace,
+      effectiveStatePath,
+      effectiveStatePath.split("/").pop()?.replace(/\.json$/, "") ?? generateRunId(),
+    );
 
   if (handoff.mode === "new" && !state.run_id) {
     state.run_id = generateRunId();
@@ -484,7 +490,7 @@ Options:
   }
 
   await applyHandoffToState(state, handoff);
-  await writeState(state.state_path, state);
+  await writeState(state.state_path || effectiveStatePath, state);
 
   const task = await getTaskByStatePath(state.state_path);
   printResult({

package/src/commands/init.ts

@@ -28,17 +28,19 @@ import { parseArgs, requireArg, optionalArg, flagArg } from "../args";
 import { printResult, renderInit } from "../output";
 import { loadConfig, resolveWorkspaceRoot } from "../config";
 import { resolveFullRoute } from "../routes";
+import {
+  parseAccountName,
+  parseContentForm,
+  parseContentOrigin,
+  parsePublishTargets,
+  parseTaskKind,
+} from "../publish-targets";
 import {
   defaultState,
   generateRunId,
   getRunStatePath,
   normalizeNewspicRenderSpec,
   writeState,
-  type ContentForm,
-  type ContentOrigin,
-  type PublishTarget,
-  type Target,
-  type TaskKind,
 } from "../state";
 
 export async function init(args: string[]): Promise<void> {
@@ -67,10 +69,10 @@ Options:
     return;
   }
 
-  const taskKind = requireArg(parsed, "task-kind", "task kind") as TaskKind;
-  const contentForm = requireArg(parsed, "content-form", "content form") as ContentForm;
+  const taskKind = parseTaskKind(requireArg(parsed, "task-kind", "task kind"));
+  const contentForm = parseContentForm(requireArg(parsed, "content-form", "content form"));
   const targetsRaw = requireArg(parsed, "targets", "publish targets");
-  const contentOrigin = requireArg(parsed, "content-origin", "content origin") as ContentOrigin;
+  const contentOrigin = parseContentOrigin(requireArg(parsed, "content-origin", "content origin"));
   const intentText = optionalArg(parsed, "intent-text") ?? "";
   const accountOverride = optionalArg(parsed, "account");
   const styleHint = optionalArg(parsed, "style-hint") ?? null;
@@ -80,31 +82,13 @@ Options:
   const config = loadConfig();
   const workspace = resolveWorkspaceRoot(optionalArg(parsed, "workspace"), config);
 
-  const targets = targetsRaw.split(",").map((t) => t.trim()) as Target[];
-
-  // Parse multi-target format: "route@account,route@account,..."
-  // Also supports RoutePrimary values (wechat-article, wechat-newspic, blog)
-  // which need to be mapped to Target enum (wechat, blog) for intent.targets.
-  const publishTargets: PublishTarget[] = [];
-  const targetParts = targetsRaw.split(",").map((t) => t.trim());
-  const defaultAccount = accountOverride || "default";
-  const mappedTargets: Target[] = [];
-
-  for (const part of targetParts) {
-    const atIdx = part.indexOf("@");
-    const route = atIdx !== -1 ? part.slice(0, atIdx).trim() : part;
-    const account = atIdx !== -1 ? part.slice(atIdx + 1).trim() : defaultAccount;
-    publishTargets.push({ route: route as any, account });
-    // Map RoutePrimary to Target enum: wechat-* → "wechat", blog → "blog"
-    mappedTargets.push(route.startsWith("wechat") ? "wechat" : route as Target);
-  }
-
-  // Single target: leave publish_targets empty (backward compat)
-  // Multi-target: populate publish_targets
-  const isMultiTarget = publishTargets.length > 1 || targetsRaw.includes("@");
-
-  // Use mapped targets (Target enum) for intent, not raw RoutePrimary values
-  const intentTargets = mappedTargets.length > 0 ? mappedTargets : targets;
+  const defaultAccount = parseAccountName(accountOverride ?? "default");
+  const parsedTargets = parsePublishTargets(targetsRaw, {
+    contentForm,
+    defaultAccount,
+  });
+  const publishTargets = parsedTargets.targets;
+  const intentTargets = parsedTargets.intentTargets;
 
   const runId = generateRunId();
   const statePath = getRunStatePath(workspace, runId);
@@ -121,16 +105,16 @@ Options:
   state.state_path = statePath;
   state.mode = "active";
   state.route = resolveFullRoute(intentText, {
-    account: accountOverride,
+    account: accountOverride ? defaultAccount : undefined,
     contentForm,
     targets: intentTargets,
   });
 
   // Set publish_targets if multi-target
-  if (isMultiTarget && publishTargets.length > 0) {
+  if (parsedTargets.explicit && publishTargets.length > 0) {
     state.publish_targets = publishTargets;
     // First target becomes primary route
-    state.route.primary = publishTargets[0].route as any;
+    state.route.primary = publishTargets[0].route;
     state.route.account = publishTargets[0].account;
   }