@amaster.ai/pi-lark 0.1.2-beta.45 → 0.1.2-beta.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/pi-lark",
-  "version": "0.1.2-beta.45",
+  "version": "0.1.2-beta.46",
   "description": "Pi extension for Lark/Feishu workspace — calendar, docs, drive, sheets, tasks, mail and more via lark-cli.",
   "keywords": [
     "pi-package",
@@ -61,7 +61,7 @@
     "vitest": "^4.0.0"
   },
   "dependencies": {
-    "@amaster.ai/pi-shared": "0.1.2-beta.45"
+    "@amaster.ai/pi-shared": "0.1.2-beta.46"
   },
   "scripts": {
     "fetch-skills": "node scripts/fetch-skills.mjs",

package/skills/lark-apps/references/lark-apps-file.md

@@ -28,7 +28,7 @@
 ## 各命令
 
 ### +file-list
-列出应用文件，支持精确过滤：`--name`（文件名）、`--path`（远端路径）、`--type`（MIME 类型）、`--size-gt`/`--size-lt`（字节）、`--uploaded-since`/`--uploaded-until`（上传时间区间，时间格式见末尾）。分页 `--page-size`（默认 20）/ `--page-token`。列表每项给名称、路径、大小、类型、上传时间（pretty 表格即这 5 列）；上传者、下载地址（如有）仅在 JSON 输出里，单文件详情用 `+file-get`。
+列出应用文件，支持精确过滤：`--name`（文件名）、`--path`（远端路径）、`--type`（MIME 类型）、`--size-gt`/`--size-lt`（字节）、`--uploaded-since`/`--uploaded-until`（上传时间区间，时间格式见末尾）。分页 `--page-size`（默认 20，范围 1..200）/ `--page-token`。列表每项给名称、路径、大小、类型、上传时间（pretty 表格即这 5 列）；上传者、下载地址（如有）仅在 JSON 输出里，单文件详情用 `+file-get`。
 
 ```bash
 lark-cli apps +file-list --app-id app_xxx

package/skills/lark-base/SKILL.md

@@ -29,7 +29,7 @@ metadata:
 ## 使用边界
 
 - Base 业务操作只使用 `lark-cli base +...` shortcut，不使用旧聚合式 `+table / +field / +record / +view / +history / +workspace`。
-- 本轮 Base 不依赖 `lark-cli schema`。SKILL 只保留路由、风险和复杂 JSON/DSL；简单命令由命令自身的参数、tips 和错误恢复承接。
+- 执行 update 前必须先查当前 shortcut 的 `--help` 或对应 reference。若命令要求完整配置，首次请求必须基于可信的当前配置执行 read-modify-write：只修改用户明确指定的内容，保留其他仍适用的可写配置，并按命令要求的结构提交。若命令支持局部／delta update，按其契约提交最小合法 payload；不得以不完整请求试错补参。
 - 用户要把 Excel / CSV / `.base` 导入成 Base 时，先转 `lark-cli drive +import --type bitable`，导入完成后再回到 Base 命令。
 - 认证、初始化、scope、身份切换、权限不足恢复属于 `lark-shared`；Base 文档只保留会影响 Base 路径选择的权限规则。
 
@@ -104,19 +104,18 @@ metadata:
 
 ## 写入前置规则
 
-- 更新前先看命令说明：需要完整提交时，先读取并补齐当前配置，只改用户指定的内容，再按命令要求提交；支持局部修改时，按命令说明和 reference 提交最小合法 payload。
 - 优先用写入返回确认结果；返回信息不足或任务明确要求核验时，再读回。
 - 写记录前先读字段结构；只写存储字段。系统字段、附件字段、`formula`、`lookup` 不作为普通记录写入目标。
 - 附件上传、下载、删除走专用 `+record-*-attachment` 命令。
 - 写字段前先读 [lark-base-field-json.md](references/lark-base-field-json.md)；涉及 `formula` / `lookup` 时必须读 [formula-field-guide.md](references/formula-field-guide.md) / [lookup-field-guide.md](references/lookup-field-guide.md)。
 - 表名、字段名、视图名、workflow 配置中的名称必须来自真实返回；跨表场景还要读取目标表结构。
-- 删除、角色更新、字段更新等高风险操作遵循 CLI 的 confirmation gate；目标不明确时先用 get/list 消歧。
+- 删除、角色更新、字段更新、表单提交（`+form-submit`）等高风险操作遵循 CLI 的 confirmation gate，必须带 `--yes`；目标不明确时先用 get/list 消歧。
 - 批量写入单批最多 200 条；连续写同一表时串行执行，遇到 `1254291` 按短暂等待后重试处理。
 - `select` 字段只支持写入字段中已有的选项；构造 CellValue 前先用 `+field-list` 或 `+field-search-options` 确认目标选项存在。
 
 ## 表单与视图细节
 
-- `+form-submit` 前必须先跑 `+form-detail`，读取 `questions[].type`、`required`、`filter` 和附件场景需要的 `base_token`；不要填写被 filter 隐藏的问题。
+- `+form-submit` 是高风险写操作，必须带 `--yes` 确认；调用前必须先跑 `+form-detail`，读取 `questions[].type`、`required`、`filter` 和附件场景需要的 `base_token`；不要填写被 filter 隐藏的问题。
 - 表单附件不要写进 `fields`，放在 `--json.attachments`；提交附件时必须同时传表单所属 Base 的 `--base-token`。
 - `+view-set-filter` 是唯一保留的 view reference；sort/group/card/timebar/visible-fields 这类配置先用对应 get 命令读现状，保留未修改字段，只替换用户要求变更的配置。
 - 视图适合持久化、共享和 UI 复用；一次性筛选/排序可先用 `+record-list` / `+record-search` 的 filter/sort 验证结果，再按需要沉淀为持久视图。

package/skills/lark-base/references/lark-base-form-submit.md

@@ -4,6 +4,8 @@
 
 通过表单分享链接填写并提交多维表格表单。仅支持分享模式（share_token），支持填写普通字段值和上传本地文件作为附件。
 
+> **⚠️ 高风险写操作（high-risk-write）：** 本命令会向表单写入并提交数据，属于高风险写操作，必须额外传递 `--yes` 进行确认，否则会返回 `confirmation_required` 错误并退出。当用户明确要求提交且目标表单无歧义时，直接附加 `--yes`，无需再次询问。
+
 ## 填写前必读：先获取表单详情
 
 **在调用 `+form-submit` 之前，必须先使用 `+form-detail` 获取表单详情。** 原因如下：
@@ -21,10 +23,11 @@ lark-cli base +form-detail --share-token <share_token>
 
 # 2️⃣ 根据返回的 questions 列表，按 type 格式化值、检查 required、判断 filter 条件
 
-# 3️⃣ 再提交
+# 3️⃣ 再提交（高风险写操作，必须带 --yes）
 lark-cli base +form-submit \
   --share-token <share_token> \
-  --json '{"fields":{...}}'
+  --json '{"fields":{...}}' \
+  --yes
 ```
 
 `+form-detail` 的返回中要重点读取 `questions[].type`、`questions[].required`、题目 `filter` 和附件场景所需的 `data.base_token`。
@@ -35,7 +38,8 @@ lark-cli base +form-submit \
 # 基本提交（填写普通字段）
 lark-cli base +form-submit \
   --share-token <share_token> \
-  --json '{"fields":{"服务评分":5,"评价内容":"服务态度好"}}'
+  --json '{"fields":{"服务评分":5,"评价内容":"服务态度好"}}' \
+  --yes
 
 # 带附件提交（需要额外提供 --base-token）
 lark-cli base +form-submit \
@@ -47,15 +51,17 @@ lark-cli base +form-submit \
       "附件字段名": ["./report.pdf", "./photo.png"],
       "另一个附件字段": ["./doc.docx"]
     }
