@amaster.ai/pi-lark 0.1.6 → 0.1.7

package/skills/lark-slides/references/troubleshooting.md

@@ -1,16 +1,27 @@
 # Troubleshooting
 
-本文件覆盖 lark-slides 的 XML 排障和常见失败处理。
+本文件覆盖 lark-slides 的通用创建前自检、XML 排障和常见失败处理。命令专属问题优先看对应 reference，例如 `+replace-slide`、`+media-upload`、`xml_presentation.slide.create`。
+
+## XML Preflight
+
+在真正创建或替换前，至少检查：
+
+- 特殊字符已转义：正文和标题里的 `&`、`<`、`>` 不能裸写；属性值里的裸 `&` 也必须写成 `&amp;`。
+- 属性引号安全：XML 属性、shell 引号、JSON 字符串包装之间没有互相打断。
+- 结构合法：`<slide>` 下只放 `<style>`、`<data>`、`<note>`，文本都在 `<content>` 内。
+- 图片路径正确：`<img src="@...">` 只在 `+create --slides` 的支持链路中使用；直接调用 `xml_presentation.slide.create` 必须先拿到 `file_token`。
 
 ## Failure Order
 
 遇到 `invalid param`、某一页创建失败、页面空白或布局错乱时，按顺序处理：
 
-1. 先判断是否已有可用的 `xml_presentation_id`：从成功 stdout、错误 hint、用户给定链接或已保存上下文中获取；没有 ID 时不要回读，直接按当前错误处理。
-2. 如果有 `xml_presentation_id`，再用 `slides +xml-get` 尝试回读，确认是否存在演示文稿、是否已有部分页面写入、或是否只是空 presentation。
+1. 记录 `xml_presentation_id`，不要假设失败代表什么都没创建。
+2. 用 `slides +xml-get` 回读，确认是否已有部分页面写入。
 3. 检查失败页是否含未转义字符：`Q&A -> Q&amp;A`，文本 `<` / `>` 写成 `&lt;` / `&gt;`，属性 URL `a=1&b=2 -> a=1&amp;b=2`。
 4. 检查标签闭合、属性引号、`<content>` 结构，以及 `<slide>` 直接子元素。
-5. 如果使用 `--slides '[...]'`，怀疑 shell 截断时直接切到两步创建：先 `slides +create`，再用 `xml_presentation.slide create` 逐页添加。
+5. 页面空白、溢出、重叠或越界时，按 [validation-checklist.md](validation-checklist.md) 运行 `xml_text_overlap_lint.py`；先修复所有 `error`，再对 `warning` 指向的页面和元素做截图复核。
+6. 如果使用 `--slides '[...]'`，怀疑 shell 截断时直接切到两步创建：先 `slides +create`，再用 `xml_presentation.slide.create` 逐页添加。
+7. 局部问题用 `+replace-slide` 块级修正；整页结构要改时再用 `slide.delete` 旧页 + `slide.create` 新页。
 
 ## Symptom Fixes
 
@@ -23,9 +34,10 @@
 | 表格列宽不合理 | 调整 `colgroup` 中 `col` 的 `width` 值 |
 | 图表没有显示 | 检查 `chartPlotArea` 和 `chartData` 是否都包含，`dim1` / `dim2` 数据数量是否匹配 |
 | 图片被裁掉一部分 | `<img>` 的 `width` / `height` 是裁剪后尺寸；要整图显示就让 `width:height` 对齐原图比例 |
-| 图片不显示 / `<img src>` 仍是 `@path` | `@` 占位符只在 `+create --slides` 中替换；直接调 `xml_presentation.slide create` 必须先用 `+media-upload` 拿 `file_token` |
+| 图片不显示 / `<img src>` 仍是 `@path` | `@` 占位符只在 `+create --slides` 中替换；直接调 `xml_presentation.slide.create` 必须先用 `+media-upload` 拿 `file_token` |
 | 新插入的 `<img>` 挡住原有元素 | `slide.get` 读原页，对照已有块坐标挑空白位置；空间不够就在同一批 `--parts` 里先移动/缩小现有块再插图 |
 | 渐变背景变成白色 | 渐变必须用 `rgba()` 格式 + 百分比停靠点，如 `linear-gradient(135deg,rgba(30,60,114,1) 0%,rgba(59,130,246,1) 100%)` |
