ooodc
a7883dbed9
- 移除 TodoItem 中的 priority、created_at 和 updated_at 字段 - 强制每个任务都必须有唯一 id，且由用户负责生成 - 修改合并模式逻辑，merge=true 下保留未提及的旧任务 - 支持已完成和已取消任务重新激活（状态改回 pending 或 in_progress） - 禁止 in_progress 状态退回到 pending，必须标记为 completed 或 cancelled - 优化状态转换校验，允许特定状态间合法切换 - 简化任务变更消息，移除详细的新增/更新/移除统计 - 更新文档和示例，明确 id 必须由用户生成和使用 - 修复和补充测试，增强状态转换和合并模式验证 - 调整任务时间戳生成逻辑，统一使用当前时间及索引 - 该变更提供更合理的任务状态机械及管理模式，提升稳定性和易用性
5.3 KiB
5.3 KiB
Validation Checklist
创建或大幅改写演示文稿后，必须做一次显式验证。目标是发现空白页、XML 损坏、内容截断、明显溢出、弱视觉层级和未验证输出。
小型已有页编辑也要做对应范围的验证：至少读取被改页面或全文 XML，确认目标元素已更新且未破坏周边结构。
Required Flow
- 记录创建或编辑返回的
xml_presentation_id，以及已知的slide_id/revision_id。 - 用
xml_presentations.get回读全文 XML。 - 检查实际页数是否符合计划或用户要求。
- 检查每页
<data>内是否有预期主要元素。 - 检查没有明显空白页、破损页、缺失标题或缺失主视觉。
- 检查页面不是全部退化为标题加 bullet list。
- 检查视觉层级：标题、主视觉、支撑信息三者可区分。
- 检查明显溢出和布局风险：重叠、越界、底部拥挤、长文本框。
- 在最终回复中给出简短验证记录。
回读命令：
lark-cli slides xml_presentations get --as user \
--params '{"xml_presentation_id":"YOUR_ID"}'
Automated XML Text Overlap Lint
回读 XML 保存到本地文件后，优先运行 XML 语法和文本重叠静态检查：
python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentation.xml>
通过标准：
summary.error_count == 0。任何 error 都必须先修复再交付。- 当前工具只检查 XML well-formed 和文本元素之间的明显重叠；它不检查越界、文本高度不足、图文压盖、表格/图表压盖或底部拥挤。
- 该工具不能替代页数核对、关键内容核对或真实视觉验收。
常见 code 的处理方向：
| code | 含义 | 处理方式 |
|---|---|---|
xml_not_well_formed |
XML 语法错误或文本未转义 | 修复标签闭合、属性引号、& / < / > 转义 |
bbox_overlap |
文本元素的估算绘制区域明显重叠 | 拉开文本坐标、缩小文本框/字号，或改成明确的分栏/分组结构 |
Page Count And Structure
- 实际页数必须等于用户要求或
slide_plan.json的页数。 - 如果创建过程部分失败，先记录已创建的
xml_presentation_id，再回读确认哪些页已写入。 - 每页都应包含
<data>，且<data>内至少有一个非背景主体元素。 - 封面、章节页、总结页可以文字较少，但不能只有空背景。
- 技术解释页、对比页、流程页、架构页必须有匹配的结构元素，例如分组框、连线、时间轴、表格或图形化区域。
Expected Elements
按 slide_plan.json 和用户要求逐页核对：
- 标题或主结论存在，并能对应
key_message。 layout_type对应的主要结构已生成。visual_focus是页面中最醒目或最大的信息区域之一。text_density影响了文本量，没有用长 bullet 框替代规划。asset_need有真实素材时已放入正确区域；没有真实素材时，fallback_if_missing已用 XML 形状、线条、标签、表格或图表兜底。
如果用户指定了关键页，例如“架构解释”“Self-Attention 机制解释”“对比或演进视角”“总结页”，最终验证记录必须逐项说明这些页已存在。
Blank Or Broken Page Signals
把下面情况视为需要修复后再交付：
<data/>为空，或只有背景、装饰线、空<content/>。- 关键文本没有出现在回读 XML 中。
- 图片仍是
@./path，或<img src>是 http(s) 外链。 - 页面依赖的图片区域为空，且没有 fallback visual。
- 返回 XML 缺页、页序明显错误，或某页内容被 shell 截断。
- 大量形状坐标完全相同，导致主体内容重叠。
- 渐变背景回退成空白或白底，导致文字不可读。
Whiteboard Elements
slide.get 回读 XML 时，<whiteboard> 块只返回位置属性（topLeftX、topLeftY、width、height），SVG / Mermaid 内容不随 XML 返回。
- whiteboard 验证只能核对坐标是否越界：
topLeftX + width ≤ 960，topLeftY + height ≤ 540。 - SVG 和 Mermaid 内容的正确性无法通过回读 XML 验证，需要人工视觉验收。
- 不要在验证记录中声称 whiteboard 内容已验证，除非用户确认了视觉效果。
Layout And Overflow Risk
优先修复这些明显风险：
- 正文或标签框高度不足，文本很可能被截断。
- 多个主体元素在同一区域重叠，而不是有意叠加背景。
- 重要内容越过画布边界，或贴近底部超过
y=500。 - 高密度页使用单个长 bullet list，没有分栏、表格或分组。
- 标题、主视觉、正文的字号和颜色差异太弱，视觉层级不清。
- 所有内容页都是同一套标题加 bullets 坐标。
Verification Record
最终回复必须包含简短验证记录，建议格式：
验证记录：
- 回读：已执行 xml_presentations.get，实际页数 N / 预期 N。
- 关键页：架构解释 / Self-Attention / 对比或演进 / 总结页均存在。
- 结构：检查了主要 shape/img/table/chart 元素，无明显空白页或破损页。
- 布局：检查了标题层级、主视觉、重叠/越界/文本溢出风险。
不要声称完成了人工视觉验收，除非确实打开或获取了可视化结果。仅从 XML 静态检查得出的结论，应表述为“静态检查未发现明显问题”。