formaldoc

formaldoc 技能

使用已发布的 formaldoc npm 包将 Markdown 转换为 .docx。

适用场景

当用户需要生成真正的 Word 文档，而不仅仅是 Markdown 或纯文本时，请使用此技能。

常见需求：

• “生成一个 docx”
• “导出为 Word”
• “将此 Markdown 转成文档”
• “将此内容保存为 .docx”
• “下载 Word 文件”

工作流

1. 确定模板

如果用户已选定模板，或上下文中有明确提示，请直接使用该模板。

如果模板不明确，请询问一次，保持简洁。

默认建议：

• cn-report 用于中文商务或工作报告内容
• cn-gov 用于中文官方或政府风格内容
• en-business 用于英文专业内容
• 后备默认模板：cn-gov

简短提示示例：

应使用哪个模板？默认模板为 cn-report。可选模板：cn-gov / cn-general / cn-academic / cn-report / en-standard / en-business / en-academic / en-legal

2. 先将 Markdown 写入文件，再从文件转换

重要：务必先将内容写入 .md 文件，再从该文件进行转换。 强烈建议采用这种方式，因为：

• 这样可以避免在代码中将整篇文档嵌入为字符串字面量，浪费 token
• 如果 Markdown 已存在于文件中，则无需再次写入——只需指定该文件即可
• 该文件可作为交付物，供用户检查、编辑并在之后重新转换

决策流程：

Does a .md file already exist on disk?
  ├── YES → use it directly (Step 3a)
  └── NO → write the content to a .md file first, then use it (Step 3a)

只有在写入临时文件确实不切实际时（例如，在无法访问文件系统的沙盒环境中），才使用内存转换（第 3b 步）。

3a. 基于文件的转换（首选）

使用 CLI——这是最简单且 token 效率最高的方式：

npx formaldoc input.md -t cn-report -o output.docx

如果文档以 ## 而非 # 开头，请使用 -l 设置标题级别：

npx formaldoc input.md -t cn-report -l 2 -o output.docx

如果需要通过编程进行控制，也可以使用 Node API：

import { convertMarkdownToDocxFile } from 'formaldoc';

const result = await convertMarkdownToDocxFile({
  inputPath: '/absolute/path/to/input.md',
  outputPath: '/absolute/path/to/output.docx',
  templateName: 'cn-report',
  titleLevel: 1, // 1-5: which heading level maps to Title (default: 1)
});

console.log(result.outputPath);

3b. 内存转换（最后手段）

仅在无法使用文件系统时使用此方式。如果可以写入文件，就不要使用此方式——在代码中嵌入较大的 Markdown 字符串会大量浪费 token。

import { writeFile } from 'node:fs/promises';
import { convertMarkdownToDocx } from 'formaldoc';

const result = await convertMarkdownToDocx({
  markdown: '## Title\n\nShort content only.',
  templateName: 'cn-report',
  titleLevel: 2, // ## maps to Title, ### to Heading1, etc.
});

await writeFile('/absolute/path/to/output.docx', result.buffer);

4. 返回生成的文件

只要环境支持返回文件，最终输出就应是 .docx 文件本身。

重要说明

• 始终优先使用文件。 如果内容已存在于 .md 文件中，请从文件转换。如果尚不存在，请先将其写入 .md 文件，再进行转换。内存转换并内嵌 Markdown 字符串是最后手段——处理大型文档时会浪费 token。
• formaldoc 以 ESM 为主。优先使用 import，不要使用 require()。
• 在 Agent 环境中优先使用绝对路径。
• 如条件允许，选择与文档标题相符的输出文件名。
• 返回真正的 .docx 成品，而不只是路径或成功消息。
• 如果 Markdown 以 ## 或更低级别的标题开头，而非 #，请使用 titleLevel（API）或 -l（CLI）。例如，titleLevel: 2 会将 ## 映射为 Title，将 ### 映射为 Heading1，依此类推。有效范围：1-5。

模板速查表

场景	推荐模板
中文工作报告、进展更新、分析	cn-report
政府、监管或中文官方文档	cn-gov
通用中文文档	cn-general
中文学术内容	cn-academic
英文商务内容	en-business
英文学术内容	en-academic
英文法律内容	en-legal
通用英文文档	en-standard