ppt-taste

name	ppt:taste
description	视觉评审 PPT, 输出双轴评分 (layout / palette 解耦) + 描述性建议 + actionable 改进项. 双模式 (锚点模式 / 通用原则模式): 锚点模式基于 ppt plugin 共享锚点库 (10 张华为 golden 锚点 + 5 条审美原则 + 5 类反模式) 做视觉对照; 通用原则模式仅按 P1-P5 原则 + AP1-AP5 反模式打分, 适用于 codex 等非华为风产物. 当用户提到 "评审 PPT" "ppt:taste" "看一下 deck 质量" "审美评分" "找问题" 时触发.
argument-hint	<pptx 路径> 或 <png 目录> [--mode anchor|general]
allowed-tools	Read, Write, Bash, Glob, Grep, AskUserQuestion
version	3.9.5

PPT:Taste — 视觉评审

视觉评审 .pptx 或 PNG 目录, 输出 markdown 报告 + 结构化 JSON (机读, 供产线下游). 核心设计: 双轴评分 (layout / palette 解耦), 引用 plugin 共享锚点库做视觉对照.

路径约定

<plugin-root> 指 ppt plugin 根目录. 推导方式: Base directory 是 <plugin-root>/skills/taste/, 取两级父目录即为 <plugin-root>. 后续 <plugin-root> 替换为实际路径.

设计基础: 双轴评分 (硬约束)

按 anchors.yaml 原则 P2 "布局结构 vs 调性配色 解耦": 不能合并 layout 和 palette 成单一 "美感分". 必须分两轴独立评分.

• layout_score (1-5): 仅评布局结构
  • 对齐 / 框比例 / 视觉重量 / 关联表达 / 留白节奏 / 字号节奏
  • 参考: 10 张 golden 锚点的 layout
• palette_score (1-5): 仅评调性配色
  • 底色 / 强调色 / 装饰元素 / 整体调性
  • 参考: 原则 P1 "浅色调优先" + 反模式 AP1 (黑色满底) / AP2 (红色满底)

为什么分两轴: 用户审美核心发现——很多 deck "布局可参考但底色需洗白". 单轴评分会把这种 deck 评中等, 双轴评分会清晰显示 "layout 4, palette 1" 让用户精准定位问题.

评分标尺锚定 (避免分数通胀)

分数	含义
5	真正出色, 达到 golden 锚点水平 (10 张华为官方主打胶片)
4	满足专业标准的合格水平, 但尚未到 golden
3	有明显问题但可用
2	多个问题, 需重做
1	严重缺陷 (命中反模式 AP1-AP5)

关键: 评 4 之前问自己 "这页真的接近 golden 锚点吗?" 避免默认 5 分.

评分模式选择

两种评分模式, 双轴解耦与 1-5 标尺在两种模式下都成立, 区别在评分依据:

• anchor (锚点模式, 默认): golden 锚点视觉对照 + P1-P5 + AP1-AP5. 适用 huawei renderer 产物及任何希望对标华为 golden 水准的 deck.
• general (通用原则模式): 仅按 anchors.yaml 的 P1-P5 原则 + AP1-AP5 反模式打分, 不做 golden 对照. 适用 codex 等非华为风格产物 — 不以 "像不像华为" 论分.

模式判定优先级 (从高到低):

