Claw-Empire 报告与 PPT 生成实战:AI 完成报告、报告历史钻取与 PptxGenJS 导出原理
Claw-Empire 报告与 PPT 生成实战:AI 完成报告、报告历史钻取与 PptxGenJS 导出原理
Claw-Empire 是一个本地优先(local-first)的 AI Agent 办公室模拟器,它把 Claude Code、Codex CLI、Gemini CLI 等 CLI/OAuth/API Agent 编排成一家虚拟自主公司。本文带你实战它的两大"办公生产力"功能:AI 自动生成报告 与 一键 PPT 导出——从发起报告请求、在报告历史中逐层钻取团队详情,到幕后用 HTML 幻灯片 + PptxGenJS 生成标准 .pptx 文件的完整原理,一篇讲清楚。
报告功能全景:一条流水线,从请求到 .pptx
在 Claw-Empire 中,"写报告"不是一次聊天,而是一条完整的任务流水线:
- 发起请求:在聊天窗口点击 Report Request 按钮并输入请求内容;
- Pack 路由:内置
report、web_research_report等工作流 Pack(见 definitions.ts),按关键词自动匹配路由结构与输出模板; - 团队执行:规划、开发、设计、QA 等部门 Agent 协作,产出执行结果、报告消息与 Markdown/幻灯片文件;
- 设计确认(可选):设计部 Agent 会先对 HTML 幻灯片做一轮视觉质检(见 report-workflow-tools.ts 中的
startReportDesignCheckpoint); - PPT 导出:最终将 HTML 幻灯片转换为 PowerPoint 文件,归档到
docs/reports/; - 报告弹窗 + 历史入库:任务完成后,前端弹出报告详情弹窗,同时报告进入"报告历史",可随时回看。
任务在看板中的流转状态可以在任务面板直接观察到:
报告历史钻取:三层结构逐层深入
报告完成后的"考古"体验来自三层钻取结构,全部数据存在本地 SQLite:
第 1 层:历史列表(按项目分组)
打开报告历史弹窗,已完成的根任务报告会按项目自动分组,每组内再分页展示,每条记录显示负责 Agent、部门与完成时间。这一层的界面逻辑在 ReportHistory.tsx,对应后端接口为 GET /api/task-reports(只查 status = 'done' 的根任务,最新 50 条,实现在 task-reports/routes.ts)。
第 2 层:团队报告详情
点击任意一条记录,进入报告详情弹窗(TaskReportPopup.tsx)。它通过 GET /api/task-reports/:taskId 返回一整棵"报告树":
- Planning 汇总页签:规划负责人的整合摘要(Consolidated Summary)及其文档列表;
- 各团队页签:每个协作子任务一节,含执行结果、报告消息、任务日志、会议纪要与产出文档;
- 文档钻取:后端会智能从任务描述、执行结果、日志中提取
.md / .pptx / .pdf等文件路径并读取内容(见 helpers.ts),Markdown 文档排最前、二进制文件(如 .pptx)显示为可识别条目; - 归档刷新:点击刷新按钮会调用
POST /api/task-reports/:taskId/archive,让规划负责人重新生成一份整合归档。
第 3 层:过程留痕
详情中还能看到该任务关联的会议纪要(meeting_minutes 表按轮次拼接发言)与任务日志,完整还原"谁在什么时候做了什么"。会议纪要在报告中的呈现示例:
前端 API 封装在 providers-reports-github.ts,getTaskReports / getTaskReportDetail / archiveTaskReport 三个函数即对应上述接口。
PPT 生成原理:HTML 幻灯片 + PptxGenJS 导出
这是 Claw-Empire 最有意思的工程细节。它并不让 AI 直接"画"PPT,而是走"HTML 先排版,再程序化导出"的路线:
步骤 1:AI 写 HTML 幻灯片
报告 Agent 先在工作区(如 docs/reports/...-slides/)产出一组 slide-01.html、slide-02.html……每张幻灯片就是一个 16:9 的 HTML 页面。仓库中 slides/ 目录保留了完整的 12 页样例,示例产物可打开 PPT_Sample.pptx 对比效果。
步骤 2:Playwright 渲染 + 元素级转换
html2pptx.cjs 是核心转换库,思路是:
- 用 Playwright(Chromium 无头浏览器)加载每张 HTML 幻灯片;
- 读取
body计算尺寸,严格校验与演示文稿布局是否一致、内容是否溢出(溢出会直接报错提示); - 解析页面中的文本、图片、形状、列表等元素及其坐标,按
0.75 pt/px换算成 PowerPoint 坐标,逐一写入 PptxGenJS 的addSlide()。
入口脚本 generate-pptx.mjs 设置 pres.layout = "LAYOUT_16x9",遍历全部幻灯片文件后调用 pres.writeFile() 输出 .pptx。
步骤 3:截图兜底方案
如果元素级转换遇到 CJS/ESM 兼容问题,还有备选方案 convert-slides.mjs:用 Playwright 把每张 HTML 按 body 尺寸截成高清 PNG,再以 100% 铺满图片的形式插入 PptxGenJS 幻灯片。牺牲文本可编辑性,换取"所见即所得"的还原度——一个非常实用的降级策略。
最终生成的 PPT 效果示例:
自己动手:快速上手清单 📋
| 目标 | 入口 |
|---|---|
| 发起一份报告/PPT 请求 | 聊天窗口 → Report Request 按钮 |
| 查看报告历史与详情 | 报告弹窗 / 报告历史(ReportHistory.tsx) |
| 参考 HTML 幻灯片样例 | docs/reports/Sample_Slides |
| 参考构建脚本 | build-pptx.mjs、html2pptx.cjs |
| 了解报告工作流 Pack | packs/definitions.ts |
| 了解报告归档与流程 | report-workflow-tools.ts、task-reports/routes.ts |
总结:为什么这套设计值得借鉴 🎯
Claw-Empire 的"报告 + PPT"方案给出了 AI 办公自动化的一个务实答案:
- AI 负责内容与排版(HTML),程序负责格式(.pptx)——HTML 是 LLM 最擅长输出的格式,而 PptxGenJS 保证导出文件在 PowerPoint/WPS 中打开零兼容问题;
- 报告不是死数据,而是可钻取的任务树——项目分组、团队页签、会议纪要、文件归档层层展开,审计友好;
- 校验前置:尺寸不匹配、内容溢出都在导出前报错,避免产出"半页文字"的坏 PPT。
对于想给自己的 AI Agent 项目加"汇报能力"的开发者,这条 请求 → Pack 路由 → 多 Agent 协作 → 设计质检 → HTML 幻灯片 → PptxGenJS 导出 → 报告历史归档 的流水线,几乎可以直接照抄。