-  }'
+  }' \
+  --yes
 
 # 使用应用身份（bot）
 lark-cli base +form-submit \
   --share-token <share_token> \
   --json '{"fields":{...}}' \
-  --as bot
+  --as bot \
+  --yes
 
-# 预览 API 调用（不实际执行）
+# 预览 API 调用（不实际执行，dry-run 无需 --yes）
 lark-cli base +form-submit \
   --share-token <share_token> \
   --json '{"fields":{...}}' \
@@ -69,6 +75,7 @@ lark-cli base +form-submit \
 | `--share-token <token>` | 是 | 表单分享 Token（必填），从表单分享链接中提取 |
 | `--base-token <token>` | 条件必填 | Base token；**当 `--json` 包含 `attachments` 时必须提供**，用于将附件上传到 Base Drive Media |
 | `--json <json>` | 是 | JSON 对象，包含 `"fields"`（普通字段值）和 `"attachments"`（附件上传），详见下方说明 |
+| `--yes` | 是 | 确认高风险写操作。本命令为 high-risk-write，不带 `--yes` 会返回 `confirmation_required` |
 | `--format` | 否 | 输出格式：json（默认）\| pretty \| table \| ndjson \| csv |
 | `--as` | 否 | 身份：user（默认）\| bot |
 | `--dry-run` | 否 | 预览 API 调用，不执行 |
