@zzclub/pipeline 0.10.0 → 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.10.0",
+  "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/commands/prepare.ts

@@ -69,15 +69,16 @@ function getManagedFormattedBodyPath(workspaceRoot: string, runId: string): stri
 }
 
 function shouldPreserveExistingRoute(params: {
-  intentText: string;
+  hasExplicitPublishTargets: boolean;
+  hasIntentOverride: boolean;
   routeOverride?: RoutePrimary;
   extrasRaw?: string;
   accountOverride?: string;
   assetPath: string;
 }): boolean {
   return (
-    Boolean(params.assetPath) &&
-    !params.intentText.trim() &&
+    (params.hasExplicitPublishTargets || Boolean(params.assetPath)) &&
+    !params.hasIntentOverride &&
     !params.routeOverride &&
     !params.extrasRaw &&
     !params.accountOverride
@@ -133,7 +134,8 @@ Options:
   const resolved = await readResolvedState(requestedStatePath);
   const statePath = resolved.path;
   const state = resolved.state;
-  const intentText = optionalArg(parsed, "intent-text") ?? state.intent.intent_text ?? "";
+  const intentTextOverride = optionalArg(parsed, "intent-text");
+  const intentText = intentTextOverride ?? state.intent.intent_text ?? "";
   const resolvedBodyPath = bodyPath
     ? await stageManagedBodyFile(state.workspace_root, state.run_id, bodyPath)
     : state.source_body_path;
@@ -154,7 +156,8 @@ Options:
 
   // ── Step 1: Channel route (1st pass) ──
   const route = shouldPreserveExistingRoute({
-    intentText,
+    hasExplicitPublishTargets: state.publish_targets.length > 0,
+    hasIntentOverride: intentTextOverride !== undefined,
     routeOverride,
     extrasRaw,
     accountOverride,

package/src/commands/wechat-export.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from "bun:test";
+import { resolveConfigRelativePath } from "../config";
+import { resolveWechatExportCustomCss } from "./wechat-export";
+
+describe("wechat-export custom CSS path precedence", () => {
+  const configPath = "/workspace/config/config.json";
+
+  test("resolves configured CSS relative to the config file", () => {
+    expect(resolveConfigRelativePath("themes/account.css", configPath)).toBe(
+      "/workspace/config/themes/account.css",
+    );
+  });
+
+  test("keeps an absolute configured CSS path", () => {
+    expect(resolveConfigRelativePath("/opt/zzhub/account.css", configPath)).toBe(
+      "/opt/zzhub/account.css",
+    );
+  });
+
+  test("uses account CSS when the CLI override is absent", () => {
+    expect(resolveWechatExportCustomCss(
+      undefined,
+      "themes/account.css",
+      "/workspace/post",
+      configPath,
+    )).toBe("/workspace/config/themes/account.css");
+  });
+
+  test("CLI CSS replaces account CSS and resolves from the current directory", () => {
+    expect(resolveWechatExportCustomCss(
+      "./local.css",
+      "themes/account.css",
+      "/workspace/post",
+      configPath,
+    )).toBe("/workspace/post/local.css");
+  });
+
+  test("returns null when neither source configures CSS", () => {
+    expect(resolveWechatExportCustomCss(undefined, null, "/workspace/post", configPath)).toBeNull();
+  });
+});

package/src/commands/wechat-export.ts

@@ -1,13 +1,12 @@
+import { resolve } from "path";
 import { optionalArg, parseArgs, requireArg } from "../args";
 import { printResult, renderWechatExport } from "../output";
-import { loadConfig } from "../config";
+import { loadConfig, resolveConfigRelativePath } from "../config";
 import { resolveMarkdownRenderer } from "../adapter-loader";
 
 const CSS_DEMO = `
-Custom CSS is injected as a <style> tag after the built-in Milkdown styles
-and before the browser renders. WeChat requires inline styles, so the
-rendering pipeline captures computed styles from the DOM — your CSS
-cascades naturally and the final inline-styled HTML will reflect it.
+Custom CSS is cascaded after the built-in theme and converted to conservative
+inline styles. Use semantic selectors or stable data-wechat-node hooks.
 
 Example custom.css:
 
@@ -26,6 +25,17 @@ Example custom.css:
   }
 `.trim();
 
+export function resolveWechatExportCustomCss(
+  cliCustomCss: string | undefined,
+  accountCustomCss: string | null | undefined,
+  cwd: string = process.cwd(),
+  configPath?: string,
+): string | null {
+  return cliCustomCss
+    ? resolve(cwd, cliCustomCss)
+    : resolveConfigRelativePath(accountCustomCss, configPath);
+}
+
 export async function wechatExport(args: string[]): Promise<void> {
   const parsed = parseArgs(args);
 
@@ -38,8 +48,8 @@ Options:
   --out                Path to exported html file (required)
   --account            Account/theme key (optional; default: default)
   --title              Page title for the render shell (optional)
-  --preview-shell-out  Path to full Milkdown preview html (optional)
-  --custom-css         Path to custom CSS file for style overrides (optional)
+  --preview-shell-out  Path to exact final-HTML preview (optional)
+  --custom-css         CSS override path; replaces account customCss (optional)
 
 ${CSS_DEMO}
 `.trim());
@@ -51,10 +61,14 @@ ${CSS_DEMO}
   const account = optionalArg(parsed, "account") ?? "default";
   const title = optionalArg(parsed, "title");
   const previewShellOutPath = optionalArg(parsed, "preview-shell-out");
-  const customCss = optionalArg(parsed, "custom-css");
+  const cliCustomCss = optionalArg(parsed, "custom-css");
 
   const config = loadConfig();
   const wxAccount = config.wx.accounts[account] ?? config.wx.accounts[config.wx.defaultAccount];
+  const customCss = resolveWechatExportCustomCss(
+    cliCustomCss,
+    wxAccount?.customCss,
+  );
   const markdownRenderer = await resolveMarkdownRenderer(config);
   const result = await markdownRenderer.render({
     markdownPath,

package/src/config.ts

@@ -85,6 +85,18 @@ export function getPipelineConfigPath(): string {
   return join(getBaseConfigDir(PIPELINE_CONFIG_DIR), PIPELINE_CONFIG_FILE);
 }
 
+/** Resolve a file path stored in config relative to the config file directory. */
+export function resolveConfigRelativePath(
+  value: string | null | undefined,
+  configPath: string = getPipelineConfigPath(),
+): string | null {
+  const trimmed = value?.trim();
+  if (!trimmed) return null;
+  return isAbsolute(trimmed)
+    ? resolve(trimmed)
+    : resolve(dirname(configPath), trimmed);
+}
+
 export function getLegacyZCliConfigPath(): string {
   return join(getBaseConfigDir(LEGACY_ZCLI_CONFIG_DIR), PIPELINE_CONFIG_FILE);
 }

package/src/providers/index.ts

@@ -1,6 +1,10 @@
 import { readFile, writeFile } from "fs/promises";
 import { join } from "path";
-import { PipelineConfig, ResolvedWorkspacePaths } from "../config";
+import {
+  resolveConfigRelativePath,
+  type PipelineConfig,
+  type ResolvedWorkspacePaths,
+} from "../config";
 import { PublishResult, RenderAsset, RoutePrimary, WorkflowState } from "../state";
 import {
   injectIllustrationImages,
@@ -80,7 +84,7 @@ async function publishWechatArticleRoute({
       outPath: workspacePaths.zotepadExportHtml,
       account,
       title: state.metadata.title,
-      customCss: wxAccount?.customCss ?? null,
+      customCss: resolveConfigRelativePath(wxAccount?.customCss),
       themeOverrides: wxAccount?.theme,
     });
     const response = await createWechatDraft({

package/src/publish-targets.ts

@@ -126,13 +126,12 @@ export function getStatePublishTargets(state: {
   publish_targets: PublishTarget[];
   route: { primary: RoutePrimary; extras: RoutePrimary[]; account: string };
 }): PublishTarget[] {
-  const targets = [
-    ...[state.route.primary, ...state.route.extras].map((route) => ({
+  const targets = state.publish_targets.length > 0
+    ? state.publish_targets
+    : [state.route.primary, ...state.route.extras].map((route) => ({
       route,
       account: state.route.account,
-    })),
-    ...state.publish_targets,
-  ];
+    }));
   const seen = new Set<string>();
   return targets.filter((target) => {
     const key = `${target.route}@${target.account}`;

package/src/routes.ts

@@ -205,12 +205,13 @@ export function routePlanFromTargets(
 ): { primary: RoutePrimary; extras: RoutePrimary[] } | null {
   const uniqueTargets = [...new Set(targets)];
   const wantsWechat = uniqueTargets.includes("wechat");
+  const wantsBlog = uniqueTargets.includes("blog");
 
   if (form === "article") {
     if (wantsWechat) {
       return {
         primary: "wechat-article",
-        extras: [],
+        extras: wantsBlog ? ["blog"] : [],
       };
     }
   }
@@ -218,6 +219,13 @@ export function routePlanFromTargets(
   if (form === "newspic" && wantsWechat) {
     return {
       primary: "wechat-newspic",
+      extras: wantsBlog ? ["blog"] : [],
+    };
+  }
+
+  if (wantsBlog) {
+    return {
+      primary: "blog",
       extras: [],
     };
   }