+| 整体风格不统一 | 封面页和结尾页用同一背景，内容页保持一致的配色和字号体系 |
 
 ## Common Errors
 
@@ -34,12 +46,18 @@
 | 400 XML 格式错误 | XML 语法错误 | 检查标签闭合、属性引号、特殊字符转义 |
 | 400 请求包装错误 | `--data` 未按 schema 包装 | 检查是否传入 `xml_presentation.content` 或 `slide.content` |
 | 创建成功但页面空白 / 内容缺失 / 布局错乱 | 常见于 `--slides '[...]'` 的 shell 转义或长参数传递问题 | 改用两步创建，并在创建后立即读取 XML 验证 |
-| 403 权限不足 | 身份或 scope 不匹配 | 先检查是否误用了 bot 身份，再确认 scope 和文档权限；无权限时根据错误响应引导用户解决 |
+| 403 权限不足 | scope 或文档权限不匹配 | 确认 scope 和文档权限；无权限时根据错误响应引导用户解决 |
 | 404 演示文稿不存在 | `xml_presentation_id` 不正确或无权限 | 检查 token；wiki URL 需先解析真实 `obj_token` |
 | 404 幻灯片不存在 | `slide_id` 不正确 | 重新读取 presentation 或 slide，确认最新 ID |
 | 400 无法删除唯一幻灯片 | 演示文稿至少保留一页 | 先创建新页，再删除旧页 |
 | 1061002 媒体上传 params error | slides 媒体上传参数不符合约定 | 用 `slides +media-upload`，不要手拼原生 `medias/upload_all`；slides 唯一可用 `parent_type` 是 `slide_file` |
-| 1061004 forbidden | 当前身份对演示文稿无编辑权限 | 确认 user/bot 对目标 PPT 有编辑权限；bot 常见于 PPT 非该 bot 创建 |
+| 1061004 forbidden | 当前用户对演示文稿无编辑权限 | 确认当前用户对目标 PPT 有编辑权限 |
 | 3350001 | XML 非 well-formed、XML 结构不符合服务端要求，或 replace 片段问题 | 优先检查未转义字符；replace 场景再看 `block_id` 和 `<content/>` |
 | 3350002 | `revision_id` 大于当前版本 | 用 `-1` 取当前版本，或重新用 `slides +xml-get` 取最新 `revision_id` |
 | validation: unsafe file path | `--file` 给了绝对路径或上层路径 | `--file` 必须是 CWD 内相对路径；先 `cd` 到素材目录再执行 |
+
+## Command-Specific References
+
+- 图片上传、`@path` 占位符、`file_token`：见 [lark-slides-media-upload.md](lark-slides-media-upload.md) 和 [lark-slides-create.md](lark-slides-create.md)。
+- 块级替换、`block_id`、3350001 replace 细节：见 [lark-slides-replace-slide.md](lark-slides-replace-slide.md)。
+- 原生 `slide.create` 包装、`before_slide_id` 和 jq 模板：见 [lark-slides-xml-presentation-slide-create.md](lark-slides-xml-presentation-slide-create.md)。

package/skills/lark-slides/references/validation-checklist.md

@@ -25,19 +25,32 @@ lark-cli slides +xml-get --as user \
   --json
 ```
 
-## Automated XML Text Overlap Lint
+## Automated XML Layout Lint
 
-提交前本地 XML 必须运行 XML 语法和文本重叠静态检查：
+`slides +xml-get` 保存 XML 后，只运行统一版式准出入口。先取得当前已加载 `lark-slides/SKILL.md` 的父目录，记为 `<lark-slides-skill-dir>`；不要猜测全局安装路径。
 
 ```bash
