# 文档表达组件参考

本文件说明飞书文档可用的结构化表达方式，供模型在需要时选择。它不是固定模板，也不是强制排版规范。

默认原则：优先理解用户目标、受众、素材形态和已有文档风格，由模型自主决定结构、语气和视觉呈现。只有当用户明确要求“美化、重排版、做成报告/方案/看起来更专业”等，或内容本身明显需要结构化承载时，才主动使用下列组件。

## 一、核心原则

1. **服务内容，而非套模板**：先判断信息最自然的表达方式，再选择段落、列表、表格、分栏、画板等元素
2. **尊重用户风格**：用户给出样例、语气、结构或已有文档时，优先沿用；没有要求时不强行使用固定开头、固定章节或固定视觉组件
3. **适度结构化**：结构化 block 用于降低理解成本，不为了“丰富”而堆叠
4. **保持一致但不过度统一**：同类信息可使用相近表达，但允许因内容差异采用不同形式
5. **图示服务理解**：流程、架构、对比、风险、路线图、指标趋势等内容在图示明显降低理解成本时，可使用画板表达

## 二、元素选择指南

需要图表时，按类型选择插入方式：思维导图/时序图/类图/饼图/甘特图可用 `<whiteboard type="mermaid">` 直接内嵌；其他新图表可启动 SubAgent 插入 `<whiteboard type="svg">完整 SVG</whiteboard>`；只有编辑**已有**画板时才调用 **lark-whiteboard** skill。

| 场景                                         | 可选表达方式                                |
|--------------------------------------------|---------------------------------------|
| 少数需要视觉提醒的短句，如风险、限制、待确认事项或关键提醒          | 需要视觉提醒时可用 `<callout>`；普通结论、摘要或章节导语优先使用段落、列表、小标题或加粗 |
| 方案对比 / 优劣势 / Before vs After                | 简短对比可用段落、列表或 `<grid>`；维度较多且需要逐项比较时再考虑 `<table>` 或画板 |
| 简短低风险对比                                    | `<grid>` 2 列分栏                        |
| 需要按行列精确比较或查阅的数据，如指标、清单、字段说明、排期           | 可用 `<table>`；短要点、步骤、摘要或普通说明优先使用段落、列表或小标题 |
| 任务清单 / 检查项                                 | `<checkbox>`                          |
| 代码片段                                       | `<pre lang="x" caption="说明">`         |
| 引用 / 公式                                    | `<blockquote>` / `<latex>`            |
| 操作入口 / 跳转链接                                | `<button>` / `<a type="url-preview">` |
| 流程图 / 时间线 / 示意图 / 自定义图形 / 架构图 / 数据图 / 思维导图等 | 画板图表                                  |


### 画板意图识别

撰写或审查每个段落/章节时，**必须判断该内容是否适合用图表达**。满足以下任一特征时，应使用画板而非纯文本；如果该内容承载章节核心结论、关键决策或主要论据，即使结构较简单也优先画板化：

| 内容特征 | 信号词 / 模式 | 推荐画板类型 |
|-|-|-|
| 多步骤的操作流程或决策路径 | "先…然后…最后"、"步骤 1/2/3"、"如果…则…否则" | 流程图 / 泳道图 |
| 系统或模块间的依赖与交互 | "调用"、"依赖"、"上游/下游"、"请求→响应" | 架构图 |
| 上下级或从属关系 | "汇报给"、"下属"、"隶属"、"团队结构" | 组织架构图 |
| 时间线或阶段演进 | "Q1/Q2"、"里程碑"、"阶段一→阶段二"、日期序列 | 时间线 / 里程碑 |
| 因果分析或问题归因 | "根因"、"原因"、"导致"、"影响因素" | 鱼骨图 |
| 两个及以上方案/对象的多维度对比 | "vs"、"方案 A/B"、"优劣"、"对比" | 对比图 |
| 层级递进或优先级排序 | "基础→进阶→高级"、"L1/L2/L3"、"核心→外围" | 金字塔图 |
| 数值趋势或周期变化 | 带数字的时间序列、"增长/下降"、百分比变化 | 折线图 / 柱状图 |
| 漏斗或转化率 | "转化率"、"漏斗"、"从…到…留存" | 漏斗图 |
| 发散或归纳的思维结构 | "要点"、"维度"、"分支"、多层嵌套列表 | 思维导图 |
| 循环或飞轮效应 | "正循环"、"飞轮"、"闭环"、"A 驱动 B 驱动 C" | 飞轮图 |
| 占比分布 | "占比"、"份额"、"分布"、百分比加总 ≈100% | 饼图 / 树状图 |

**判断规则：**
- 重要信息能图示就图示；不要为了省步骤把关键流程、架构、对比、风险链路写成纯文本
- 低重要度、局部辅助信息才用 `<table>` / `<grid>` / `<callout>` 承载
- 确定需要插入哪些图表后，参照 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 中的方式，插入图表画板。

## 三、颜色语义

如果使用颜色，建议保持语义一致；不需要颜色时可以保持朴素文本风格：

| 语义 | emoji 前缀 | callout 背景色 | 文字色 |
|-|-|-|-|
| 信息、说明 | ℹ️ "说明：" | `light-blue` | `blue` |
| 成功、推荐 | ✅ "推荐：" | `light-green` | `green` |
| 警告 / 错误 / 风险 | ⚠️❌ | `light-red` | `red` |
| 注意、待确认 | ❗"注意：" | `light-yellow` | `yellow` |
| 中性、辅助 | — | `light-gray` | — |

- 表头可使用 `background-color="light-gray"`，也可以保持默认样式
- 关键指标如使用 `<span text-color="green/red">` 突出，建议同时用 ↑↓ 或 +/- 标注方向（色觉无障碍）

## 四、排版规范

- 标题层级、段落长度、列表嵌套和 Grid 列数应以可读性为准，避免过深层级和过宽分栏
- 文档开头可以是结论、背景、摘要、问题陈述、目录或直接正文，不强制使用 `<callout>`

## 五、质量自检

生成内容后可以从以下角度自检，但不要把这些项当作硬性比例或固定模板：

| 指标 | 自检问题 |
|-|-|
| 信息表达 | 当前结构是否符合用户目标，而不是套用固定报告模板？ |
| 阅读负担 | 是否有段落过长、层级过深、表格过宽或组件过多的问题？ |
| 风格匹配 | 是否延续了用户给定样例或已有文档风格？ |
| 组件必要性 | callout、grid、table、whiteboard 等是否真的提升理解？ |
| 保真度 | 改写时是否保留了原文事实、引用、图片、附件和资源块？ |