# XML 扩展块补充说明
本文件用于补充说明 block XML 扩展能力。常用标签和通用规则见 [`lark-doc-xml.md`](lark-doc-xml.md)；后续新增其他 block 说明时可继续追加到本文件。
## 拓展标签
- ``
- ``：`action` 可为 `OpenLink`、`DuplicatePage` 或 `FollowPage`；可选 `background-color`、`src`。
- ``：使用毫秒时间戳。
- ``：创建空白表格；``：复制已有表格。
- ``：挂载任务，`task-id` 为任务 GUID。
- ``：挂载聊天卡片。
- ``：子页面列表块，仅 wiki 文档可插入。
## HTML5 block
1. 写入 HTML 内容块时，把完整单文件 HTML 存为本地 `.html` 文件，XML 写 ``；已有 `data-ref` 时配合 `--reference-map @./reference-map.json`。读取时 `` 只是占位，必须从 `document.reference_map["html5-block"]["html5_1"].data` 读取 HTML；若 entry 是 `path`，读取对应 `@./doc-fetch-resources/...html` 文件。
2. 格式如下：
```html
...
```
### 布局与高度
只使用 `auto` 或 `viewport`：正文需要在文档中完整展开时使用 `auto`；内容需要在 HTML Block 内滚动或单屏呈现时使用 `viewport`。`lark-cli` 会将 HTML 原样写入 `reference_map`，不会校验该字段，因此创建或更新前必须在 `` 中显式声明。
- `auto`：使用普通文档流，不给根容器设置固定高度或 `overflow: hidden`。需要固定操作区时，在业务容器上设置 CSS `height` 和 `overflow: auto`，不要把像素值写入 meta。
- `viewport`：使用 `100vh` 和内部滚动、切页或缩放，适用于游戏、幻灯片、Dashboard、canvas 编辑器。
- 页面加载后的内容追加或展开不会由 `lark-cli` 刷新高度，不要臆造相关 CLI flag。
- 文档常见可用宽度约 `820px`；根容器使用 `width: 100%`、`max-width: 100%`、`box-sizing: border-box`。
### 内容限制
- HTML 总长度上限为 500KB。不要内联大图片、Base64、字体、长 JSON/CSV 或大量 mock 数据。
## OKR block
``：创建时仅支持 root-only。
OKR block 可用 XML 格式完整表达。创建前先参考 [`lark-okr`](../../lark-okr/SKILL.md) 确认可用周期；创建时只写 root-only `` 挂载已有 OKR，不构造 Objective/KR/Progress 子树。
获取时，XML 结构示例如下：
```xml
O 描述
O 进展
事项
KR 描述
KR 进展
```
- `cycle-id` 仅用于创建时挂载已有当前周期 OKR；`cycle-name`、`user-name` 只读。
- `objective-id`、`key-result-id` 为只读业务 ID，更新已有 OKR 时保持不变。
- `okr-objective` / `okr-key-result`
- 可更新 `status`、`percent`、`score`；`percent` / `score` 取值 0-100，`status` 取值 `unset`/`normal`/`risk`/`extended`。
- 不可更新 objective 和 key-result 内容描述。
- `okr-progress` 承载进展内容，支持更新。直接子节点支持 ``、``、``、`![]()
`、``、``、`