# doc-to-ppt-skill **Repository Path**: BraveCao/doc-to-ppt-skill ## Basic Information - **Project Name**: doc-to-ppt-skill - **Description**: Commercial doc-to-ppt Codex skill with editable PPT generation, visual QA, content QA, Yongxin brand pipeline, and image2 gating. - **Primary Language**: HTML - **License**: AGPL-3.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-06-14 - **Last Updated**: 2026-07-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # doc-to-ppt `doc-to-ppt` 是一个 Codex Skill,用于把 Markdown、TXT、DOCX、PDF 或纯文本源文档转换为经过审核的图片型 PowerPoint 演示稿。 这个项目的目标不是简单“把文字搬进 PPT”,而是建立一条可控的商业交付流水线:先解析和审计源文档,再由 LLM 做编辑型分页,用户确认设计方向后,通过 Codex `image_gen` 或 OpenAI 兼容的 image2 端点生成高保真页面原型,经过人工审核后,再把审核通过的页面图组装成最终 PPTX。 ## 核心能力 - 将源文档转换为可追溯的幻灯片规划。 - 强制使用 LLM 编辑型分页,禁止退回到规则式段落切片。 - 在视觉生成前收集并校验用户确认的 VI / 设计简报。 - 先生成前 5 页样稿,人工确认后再生成全量页面。 - 支持 Codex `image_gen` 队列模式,也支持用户明确批准后的付费 image2 生成。 - 每页使用一张人工确认的高保真页面图,最终组装为 `output.pptx`。 - 支持视觉、内容、字体、品牌和发布就绪检查。 - 内置永信至诚 / Integrity Technologies 官方模式,品牌资产与 QA 规则独立隔离。 ## 目录结构 ```text doc-to-ppt/ SKILL.md Codex 使用的 Skill 主说明 skill-cn.md 中文操作说明 README.md 项目使用说明 .secrets/image2.local.json 可同步的 image2 配置模板,不含真实密钥 agents/ Agent 配置 assets/ brand-kits/yongxin/ 永信至诚品牌资产、logo、模板参考和提取媒体 sample-inputs/ 示例输入和示例规划 references/ 工作流、QA、提示词、VI 和内容规则 scripts/ 流水线、审计、渲染和工具脚本 ``` ## 运行环境 必需项: - Python 3.10+ - 脚本依赖的 Python 包,例如 `python-docx`、`Pillow`、`pypdf`、`pdf2image`、`reportlab` - 执行 Playwright 视觉检查时需要 Node.js - 一个 OpenAI 兼容的 `chat/completions` 文本模型,用于强制 LLM 编辑型分页 推荐项: - Playwright Chromium,用于浏览器视觉 QA - LibreOffice、Keynote、PowerPoint 或其他 PPTX 预览导出工具 - Poppler 工具,例如 `pdftoppm`,用于 PDF 渲染 - Tesseract,用于 OCR 方式检查最终页面可见文本 - image2 兼容图片生成端点,用于高保真 PPT 页面原型生成 环境检查: ```bash python3 doc-to-ppt/scripts/environment_check.py \ --out environment_report.json ``` 如果准备使用 image2,可以只验证 `/models` 连通性,不生成图片、不消耗额度: ```bash python3 doc-to-ppt/scripts/environment_check.py \ --check-image2-network \ --image2-config doc-to-ppt/.secrets/image2.local.json \ --out environment_report.json ``` 如果缺少依赖,先生成 dry-run 安装计划: ```bash python3 doc-to-ppt/scripts/bootstrap_dependencies.py \ --include-optional \ --out dependency_bootstrap_report.json ``` 不要静默执行 `--install`。只有用户明确同意安装计划后,才允许执行真实安装。 ## 配置说明 ### LLM 分页模型 主流水线需要文本 LLM 完成编辑型分页。可以通过环境变量配置: ```bash export DOC_TO_PPT_LLM_BASE_URL="https://api.openai.com/v1" export DOC_TO_PPT_LLM_API_KEY="your-text-llm-key" export DOC_TO_PPT_LLM_MODEL="your-text-llm-model" ``` 也可以通过命令行参数传入: ```bash --llm-api-base --llm-api-key --llm-model ``` ### image2 配置 可同步到仓库的模板文件是: ```text doc-to-ppt/.secrets/image2.local.json ``` 该文件只放占位值,不应写入真实地址和真实 key: ```json { "base_url": "请填写服务器地址", "api_key": "请填写Api-Key", "model": "gpt-image-2", "endpoint": "images_generations", "response_format": "b64_json", "quality": "high" } ``` 真实生成前,可以在本地替换 `base_url` 和 `api_key`,也可以使用环境变量: ```bash export IMAGE2_BASE_URL="https://your-image-api.example/v1" export IMAGE2_API_KEY="your-image-api-key" export IMAGE2_MODEL="gpt-image-2" ``` 付费 image2 生成默认被阻断。只有用户明确批准当前任务可以使用付费图片生成时,才允许添加 `--allow-paid-image2`。 ## 通用 PPT 生成流程 标准交互流程如下: 1. 检查运行环境。 2. 摄取源文档。 3. 构建并执行 LLM 编辑型分页。 4. 审计分页细节,并让用户确认分页方案。 5. 收集 VI / 设计简报。 6. 构建并生成前 5 页页面原型。 7. 等待用户审核前 5 页样稿。 8. 生成全量页面原型。 9. 等待用户审核全量页面。 10. 将审核通过的页面图组装为 `output.pptx`。 11. 执行预览导出、视觉 QA、内容 QA、字体 QA、设计质量判断和统一 QA。 通用入口: ```bash python3 doc-to-ppt/scripts/orchestrate_ppt_generation.py \ --source path/to/source.docx \ --workdir doc-to-ppt-output \ --llm-api-base "$DOC_TO_PPT_LLM_BASE_URL" \ --llm-api-key "$DOC_TO_PPT_LLM_API_KEY" \ --llm-model "$DOC_TO_PPT_LLM_MODEL" \ --prototype-provider image_gen ``` 用户明确批准后使用 image2: ```bash python3 doc-to-ppt/scripts/orchestrate_ppt_generation.py \ --source path/to/source.docx \ --workdir doc-to-ppt-output \ --llm-api-base "$DOC_TO_PPT_LLM_BASE_URL" \ --llm-api-key "$DOC_TO_PPT_LLM_API_KEY" \ --llm-model "$DOC_TO_PPT_LLM_MODEL" \ --prototype-provider image2 \ --image2-config doc-to-ppt/.secrets/image2.local.json \ --allow-paid-image2 ``` 对于 `gpt-image-2` 的 16:9 PPT 页面,流水线默认将输出尺寸映射为 `2560x1440`。 ## 永信至诚官方模式 当 PPT 需要遵循永信至诚 / Integrity Technologies 官方 VI 时,使用专用快捷入口: ```bash python3 doc-to-ppt/scripts/orchestrate_yongxin_ppt.py \ --source path/to/source.docx \ --workdir yongxin-ppt-output \ --llm-api-base "$DOC_TO_PPT_LLM_BASE_URL" \ --llm-api-key "$DOC_TO_PPT_LLM_API_KEY" \ --llm-model "$DOC_TO_PPT_LLM_MODEL" ``` 该模式会固定永信官方黑/白/黄 VI、logo 处理方式、字体风格提示词和禁用风格。永信品牌资产、模板相似度检查和品牌 QA 必须与通用流水线保持隔离。 ## 重要脚本 - `scripts/environment_check.py`:检查 Python、Node、预览/OCR 工具,以及可选 image2 `/models` 连通性。 - `scripts/bootstrap_dependencies.py`:生成 dry-run 依赖安装计划。 - `scripts/ingest_document.py`:将源文件转换为 `document_outline.json`。 - `scripts/build_llm_pagination_prompt.py`:构建强制 LLM 编辑型分页提示包。 - `scripts/run_llm_pagination.py`:调用配置好的 `chat/completions` 模型并输出 `llm_pagination_plan.json`。 - `scripts/plan_presentation.py`:根据 LLM 分页结果生成可追溯的幻灯片计划。 - `scripts/audit_pagination_detail.py`:阻断薄内容、泛标题、缺 source_id、漏掉 must_keep 的分页结果。 - `scripts/collect_vi_design_brief.py`:收集并校验用户确认的 VI / 设计简报。 - `scripts/build_multimodal_prototype_prompts.py`:构建每页的高保真原型生成提示词。 - `scripts/generate_multimodal_prototypes.py`:排队 `image_gen` 或执行 image2 原型生成。 - `scripts/audit_multimodal_design_review.py`:强制执行样稿和全量页面的人审门禁。 - `scripts/build_image_pptx_from_prototypes.py`:将审核通过的页面图组装成最终 PPTX。 - `scripts/preview_export.py`:导出预览图片和 `preview.html`。 - `scripts/audit_design_judge.py`:执行商业精美度检查。 - `scripts/audit_content_coverage.py`:检查源文档到幻灯片的内容覆盖。 - `scripts/audit_rendered_content.py`:检查最终渲染页面的可见内容,可选 OCR。 - `scripts/audit_font_compatibility.py`:检查 macOS / Windows 字体兼容。 - `scripts/audit_brand_style.py`:永信品牌风格检查。 - `scripts/audit_yongxin_template_similarity.py`:永信官方模板视觉结构相似度检查。 - `scripts/audit_ppt.py`:生成统一 QA 报告。 - `scripts/repair_plan.py`:根据失败 QA 生成可执行修复计划。 - `scripts/release_quality_check.py`:快速语法、入口和 Skill 有效性检查。 ## 质量门禁 在必要报告通过前,不应把 PPT 标记为完成。不可用的检查必须明确记录,并在交付说明中提示用户。 硬性要求包括: - 只允许 LLM 编辑型分页,不允许规则式切片兜底。 - `must_keep` 源内容覆盖率必须达到 100%。 - `should_keep` 源内容覆盖率至少达到 85%。 - 不允许改写关键数字、日期、金额、人名、机构名或结论。 - 页面原型设计前必须有用户确认的 VI 简报。 - 前 5 页样稿必须经过人工确认后,才能生成全量页面。 - 全量页面必须经过人工确认后,才能组装最终 PPTX。 - 最终 PPTX 必须视觉上保留审核通过的高保真页面图。 - 禁止使用隐藏文本、画布外文本、1pt 小字或角落堆字来伪造内容覆盖率。 - 付费 image2 必须在用户明确批准后才能调用。 ## 发布检查 代码或文档变更后,运行快速发布检查: ```bash python3 doc-to-ppt/scripts/release_quality_check.py ``` 如果修改了渲染、规划、QA 或模板相关逻辑,运行回归套件: ```bash python3 doc-to-ppt/scripts/run_regression_suite.py ``` 如果变更可能影响永信官方链路,加入永信回归: ```bash python3 doc-to-ppt/scripts/run_regression_suite.py --include-yongxin ``` ## 安全说明 - 不要提交真实 API Key、生产网关地址、客户源文档、含私密内容的生成结果或付费生成输出。 - `doc-to-ppt/.secrets/image2.local.json` 只是仓库模板。真实值应保存在本地,或通过环境变量注入。 - 如果需要把文档内容发送给第三方图片端点,必须先确认该端点是当前源文档允许使用的可信目的地。 - `/models` 验证只代表连通性,不代表已经批准外部数据传输。 - `.secrets/` 目录默认忽略所有文件,只放行无密钥模板 `image2.local.json`。真实备份文件不要取消忽略。 ## 常见输出产物 典型工作目录会包含: - `document_outline.json` - `design_brief.json` - `llm_pagination_prompt.json` - `llm_pagination_plan.json` - `presentation_plan.json` - `pagination_detail_report.json` - `vi_design_brief.json` - `multimodal_prototype_prompts_sample.json` - `multimodal_prototypes_sample_report.json` - `prototype_sample_review_pack.md` - `multimodal_design_sample_review_report.json` - `multimodal_prototype_prompts.json` - `multimodal_prototypes_report.json` - `prototype_full_review_pack.md` - `multimodal_design_review_report.json` - `output.pptx` - `delivery_manifest.json`