@@ -138,7 +145,8 @@ https://www.example.com/share/base/form/shrbcvST8eZy0vk8zjVZ1CAXNye
 ```bash
 lark-cli base +form-submit \
   --share-token shrbcvST8eZy0vk8zjVZ1CAXNye \
-  --json '{"fields":{...}}'
+  --json '{"fields":{...}}' \
+  --yes
 ```
 
 ## 输出格式
@@ -158,6 +166,7 @@ lark-cli base +form-submit \
 
 ## 提示
 
+- **本命令为高风险写操作（high-risk-write），必须额外传递 `--yes` 确认**，否则返回 `confirmation_required` 并以非零码退出；`--dry-run` 预览除外
 - 本命令仅支持通过表单分享链接（share_token）提交，不支持通过 base_token + table_id + view_id 方式提交
 - **当 `--json` 包含 `attachments` 时，必须额外提供 `--base-token`**，因为附件上传到 Base Drive Media 需要指定目标 Base
 - 附件字段只需在 `--json.attachments` 中提供本地路径即可，CLI 自动完成校验、并行上传、Token 获取和合并写入

package/skills/lark-doc/references/lark-doc-xml.md

@@ -13,7 +13,7 @@ p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr
 ## 容器标签
 |标签|说明|关键属性|
 |-|-|-|
-| `<callout>` | 高亮框，子块仅支持文本、标题、列表、待办、引用 | `emoji`(默认 bulb), `background-color`, `border-color`, `text-color` |
+| `<callout>` | 高亮框，子块仅支持文本块（如 `<p>`）、标题、列表、待办、引用；禁止裸文本及 `<table>`、`<img>`、`<pre>`、`<hr>`、`<grid>`、`<whiteboard>`、`<sheet>` 等其他块级标签或资源块 | `emoji`(默认 bulb), `background-color`, `border-color`, `text-color` |
 | `<grid>` + `<column>` | 分栏布局，各列 width-ratio 之和为 1 | `width-ratio` |
 | `<whiteboard>` | 嵌入画板 | `type`: `blank` \| `mermaid` \| `plantuml` \| `svg` |
 | `<pre>` | （代码块，内含 `code`）| `lang`, `caption` |

package/skills/lark-drive/references/lark-drive-search.md

@@ -96,6 +96,7 @@ lark-cli drive +search --query 方案 --page-token '<PAGE_TOKEN>'
 - "某项目发布会重点" → 先搜项目名 + "发布会" + "重点/功能/一览"，再按标题和摘要判断是否需要只搜标题或扩大到正文。
 
 每轮扩展都要保留非污染、可解释的 evidence（URL/token/标题/摘要）；不能因为某个扩展词搜到高相似标题就跳过证据核验。
+扩展 query 时，优先保留用户已经指定的空间、文件夹、群聊、人员、时间和类型等 filter；确需放宽检索范围时，先向用户说明原因并征得确认。
 
 ## 参数
 

package/skills/lark-im/references/card/card-2.0-schema.md

@@ -29,7 +29,7 @@ Card 2.0 组件按**容器 / 展示 / 交互**三类，均通过 `tag` 字段声
     "title":    { "tag": "plain_text", "content": "卡片标题" },
     "subtitle": { "tag": "plain_text", "content": "副标题：一句上下文（时间/来源/状态）" },
     "template": "blue",
