Document Generator

核心用法

document-generator 是一套基于 Python 的文档自动化生成系统，通过命令行脚本将结构化数据转换为专业格式的 Word（.docx）、Excel（.xlsx）或 PDF（.pdf）文件。

Word 生成：支持多级标题、表格（含样式）、图片（含题注）、段落、列表及页眉页脚。复杂内容可通过 JSON 结构描述，调用 create_word.py 渲染。

Excel 生成：创建多工作表、填充单元格、应用数字格式与边框，支持公式与基础图表（柱状图、折线图、饼图）。

PDF 生成：提供两条技术路径——WeasyPrint（HTML→PDF，高质量排版）或 fpdf2（纯文本+样式），支持页眉页脚、页码控制。

模板系统：内置 Jinja2 变量替换，允许用户以 JSON 或 HTML 定义自定义模板，实现动态内容注入。

显著优点

1. 多格式统一接口：单一技能覆盖三大办公文档格式，降低学习成本。
2. 声明式内容描述：JSON 结构描述复杂文档，便于程序生成与版本管理。
3. 高保真 PDF：WeasyPrint 基于 Web 标准渲染，支持中文（如 Microsoft YaHei）与精细样式。
4. 模板复用：预置常见文档类型模板，减少重复编码。

潜在缺点与局限性

• 依赖管理复杂：需预装 5 个 Python 包（python-docx、openpyxl、fpdf2、weasyprint、jinja2），WeasyPrint 额外依赖系统库（Pango、Cairo），Linux 环境配置门槛较高。
• 无交互式编辑：纯代码驱动，无 GUI 或实时预览，调试样式需反复生成。
• Excel 图表能力有限：仅支持基础图表类型，复杂可视化需借助其他工具。
• 性能瓶颈：超大 Excel（>10k 行）需手动启用流式写入，默认模式内存占用高。

适合人群

• 需批量生成合同、发票、证书的企业自动化场景
• 数据分析师将结构化结果导出为格式化报告
• 开发者构建文档流水线（CI/CD 生成发布物）

常规风险

• 依赖冲突：WeasyPrint 与系统 GTK 库版本耦合，升级可能导致渲染异常。
• 路径安全：脚本接受用户输入的文件路径与图片路径，需调用方确保无路径遍历攻击。
• 模板注入：Jinja2 模板若来源不可信，存在沙箱逃逸风险（虽文档未提及沙箱加固）。

核心用法

document-generator 是一款专注于本地文档生成的Agent技能，支持Word（.docx）、Excel（.xlsx）和PDF三种主流格式的程序化创建。用户可通过简单的命令行调用或JSON结构描述，快速生成包含多级标题、表格、图片、自定义样式等丰富元素的商务文档。技能采用成熟的开源Python库栈（python-docx、openpyxl、WeasyPrint等），无需依赖外部API或云服务，完全在本地环境执行。

使用方式分为三个层级：基础命令行模式适合快速生成简单文档；中级JSON结构模式支持段落、列表、表格、图片等复合内容编排；高级模板模式允许用户基于Jinja2模板引擎实现动态数据替换，满足批量个性化生成需求。例如，销售团队可将CRM数据直接注入模板，一键生成数百份差异化报价单。

显著优点

格式覆盖全面：单一技能覆盖办公三大核心格式，避免用户在多个工具间切换。Word支持9级标题、页眉页脚、预设表格样式；Excel支持公式、图表、单元格格式；PDF支持HTML转高质量排版，满足从简单报表到精美宣传册的 diverse 需求。

离线优先架构：所有依赖均为本地Python库，执行过程零网络请求，保障数据不出本地环境，特别适合处理敏感商业数据或在内网环境部署。

模板化效率：内置Jinja2模板系统，业务人员可预先设计文档框架，运营人员仅需更新JSON数据即可批量产出，大幅降低重复排版工作量。

确定性输出：纯文档生成逻辑，无动态代码执行或系统调用，行为高度可预测，便于集成至自动化工作流。

潜在缺点与局限性

环境依赖前置：首次使用需手动安装Python依赖包及Linux系统库（WeasyPrint所需Pango、Cairo等），对非技术用户门槛较高。若依赖缺失，技能会直接报错终止，缺乏自动修复机制。

功能边界清晰：专注于"生成"而非"编辑"，无法读取或修改现有文档。复杂版式（如图文混排环绕、高级Excel透视表）需预先生成再人工精调。

性能瓶颈：大体积Excel（超万行）需显式启用write-only流式模式，否则内存占用显著；PDF依赖WeasyPrint的渲染引擎，复杂CSS页面可能出现跨页断行异常。

生态版本锁定：依赖库版本与Python版本强相关，升级环境可能导致兼容性问题。

适合的目标群体

• 企业运营人员：需定期输出标准化报告、对账单、合同模板的财务、HR、市场部门
• 开发者/自动化工程师：构建RPA流程、CI/CD报告生成、后台管理系统的文档导出功能
• 教育/研究机构：批量生成证书、成绩单、实验报告等格式统一但内容个性化的文档
• 中小型电商/服务商：快速制作报价单、发货单、电子发票等商务单据

使用风险

性能风险：未优化的大数据集生成可能导致内存溢出或超时，建议分页处理或采用流式写入模式。依赖维护风险：WeasyPrint等库与系统GTK/Pango版本耦合，跨平台部署时需验证渲染一致性。模板注入风险：Jinja2模板若接收未过滤的用户输入，理论上存在模板注入漏洞，建议对动态变量进行白名单校验。文件覆盖风险：技能默认按指定路径写入，若路径配置错误可能覆盖重要文件，建议配置输出目录隔离策略。