# 课件配图和检查规范

## 1. 交付对象

Skill 支持四类源文件：HTML/SVG、PPT/PPTX、PDF、图片型课件。源文件必须保持可追踪，导出物不能成为唯一可编辑来源。

## 2. 输入契约

### 必需输入

- 课件文件、预览 URL 或逐页内容；
- 可确定的页面顺序；
- 至少一个主要交付场景。

### 可选输入

- 品牌色、字体、Logo 和设计系统；
- 受众、授课方式、投影环境；
- 需要保留或禁止的视觉元素；
- 用户点名的重点页、问题页或不可修改页；
- 目标输出格式与保存位置。

缺少可选输入时先从现有课件推断。只有选择会实质改变结果时才询问。

## 3. 页面 Manifest 契约

Manifest 根对象包含：

- `deck`：课件名称；
- `version`：Manifest 版本；
- `theme`：颜色角色；
- `delivery_modes`：需要验证的模式；
- `pages`：页面对象数组。

每个页面对象必须包含：

- `page`：正整数且在数组内唯一；
- `level`：`hero`、`support`、`keep`、`evidence` 之一；
- `status`：`planned`、`implemented`、`verified`、`blocked` 之一。

`hero` 或 `support` 还必须包含：

- `business_question`：图要回答的问题；
- `visual_type`：稳定的 kebab-case 类型名；
- `caption`：读图后的结论句。

`keep` 必须提供 `reason`。`evidence` 必须提供 `source` 或 `reason`。

## 4. HTML/SVG 契约

语义图容器至少包含：

```html
<div class="semantic-visual business-visual"
     data-visual-type="input-output"
     data-business-question="输入经过什么处理形成什么输出">
  <svg viewBox="0 0 900 190"
       role="img"
       aria-label="材料经过流程梳理形成可核对成果">…</svg>
  <div class="semantic-caption">材料按价值流归位，形成可核对的流程证据</div>
</div>
```

要求：

- `data-visual-type` 使用 kebab-case；
- `data-business-question` 是完整问题；
- `aria-label` 描述图的结论，不写“图片”；
- 文本使用真实 `<text>`，不将中文标签转曲或栅格化；
- 主路径、反馈路径和风险路径使用稳定的视觉角色；
- 外部图片提供 `alt`，自然尺寸不为 0。

## 5. PPTX 契约

- 普通节点、箭头和标签保持可编辑；
- 连接线与节点建立真实连接，移动节点时不脱节；
- 复杂 SVG 保留源文件及生成参数；
- 不把整页截图当作 PPT 页面；
- 母版、页码、演讲者备注和打印边界保持可用。

## 6. 图形类型命名

标准类型：

- `stage-flow`
- `comparison`
- `input-output`
- `layered-architecture`
- `deliverable-stack`
- `decision-matrix`
- `selection-funnel`
- `governance-gate`
- `lifecycle`
- `scorecard`
- `swimlane`
- `product-screenshot`

新增类型使用 kebab-case，并在 Manifest、实现和审计报告中保持一致。

## 7. 证据目录

推荐输出：

```text
outputs/visual-audit/
├── audit-report.json
├── audit-report.md
├── contact-desktop-001-021.jpg
├── contact-fullscreen-001-021.jpg
├── desktop/
├── fullscreen/
├── mobile/
└── print/
```

截图文件名包含连续页码与稳定页面 ID，例如 `027-m2-s7.png`。

## 8. 严重度契约

- P0：内容缺失、关键文字被裁切、资源失败、打印失败或页面不可用。
- P1：图文逻辑错误、主图过小、明显偏心、投屏字号不足或严重失衡。
- P2：非阻断性小字、轻微留白/对齐问题、可见但越出 SVG 画布的文字、模板节奏提醒。

## 9. 完成状态

`planned` 表示已决策未实现；`implemented` 表示已写入源文件；`verified` 表示完成实际渲染与人工复核；`blocked` 表示缺少素材、工具或业务关系。

只有 `verified` 页面计入已完成页数。

## 10. 包结构

标准完整包：

```text
courseware-visuals-qa/
├── SKILL.md
├── references/
│   ├── specification.md
│   ├── visual-playbook.md
│   ├── qa-playbook.md
│   ├── examples.md
│   └── troubleshooting.md
├── assets/
│   ├── semantic-visual-starter.js
│   ├── design-tokens.json
│   ├── visual-manifest.schema.json
│   ├── visual-manifest.example.json
│   └── audit-report-template.md
├── scripts/
│   ├── audit_courseware_visuals.py
│   ├── validate_visual_manifest.py
│   └── check_skill_package.py
└── evals/
    ├── evals.json
    └── trigger-evals.json
```