-    "icon": { "tag": "standard_icon", "token": "notice_colorful" },
+    "icon": { "tag": "standard_icon", "token": "lark-logo_colorful" },
     "text_tag_list": [
       { "tag": "text_tag", "text": { "tag": "plain_text", "content": "状态标签" }, "color": "blue" }
     ]

package/skills/lark-im/references/card/lark-im-card-style.md

@@ -105,12 +105,12 @@
 "header": {
   "title": { "tag": "plain_text", "content": "卡片标题" },
   "template": "blue",
-  "icon": { "tag": "standard_icon", "token": "mail_colorful" }
+  "icon": { "tag": "standard_icon", "token": "calendar_colorful" }
 }
 ```
 
-- `token` 从 `resource/icons.md` 按场景选取；彩色图标用 `*_colorful` 后缀，单色用普通名称。
-- 常用速查：通知 `notice_colorful`、告警 `warning_colorful`、审批 `approve_colorful`、日历 `calendar_colorful`、数据 `chart_colorful`、任务 `todo_colorful`、AI `myai_colorful`。
+- `token` 必须从 `resource/icons.md` 的精确枚举中选择；禁止根据名称规律自行拼接 token。没有合适的 token 时省略 icon。
+- 场景速查：日历 `calendar_colorful`、待办 `todo_colorful`、投票 `vote_colorful`、妙记 `file-lark-minutes_colorful`、多维表格 `wiki-bitable_colorful`、表单 `file-form_colorful`、社区 `larkcommunity_colorful`、招聘 `hirelogo_colorful`、飞书品牌 `lark-logo_colorful`、Meego `meego_colorful`、AI `myai_colorful`、aPaaS `apaas_colorful`、审批 `approval_colorful`、通用 AI `ai-common_colorful`。
 
 ### 1. 配色纪律（服务 P6 语义一致）
 
@@ -212,7 +212,7 @@ header 有三层能力，**尽量用满**（至少用 `title` + `icon`；`subtit
   "title":    { "tag": "plain_text", "content": "发版审批" },
   "subtitle": { "tag": "plain_text", "content": "2026-06-25 · 后端服务" },
   "template": "blue",
-  "icon": { "tag": "standard_icon", "token": "approve_colorful" },
+  "icon": { "tag": "standard_icon", "token": "approval_colorful" },
   "text_tag_list": [
     { "tag": "text_tag", "text": { "tag": "plain_text", "content": "待审批" }, "color": "yellow" }
   ]

package/skills/lark-im/references/card/resource/icons.md

@@ -34,5 +34,19 @@
 | 通知/铃铛 | `bell_outlined` | 定位 | `pin_outlined` |
 | 附件 | `attachment_outlined` | 审批 | `approval_outlined` |
 
+## 彩色图标（精确 token）
+
+彩色图标必须从下表按**完整字符串**选择，禁止根据名称规律自行拼接。彩色 token 自带颜色，不要再推导其他后缀或变体。
+
+| 含义 | token | 含义 | token |
+|---|---|---|---|
+| 日历 | `calendar_colorful` | 待办 | `todo_colorful` |
+| 投票 | `vote_colorful` | 飞书妙记 | `file-lark-minutes_colorful` |
+| 多维表格 | `wiki-bitable_colorful` | 表单 | `file-form_colorful` |
+| 飞书社区 | `larkcommunity_colorful` | 招聘 | `hirelogo_colorful` |
+| 飞书品牌 | `lark-logo_colorful` | Meego | `meego_colorful` |
+| AI | `myai_colorful` | aPaaS | `apaas_colorful` |
+| 审批 | `approval_colorful` | 通用 AI | `ai-common_colorful` |
+
 > token 必须与官方完全一致，否则图标不渲染。上表为常用项，全量（数百个，分系统/商务/沟通/用户/媒体/文档等类目）以官方图标库为准：
 > https://open.larkoffice.com/document/feishu-cards/enumerations-for-icons

package/skills/lark-slides/SKILL.md

@@ -101,9 +101,9 @@ metadata:
 
 **CRITICAL — 新建演示文稿或大幅改写页面时，规划 `asset_need` MUST 遵循 [asset-planning.md](references/asset-planning.md)：只做元数据规划，必须有 `fallback_if_missing`，不得要求真实搜索、下载或上传素材。**
 
