@zzclub/pipeline 0.13.2 → 0.16.0

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,25 @@
+# Bundled article styles
+
+The browser renderer includes `@zzclub/milkdown-article-style` (`article.css` and `tokens-default.css`), distributed under the following license. Other dependencies retain their own licenses. Commercial article templates are separate packages and are not covered by this license.
+
+MIT License
+
+Copyright (c) 2026 aatrooox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@zzclub/pipeline",
-  "version": "0.13.2",
+  "version": "0.16.0",
   "type": "module",
+  "license": "MIT",
   "bin": {
     "zzp": "./src/cli.ts",
     "zzhub-pipeline": "./src/cli.ts"
@@ -10,7 +11,9 @@
     "access": "public"
   },
   "files": [
-    "src/"
+    "src/",
+    "ARTICLE-THEMES.md",
+    "THIRD-PARTY-NOTICES.md"
   ],
   "scripts": {
     "dev": "bun run src/cli.ts",
@@ -40,6 +43,7 @@
     "@types/pngjs": "^6.0.5",
     "changelogen": "^0.6.2",
     "juice": "11.1.1",
+    "remark-highlight-mark": "^1.4.0",
     "typescript": "^5.7.0",
     "vite": "^7.1.10"
   }

package/src/adapter-types.ts

@@ -143,6 +143,9 @@ export interface MarkdownRenderInput {
   /** Path to custom CSS file for style overrides */
   customCss?: string | null;
 
+  /** 可选的离线正文模板，旧插件可以忽略。 */
+  articleThemePath?: string | null;
+
   /** Workflow state for context */
   state?: WorkflowState;
 

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

@@ -52,6 +52,7 @@ export const builtinMarkdownRenderer: MarkdownRenderPlugin = {
       title: input.title,
       previewShellOutPath: input.previewShellOutPath,
       customCss: input.customCss,
+      articleThemePath: input.articleThemePath,
       themeOverrides: input.themeOverrides,
       timeoutMs: input.timeoutMs,
       debugDir: input.debugDir ?? undefined,

package/src/article-theme.test.ts

@@ -0,0 +1,87 @@
+import { afterEach, expect, test } from "bun:test";
+import { mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { readArticleTheme, snapshotArticleTheme } from "./article-theme";
+import { filterIdempotent } from "./providers/publish-core";
+
+const roots: string[] = [];
+afterEach(async () => { for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true }); });
+
+async function fixture() {
+  const root = await mkdtemp(join(tmpdir(), "zzp-theme-"));
+  roots.push(root);
+  const manifest = { schemaVersion: 1, engineVersion: 1, id: "test", name: "样板", version: "1.0.0", assets: ["asset.png"] };
+  for (const [name, content] of Object.entries({ "manifest.json": JSON.stringify(manifest), "article.css": "p { color: red; }", "example.md": "==亮点==", "preview.html": "<p>预览</p>", "LICENSE.txt": "test only", "asset.png": "asset-1" })) await writeFile(join(root, name), content);
+  return { root, manifest };
+}
+
+test("离线包校验、并发安装与样式/素材版本失效", async () => {
+  const { root } = await fixture();
+  const theme = await readArticleTheme(root);
+  const [a, b] = await Promise.all([snapshotArticleTheme(theme, join(root, "installed")), snapshotArticleTheme(theme, join(root, "installed"))]);
+  expect(a.path).toBe(b.path);
+  expect((await readArticleTheme(a.path)).hash).toBe(theme.hash);
+  await writeFile(join(root, "asset.png"), "asset-2");
+  expect((await readArticleTheme(root)).hash).not.toBe(theme.hash);
+  await writeFile(join(root, "article.css"), "p { color: blue; }");
+  const changed = await readArticleTheme(root);
+  expect(changed.hash).not.toBe(theme.hash);
+  expect(await readFile(join(a.path, "..", "article.css"), "utf8")).toContain("red");
+  const target = { route: "wechat-article" as const, account: "default" };
+  const result = { ...target, status: "success" as const, content_version: 1, render_version: 1, article_theme_hash: theme.hash };
+  expect(filterIdempotent([target], [result as any], 1, 1, new Map([["wechat-article@default", theme.hash]]))).toHaveLength(0);
+  expect(filterIdempotent([target], [result as any], 1, 1, new Map([["wechat-article@default", changed.hash]]))).toHaveLength(1);
+  expect(filterIdempotent([target], [{ ...result, article_theme_hash: undefined } as any], 1, 1)).toHaveLength(0);
+});
+
+test("越界、符号链接、网络样式与不兼容版本不能导入", async () => {
+  const { root, manifest } = await fixture();
+  for (const patch of [{ assets: ["../outside"] }, { schemaVersion: 2 }, { engineVersion: 2 }, { editorVars: { "--brand": "url(file:///secret)" } }]) {
+    await writeFile(join(root, "manifest.json"), JSON.stringify({ ...manifest, ...patch }));
+    await expect(readArticleTheme(root)).rejects.toThrow();
+  }
+  await writeFile(join(root, "manifest.json"), JSON.stringify(manifest));
+  await rm(join(root, "asset.png"));
+  await symlink(join(root, "LICENSE.txt"), join(root, "asset.png"));
+  await expect(readArticleTheme(root)).rejects.toThrow("符号链接");
+  await rm(join(root, "asset.png"));
+  await writeFile(join(root, "asset.png"), "asset");
+  for (const css of ["@import 'https://example.com/css';", String.raw`p { background: u\72l(file:///secret); }`, "p { background: url/**/(file:///secret); }"]) {
+    await writeFile(join(root, "article.css"), css);
+    await expect(readArticleTheme(root)).rejects.toThrow("外部资源");
+  }
+});
+
+test("结果未知阻止普通重发，明确重置才建立新发布尝试", async () => {
+  const { root } = await fixture();
+  const { defaultState, readState, writeState } = await import("./state");
+  const { PipelineConfigSchema } = await import("./schema/config");
+  const { resolveWorkspacePaths } = await import("./config");
+  const { executePublishTargets } = await import("./providers/publish-core");
+  const { reset } = await import("./commands/reset");
+  const state = defaultState();
+  state.run_id = "unknown-result";
+  state.workspace_root = root;
+  state.state_path = join(root, "state.json");
+  state.intent.content_form = "article";
+  state.asset_path = root;
+  state.publish.results = [{ route: "wechat-article", account: "default", status: "failed", detail: "WX_RESULT_UNKNOWN", published_at: null, content_version: 0, render_version: 0 }];
+  const config = PipelineConfigSchema.parse({});
+  const result = await executePublishTargets({ state, targets: [{ route: "wechat-article", account: "default" }], dryRun: true, config, workspacePaths: resolveWorkspacePaths(root, config) });
+  expect(result.errors[0]?.error).toContain("WX_RESULT_UNKNOWN");
+  state.intent.article_theme = join(root, "missing-template");
+  const invalidTheme = await executePublishTargets({ state, targets: [{ route: "wechat-article", account: "default" }], dryRun: true, config, workspacePaths: resolveWorkspacePaths(root, config) });
+  expect(invalidTheme.errors[0]?.error).toContain("WX_RESULT_UNKNOWN");
+  state.intent.article_theme = null;
+  await writeState(state.state_path, state);
+  await reset(["--state", state.state_path, "--mode", "publish"]);
+  const retried = await readState(state.state_path);
+  expect(retried.publish.attempt).toBe(1);
+  expect(retried.publish.results).toHaveLength(0);
+  config.wx.defaultAccount = "main";
+  config.wx.accounts = { main: { ...config.wx.accounts.default!, articleTheme: root } };
+  const fallback = await executePublishTargets({ state: retried, targets: [{ route: "wechat-article", account: "default" }], dryRun: true, config, workspacePaths: resolveWorkspacePaths(root, config) });
+  expect(fallback.errors).toHaveLength(0);
+  expect(fallback.results[0]?.article_theme_hash).toBe((await readArticleTheme(root)).hash);
+});

package/src/article-theme.ts

@@ -0,0 +1,115 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdir, mkdtemp, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { z } from "zod";
+
+/** 模板只包含声明、CSS 与素材，不执行客户包中的脚本。 */
+export const ArticleThemeSchema = z.object({
+  schemaVersion: z.literal(1),
+  engineVersion: z.literal(1),
+  id: z.string().regex(/^[a-z0-9][a-z0-9_-]{0,63}$/),
+  name: z.string().min(1).max(80),
+  version: z.string().regex(/^\d+\.\d+\.\d+$/),
+  description: z.string().max(500).default(""),
+  stylesheet: z.string().default("article.css"),
+  sample: z.string().default("example.md"),
+  preview: z.string().default("preview.html"),
+  license: z.string().default("LICENSE.txt"),
+  assets: z.array(z.string()).max(100).default([]),
+  editorVars: z.record(z.string(), z.string()).default({}),
+  exportTheme: z.record(z.string(), z.string()).default({}),
+  structure: z.object({
+    numberedHeadings: z.boolean().default(false),
+    headingLabel: z.string().max(30).default(""),
+    quoteLabel: z.string().max(30).default(""),
+    headerImage: z.string().nullable().default(null),
+  }).default({ numberedHeadings: false, headingLabel: "", quoteLabel: "", headerImage: null }),
+}).strict();
+
+export type ArticleThemeManifest = z.infer<typeof ArticleThemeSchema>;
+export interface ArticleThemePackage {
+  manifest: ArticleThemeManifest;
+  path: string;
+  hash: string;
+  css: string;
+  files: Map<string, Uint8Array>;
+}
+
+/** 限制所有资源在包内，拒绝符号链接、目录越界及过大文件。 */
+export async function readArticleTheme(inputPath: string): Promise<ArticleThemePackage> {
+  const entry = resolve(inputPath);
+  const entryStat = await lstat(entry);
+  if (entryStat.isSymbolicLink()) throw new Error("模板入口不能是符号链接");
+  const manifestPath = entryStat.isDirectory() ? join(entry, "manifest.json") : entry;
+  const root = await realpath(dirname(manifestPath));
+  const files = new Map<string, Uint8Array>();
+  let total = 0;
+  async function read(name: string): Promise<Uint8Array> {
+    if (!name || isAbsolute(name) || name.split(/[\\/]/).includes("..") || name.includes("\\")) throw new Error("模板资源必须位于包内");
+    const target = resolve(root, name);
+    const rel = relative(root, target);
+    if (!rel || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new Error("模板资源路径越界");
+    let current = root;
+    for (const part of rel.split(sep)) {
+      current = join(current, part);
+      if ((await lstat(current)).isSymbolicLink()) throw new Error("模板资源不能是符号链接");
+    }
+    const stat = await lstat(target);
+    if (!stat.isFile() || stat.size > 5 * 1024 * 1024) throw new Error("模板单个资源不能超过 5 MiB");
+    const bytes = await readFile(target);
+    total += bytes.byteLength;
+    if (total > 20 * 1024 * 1024) throw new Error("模板资源合计不能超过 20 MiB");
+    files.set(name, bytes);
+    return bytes;
+  }
+  const manifestName = basename(manifestPath);
+  const manifest = ArticleThemeSchema.parse(JSON.parse(new TextDecoder().decode(await read(manifestName))));
+  const paths = [manifest.stylesheet, manifest.sample, manifest.preview, manifest.license, ...manifest.assets];
+  if (manifest.structure.headerImage) paths.push(manifest.structure.headerImage);
+  for (const name of new Set(paths)) await read(name);
+  const css = new TextDecoder().decode(files.get(manifest.stylesheet));
+  // 模板无需 CSS 转义；拒绝用转义或注释隐藏的网络/文件资源。
+  const unsafeCss = (value: string) => /\\|@import\b|url\s*\(|expression\s*\(/i.test(value.replace(/\/\*[\s\S]*?\*\//g, ""));
+  if (Object.keys(manifest.editorVars).some(key => !/^--[a-zA-Z0-9_-]+$/.test(key))) throw new Error("模板变量名无效");
+  for (const value of [...Object.values(manifest.editorVars), ...Object.values(manifest.exportTheme)]) {
+    if (value.length > 8192 || unsafeCss(value)) throw new Error("模板变量不能包含外部资源或 CSS 转义");
+  }
+  if (manifest.structure.headerImage && !/\.(png|jpe?g|gif|webp)$/i.test(manifest.structure.headerImage)) throw new Error("模板页首素材仅支持 PNG、JPEG、GIF、WebP");
+  if (css.length > 256_000 || unsafeCss(css)) throw new Error("模板 CSS 不支持外部资源、CSS 转义或可执行表达式");
+  const digest = createHash("sha256").update(JSON.stringify(manifest)).update(css);
+  for (const name of [...new Set([...manifest.assets, ...(manifest.structure.headerImage ? [manifest.structure.headerImage] : [])])].sort()) {
+    digest.update(name).update(files.get(name)!);
+  }
+  return { manifest, path: join(root, manifestName), css, files, hash: digest.digest("hex") };
+}
+
+/** 内容寻址的只读副本，运行中修改原模板不会改变当前发布结果。 */
+export async function snapshotArticleTheme(theme: ArticleThemePackage, destination: string): Promise<ArticleThemePackage> {
+  await mkdir(destination, { recursive: true });
+  const root = join(await realpath(destination), `${theme.manifest.id}-${theme.hash}`);
+  try {
+    const existing = await readArticleTheme(root);
+    if (existing.hash !== theme.hash) throw new Error("已安装的模板被修改，请重新导入到新的目录");
+    return existing;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  const temporary = await mkdtemp(join(dirname(root), ".import-"));
+  try {
+    for (const [name, bytes] of theme.files) {
+      const target = join(temporary, name);
+      await mkdir(dirname(target), { recursive: true });
+      await writeFile(target, bytes);
+    }
+    await writeFile(join(temporary, "manifest.json"), JSON.stringify(theme.manifest, null, 2));
+    try { await rename(temporary, root); }
+    catch (error) {
+      if (!["EEXIST", "ENOTEMPTY"].includes((error as NodeJS.ErrnoException).code || "")) throw error;
+      if ((await readArticleTheme(root)).hash !== theme.hash) throw new Error("已安装的模板内容不一致");
+    }
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+  }
+  const entry = join(root, "manifest.json");
+  return { ...theme, path: entry };
+}

package/src/commands/abandon.test.ts

@@ -13,7 +13,7 @@ async function makeTempDir(prefix: string): Promise<string> {
   return mkdtemp(join(tmpdir(), prefix));
 }
 
-async function captureJsonOutput<T>(fn: () => Promise<void>): Promise<T> {
+async function captureJsonOutput<T>(fn: () => Promise<unknown>): Promise<T> {
   const original = console.log;
   const lines: string[] = [];
   console.log = (...args: unknown[]) => {

package/src/commands/article-theme.ts

@@ -0,0 +1,16 @@
+import { parseArgs, optionalArg, requireArg } from "../args";
+import { readArticleTheme, snapshotArticleTheme } from "../article-theme";
+import { printResult } from "../output";
+
+/** 校验或安装离线模板，供 CLI 和桌面端共用。 */
+export async function articleTheme(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+  if (parsed.help) {
+    console.log("Usage: zzp article-theme --path <模板目录或 manifest.json> [--install <本地模板库>]\n只校验或复制模板，不联网、不发布。");
+    return;
+  }
+  let theme = await readArticleTheme(requireArg(parsed, "path", "template path"));
+  const destination = optionalArg(parsed, "install");
+  if (destination) theme = await snapshotArticleTheme(theme, destination);
+  printResult({ ...theme.manifest, path: theme.path, hash: theme.hash });
+}

package/src/commands/checkpoint.test.ts

@@ -10,7 +10,7 @@ async function makeTempDir(prefix: string): Promise<string> {
   return mkdtemp(join(tmpdir(), prefix));
 }
 
-async function captureJsonOutput<T>(fn: () => Promise<void>): Promise<T> {
+async function captureJsonOutput<T>(fn: () => Promise<unknown>): Promise<T> {
   const original = console.log;
   const lines: string[] = [];
   console.log = (...args: unknown[]) => {
@@ -24,7 +24,7 @@ async function captureJsonOutput<T>(fn: () => Promise<void>): Promise<T> {
   return JSON.parse(lines.join("\n").trim()) as T;
 }
 
-async function captureTextOutput(fn: () => Promise<void>): Promise<string> {
+async function captureTextOutput(fn: () => Promise<unknown>): Promise<string> {
   const original = console.log;
   const lines: string[] = [];
   console.log = (...args: unknown[]) => {

package/src/commands/ingest-handoff.ts

@@ -26,6 +26,7 @@ import { findTask, getTaskByStatePath } from "../task-manager";
 
 interface PublishHandoffInput {
   cover_theme?: string | null;
+  article_theme?: string | null;
   content_form: ContentForm;
   body_path: string;
   target_account: string;
@@ -38,6 +39,7 @@ type WorkflowHandoffMode = "new" | "resume";
 
 interface WorkflowHandoffInput {
   cover_theme?: string | null;
+  article_theme?: string | null;
   mode?: WorkflowHandoffMode;
   state_path?: string;
   run_id?: string;
@@ -55,6 +57,7 @@ interface WorkflowHandoffInput {
 
 interface ResolvedWorkflowHandoff {
   cover_theme?: string | null;
+  article_theme?: string | null;
   source: "publish_handoff" | "workflow_handoff";
   mode: WorkflowHandoffMode;
   state_path?: string;
@@ -167,6 +170,7 @@ function parsePublishHandoff(raw: unknown): ResolvedWorkflowHandoff {
 
   return {
     source: "publish_handoff",
+    article_theme: input.article_theme === null ? null : cleanString(input.article_theme, "article_theme"),
     cover_theme: input.cover_theme === null ? null : cleanString(input.cover_theme, "publish_handoff.cover_theme"),
     mode: "new",
     content_form: contentForm,
@@ -199,6 +203,7 @@ function parseWorkflowHandoff(raw: unknown): ResolvedWorkflowHandoff {
       : "new");
   const handoff: ResolvedWorkflowHandoff = {
     source: "workflow_handoff",
+    article_theme: input.article_theme === null ? null : cleanString(input.article_theme, "article_theme"),
     cover_theme: input.cover_theme === null ? null : cleanString(input.cover_theme, "workflow_handoff.cover_theme"),
     mode,
     state_path: cleanString(input.state_path, "workflow_handoff.state_path"),
@@ -326,6 +331,7 @@ async function applyHandoffToState(
 ): Promise<void> {
   const targets: Target[] = state.intent.targets.length > 0 ? state.intent.targets : ["wechat"];
   let restartFromPrepare = false;
+  if (handoff.article_theme !== undefined) state.intent.article_theme = handoff.article_theme ? resolve(handoff.article_theme) : null;
   const themeChanged = handoff.cover_theme !== undefined && handoff.cover_theme !== state.intent.cover_theme;
   if (themeChanged) {
     resolveCoverTheme(loadConfig().render.cover, "poster-3-4", handoff.target_account ?? state.route.account, handoff.cover_theme);

package/src/commands/init.ts

@@ -24,6 +24,8 @@
  */
 
 import { readFile } from "fs/promises";
+import { resolve } from "node:path";
+import { z } from "zod";
 import { parseArgs, requireArg, optionalArg, flagArg } from "../args";
 import { printResult, renderInit } from "../output";
 import { loadConfig, resolveWorkspaceRoot } from "../config";
@@ -66,6 +68,7 @@ Options:
   --requires-style     Flag
   --requires-render    Flag
   --requires-publish   Flag
+  --newspic-file       Confirmed newspic text and photos JSON file (optional)
   --existing-draft-media-id  Update existing WeChat draft instead of creating new one (optional)
 `.trim());
     return;
@@ -83,6 +86,12 @@ Options:
   const existingDraftMediaId = optionalArg(parsed, "existing-draft-media-id") ?? null;
   const noteId = optionalArg(parsed, "note-id") ?? null;
   const config = loadConfig();
+  const newspicFile = optionalArg(parsed, "newspic-file");
+  if (newspicFile) {
+    if (contentForm !== "newspic") throw new Error("newspic-file requires content form newspic");
+    z.object({ content: z.string().trim().min(1).max(100_000), photos: z.array(z.string().min(1)).max(20) }).strict()
+      .parse(JSON.parse(await readFile(newspicFile, "utf8")));
+  }
   const workspace = resolveWorkspaceRoot(optionalArg(parsed, "workspace"), config);
   if (coverTheme !== null) resolveCoverTheme(config.render.cover, "poster-3-4", accountOverride, coverTheme);
 
@@ -132,6 +141,7 @@ Options:
     style_hint: styleHint,
     cover_theme: coverTheme,
     newspic_render: newspicRender,
+    ...(newspicFile ? { newspic_file: resolve(newspicFile) } : {}),
     requires: {
       research: flagArg(parsed, "requires-research"),
       style: flagArg(parsed, "requires-style"),

package/src/commands/prepare.ts

@@ -197,7 +197,11 @@ Options:
   // 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");
+  // 只有用户明确上传的配图才跳过生成；空配图继续默认渲染流程。
+  const hasUploadedPhotos = state.intent.newspic_file
+    ? JSON.parse(await readFile(state.intent.newspic_file, "utf8")).photos.length > 0
+    : false;
+  state.intent.requires.render = allRoutes.some((r) => r !== "blog" && !(r === "wechat-newspic" && hasUploadedPhotos));
   state.intent.requires.publish = state.intent.task_kind === "publish";
 
   // ── Step 2: Author select ──

package/src/commands/publish.ts

@@ -13,6 +13,7 @@
  * Output: Updated state with publish.results
  */
 
+import { resolve } from "node:path";
 import { parseArgs, requireArg, optionalArg, flagArg } from "../args";
 import { printResult, renderPublish } from "../output";
 import { loadConfig, resolveWorkspacePaths } from "../config";
@@ -46,6 +47,7 @@ Usage: zzhub-pipeline publish [options]
 Options:
   --state      Path to state JSON (required)
   --route      Only publish this route (optional; default: all targets)
+  --article-theme    Local article theme package (optional)
   --dry-run    Print commands without executing (optional)
 `.trim());
     return;
@@ -65,6 +67,8 @@ Options:
   const statePath = resolved.path;
   const state = resolved.state;
   const config = loadConfig();
+  const articleTheme = optionalArg(parsed, "article-theme");
+  if (articleTheme) state.intent.article_theme = resolve(articleTheme);
   const workspacePaths = resolveWorkspacePaths(state.workspace_root, config);
 
   if (!state.asset_path) {

package/src/commands/reset.ts

@@ -121,6 +121,8 @@ Modes:
 
     case "publish":
       reenterPublish(state);
+      // 用户核对草稿后明确重置，才生成新的请求幂等身份。
+      state.publish.attempt = (state.publish.attempt ?? 0) + 1;
       state.publish.results = state.publish.results.filter(
         (result) =>
           result.content_version !== state.artifacts.content_version ||

package/src/commands/wechat-export.ts

@@ -69,6 +69,8 @@ Options:
   --account            Account/theme key (optional; default: default)
   --title              Page title for the render shell (optional)
   --preview-shell-out  Path to exact final-HTML preview (optional)
+  --article-theme      Local article theme package (optional)
+  --summary-only       Omit HTML from stdout; still write the complete output file
   --custom-css         CSS override path; replaces account customCss (optional)
   --timeout-ms         Real browser wait limit in ms (default: 15000)
   --debug-dir          Write intermediate artifacts for debugging (optional)
@@ -123,6 +125,7 @@ ${CSS_DEMO}
       title,
       previewShellOutPath,
       customCss,
+      articleThemePath: optionalArg(parsed, "article-theme") ? resolve(optionalArg(parsed, "article-theme")!) : resolveConfigRelativePath(wxAccount?.articleTheme),
       themeOverrides: wxAccount?.theme,
       timeoutMs: timeoutMs !== undefined && Number.isFinite(timeoutMs) ? timeoutMs : undefined,
       debugDir: debugDir ? resolve(process.cwd(), debugDir) : undefined,
@@ -166,6 +169,7 @@ ${CSS_DEMO}
     printResult(
       {
         ...resultRest,
+        ...(flagArg(parsed, "summary-only") ? { html: undefined } : {}),
         preview_url,
         preview_dashboard_url,
         preview_register_error,

package/src/commands/wechat-preview.ts

@@ -31,6 +31,7 @@ Usage: zzhub-pipeline wechat-preview <subcommand> [options]
 
 Subcommands:
   serve     Start the singleton local preview server (or print existing URL)
+  studio    Start server and open WeChat Visual Studio in browser
   status    Show whether the preview server is running
   open      Open the dashboard in a browser
   list      List registered preview entries
@@ -95,6 +96,40 @@ export async function wechatPreview(args: string[]): Promise<void> {
     return;
   }
 
+  if (sub === "studio") {
+    const host = optionalArg(parsed, "host");
+    const portRaw = optionalArg(parsed, "port");
+    const port = portRaw ? Number(portRaw) : undefined;
+    const force = flagArg(parsed, "force");
+
+    const result = await startPreviewServer({
+      host,
+      port: port !== undefined && Number.isFinite(port) ? port : undefined,
+      reuseExisting: !force,
+    });
+
+    const studioUrl = `${result.url}/studio`;
+    if (!flagArg(parsed, "no-open")) {
+      await openUrl(studioUrl);
+    }
+
+    printResult({
+      action: "studio",
+      url: studioUrl,
+      host: result.host,
+      port: result.port,
+      reused: result.reused,
+      message: `WeChat Visual Studio opened at ${studioUrl}`,
+    });
+
+    if (!result.reused) {
+      await new Promise<void>(() => {
+        // blocked until SIGINT/SIGTERM
+      });
+    }
+    return;
+  }
+
   if (sub === "status") {
     const host = optionalArg(parsed, "host");
     const portRaw = optionalArg(parsed, "port");

package/src/plugins.ts

@@ -22,6 +22,7 @@ import { review } from "./commands/review";
 import { status } from "./commands/status";
 import { syncBlog } from "./commands/sync-blog";
 import { tasks } from "./commands/tasks";
+import { articleTheme } from "./commands/article-theme";
 import { wechatExport } from "./commands/wechat-export";
 import { wechatPreview } from "./commands/wechat-preview";
 import { wxDrafts } from "./commands/wx-drafts";
@@ -72,6 +73,7 @@ export function getCommandPlugins(): CommandPlugin[] {
         { name: "sync-blog", summary: "Copy post.md to blog repo, publish, and record result in state JSON", plugin: "ops", handler: syncBlog },
         { name: "republish", summary: "Publish completed task to additional accounts/platforms", plugin: "ops", handler: republish },
         { name: "imgx", summary: "Run bundled imgx renderer subcommands", plugin: "ops", handler: imgxCommand },
+        { name: "article-theme", summary: "Inspect or install a local article theme", plugin: "ops", handler: articleTheme },
         { name: "wechat-export", summary: "Render markdown to WeChat HTML with bundled preview styles", plugin: "ops", handler: wechatExport },
         { name: "wechat-preview", summary: "Local singleton server to preview exported WeChat HTML", plugin: "ops", handler: wechatPreview },
         { name: "cos-upload", summary: "Upload a local image to configured COS CDN", plugin: "ops", handler: cosUpload },

package/src/providers/index.ts

@@ -1,3 +1,5 @@
+import type { ArticleThemePackage } from "../article-theme";
+import { createHash } from "node:crypto";
 import { readFile, writeFile } from "fs/promises";
 import { join } from "path";
 import {
@@ -21,6 +23,7 @@ export interface PublishRouteContext {
   config: PipelineConfig;
   workspacePaths: ResolvedWorkspacePaths;
   accountOverride?: string;
+  articleTheme?: ArticleThemePackage;
 }
 
 export type PublishProvider = (ctx: PublishRouteContext) => Promise<PublishResult>;
@@ -31,6 +34,7 @@ async function publishWechatArticleRoute({
   config,
   workspacePaths,
   accountOverride,
+  articleTheme,
 }: PublishRouteContext): Promise<PublishResult> {
   const postPath = join(state.asset_path, "post.md");
   let exportPostPath = postPath;
@@ -87,6 +91,7 @@ async function publishWechatArticleRoute({
       account,
       title: state.metadata.title,
       customCss: resolveConfigRelativePath(wxAccount?.customCss),
+      articleThemePath: articleTheme?.path,
       themeOverrides: wxAccount?.theme,
     });
     const { html } = rendered;
@@ -124,6 +129,7 @@ async function publishWechatArticleRoute({
       title: state.metadata.title,
       html,
       photos,
+      idempotencyKey: createHash("sha256").update(JSON.stringify([state.run_id, state.publish.attempt ?? 0, account, state.artifacts.content_version, state.artifacts.render_version, articleTheme?.hash, state.intent.existing_draft_media_id])).digest("hex"),
       config,
       existingDraftMediaId: state.intent.existing_draft_media_id,
       noteId: state.intent.note_id,
@@ -162,8 +168,15 @@ async function publishWechatNewspicRoute({
 }: PublishRouteContext): Promise<PublishResult> {
   const postPath = join(state.asset_path, "post.md");
   const postContent = await readFile(postPath, "utf-8");
+  // 副本正文原样发送，手动配图优先，空配图使用生成的封面和内容页。
+  const snapshot = state.intent.newspic_file
+    ? JSON.parse(await readFile(state.intent.newspic_file, "utf8")) as { content: string; photos: string[] }
+    : null;
   const bodyImageUrls = extractImageUrls(postContent);
-  const cleanContent = prepareBodyForNewspic(postContent);
+  let cleanContent = snapshot?.content ?? prepareBodyForNewspic(postContent);
+  // 旧入口没有独立配文时使用短摘录，全文已保存在内容图中。
+  if (!snapshot && Buffer.byteLength(cleanContent, "utf8") > 2048)
+    cleanContent = `${Array.from(cleanContent).slice(0, 500).join("")}…`;
   const cleanPath = join(state.asset_path, "post-clean.md");
   if (!dryRun) {
     await writeFile(cleanPath, cleanContent, "utf-8");
@@ -178,7 +191,7 @@ async function publishWechatNewspicRoute({
     });
 
   const renderPhotos = assets.map((asset) => asset.path);
-  const photos = mergePhotoLists(renderPhotos, bodyImageUrls);
+  const photos = snapshot ? (snapshot.photos.length ? snapshot.photos : renderPhotos) : mergePhotoLists(renderPhotos, bodyImageUrls);
 
   const account = accountOverride || state.route.account;
 
@@ -198,10 +211,12 @@ async function publishWechatNewspicRoute({
 
   try {
     const response = await createWechatNewspic({
+      idempotencyKey: createHash("sha256").update(JSON.stringify([state.run_id, state.publish.attempt ?? 0, account, "newspic", state.artifacts.content_version, state.artifacts.render_version, state.intent.existing_draft_media_id])).digest("hex"),
       account,
       title: state.metadata.title,
       content: cleanContent,
       photos,
+      explicitPhotos: !!snapshot,
       config,
       existingDraftMediaId: state.intent.existing_draft_media_id,
       noteId: state.intent.note_id,