中文 | English
PolyDoc 是一个高性能、高保真的 HTML 文档转换服务，致力于解决业务系统中 HTML 导出为离线文档（PDF/Word/Markdown）时的痛点，如图片丢失、样式错乱和中文乱码问题。
-
A 级：像素级 PDF 还原 📄
- 基于 Chromium 渲染，视觉效果与浏览器完全一致。
- 智能分页算法，防止表格行和图片被切断。
- 自动注入页眉页脚。
-
B 级：结构化 Word 导出 📝
- 智能 DOM 降级，将复杂的 Flex/Grid 布局转换为 Word 友好的 Table/流式布局。
- 自动处理 CSS 样式内联和单位转换。
- 图片/背景图自动本地化处理。
-
C 级：语义化 Markdown 📋
- 保留文档核心语义（标题、列表、表格）。
- 自动清洗多余样式，生成清晰的 Markdown 源码。
-
全流程资源处理 🛡️
- 自动提取并下载外链图片，解决内网隔离导致的“红叉”问题。
- 智能格式清洗（WebP 转 JPG）与体积压缩。
- SSRF 安全防护，禁止请求内网地址。
- Node.js v18+
- Docker (可选，推荐用于生产环境以保证字体支持)
git clone https://github.com/YOLO-9257/PolyDoc.git
cd PolyDoc
npm install复制环境变量示例文件：
cp .env.example .env.env 配置项说明：
| 变量名 | 说明 | 默认值 |
|---|---|---|
PORT |
服务端口 | 3000 |
MAX_CONCURRENT_TASKS |
并发任务数限制 | 4 |
IMAGE_MAX_WIDTH |
图片最大宽度（自动缩放） | 1200 |
IMAGE_QUALITY |
图片压缩质量 (0-100) | 80 |
PUPPETEER_EXECUTABLE_PATH |
自定义 Chromium 路径 | (自动识别) |
# 开发模式
npm run start:dev
# 生产模式
npm run build
npm run start:prod服务启动后，API 默认监听在 http://localhost:3000。
接口: POST /api/v1/convert
请求体 (JSON):
{
"htmlContent": "<html><body><h1>Hello PolyDoc</h1></body></html>",
"targetFormat": "pdf",
"config": {
"optimizeImages": true,
"filename": "my_document",
"ai": {
"enabled": true,
"optimizeMode": "format"
},
"pdfOptions": {
"format": "A4",
"landscape": false,
"adaptivePagination": true,
"adaptivePaginationPasses": 2,
"renderMode": "interactive",
"waitForSelector": "#app-ready",
"waitForTimeoutMs": 1200,
"renderTimeoutMs": 30000,
"allowedScriptDomains": ["cdn.jsdelivr.net"]
}
}
}targetFormat 支持: pdf, docx, md
- 静态页面：
renderMode=static（默认），速度更快。 - 动态页面（SPA/懒加载）：
renderMode=interactive，建议配合：waitForSelector：关键节点出现再导出waitForTimeoutMs：补偿动画/异步数据渲染allowedScriptDomains：仅允许白名单域名脚本执行
- 高保真模式建议设置：
optimizeImages=false，避免图片被二次压缩或缩放。 - 简历场景建议开启：
pdfOptions.adaptivePagination=true，并设置adaptivePaginationPasses=2，可自动减少跨页切断与标题悬挂。
ai.optimizeMode支持：none：不做内容与格式优化format：仅优化结构与排版content：仅优化文案表达both：同时优化格式与内容（默认）
- 如果你想更精细控制，也可以传：
ai.optimizeFormat: true|falseai.optimizeContent: true|false
- Web 界面支持“保存为全局配置”，保存后会持久化到服务端本地文件（默认：
data/global-ai-config.json）。 - 后续所有转换请求会自动合并全局配置并生效，无需每次重复填写 API Key / 模型。
- 提供“测试模型可用性”按钮，可在导出前快速检查模型连通性与延迟。
- 你也可以通过 API 管理：
GET /api/v1/settings/ai：读取全局配置（API Key 脱敏）PUT /api/v1/settings/ai：更新全局配置POST /api/v1/convert/ai-test：测试当前配置（或全局配置）是否可用
- Web 界面新增“交互式简历调整”区域，可输入自然语言指令（如“强化项目量化成果”）并多轮迭代。
- 每次调整会直接返回新的 HTML，可继续修改再导出 PDF/Word/Markdown。
- 后端接口：
POST /api/v1/convert/ai-adjust- 入参：
htmlContent,instruction,targetFormat,ai,history - 出参：
htmlContent（调整后的完整 HTML）
npm run baseline:pdf详细说明见 scripts/README.baseline.md。
为了确保中文字体（如 Noto Sans SC, 文泉驿）正常显示，强烈建议使用 Docker 部署。
# 构建镜像
docker build -t polydoc:latest .
# 运行容器
docker run -d -p 3000:3000 polydoc:latest关于样式还原等级定义、技术架构设计和详细的实现逻辑，请参阅 架构与设计文档。
欢迎提交 Issue 和 Pull Request！详细指南请查看 CONTRIBUTING.md。
本项目基于 MIT License 开源。