LearnPrompt/humanize-ppt · 上手攻略

• 仓库：LearnPrompt/humanize-ppt
• 链接：https://github.com/LearnPrompt/humanize-ppt
• 分类：claude-code-skill
• 作者：Tom
• 更新：2026-08-13

是什么

Humanize PPT 是一个 AI Agent Skill（Codex / Claude Code / Hermes 等），核心功能是把任意资料编排成一条"能上台讲"的演讲线，而不是一堆"只能看"的漂亮页面。它不做渲染，而是指挥下游渲染 skill 出图出视频，编排完后跑自动演讲体检，最后交付演讲模式或原生 PPTX。

它的核心理论叫 AST（Audience-State-Transfer，观众状态转移）：每翻一页幻灯片，都应该推动观众从"不知道"走向"知道了"，而不是堆砌信息。

解决什么问题

AI PPT skill 能渲染出漂亮的 HTML 页面，但漂亮≠能讲。常见问题是： - 一个简单概念铺成十几页，页是漂亮的，话是接不上的 - 页码徽章遮挡正文、字体溢出、视觉元素打架——这些"只能看不能讲"的页混在里面 - 没有演讲稿，观众不知道每页该讲什么、怎么过渡

Humanize PPT 的分工很清晰：下游渲染器负责画好看，Humanize 负责让它能讲。

快速安装

方式一：直接发给 Agent（最简单）

把这句话发给 Codex / Claude Code / Hermes：

请安装 Humanize PPT Skill：https://github.com/LearnPrompt/humanize-ppt

Agent 会自动安装并加载。

方式二：npx 一行

npx skills add LearnPrompt/humanize-ppt -g

方式三：Claude Code plugin marketplace

/plugin marketplace add LearnPrompt/humanize-ppt
/plugin install humanize-ppt

下游渲染 Skill（按需安装）

Humanize 只负责编排，不负责渲染。实际渲染需要配下游 skill：

配图需要：baoyu-image-gen（JimLiu/baoyu-skills，走本地 Codex CLI，无需 API key） 视频需要：remotion-video-production + remotion-best-practices

核心用法

最小可跑命令

准备好 source.md（演讲资料）和一个下游渲染 skill 后，一条话全流程跑完：

中文 HTML deck：

用 humanize-ppt 把这份材料做成中文演讲 PPT：先出 AST 大纲和每页意图，
按大纲调 guizang-ppt-skill 原生渲染，配图用 baoyu-image-gen、视频用 remotion，
渲染完跑一遍演讲体检告诉我哪几页只能看不能讲，最后出演讲模式。

原生 PPTX：

用 humanize-ppt 先定 AST，再调 ppt-master 原生渲染，
最后把 PPTX 回灌演讲体检。

CLI 分阶段使用（进阶）

# 1. 生成 AST 大纲和渲染 prompt
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

# 2. 渲染后跑演讲体检（3 轮封顶）
python3 scripts/humanize_ppt.py \
  --qa-from <渲染好的.html> \
  --out .humanize-ppt-runs/ai-tool-update \
  --renderer guizang --max-qa-iterations 3

# 3. 生成风格画廊（4 个封面候选）
python3 scripts/humanize_ppt.py \
  --source examples/01-ai-tool-update/source.md \
  --out .humanize-ppt-runs/ai-tool-update \
  --renderer guizang --style-gallery

演讲体检（Presentation Checkup）

渲染完成后，Humanize 会自动扫页，对比渲染结果与 AST 大纲的差异，输出： - qa_report.md：每页的体检结果 - fix_prompt.md：给下游 skill 的修复指令 - qa_iteration.json：迭代记录

体检会检查：文字溢出、徽章遮挡、低对比度、英文断词、字体契约缺失、图片 alt 缺失等失败模式。v1.1 PPT Master 路径还会检查 OOXML 包、页数、可编辑对象、speaker notes、AST 漂移、关系和转场。

⚠️ 视觉遮挡类问题（如页码徽章遮挡正文）静态扫描测不出，靠截图复核兜底——这是已知的"测不出的失败类"，目录里如实标注了。

典型适用场景

1. 学术报告 / 会议演讲：先有论文或资料，想生成能上台讲的结构，配合 ppt-master 输出原生 PPTX
2. 产品演示 / 技术分享：需要图 / SVG 图表 / 视频配合，baoyu-image-gen + remotion 填媒体槽
3. 教学课件：逐页决定要不要画面，演讲体检确保每页"拿得出口"
4. Agent 团队协作：Humanize 编排，guizang/ppt-master 渲染，baoyu 出图，分工明确
5. 把老 PPT 重新编排：导入现有 PPT 内容，用 AST 重新组织成能讲的线

坑与注意

⚠️ Humanize 不渲染，它只指挥

Humanize 生成的 guizang-production-prompt.md 或 ppt-master-production-prompt.md 需要交给对应 skill 执行。不要在 Humanize 里后处理 HTML。

⚠️ Python 版本要求

Humanize 会自动探测 Python 3.10+，但系统 python3 可能仍是 3.9（macOS 预装版本）。需要确认：

python3 --version  # 需 >= 3.10

可用 --ppt-master-python <path> 指定解释器路径。

⚠️ 本机写入上限 ~1 MB

local_file_write 等工具受 Chrome native messaging 限制，单次上限约 1 MB，超大内容分块写入。

⚠️ 媒体槽需要真实资产

slide_plan.json 里的 media 槽（配图/视频/图表）是真实任务，不是占位符： - 配图：baoyu-image-gen（本地 Codex CLI，无需 key） - 视频：Remotion 渲染确定性 mp4 - 图表：确定性内联 SVG/HTML

氛围/概念/hero 图用图像模型出；数据、指标、流程等带精确文字数字的图用确定性 SVG（图像模型会糊字）。

⚠️ Move 操作的注意事项（如果用到 ZotMoov 场景）

本 skill 与 ZotMoov 完全无关，但如果你同时管理大量 PDF 附件，ZotMoov（见另一篇攻略）是更好的附件管理方案，Humanize 只处理演讲编排。

与同类对比

一句话：模板库负责"渲染得好看"，Humanize 负责"能讲、有人盯、能上台"。它们是上下游，不是竞品。

一句话推荐结论

如果你需要 AI Agent 帮你做能上台讲的 PPT——而不是一堆只能看的漂亮页——Humanize PPT 是目前把 AST 理论、工程化演讲体检和下游渲染分工结合得最好的方案。装好 humanize-ppt + guizang-ppt-skill（或 ppt-master），一条 prompt 就能跑完整条链路；演讲体检能自动揪出页码遮挡等问题，比人肉一页页检查省太多。