-**CRITICAL — 将完整 `<slide>` XML 提交给 `slides +create --slides`、`xml_presentation.slide create` 或 `slides +replace-pages` 之前，MUST 先把待提交 XML 保存到本地文件并运行 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py)；`summary.error_count` 必须为 0 才能调用接口。**
+**CRITICAL — 将完整 `<slide>` XML 提交给 `slides +create --slides`、`xml_presentation.slide create` 或 `slides +replace-pages` 之前，MUST 先把待提交 XML 保存到本地文件并运行唯一版式准出入口 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py)；`summary.error_count` 必须为 0 才能调用接口，`summary.warning_count > 0` 时必须先做对应页面的截图复核。**
 
-**CRITICAL — 创建或大幅改写后，MUST 按 [validation-checklist.md](references/validation-checklist.md) 做显式验证：回读全文 XML、核对页数和关键元素、检查空白/破损页、明显溢出、布局风险；XML 语法和文本重叠静态检查优先使用 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py)。**
+**CRITICAL — 创建或大幅改写后，MUST 按 [validation-checklist.md](references/validation-checklist.md) 做显式验证：回读全文 XML、核对页数和关键元素，并使用 [`scripts/xml_text_overlap_lint.py`](scripts/xml_text_overlap_lint.py) 统一检查 XML、越界、重叠、空白页和内容稀疏风险。**
 
 **CRITICAL — 创建前自检或失败排障时，MUST 按 [troubleshooting.md](references/troubleshooting.md) 检查 XML 转义、结构、shell 截断、图片 token、3350001 和布局风险。**
 

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

@@ -4,7 +4,7 @@
 
 获取幻灯片页面截图并保存为本地图片文件。默认用于已存在 PPT 页面截图；传入 `--content` 时用于直接渲染单个 `<slide>` XML 片段预览。本 shortcut 会在 CLI 进程内解码并写入文件，stdout 只返回文件路径、大小、页面 ID 等元信息，避免把图片 Base64 输出给模型。
 
-注意：该截图能力受应用白名单限制，绝大多数应用不可用。截图失败时不要引导用户申请 `slides:presentation:screenshot` 权限；记录错误后降级到 XML 读回、结构 lint、文本重叠检查等非截图检查路径。
+截图失败则降级到 XML 读回、结构 lint等非截图检查路径。
 
 ## 命令
 
@@ -26,8 +26,8 @@ lark-cli slides +screenshot --as user \
 | 参数 | 必需 | 说明 |
 |------|------|------|
 | `--presentation` | list 模式必需 | `xml_presentation_id`、`/slides/` URL，或解析后为 slides 的 `/wiki/` URL。传 `--content` 时不能使用 |
-| `--slide-id` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面 short ID；多页截图时重复传入；一次最多 10 页（`--slide-id` + `--slide-number` 合计小于等于 10） |
-| `--slide-number` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面页号；多页截图时重复传入；一次最多 10 页（`--slide-id` + `--slide-number` 合计小于等于 10） |
+| `--slide-id` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面 short ID；多页截图时重复传入，或用逗号分隔一次传多个（如 `--slide-id slide_1,slide_2`）；一次最多 10 页（`--slide-id` + `--slide-number` 合计小于等于 10） |
+| `--slide-number` | list 模式至少提供 `--slide-id` / `--slide-number` 之一 | 页面页号；多页截图时重复传入，或用逗号分隔一次传多个（如 `--slide-number 1,2,3`）；一次最多 10 页（`--slide-id` + `--slide-number` 合计小于等于 10） |
 | `--content` | render 模式必需 | 要直接渲染的 `<slide>` XML 片段；支持直接传值、`@file`、`-` stdin。传入后不能同时传 `--slide-id` / `--slide-number` |
 | `--output-dir` | 否 | 输出目录，默认 `.lark-slides/screenshots`；必须是当前目录内的相对路径 |
 | `--output-name` | 否 | render 模式的输出文件名 stem；未指定时优先用返回的 `slide_id`，否则用 `rendered-slide`。若目标文件已存在，会自动追加递增后缀避免覆盖 |
@@ -44,7 +44,7 @@ lark-cli slides +screenshot --as user \
 
 ### 多页截图
 
