LearnPrompt/humanize-ppt · 上手攻略
- 仓库：LearnPrompt/humanize-ppt
- 链接：https://github.com/LearnPrompt/humanize-ppt
- 分类：presentation · AI-workflow
- 作者：Tom
- 更新：2026-08-13
它是什么
Humanize PPT 是一个专为演讲场景设计的 AI PPT 工作流 Skill，面向 Claude Code / Codex / Hermes 等 Agent。它的核心定位不是"渲染好看的模板"，而是补足模板库不管的环节——把一份资料编排成一条能让观众跟着走的演讲线。
与直接套模板的路径（资料 → 模板 → 渲染 → 交付）不同，Humanize 在渲染前插入三层处理：AST 大纲编排、媒体决策（何时配图/视频/SVG）、自动演讲体检，最终把渲染交接给下游模板库（guizang-ppt-skill / ppt-master / beautiful-html-templates 等）产出最终 deck。
⚠️ 注意：Humanize 不产出最终渲染文件，它输出的是 AST 大纲 + 渲染 brief + 演讲体检报告，渲染交给下游 Skill。
解决什么问题
普通 PPT Skill 的失败模式：资料铺成十几页好看的 HTML，听众看完只知道"这个工具很好用"，但讲的人说不出一条逻辑线。问题根源是把信息容器当演讲媒介用，忽略了"每翻一页、观众状态是否真的推进"。
Humanize 解决三个具体问题：
- 无结构：资料直接进模板，没有"观众是谁、看完要变成什么状态"的编排
- 无素材决策：模板库自己决定要不要配图，AI 随机出图、图不对题
- 无质量门：渲染完直接交付，没有"哪几页只能看不能讲"的检查机制
快速安装
# 方式一：发给 Agent 直接装
请安装 Humanize PPT Skill：https://github.com/LearnPrompt/humanize-ppt
# 方式二：npx 安装
npx skills add LearnPrompt/humanize-ppt -g
# 方式三：Claude Code plugin marketplace
/plugin marketplace add LearnPrompt/humanize-ppt
/plugin install humanize-ppt
# 下游渲染 Skill（按需安装）
# 中文 deck
npx skills add op7418/guizang-ppt-skill -g
# 英文 deck（viewport-safe HTML）
npx skills add zarazhangrui/frontend-slides -g
# 原生可编辑 PPTX
npx skills add hugohe3/ppt-master -g
# 配图（本地 Codex CLI，无需 API key）
npx skills add JimLiu/baoyu-skills/baoyu-image-gen -g
核心用法
最小可跑命令
# 前置：装好 humanize-ppt + guizang-ppt-skill
# 资料准备：把材料写成 source.md
# 一句话启动全流程：
# "用 humanize-ppt 把这份材料做成中文演讲 PPT：先出 AST 大纲和每页意图，按大纲调 guizang-ppt-skill 原生渲染，配图用 baoyu-image-gen，渲染完跑一遍演讲体检告诉我哪几页只能看不能讲，最后出演讲模式。"
# CLI 手动分阶段（可选）：
python3 scripts/humanize_ppt.py \
--source examples/01-ai-tool-update/source.md \
--out .humanize-ppt-runs/ai-tool-update \
--title "AI 工具更新，不只是功能清单" \
--renderer guizang \
--guizang-style A \
--guizang-theme ink-classic
⚠️ 环境要求：Python 3.10+（部分系统 python3 仍为 3.9，不能只看命令名）。下游渲染器各自独立安装。
AST 大纲（核心）
AST = Audience-State-Transfer（观众状态转移）。Humanize 基于 70+ TED 演讲的结构规律，生成逐页"观众进入状态 → 本页意图 → 离开状态"大纲。不是把资料切页，而是编排"每翻一页观众多懂一点"的那条线。
媒体决策
逐页决定要不要图 / SVG 图表 / 视频，写入 slide_plan.json 的 media 槽（含 asset_path + prompt_hint），下游按路径产出真实文件：
- 配图 → baoyu-image-gen（本地 Codex CLI，gpt-image，无需 API key）
- 视频 → Remotion（确定性 mp4，无旁白）
- 图表 → 确定性内联 SVG / HTML
演讲体检
渲染结束后自动 QA，检查失败模式（页码徽章遮挡、文字溢出等），输出 qa_report.md + fix_prompt.md。3 轮封顶，不收敛标 needs-human。
# 对已有渲染结果跑体检
python3 scripts/humanize_ppt.py \
--qa-from <rendered.html> \
--out <之前的 out 目录> \
--renderer guizang \
--guizang-style A \
--max-qa-iterations 3
演讲模式
从 slide_plan.json + speaker_intent.md 直接产出 presenter-shell.html：左边当前页放大 + 计时器，右边是本页演讲稿、提词（cues）、下一页预览、整场页目录。
典型适用场景
- 产品发布会 / 技术分享：需要一条清晰的逻辑线，不是功能清单堆砌
- 学术报告：需要把论文核心贡献翻译成"观众能跟上的节奏"
- 内部培训：大量知识需要按认知梯度编排，不是把文档贴上去
- Agent 团队协作：Humanize 出 AST，下游 ppt-master 渲染成 PPTX，交付原生可编辑文件
坑与注意
| 坑 | 说明 |
|---|---|
| Python 3.9 兼容 | 部分系统 python3 仍是 3.9，Humanize 会自动探测并写进 handoff；固定环境时用 --ppt-master-python 指定 |
| 体检只能扫渲染后 | 演讲体检依赖渲染产物，裸 AST 大纲无法 QA |
| 下游 Skill 独立装 | Humanize 只管编排，guizang / ppt-master / beautiful-html-templates 需各自独立安装 |
| 媒体生成需额外 key | baoyu-image-gen 走本地 Codex CLI（已登录 ChatGPT 订阅）；Remotion 需 ffmpeg + Node.js |
| 风格画廊停在渲染前 | --style-gallery 出封面候选后暂停，不自动渲染，由用户选完再出完整 deck |
| PPTX 路径需 ppt-master | --renderer ppt-master 生成 ppt-master-production-prompt.md，需配合 ppt-master Skill 渲染 |
⚠️ 风险边界：Humanize 本身不处理最终渲染，最终 deck 质量依赖下游渲染 Skill 的能力。PPT Master 原生导出已验证（10 页 399 个可编辑容器、notes、Fade 转场），guizang 有 7 条专属失败规则，英文路线（frontend-slides / beautiful-html-templates）规则较少。
与同类对比
| 维度 | 直接套模板 | Humanize PPT |
|---|---|---|
| 起点 | 资料直接进模板 | 先问观众是谁、看完变成什么状态 |
| 密度 | 一个概念铺成十几页 | 编成一条能讲的线 |
| 素材 | 模板自带什么用什么 | 逐页决定图/SVG/视频，写计划交下游产 |
| 渲染 | 自己渲染 | 交给下游模板库原生渲染 |
| 质量门 | 渲染完即交付 | 自动演讲体检 3 轮，输出 fix prompt |
Humanize 是渲染的下游，不是竞品。模板库负责"渲染得好看"，Humanize 负责"能讲、有人盯、能上台"。
一句话推荐结论
如果你需要的是"资料铺成好看 deck"——直接用 guizang-ppt-skill / ppt-master。如果你需要的是"让观众跟着走的那条线"——先跑 Humanize，再接下游渲染。
原始仓库：https://github.com/LearnPrompt/humanize-ppt