# XML 扩展块补充说明
本文件用于补充说明 block XML 扩展能力。常用标签和通用规则见 [`lark-doc-xml.md`](lark-doc-xml.md)；后续新增其他 block 说明时可继续追加到本文件。
## 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
...
```
### 布局与高度
- `lark-cli` 会读取 `.html` 文件并原样写入 `reference_map`，不会解析或校验 `html-box-height-mode`；创建或更新文档前在 `` 中显式声明 `auto` 或 `viewport`。
- 生成时只使用 `auto` 或 `viewport`，不要臆造 `fixed`、`initial` 或像素值等其他 mode。
- 文档常见可用宽度约 `820px`；根容器使用 `width: 100%`、`max-width: 100%`、`box-sizing: border-box`。
四种策略：
1. 内容自然撑开：`auto` + 普通文档流；根容器不设固定高度或 `overflow: hidden`。
2. 仅按初始内容定高：`auto` + 首次渲染后不再追加或展开内容。
3. 固定像素操作区：`auto` + 业务容器按场景设置固定的 CSS `height` 和 `overflow: auto`；高度数值不写进 meta。
4. 单屏应用：`viewport` + `100vh` + 内部滚动、切页或缩放；适用于游戏、幻灯片、Dashboard、canvas 编辑器。
正文需要在飞书文档中完整展开时选 `auto`；内容应在 HTML Block 内滚动时选 `viewport`。`lark-cli` 不参与页面加载后的高度刷新，不要臆造相关 CLI flag。
### 内容限制
- HTML 总长度上限为 500KB。不要内联大图片、Base64、字体、长 JSON/CSV 或大量 mock 数据。
## OKR block
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` 承载进展内容，支持更新。直接子节点支持 ``、``、``、`![]()
`、``、``、`