@akairos/pipeline 0.21.0 → 0.22.0

package/article-snapshot.ts

@@ -0,0 +1,2 @@
+export { createArticleSnapshot, validateArticleSnapshot, createArtifactManifest, hashArtifactManifest, validateArtifactManifest, rewriteArticleImages } from "./src/article-snapshot";
+export type { ArticleSnapshot, ArticleSnapshotInput, ArticleSnapshotContent, BodyAssetIdentity, ArtifactManifest } from "./src/article-snapshot";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akairos/pipeline",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "type": "module",
   "license": "MIT",
   "bin": {
@@ -14,6 +14,7 @@
     "src/",
     "article-style.ts",
     "cover-snapshot.ts",
+    "article-snapshot.ts",
     "ARTICLE-THEMES.md",
     "THIRD-PARTY-NOTICES.md"
   ],
@@ -30,11 +31,12 @@
   },
   "dependencies": {
     "@akairos/milkdown-article-plugins": "^0.1.6",
-    "@akairos/myno": "0.3.2",
-    "@akairos/typeset-studio": "0.3.0",
+    "@akairos/myno": "0.4.1",
+    "@akairos/typeset-studio": "0.4.0",
     "@chenglou/pretext": "0.0.8",
     "image-size": "^2.0.2",
     "pngjs": "^7.0.0",
+    "remark": "^15.0.1",
     "zod": "^4.4.2"
   },
   "optionalDependencies": {

package/src/article-snapshot.test.ts

@@ -0,0 +1,39 @@
+import { expect, test } from "bun:test";
+import { createArticleSnapshot, validateArticleSnapshot, rewriteArticleImages, createArtifactManifest, hashArtifactManifest, validateArtifactManifest } from "../article-snapshot";
+
+const asset = { id: "31161ca7-af98-4a84-adc7-c60885a3bd0f", sha256: "a".repeat(64), contentType: "image/png" as const, byteLength: 100, width: 10, height: 10 };
+const input = { documentId: "521b9c37-1d74-4f23-a0ad-1801ad2f3669", documentRevision: 1, title: "预览", account: "fixed-account", body: `![描述](asset:${asset.id} "图注")`, bodyAssets: [asset] };
+
+test("完整文章输入 hash 绑定修订、正文/账号及素材，拒绝未托管/过量图片", () => {
+  const snapshot = createArticleSnapshot(input);
+  expect(validateArticleSnapshot(snapshot, input)).toEqual(snapshot);
+  expect(() => validateArticleSnapshot(snapshot, { ...input, title: "变化" })).toThrow("input hash");
+  expect(createArticleSnapshot({ ...input, documentRevision: 2 }).inputHash).not.toBe(snapshot.inputHash);
+  for (const body of ["![外图](https://example.test/a.png)", "<img src='asset:bad'>", Array(21).fill(input.body).join("\n")]) expect(() => createArticleSnapshot({ ...input, body })).toThrow();
+  expect(() => createArticleSnapshot({ ...input, bodyAssets: [asset, asset] })).toThrow("Duplicate");
+  expect(() => validateArticleSnapshot({ ...snapshot, schemaVersion: 2 }, input)).toThrow();
+});
+
+test("图片引用转换保定义图注、描述与代码/普通链接/共享definition", () => {
+  const source = '[普通][shared]\n\n![描述][shared]\n\n[shared]: /api/assets/body/image "定义图注"\n\n```md\n![代码](/api/assets/body/image)\n```';
+  const rewritten = rewriteArticleImages(source, () => `asset:${asset.id}`);
+  expect(rewritten).toContain(`![描述](asset:${asset.id} "定义图注")`);
+  expect(rewritten).toContain('[shared]: /api/assets/body/image "定义图注"');
+  expect(rewritten).toContain('[普通][shared]');
+  expect(rewritten).toContain('![代码](/api/assets/body/image)');
+  const brackets = rewriteArticleImages('![左\\[右\\]尾][shared]\n\n[shared]: /image "图注"', () => `asset:${asset.id}`);
+  expect(brackets).toContain(`![左\\[右\\]尾](asset:${asset.id} "图注")`);
+  expect(createArticleSnapshot({ ...input, body: brackets }).inputHash).toBeTruthy();
+});
+
+test("产物 manifest 严格固定key/type和双hash身份", () => {
+  const manifest = createArtifactManifest({ snapshotHash: "b".repeat(64), runtime: { pipeline: "0.22.0", myno: "0.4.1", typeset: "0.4.0" }, artifacts: [
+    { key: "cover", kind: "cover", contentType: "image/png", byteLength: 1, sha256: "c".repeat(64) },
+    { key: "article", kind: "html", contentType: "text/html", byteLength: 2, sha256: "d".repeat(64) },
+    { key: `media_${asset.id}`, kind: "media", contentType: "image/png", byteLength: 100, sha256: asset.sha256 },
+  ] });
+  expect(validateArtifactManifest(manifest, hashArtifactManifest(manifest))).toEqual(manifest);
+  expect(() => validateArtifactManifest(manifest, "0".repeat(64))).toThrow();
+  expect(() => validateArtifactManifest({ ...manifest, path: "/private/html" })).toThrow();
+  expect(() => createArtifactManifest({ ...manifest, artifacts: [...manifest.artifacts, manifest.artifacts[0]!] })).toThrow();
+});

package/src/article-snapshot.ts

@@ -0,0 +1,121 @@
+import { createHash } from "node:crypto";
+import { remark } from "remark";
+import { z } from "zod";
+import { validateArticleStyleSnapshot, type ArticleStyleSnapshot } from "./article-style";
+import { validateCoverSnapshot, type CoverSnapshot } from "./cover-snapshot";
+
+const hash = z.string().regex(/^[a-f\d]{64}$/);
+const uuid = z.string().uuid().transform(value => value.toLowerCase());
+export const BodyAssetIdentitySchema = z.object({
+  id: uuid, sha256: hash, contentType: z.enum(["image/png", "image/jpeg", "image/webp"]),
+  byteLength: z.number().int().positive().max(5 * 1024 * 1024),
+  width: z.number().int().positive(), height: z.number().int().positive(),
+}).strict().refine(value => value.width * value.height <= 32_000_000, "Body image exceeds 32 megapixels");
+export type BodyAssetIdentity = z.infer<typeof BodyAssetIdentitySchema>;
+
+export interface ArticleSnapshotContent {
+  title: string; body: string; account: string;
+  articleStyle?: ArticleStyleSnapshot; coverSnapshot?: CoverSnapshot;
+}
+export interface ArticleSnapshotInput extends ArticleSnapshotContent {
+  documentId: string; documentRevision: number; bodyAssets: BodyAssetIdentity[];
+}
+const ArticleSnapshotSchema = z.object({
+  schemaVersion: z.literal(1), documentId: uuid, documentRevision: z.number().int().positive(),
+  bodyAssets: z.array(BodyAssetIdentitySchema).max(20), inputHash: hash,
+}).strict();
+export type ArticleSnapshot = z.infer<typeof ArticleSnapshotSchema>;
+
+interface ImageNode { type: string; url?: string; identifier?: string; alt?: string; title?: string | null; value?: string; position?: { start: { offset?: number }; end: { offset?: number } }; children?: ImageNode[] }
+
+/** 只遍历 Markdown 图片节点，代码和普通链接不参与资产绑定。 */
+export function rewriteArticleImages(body: string, resolveImage: (source: string) => string): string {
+  const tree = remark().parse(body) as ImageNode;
+  const definitions = new Map<string, ImageNode>();
+  const collect = (node: ImageNode) => { if (node.type === "definition") definitions.set(node.identifier!, node); node.children?.forEach(collect); };
+  collect(tree);
+  const edits: Array<{ start: number; end: number; text: string }> = [];
+  let count = 0;
+  const visit = (node: ImageNode) => {
+    if (node.type === "html" && /<img\b/i.test(node.value || "")) throw new Error("Raw HTML images must be converted to managed Markdown images");
+    if (node.type === "image" || node.type === "imageReference") {
+      if (++count > 20) throw new Error("Article supports at most 20 visible images");
+      const definition = definitions.get(node.identifier!);
+      const source = node.url ?? definition?.url;
+      if (!source) throw new Error("Unresolved image reference");
+      const mapped = resolveImage(source);
+      if (mapped !== source) {
+        const start = node.position?.start.offset, end = node.position?.end.offset;
+        if (start === undefined || end === undefined) throw new Error("Image source position is unavailable");
+        const escape = (text: string) => text.replace(/\\/g, "\\\\").replace(/\[/g, "\\[").replace(/\]/g, "\\]");
+        const originalTitle = node.title ?? definition?.title;
+        const title = originalTitle ? ` "${originalTitle.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"` : "";
+        edits.push({ start, end, text: `![${escape(node.alt || "")}](${mapped}${title})` });
+      }
+    }
+    node.children?.forEach(visit);
+  };
+  visit(tree);
+  for (const edit of edits.sort((a, b) => b.start - a.start)) body = body.slice(0, edit.start) + edit.text + body.slice(edit.end);
+  return body;
+}
+
+export function canonicalHash(value: unknown): string {
+  const normalize = (item: any): any => Array.isArray(item) ? item.map(normalize) : item && typeof item === "object"
+    ? Object.fromEntries(Object.keys(item).sort().filter(key => item[key] !== undefined).map(key => [key, normalize(item[key])])) : item;
+  return createHash("sha256").update(JSON.stringify(normalize(value))).digest("hex");
+}
+
+/** 输入 hash 包含文章、账号固定身份、配置内容与素材清单，不重复保存大字段。 */
+export function createArticleSnapshot(value: ArticleSnapshotInput): ArticleSnapshot {
+  const content = z.object({ title: z.string().trim().min(1).max(255), body: z.string().min(1), account: z.string().regex(/^[a-zA-Z0-9_.-]+$/) }).parse(value);
+  if (Buffer.byteLength(content.body) > 2_097_152) throw new Error("Article body exceeds 2 MiB");
+  const header = ArticleSnapshotSchema.omit({ inputHash: true }).parse({ schemaVersion: 1, documentId: value.documentId, documentRevision: value.documentRevision, bodyAssets: value.bodyAssets });
+  header.bodyAssets.sort((a, b) => a.id.localeCompare(b.id));
+  const identities = new Map(header.bodyAssets.map(asset => [asset.id, asset]));
+  if (identities.size !== header.bodyAssets.length) throw new Error("Duplicate body asset id");
+  const uniqueBytes = new Map(header.bodyAssets.map(asset => [asset.sha256, asset.byteLength]));
+  if ([...uniqueBytes.values()].reduce((sum, bytes) => sum + bytes, 0) > 40 * 1024 * 1024) throw new Error("Body assets exceed 40 MiB");
+  const used = new Set<string>();
+  rewriteArticleImages(content.body, source => {
+    const id = /^asset:([a-f\d-]+)$/.exec(source)?.[1];
+    if (!id || !identities.has(id)) throw new Error("Article contains an unmanaged image");
+    used.add(id); return source;
+  });
+  if (used.size !== identities.size) throw new Error("Body asset is not referenced by the article");
+  const articleStyle = value.articleStyle ? validateArticleStyleSnapshot(value.articleStyle) : undefined;
+  const coverSnapshot = value.coverSnapshot ? validateCoverSnapshot(value.coverSnapshot) : undefined;
+  return { ...header, inputHash: canonicalHash({ ...header, ...content, articleStyle, coverSnapshot }) };
+}
+
+export function validateArticleSnapshot(value: unknown, content: ArticleSnapshotContent): ArticleSnapshot {
+  const input = ArticleSnapshotSchema.parse(value);
+  const snapshot = createArticleSnapshot({ ...content, ...input });
+  if (snapshot.inputHash !== input.inputHash) throw new Error("Article input hash mismatch");
+  return snapshot;
+}
+
+const ArtifactSchema = z.object({
+  key: z.string().regex(/^(article|cover|media_[a-f\d-]{36})$/), kind: z.enum(["html", "cover", "media"]),
+  contentType: z.enum(["text/html", "image/png", "image/jpeg", "image/webp", "image/gif"]), byteLength: z.number().int().positive().max(50 * 1024 * 1024), sha256: hash,
+}).strict();
+const ArtifactManifestSchema = z.object({
+  schemaVersion: z.literal(1), snapshotHash: hash, artifacts: z.array(ArtifactSchema).min(2).max(42),
+  runtime: z.object({ pipeline: z.string().min(1), myno: z.string().min(1), typeset: z.string().min(1) }).strict(),
+}).strict().superRefine((value, ctx) => {
+  const keys = value.artifacts.map(item => item.key);
+  if (new Set(keys).size !== keys.length || !keys.includes("article") || !keys.includes("cover")) ctx.addIssue({ code: "custom", message: "Artifact keys must be unique and contain article/cover" });
+  for (const item of value.artifacts) if (item.key === "article" ? item.kind !== "html" || item.contentType !== "text/html" : item.key === "cover" ? item.kind !== "cover" || item.contentType !== "image/png" : item.kind !== "media" || item.contentType === "text/html") ctx.addIssue({ code: "custom", message: "Artifact key and type mismatch" });
+});
+export type ArtifactManifest = z.infer<typeof ArtifactManifestSchema>;
+export function createArtifactManifest(value: Omit<ArtifactManifest, "schemaVersion">): ArtifactManifest {
+  const manifest = ArtifactManifestSchema.parse({ schemaVersion: 1, ...value });
+  manifest.artifacts.sort((a, b) => a.key.localeCompare(b.key));
+  return manifest;
+}
+export function hashArtifactManifest(value: ArtifactManifest): string { return canonicalHash(ArtifactManifestSchema.parse(value)); }
+export function validateArtifactManifest(value: unknown, expectedHash?: string): ArtifactManifest {
+  const manifest = ArtifactManifestSchema.parse(value);
+  if (expectedHash && hashArtifactManifest(manifest) !== expectedHash) throw new Error("Artifact manifest hash mismatch");
+  return manifest;
+}

package/src/commands/article-export.ts

@@ -0,0 +1,17 @@
+import { parseArgs, requireArg } from "../args";
+import { loadTaskState } from "../task-manager";
+import { loadConfig, resolveWorkspacePaths } from "../config";
+import { readArticleTheme } from "../article-theme";
+import { exportWechatArticle } from "../providers/article-export";
+import { printResult } from "../output";
+
+/** 在发布检查点只导出本地 HTML，预览绝不调用发布 provider。 */
+export async function articleExport(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+  const { state } = await loadTaskState(requireArg(parsed, "state", "state JSON path"));
+  if (state.route.primary !== "wechat-article" || state.phase.render.status !== "done" || !state.asset_path) throw new Error("Article preview requires a rendered article run");
+  const config = loadConfig();
+  const articleTheme = state.intent.article_theme ? await readArticleTheme(state.intent.article_theme) : undefined;
+  const result = await exportWechatArticle({ state, config, workspacePaths: resolveWorkspacePaths(state.workspace_root, config), account: state.route.account, articleTheme });
+  printResult({ htmlPath: result.rendered.htmlPath, coverPath: result.photos[0], assetPath: state.asset_path });
+}

package/src/commands/prepare-finalize.ts

@@ -40,6 +40,7 @@ import {
   stripLeadingTitleHeading,
   removePageMarkers,
 } from "../text";
+import { rewriteArticleImages } from "../article-snapshot";
 
 function isExternalAssetRef(value: string): boolean {
   return /^(https?:|data:|blob:|\/\/)/i.test(value);
@@ -133,7 +134,12 @@ async function materializeInlineAssets(options: {
     return targetRelativePath;
   };
 
-  let rewritten = options.body.replace(
+  let rewritten = process.env.ZZHUB_PIPELINE_ARTICLE_SNAPSHOT === "1"
+    ? rewriteArticleImages(options.body, source => {
+      const target = registerAsset(source);
+      return target ? formatRelativeAssetRef(target) : source;
+    })
+    : options.body.replace(
     /!\[([^\]]*)\]\((?:<([^>]+)>|([^\s)]+))(\s+(?:"[^"]*"|'[^']*'))?\)/g,
     (match, alt, angleSrc, bareSrc, titleSuffix) => {
       const targetRelativePath = registerAsset(String(angleSrc ?? bareSrc ?? ""));
@@ -147,7 +153,7 @@ async function materializeInlineAssets(options: {
     },
   );
 
-  rewritten = rewritten.replace(
+  if (process.env.ZZHUB_PIPELINE_ARTICLE_SNAPSHOT !== "1") rewritten = rewritten.replace(
     /(<img\b[^>]*\bsrc=["'])([^"']+)(["'][^>]*>)/gi,
     (match, prefix, src, suffix) => {
       const targetRelativePath = registerAsset(String(src ?? ""));

package/src/plugins.ts

@@ -30,6 +30,7 @@ import { wxDraftDelete } from "./commands/wx-draft-delete";
 import type { CommandOutcome } from "./command-outcome";
 import { monitor } from "./commands/monitor";
 import { typesetAssetsSync } from "./commands/typeset-assets-sync";
+import { articleExport } from "./commands/article-export";
 
 export interface CommandDefinition {
   name: string;
@@ -76,6 +77,7 @@ export function getCommandPlugins(): CommandPlugin[] {
         { 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: "article-export", summary: "Export a rendered article locally without publishing", plugin: "ops", handler: articleExport },
         { 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 },
         { name: "typeset-assets-sync", summary: "Upload Studio template assets and build a runtime config package", plugin: "ops", handler: typesetAssetsSync },

package/src/providers/article-export.ts

@@ -0,0 +1,68 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { resolveMarkdownRenderer } from "../adapter-loader";
+import { resolveConfigRelativePath, type PipelineConfig, type ResolvedWorkspacePaths } from "../config";
+import type { ArticleThemePackage } from "../article-theme";
+import type { WorkflowState } from "../state";
+import { injectIllustrationImages } from "../text";
+import { reportProgress } from "../monitor/recorder";
+import { validateArtifactManifest, type ArtifactManifest } from "../article-snapshot";
+import type { MarkdownRenderOutput } from "../adapter-types";
+
+/** 文章导出只做本地排版，预览与直接发布复用；没有微信上传操作。 */
+export async function exportWechatArticle({ state, config, workspacePaths, account, articleTheme }: {
+  state: WorkflowState; config: PipelineConfig; workspacePaths: ResolvedWorkspacePaths; account: string; articleTheme?: ArticleThemePackage;
+}): Promise<{ html: string; photos: string[]; rendered: MarkdownRenderOutput; exportPostPath: string }> {
+  let exportPostPath = join(state.asset_path, "post.md");
+  const cover = state.images.render_assets.find(asset => asset.route === "wechat-article" && asset.kind === "cover");
+  const photos = cover ? [cover.path] : [];
+  if (state.images.body_inputs.scope === "article" && state.images.body_inputs.status === "ready") {
+    const body = injectIllustrationImages(await readFile(exportPostPath, "utf8"), state.images.body_inputs.received);
+    exportPostPath = join(state.asset_path, "post-wechat-draft.md");
+    await writeFile(exportPostPath, body);
+    photos.push(...state.images.body_inputs.received.map(image => image.path));
+  }
+  const renderer = await resolveMarkdownRenderer(config);
+  const wxAccount = config.wx.accounts[account] ?? config.wx.accounts[config.wx.defaultAccount];
+  const standalone = articleTheme?.manifest.css !== undefined;
+  const rendered = await renderer.render({ onProgress: reportProgress, markdownPath: exportPostPath,
+    outPath: workspacePaths.zotepadExportHtml, account, title: state.metadata.title,
+    customCss: standalone ? null : resolveConfigRelativePath(wxAccount?.customCss),
+    articleThemePath: articleTheme?.path, themeOverrides: standalone ? undefined : wxAccount?.theme });
+  return { html: rendered.html, photos, rendered, exportPostPath };
+}
+
+export interface FrozenArticleArtifacts {
+  manifest: ArtifactManifest;
+  manifestHash: string;
+  files: Record<string, string>;
+}
+
+/** 私有 manifest 是唯一文件白名单；确认发布只读已验证产物，不再导出或渲染。 */
+export async function readFrozenArticleArtifacts(manifestPath: string): Promise<{ html: string; photos: string[]; rendered?: undefined; exportPostPath: string }> {
+  const stored = JSON.parse(await readFile(manifestPath, "utf8")) as FrozenArticleArtifacts;
+  if (stored.manifestHash !== process.env.ZZHUB_PIPELINE_ARTIFACT_MANIFEST_HASH || stored.manifest.snapshotHash !== process.env.ZZHUB_PIPELINE_ARTICLE_SNAPSHOT_HASH) throw new Error("Frozen artifact identity does not match the confirmed job");
+  const manifest = validateArtifactManifest(stored.manifest, stored.manifestHash);
+  const root = dirname(resolve(manifestPath));
+  const bytes = new Map<string, Buffer>();
+  const paths = new Map<string, string>();
+  for (const artifact of manifest.artifacts) {
+    const name = stored.files[artifact.key];
+    if (!name || name.includes("/") || name.includes("\\") || name === "." || name === "..") throw new Error("Invalid private artifact file");
+    const path = join(root, name);
+    const data = await readFile(path);
+    if (data.byteLength !== artifact.byteLength || createHash("sha256").update(data).digest("hex") !== artifact.sha256) throw new Error("Frozen article artifact hash mismatch");
+    bytes.set(artifact.key, data); paths.set(artifact.key, path);
+  }
+  let html = bytes.get("article")!.toString("utf8");
+  html = await new HTMLRewriter().on("img", { element(element) {
+    const source = element.getAttribute("src") || "";
+    const id = /^asset:([a-f\d-]{36})$/.exec(source)?.[1];
+    const path = id ? paths.get(`media_${id}`) : undefined;
+    if (!path) throw new Error("Frozen HTML contains an unmanaged image");
+    element.setAttribute("src", path);
+    if (element.hasAttribute("data-src")) element.setAttribute("data-src", path);
+  } }).transform(new Response(html)).text();
+  return { html, photos: [paths.get("cover")!, ...manifest.artifacts.filter(artifact => artifact.kind === "media").map(artifact => paths.get(artifact.key)!)], exportPostPath: paths.get("article")! };
+}

package/src/providers/index.ts

@@ -3,17 +3,14 @@ import { createHash } from "node:crypto";
 import { readFile, writeFile } from "fs/promises";
 import { join } from "path";
 import {
-  resolveConfigRelativePath,
   type PipelineConfig,
   type ResolvedWorkspacePaths,
 } from "../config";
 import { PublishResult, RenderAsset, RoutePrimary, WorkflowState } from "../state";
 import {
-  injectIllustrationImages,
   prepareBodyForNewspic,
 } from "../text";
-import { resolveMarkdownRenderer } from "../adapter-loader";
-import { reportProgress } from "../monitor/recorder";
+import { exportWechatArticle, readFrozenArticleArtifacts } from "./article-export";
 import { publishBlogRoute } from "./blog";
 import { createWechatDraft, createWechatNewspic, extractImageUrls, mergePhotoLists } from "./wechat";
 
@@ -36,70 +33,22 @@ async function publishWechatArticleRoute({
   accountOverride,
   articleTheme,
 }: PublishRouteContext): Promise<PublishResult> {
-  const postPath = join(state.asset_path, "post.md");
-  let exportPostPath = postPath;
-  const cover = (state.images.render_assets as RenderAsset[]).find(
-    (asset) => asset.route === "wechat-article" && asset.kind === "cover",
-  );
-
-  const photos: string[] = [];
-  if (cover) {
-    photos.push(cover.path);
-  }
-  if (
-    state.images.body_inputs.scope === "article" &&
-    state.images.body_inputs.status === "ready"
-  ) {
-    const postContent = await readFile(postPath, "utf-8");
-    const draftContent = injectIllustrationImages(
-      postContent,
-      state.images.body_inputs.received,
-    );
-    exportPostPath = join(state.asset_path, "post-wechat-draft.md");
-    if (!dryRun) {
-      await writeFile(exportPostPath, draftContent, "utf-8");
-    }
-
-    for (const img of state.images.body_inputs.received) {
-      photos.push(img.path);
-    }
-  }
-
   const account = accountOverride || state.route.account;
-
   if (dryRun) {
-    console.error(`[dry-run] Zotepad export: ${exportPostPath}`);
-    console.error(`[dry-run] Wechat draft: ${state.metadata.title}`);
-    return {
-      route: "wechat-article",
-      account,
-      status: "skipped",
-      detail: "dry-run",
-      published_at: null,
-      content_version: state.artifacts.content_version,
-      render_version: state.artifacts.render_version,
-    };
+    return { route: "wechat-article", account, status: "skipped", detail: "dry-run", published_at: null,
+      content_version: state.artifacts.content_version, render_version: state.artifacts.render_version };
   }
 
   try {
-    const markdownRenderer = await resolveMarkdownRenderer(config);
-    const wxAccount = config.wx.accounts[account] ?? config.wx.accounts[config.wx.defaultAccount];
-    // 独立正文配置与发布账号的凭据、默认 CSS 分离。
-    const standalone = articleTheme?.manifest.css !== undefined;
-    const rendered = await markdownRenderer.render({
-      onProgress: reportProgress,
-      markdownPath: exportPostPath,
-      outPath: workspacePaths.zotepadExportHtml,
-      account,
-      title: state.metadata.title,
-      customCss: standalone ? null : resolveConfigRelativePath(wxAccount?.customCss),
-      articleThemePath: articleTheme?.path,
-      themeOverrides: standalone ? undefined : wxAccount?.theme,
-    });
-    const { html } = rendered;
+    if (process.env.ZZHUB_PIPELINE_PREVIEW_ONLY === "1") throw new Error("Preview operation cannot publish or upload WeChat images");
+    const frozenPath = process.env.ZZHUB_PIPELINE_ARTICLE_ARTIFACTS;
+    const prepared = frozenPath
+      ? await readFrozenArticleArtifacts(frozenPath)
+      : await exportWechatArticle({ state, config, workspacePaths, account, articleTheme });
+    const { html, photos, rendered, exportPostPath } = prepared;
 
     // Register with local preview server unless explicitly disabled.
-    if (process.env.ZZHUB_WECHAT_PREVIEW_ON_PUBLISH !== "0") {
+    if (rendered && process.env.ZZHUB_WECHAT_PREVIEW_ON_PUBLISH !== "0") {
       try {
         const { registerPreviewEntry } = await import("../wechat-preview/server");
         const registration = await registerPreviewEntry(
@@ -131,6 +80,7 @@ async function publishWechatArticleRoute({
       title: state.metadata.title,
       html,
       photos,
+      ...(frozenPath ? { explicitPhotos: true } : {}),
       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,

package/src/providers/wechat.ts

@@ -139,6 +139,8 @@ interface BaseWechatPublishInput {
 }
 
 export interface WechatDraftInput extends BaseWechatPublishInput {
+  /** 冻结产物已给出真实图片清单，禁止从代码文本再猜图片来源。 */
+  explicitPhotos?: boolean;
   html: string;
   existingDraftMediaId?: string | null;
 }
@@ -642,7 +644,7 @@ export function calculatePicCrop(width: number, height: number): { pic_crop_235_
 
 export async function createWechatDraft(input: WechatDraftInput): Promise<Record<string, unknown>> {
   const runtime = getWxRuntimeConfig(input.config, input.account);
-  const fallbackPhotos = extractImageUrls(input.html);
+  const fallbackPhotos = input.explicitPhotos ? [] : extractImageUrls(input.html);
   const photos = parsePhotos(input.photos);
   const finalPhotos = mergePhotoLists(photos, fallbackPhotos);
   if (finalPhotos.length === 0) {