gorden-ppt-skill

gorden-ppt-skill

バージョン 同じディレクトリの VERSION を参照してください。

---

🚨 この Skill を有効にした後、最初に行うこと：自動更新を実行する

AI は、この会話でこの Skill を初めて使用するとき、必ず次のコマンドを最初の tool call として実行してください。

python3 scripts/apply_update.py

このコマンドは自動的に次の処理を行います。

1. リモートの update_source（git+ リポジトリ）から最新の updates.json を取得します
2. ローカルの VERSION とリモートの latest_version を比較します
3. 新しいバージョンがある場合 → 実際に変更されたファイルのみをダウンロードします（差分更新のため、LFS の通信量を無駄にしません）
4. 最新の場合 → 数秒以内に終了し、OK Nothing to do と出力します

⚠️ この Skill は更新を自動で push しません。AI が自発的に pull する必要があります。この手順を省略すると、古いバージョンを使ってしまい、動作、ルール、テンプレートがドキュメントと一致しない可能性があります。

✅ 同じ会話内で実行するのは一度だけで十分です。以降の tool call では確認を繰り返す必要はありません。

---

⚠️ 非商用利用：この Skill と組み込みの PPT テンプレートは、個人の学習および研究のみを目的としており、あらゆる商用利用を固く禁じます（商用プレゼンテーション、販売、研修での配布、顧客向け提案、営利目的の社内利用などを含みます）。テンプレート素材は第三者デザイナーの作品です。二次的な商用利用には、原作者の許諾が必要です。

この Skill を使用するタイミング

ユーザーの要望が次のいずれかに該当する場合、この Skill を使用してください。

• 「PPT／プレゼンテーション／スライドを作成してほしい」という要望がある場合。業務報告、年次総括、四半期レビュー、プロジェクト提案、昇進・採用面接用の発表、教材、研究計画の発表、読書レポートなど、内容は問いません。
• ユーザーから文章のアウトラインや説明が提示され、「PPT にしてほしい」と希望している場合
• ユーザーが .pptx ファイルを提供し、「このテンプレートに沿って新しいものを作ってほしい」と希望している場合
• ユーザーが「レイアウトを崩さずに」、PPT の一部のテキストを「調整／編集してほしい」と希望している場合
• ユーザーが複数の PPT テンプレートを比較し、適切なものを選びたいと希望している場合

更新メカニズムの説明

更新ツール一式には、次の 2 つのスクリプトがあります。

スクリプト	内容	使用タイミング
scripts/apply_update.py	確認＋適用（一度に実行）	Skill を有効にしたとき、毎回最初に実行（上部の赤枠を参照）
scripts/check_update.py	確認のみ。適用はせず、変更されるファイルを一覧表示	変更内容だけを先に確認し、すぐには更新したくない場合

まず変更内容を確認してからアップグレードするか決めたい場合：

python3 scripts/check_update.py     # 列出 added / modified / removed

updates.json の update_source は git+https://github.com/GordenSun/GordenPPTSkill.git#main に設定済みです。すぐに使えるため、変更は不要です。

3 つのモード

ユーザーの要望を受け取ったら、まずどのモードを使うか判断してください。

モード A：組み込みテンプレートから選ぶ

デフォルトではこの方法を使います。 組み込みの 21 種類のテンプレートで、中国語のシーンの大部分をカバーできます。

1. templates/INDEX.md を読む —— 各テンプレートのスタイル、メインカラー、適用シーン、ページ数をまとめた簡潔な一覧です。
2. ユーザーの入力と照合する —— ユーザーの説明（シーン、スタイルのキーワード、必要なページの種類、色の好み）を各テンプレートの intro.md と比較します。
3. テンプレート選択の判断基準：
   • ユーザーがテンプレートを明確に指定している → そのテンプレートを使います。
   • 最適なテンプレートが 1 つだけだと確信できる（シーン＋スタイル＋メインカラーがすべて強く一致し、ほかのテンプレートより明らかに適している）→ そのまま使ってもかまいません。ただし、作業開始前にどのテンプレートを選んだか、その理由とともに一言ユーザーに伝え、取り消せる機会を設けてください。
   • それ以外すべての場合（ユーザーが指定していない場合、または最適なものを確信できない場合）→ 必ずユーザーに選んでもらってください：
     • AskQuestion を使ってちょうど 3 つの候補テンプレートを提示します。それぞれに一言で理由（スタイル／適用シーン／ページ数）を添え、判断材料として該当する templates/<slug>/preview.png も必ず一緒に表示してください。
     • 選択肢には必ず「どれも気に入らないので、別の候補を表示」を追加します。ユーザーがそれを選んだ場合は、一致度に基づいてこれまで提示していない別の候補を 3 つ提示します（同様にプレビュー画像を添えます）。ユーザーが選ぶまで、または候補がなくなるまで、繰り返すことができます。
     • 候補をすべて提示しても気に入らない場合は、より具体的な希望（スタイル／色／シーン）を尋ねるか、モード C のオリジナルデザインに切り替えます。
   • ⚠️ プレビュー画像をユーザーに見せず、曖昧な照合だけで独断でテンプレートを決めないでください。
