feat: 将主题令牌接入 DOCX 动态模板

apps/desktop/scripts/verify-docx-theme-styles.mjs

@@ -3,6 +3,7 @@ import http from "node:http";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createApplicationService } from "@md-to-pdf/application";
+import { defaultExportConfig } from "@md-to-pdf/core";
 import {
   DOCX_STYLE_SLOT_NAMES,
   createDocxThemeStyleCaptureScript,
@@ -120,8 +121,17 @@ try {
   const tokenSets = [];
   for (const theme of bundledThemes) {
     console.error(`[Electron DOCX theme styles] capturing ${theme.id}`);
-    const themeCss = await application.getThemeCss(theme.id);
+    const prepared = await application.prepareDocxExport({
-    assert(themeCss !== undefined, `主题 ${theme.id} 缺少 CSS`);
+      markdown: `# ${theme.name}`,
+      fileName: `${theme.id}.md`,
+      language: "zh-CN",
+      exportConfig: {
+        ...defaultExportConfig,
+        themeId: theme.id
+      }
+    });
+    const themeCss = prepared.theme.css;
+    const manifest = prepared.theme.manifest;
     const themeFingerprint =
       await createDocxThemeStyleFingerprint(theme.id, themeCss);
     const request = {
@@ -150,7 +160,7 @@ try {
     tokenSets.push(
       resolveDocxThemeTokens({
         snapshot,
-        config: normalizeDocxThemeMappingConfig(theme)
+        config: normalizeDocxThemeMappingConfig(manifest)
       })
     );
   }

apps/desktop/src/desktop-application-controller.ts

@@ -17,6 +17,7 @@ import {
 import path from "node:path";
 import {
   DocxExportService,
+  DocxThemeTokenService,
   MAXIMUM_MARKDOWN_LENGTH,
   readDocxExportRuntimeLimits,
   type ApplicationService
@@ -159,6 +160,9 @@ export class DesktopApplicationController {
     const pandocRuntime = new PandocRuntime({
       desktopResourcesPath: options.desktopResourcesPath
     });
+    this.#docxMediaEngine = new ElectronDocxMediaEngine({
+      renderUrl: options.docxRenderUrl
+    });
     this.#docxExportService = new DocxExportService({
       application: this.#applicationService,
       runtime: pandocRuntime,
@@ -169,11 +173,11 @@ export class DesktopApplicationController {
           import.meta.url
         )
       }),
+      themeTokens: new DocxThemeTokenService(
+        this.#docxMediaEngine
+      ),
       limits: readDocxExportRuntimeLimits()
     });
-    this.#docxMediaEngine = new ElectronDocxMediaEngine({
-      renderUrl: options.docxRenderUrl
-    });
   }
 
   async initialize() {

apps/desktop/src/electron-docx-media-engine.ts

@@ -21,6 +21,7 @@ export interface ElectronDocxMediaEngineOptions {
 export class ElectronDocxMediaEngine
   implements DocxMediaCaptureAdapter, DocxThemeStyleCaptureAdapter
 {
+  readonly themeStyleBaseUrl: string;
   private readonly renderUrl: string;
   private windowPromise: Promise<BrowserWindow> | undefined;
   private queue = Promise.resolve();
@@ -28,6 +29,7 @@ export class ElectronDocxMediaEngine
 
   constructor(options: ElectronDocxMediaEngineOptions) {
     this.renderUrl = options.renderUrl;
+    this.themeStyleBaseUrl = this.renderUrl;
   }
 
   capture(

apps/server/scripts/verify-docx-theme-styles.mjs

@@ -3,12 +3,22 @@ import http from "node:http";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createApplicationService } from "@md-to-pdf/application";
+import {
+  DOCX_PANDOC_VERSION,
+  defaultExportConfig
+} from "@md-to-pdf/core";
 import {
   DOCX_STYLE_SLOT_NAMES,
   createDocxThemeStyleFingerprint,
   normalizeDocxThemeMappingConfig,
   resolveDocxThemeTokens
 } from "@md-to-pdf/docx-theme-engine";
+import {
+  PandocRuntime,
+  createDynamicReferenceDocx,
+  readReferenceDocxPackage,
+  resolveTokenFonts
+} from "@md-to-pdf/docx-engine";
 import { chromium } from "playwright";
 import { captureDocxThemeStyleWithPlaywrightPage } from "../dist/playwright-docx-theme-style.js";
 
@@ -19,6 +29,10 @@ const outputDirectory = path.join(
   "output",
   "docx-theme-styles"
 );
+const referenceDirectory = path.join(
+  outputDirectory,
+  "references"
+);
 
 function assert(condition, message) {
   if (!condition) {
@@ -26,6 +40,81 @@ function assert(condition, message) {
   }
 }
 
+function styleBlock(stylesXml, styleId) {
+  const escaped = styleId.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+  return stylesXml.match(
+    new RegExp(
+      `<w:style[^>]*w:styleId="${escaped}"[^>]*>[\\s\\S]*?<\\/w:style>`,
+      "u"
+    )
+  )?.[0];
+}
+
+function inspectReference(reference, tokens) {
+  const entries = readReferenceDocxPackage(reference.content).entries;
+  const stylesXml = new TextDecoder().decode(
+    entries.get("word/styles.xml")
+  );
+  const fontTableXml = new TextDecoder().decode(
+    entries.get("word/fontTable.xml")
+  );
+  const normal = styleBlock(stylesXml, "Normal");
+  const paragraph = tokens.slots.find(
+    (slot) => slot.slot === "paragraph"
+  )?.style;
+  assert(normal, `主题 ${tokens.themeId} 缺少 Normal 样式`);
+  const fonts = resolveTokenFonts(paragraph, {
+    latin: "Arial",
+    eastAsia: "SimSun"
+  });
+  if (paragraph?.fontCandidates.length) {
+    assert(
+      normal.includes(`w:ascii="${fonts.latin}"`),
+      `主题 ${tokens.themeId} 的 Latin 正文字体未写入模板`
+    );
+    assert(
+      normal.includes(`w:eastAsia="${fonts.eastAsia}"`),
+      `主题 ${tokens.themeId} 的东亚正文字体未写入模板`
+    );
+    assert(
+      fontTableXml.includes(`w:name="${fonts.eastAsia}"`),
+      `主题 ${tokens.themeId} 的东亚字体未写入字体表`
+    );
+  }
+  if (paragraph?.fontSizePt !== undefined) {
+    assert(
+      normal.includes(
+        `w:sz w:val="${Math.round(paragraph.fontSizePt * 2)}"`
+      ),
+      `主题 ${tokens.themeId} 的正文字号未写入模板`
+    );
+  }
+  for (const styleId of [
+    "Heading1",
+    "SourceCode",
+    "Table",
+    "MdOfficialTitle",
+    "MdBriefingTitle",
+    "MdProjectReportTitle",
+    "MdTenderTitle"
+  ]) {
+    assert(
+      stylesXml.includes(`w:styleId="${styleId}"`),
+      `主题 ${tokens.themeId} 缺少样式 ${styleId}`
+    );
+  }
+  return {
+    bytes: reference.content.byteLength,
+    templateFingerprint: reference.templateFingerprint,
+    cacheKey: reference.cacheKey,
+    stylePreset: reference.stylePreset,
+    partCount: reference.partCount,
+    paragraphFonts: fonts,
+    customStyleCount:
+      stylesXml.match(/w:styleId="Md[A-Za-z]+"/gu)?.length ?? 0
+  };
+}
+
 const application = createApplicationService({
   bundledRoot: path.join(repositoryDirectory, "themes"),
   localRoot: path.join(repositoryDirectory, ".local", "themes")
@@ -88,6 +177,20 @@ if (!address || typeof address === "string") {
 }
 const baseUrl = `http://127.0.0.1:${address.port}/`;
 const browser = await chromium.launch({ headless: true });
+const runtime = new PandocRuntime(
+  process.env.DOCX_PANDOC_PATH?.trim()
+    ? { configuredPath: process.env.DOCX_PANDOC_PATH.trim() }
+    : {}
+);
+const capability = await runtime.probe();
+if (capability.capability.status !== "available") {
+  throw new Error(capability.capability.message);
+}
+assert(
+  capability.capability.detectedVersion === DOCX_PANDOC_VERSION,
+  `Pandoc 版本不匹配：期望 ${DOCX_PANDOC_VERSION}，实际 ${capability.capability.detectedVersion}`
+);
+const baseline = await runtime.getDefaultReferenceDocx();
 
 try {
   const context = await browser.newContext({
@@ -104,10 +207,20 @@ try {
   );
   const snapshots = [];
   const tokenSets = [];
+  const references = [];
   for (const theme of bundledThemes) {
     console.error(`[DOCX theme styles] capturing ${theme.id}`);
-    const themeCss = await application.getThemeCss(theme.id);
+    const prepared = await application.prepareDocxExport({
-    assert(themeCss !== undefined, `主题 ${theme.id} 缺少 CSS`);
+      markdown: `# ${theme.name}`,
+      fileName: `${theme.id}.md`,
+      language: "zh-CN",
+      exportConfig: {
+        ...defaultExportConfig,
+        themeId: theme.id
+      }
+    });
+    const themeCss = prepared.theme.css;
+    const manifest = prepared.theme.manifest;
     const themeFingerprint =
       await createDocxThemeStyleFingerprint(theme.id, themeCss);
     const snapshot =
@@ -129,12 +242,27 @@ try {
         .join("、")}`
     );
     snapshots.push(snapshot);
-    tokenSets.push(
+    const tokens = resolveDocxThemeTokens({
-      resolveDocxThemeTokens({
+      snapshot,
-        snapshot,
+      config: normalizeDocxThemeMappingConfig(manifest)
-        config: normalizeDocxThemeMappingConfig(theme)
+    });
-      })
+    tokenSets.push(tokens);
+    const reference = createDynamicReferenceDocx(baseline, {
+      exportConfig: prepared.request.exportConfig,
+      theme: manifest,
+      fileName: prepared.request.fileName,
+      metadata: prepared.document.metadata,
+      themeTokens: tokens
+    });
+    fs.mkdirSync(referenceDirectory, { recursive: true });
+    fs.writeFileSync(
+      path.join(referenceDirectory, `${theme.id}.docx`),
+      reference.content
     );
+    references.push({
+      themeId: theme.id,
+      ...inspectReference(reference, tokens)
+    });
   }
   assert(
     snapshots.length === 14,
@@ -172,7 +300,9 @@ try {
         themeCount: snapshots.length,
         slotCount: DOCX_STYLE_SLOT_NAMES.length,
         snapshots,
-        tokenSets
+        tokenSets,
+        pandocVersion: capability.capability.detectedVersion,
+        references
       },
       null,
       2
@@ -190,7 +320,9 @@ try {
       diagnostics: tokenSets.reduce(
         (count, tokens) => count + tokens.diagnostics.length,
         0
-      )
+      ),
+      pandocVersion: capability.capability.detectedVersion,
+      references: references.length
     })
   );
   await context.close();

apps/server/src/app.ts

@@ -14,6 +14,7 @@ import {
   ApplicationRequestError,
   DocxExportService,
   DocxExportServiceError,
+  DocxThemeTokenService,
   createApplicationService,
   readDocxExportRuntimeLimits,
   type ApplicationService
@@ -133,6 +134,7 @@ function createDocxServerTiming(
     `queue;dur=${milliseconds(timings.queueMs)}`,
     `runtime-probe;dur=${milliseconds(timings.probeMs)}`,
     `prepare;dur=${milliseconds(timings.prepareMs)}`,
+    `theme-style;dur=${milliseconds(timings.themeStyleMs)}`,
     `media;dur=${milliseconds(timings.mediaMs)}`,
     `reference;dur=${milliseconds(timings.referenceMs)}`,
     `pandoc;dur=${milliseconds(timings.pandocMs)}`,
@@ -166,6 +168,8 @@ export function buildApp(options: BuildAppOptions = {}) {
   const pandocRuntime = options.docxExportService
     ? undefined
     : new PandocRuntime();
+  const docxMediaAdapter =
+    options.docxMediaAdapter ?? createDocxMediaEngine();
   const docxExportService =
     options.docxExportService ??
     new DocxExportService({
@@ -174,10 +178,11 @@ export function buildApp(options: BuildAppOptions = {}) {
       converter: new PandocDocxConverter({
         runtime: pandocRuntime!
       }),
+      themeTokens: new DocxThemeTokenService(
+        docxMediaAdapter
+      ),
       limits: readDocxExportRuntimeLimits()
     });
-  const docxMediaAdapter =
-    options.docxMediaAdapter ?? createDocxMediaEngine();
 
   if (options.prewarmPdfBrowser) {
     app.addHook("onReady", async () => {

apps/server/src/docx-media-engine.ts

@@ -38,6 +38,7 @@ async function closeContext(context: BrowserContext) {
 export class PlaywrightDocxMediaEngine
   implements ServerDocxMediaCaptureAdapter
 {
+  readonly themeStyleBaseUrl: string;
   private readonly renderOrigin: string;
   private readonly renderUrl: string;
   private readonly launchBrowser: () => Promise<Browser>;
@@ -54,6 +55,7 @@ export class PlaywrightDocxMediaEngine
       "/preview-frame.html?target=continuous",
       this.renderOrigin
     ).href;
+    this.themeStyleBaseUrl = this.renderUrl;
     this.launchBrowser =
       options.launchBrowser ??
       (() =>

apps/server/tests/docx-api.test.ts

@@ -42,11 +42,12 @@ function generatedDocx(): DocxExportResult {
       queueMs: 1,
       probeMs: 2,
       prepareMs: 3,
-      mediaMs: 4,
+      themeStyleMs: 4,
-      referenceMs: 5,
+      mediaMs: 5,
-      pandocMs: 6,
+      referenceMs: 6,
-      validationMs: 7,
+      pandocMs: 7,
-      totalMs: 28
+      validationMs: 8,
+      totalMs: 36
     }
   };
 }
@@ -72,6 +73,8 @@ function createDocxService(
 
 function createMediaAdapter() {
   return {
+    themeStyleBaseUrl:
+      "http://localhost:5173/preview-frame.html",
     capture: vi.fn<
       DocxMediaCaptureAdapter["capture"]
     >(async () => ({
@@ -82,6 +85,9 @@ function createMediaAdapter() {
       },
       captures: []
     })),
+    captureThemeStyle: vi.fn(async () => {
+      throw new Error("此测试使用注入的 DOCX 导出服务");
+    }),
     close: vi.fn(async () => undefined)
   } satisfies ServerDocxMediaCaptureAdapter;
 }
@@ -173,7 +179,7 @@ describe("DOCX HTTP API", () => {
       "runtime-probe;dur=2.0"
     );
     expect(response.headers["server-timing"]).toContain(
-      "pandoc;dur=6.0"
+      "pandoc;dur=7.0"
     );
     expect(response.rawPayload).toEqual(
       Buffer.from([80, 75, 3, 4])

apps/web/tests/docx-export.test.ts

@@ -133,6 +133,7 @@ describe("DOCX 导出客户端", () => {
         queueMs: 0,
         probeMs: 0,
         prepareMs: 0,
+        themeStyleMs: 0,
         mediaMs: 0,
         referenceMs: 0,
         pandocMs: 0,

docs/PROGRESS.md

@@ -193,6 +193,20 @@ Front Matter 和正文首个 H1 构建主题无关的语义树，再由 Renderer
 `reference.docx` 或最终 DOCX；下一步阶段 12B 将把已归一化的主题令牌
 接入动态 Word 模板。
 
+`v0.6.0` 阶段 12B 已将主题令牌接入真实 DOCX 生产链。应用层现在复用
+Server Playwright 与 Desktop Electron 适配器，按主题 CSS SHA-256
+指纹缓存计算样式快照，并与媒体捕获并行生成 56 槽位令牌；`explicit`
+模式直接使用清单覆盖与预设降级，无需启动浏览器。完整令牌进入 Pandoc
+转换输入和动态模板缓存键，主题变化不会复用旧模板；诊断进入导出警告，
+并新增 `themeStyleMs` 耗时。DOCX 引擎通过固定槽位映射写入标准 Markdown
+样式和 31 个 `Md*` 结构样式，同时覆盖字体、字号、颜色、段落、代码、
+引用、表格、图注、链接、字体表与 Office 主题字体，全程不按主题 ID
+分支。Playwright Chromium 151 与 Electron Chromium 150 对 14 套主题
+各采集 784 个槽位，完整令牌差异为 0；固定 Pandoc 3.9.0.2 的默认模板
+成功生成并验证 14 份动态 `reference.docx`，每份均含 31 个结构样式。
+当前结构样式尚未绑定到 Pandoc AST，封面、版头、分节与标题去重留给
+阶段 12C。
+
 ## 2. 已完成
 
 ### 2.1 项目骨架
@@ -1124,7 +1138,8 @@ ECharts 第二阶段浏览器与 PDF 验证结果：
   近似诊断已通过 14 主题双引擎矩阵；下一步由统一语义文档模型消费令牌；
 - 阶段 12A：已建立独立统一语义文档模型，Renderer 与 DOCX 准备结果
   共用同一语义树，现有 HTML DOM 保持兼容；
-- 阶段 12B：将主题令牌接入动态 `reference.docx`；
+- 阶段 12B：已将跨端主题令牌接入动态 `reference.docx`，14 主题双引擎
+  令牌和真实 Pandoc 模板矩阵通过；
 - 阶段 12C：完成 Pandoc 结构映射、封面分节、标题去重、表格宽度和
   分页控制；
 - 阶段 12D：完成 14 套主题的真实 Word/WPS 视觉与结构回归；

package-lock.json

@@ -9916,6 +9916,7 @@
       "dependencies": {
         "@md-to-pdf/core": "0.1.0",
         "@md-to-pdf/docx-engine": "0.1.0",
+        "@md-to-pdf/docx-theme-engine": "0.1.0",
         "@md-to-pdf/renderer": "0.1.0"
       },
       "devDependencies": {
@@ -9938,6 +9939,7 @@
       "version": "0.1.0",
       "dependencies": {
         "@md-to-pdf/core": "0.1.0",
+        "@md-to-pdf/docx-theme-engine": "0.1.0",
         "@xmldom/xmldom": "0.9.10",
         "fflate": "0.8.3"
       },

package.json

@@ -30,7 +30,7 @@
     "verify:docx-conversion": "npm run build -w @md-to-pdf/core && npm run build -w @md-to-pdf/docx-engine && npm run verify:conversion -w @md-to-pdf/docx-engine",
     "verify:docx-matrix": "npm run build -w @md-to-pdf/core && npm run build -w @md-to-pdf/docx-engine && npm run verify:acceptance -w @md-to-pdf/docx-engine",
     "verify:docx-themes": "npm run build:web-runtime && npm run verify:themes -w @md-to-pdf/docx-engine",
-    "verify:docx-theme-styles": "npm run build -w @md-to-pdf/core && npm run build -w @md-to-pdf/semantic-document && npm run build -w @md-to-pdf/docx-theme-engine && npm run build -w @md-to-pdf/renderer && npm run build -w @md-to-pdf/application && npm run build -w @md-to-pdf/server && npm run verify:docx-theme-styles -w @md-to-pdf/server && npm run verify:docx-theme-styles -w @md-to-pdf/desktop",
+    "verify:docx-theme-styles": "npm run build -w @md-to-pdf/core && npm run build -w @md-to-pdf/semantic-document && npm run build -w @md-to-pdf/docx-theme-engine && npm run build -w @md-to-pdf/docx-engine && npm run build -w @md-to-pdf/renderer && npm run build -w @md-to-pdf/application && npm run build -w @md-to-pdf/server && npm run verify:docx-theme-styles -w @md-to-pdf/server && npm run verify:docx-theme-styles -w @md-to-pdf/desktop",
     "verify:docx-acceptance": "npm run build:web-runtime && npm run build -w @md-to-pdf/server && npm run build -w @md-to-pdf/desktop && npm run verify:pandoc -w @md-to-pdf/docx-engine && npm run verify:conversion -w @md-to-pdf/docx-engine && npm run verify:acceptance -w @md-to-pdf/docx-engine && npm run verify:docx-http -w @md-to-pdf/server && npm run test -w @md-to-pdf/desktop -- desktop-docx-save.test.ts",
     "verify:docx-http": "npm run build:web-runtime && npm run build -w @md-to-pdf/server && npm run verify:docx-http -w @md-to-pdf/server",
     "test": "npm run test -w @md-to-pdf/markdown-echarts && npm run test -w @md-to-pdf/core && npm run build -w @md-to-pdf/core && npm run test -w @md-to-pdf/semantic-document && npm run build -w @md-to-pdf/semantic-document && npm run test -w @md-to-pdf/docx-theme-engine && npm run test -w @md-to-pdf/docx-engine && npm run test -w @md-to-pdf/renderer && npm run test -w @md-to-pdf/application && npm run build -w @md-to-pdf/application && npm run test -w @md-to-pdf/preview-engine && npm run build -w @md-to-pdf/preview-engine && npm run test -w @md-to-pdf/web && npm run test -w @md-to-pdf/server && npm run test -w @md-to-pdf/desktop",

packages/application/README.md

@@ -13,6 +13,7 @@ src/
   application-service.ts  渲染、主题和资源用例入口
   docx-export-service.ts  DOCX 并发、超时、错误和完整导出编排
   docx-media-service.ts   DOCX 媒体尺寸计算、PNG 校验与清单组装
+  docx-theme-token-service.ts 主题指纹、快照缓存和 Word 令牌准备
   image-resources.ts      本地、Base64 与受限远程图片处理
   theme-registry.ts       内置及自定义主题扫描、校验与缓存
   index.ts                公共导出入口
@@ -21,6 +22,7 @@ tests/
   bundled-themes.test.ts
   docx-export-service.test.ts
   docx-media-service.test.ts
+  docx-theme-token-service.test.ts
   image-resources.test.ts
 ```
 
@@ -56,10 +58,14 @@ Desktop 才会以 Markdown 所在目录为边界解析相对资源。
 大小、总大小和媒体 ID。最终按文档顺序输出稳定的 `media-001.png`
 清单；它不依赖 Playwright 或 Electron，平台代码只负责 Chromium 捕获。
 
-`DocxExportService` 串联 capability 探测、请求准备、平台媒体捕获、
+`DocxThemeTokenService` 复用 Server Playwright 或 Desktop Electron
-Pandoc 转换和最终 OOXML 校验。默认并发为 1、队列为 4、总超时为 90 秒；
+适配器采集主题计算样式，按主题 CSS 指纹缓存快照并生成 56 槽位令牌。
+`explicit` 模式不启动浏览器，直接使用清单覆盖和预设降级。
+
+`DocxExportService` 串联 capability 探测、请求准备、平台媒体捕获、主题
+令牌准备、Pandoc 转换和最终 OOXML 校验。媒体与主题令牌并行准备。默认并发为 1、队列为 4、总超时为 90 秒；
 可以通过 `DOCX_CONCURRENCY`、`DOCX_MAX_QUEUE` 和 `DOCX_TIMEOUT_MS`
-配置。排队、探测、准备、媒体、模板、Pandoc、校验和总耗时使用共享协议
+配置。排队、探测、准备、主题样式、媒体、模板、Pandoc、校验和总耗时使用共享协议
 返回；关闭服务时会取消活动任务、拒绝排队任务并等待清理完成。
 
 内置主题来自仓库 `themes/`，当前名称为 Typora Github、

packages/application/package.json

@@ -23,6 +23,7 @@
   "dependencies": {
     "@md-to-pdf/core": "0.1.0",
     "@md-to-pdf/docx-engine": "0.1.0",
+    "@md-to-pdf/docx-theme-engine": "0.1.0",
     "@md-to-pdf/renderer": "0.1.0"
   },
   "devDependencies": {

packages/application/src/docx-export-service.ts

@@ -20,6 +20,10 @@ import {
   prepareDocxMedia,
   type DocxMediaCaptureAdapter
 } from "./docx-media-service.js";
+import type {
+  DocxThemeTokenProvider,
+  PreparedDocxThemeTokens
+} from "./docx-theme-token-service.js";
 import type { ImageResolutionContext } from "./image-resources.js";
 
 const DEFAULT_DOCX_CONCURRENCY = 1;
@@ -47,6 +51,7 @@ export interface DocxExportServiceOptions {
   application: Pick<ApplicationService, "prepareDocxExport">;
   runtime: DocxCapabilityProvider;
   converter: DocxConversionPort;
+  themeTokens: DocxThemeTokenProvider;
   limits?: Partial<DocxExportRuntimeLimits>;
 }
 
@@ -359,24 +364,51 @@ export class DocxExportService {
         const prepareMs = performance.now() - prepareStarted;
         controller.signal.throwIfAborted();
 
-        const mediaStarted = performance.now();
+        let themeStyleMs = 0;
-        const media = await prepareDocxMedia(
+        let mediaMs = 0;
-          prepared,
+        const [themeTokens, media] = await Promise.all([
-          options.mediaAdapter,
+          (async () => {
-          controller.signal
+            const started = performance.now();
-        );
+            try {
-        const mediaMs = performance.now() - mediaStarted;
+              return await this.options.themeTokens.prepare(
+                prepared,
+                controller.signal
+              );
+            } finally {
+              themeStyleMs = performance.now() - started;
+            }
+          })(),
+          (async () => {
+            const started = performance.now();
+            try {
+              return await prepareDocxMedia(
+                prepared,
+                options.mediaAdapter,
+                controller.signal
+              );
+            } finally {
+              mediaMs = performance.now() - started;
+            }
+          })()
+        ]);
         controller.signal.throwIfAborted();
 
         const conversion = await this.options.converter.convert(
-          this.createConversionInput(prepared, media),
+          this.createConversionInput(
+            prepared,
+            themeTokens,
+            media
+          ),
           controller.signal
         );
         return {
           docx: conversion.docx,
           fileName: createDocxFileName(prepared.request.fileName),
           diagnostics: {
-            warnings: media.warnings,
+            warnings: [
+              ...media.warnings,
+              ...themeTokens.warnings
+            ],
             echartsErrors: media.echartsErrors,
             mermaidErrors: media.mermaidErrors
           },
@@ -384,6 +416,7 @@ export class DocxExportService {
             queueMs,
             probeMs,
             prepareMs,
+            themeStyleMs,
             mediaMs,
             referenceMs: conversion.timings.referenceMs,
             pandocMs: conversion.timings.pandocMs,
@@ -446,6 +479,7 @@ export class DocxExportService {
 
   private createConversionInput(
     prepared: PreparedDocxExport,
+    themeTokens: PreparedDocxThemeTokens,
     media: Awaited<ReturnType<typeof prepareDocxMedia>>
   ): PandocDocxConversionInput {
     return {
@@ -454,6 +488,7 @@ export class DocxExportService {
       language: prepared.request.language,
       exportConfig: prepared.request.exportConfig,
       theme: prepared.theme.manifest,
+      themeTokens: themeTokens.tokens,
       metadata: prepared.document.metadata,
       media
     };

packages/application/src/docx-theme-token-service.ts

@@ -0,0 +1,105 @@
+import type {
+  DocxThemeTokenSet,
+  DocxThemeStyleCaptureAdapter
+} from "@md-to-pdf/docx-theme-engine";
+import {
+  DOCX_STYLE_SLOTS,
+  DocxThemeStyleSnapshotCache,
+  createDocxThemeStyleFingerprint,
+  normalizeDocxThemeMappingConfig,
+  resolveDocxThemeTokens,
+  type DocxThemeStyleSnapshot
+} from "@md-to-pdf/docx-theme-engine";
+import type { PreparedDocxExport } from "./application-service.js";
+
+export interface PreparedDocxThemeTokens {
+  tokens: DocxThemeTokenSet;
+  warnings: string[];
+}
+
+export interface DocxThemeTokenProvider {
+  prepare(
+    prepared: PreparedDocxExport,
+    signal?: AbortSignal
+  ): Promise<PreparedDocxThemeTokens>;
+}
+
+function createExplicitSnapshot(
+  themeId: string,
+  themeFingerprint: string
+): DocxThemeStyleSnapshot {
+  return {
+    schemaVersion: 1,
+    themeId,
+    themeFingerprint,
+    viewport: {
+      widthPx: 794,
+      heightPx: 1123,
+      deviceScaleFactor: 1
+    },
+    rootFontSizePx: 16,
+    slots: DOCX_STYLE_SLOTS.map(({ name }) => ({
+      slot: name,
+      matched: false
+    }))
+  };
+}
+
+export class DocxThemeTokenService
+  implements DocxThemeTokenProvider
+{
+  private readonly snapshots: DocxThemeStyleSnapshotCache;
+
+  constructor(
+    private readonly adapter: DocxThemeStyleCaptureAdapter
+  ) {
+    this.snapshots = new DocxThemeStyleSnapshotCache(adapter);
+  }
+
+  async prepare(
+    prepared: PreparedDocxExport,
+    signal?: AbortSignal
+  ): Promise<PreparedDocxThemeTokens> {
+    signal?.throwIfAborted();
+    const config = normalizeDocxThemeMappingConfig(
+      prepared.theme.manifest
+    );
+    const themeFingerprint =
+      await createDocxThemeStyleFingerprint(
+        prepared.theme.manifest.id,
+        prepared.theme.css
+      );
+    signal?.throwIfAborted();
+    const snapshot =
+      config.mode === "explicit"
+        ? createExplicitSnapshot(
+            prepared.theme.manifest.id,
+            themeFingerprint
+          )
+        : await this.snapshots.capture(
+            {
+              themeId: prepared.theme.manifest.id,
+              themeFingerprint,
+              themeCss: prepared.theme.css,
+              baseUrl: this.adapter.themeStyleBaseUrl
+            },
+            signal
+          );
+    const tokens = resolveDocxThemeTokens({
+      snapshot,
+      config
+    });
+    return {
+      tokens,
+      warnings: tokens.diagnostics
+        .filter(
+          (diagnostic) => diagnostic.severity !== "info"
+        )
+        .map((diagnostic) => diagnostic.message)
+    };
+  }
+
+  invalidate(themeId?: string) {
+    this.snapshots.invalidate(themeId);
+  }
+}

packages/application/src/index.ts

@@ -30,6 +30,11 @@ export {
   type DocxMediaCaptureRequest,
   type DocxMediaRenderDimensions
 } from "./docx-media-service.js";
+export {
+  DocxThemeTokenService,
+  type DocxThemeTokenProvider,
+  type PreparedDocxThemeTokens
+} from "./docx-theme-token-service.js";
 export {
   DocxExportService,
   DocxExportServiceError,

packages/application/tests/docx-export-service.test.ts

@@ -10,6 +10,7 @@ import type {
   PandocDocxConversionResult,
   PandocRuntimeResolution
 } from "@md-to-pdf/docx-engine";
+import type { DocxThemeTokenSet } from "@md-to-pdf/docx-theme-engine";
 import {
   DocxExportService,
   readDocxExportRuntimeLimits,
@@ -84,6 +85,16 @@ const availableCapability: DocxCapability = {
   detectedVersion: "3.9.0.2"
 };
 
+const themeTokens: DocxThemeTokenSet = {
+  schemaVersion: 1,
+  themeId: "test-theme",
+  themeFingerprint: "c".repeat(64),
+  mode: "auto-with-overrides",
+  basePreset: "technical",
+  slots: [],
+  diagnostics: []
+};
+
 function resolution(
   capability: DocxCapability = availableCapability
 ): PandocRuntimeResolution {
@@ -151,13 +162,22 @@ function createService(options: {
         options.convert ??
         vi.fn().mockResolvedValue(conversionResult())
     },
+    themeTokens: {
+      prepare: vi.fn().mockResolvedValue({
+        tokens: themeTokens,
+        warnings: []
+      })
+    },
     limits: options.limits
   });
 }
 
 describe("DOCX 共享导出服务", () => {
   it("串联准备、媒体和转换并返回完整耗时", async () => {
-    const service = createService({});
+    const convert = vi
+      .fn()
+      .mockResolvedValue(conversionResult());
+    const service = createService({ convert });
     const result = await service.generate(
       { markdown: "# 测试" },
       { mediaAdapter: emptyAdapter }
@@ -170,7 +190,14 @@ describe("DOCX 共享导出服务", () => {
       echartsErrors: [],
       mermaidErrors: []
     });
+    expect(convert).toHaveBeenCalledWith(
+      expect.objectContaining({
+        themeTokens
+      }),
+      expect.any(AbortSignal)
+    );
     expect(result.timings).toMatchObject({
+      themeStyleMs: expect.any(Number),
       referenceMs: 3,
       pandocMs: 4,
       validationMs: 5

packages/application/tests/docx-theme-token-service.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  defaultExportConfig,
+  type ThemeManifest
+} from "@md-to-pdf/core";
+import {
+  DOCX_STYLE_SLOTS,
+  type DocxThemeStyleCaptureAdapter
+} from "@md-to-pdf/docx-theme-engine";
+import {
+  DocxThemeTokenService,
+  type PreparedDocxExport
+} from "../src/index.js";
+
+function manifest(
+  docxStyle: ThemeManifest["docxStyle"] = {
+    mode: "auto",
+    basePreset: "technical"
+  }
+): ThemeManifest {
+  return {
+    manifestVersion: 1,
+    id: "test-theme",
+    name: "测试主题",
+    version: "1.0.0",
+    description: "测试",
+    author: "测试",
+    license: "内部许可",
+    entry: "theme.css",
+    domPreset: "generic",
+    defaultFontSize: "16px",
+    supportedFeatures: [],
+    category: "general",
+    compatibleProfiles: [],
+    docxStyle,
+    bundled: true
+  };
+}
+
+function prepared(
+  docxStyle?: ThemeManifest["docxStyle"]
+): PreparedDocxExport {
+  return {
+    request: {
+      markdown: "# 测试",
+      fileName: "测试.md",
+      language: "zh-CN",
+      resources: [],
+      exportConfig: {
+        ...defaultExportConfig,
+        themeId: "test-theme"
+      }
+    },
+    document: {
+      rendererVersion: 1,
+      articleHtml:
+        '<article id="write"><h1>测试</h1></article>',
+      bodyHtml: "<h1>测试</h1>",
+      metadata: {
+        title: "测试",
+        author: "",
+        subject: "",
+        keywords: [],
+        language: "zh-CN"
+      },
+      semanticDocument: {
+        schemaVersion: 1,
+        titlePolicy: {
+          metadataTitle: "suppress",
+          firstBodyHeading: "keep"
+        },
+        regions: []
+      },
+      features: [],
+      warnings: []
+    },
+    theme: {
+      manifest: manifest(docxStyle),
+      source: "bundled",
+      css: "#write { font-family: Test; }"
+    }
+  };
+}
+
+function adapter(): DocxThemeStyleCaptureAdapter {
+  return {
+    themeStyleBaseUrl:
+      "http://localhost:5173/preview-frame.html",
+    captureThemeStyle: vi.fn(async (request) => ({
+      schemaVersion: 1,
+      themeId: request.themeId,
+      themeFingerprint: request.themeFingerprint,
+      viewport: {
+        widthPx: 794,
+        heightPx: 1123,
+        deviceScaleFactor: 1
+      },
+      rootFontSizePx: 16,
+      slots: DOCX_STYLE_SLOTS.map(({ name }) => ({
+        slot: name,
+        matched: false
+      }))
+    }))
+  };
+}
+
+describe("DOCX 主题令牌准备服务", () => {
+  it("按主题指纹缓存跨端样式快照", async () => {
+    const captureAdapter = adapter();
+    const service = new DocxThemeTokenService(captureAdapter);
+
+    const first = await service.prepare(prepared());
+    const second = await service.prepare(prepared());
+
+    expect(captureAdapter.captureThemeStyle).toHaveBeenCalledTimes(1);
+    expect(first.tokens).toEqual(second.tokens);
+    expect(first.tokens.themeId).toBe("test-theme");
+    expect(first.tokens.themeFingerprint).toMatch(/^[a-f0-9]{64}$/u);
+    expect(first.tokens.slots).toHaveLength(DOCX_STYLE_SLOTS.length);
+  });
+
+  it("显式模式跳过浏览器采集并只产生信息级降级诊断", async () => {
+    const captureAdapter = adapter();
+    const service = new DocxThemeTokenService(captureAdapter);
+
+    const result = await service.prepare(
+      prepared({
+        mode: "explicit",
+        basePreset: "technical"
+      })
+    );
+
+    expect(captureAdapter.captureThemeStyle).not.toHaveBeenCalled();
+    expect(result.tokens.mode).toBe("explicit");
+    expect(result.warnings).toEqual([]);
+    expect(
+      result.tokens.diagnostics.every(
+        (diagnostic) => diagnostic.severity === "info"
+      )
+    ).toBe(true);
+  });
+});

packages/core/src/docx.ts

@@ -187,6 +187,7 @@ export interface DocxGenerationTimings {
   queueMs: number;
   probeMs: number;
   prepareMs: number;
+  themeStyleMs: number;
   mediaMs: number;
   referenceMs: number;
   pandocMs: number;

packages/docx-engine/README.md

@@ -1,8 +1,8 @@
 # @md-to-pdf/docx-engine
 
 纯 Node.js 的 DOCX 模板和 Pandoc 编排核心。当前阶段负责读取固定 Pandoc
-版本的默认 `reference.docx`、验证 ZIP 安全边界，将主题 DOCX 样式声明
+版本的默认 `reference.docx`、验证 ZIP 安全边界，将归一化主题令牌和
-解析为完整样式预设，并生成纸张、页边距、字体、段落、代码、表格、
+兼容样式预设映射为 Word 样式，并生成纸张、页边距、字体、段落、代码、表格、
 页眉、页脚和页码均已映射的动态模板。Pandoc 转换器通过静态 Lua Filter
 将普通图片、Mermaid 和 ECharts 节点替换为受控 PNG，同时保留 Markdown
 正文、标题、列表、表格、代码和公式的可编辑文档结构。
@@ -12,7 +12,9 @@
 - 不依赖 Fastify、Electron 或浏览器 UI；
 - ZIP 使用纯 JavaScript `fflate`；
 - OOXML 使用 `@xmldom/xmldom`，不拼接未经转义的用户 XML；
-- 不解析任意主题 CSS，主题通过 `docxStyle` 提供受限结构化覆盖；
+- 不解析任意主题 CSS，只消费 `@md-to-pdf/docx-theme-engine` 的受限
+  语义令牌；`docxStyle` 预设在槽位缺失时提供兼容降级；
+- 槽位只映射到稳定的标准或 `Md*` Word 样式，不包含主题 ID 分支；
 - 生成结果会复验全部 XML、包内关系、内容类型、最终节和关键样式；
 - 每次转换使用独立临时目录、隔离 Pandoc data 目录并在 `finally` 清理；
 - 媒体映射检查顺序、PNG、像素、单图/总大小和物理显示尺寸；
@@ -37,6 +39,7 @@ npm run build -w @md-to-pdf/docx-engine
 npm run verify:docx-reference
 npm run verify:docx-conversion
 npm run verify:docx-acceptance
+npm run verify:docx-theme-styles
 ```
 
 `verify:docx-reference` 要求本机 `PATH` 中存在 Pandoc 3.9.0.2，也可以通过
@@ -51,3 +54,8 @@ npm run verify:docx-acceptance
 `output/docx-acceptance/`，供 Word/WPS 互操作验收使用。根级命令还会
 依次执行动态模板、媒体转换、Server HTTP 和 Desktop 原生保存验收；
 仅需重跑三配置矩阵时可使用 `npm run verify:docx-matrix`。
+
+`verify:docx-theme-styles` 使用 Playwright 与 Electron 分别采集 14 套
+内置主题的 56 个槽位，检查跨引擎令牌一致性，并使用固定 Pandoc 默认
+模板生成 14 份动态 `reference.docx`。模板矩阵检查标准 Markdown 样式、
+结构化 `Md*` 样式、正文字体、字号、字体表和缓存指纹。

packages/docx-engine/package.json

@@ -27,6 +27,7 @@
   },
   "dependencies": {
     "@md-to-pdf/core": "0.1.0",
+    "@md-to-pdf/docx-theme-engine": "0.1.0",
     "@xmldom/xmldom": "0.9.10",
     "fflate": "0.8.3"
   },

packages/docx-engine/src/index.ts

@@ -12,4 +12,5 @@ export * from "./reference-package.js";
 export * from "./section-transform.js";
 export * from "./style-presets.js";
 export * from "./styles-transform.js";
+export * from "./token-style-map.js";
 export * from "./validator.js";

packages/docx-engine/src/pandoc-converter.ts

@@ -17,6 +17,7 @@ import {
   type PreparedDocxMedia,
   type ThemeManifest
 } from "@md-to-pdf/core";
+import type { DocxThemeTokenSet } from "@md-to-pdf/docx-theme-engine";
 import {
   createDynamicReferenceCacheKey,
   createDynamicReferenceDocx,
@@ -57,6 +58,7 @@ export interface PandocDocxConversionInput {
   language: string;
   exportConfig: ExportConfig;
   theme: ThemeManifest;
+  themeTokens: DocxThemeTokenSet;
   metadata: MarkdownDocumentMetadata;
   media: PreparedDocxMedia;
 }
@@ -133,6 +135,7 @@ function referenceOptions(
   return {
     exportConfig: input.exportConfig,
     theme: input.theme,
+    themeTokens: input.themeTokens,
     fileName: input.fileName,
     metadata: {
       title: input.metadata.title,

packages/docx-engine/src/reference-builder.ts

@@ -23,6 +23,10 @@ import {
   transformStylesXml,
   transformThemeFontsXml
 } from "./styles-transform.js";
+import {
+  createDocxTokenSlotMap,
+  resolveTokenFonts
+} from "./token-style-map.js";
 import { resolveDocxThemeStyle } from "./style-presets.js";
 import { validateDynamicReferenceDocx } from "./validator.js";
 
@@ -67,6 +71,7 @@ export function createDynamicReferenceCacheKey(
           docxStyle: options.theme.docxStyle,
           pageDefaults: options.theme.pageDefaults
         },
+        themeTokens: options.themeTokens,
         paper: options.exportConfig.paper,
         pageDecorationsMode:
           options.exportConfig.pageDecorationsMode,
@@ -85,29 +90,46 @@ export function createDynamicReferenceDocx(
 ): DynamicReferenceDocxResult {
   const reference = readReferenceDocxPackage(baseline);
   const style = resolveDocxThemeStyle(options.theme);
+  const tokenSlots = options.themeTokens
+    ? createDocxTokenSlotMap(options.themeTokens)
+    : undefined;
+  const bodyFonts = resolveTokenFonts(
+    tokenSlots?.get("paragraph")?.style ??
+      tokenSlots?.get("document")?.style,
+    style.body.fonts
+  );
   const page = resolveReferencePageOptions(options);
   const withDecorations = createHeaderFooterParts(
     reference.entries,
     options,
     page.header,
     page.footer,
-    style.body.fonts.eastAsia,
+    bodyFonts.eastAsia,
     page.dimensions.width - page.margins.left - page.margins.right
   );
   const entries = withDecorations.entries;
   entries.set(
     "word/styles.xml",
-    transformStylesXml(entries.get("word/styles.xml")!, style)
+    transformStylesXml(
+      entries.get("word/styles.xml")!,
+      style,
+      options.themeTokens
+    )
   );
   entries.set(
     "word/fontTable.xml",
-    transformFontTableXml(entries.get("word/fontTable.xml")!, style)
+    transformFontTableXml(
+      entries.get("word/fontTable.xml")!,
+      style,
+      options.themeTokens
+    )
   );
   entries.set(
     "word/theme/theme1.xml",
     transformThemeFontsXml(
       entries.get("word/theme/theme1.xml")!,
-      style
+      style,
+      options.themeTokens
     )
   );
   entries.set(

packages/docx-engine/src/reference-options.ts

@@ -7,12 +7,14 @@ import {
   type MarkdownDocumentMetadata,
   type ThemeManifest
 } from "@md-to-pdf/core";
+import type { DocxThemeTokenSet } from "@md-to-pdf/docx-theme-engine";
 
 export interface DynamicReferenceDocxOptions {
   exportConfig: ExportConfig;
   theme: ThemeManifest;
   fileName: string;
   metadata: Pick<MarkdownDocumentMetadata, "title" | "author">;
+  themeTokens?: DocxThemeTokenSet;
 }
 
 export function resolveReferencePageOptions(

packages/docx-engine/src/styles-transform.ts

@@ -1,5 +1,16 @@
 import type { DocxFontFamily } from "@md-to-pdf/core";
+import type {
+  DocxSlotStyleToken,
+  DocxStyleSlotName,
+  DocxThemeTokenSet
+} from "@md-to-pdf/docx-theme-engine";
 import type { ResolvedDocxThemeStyle } from "./style-presets.js";
+import {
+  DOCX_SLOT_WORD_STYLE_BINDINGS,
+  collectDocxTokenFonts,
+  createDocxTokenSlotMap,
+  resolveTokenFonts
+} from "./token-style-map.js";
 import {
   DRAWING_NAMESPACE,
   WORD_NAMESPACE,
@@ -152,6 +163,242 @@ function ensureStyle(
   return style;
 }
 
+function setWordAttribute(
+  element: XmlElement,
+  name: string,
+  value: string
+) {
+  element.setAttributeNS(WORD_NAMESPACE, `w:${name}`, value);
+}
+
+function toggleProperty(
+  parent: XmlElement,
+  localName: string,
+  enabled: boolean | undefined
+) {
+  if (enabled === undefined) {
+    return;
+  }
+  removeDirectChildren(parent, WORD_NAMESPACE, localName);
+  if (enabled) {
+    appendElement(parent, WORD_NAMESPACE, `w:${localName}`);
+  }
+}
+
+function fallbackFontsForSlot(
+  slot: DocxStyleSlotName,
+  fallback: ResolvedDocxThemeStyle
+) {
+  if (slot.startsWith("heading-") || slot.endsWith("-title")) {
+    return fallback.headings.fonts;
+  }
+  if (slot === "inline-code" || slot === "code-block") {
+    return fallback.code.fonts;
+  }
+  if (
+    slot === "table" ||
+    slot === "table-header" ||
+    slot === "table-cell"
+  ) {
+    return fallback.table.fonts;
+  }
+  if (slot === "caption") {
+    return fallback.caption.fonts;
+  }
+  return fallback.body.fonts;
+}
+
+function applyTokenRunStyle(
+  parent: XmlElement,
+  token: DocxSlotStyleToken,
+  fallbackFonts: DocxFontFamily
+) {
+  if (token.fontCandidates.length) {
+    setFonts(parent, resolveTokenFonts(token, fallbackFonts));
+  }
+  if (token.fontSizePt !== undefined) {
+    removeDirectChildren(parent, WORD_NAMESPACE, "sz", "szCs");
+    const size = pointsToHalfPoints(token.fontSizePt);
+    appendElement(parent, WORD_NAMESPACE, "w:sz", {
+      "w:val": size
+    });
+    appendElement(parent, WORD_NAMESPACE, "w:szCs", {
+      "w:val": size
+    });
+  }
+  if (token.color !== undefined) {
+    removeDirectChildren(parent, WORD_NAMESPACE, "color");
+    appendElement(parent, WORD_NAMESPACE, "w:color", {
+      "w:val": colorValue(token.color)
+    });
+  }
+  if (token.backgroundColor !== undefined) {
+    removeDirectChildren(parent, WORD_NAMESPACE, "shd");
+    appendElement(parent, WORD_NAMESPACE, "w:shd", {
+      "w:val": "clear",
+      "w:color": "auto",
+      "w:fill": colorValue(token.backgroundColor)
+    });
+  }
+  if (token.underline !== undefined) {
+    removeDirectChildren(parent, WORD_NAMESPACE, "u");
+    if (token.underline) {
+      appendElement(parent, WORD_NAMESPACE, "w:u", {
+        "w:val": "single"
+      });
+    }
+  }
+  if (token.letterSpacingPt !== undefined) {
+    removeDirectChildren(parent, WORD_NAMESPACE, "spacing");
+    appendElement(parent, WORD_NAMESPACE, "w:spacing", {
+      "w:val": pointsToTwips(token.letterSpacingPt)
+    });
+  }
+  toggleProperty(parent, "b", token.bold);
+  toggleProperty(parent, "bCs", token.bold);
+  toggleProperty(parent, "i", token.italic);
+  toggleProperty(parent, "iCs", token.italic);
+  toggleProperty(parent, "strike", token.strikethrough);
+  toggleProperty(parent, "vanish", token.hidden);
+}
+
+function applyTokenBorders(
+  parent: XmlElement,
+  token: DocxSlotStyleToken
+) {
+  if (!token.borders) {
+    return;
+  }
+  removeDirectChildren(parent, WORD_NAMESPACE, "pBdr");
+  const borders = appendElement(
+    parent,
+    WORD_NAMESPACE,
+    "w:pBdr"
+  );
+  for (const side of [
+    "top",
+    "right",
+    "bottom",
+    "left"
+  ] as const) {
+    const border = token.borders[side];
+    if (!border) {
+      continue;
+    }
+    appendElement(borders, WORD_NAMESPACE, `w:${side}`, {
+      "w:val": border.style,
+      "w:sz": String(
+        Math.max(0, Math.min(160, Math.round(border.widthPt * 8)))
+      ),
+      "w:space": String(
+        Math.max(
+          0,
+          Math.min(
+            31,
+            Math.round(token.paddingPt?.[side] ?? 0)
+          )
+        )
+      ),
+      "w:color": colorValue(border.color)
+    });
+  }
+}
+
+function applyTokenParagraphStyle(
+  parent: XmlElement,
+  token: DocxSlotStyleToken
+) {
+  if (
+    token.spacingBeforePt !== undefined ||
+    token.spacingAfterPt !== undefined ||
+    token.lineSpacing !== undefined
+  ) {
+    const spacing = ensureDirectElement(
+      parent,
+      WORD_NAMESPACE,
+      "w:spacing"
+    );
+    if (token.spacingBeforePt !== undefined) {
+      setWordAttribute(
+        spacing,
+        "before",
+        pointsToTwips(token.spacingBeforePt)
+      );
+    }
+    if (token.spacingAfterPt !== undefined) {
+      setWordAttribute(
+        spacing,
+        "after",
+        pointsToTwips(token.spacingAfterPt)
+      );
+    }
+    if (token.lineSpacing !== undefined) {
+      setWordAttribute(
+        spacing,
+        "line",
+        String(Math.round(token.lineSpacing * 240))
+      );
+      setWordAttribute(spacing, "lineRule", "auto");
+    }
+  }
+  if (
+    token.firstLineIndentPt !== undefined ||
+    token.leftIndentPt !== undefined ||
+    token.rightIndentPt !== undefined
+  ) {
+    const indent = ensureDirectElement(
+      parent,
+      WORD_NAMESPACE,
+      "w:ind"
+    );
+    if (token.firstLineIndentPt !== undefined) {
+      setWordAttribute(
+        indent,
+        "firstLine",
+        pointsToTwips(token.firstLineIndentPt)
+      );
+      indent.removeAttributeNS(WORD_NAMESPACE, "firstLineChars");
+    }
+    if (token.leftIndentPt !== undefined) {
+      setWordAttribute(
+        indent,
+        "left",
+        pointsToTwips(token.leftIndentPt)
+      );
+      indent.removeAttributeNS(WORD_NAMESPACE, "leftChars");
+    }
+    if (token.rightIndentPt !== undefined) {
+      setWordAttribute(
+        indent,
+        "right",
+        pointsToTwips(token.rightIndentPt)
+      );
+    }
+  }
+  if (token.alignment !== undefined) {
+    removeDirectChildren(parent, WORD_NAMESPACE, "jc");
+    appendElement(parent, WORD_NAMESPACE, "w:jc", {
+      "w:val": token.alignment
+    });
+  }
+  if (token.backgroundColor !== undefined) {
+    removeDirectChildren(parent, WORD_NAMESPACE, "shd");
+    appendElement(parent, WORD_NAMESPACE, "w:shd", {
+      "w:val": "clear",
+      "w:color": "auto",
+      "w:fill": colorValue(token.backgroundColor)
+    });
+  }
+  applyTokenBorders(parent, token);
+  toggleProperty(parent, "keepLines", token.keepLines);
+  toggleProperty(parent, "keepNext", token.keepWithNext);
+  toggleProperty(
+    parent,
+    "pageBreakBefore",
+    token.pageBreakBefore
+  );
+}
+
 function applyBodyStyle(
   styles: XmlElement,
   style: ResolvedDocxThemeStyle
@@ -589,9 +836,215 @@ function applyTableAndCaption(
   );
 }
 
+function applyTableTokenStyles(
+  styles: XmlElement,
+  slots: ReadonlyMap<
+    DocxStyleSlotName,
+    { style: DocxSlotStyleToken }
+  >,
+  fallback: ResolvedDocxThemeStyle
+) {
+  const tableToken = slots.get("table")?.style;
+  const cellToken =
+    slots.get("table-cell")?.style ?? tableToken;
+  const headerToken =
+    slots.get("table-header")?.style ?? cellToken;
+  if (!tableToken && !cellToken && !headerToken) {
+    return;
+  }
+  const table = ensureStyle(
+    styles,
+    "Table",
+    "table",
+    "TableNormal"
+  );
+  const tblPr = ensureDirectElement(
+    table,
+    WORD_NAMESPACE,
+    "w:tblPr"
+  );
+  if (tableToken?.widthPercent !== undefined) {
+    removeDirectChildren(tblPr, WORD_NAMESPACE, "tblW");
+    appendElement(tblPr, WORD_NAMESPACE, "w:tblW", {
+      "w:w": String(
+        Math.round(tableToken.widthPercent * 50)
+      ),
+      "w:type": "pct"
+    });
+  }
+  const padding = cellToken?.paddingPt ?? tableToken?.paddingPt;
+  if (padding) {
+    removeDirectChildren(tblPr, WORD_NAMESPACE, "tblCellMar");
+    const margins = appendElement(
+      tblPr,
+      WORD_NAMESPACE,
+      "w:tblCellMar"
+    );
+    for (const side of [
+      "top",
+      "right",
+      "bottom",
+      "left"
+    ] as const) {
+      appendElement(margins, WORD_NAMESPACE, `w:${side}`, {
+        "w:w": pointsToTwips(padding[side]),
+        "w:type": "dxa"
+      });
+    }
+  }
+  if (tableToken?.borders) {
+    removeDirectChildren(tblPr, WORD_NAMESPACE, "tblBorders");
+    const borders = appendElement(
+      tblPr,
+      WORD_NAMESPACE,
+      "w:tblBorders"
+    );
+    for (const side of [
+      "top",
+      "right",
+      "bottom",
+      "left"
+    ] as const) {
+      const border = tableToken.borders[side];
+      if (!border) {
+        continue;
+      }
+      appendElement(borders, WORD_NAMESPACE, `w:${side}`, {
+        "w:val": border.style,
+        "w:sz": String(Math.round(border.widthPt * 8)),
+        "w:space": "0",
+        "w:color": colorValue(border.color)
+      });
+    }
+  }
+  if (cellToken) {
+    applyTokenRunStyle(
+      ensureDirectElement(table, WORD_NAMESPACE, "w:rPr"),
+      cellToken,
+      fallback.table.fonts
+    );
+  }
+  let firstRow = directChildren(
+    table,
+    WORD_NAMESPACE,
+    "tblStylePr"
+  ).find(
+    (element) =>
+      element.getAttributeNS(WORD_NAMESPACE, "type") === "firstRow"
+  );
+  if (!firstRow) {
+    firstRow = appendElement(
+      table,
+      WORD_NAMESPACE,
+      "w:tblStylePr",
+      { "w:type": "firstRow" }
+    );
+  }
+  if (headerToken) {
+    applyTokenRunStyle(
+      ensureDirectElement(firstRow, WORD_NAMESPACE, "w:rPr"),
+      headerToken,
+      fallback.table.fonts
+    );
+    if (headerToken.backgroundColor !== undefined) {
+      const tcPr = ensureDirectElement(
+        firstRow,
+        WORD_NAMESPACE,
+        "w:tcPr"
+      );
+      removeDirectChildren(tcPr, WORD_NAMESPACE, "shd");
+      appendElement(tcPr, WORD_NAMESPACE, "w:shd", {
+        "w:val": "clear",
+        "w:color": "auto",
+        "w:fill": colorValue(
+          headerToken.backgroundColor
+        )
+      });
+    }
+  }
+}
+
+function applyTokenStyles(
+  styles: XmlElement,
+  tokens: DocxThemeTokenSet,
+  fallback: ResolvedDocxThemeStyle
+) {
+  const slots = createDocxTokenSlotMap(tokens);
+  const documentToken = slots.get("document")?.style;
+  if (documentToken) {
+    const defaults = firstDirectChild(
+      styles,
+      WORD_NAMESPACE,
+      "docDefaults"
+    );
+    if (defaults) {
+      applyTokenRunStyle(
+        ensureDirectElement(
+          ensureDirectElement(
+            defaults,
+            WORD_NAMESPACE,
+            "w:rPrDefault"
+          ),
+          WORD_NAMESPACE,
+          "w:rPr"
+        ),
+        documentToken,
+        fallback.body.fonts
+      );
+      applyTokenParagraphStyle(
+        ensureDirectElement(
+          ensureDirectElement(
+            defaults,
+            WORD_NAMESPACE,
+            "w:pPrDefault"
+          ),
+          WORD_NAMESPACE,
+          "w:pPr"
+        ),
+        documentToken
+      );
+    }
+  }
+  for (const [slot, entry] of slots) {
+    const bindings = DOCX_SLOT_WORD_STYLE_BINDINGS[slot];
+    if (!bindings) {
+      continue;
+    }
+    for (const binding of bindings) {
+      const target = ensureStyle(
+        styles,
+        binding.styleId,
+        binding.type,
+        binding.basedOn
+      );
+      if (binding.type === "paragraph") {
+        applyTokenParagraphStyle(
+          ensureDirectElement(
+            target,
+            WORD_NAMESPACE,
+            "w:pPr"
+          ),
+          entry.style
+        );
+      }
+      applyTokenRunStyle(
+        ensureDirectElement(
+          target,
+          WORD_NAMESPACE,
+          "w:rPr"
+        ),
+        entry.style,
+        fallbackFontsForSlot(slot, fallback)
+      );
+    }
+  }
+  applyTableTokenStyles(styles, slots, fallback);
+}
+
 export function transformStylesXml(
   content: Uint8Array,
-  style: ResolvedDocxThemeStyle
+  style: ResolvedDocxThemeStyle,
+  tokens?: DocxThemeTokenSet
 ) {
   const document = parseXmlPart(content, "word/styles.xml");
   const styles = document.documentElement!;
@@ -605,12 +1058,16 @@ export function transformStylesXml(
   applyHeadings(styles, style);
   applyCodeAndQuote(styles, style);
   applyTableAndCaption(styles, style);
+  if (tokens) {
+    applyTokenStyles(styles, tokens, style);
+  }
   return serializeXmlPart(document);
 }
 
 export function transformFontTableXml(
   content: Uint8Array,
-  style: ResolvedDocxThemeStyle
+  style: ResolvedDocxThemeStyle,
+  tokens?: DocxThemeTokenSet
 ) {
   const document = parseXmlPart(content, "word/fontTable.xml");
   const root = document.documentElement!;
@@ -628,6 +1085,11 @@ export function transformFontTableXml(
       requiredFonts.add(fonts.complexScript);
     }
   }
+  if (tokens) {
+    for (const font of collectDocxTokenFonts(tokens)) {
+      requiredFonts.add(font);
+    }
+  }
   const existing = new Set(
     Array.from(
       root.getElementsByTagNameNS(WORD_NAMESPACE, "font")
@@ -648,9 +1110,22 @@ export function transformFontTableXml(
 
 export function transformThemeFontsXml(
   content: Uint8Array,
-  style: ResolvedDocxThemeStyle
+  style: ResolvedDocxThemeStyle,
+  tokens?: DocxThemeTokenSet
 ) {
   const document = parseXmlPart(content, "word/theme/theme1.xml");
+  const slots = tokens
+    ? createDocxTokenSlotMap(tokens)
+    : undefined;
+  const headingFonts = resolveTokenFonts(
+    slots?.get("heading-1")?.style,
+    style.headings.fonts
+  );
+  const bodyFonts = resolveTokenFonts(
+    slots?.get("paragraph")?.style ??
+      slots?.get("document")?.style,
+    style.body.fonts
+  );
   for (const schemeName of ["majorFont", "minorFont"]) {
     const scheme = document.getElementsByTagNameNS(
       DRAWING_NAMESPACE,
@@ -670,14 +1145,14 @@ export function transformThemeFontsXml(
     latin?.setAttribute(
       "typeface",
       schemeName === "majorFont"
-        ? style.headings.fonts.latin
+        ? headingFonts.latin
-        : style.body.fonts.latin
+        : bodyFonts.latin
     );
     eastAsia?.setAttribute(
       "typeface",
       schemeName === "majorFont"
-        ? style.headings.fonts.eastAsia
+        ? headingFonts.eastAsia
-        : style.body.fonts.eastAsia
+        : bodyFonts.eastAsia
     );
   }
   return serializeXmlPart(document);

packages/docx-engine/src/token-style-map.ts

@@ -0,0 +1,192 @@
+import type { DocxFontFamily } from "@md-to-pdf/core";
+import {
+  docxThemeTokenSetSchema,
+  type DocxResolvedStyleSlot,
+  type DocxSlotStyleToken,
+  type DocxStyleSlotName,
+  type DocxThemeTokenSet
+} from "@md-to-pdf/docx-theme-engine";
+
+export interface DocxWordStyleBinding {
+  styleId: string;
+  type: "paragraph" | "character";
+  basedOn?: string;
+}
+
+function paragraph(
+  styleId: string,
+  basedOn = "Normal"
+): DocxWordStyleBinding {
+  return { styleId, type: "paragraph", basedOn };
+}
+
+function character(
+  styleId: string,
+  basedOn = "DefaultParagraphFont"
+): DocxWordStyleBinding {
+  return { styleId, type: "character", basedOn };
+}
+
+export const DOCX_SLOT_WORD_STYLE_BINDINGS: Readonly<
+  Partial<
+    Record<
+      DocxStyleSlotName,
+      readonly DocxWordStyleBinding[]
+    >
+  >
+> = {
+  "document-title": [paragraph("Title")],
+  "document-author": [paragraph("Author")],
+  paragraph: [
+    paragraph("Normal", ""),
+    paragraph("BodyText"),
+    paragraph("FirstParagraph"),
+    paragraph("Definition"),
+    paragraph("Figure")
+  ],
+  strong: [character("Strong")],
+  emphasis: [character("Emphasis")],
+  strikethrough: [character("Strikeout")],
+  "inline-code": [character("VerbatimChar", "BodyTextChar")],
+  "heading-1": [
+    paragraph("Heading1"),
+    character("Heading1Char")
+  ],
+  "heading-2": [
+    paragraph("Heading2"),
+    character("Heading2Char")
+  ],
+  "heading-3": [
+    paragraph("Heading3"),
+    character("Heading3Char")
+  ],
+  "heading-4": [
+    paragraph("Heading4"),
+    character("Heading4Char")
+  ],
+  "heading-5": [
+    paragraph("Heading5"),
+    character("Heading5Char")
+  ],
+  "heading-6": [
+    paragraph("Heading6"),
+    character("Heading6Char")
+  ],
+  "unordered-list": [paragraph("MdUnorderedList", "BodyText")],
+  "ordered-list": [paragraph("MdOrderedList", "BodyText")],
+  "list-item": [
+    paragraph("Compact", "BodyText"),
+    paragraph("ListParagraph", "BodyText")
+  ],
+  "block-quote": [paragraph("BlockText", "BodyText")],
+  "code-block": [paragraph("SourceCode")],
+  hyperlink: [character("Hyperlink", "BodyTextChar")],
+  figure: [paragraph("Figure")],
+  caption: [
+    paragraph("Caption"),
+    paragraph("TableCaption", "Caption"),
+    paragraph("ImageCaption", "Caption")
+  ],
+  footnotes: [paragraph("FootnoteText")],
+  "official-masthead": [paragraph("MdOfficialMasthead")],
+  "official-classification": [
+    paragraph("MdOfficialClassification")
+  ],
+  "official-issuer": [paragraph("MdOfficialIssuer")],
+  "official-issue-row": [paragraph("MdOfficialIssueRow")],
+  "official-number": [paragraph("MdOfficialNumber")],
+  "official-signatory": [paragraph("MdOfficialSignatory")],
+  "official-title": [paragraph("MdOfficialTitle")],
+  "official-signature": [paragraph("MdOfficialSignature")],
+  "official-edition": [paragraph("MdOfficialEdition")],
+  "briefing-masthead": [paragraph("MdBriefingMasthead")],
+  "briefing-meta": [paragraph("MdBriefingMeta")],
+  "briefing-title": [paragraph("MdBriefingTitle")],
+  "briefing-contact": [paragraph("MdBriefingContact")],
+  "project-report-cover": [paragraph("MdProjectReportCover")],
+  "project-report-project-name": [
+    paragraph("MdProjectReportProjectName")
+  ],
+  "project-report-title": [paragraph("MdProjectReportTitle")],
+  "project-report-version": [
+    paragraph("MdProjectReportVersion")
+  ],
+  "project-report-owner": [paragraph("MdProjectReportOwner")],
+  "project-report-prepared-by": [
+    paragraph("MdProjectReportPreparedBy")
+  ],
+  "project-report-date": [paragraph("MdProjectReportDate")],
+  "tender-cover": [paragraph("MdTenderCover")],
+  "tender-copy-mark": [paragraph("MdTenderCopyMark")],
+  "tender-project-name": [paragraph("MdTenderProjectName")],
+  "tender-project-number": [
+    paragraph("MdTenderProjectNumber")
+  ],
+  "tender-title": [paragraph("MdTenderTitle")],
+  "tender-volume": [paragraph("MdTenderVolume")],
+  "tender-bidder": [paragraph("MdTenderBidder")],
+  "tender-representative": [
+    paragraph("MdTenderRepresentative")
+  ],
+  "tender-date": [paragraph("MdTenderDate")]
+};
+
+const eastAsiaFontPattern =
+  /(?:yahei|simsun|simhei|fangsong|kaiti|dengxian|cjk|source\s+han|pingfang|heiti|songti|宋|黑|仿宋|楷|等线)/iu;
+const genericFontNames = new Set([
+  "serif",
+  "sans-serif",
+  "monospace",
+  "cursive",
+  "fantasy",
+  "system-ui"
+]);
+
+export function resolveTokenFonts(
+  token: DocxSlotStyleToken | undefined,
+  fallback: DocxFontFamily
+): DocxFontFamily {
+  const candidates = (token?.fontCandidates ?? []).filter(
+    (candidate) =>
+      !genericFontNames.has(candidate.trim().toLowerCase())
+  );
+  if (!candidates.length) {
+    return fallback;
+  }
+  const eastAsia =
+    candidates.find((candidate) =>
+      eastAsiaFontPattern.test(candidate)
+    ) ?? candidates[0]!;
+  const latin =
+    candidates.find(
+      (candidate) => !eastAsiaFontPattern.test(candidate)
+    ) ?? candidates[0]!;
+  return {
+    latin,
+    eastAsia,
+    complexScript: latin
+  };
+}
+
+export function createDocxTokenSlotMap(
+  input: DocxThemeTokenSet
+): ReadonlyMap<DocxStyleSlotName, DocxResolvedStyleSlot> {
+  const tokens = docxThemeTokenSetSchema.parse(input);
+  return new Map(
+    tokens.slots.map((entry) => [entry.slot, entry])
+  );
+}
+
+export function collectDocxTokenFonts(
+  input: DocxThemeTokenSet
+): Set<string> {
+  const fonts = new Set<string>();
+  for (const { style } of input.slots) {
+    for (const candidate of style.fontCandidates) {
+      if (!genericFontNames.has(candidate.trim().toLowerCase())) {
+        fonts.add(candidate);
+      }
+    }
+  }
+  return fonts;
+}

packages/docx-engine/tests/pandoc-converter.test.ts

@@ -13,6 +13,7 @@ import {
   type PreparedDocxMedia,
   type ThemeManifest
 } from "@md-to-pdf/core";
+import type { DocxThemeTokenSet } from "@md-to-pdf/docx-theme-engine";
 import {
   PandocDocxConversionError,
   PandocDocxConverter,
@@ -49,6 +50,16 @@ const emptyMedia: PreparedDocxMedia = {
   totalBytes: 0
 };
 
+const themeTokens: DocxThemeTokenSet = {
+  schemaVersion: 1,
+  themeId: "test-theme",
+  themeFingerprint: "c".repeat(64),
+  mode: "auto-with-overrides",
+  basePreset: "technical",
+  slots: [],
+  diagnostics: []
+};
+
 function input() {
   return {
     markdown: "# 测试",
@@ -56,6 +67,7 @@ function input() {
     language: "zh-CN",
     exportConfig: defaultExportConfig,
     theme: theme(),
+    themeTokens,
     metadata: {
       title: "测试",
       author: "测试人",

packages/docx-engine/tests/reference-builder.test.ts

@@ -6,6 +6,10 @@ import {
   type ExportConfig,
   type ThemeManifest
 } from "@md-to-pdf/core";
+import type {
+  DocxResolvedStyleSlot,
+  DocxThemeTokenSet
+} from "@md-to-pdf/docx-theme-engine";
 import {
   createDynamicReferenceDocx,
   validateGeneratedDocx,
@@ -129,6 +133,21 @@ function theme(
   };
 }
 
+function themeTokens(
+  fingerprint = "c".repeat(64),
+  slots: DocxResolvedStyleSlot[] = []
+): DocxThemeTokenSet {
+  return {
+    schemaVersion: 1,
+    themeId: "test-theme",
+    themeFingerprint: fingerprint,
+    mode: "auto-with-overrides",
+    basePreset: "technical",
+    slots,
+    diagnostics: []
+  };
+}
+
 function createOptions(exportConfig: ExportConfig) {
   return {
     exportConfig,
@@ -137,7 +156,8 @@ function createOptions(exportConfig: ExportConfig) {
     metadata: {
       title: "年度 <报告>",
       author: "测试人"
-    }
+    },
+    themeTokens: themeTokens()
   };
 }
 
@@ -159,6 +179,10 @@ describe("动态 reference.docx", () => {
         author: "测试人"
       }
     });
+    const changedTokens = createDynamicReferenceDocx(baseline, {
+      ...createOptions(defaultExportConfig),
+      themeTokens: themeTokens("d".repeat(64))
+    });
     const entries = unzipSync(first.content);
     const documentXml = decoder.decode(entries["word/document.xml"]);
     const stylesXml = decoder.decode(entries["word/styles.xml"]);
@@ -169,6 +193,7 @@ describe("动态 reference.docx", () => {
     );
     expect(first.cacheKey).toBe(second.cacheKey);
     expect(first.cacheKey).not.toBe(changedMetadata.cacheKey);
+    expect(first.cacheKey).not.toBe(changedTokens.cacheKey);
     expect(documentXml).toContain('w:w="11906"');
     expect(documentXml).toContain('w:h="16838"');
     expect(documentXml).toContain('w:top="907"');
@@ -186,6 +211,106 @@ describe("动态 reference.docx", () => {
     });
   });
 
+  it("将通用主题令牌写入标准样式、结构样式和字体部件", () => {
+    const result = createDynamicReferenceDocx(
+      createBaselineReference(),
+      {
+        ...createOptions(defaultExportConfig),
+        themeTokens: themeTokens("e".repeat(64), [
+          {
+            slot: "paragraph",
+            source: "computed-css",
+            confidence: "exact",
+            style: {
+              fontCandidates: [
+                "Source Han Serif SC",
+                "Times New Roman"
+              ],
+              fontSizePt: 14,
+              color: "#112233",
+              lineSpacing: 1.8,
+              firstLineIndentPt: 28
+            }
+          },
+          {
+            slot: "heading-1",
+            source: "computed-css",
+            confidence: "exact",
+            style: {
+              fontCandidates: ["SimHei", "Arial"],
+              fontSizePt: 22,
+              bold: true,
+              color: "#aa0000",
+              alignment: "center",
+              keepWithNext: true
+            }
+          },
+          {
+            slot: "table",
+            source: "computed-css",
+            confidence: "exact",
+            style: {
+              fontCandidates: [],
+              widthPercent: 100,
+              paddingPt: {
+                top: 3,
+                right: 4,
+                bottom: 3,
+                left: 4
+              },
+              borders: {
+                top: {
+                  widthPt: 1,
+                  color: "#445566",
+                  style: "single"
+                }
+              }
+            }
+          },
+          {
+            slot: "official-title",
+            source: "computed-css",
+            confidence: "exact",
+            style: {
+              fontCandidates: ["SimSun"],
+              fontSizePt: 22,
+              color: "#ff0000",
+              alignment: "center",
+              keepWithNext: true
+            }
+          }
+        ])
+      }
+    );
+    const entries = unzipSync(result.content);
+    const stylesXml = decoder.decode(entries["word/styles.xml"]);
+    const fontTableXml = decoder.decode(
+      entries["word/fontTable.xml"]
+    );
+    const themeXml = decoder.decode(
+      entries["word/theme/theme1.xml"]
+    );
+
+    expect(stylesXml).toContain('w:styleId="MdOfficialTitle"');
+    expect(stylesXml).toContain('w:eastAsia="Source Han Serif SC"');
+    expect(stylesXml).toContain('w:ascii="Times New Roman"');
+    expect(stylesXml).toContain('w:val="112233"');
+    expect(stylesXml).toContain('w:styleId="Heading1"');
+    expect(stylesXml).toContain('w:val="AA0000"');
+    expect(stylesXml).toContain('w:w="5000" w:type="pct"');
+    expect(stylesXml).toContain('w:color="445566"');
+    expect(fontTableXml).toContain(
+      'w:name="Source Han Serif SC"'
+    );
+    expect(fontTableXml).toContain('w:name="SimHei"');
+    expect(themeXml).toContain(
+      '<a:latin typeface="Arial"'
+    );
+    expect(themeXml).toContain(
+      '<a:ea typeface="SimHei"'
+    );
+  });
+
   it("生成横向、自定义页边距和奇偶首页页眉页脚", () => {
     const exportConfig: ExportConfig = {
       ...defaultExportConfig,

packages/docx-engine/tests/token-style-map.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from "vitest";
+import type { DocxThemeTokenSet } from "@md-to-pdf/docx-theme-engine";
+import {
+  DOCX_SLOT_WORD_STYLE_BINDINGS,
+  collectDocxTokenFonts,
+  createDocxTokenSlotMap,
+  resolveTokenFonts
+} from "../src/index.js";
+
+const tokens: DocxThemeTokenSet = {
+  schemaVersion: 1,
+  themeId: "test-theme",
+  themeFingerprint: "a".repeat(64),
+  mode: "auto",
+  basePreset: "general",
+  slots: [
+    {
+      slot: "paragraph",
+      source: "computed-css",
+      confidence: "exact",
+      style: {
+        fontCandidates: [
+          "Source Han Serif SC",
+          "Times New Roman",
+          "serif"
+        ]
+      }
+    }
+  ],
+  diagnostics: []
+};
+
+describe("DOCX 令牌样式映射", () => {
+  it("以稳定样式 ID 覆盖标准 Markdown 和结构槽位", () => {
+    expect(
+      DOCX_SLOT_WORD_STYLE_BINDINGS["heading-1"]
+    ).toEqual([
+      {
+        styleId: "Heading1",
+        type: "paragraph",
+        basedOn: "Normal"
+      },
+      {
+        styleId: "Heading1Char",
+        type: "character",
+        basedOn: "DefaultParagraphFont"
+      }
+    ]);
+    expect(
+      DOCX_SLOT_WORD_STYLE_BINDINGS["official-title"]?.[0]
+        ?.styleId
+    ).toBe("MdOfficialTitle");
+    expect(
+      DOCX_SLOT_WORD_STYLE_BINDINGS["tender-representative"]?.[0]
+        ?.styleId
+    ).toBe("MdTenderRepresentative");
+  });
+
+  it("按文字系统选择字体并过滤 CSS 通用族名", () => {
+    const slot = createDocxTokenSlotMap(tokens).get("paragraph");
+    expect(
+      resolveTokenFonts(slot?.style, {
+        latin: "Arial",
+        eastAsia: "SimSun"
+      })
+    ).toEqual({
+      latin: "Times New Roman",
+      eastAsia: "Source Han Serif SC",
+      complexScript: "Times New Roman"
+    });
+    expect([...collectDocxTokenFonts(tokens)]).toEqual([
+      "Source Han Serif SC",
+      "Times New Roman"
+    ]);
+  });
+});

packages/docx-theme-engine/README.md

@@ -29,6 +29,7 @@ DOCX 主题映射引擎负责在浏览器主题 CSS 与 Word 样式之间建立
 
 Server Playwright 与 Desktop Electron 适配器负责在现有受限浏览器生命周期
 中执行本包脚本；主题 CSS 和字体资源继续使用各平台已有的同源资源协议。
-`@md-to-pdf/docx-engine` 后续消费本包令牌生成 `reference.docx` 和最终
+`@md-to-pdf/application` 已负责指纹、快照缓存和令牌准备，
-OOXML。Flex、Grid 和超出 Word 上限的装饰边不会静默丢弃，而是保留近似
+`@md-to-pdf/docx-engine` 已消费本包令牌生成动态 `reference.docx`。
+Flex、Grid 和超出 Word 上限的装饰边不会静默丢弃，而是保留近似
 令牌与诊断，供语义文档结构层选择 Word 表格、分节或段落布局实现。

packages/docx-theme-engine/src/normalizer.ts

@@ -759,7 +759,9 @@ export function resolveDocxThemeTokens(
           style: normalized.style
         };
       } else {
-        const missing = entry?.matched !== true;
+        const missing =
+          input.config.mode !== "explicit" &&
+          entry?.matched !== true;
         diagnostics.push({
           severity: missing ? "warning" : "info",
           code:

packages/docx-theme-engine/src/runtime.ts

@@ -25,6 +25,7 @@ export type DocxThemeStyleCaptureRequest = z.infer<
 >;
 
 export interface DocxThemeStyleCaptureAdapter {
+  readonly themeStyleBaseUrl: string;
   captureThemeStyle(
     request: DocxThemeStyleCaptureRequest,
     signal?: AbortSignal