humanize-ppt

Humanize PPT

ユーザーが素材、メモ、音声の書き起こし、文書、リンクを、後続のスキルにレンダリングを委ねる前に、プレゼンテーション向けのアウトラインとページごとのメディア方針にまとめたい場合に、このスキルを使用します。古い PPT/PPTX ファイルは直接読み込めません。まずテキストを抽出し（scripts/pptx_qa.py のダンプ／検査出力を参照）、そのテキストを --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 に記録され、実際の出力に基づいてのみ更新されます。

Humanize は、下流の PPT / HTML スライドスキルを実行する前に動作し、レンダリング後のプレゼンテーションチェックアップの前後を支えます。AST の契約、ページごとのメディア選定（このページに写真、システム図、10秒のプロセス動画が必要か、あるいは何も必要ないか）、次のエージェントが使う制作ブリーフ、レンダリング済み HTML/PPTX のチェックアップを担当します。レンダリング後のデッキ自体は担当しません。

レンダリング前には、アウトラインプレビューとレンダラーのスタイル確認という2つの人間によるレビューゲートがあります。HTML の経路では、Humanize の --style-gallery が4つ以上の実際の表紙を提示します。PPT Master は、ネイティブのビジュアルプレビューを備えた必須の3段階 Confirm UI をすでに提供しているため、--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 は情報を入れる器ではありません。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 の判断。どのページにどの種類の素材（画像／図解／動画）が必要か、その目的とともに記載します。
6. video_slots.json — Remotion／HyperFrames／ネイティブ動画の挿入計画（任意）。
7. style_brief.md — 後続の制作工程に向けたビジュアル原則。
8. renderer_registry.json — この実行でのレンダラー機能のスナップショット。
9. router_plan.json — 選択したプライマリレンダラーと段階的なルート計画。
10. commands/*.md — 各後続の専門エージェント向けの範囲を限定した指示。
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 ゲート（brief モード）または反復ごとの 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 は作成せず、スタイル選択はネイティブの確認 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 の不変条件（これらは厳守すべきルールです。1つでも破ると、v0.6.4 の範囲外になります）

1. Humanize は brief のみを作成します。 レンダラー向けの制作契約を作成して終了します。後続のテンプレートや最終的な HTML／PPTX を開いたり、コピーしたり、後処理したりすることはありません。
2. 後続のレンダラーは完全にネイティブです。 次のエージェントは、後続スキル独自の SKILL.md に従います。brief では、次のエージェントが読み込むスキル、使用する 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 を読み込みます。これは、PPT Master のビジュアル仕様を重複させずに、Humanize のページ構成とノートの意図を固定するものです。

作業ルール

6. Humanize PPT が先に AST 契約を作成できる場合は、スライドレンダラーに素材を直接処理させないでください。
7. ステージビュー全体の担当は後続スキルに残してください。Humanize の presenter-shell.html は機能するベースラインであり、ネイティブコンソールの代替ではありません。
8. humanizer ツールの AI 文章のクリーンアップ原則を取り入れますが、Humanize PPT をテキストの推敲だけに縮小しないでください。
9. 検証されていない広範な約束より、小規模で検証済みのワークフローを優先してください。
10. 公開用 Skill をリリースする際は、リポジトリを作成してプッシュし、GitHub からローカルにインストールし、安全なフルサンプルを 1 つ実行し、検証済みの既知の正常なチェックポイント（examples/03-codex-guizang-native-ink-classic/）で brief とプレゼンテーションのチェックアップを確認してから、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/ ディレクトリには、frontmatter（description、alwaysApply、enabled、updatedAt、provider）と、利用可能なエージェント、スキル、SOP、使用要件を説明する <system_reminder> ブロックを含む、rules/<plugin-name>_rules.md のようなシナリオルールファイルを含めます。unzip -l で、ルートが index.html/assets/screenshots/source ではないこと、また、対象のアップローダーがラッパーディレクトリを明示的に要求していない限り、フォルダーで包まれていないことを確認してください。
13. HyperFrames／Remotion の動画を、PPT の内容を置き換える単一の埋め込みプレーヤーとして扱わないでください。Humanize PPT の成果物では、動画ツールは素材の作成手段です。トランジション、解説クリップ、比較用のビフォー／アフター、トーキングマテリアルの挿入、SNS 向けプレビュー、特定のスライドのニーズを満たす代替スチルを作成します。ページごとの 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 — フロントマターの一行説明の根拠となる、レンダラーごとの検証証拠です。
• adapters/ppt-master-bridge-notes.md — ネイティブ PPTX ルートの境界と OOXML チェックアップの仕様です。
• SPEC.md — エンジンの技術仕様です。CLI のインターフェース、データフロー、出力仕様、スタイルギャラリー、チェックアップ、メディアモデル、レンダラーレジストリについて説明しています。
• すべてのリファレンス、アダプター、バージョン情報、ヘルパースクリプトを注釈付きで掲載した完全な索引：docs/index.md。

ローカルデモ

推奨される安定したエントリーポイントは scripts/humanize_ppt.py です（バージョン付きスクリプトは互換性維持のためのラッパーとして残されています）。ブリーフモード、プレゼンテーションチェックアップ、ネイティブ PPTX、アウトラインプレビュー、旧エントリーポイントを含む CLI の使用例は、docs/local-demo.md に記載されています。

--out に関する警告： --out には、専用の実行ディレクトリを指定してください。ブリーフモードでは、実行のたびにそのディレクトリを最初から作り直します。ただし、自動的に削除されるのは、ディレクトリが存在しないか空の場合、またはルートに以前の Humanize PPT 実行を示すファイル（run_manifest.json / style_gallery_plan.json / outline-preview.md / preview-confirmed.json）がある場合に限られます。それ以外の場合は処理を拒否し、--force を指定するよう求めます。