humanize-ppt

Humanize PPT

当用户希望将原始材料、笔记、语音转录、文档或链接整理成可用于演示的提纲，并逐页确定媒体内容，再交由下游技能进行渲染时，请使用此技能。不会直接读取旧版 PPT/PPTX 文件：请先提取其中的文本（参见 scripts/pptx_qa.py 的 dump/inspect 输出），然后将文本作为 --source 输入。对于已由 Humanize PPT 渲染的演示文稿，请改用 --qa-from <rendered.pptx>，进行演示文稿检查，而非简报模式。

定位

Humanize PPT 是一套为演讲而生的演示系统：包含大纲导演（AST 受众状态迁移——每次翻页都会推动受众向前）、逐页视觉增强导演（真实图片／SVG 图表／Remotion 视频）、制作简报编排器、演示体检运行器（演讲体检；此前称为 QA 循环，CLI 标志仍为 --qa-from），以及演讲者模式交接。其设计初衷是：HTML-PPT 模板技能擅长概念展示，却会把一个简单想法扩展成十几页精美幻灯片，而一场真正的 90 分钟演讲通常只有约 30 页——精美的外壳跑在了内容密度前面。Humanize 弥合这一差距：它保留美感（由下游模板技能原生渲染），并让内容适合演讲——让演讲者能够站起来讲出来的一段内容。下游模板技能负责“渲染得漂亮”；Humanize 负责“这是场演讲，而且有人检查过”。

用一句话概括演示体检：它不评判美观程度，而是评判大纲。它会将每张渲染后的页面与对应的大纲页面进行比较，找出那些只能看、却无法据此演讲的页面，并持续检查，直到每一页都能让演讲者站起来讲述。用通俗的话说，未通过检查的页面是指：页面上只有寥寥几字，始终没能讲完要点；或者未能实现承诺的受众状态迁移（听众离开该页时的状态与进入时相同）。这样的页面不该存在；体检会将其找出并生成修复说明。

Humanize 广泛兼容能够处理纯 Markdown 和 JSON 的下游渲染器。已验证的路径包括：中文 HTML → guizang-ppt-skill；英文 HTML → frontend-slides / beautiful-html-templates；原生可编辑 PowerPoint → ppt-master。其他下游渲染器仍可热插拔；支持级别记录在 registry/renderer_registry.json 中，只有经过实际输出验证才会更新。

它在下游 PPT／HTML 幻灯片技能运行之前执行，并在渲染后的演示体检过程中提供支持。它负责 AST 约定、逐页媒体选择（这一页需要照片、系统图表、10 秒流程视频，还是不需要媒体？）、供下一个 Agent 使用的制作简报，以及对已渲染 HTML/PPTX 的体检。它不负责最终渲染出的演示文稿本身。

渲染前有两个人工审核环节：大纲预览和渲染器的风格审核。HTML 路径使用 Humanize 的至少包含 4 个真实封面的 --style-gallery。PPT Master 已有原生视觉预览的强制三阶段确认界面，因此 --renderer ppt-master --style-gallery 会委托给该审核环节，并写入 style_gallery_plan.json + commands/style-gallery/ppt-master-confirm-ui.md，而不是重复生成目录。

用户先调用一次 Humanize PPT 获取简报，再将简报交给下游技能进行原生渲染，然后再次调用 Humanize，并使用 --qa-from <rendered.html|native.pptx> 运行 3 轮演示体检。每轮都会写入 qa_report.md、fix_prompt.md 和 qa_iteration.json。完成 3 轮后仍有未通过项时，状态会变为 needs-human。

Humanize PPT 绝不会复制下游技能的模板、向其中注入自定义章节，也不会对渲染后的 HTML 或 PPTX 进行后处理。修复会交还给下游的源文件作者。请参阅 references/guizang-production-brief-orchestrator.md 和 adapters/ppt-master-bridge-notes.md。

对外介绍时，应将 Humanize PPT 描述为与原生下游渲染器配合使用的简报编排器。不要将其说成渲染器，也不要将其说成会替用户挑选最佳视觉风格的“路由器”——这项决定由简报、下游技能自己的模板以及人工审核共同完成。如果用户只想要一张漂亮的模板页面，那是渲染技能的工作，而不是 Humanize 的工作：说明这一选择，而不是加以禁止。

AST 理论

AST 是 Audience-State-Transfer（受众-状态-转变） 的缩写。

• Audience（受众）：谁在聆听，他们了解什么、排斥什么，以及他们为什么愿意继续听下去。
• State（状态）：演示文稿播放前后的受众状态，以及阻碍状态转变的核心矛盾。
• Transfer（转变）：逐页推进的路径，引导受众从初始状态转变为期望状态。

