ianustec/openwebui-generate-documents

# 生成文档 — Open WebUI 的原生 DOCX 引擎 一个 [Open WebUI](https://github.com/open-webui/open-webui) **工具**，可以从 Markdown（包含 YAML frontmatter）或由模型生成的 JSON 规范生成**原生 Word (.docx)** 文档。它不导出 HTML 或 PDF：而是直接使用 `python-docx` 构建文档，拥有一套连贯的设计系统 —— 封面页、带有分割线的编号标题、样式化的表格、标注框、代码块、签名、TOC 以及页眉/页脚。 生成的文件通过 Open WebUI 的 **Files API** 保存（带有 `/cache/files` 回退机制），聊天中会出现一个可点击的**下载链接**。  *文档基于示例 [`examples/report.md`](examples/report.md) → [`examples/demo_report.docx`](examples/demo_report.docx) 生成。* ## 功能 - **原生、可编辑的 .docx**（文本、表格和样式均可在 Word / Pages / LibreOffice 中编辑）。 - **双输入，自动检测**：带 frontmatter 的 Markdown（首选）**或** JSON —— 输出相同。 - **7 种模板**，具有派生自单一 `accent` 颜色的连贯调色板：`report`、`whitepaper`、`proposal`、`letter`、`memo`、`minutes`、`blank`。 - **封面页**：`band`（强调色面板）、`rule`（编辑风格）或 `plain`。 - **编号标题**（1, 1.1, 1.1.1），带有 H1/H2 强调分割线 —— 自动去除任何手动编号。 - **丰富的表格**：填充的强调色表头、斑马线行、数字/货币列自动右对齐。 - **标注框**：`info`、`success`、`warning`、`danger`（彩色条+背景色）。 - **列表**（项目符号、有序列表、清单），**引用**，**代码块**，**签名**，**TOC**，分页符。 - **`==highlight==`** 映射为强调色高亮；智能引号；排版间距。 - **页眉 / 页脚**，具有 3 个区域（`left`/`center`/`right`）和实时页码（`{{page}}` / `{{pages}}`）。 - **具有可读性的文件名**，派生自标题（例如 `Q3 Board Report.docx`）。 - **可选图片**，来自 Unsplash（需密钥）或通过 Open WebUI 生成。 - **单文件**：一个独立的 `.py` 文件，可直接粘贴到工具注册表中。 ## 环境要求 - Open WebUI `>= 0.4.0` - Python：`python-docx`、`Pillow`、`markdown-it-py`、`mdit-py-plugins`、`PyYAML`、`lxml`（在 frontmatter 中声明 → Open WebUI 会自动安装） - 可选：`httpx`（从 URL / Unsplash 获取图片） ## 安装说明 ### 选项 A — 从 Open WebUI 社区 1. 打开 Open WebUI 社区网站上的工具页面。 2. 点击 **Get** / **Import** 导入到您的实例中。 ### 选项 B — 手动 1. 在您的 Open WebUI 实例中，转到 **Workspace → Tools → +**。 2. 粘贴 [`generate_documents.py`](generate_documents.py) 的内容。 3. 保存。声明的依赖项将在首次使用时安装。 4. 为需要使用该工具的模型（或聊天）启用此工具。 ## 用法 模型调用 `generate_document(content)`，其中 `content` 是带 frontmatter 的 Markdown（首选）**或** JSON 字符串。 ### Markdown（首选） ``` --- template: report title: "Digital Transformation Program — FY 2026" subtitle: "Strategic plan, roadmap and budget" author: "Northwind Analytics" cover: auto header: left: "Northwind Analytics — Confidential" right: "Rev. 1.0" footer: center: "Page {{page}} of {{pages}}" styles: accent: "#1B6B93" --- # 执行摘要 Revenue grew **24%** year over year. ::: callout type="success" title="Highlight" Operating margin expanded by ==6 pp==. ::: | Objective | KPI target | Priority | |-----------|-----------|----------| | Process automation | 80% of flows | ==High== | ``` 请参阅 [`examples/report.md`](examples/report.md) 中的完整示例。 ### JSON（旧版，仍受支持） ``` { "template": "report", "title": "FY 2026 Report", "cover": "auto", "styles": { "accent": "#1B6B93" }, "blocks": [ { "type": "heading", "level": 1, "text": "Executive Summary" }, { "type": "paragraph", "text": "Revenue grew 24% YoY." }, { "type": "callout", "kind": "success", "title": "Highlight", "text": "Margin +6pp." } ] } ``` ### 模板 `report` · `whitepaper` · `proposal` · `letter` · `memo` · `minutes` · `blank`。 每个模板都从单一的 `accent` 颜色派生出完整的调色板，因此 `styles: { accent: "#C0392B" }` 会对整个文档重新调整主题。 ### 内容块（Markdown 语法） | 区块 | 语法 | |---|---| | 标题 | `# H1` … `#### H4`（在 `report`/`whitepaper` 中自动编号） | | 强调 | `**bold**`, `*italic*`, `` `code` ``, `==highlight==` | | 列表 | `- bullet`, `1. ordered`, `- [ ] checklist` | | 表格 | 标准 Markdown 管道表格（数字列自动右对齐） | | 标注框 | `::: callout type="info\|success\|warning\|danger" title="..."` … `:::` | | 引用 | `> quoted text` | | 代码 | 围栏 ```` ``` ```` 区块 | | 签名 | `::: signature name="..." role="..." date="..."` … `:::` | | 目录 | `[[toc]]` | | 分页符 | `\newpage` | ## 截图 | 封面 | 内容 | |---|---| |  |  | | **标注框和表格** | **风险矩阵和签名** | |  |  | ## Valves（配置） | Valve | 默认值 | 描述 | |---|---|---| | `default_template` | `blank` | 当规范未设置模板时使用的模板 | | `unsplash_access_key` | `""` | 用于获取图库图片的 Unsplash 密钥（可选） | | `image_generation_url` | `""` | OpenAI 兼容的图片端点（可选） | | `image_generation_api_key` | `""` | `image_generation_url` 的 Bearer token | | `docx_export_dir` | `/app/backend/data/cache/files` | 保存文件的回退目录 | | `emit_status` | `true` | 在聊天中发送状态事件 | ## 工作原理 1. 模型生成 Markdown（或 JSON）并调用 `generate_document`。 2. 解析器将两种格式规范统一，将其与模板默认值合并，并解析强调色调色板。 3. 每个区块均以原生 OOXML（段落、表格、阴影、边框、域）形式写入。 4. `.docx` 通过 Files API（回退至 `/cache/files`）保存，并在聊天中返回下载链接。 ## 本地开发 / 测试 需要 `python-docx`、`markdown-it-py`、`mdit-py-plugins`、`PyYAML`（以及可选的 `pillow`/`httpx`）： ``` pip install python-docx pillow httpx markdown-it-py mdit-py-plugins PyYAML python examples/build.py # → examples/demo_report.docx ``` 该文件设计为可在 Open WebUI 内运行：`open_webui.*` 导入是可选的，当缺少这些导入时，该工具会优雅降级（方便进行独立的渲染测试）。 ## 贡献 欢迎提交 Issue 和 PR。请保持文件为**单文件**，并且核心功能不强制依赖网络。 ## 许可证 [MIT](LICENSE) © IANUSTEC

标签：Markdown, Open WebUI, python-docx, Word, 恶意代码分类, 插件工具, 文档生成, 逆向工具