飞书文档可读性优化

# 飞书文档可读性优化 Skill

## 概述

本 Skill 旨在解决飞书云文档（Lark Doc）在自动化编辑中常见的格式问题，重点提升文档的视觉层次感和可读性。它基于对飞书 Markdown 渲染引擎底层逻辑（API vs. 交互式编辑）的深入理解，提供了一套经过验证的“最佳实践”。

## 🏆 三大核心原则

### 1. 🚀 核心铁律：最小修改原则 (The Principle of Minimal Modification)

**权重：最高 (Critical)**
**定义**：任何格式优化都必须是“手术刀式”的精准微调，**严禁**因为修改一个标点而重写整个段落，更不可重写整篇文档。

**❌ 绝对禁止：**
- **严禁使用 `overwrite` 模式**：除非旨在清空文档重写，否则绝不允许使用 `overwrite` 进行修改，这会导致评论、历史记录、图片 Token 和未知的富文本属性丢失。
- **严禁大范围选区**：`selection_with_ellipsis` 不得跨越多个不相关的段落或标题。
- **严禁盲目重构**：不得在未获取该段落完整 Token（如图片、公式）的情况下重写包含该 Token 的段落。

**✅ 最佳实践：**
- **字节级定位**：`selection` 应短至仅仅包含“待修改目标 + 确保唯一的最小上下文”。
    - ✅ 优秀：`selection="token=\"xxx\"...**标题"` （利用 Token 定位）
    - ✅ 优秀：`selection="。**下一标题"` （利用标点定位）
    - ❌ 错误：`selection="上一段开头...下一段结尾"` （范围太广，极易误伤）
- **增量操作**：优先使用 `insert_before` / `insert_after` 插入内容，而非 `replace_range` 替换内容。
- **格式隔离**：确保修改后的 Markdown 文本与原文在“未修改部分”完全一致（包括此时看不到的隐藏字符）。

### 2. 间距法则 (The Law of Visual Spacing)

**权重：高 (High)**
**问题**：API 写入的 Markdown 纯文本会被飞书解析器进行“空白清洗”（Whitespace Optimization），导致标准的空行被合并，文档显得拥挤。

**✅ 解决方案**：使用 **带属性的占位段落** ` {align="center"}`。
只有带有非默认属性（如 Center）的空段落，才会被解析器视为“有意义的内容”而强制保留。

**📜 书写规范（基于最小修改原则）：**
1.  **插入式注入**：使用 `insert_before` 在标题前插入 Spacer，而非 Replace 整个标题块。
2.  **必须以空格开头**：` {align...`（无空格会被渲染为乱码文本）。
3.  **列表后阻断**：若前文是列表，必须使用 **双换行** `\n\n` 先结束列表，再插入标记。

### 3. 本土化格式卫生 (Formatting...