核心观点：

PPT 不是信息容器，而是推动受众状态转变的载体。

必需的输出约定

每次运行 Humanize PPT 时，都要生成：

1. deck_brief.md — 受众、目标、矛盾和成功标准。
2. ast_outline.md — AST 映射和叙事弧线。
3. slide_plan.json — 逐页规划，每页都包含 media: {image, diagram, video} 决策和 layout_hint。
4. speaker_intent.md — 演讲者在每页应采取的行动。下游技能会将其用作生成原生演讲者备注和演示者界面的依据。
5. asset_manifest.md — Humanize 对每页素材的决策：每页需要哪种素材（image / diagram / video），以及用途。
6. video_slots.json — 可选的 Remotion / HyperFrames / 原生视频插入计划。
7. style_brief.md — 下游制作的视觉原则。
8. renderer_registry.json — 本次运行的渲染器能力快照。
9. router_plan.json — 所选的主渲染器和分阶段路由计划。
10. commands/*.md — 为每个下游专业 Agent 提供的范围明确的指令。
11. run_manifest.json — 最终文件清单、路由状态和 QA 状态。
12. <renderer>-production-prompt.md — 下游入口。除 HTML 路由外，ppt-master 还会生成 ppt-master-production-prompt.md、自包含的 ppt-master-source.md，以及可丢弃的 outputs/ppt-master-handoff/ 副本。
13. outputs/qa/qa_report.md — 首轮 QA 门禁结果（简报模式）或各轮 QA 发现（QA 模式）。

QA 模式（渲染后）还会为每轮生成：

14. outputs/qa/fix_prompt.md — 可供下游技能执行的修复指令。
15. outputs/qa/qa_iteration.json — 轮次、状态（iterate / pass / needs-human）、未解决的问题和历史记录。

样式库模式（--style-gallery，大纲前置门禁）则会生成以下内容并停止：

16. HTML 路由：style_gallery.html，以及 ≥4 个封面条目。PPT Master 不会生成虚假的 HTML 样式库；样式选择保留在其原生 Confirm UI 中。
17. style_gallery_plan.json — HTML 的封面候选项，或 PPT Master 的 mode: downstream-confirm-ui。
18. commands/style-gallery/<id>.md — HTML 的封面指令，或原生门禁的 ppt-master-confirm-ui.md。

推荐的 OPC 工作流（v0.6.4）

O — Outline + Per-Page Media Direction
  Humanize PPT: raw material → AST outline + per-page media decision
  (deck_brief.md, ast_outline.md, slide_plan.json, speaker_intent.md,
   asset_manifest.md, video_slots.json, style_brief.md)

P — Native Renderer Invocation (100% downstream)
  zh  → guizang-ppt-skill        (Style A or B, native; recommended)
  en  → frontend-slides / beautiful-html-templates (native; recommended)
  pptx → ppt-master (native DrawingML; explicit --renderer ppt-master)
  other HTML-PPT skills → hot-pluggable, same brief contract
  Humanize emits the production prompt and stops. The downstream
  skill renders the deck. Humanize does NOT copy templates, does
  NOT inject SLIDES_HERE / [必填] replacements, does NOT add
  postMessage bridges to the rendered HTML.

Q — Presentation Checkup (演讲体检) on the rendered artifact
  Humanize --qa-from <rendered.html|native.pptx> reads the output of P,
  compares pages against the outline, scans for failure modes
  (references/qa-failure-modes.md), writes qa_report.md and
  fix_prompt.md, tracks iteration in qa_iteration.json.
  Cap: 3 rounds. After cap with remaining findings, status
  flips to needs-human.

C — Complete / Control
  Downstream skill native speaker notes + presenter shell + deploy
  (Humanize does not own these in v0.6.4 — the brief tells the
  next agent to produce them in the downstream skill's own format)

规则

v0.6.4 不变量（这些是硬性规则；违反其中任何一条，就超出了 v0.6.4 的边界）

1. Humanize 仅生成简报。 它负责编写渲染器生产契约，然后就此结束。它不会打开、复制或后处理下游模板或最终 HTML/PPTX。
2. 下游渲染器完全原生。 下一个 Agent 遵循下游技能自己的 SKILL.md。简报会告知下一个 Agent 要加载哪项技能、使用哪种 Style（A/B）、从哪些布局中选择，以及必须通过哪些 QA 门槛——但不会包含模板内部细节。
3. 演示文稿检查最多迭代 3 轮。 到第 4 轮仍有未通过的发现时，状态为 needs-human。循环不会无限运行，而是将决策交还给人工。
4. 演讲者备注和演示者外壳——Humanize 生成基线版 presenter-shell.html；下游负责完整演示界面。 Humanize 负责语义源文件（speaker_intent.md），现在还会直接根据 slide_plan.json + speaker_intent.md 写入 outputs/presenter/presenter-shell.html（可独立使用，即使下游演示文稿尚未生成）。下游技能负责生成原生演讲者备注和更完整的演示者控制台。Humanize 不会向渲染后的 HTML 注入 postMessage 桥接或 ?slide= URL 参数。
5. 生产提示词是下游入口。 它列明渲染器必须读取的所有支持材料。PPT Master 还会读取 ppt-master-source.md，以固定 Humanize 的页面故事和备注意图，而不重复 PPT Master 的视觉契约。

工作规则

6. 如果 Humanize PPT 能先生成 AST 契约，就不要让幻灯片渲染器直接使用原始材料。
7. 完整演示界面的负责人应始终是下游技能；Humanize 的 presenter-shell.html 是可用的基线，而非原生控制台的替代品。
8. 吸收 humanizer 工具中的 AI 写作清理原则，但不要把 Humanize PPT 简化为文本润色。
9. 优先采用经过验证的小型工作流，而不是未经验证的宽泛承诺。
10. 发布公开 Skill 时，应创建并推送代码仓库，在本地从 GitHub 安装，运行一个安全的完整示例，在经过验证的已知良好检查点（examples/03-codex-guizang-native-ink-classic/）上验证简报和演示文稿检查，然后才润色 README 细节。
11. 开发 Agent Teams 时，在接入真实下游 Skill 之前，先生成 router_plan.json、run_manifest.json、受限的 commands/*.md 以及每个渲染器的生产提示词。
12. 为 WorkBuddy/CodeBuddy 团队上传包打包时，不要将演示或渲染后的 HTML 输出打包进团队 zip。上传 zip 必须采用类似 trading-team 的团队插件结构：根目录包含 .codebuddy-plugin/plugin.json、agents/、skills/、rules/ 和 setting.json（还可选包含 avatars/、.workbuddy-plugin/、README.md、settings.json）。rules/ 目录应包含场景规则文件，例如 rules/<plugin-name>_rules.md，其中带有 frontmatter（description、alwaysApply、enabled、updatedAt、provider）和 <system_reminder> 块，用于说明可用的 Agent、技能、SOP 和使用要求。通过 unzip -l 验证根目录不是 index.html/assets/screenshots/source，也没有被文件夹包裹，除非目标上传器明确要求使用包装目录。
13. 不要把 HyperFrames/Remotion 视频当成取代 PPT 内容的单个嵌入式播放器。对于 Humanize PPT 交付物，视频工具是素材制作工具：用于转场、讲解片段、前后对比、讲解素材插入、社交媒体预览和备用静帧，以满足特定页面需求。每页的 media.video 决策（参见 slide_plan.json 模式）会告知下游技能哪些页面需要 Remotion 片段、片段的用途和时长。

运维参考

• references/guizang-production-brief-orchestrator.md — 规范性简报说明：<renderer>-production-prompt.md 必须包含和不得包含的内容。
• references/qa-failure-modes.md（以及英文镜像 references/qa-failure-modes.en.md）— 演示文稿检查中的失败模式目录；代码侧的权威来源是 scripts/humanize_ppt_v2.py 中的 FAILURE_MODES。
• references/style-gallery-spec.md — --style-gallery 封面样式关卡。
• references/renderer-guidance.md — 各渲染器推荐路径和已知良好检查点规则。
• references/renderer-verification.md — 各渲染器的验证证据，为 frontmatter 中的一行说明提供依据。
• adapters/ppt-master-bridge-notes.md — 原生 PPTX 路线边界和 OOXML 检查约定。
• SPEC.md — 引擎技术规范：CLI 接口、数据流、输出约定、样式库、检查、媒体模型、渲染器注册表。
• 所有参考资料、适配器、版本说明和辅助脚本的完整注释索引：docs/index.md。

本地演示

推荐的稳定入口是 scripts/humanize_ppt.py（带版本号的脚本仍作为兼容性垫片）。完整的 CLI 示例——简报模式、演示文稿检查、原生 PPTX、大纲预览、旧版入口——见 docs/local-demo.md。

--out 警告： 请将 --out 指向专用的运行目录。简报模式每次运行都会从头重建该目录，但只有在目录不存在、为空，或根目录中已包含上一次 Humanize PPT 运行的标记（run_manifest.json / style_gallery_plan.json / outline-preview.md / preview-confirmed.json）时，才会自动清空目录；否则会拒绝执行，并要求使用 --force。