McKinsey PPT Design — Harness Framework

Version: 2.3.3-harness-v2 · Engine: MckEngine (python-pptx) · Author: likaku

Required tools: Read, Write, Bash · Requires: pip install python-pptx lxml

---

常见崩坏模式（每次生成前必读，先于 HARD RULES）

告诉 AI 要做什么效果一般，告诉它前人最容易在哪里塌效果更好。 以下三种反模式均已在真实执行中被验证，每次必须主动警惕。

反模式 1：口头宣布"门禁通过"（最常见）

错误做法：

「S4 QA 共 7 个 errors，判断均为 engine 设计行为，门禁通过，进入 S5」

问题所在：passed 是由 AI 口头判断的，不是由程序派生的。无论理由多充分，这句话都是 AI 在给自己写完成证书。

正确做法：

1. 执行 python references/scripts/gate_check.py <pptx路径> <项目目录>
2. 读取 <项目目录>/gate_result.json
3. 只有 gate_result.json 中 "passed": true 时，才能进入 S5
4. 如果 "passed": false，修复 user_code_errors 列表中的问题，重新渲染，再次执行 gate_check

---

反模式 2：S3 门禁"脑子里过一遍"就算通过

错误做法：

「S3 内容门禁预检：API 格式正确，字数在限制内，通过，进入 S4」（没有执行任何代码）

问题所在：今天真实发生的 3 个 API 格式错误（four_column/matrix_2x2/executive_summary 参数格式），靠脑子过是过不出来的，必须靠代码检查。

正确做法：

1. 执行 python references/scripts/gate_check_s3.py <content.json路径> <项目目录>
2. 读取 <项目目录>/gate_s3.json
3. 只有 "passed": true 时，才能进入 S4
4. 如果有 fail 项，修正 content.json，重新执行 gate_check_s3

---

反模式 3：engine_bug 分类作为软话逃生口

错误做法：

「peer_font_inconsistency 是 engine 内部设计行为，不是用户代码问题，可以放行」

问题所在：这个分类本身是正确的，但由 AI 在对话里口头做出，等于把豁免权交给了 AI 自己——而 AI 有动机让自己通过。

正确做法： gate_check.py 里有硬编码的 ENGINE_BUG_WHITELIST 枚举。只有在白名单里的 error category，才会被豁免。白名单是代码，不是 AI 的判断。如果你认为某类 error 应该加入白名单，修改 gate_check.py 里的枚举，而不是口头声明豁免。

---

HARD RULES（必须遵守，不可绕过）

1. 每次生成必须走五阶段流程，不允许"一句话直接生成"跳过前置阶段
2. TaskCreate 驱动进度：开始前创建5个 task，每阶段完成后立即 TaskUpdate completed
3. 按需加载上下文：每个阶段只读对应文件，不要全量加载旧版 SKILL.md 里的内容
4. 门禁必须机读化：S3 和 S4 门禁必须执行对应的 gate_check 脚本，读 JSON 结果，不得口头判断
5. Self-Refinement 必做：每次修正 pattern-level 问题后，写入 experiences/ 对应文件
6. 引擎路径固定：sys.path.insert(0, os.path.expanduser('~/.workbuddy/skills/mck-ppt-design'))

---

知识路由（上下文加载索引）

在每个阶段开始时，读对应文件。不要一次性全读。