4. 使用するテンプレートが決まったら：
   • templates/<slug>/intro.md を読む（テンプレートの特徴が簡潔にまとめられています）
   • templates/<slug>/detail.json を読む（各ページ／各テキスト領域の詳細を示す構造化データです）
   • モード A のワークフロー に従ってページを選び、edits.json を作成し、build_pptx.py を実行します

モード B：ユーザーが用意した PPT テンプレートを使う

ユーザーが .pptx ファイルを提供し、それをテンプレートとして使うことを明確に希望している場合：

1. ユーザーの pptx を「未知のテンプレート」として扱います
2. scripts/render_slides.py を使って各ページを PNG としてレンダリングし、python-pptx を使って各ページの shape／paragraph／run 構造をその場で調べます（追加スクリプトは不要です）
3. 各ページを自分で確認します（PNG＋shape の出力）：
   • 各ページの役割を推測します（表紙／目次／章扉／本文／終了／テンプレートの宣伝）
   • 各ページにどのような内容が適しているかを推測します
   • テンプレートの宣伝、「稲殻児」、ダウンロードへのお礼などはスキップします
4. モード B のワークフロー に従い、明示的な address を使ってページを選択し、テキストを置き換える edits.json を作成します
5. ユーザーのテンプレートの原本は変更しないでください。変更内容はすべて新しい output.pptx に書き込みます

モード C：完全なオリジナル（テンプレートを使わない）

ユーザーが「オリジナルデザイン／テンプレートを使わない／シンプルですっきりしたスタイル」を明確に希望している場合：

1. できるだけ簡潔なレイアウトを作成します —— 余白を広く取り、配置を厳密に揃え、装飾を最小限にします
2. 1 ページあたりの要素は 4 個以下とし、複雑な図形やアイコンのグループ化を避けます
3. フォント：英語は Arial／Helvetica、中国語は 微軟雅黑／思源黒体。タイトルは太字にするだけで十分です
4. メインカラーは 1 色＋グレー階調＋白背景とし、複数のスタイルを無理に組み合わせないでください
5. python-pptx を使って直接コードで生成し、references/original-design-guide.md を参照します

编辑铁律（所有模式通用）

1. 不改排版 —— 只改文字。形状的位置、大小、颜色、字体、字号、行距，都不动。
2. 所有占位文字必须替换 —— 模板里的 "Question 1" / "Vivamus..." / "Key Words Here" / "项目名称" 等占位文本都必须用真实内容替换。一份完成的 PPT 里不应出现任何示例占位词。
3. max_chars 是软性参考，不是硬性上限；严禁用省略号截断 —— detail.json 每个 slot 的 max_chars / chars_per_line / max_lines 是按文本框尺寸估算的容量，仅供参考，帮助你把握"这格大概能放多少字"。
   • 优先写自然、完整、精炼的文字。略微超出通常没关系（容量已留 20% 余量，PPT 文本框本身也有弹性）。
   • 绝对禁止为了凑数而砍掉后半句、在结尾加 ... / … / 等等 来硬凑长度 —— 被省略号截断的半句话，比轻微超框难看得多，是最差的结果。
   • 真的太长时，按优先级处理：① 用更精炼的措辞重写（真正的概括，不是切断）；② 减少要点条数 / 换一个空间更大的版式或页面；③ 实在不行，宁可让它轻微超出一点，也不要出现省略号。
   • build_pptx.py 的出框检测只是提示、不阻断保存。日常不要加 --strict（它会因超框拒绝保存，从而诱导截断）。capacity_unknown:true 的槽测不准，凭目测把握。
4. 数字 / 序号默认不动 —— editable: false 的 slot 是装饰性 "01/02/1/2/%" 之类，除非用户明确要求改顺序，否则保持。
5. 图形 / 图表通常无法同步 —— 装饰性的进度条 / 圆环 / 旗帜路径 / 流程箭头是固定形状；改了百分比文字不会改弧长。每个模板 detail.json 里如有这类页面会在 cautions 字段列出。
6. 真实数据图表才能改数据 —— 如果某页有 PPT 原生 chart（shape.has_chart=True），可以用 build_pptx.py --chart-data 同步更新；详见 references/chart-editing.md。
7. 章节名前后呼应 —— 改了目录章节名，对应的分章扉页 + 内容页面包屑文字都要同步改。
8. 封面 / 致谢页按模板能力来，不要硬造 ——
   • 读 detail.json 的 page_roles，如果 cover 数组为空，直接从第一张内容页开始，不要拿一张内容页当封面用，更不要从其他模板临时凑一张封面页。
   • 如果 ending 数组为空，直接以最后一张内容页收尾，不要硬造"感谢聆听"。
   • 同理，agenda 空 → 不强加目录；section_divider 空 → 不强加分章扉页。
   • 也就是说：模板有什么角色就用什么角色，少一个角色就少一页，不要破坏视觉一致性去拼凑。这条规则在 v1.0.3 起对所有模板生效。