-python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentation-or-slide.xml>
+python3 "<lark-slides-skill-dir>/scripts/xml_text_overlap_lint.py" --input <presentation.xml>
 ```
 
-通过标准：
+它一次检查 XML/SXSD 合法性、元素越界、文本重叠、空白页、文本高度风险、整页内容稀疏和大卡片内容覆盖率。大卡片自身 `<content>` 的估算文本面积与卡片内平级元素一起参与覆盖率并集计算。
 
-- `summary.error_count == 0`。任何 error 都必须先修复再提交接口。
-- 当前工具检查 XML well-formed、SXSD tag/attr 支持情况、IconPark icon 类型和 icon 填充可见性、文本元素之间的明显重叠，以及 whiteboard 容器与外部 sibling 元素的可疑边界重叠；它不检查越界、文本高度不足、图文压盖、表格/图表压盖或底部拥挤。
-- 该工具不能替代页数核对、关键内容核对或真实视觉验收。
+准出规则：
+
+- `summary.error_count > 0` 或 `summary.release_ready == false`：阻断创建、替换或交付，必须先修复。
+- `summary.warning_count > 0`：静态检查不直接阻断，但 `summary.screenshot_review_required == true`，必须复核对应页面截图。
+- `slides[].status` 为 `blocked`、`needs_screenshot_review` 或 `passed`，可直接决定逐页后续动作。
+- CLI 在存在 `error` 时退出码为 1；只有 `warning` 时仍输出 JSON 并退出 0，供截图复核链路继续执行。
+
+每条 `error` / `warning` 都包含：
+
+- `element_ids`：相关 XML 元素 ID；
+- `rule`：规则 ID、名称、阈值和比较关系；
+- `measurement`：越界量、交叠面积、覆盖率等实测值；
+- `related_objects`：相关对象的类型与坐标框；
+- `target`、`message`、`hint`：页码、语义说明和处理建议。
+
+当 `sparse_container_content.measurement.content_coverage_ratio < rule.threshold` 时，需要结合同页截图判断留白是否有意设计；不要仅凭 warning 自动扩充内容。
 
 常见 code 的处理方向：
 
@@ -51,7 +64,39 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 | `icon_missing_fill_color` | 视觉规范要求 `<icon>` 设置 `<fill><fillColor color="..."/></fill>`，避免图标不可见 | 给 `<icon>` 添加显式非透明填充色，例如 `rgba(37, 99, 235, 1)` |
 | `icon_transparent_fill_color` | `<icon>` 的 `fillColor` 是透明色，不满足视觉可见性要求 | 改成与背景有足够对比的非透明颜色 |
 | `bbox_overlap` | 文本元素的估算绘制区域明显重叠 | 拉开文本坐标、缩小文本框/字号，或改成明确的分栏/分组结构 |
-| `whiteboard_external_overlap` | whiteboard 容器 bbox 与外部 sibling 元素跨边界重叠 | 按 lint `hint` 缩小或移动 whiteboard / 外部元素；若接受该风险，最终必须以截图 QA 或等价渲染视觉检查为准 |
+| `*_out_of_canvas` | 元素边界超出页面画布 | 根据 `measurement.overflow` 移回画布或缩小尺寸 |
+| `blank_slide` | 页面没有画布内可见内容 | 补充主体内容；仅有空背景或空形状不能准出 |
+| `sparse_container_content` | 大卡片内容覆盖率低于阈值 | 按元素 ID 定位卡片，结合截图判断是否补充或放大内容 |
+| `sparse_slide_content` | 全页有效内容覆盖率偏低 | 复核截图，确认是否为有意留白 |
+
+## Screenshot QA
+
+获取页面截图后，必须做视觉验收；不要只凭 XML 回读或静态 lint 结论声称截图验收通过。验收时假设页面存在问题，主动寻找并报告所有风险，包括轻微问题。
+
+```text
+请逐页目视检查这些幻灯片截图。先假设存在问题，并尽量找出它们。
+
+重点检查：
+- 元素重叠：文字与形状、图片或图表互相遮挡，线条穿过文字，卡片或标签堆叠。
+- 文本溢出或被裁切：靠近页面边缘、文本框边界或卡片边界处被截断。
+- 装饰元素位置错误：分割线、强调线或标签底板按单行文字布置，但标题或正文换行后压住文字或距离异常。
+- 来源标注、页脚或页码与上方内容碰撞。
+- 元素距离过近：相邻元素间距明显不足，卡片或分区几乎贴在一起；按 960x540 画布估算，小于约 15 px 的间隔通常要标记。
+- 间距不均：局部留白过大，另一处过于拥挤。
+- 页面边距不足：主体内容贴近幻灯片边缘；按 960x540 画布估算，小于约 30 px 的外边距通常要标记。
+- 列、卡片、图标或同类元素没有稳定对齐。
+- 图片或图表渲染异常：空白、变形、低清、关键内容不可读或预期图形缺失。
+- 文本对比度不足，例如浅灰文字放在米色或浅色背景上。
+- 图标对比度不足，例如深色图标放在深色背景上，且没有浅色圆形或底板承托。
+- 文本框过窄，导致不必要的频繁换行。
+- 残留占位符、模板默认文字或未替换内容。
+
+对每一页分别列出发现的问题或可疑区域，即使只是轻微问题也要记录。
+
+报告所有发现的问题，包括轻微问题。
+```
+
+必须根据问题严重度决定是否修复：空白页、破图、文字遮挡、明显裁切、低对比不可读、占位符残留等必须先修复再交付；轻微间距或对齐问题如果不修复，最终验证记录要说明已知风险。
 
 ## Page Count And Structure
 
@@ -85,14 +130,6 @@ python3 skills/lark-slides/scripts/xml_text_overlap_lint.py --input <presentatio
 - 大量形状坐标完全相同，导致主体内容重叠。
 - 渐变背景回退成空白或白底，导致文字不可读。
 
-## Whiteboard Elements
-
-`slide.get` 回读 XML 时，`<whiteboard>` 块只返回位置属性（`topLeftX`、`topLeftY`、`width`、`height`），SVG / Mermaid 内容**不随 XML 返回**。
-
-- whiteboard 验证可以核对坐标是否越界：`topLeftX + width ≤ 960`，`topLeftY + height ≤ 540`；lint 还会报告 whiteboard 容器与外部 sibling 元素的可疑边界重叠。
-- SVG 和 Mermaid 内容的正确性无法通过回读 XML 验证，需要人工视觉验收。
-- 不要在验证记录中声称 whiteboard 内容已验证，除非用户确认了视觉效果。
-
 ## Layout And Overflow Risk
 
 优先修复这些明显风险：

package/skills/lark-slides/references/visual-planning.md

@@ -7,27 +7,29 @@
 ## Core Rules
 
 - `layout_type` must change geometry: element positions, region sizes, alignment, and visual rhythm must differ across page types.
-- `visual_focus` determines the largest or highest-contrast region. It can be an image, diagram, metric, quote, table, or shape-based placeholder.
+- `visual_focus` determines the largest or highest-contrast region. It can be an image, diagram, metric, quote, or table.
 - `text_density` caps visible text:
   - `low`: title plus one short statement, or 1-3 labels.
   - `medium`: title plus 2-4 concise bullets or labeled regions.
   - `high`: use a table, columns, grouped labels, or annotations. Do not use one long bullet box.
 - Do not create a deck where every content page is title plus bullets. For 4 or more pages, use at least 4 different layout structures when the content allows.
-- Keep generous margins. Use `60-80` px outer margins on standard content pages unless a full-bleed image or cover treatment is intentional.
+- Keep safe outer margins around `40` px on standard content pages, and fill the content area densely with a card grid rather than leaving large empty space. Only go full-bleed for an intentional image or cover treatment.
 - Reserve vertical space for titles. A typical content title area is `y=36..90`; main content should usually start at `y>=110`.
 - Avoid crowding the bottom edge. Keep non-background content above `y=500` unless it is a footer.
-- Prefer fewer, larger objects over many small text boxes.
 - Keep backgrounds consistent with the deck's `visual_system.background_strategy`. Normal content pages should use the same base background unless there is a clear page-role reason to change.
 - Treat text fit as a layout constraint, not a cleanup step. If a text box is too small for the intended line count, shorten the text, split it, or allocate more space before creating XML.
+- Do not use `<shape>` to build pictorial visuals like mock photos or fake objects. Use the image generation tool instead.
+- Do not place a `rect` or `line` for dividing or decorative purposes directly under a `headline` or `title`.
+- Do not use section bands, horizontal bars, vertical bars, or page-edge strips.
 
 ## Background And Motif Consistency
 
 Decks can vary page backgrounds, but variation must be intentional and legible:
 
 - Pick one default background for ordinary content pages and reuse it exactly. Avoid near-identical drift such as several slightly different off-white values unless it encodes a clear section change.
-- Cover, section divider, emphasis, and conclusion pages may use a dark, image-led, or high-contrast background. They must still share the deck's primary color, motif, edge treatment, typography, or geometry.
+- Cover, section divider, emphasis, and conclusion pages may use a dark, image-led, or high-contrast background. They must still share the deck's primary color, motif, typography, or geometry.
 - If a cover uses a split composition, make the split visible in the background or layout. For example, reserve a darker text region and a related but distinct visual region instead of placing all elements on one flat field.
-- Reuse a small number of visual devices: side bar, card radius, node style, line weight, icon container, or footer treatment. Do not introduce a new decorative language on each page.
+- Reuse a small number of visual devices: card radius, node style, icon container, or footer treatment. Do not introduce a new decorative language on each page.
 - Insert background and motif shapes before content elements so they do not cover text, images, or diagrams.
 
 ## Text Fit Guardrails
@@ -38,11 +40,11 @@ Use these as conservative minimums on a 960 x 540 canvas. Increase height when u
 |----------|-------------------|----------------|
 | Caption, 1 line | 10-12 | 18 |
 | Caption, 2 lines | 10-12 | 30 |
-| Body, 1 line | 13-16 | 24 |
-| Body, 2 lines | 13-16 | 40 |
-| Body, 2 lines, bold | 15-18 | 48 |
-| Headline, 1 line | 24-32 | 42 |
-| Title, 2 lines | 34-44 | 110 |
+| Body, 1 line | 12-14 | 24 |
+| Body, 2 lines | 12-14 | 40 |
+| Body, 2 lines, bold | 12-14 | 48 |
+| Headline, 1 line | 20-28 | 42 |
+| Title, 2 lines | 28-36 | 110 |
 
 Additional rules:
 
@@ -62,11 +64,12 @@ Purpose: introduce the deck's point of view.
 Geometry:
 - Use one dominant title block, usually `x=70..120`, `y=150..250`, `width=700..820`.
 - Add one subtitle or context line, not a bullet list.
-- Optional visual focus can be a full-bleed background, large side image, accent band, or abstract shape motif.
-- If the cover has a right-side diagram, screenshot, or motif cluster, use a split layout: keep the title/subtitle region within the left or central text region, and reserve a separate visual region so labels and connectors do not cross the title.
+- Visual focus MUST be an `<img>`: a full-bleed background image or a large **full-height** side image (searched by the image search tool or generated by the image generation tool). Do NOT compose the cover visual from `<shape>` or `<icon>`.
+- If the cover has a large full-height side image, use a split layout: keep the title and subtitle in the text region on the opposite side, and reserve a separate visual region so the image does not overlap the title. Crop (size and place) the side image so it stays within its visual region and does not extend into the text region.
 - For split covers, make the background reinforce the composition, such as a darker text side and a related visual panel. Avoid one flat field where title and diagram compete for attention.
 - Keep source metadata to one short line where possible. If it wraps, shorten author lists or move details to notes.
 - The main title should be controlled, normally one or two lines. Do not let it occupy both the text region and the visual region.
+- Do not add a vertical accent bar, side rail, or decorative line/strip. 
 
 Text:
 - `low` only unless the user explicitly asks for detail.
@@ -78,7 +81,7 @@ Purpose: reset rhythm and mark a new chapter.
 Geometry:
 - Use a large section number, chapter label, or single centered claim.
 - Keep the page sparse. A divider is not a content page.
-- Visual focus can be one oversized number, a vertical accent bar, or a full-width band.
+- Visual focus can be one oversized number.
 
 Text:
 - Title plus one phrase. No bullets.
@@ -103,7 +106,7 @@ Purpose: let a visual establish context, with text explaining implication.
 Geometry:
 - Left visual region should occupy roughly `35-45%` of slide width, often full height or tall crop.
 - Right text region starts around `x=420` and should have a strong headline plus short support.
-- If no real image is available, create a shape-based placeholder visual that matches `asset_need`.
+- If no image is available, use the image generation tool to create an approximate image that matches `asset_need`.
 - For dense screenshots, paper figures, or product captures with small labels, allocate a larger visual region when possible: often `50-65%` of slide width or at least `320` px height.
 - Place screenshots in a deliberate frame or panel, and leave enough margin so axes, captions, and edge labels are not cropped by the slide boundary.
 
@@ -118,7 +121,7 @@ Purpose: lead with a message, then reinforce it with a visual.
 Geometry:
 - Left text region starts around `x=60..90`, width `400..460`.
 - Right visual region occupies roughly `35-45%` of slide width.
-- Align the image or placeholder with the main text block, not only with the title.
+- Align the image with the main text block, not only with the title.
 - For dense screenshots, paper figures, or product captures with small labels, increase the visual region and reduce text. A readable image is more valuable than a fully populated text column.
 
 Text:
@@ -130,8 +133,8 @@ Text:
 Purpose: make one metric or fact memorable.
 
 Geometry:
-- Reserve the largest object for the metric: font size often `64-110`, region at least `300 x 120`.
-- Set `autoFit="normal-auto-fit"` on the metric's `<content>` so an oversized number shrinks to fit its box instead of overflowing.
+- Reserve the largest object for the metric: font size often `40-52`.
+- MUST Set `wrap="true" autoFit="normal-auto-fit"` on the metric's `<content>` so an oversized number shrinks to fit its box.
 - Pair the number with one explanation and optional 2-3 small supporting labels.
 - Do not bury the number in a bullet list or small card.
 
@@ -169,7 +172,7 @@ Text:
 
 Purpose: explain components, dependencies, or system flow.
 
-Implementation: prefer Mermaid `<whiteboard>` (see `lark-slides-whiteboard.md`); use `<shape>` + `<line>` as fallback.
+Implementation: use `<shape>` + `<line>`.
 
 Geometry:
 - Main visual area should be a diagram, not prose.
@@ -185,7 +188,7 @@ Text:
 
 Purpose: show operational steps, workflow, or cause-effect path.
 
-Implementation: prefer Mermaid `<whiteboard>` (see `lark-slides-whiteboard.md`); use `<shape>` + `<line>` as fallback.
+Implementation: use `<shape>` + `<line>`.
 
 Geometry:
 - Use numbered steps connected by arrows or lines.
@@ -214,19 +217,19 @@ Purpose: close with decision, recommendation, or next action.
 
 Geometry:
 - Use one dominant closing statement or call to action.
-- Add up to 3 next-step cards, checklist items, or owner/date labels.
 - Visual focus should be the recommendation or action, not decorative filler.
+- When using a full-bleed background image, add a semi-transparent scrim between the image and the text so the text stays legible; verify contrast.
 
 Text:
 - Keep the final page easy to remember. Avoid recap overload.
-- Conclusion pages may mirror the cover background, but must clearly reuse the deck's motif or color roles so the ending feels intentional.
+- Conclusion pages may mirror the cover background.
 
 ## Screenshot And Paper Figure Pages
 
 When a page uses a real screenshot, chart, paper figure, or product capture:
 
 - Choose screenshot placement based on page role, not a fixed slide number. Method overview, evidence, comparison, and failure-analysis pages are common candidates; title, agenda, and conclusion pages usually are not.
-- Use the real asset only when it is readable at slide size. If the figure is too dense, crop to the relevant region, create a zoomed detail, or redraw the core message with native shapes.
+- Use the real asset only when it is readable at slide size. If the figure is too dense, crop to the relevant region, create a zoomed detail, or regenerate the core message with the image generation tool.
 - A screenshot should normally be the visual focus. Do not shrink it into a decorative thumbnail while surrounding it with dense text.
 - Pair the image with a small number of interpretive annotations that tell the audience what to notice.
 - Always include a short source caption when using external or paper-derived visuals.