阶段	必须读	说明
S1 需求	references/team/brand-guide.md	了解设计约束
S2 结构	references/framework/engine-api.md + references/layout-matrix.yaml	版式选择和能力边界
S3 内容	references/framework/guard-rails.md + experiences/*.md（存在时）	防溢出规则 + 历史踩坑
S4 渲染	用到的 references/layouts/*.md（只读实际用到的版式）	版式实现细节
S5 交付	无	—

完整路由表：references/INDEX.md

---

五阶段生成流程

┌─────────┐   ┌─────────────┐   ┌─────────────┐   ┌──────────────┐   ┌──────────┐
│ S1 需求  │──▶│ S2 结构 ⭐   │──▶│ S3 内容 ⭐   │──▶│ S4 渲染+QA ⭐⭐│──▶│ S5 交付   │
│ brief.md│   │ outline.json│   │content.json │   │  .pptx       │   │ + 沉淀   │
└─────────┘   └─────────────┘   └─────────────┘   └──────────────┘   └──────────┘
                    ⭐ = 门禁（FAIL 则在本阶段修正，不得跳过）
    S3/S4 门禁必须运行 gate_check 脚本，读 JSON 结果 — 不得口头宣布通过

Stage 1: 需求定义

读文件：references/team/brand-guide.md

收集信息：

• 受众（职位/决策角色）
• 目标（决策/汇报/说服）
• 时长（分钟数 → 约 1 分钟/页）
• 关键信息（最多 5 条核心 message）
• 数据来源（有哪些数据可用）

产出：在工作目录创建 ppt-project-{slug}/brief.md

门禁：audience + goal + key_messages 三项非空（AI 自评即可）

---

Stage 2: 结构设计

读文件：references/framework/engine-api.md, references/layout-matrix.yaml

任务：

1. 根据时长确定页数（1分钟/页）
2. 为每张幻灯片选定 layout（查 engine-api.md 速查表）
3. 每页写一句核心 key_point（完整句子，不是标签）
4. 确认版式在能力边界内（查 layout-matrix.yaml）

产出：ppt-project-{slug}/outline.json

{
  "brief": {"audience": "董事会", "goal": "战略汇报", "duration_minutes": 15},
  "slides": [
    {"idx": 1, "layout": "cover", "title": "Q1 2026 战略回顾", "key_point": ""},
    {"idx": 2, "layout": "toc", "title": "目录", "key_point": ""},
    {"idx": 3, "layout": "table_insight", "title": "市场格局三大转变驱动战略重构", "key_point": ""}
  ]
}

⭐ 门禁 S2（AI 自评）：

• cover 幻灯片存在
• 幻灯片数量在时长约束内（count <= duration_minutes * 1.2）
• 所有 layout 在 layout-matrix.yaml 中有定义
• Action Title 均为完整句子（len > 10，包含动词）
• two_column_text 数量 ≤ 1

---

Stage 3: 内容填充

读文件：references/framework/guard-rails.md, experiences/*.md（全部存在的文件）

任务：

1. 为每张幻灯片填充具体文案、数字、图表数据
2. 确保每页有 source 出处
3. 按 layout-matrix.yaml 的 char_budget 控制文字量

产出：ppt-project-{slug}/content.json

⭐ 门禁 S3（必须机读化，不得 AI 自评）：

python ~/.workbuddy/skills/mck-ppt-design/references/scripts/gate_check_s3.py \
    <项目目录>/content.json  <项目目录>

读取 <项目目录>/gate_s3.json：

• "passed": true → 进入 S4
• "passed": false → 修正 content.json 中 fail_items 列出的问题，重新执行

---

Stage 4: 渲染 + QA

读文件：用到的版式对应的 references/layouts/*.md

任务：

1. 根据 content.json 生成 Python 渲染脚本
2. 执行脚本生成 .pptx
3. 运行 QA 门禁脚本

⭐⭐ 门禁 S4（必须机读化，不得口头宣布通过）：

python ~/.workbuddy/skills/mck-ppt-design/references/scripts/gate_check.py \
    <pptx路径>  <项目目录>

读取 <项目目录>/gate_result.json：

• "passed": true → 进入 S5
• "passed": false → 查看 user_code_errors，修复渲染代码，重新渲染，再次执行

注意：engine_bug 类 errors（peer_font_inconsistency 等白名单条目）由脚本自动豁免，不需要 AI 口头判断。

产出：<项目目录>/gate_result.json + .pptx

---

Stage 5: 交付 + Self-Refinement

任务：

1. 读取 gate_result.json 确认 passed: true（不得在无此文件时声称通过）
2. 交付 .pptx 文件
3. Self-Refinement：判断本次是否有 pattern-level 修正

⭐ Self-Refinement 协议：

修正后判断：
  ONE-TIME（单次特定调整）→ 不需要沉淀
  PATTERN（跨 deck 可重现的问题）→ 必须写入 experiences/
    - 溢出类 → experiences/overflow.md
    - 图表限制 → experiences/chart-limits.md
    - 版式踩坑 → experiences/layout-pitfalls.md
    - 中文渲染 → experiences/cjk-issues.md

格式：
  ## Experience NNN: {title}
  **Date**: YYYY-MM-DD
  **Problem**: ...
  **Root Cause**: ...
  **Fix**: ...
  **Rule**: ...（门禁层面如何预防）

---

Fast Track（简单需求跳过 S2/S3 门禁）

满足全部条件时，AI 可跳过 S2 结构评审和 S3 内容审查：

• 总页数 ≤ 5
• 无数据图表（donut/bar/table 类）
• 用户明确表达"快速"/"马上要"/"简单"

仍然必须：S1 需求收集 + S4 QA 门禁（gate_check.py 脚本执行）+ S5 交付

---

Checkpoint / 断点恢复

当用户说"继续做那个 PPT"时：

import os, json, glob

projects = glob.glob('ppt-project-*/')
for proj in projects:
    brief   = os.path.exists(f'{proj}brief.md')
    outline = os.path.exists(f'{proj}outline.json')
    content = os.path.exists(f'{proj}content.json')
    gate_s3 = os.path.exists(f'{proj}gate_s3.json')
    gate_s4 = os.path.exists(f'{proj}gate_result.json')
    pptx    = bool(glob.glob(f'{proj}*.pptx'))

    if not brief:           stage = 1
    elif not outline:       stage = 2
    elif not content:       stage = 3
    elif not gate_s3:       stage = '3-gate'   # content 有了但 gate 还没跑
    elif not pptx:          stage = 4
    elif not gate_s4:       stage = '4-gate'   # pptx 有了但 gate 还没跑
    else:                   stage = 5

    print(f"项目 {proj}: 当前处于 Stage {stage}")

---

MckEngine 快速模板

import sys, os
sys.path.insert(0, os.path.expanduser('~/.workbuddy/skills/mck-ppt-design'))
from mck_ppt import MckEngine
from mck_ppt.constants import *

eng = MckEngine(total_slides=12)
eng.cover(title='标题', subtitle='副标题', author='作者', date='2026年')
eng.toc(items=[('1', '章节一', '一句话描述'), ('2', '章节二', '一句话描述')])
# ... 内容页 ...
eng.closing(title='谢谢', message='期待进一步交流')
eng.save('output/deck.pptx')  # 自动 full_cleanup

详细 API：references/framework/engine-api.md 版式规范：references/layouts/ 10条护栏：references/framework/guard-rails.md 版式能力边界：references/layout-matrix.yaml 历史踩坑：experiences/ S3 门禁脚本：references/scripts/gate_check_s3.py S4 门禁脚本：references/scripts/gate_check.py