0. 锚点可用性前置 (marketplace 安装场景): 先 Glob <plugin-root>/anchors/golden/*.png. 若 anchors.yaml 或 golden PNG 缺失 (publisher 发布到公共 marketplace 时排除了华为锚点资产 SEC-001/002), 则强制 general 模式, 评分依据用本 SKILL.md「内置审美原则」节 (不依赖 anchors.yaml). 即使用户传 --mode anchor 也降级, 并在报告与对话各提示一句『锚点库未随发布提供, 已按通用原则模式评审』. 开发环境 (cc-dev / 本地 plugin) 锚点齐全, 此条不触发.
1. 用户显式 --mode anchor|general
2. 已知产物来源: 检查 deck 同目录 .ppt-workdir/runs/*-codex/manifest.json, 仅当某 manifest 的 pptx_path 指向目标 deck (路径归一化后一致) 时 → general; 其余情况 (无 -codex run 目录, 或 manifest 指向别的 deck — 如 --compare 后双引擎产物共存同一目录) → anchor. 不能只看 "-codex run 目录是否存在", 双引擎共存目录会误判 renderer 产物
3. 默认 anchor

参数解析

从 $ARGUMENTS 解析:

• 路径 (必需): .pptx 文件 或 PNG 目录 (含 slide-NN.png)
• --mode anchor|general (可选): 评分模式, 缺省按「评分模式选择」节判定

示例:

• /ppt:taste output/report.pptx — 输入 PPTX, skill 内部转 PNG
• /ppt:taste output/.ppt-workdir/png/ — 输入 PNG 目录, 直接评
• /ppt:taste output/codex-deck.pptx --mode general — 通用原则模式评审

执行流程

Step 1: 输入识别 + PNG 准备

判断输入类型:

• .pptx 文件: 用 LibreOffice 转 PDF, 再用 PyMuPDF 转 PNG

  TMP=<deck-stem>.ppt-workdir-taste
  mkdir -p "$TMP"
  soffice --headless --convert-to pdf --outdir "$TMP" "<pptx-path>"
  # 然后 PyMuPDF 转 PNG (一行 Python 脚本, dpi=96)
  

  PPTX 转 PNG 不依赖 ppt:create 工具链, 独立运行
• PNG 目录: 直接进 Step 2

Step 2: 加载锚点库 (锚点模式必做)

前置: 若「评分模式选择」第 0 条判定锚点缺失 (marketplace 安装), 跳过本 Step, 走「通用原则模式规程」的 Step 2 (general 替代) + 内置审美原则.

执行前用 Read 加载以下文件到当前会话:

1. <plugin-root>/anchors.yaml (锚点库索引)

   • 5 条审美原则 (P1-P5)
   • 5 类反模式 (AP1-AP5)
   • 103 锚点 metadata (golden 10 + layout-only 23 + extended 70)

2. <plugin-root>/anchors/golden/ 全部 10 张 PNG (视觉参考):

   Glob: <plugin-root>/anchors/golden/*.png
   Read 全部 10 张
   

   这 10 张是用户从 211 张华为胶片中重选的高质量参考, 评每张目标 slide 时主动用这 10 张做视觉对照.

3. layout-only / extended 默认不 Read PNG, 仅从 anchors.yaml 读文字描述. 评审中如遇特定 deck 类型 (如 channel / wifi6 商务调) 需要补充参考, 按需 Read <plugin-root>/anchors/layout-only/<deck_id>/*.png.

Step 3: 逐页评审

对每张 slide PNG (用 Read 加载):

1. 识别 slide type: cover / toc / section / content / data / closing / slogan
2. 找对应 golden 锚点比对:
   • cover → wifi7-p001
   • content → banking-p004 / p021 / p026
   • data → datacenter-p003 / p005
   • closing → banking-p043
   • 未明确分类的 golden (banking-p021/p026/datacenter-p005/wifi7-p004/p019/p094) 作为通用 content / data 参考
3. 双轴评分:
   • layout_score (1-5) + 1-2 句具体观察 (对齐 / 留白 / 视觉重量等)
   • palette_score (1-5) + 1-2 句具体观察 (底色 / 强调色 / 调性)
4. 反模式检查: 对照 AP1-AP5 标明命中项 (若有)
5. 改进建议 (仅当任一轴 ≤ 3 时): actionable 1-2 句, 引用具体 golden 锚点 (如 "改为浅色底, 参考 wifi7-p001 的自然摄影调性")

Step 4: 输出 markdown 报告

落到 <deck-stem>.taste-report.md, 跟输入 deck 同目录. 格式:

# ppt:taste 评审报告

- **Deck**: <name>
- **Timestamp**: <ISO 8601>
- **Pages**: <N>
- **Mode**: anchor | general-principles
- **Anchor library version**: 2.0 (plugin scope)

## Deck 总分

| 维度 | 平均 | 最高 | 最低 |
|---|---|---|---|
| Layout | x.xx | x | x |
| Palette | x.xx | x | x |

**综合判断** (2-3 句): {基于双轴平均给出整体定位}

## 逐页评分

| # | Type | Layout | Palette | 观察 | 反模式 |
|---|---|---|---|---|---|
| 1 | cover | 4 | 4 | ... | — |
| 2 | toc | 3 | 2 | 装饰字过大 + 黑底 | AP3 |
| ... |

## 命中反模式汇总

| 页 | AP | 描述 | 修复方向 |
|---|---|---|---|
| 2 | AP3 | 巨型装饰字 | 标题字号缩到正文 3 倍以内 |
| 4 | AP1 | 黑色满底 | 改浅色底 (参考 wifi7-p001) |
| ... |

## 改进项 (按优先级)

1. **{slide-N} {核心问题}**: {具体修复方向, 引用 golden 锚点}
2. ...

## 锚点参考来源

本评审使用以下 golden 锚点作为视觉对照:
- {列出实际用到的 golden 文件}

(general 模式下「锚点参考来源」节替换为: ## 评分依据 + 一行 anchors.yaml P1-P5 + AP1-AP5)

Step 4b: 输出结构化 JSON 报告

除 markdown 外, 同一次评审额外落一份 <deck-stem>.taste-report.json (与 .md 同目录同 stem), 供产线下游 (orchestrator run 目录 / CI 门 / 趋势对比) 机读. JSON 与 markdown 必须同源同值 (同一组评分, 不要重新评).

字段契约单一来源: <plugin-root>/schemas/taste_report.py (pydantic TasteReport). 骨架:

{
  "deck": "<deck 文件名>",
  "timestamp": "<ISO 8601>",
  "pages": 19,
  "mode": "anchor",
  "anchor_library_version": "2.0 (plugin scope)",
  "verdict": "<综合判断 2-3 句, 同 markdown>",
  "summary": {
    "layout_avg": 3.58, "layout_max": 4, "layout_min": 2,
    "palette_avg": 3.95, "palette_max": 5, "palette_min": 3
  },
  "slides": [
    {
      "index": 1, "slide_type": "cover",
      "layout_score": 4, "palette_score": 4,
      "antipatterns": [],
      "observation": "<该页 1-2 句具体观察>",
      "top_issue": null,
      "suggestion": null
    }
  ],
  "antipattern_hits": [
    {"slide": 3, "ap": "AP4", "description": "<描述>", "fix": "<修复方向>"}
  ],
  "improvements": [
    {"rank": 1, "title": "<核心问题>", "detail": "<修复方向, 引用 golden 锚点或原则编号>", "slides": [3]}
  ]
}

硬约束 (Step 4c 校验器逐条强制, 违反报错):

1. summary.layout_avg / palette_avg = slides 各自实际平均 (保留 2 位小数, 容差 0.01); max/min 取 slides 实际极值.
2. pages == slides 条数; slides[].index 连续 1..N, 无跳号/重复.
3. 命中 AP 的页 (slides[].antipatterns 非空), 对应轴自动 <= 2 (与逐页评分一致).
4. antipattern_hits 每条的 (slide, ap) 必须在该页 slides[].antipatterns 声明过.
5. slides[].antipatterns 无命中时写 [] (绝不写 ["—"]); top_issue/suggestion 仅任一轴 <= 3 或命中 AP 时填, 否则 null.
6. mode 仅 "anchor" 或 "general-principles" (general 模式含 marketplace 锚点缺失 fallback); 无多余字段 (extra=forbid).

Step 4c: JSON 自校验 (fail-loud)

写完 JSON 后用契约校验器验证结构合规:

uv run --script <plugin-root>/schemas/taste_report.py <deck-stem>.taste-report.json

• 输出 OK: ... -> 通过, 进 Step 5.
• 输出 FAIL: ... (exit 1) -> 按报错信息修正 JSON 重写, 重跑直到 OK. 不要把不合规 JSON 留给用户.
• 若环境无 uv / pydantic 无法运行校验器 (极少数离线场景), 跳过自动校验, 但仍须人工对照上方 6 条硬约束确保结构正确.

Step 5: 输出确认

完成 markdown + JSON 两份报告后:

1. 输出两份报告路径 (.taste-report.md + .taste-report.json) 让用户打开
2. 简短总结 deck 级别 layout / palette 双轴分数 + Top 3 改进项
3. 询问用户是否需要对某些页深入分析 / 或对建议提问

内置审美原则 (锚点缺失 fallback)

发布到公共 marketplace 的 ppt 不含 anchors.yaml / anchors 资产 (华为内部胶片, publisher SEC-001/002 排除). 此时 general 模式用下列内置 P1-P5 + AP1-AP5 评分 (与 anchors.yaml 的 principles/antipatterns 同源, 仅去除含锚点 ID 的 evidence):

审美原则 (P1-P5):

• P1 浅色调优先 (palette, 权重高): 整体调性优先浅色 / 白底 / 浅蓝渐变. 避免: 黑色满底 / 红色满底 / 深蓝商务调 / 棕黑装饰底.
• P2 布局结构 vs 调性配色 解耦 (权重 critical): 布局/结构与调色/底色是独立维度, 必须分两轴评 (layout_score / palette_score).
• P3 字号节制 + 内容舒展 (layout, 权重高): 标题中等大 (不超过正文 3 倍), 正文字大且有留白, 数据数字用红色加粗作焦点, 装饰字 (目录/01/02 编号) 不应巨大.
• P4 框间关联可视化 (layout, 权重中): 多对象不能堆罗列, 必须有视觉化关联——漏斗 (流动) / 箭头 (因果转换) / 比喻图 (作锚) / 结构化标签 (场景/模型/工程/平台).
• P5 数据严谨 (权重中): 所有数据页底部必有来源标注 (Gartner / 公司年报 / URL).

反模式 (AP1-AP5, 命中即对应轴 ≤ 2):

• AP1 黑色/深色满底章节分隔: 整页黑底/深底 + 巨号红/黄/白装饰字作章节分隔 (除战略煽情口号外不应用).
• AP2 红色满底: 整页红色满底 (如谢谢页/封底).
• AP3 巨型装饰字: '目录' / '01' / '03' / 巨号谢谢 等装饰字超过正文 4 倍, 占画面 1/3 以上.
• AP4 内容稀疏 + 巨字补位: 一页只有 3-4 个词 + 配巨号字, 信息密度过低.
• AP5 模板变量字面值渲染: code='X' / title='Y' / summary='Z' 这种 Python-like 变量定义直接出现在 PPT 内容层.

通用原则模式规程 (--mode general)

general 模式复用上述执行流程骨架 (Step 1 PNG 准备 / Step 4 报告 / Step 5 确认不变), 仅替换 Step 2 与 Step 3:

Step 2 (general 替代): 加载评分依据

优先 Read <plugin-root>/anchors.yaml 的 principles 节 (P1-P5) + antipatterns 节 (AP1-AP5). 若 anchors.yaml 缺失 (marketplace 安装, publisher 已排除锚点资产) → 直接用本 SKILL.md「内置审美原则 (锚点缺失 fallback)」节的 P1-P5 + AP1-AP5, 不报错. 不 Read golden PNG — 省 token, 且不以 "像不像华为" 论分. layout-only / extended 同样不加载.

Step 3 (general 替代): 逐页评审

对每张 slide PNG (用 Read 加载):

1. 识别 slide type: cover / toc / section / content / data / closing / slogan
2. 逐条原则观察: 每页按 P1 (浅色调) / P3 (字号节制 + 内容舒展) / P4 (框间关联可视化) / P5 (数据严谨) 逐条给出具体观察; P2 (解耦) 体现为双轴评分本身, 不单独打分
3. 反模式检查: 对照 AP1-AP5 标明命中项 (若有)
4. 双轴评分 (标尺语义平移):
   • 5 = P1/P3/P4/P5 全满足且无任何 AP 命中, 布局有编辑级叙事感
   • 4 = 满足专业标准的合格水平
   • 3 及以下与锚点模式标尺含义相同
   • 命中 AP 任一, 对应轴自动 ≤ 2