9. 同级标题字号必须一致，不要逐处改字号 ——
   • detail.json 顶部有 type_scale（字号层级表，level 1 = 最大），每个 slot 标了 level。同一 level 的文字保持模板原字号，不要改字号。
   • 某处文字偏长时，用更精炼的措辞重写来控制长度（见第 3 条），不要把这一处字号改小（会破坏同级一致），也不要截断加省略号。
   • 选多页拼一份 PPT 时，让各页同 level 的标题用词长度相近，整体才齐整。

标准工作流（模式 A）

# 1. 从 templates/INDEX.md 选定一个模板，例如 minimal-business-summary
TEMPLATE=templates/minimal-business-summary

# 2. 读两个文件
#    - $TEMPLATE/intro.md     -> 模板风格 / 适用场景 / 结构概述
#    - $TEMPLATE/detail.json  -> 每页 / 每个文本位的详细描述

# 3. 自己决定要用哪些页（用 detail.json 的 page.role 和 use_for）
#    生成 edits.json：
#    {
#      "template_slug": "minimal-business-summary",
#      "selected_slides": [1, 2, 3, 5, 7, 9, 10, 12, 13, 14, 16],
#      "edits": [
#        {"slide": 1, "slot_id": "cover_title_cn", "new_text": "2026 年度复盘"},
#        ...
#      ]
#    }

# 4. 跑构建（不要加 --strict：出框检测只作提示，不应阻断；超框宁可轻微超出也别截断加省略号）
python3 scripts/build_pptx.py \
    $TEMPLATE/template.pptx \
    edits.json \
    out/final.pptx \
    --detail $TEMPLATE/detail.json

# 5. （可选）渲染最终 pptx 给用户预览 / 自检（每页一张 PNG）
python3 scripts/render_slides.py out/final.pptx out/renders --dpi 144

目录结构

GordenPPTSkill/
├── SKILL.md               ← 本文件
├── VERSION                ← 当前版本号
├── CHANGELOG.md           ← 人类可读变更日志
├── updates.json           ← 机器可读版本增量索引
├── manifest.json          ← 所有文件的 sha256 与版本归属
├── README.md              ← 仓库概览（用户阅读）
├── scripts/
│   ├── build_pptx.py          # 按 edits.json 选页 + 换字 → 输出 pptx（含出框检测）
│   ├── render_slides.py       # pptx → PDF → 每页 PNG（预览/自检）
│   ├── compute_capacity.py    # 由 template.pptx 计算每个 slot 的容量字段（数据准备）
│   ├── check_update.py        # 检查远端是否有更新
│   ├── apply_update.py        # 增量更新本地文件
│   └── build_manifest.py      # 重建 manifest.json
├── references/
│   ├── workflow.md
│   ├── pptx-edit-schema.md
│   ├── custom-template-workflow.md
│   ├── chart-editing.md
│   └── original-design-guide.md
└── templates/
    ├── INDEX.md
    └── <slug>/
        ├── template.pptx
        ├── intro.md       # 高度浓缩简介
        ├── detail.json    # 详细页面 / slot 数据（含容量字段 + type_scale）
        └── preview.png    # 4 页 2×2 拼接预览图

关键脚本一句话说明

脚本	干嘛用
build_pptx.py	按 edits.json（选页 + 文字替换）从模板生成最终 pptx；带出框检测，--strict 时出框拒绝保存
render_slides.py	把任意 pptx 渲染成每页一张 PNG（用 LibreOffice + pdftoppm），用于预览 / 自检
compute_capacity.py	由 template.pptx 算出每个 slot 的 chars_per_line/max_lines/max_chars 等容量字段（自带模板已算好，仅在加新模板时需要）
check_update.py	对比本地 VERSION 和远端 updates.json，告诉你要不要更新
apply_update.py	按 updates.json 的 delta 列表只下载变动文件
build_manifest.py	重新计算 manifest.json

字体说明

模板 XML 里大量使用 微软雅黑。如果运行环境没有该字体，配合 ~/.config/fontconfig/fonts.conf 把它别名到本地已安装的字体（推荐顺序：WenQuanYi Micro Hei → DengXian → Noto Sans SC → PingFang SC）。预览图正是用这条 fallback 链渲染的。

最终交给用户的 .pptx 在 PowerPoint / WPS / Keynote 里打开时会自动用宿主机的字体渲染，因此不需要担心字体丢失问题。

一些常见误区

• 不要只改文字不改章节名一致性 —— 改 agenda 必须同步改分章扉页
• 不要在装饰图上加文字以为是真图表
• 不要把 lorem ipsum 留在最终 PPT 里
• 不要为了塞下文字而忽略 max_chars
• 不要修改用户原始模板文件 —— 所有产出都到新文件
• 不要用本 Skill 做商业项目 —— 见顶部声明