yzsp-studio/mediakit-shared-suite / ppt
ppt
Unverified飞书幻灯片:创建和编辑幻灯片。创建演示文稿、读取幻灯片内容、管理幻灯片页面(创建、删除、读取、局部替换)。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。
references/workflow/validation-visual.md
View on GitHub# 截图视觉校验
本文件覆盖**截图后的人工视觉核对**,与 [validation-xml.md](validation-xml.md) 中的服务端 lint 和 XML 内容核对共同用于验收。按任务工作流完成必要截图;截图不可用时,该页保留未完成视觉验收状态,不要声称做过视觉核对。
截图视觉校验能发现 XML 难以判断的问题(文字截断、图片裁切、图表压盖、弱对比)。截图时假设页面有问题,主动找出并报告所有风险。
截图保存在当前工作目录 `<CWD>` 下,命令显式传 `--output-dir`;使用响应中的实际图片路径核对,保留来源截图用于前后比较。
截图命令(逐页传 `--slide-id`,单批最多 8 页,超出按批次串行):
```bash
lark-cli slides +screenshot \
--presentation "YOUR_ID" \
--slide-id "SLIDE_ID_1" \
--slide-id "SLIDE_ID_2" \
--output-dir ./screenshots/
```
渲染与视觉类常见问题与修法(发现后对照修复)。前四类只能靠截图主观判断,后四类回读 XML 也能查出根因、修法确定:
| 看到的问题 | 处理方式 |
|-----------|----------|
| 文字和背景色太接近 | 深色背景用浅色文字,浅色背景用深色文字 |
| 图片被裁掉一部分 | `<img>` 的 `width` / `height` 是裁剪后尺寸;要整图显示就让 `width:height` 对齐原图比例 |
| 表格列宽不合理 | 调整 `colgroup` 中 `col` 的 `width` 值 |
| 整体风格不统一 | 封面页和结尾页用同一背景,内容页保持一致的配色和字号体系 |
| 图表没有显示 | 检查 `chartPlotArea` 和 `chartData` 是否都包含,`dim1` / `dim2` 数据数量是否匹配 |
| 图片不显示 / `<img src>` 仍是 `@path` | `@` 占位符由 `+create` 和 `+add-slide` 替换 |
| 新插入的 `<img>` 挡住原有元素 | `slide.get` 读原页,对照已有块坐标挑空白位置;空间不够就在同一批 `--parts` 里先移动/缩小现有块再插图 |
| 渐变背景变成白色 | 渐变必须用 `rgba()` 格式 + 百分比停靠点,如 `linear-gradient(135deg,rgba(30,60,114,1) 0%,rgba(59,130,246,1) 100%)` |
逐页目视检查时的排查清单(可直接作为提示词):
```text
请逐页目视检查这些幻灯片截图。先假设存在问题,并尽量找出它们。
重点检查:
- 元素重叠:文字与形状、图片或图表互相遮挡,线条穿过文字,形状或标签相互堆叠。
- 文本溢出或被裁切:靠近页面边缘、文本框边界或形状边界处被截断。
- 装饰元素位置错误:分割线、强调线或标签底板按单行文字布置,但标题或正文换行后压住文字或距离异常。
- 来源标注、页脚或页码与上方内容碰撞。
- 元素距离过近:相邻元素间距明显不足,形状或分区几乎贴在一起;按 960x540 画布估算,小于约 15 px 的间隔通常要标记。
- 间距不均:局部留白过大,另一处过于拥挤。
- 页面边距不足:主体内容贴近幻灯片边缘;按 960x540 画布估算,小于约 30 px 的外边距通常要标记。
- 列、形状、图标或同类元素没有稳定对齐。
- 图片或图表渲染异常:空白、变形、低清、关键内容不可读或预期图形缺失。
- 背景图 / 封面主视觉图里出现了文字(生图带字):这类图不应带文字,一旦发现必须重新生成替换。
- 文本对比度不足,例如浅灰文字放在米色或浅色背景上。
- 图标对比度不足,例如深色图标放在深色背景上,且没有浅色圆形或底板承托。
- 文本框过窄,导致不必要的频繁换行。
- 残留占位符、模板默认文字或未替换内容。
- 流程线或反馈线:核对起止节点、箭头方向和折线路径,避免端点悬空或穿过文字;表达闭环时,反馈线应明确回到对应节点。抽查截图时应覆盖这类页面。
- 树状图:核对节点、连线、箭头方向、分组边界和标签可读性;视觉正常不等于满足可编辑要求,仍须在回读 XML 中确认树状图主体没有 `<embed>`。
对每一页分别列出发现的问题或可疑区域,即使只是轻微问题也要记录。
报告所有发现的问题,包括轻微问题。
```
每页按以下 rubric 记录 `pass`/`fix` 结论;页面含图表时,额外检查图表精确可读性:
| 项目 | Pass 标准 | Fix 信号 |
|---|---|---|
| 可读性 | 标题、正文、标签和关键数字可读;对比度足够,文本层级之间有清楚的视觉间距 | 文字截断、字号过小、低对比、关键标签不可读,或相邻文字间距过近而视觉粘连 |
| 布局 | 主体未被意外遮挡,页边距和底部留白合理 | 重叠、越界、图片裁切、元素贴边、底部拥挤,或文字虽未相交但视觉上像碰撞 |
| 视觉层级 | 主结论、主视觉、支撑信息一眼可区分 | 所有元素同权重、主视觉过小、页面退化为文字堆叠 |
| 内容完整性 | 无空白、破图、占位符或错误页序;图示表达与页面角色匹配 | 空白/破损页、缺失图片、遗留模板文案或与计划不符 |
| 图表精确可读性(有图表时) | 若页面结论依赖精确比较、排序或阈值判断,读者可直接获得每个关键数据点的值:柱/线/饼图有直接数据标签,或有与图表一一对应的等价数据表/注释 | 只能靠坐标轴估读关键数值、缺少决定结论的数据标签、图例与系列无法对应;仅用于展示趋势且不承载精确结论的图表可不强制逐点标签 |
图表检查先问“页面是否要求读者作精确判断”:
- **需要**:比较群体得分、排名、是否达到阈值、预算/目标差异、需要从图中选方案。没有直接数值或等价数据表即为 `fix`。
- **不需要**:只表达上升/下降趋势、定性分布或结构关系,且标题/正文已经明确结论;可不逐点展示数值,但仍须检查轴、图例、系列和关键标注是否可读。
推荐把记录按如下格式保存:
```text
| slide_id | screenshot | status | findings | action |
|---|---|---|---|---|
| p001 | screenshots/p001.png | pass | hierarchy and contrast clear | - |
| p002 | screenshots/p002.png | fix | bottom labels are clipped | enlarge text box, then rescreenshot |
```
只有逐页实际看过并记录 `pass`/`fix` 的页,才能写“该页已截图确认”;截图落盘、批量成功或只看关键页都不算。对 lint 返回或被豁免的每条发现,按元素 ID 和坐标定位到截图中的具体区域,并结合回读 XML 核对,不能只写“整体正常”。截图不能替代对已确认真实问题的修复;修复后开启 lint 重提并重新查看截图。
必要截图因限流、超时或读取失败而未完成时,按错误提示恢复后重试;仍不可用则保留该页未验收状态,说明缺失页及原因,不得凭 `ok: true`、无 `issues`、静态检查或导出成功改记为 `pass`,也不得把整稿交付为已完成验收。
按问题严重度决定是否修复:空白页、破图、文字遮挡、明显裁切、低对比不可读、占位符残留等必须先修复再交付;轻微间距或对齐问题若不修复,最终验证记录要说明已知风险。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |