turbodocx-html-to-docx

HTML 转 DOCX 设置

此技能会将 @turbodocx/html-to-docx 添加到 JavaScript/TypeScript 项目中。这是一个零依赖库，可将 HTML 字符串转换为 Word 文档，无需 Puppeteer、Chrome 或 LibreOffice。它既可在 Node.js 中运行，也可在浏览器中运行（通过打包的 IIFE/ESM 构建版本）。

尽可能优先使用服务端。 在服务端运行速度更快，可避免约 2.4 MB 的浏览器包，免去对 polyfill 的需求，并且可以使用 sharp（用于将 SVG 转换为 PNG）。只要项目有任何后端（Express/Fastify/Next.js API 路由等），就默认采用服务端集成；仅当项目确实是静态项目，或用户明确要求在客户端生成时，才使用浏览器包。

阶段 1：检测项目类型

使用 Glob 检查项目类型：

1. Node.js / 基于 npm 的项目 — 根目录中存在 package.json。这是首选路径。

   • 同时检查是否存在 tsconfig.json，以确定是否使用 TypeScript。
   • 根据锁文件检测包管理器：
     • pnpm-lock.yaml → pnpm
     • yarn.lock → yarn
     • bun.lockb → bun
     • package-lock.json 或没有锁文件 → npm
   • 检查 package.json 中是否有 "type": "module"，以确定使用 ESM 还是 CommonJS 导入。
   • 如果项目同时有服务端运行时和客户端（例如 Next.js、Remix、Nuxt、SvelteKit），默认采用服务端路由/处理程序/操作路径——除非用户明确要求，否则不要在客户端组件中生成文档。
   • 继续执行阶段 2（npm 安装路径）。

2. 仅限浏览器的项目 — 没有 package.json，但存在 HTML 文件（*.html），或者用户明确表示想在静态页面/CDN 设置中使用。在确定采用此路径前，先简要向用户确认他们是否没有更希望用于运行此功能的后端——优先使用服务端。如果用户确认必须使用浏览器：

   • 完全跳过 npm 安装。该库提供自包含的浏览器包（dist/html-to-docx.browser.js，约 2.4 MB 的 IIFE），其中内联了所有依赖项。
   • 阅读 references/usage.md 中的 Browser Usage 部分，了解 polyfill 代码片段、HTMLToDOCX(...) 全局函数以及相关限制（不支持 sharp、远程图片受 CORS 限制、没有文件系统）。
   • 添加一个 <script src="...">，引用托管副本或 CDN 构建版本，并根据用户的页面生成一个最简可运行示例。
   • 跳过下文的阶段 2–4；浏览器路径无需安装。

3. 两者都不是 — 没有 package.json，也没有 HTML 文件。继续操作前，询问用户目标环境是什么（Node.js、打包工具或静态 HTML），并建议默认采用服务端。

阶段 2：安装软件包

运行检测到的包管理器对应的安装命令：

• npm：npm install @turbodocx/html-to-docx
• pnpm：pnpm add @turbodocx/html-to-docx
• yarn：yarn add @turbodocx/html-to-docx
• bun：bun add @turbodocx/html-to-docx

无需环境变量——这是一个本地库，不需要 API 密钥。

阶段 3：阅读参考资料

阅读此技能目录中的 references/usage.md。其中包含完整的 API、配置选项和代码示例。

阶段 4：分析代码库并生成代码

步骤 4.1：探索项目

使用 Glob 和 Read 了解：

• 源文件所在位置（src/、app/、lib/、根目录）
• 使用的框架（Express、Fastify、NestJS、Next.js、Hono、Koa 或无）
• 现有模式：路由的定义方式、文件的组织方式、命名惯例
• 项目使用 TypeScript 还是 JavaScript
• 使用 ESM（import）还是 CommonJS（require）风格

步骤 4.2：与用户确认

简要说明你的发现，以及计划将新文件放在哪里。询问用户是否认可。

第 4.3 步：生成辅助模块

创建一个辅助模块，使用合理的默认值封装 HTMLtoDOCX。将其放在项目存放实用工具的位置（例如 src/lib/、src/utils/、lib/）。

辅助模块应：

• 按照项目的导入风格（ESM 或 CJS）导入 HTMLtoDOCX
• 导出一个类似 generateDocx(html, options?) 的函数，调用 HTMLtoDOCX 并返回一个 Buffer
• 包含常用默认值（字体、页边距），并允许用户覆盖
• 如果项目使用 TypeScript，则使用 TypeScript

第 4.4 步：生成集成代码

根据项目需求：

如果是 Web 服务（Express、Fastify、NestJS、Next.js 等）： 创建一个接收 HTML（在请求正文中）并返回 .docx 文件的端点。遵循框架的路由模式：

• Express：使用 Router，并设置 res.setHeader('Content-Type', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document')，然后调用 res.send(buffer)
• Next.js App Router：创建 app/api/.../route.ts 文件，导出 POST 函数，并返回 new Response(buffer, { headers })
• NestJS：使用 @Controller + @Post，通过 @Res() res 流式传输缓冲区
• 其他框架：遵循其惯例

设置响应头：

Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename="document.docx"

将路由接入应用的主文件（除非使用 Next.js 这类基于文件的路由）。

如果是独立/脚本项目： 创建一个脚本，读取 HTML（来自文件、stdin 或字符串）并写入 .docx 文件。提供一个基本的 HTML 字符串示例进行演示。

第 5 阶段：验证并总结

如果项目使用 TypeScript，运行 npx tsc --noEmit 检查类型错误。

打印摘要：

• 创建和修改的文件
• 安装的包
• 使用方法（端点的 curl 命令示例，或如何运行脚本）
• 文档链接：https://docs.turbodocx.com/docs
• 可自定义的关键选项（页面大小、方向、页边距、字体、页眉/页脚）