-一次不要超过 10 页；如需更多页面，分批调用。
+一次不要超过 10 页；如需更多页面，分批调用。可以重复传参，也可以用逗号分隔一次传多个：
 
 ```bash
 lark-cli slides +screenshot --as user \

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

@@ -19,7 +19,7 @@
 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. 页面空白、溢出、重叠或越界时，按 [validation-checklist.md](validation-checklist.md) 运行 XML 文本重叠检查，并人工核对越界、截断、图文压盖等视觉风险；工具当前只会报告 `xml_not_well_formed` / `bbox_overlap`。
+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` 新页。
 

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
 
-`slides +xml-get` 保存 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.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 和文本元素之间的明显重叠；它不检查越界、文本高度不足、图文压盖、表格/图表压盖或底部拥挤。
-- 该工具不能替代页数核对、关键内容核对或真实视觉验收。
+准出规则：
+
+- `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,6 +64,10 @@ 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` | 文本元素的估算绘制区域明显重叠 | 拉开文本坐标、缩小文本框/字号，或改成明确的分栏/分组结构 |
+| `*_out_of_canvas` | 元素边界超出页面画布 | 根据 `measurement.overflow` 移回画布或缩小尺寸 |
+| `blank_slide` | 页面没有画布内可见内容 | 补充主体内容；仅有空背景或空形状不能准出 |
+| `sparse_container_content` | 大卡片内容覆盖率低于阈值 | 按元素 ID 定位卡片，结合截图判断是否补充或放大内容 |
+| `sparse_slide_content` | 全页有效内容覆盖率偏低 | 复核截图，确认是否为有意留白 |
 
 ## Screenshot QA
 

package/skills/lark-slides/references/xml-schema-quick-ref.md

@@ -188,6 +188,13 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 - `<shadow>`
 - `<content>`
 
+`type` 常用取值：`text`（文本框）、`rect`、`round-rect`（圆角矩形）、`ellipse`（椭圆/圆）、`triangle`、`diamond`、`parallelogram`、`trapezoid`、`custom`（配合 `path` 属性写 SVG 路径串）。箭头、星形、标注气泡、`chevron`、`flow-chart-*` 等更多形状见 XSD `ShapeType` 枚举。
+
+其它可选属性：
+
+- `presetHandlers`：控制点，用于圆角等。例如 `<shape type="rect" presetHandlers="60">` = 圆角半径 60px 的圆角矩形；多个控制点用逗号分隔。
+- `path`：仅 `type="custom"` 时使用，SVG 路径串。
+
 ### line
 
 ```xml
@@ -198,6 +205,16 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 
 `line` 使用的是 `startX` / `startY` / `endX` / `endY`，不是 `x1` / `y1` / `x2` / `y2`。
 
+### polyline
+
+折线 / 曲线连接线，用外接矩形定位（`topLeftX` / `topLeftY` / `width` / `height`），不是端点坐标；`<border>` 必填（无 border 不可见）。`type` 默认 `bent-connector2`（可选 `bent-connector2-5` 折线 / `curved-connector2-5` 曲线）。
+
+```xml
+<polyline topLeftX="120" topLeftY="120" width="200" height="100">
+  <border color="rgb(43, 47, 54)" width="2"/>
+</polyline>
+```
+
 ### img
 
 ```xml
@@ -238,6 +255,7 @@ XSD 中的 `title`、`headline`、`sub-headline`、`body`、`caption` 主要出
 - `<colgroup>` 直接子元素只有 `<col width="...">`，width 定义列宽，默认 110。
 - `<tr height="...">` 直接子元素只有 `<td>`，height 定义行高，默认 37。
 - `<td>` 直接子元素只有 `<fill>`（背景）、`<content>`（文字）和边框配置（一般不用），不能嵌套 `<shape>`、`<img>`、`<icon>`。
+- 合并单元格：`<td>` 上用 `colspan`（跨列，默认 1）和 `rowspan`（跨行，默认 1）；被合并覆盖的单元格不再写对应 `<td>`。
 
 表头默认的白底白字视觉效果极差，必须设置背景和文字颜色，需在首行每个 `<td>` 上加 `<fill>`（配合 `bold` 与对比文字色）与正文行区分。