feat(docs): soften lark doc style guidance

skills/lark-doc/SKILL.md

@@ -27,8 +27,9 @@ lark-cli docs +update --api-version v2 --doc "文档URL或token" --command appen
 1. [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) — 认证、权限处理、全局参数（所有操作通用）
 2. **读取文档（`docs +fetch --api-version v2`）** → 必读 [`lark-doc-fetch.md`](references/lark-doc-fetch.md)（`--scope` / `--detail` 选择、局部读取策略、`<fragment>` / `<excerpt>` 输出结构）
 3. **创建或编辑文档内容** → 必读 [`lark-doc-xml.md`](references/lark-doc-xml.md)（XML 语法规则，仅当用户明确要求 Markdown 时改读 [`lark-doc-md.md`](references/lark-doc-md.md)）；从零创建时加读 [`lark-doc-create-workflow.md`](references/style/lark-doc-create-workflow.md)；编辑已有文档时加读 [`lark-doc-update-workflow.md`](references/style/lark-doc-update-workflow.md)
+4. **需要使用 callout、grid、table、whiteboard 等富 block 时** → 参考 [`lark-doc-style.md`](references/style/lark-doc-style.md) 的元素能力说明。该文件不是固定模板或强制排版规范；除非用户明确要求美化、重排版或特定风格，不要为了“达标”主动套用固定结构。
 
-**未读完以上文件就执行相应操作会导致参数选择错误、格式错误或样式不达标。**
+**未读完以上文件就执行相应操作会导致参数选择错误或格式错误。**
 
 > **格式选择规则（全局）：**
 > - **创建 / 导入场景**（`docs +create`，或 `docs +update --command append/overwrite` 的整段写入）：XML 和 Markdown 都可以。用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；否则默认 XML（可用 callout、grid、checkbox 等富 block）。
@@ -41,7 +42,7 @@ lark-cli docs +update --api-version v2 --doc "文档URL或token" --command appen
   - 已知 block_id = `blkcn456`
   - 应返回 `https://xxx.feishu.cn/docx/doxcn123#blkcn456`
 - 用户需要在文档内**创建、复制或移动**资源块（画板、电子表格、多维表格等）时，必须先读取 [`lark-doc-xml.md`](references/lark-doc-xml.md) 的「三、资源块」章节
-- 写文档时，重要信息（核心流程、架构、对比、风险、路线图、关键指标、因果关系）优先规划为画板，不要只用文字或表格承载
+- 写文档时，由内容和用户意图决定表达形式；流程、架构、路线图、关键指标等信息可以使用画板，但不要默认把重要信息都画板化
 - 新增画板必须隔离到 SubAgent：简单图由 SubAgent 直接插入 `<whiteboard type="svg">完整 SVG</whiteboard>`，不读 `lark-whiteboard`；复杂图才由主 Agent 先建 `<whiteboard type="blank"></whiteboard>`，再启动 SubAgent 读取 `lark-whiteboard` 写入
 - 用户说"看一下文档里的图片/附件/素材""预览素材" → 用 `lark-cli docs +media-preview`
 - 用户明确说"下载素材" → 用 `lark-cli docs +media-download`

skills/lark-doc/references/lark-doc-create.md

@@ -2,10 +2,11 @@
 
 > **前置条件（MUST READ）：** 生成文档内容前，必须先用 Read 工具读取以下文件，缺一不可：
 > 1. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
-> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 排版指南（元素选择、丰富度规则、颜色语义）
-> 3. [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、并行执行策略）
+> 2. [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、并行执行策略）
 >
-> **未读完以上文件就生成内容会导致格式错误或样式不达标。**
+> **需要使用 callout、grid、table、whiteboard 等富 block，或用户明确要求美化/重排版时，再参考 [`lark-doc-style.md`](style/lark-doc-style.md)。该文件是表达组件参考，不是固定模板。**
+>
+> **未读完以上文件就生成内容会导致格式错误。**
 
 从 XML（默认）或 Markdown 内容创建一个新的飞书云文档。
 
@@ -74,7 +75,7 @@ lark-cli docs +create --api-version v2 --doc-format markdown --content $'# 项
 
 - 文档标题从内容中自动提取：XML 使用 `<title>`；Markdown 使用文档开头唯一的一级标题（`# 标题`），正文从 `##` 开始。不要在内容开头重复写标题，也不要在 Markdown 正文中使用多个一级标题。
 - **创建较长的文档时只建骨架**：`--content` 仅传标题 + 各级 heading + 简短占位摘要；正文留给后续 `block_insert_after --block-id <章节标题 block_id>` 分段追加。一次性塞超长 `--content` 既容易触发参数限制，调试也更难。
-- **视觉丰富度**：必须遵循 [`lark-doc-style.md`](style/lark-doc-style.md) 中的样式指南，主动使用结构化 block 丰富文档
+- **表达形式**：由用户目标和内容决定。需要结构化表达时可参考 [`lark-doc-style.md`](style/lark-doc-style.md)，但不要默认套用固定开头、固定富 block 比例或固定图表
 
 ## 参考
 

skills/lark-doc/references/lark-doc-update.md

@@ -3,10 +3,11 @@
 
 > **前置条件（MUST READ）：** 生成文档内容前，必须先用 Read 工具读取以下文件，缺一不可：
 > 1. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
-> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 排版指南（元素选择、丰富度规则、颜色语义）
-> 3. [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、并行执行策略）
+> 2. [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、并行执行策略）
 >
-> **未读完以上文件就生成内容会导致格式错误或样式不达标。**
+> **需要使用 callout、grid、table、whiteboard 等富 block，或用户明确要求美化/重排版时，再参考 [`lark-doc-style.md`](style/lark-doc-style.md)。该文件是表达组件参考，不是固定模板。**
+>
+> **未读完以上文件就生成内容会导致格式错误。**
 
 通过八种指令精确更新飞书云文档。支持字符串级别和 block 级别的操作。
 
@@ -242,7 +243,7 @@ lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \
   1. 用 `block_insert_after` 在目标位置插入新的富文本结构
   2. 用 `block_delete` 批量删除旧的 block
   3. 这样可以保留文档中其他不相关的内容（图片、评论等）
-- **视觉丰富度**：插入或替换内容时，同样遵循 [`lark-doc-style.md`](style/lark-doc-style.md) 中的样式指南，主动使用结构化 block
+- **表达形式**：插入或替换内容时，优先沿用用户要求和已有文档风格；需要结构化表达时可参考 [`lark-doc-style.md`](style/lark-doc-style.md)，但不要为了固定丰富度主动添加组件
 
 ## 参考
 

skills/lark-doc/references/style/lark-doc-create-workflow.md

@@ -8,49 +8,49 @@
 
 1. **Plan（规划）** — 根据用户目标和文档当前状态，评估下一步该做什么
 2. **Execute（执行）** — 运行相应的 `lark-cli docs` 命令，或 **spawn** Agent 子任务并行推进
-3. **Observe（观察）** — 检查命令输出，验证正确性，核查样式是否达标
+3. **Observe（观察）** — 检查命令输出，验证正确性，确认内容是否满足用户目标
 4. **Iterate（迭代）** — 如需调整，回到 Plan 继续循环
 
 循环在文档达到质量标准且满足用户需求时结束。不要试图一次性产出完美内容——迭代打磨效果更好。根据用户实际需求灵活决定文档结构和版块，而不是套用固定模板。
 
 
 ## 典型 Code-Act Loop 流程
 
-### 第一波 — 规划与骨架（串行）
+### 步骤一：规划与初始创建（串行）
 
 1. 分析用户需求：受众、目的、范围
-2. 设计大纲——每个 h1/h2 章节至少规划 1 个非文本 block；承载重要信息的章节优先规划画板
-3. `docs +create --api-version v2` **只建骨架**：标题 + 开头 `<callout>` + 各级标题 + 每节一句占位摘要
-   - ⚠️ **不要**一次性把完整章节内容塞进 `--content`。超长 `--content` 容易触发字符/参数限制。
-   - 完整内容留到第二波，由各 Agent 用 `block_insert_after --block-id <章节标题 block_id>` 分段写入。
+2. 设计大纲：根据任务自然选择结构。可以是短文、纪要、FAQ、方案、报告、清单或其他形式；不要默认套固定章节、固定开头或固定富 block 配比
+3. `docs +create --api-version v2` 创建文档。长文档可**只建骨架**：标题 + 各级标题 + 每节一句占位摘要；短文档可以一次写入完整内容
+   - ⚠️ 创建较长文档时，**不要**一次性把完整章节内容塞进 `--content`。超长 `--content` 容易触发字符/参数限制。
+   - 完整内容留到步骤二，由各 Agent 用 `block_insert_after --block-id <章节标题 block_id>` 分段写入。
    - ⚠️ **`@file` 路径限制**：`--content @file` 只接受当前工作目录下的相对路径，传绝对路径（如 `@/tmp/xxx.md`）会报 `unsafe file path`。需要落盘时，将文件写在 cwd 下，用完自行清理。
 
-### 第二波 — 内容撰写（并行 Agent）
+### 步骤二：分段撰写（并行 Agent）
 
 4. Spawn Agent 并行撰写各章节。每个 Agent 需收到：
-   - 文档 token、负责的章节范围、期望的 block 类型
-   - `lark-doc-xml.md` 和 `lark-doc-style.md` 的完整路径（Agent 须先读取）
+   - 文档 token、负责的章节范围、用户目标、目标读者和已有风格线索
+   - `lark-doc-xml.md` 的完整路径（Agent 须先读取）；仅在需要使用富 block 或用户要求美化时提供 `lark-doc-style.md`
    - 使用 `block_insert_after --block-id <章节标题 block_id>` 写入对应章节内容
 
-### 第三波 — 整合审查 + 画板意图识别（串行）
+### 步骤三：整合审查与画板识别（串行）
 
 5. `docs +fetch --api-version v2 --detail with-ids` 获取文档，审查整体效果
-6. 评估样式达标（富 block 密度、元素多样性、连续 `<p>` 数量）
+6. 评估内容是否满足用户目标：事实是否完整、结构是否清楚、语气是否匹配、是否保留必要素材
 7. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断是否有段落适合用图表达。重要信息优先画板化，记录需要插图的章节、推荐画板类型、mermaid/SVG 路径和用于画图的源内容
 
-### 第四波 — 画板与润色（并行 Agent）
+### 步骤四：画板处理与润色（并行 Agent）
 
-8. **优先处理第三波识别出的画板需求**：
+8. **优先处理步骤三识别出的画板需求**：
    参考 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md)中的方式，插入图表画板。
 9. Spawn 内容改写 Agent 定向润色：
-   - 文字密集章节转为 `<table>`/`<grid>`/`<callout>`
-   - 主要章节间补充 `<hr/>`
+   - 文字密集且不易读的章节可转为 `<table>`/`<grid>`/`<callout>`，也可以拆段、改列表或保留纯文本
+   - 需要明显分隔的主题可补充 `<hr/>`，不强制章节间都使用
    - 本地图片使用 `docs +media-insert` 插入
 
 
 ## Agent 子任务要求
 
-内容改写 Agent 必须收到：文档 token、章节范围（标题/block ID）、`lark-doc-xml.md` 和 `lark-doc-style.md` 路径、具体的 `docs +update` command 和 `--block-id`。
+内容改写 Agent 必须收到：文档 token、章节范围（标题/block ID）、`lark-doc-xml.md` 路径、用户目标/风格要求、具体的 `docs +update` command 和 `--block-id`。只有在需要使用富 block 或用户要求美化时，才提供 `lark-doc-style.md` 路径。
 
 Mermaid 图由主 Agent 直接插入 `<whiteboard type="mermaid">...</whiteboard>`，无需 SubAgent。
 

skills/lark-doc/references/style/lark-doc-style.md

@@ -1,23 +1,25 @@
-# 文档样式指南
+# 文档表达组件参考
 
-创建或编辑文档时，必须遵循本指南，使用结构化 block 提升可读性和视觉层次。
+本文件说明飞书文档可用的结构化表达方式，供模型在需要时选择。它不是固定模板，也不是强制排版规范。
+
+默认原则：优先理解用户目标、受众、素材形态和已有文档风格，由模型自主决定结构、语气和视觉呈现。只有当用户明确要求“美化、重排版、做成报告/方案/看起来更专业”等，或内容本身明显需要结构化承载时，才主动使用下列组件。
 
 ## 一、核心原则
 
-1. **结构优于文字**：能用结构化 block 表达的信息，不用纯文本段落
-2. **Front-load 结论**：文档以 `<callout>` 开头概括核心结论；每章节首段点明要旨
-3. **视觉节奏**：连续纯文本不超过 3 段；不同主题章节间用 `<hr/>` 分隔
-4. **风格一致**：同类信息使用同类元素，全篇风格统一
+1. **服务内容，而非套模板**：先判断信息最自然的表达方式，再选择段落、列表、表格、分栏、画板等元素
+2. **尊重用户风格**：用户给出样例、语气、结构或已有文档时，优先沿用；没有要求时不强行使用固定开头、固定章节或固定视觉组件
+3. **适度结构化**：结构化 block 用于降低理解成本，不为了“丰富”而堆叠
+4. **保持一致但不过度统一**：同类信息可使用相近表达，但允许因内容差异采用不同形式
 5. **重要信息画板化**：核心流程、架构、对比、风险、路线图、指标趋势等重要信息优先使用画板表达
 
 ## 二、元素选择指南
 
-涉及图表需求时，按类型选择插入方式：思维导图/时序图/类图/饼图/甘特图用 `<whiteboard type="mermaid">` 直接内嵌；其他新图表启动 SubAgent 插入 `<whiteboard type="svg">完整 SVG</whiteboard>`；只有编辑**已有**画板时才调用 **lark-whiteboard** skill。
+需要图表时，按类型选择插入方式：思维导图/时序图/类图/饼图/甘特图可用 `<whiteboard type="mermaid">` 直接内嵌；其他新图表可启动 SubAgent 插入 `<whiteboard type="svg">完整 SVG</whiteboard>`；只有编辑**已有**画板时才调用 **lark-whiteboard** skill。
 
 | 场景                                         | 推荐方案                                  |
 |--------------------------------------------|---------------------------------------|
-| 核心结论 / 摘要 / 注意事项                           | `<callout>` + emoji + 背景色             |
-| 重要方案对比 / 优劣势 / Before vs After             | `<grid>` 2 列分栏；SVG SubAgent           |
+| 需要突出的一小段结论 / 摘要 / 注意事项                    | `<callout>`；是否使用 emoji 和颜色由文档语气决定 |
+| 方案对比 / 优劣势 / Before vs After                | `<grid>` 2 列分栏、`<table>` 或画板，按复杂度选择 |
 | 简短低风险对比                                    | `<grid>` 2 列分栏                        |
 | 3+ 属性的结构化数据 / 指标表                          | `<table>` + 表头背景色                     |
 | 任务清单 / 检查项                                 | `<checkbox>`                          |
@@ -53,7 +55,7 @@
 
 ## 三、颜色语义
 
-全篇保持语义一致，同一语义必须使用同一颜色：
+如果使用颜色，建议保持语义一致；不需要颜色时可以保持朴素文本风格：
 
 | 语义 | emoji 前缀 | callout 背景色 | 文字色 |
 |-|-|-|-|
@@ -63,23 +65,22 @@
 | 注意、待确认 | ❗"注意：" | `light-yellow` | `yellow` |
 | 中性、辅助 | — | `light-gray` | — |
 
-- 表头统一 `background-color="light-gray"`
-- 关键指标用 `<span text-color="green/red">` 突出，**必须同时用 ↑↓ 或 +/- 标注方向**（色觉无障碍）
+- 表头可使用 `background-color="light-gray"`，也可以保持默认样式
+- 关键指标如使用 `<span text-color="green/red">` 突出，建议同时用 ↑↓ 或 +/- 标注方向（色觉无障碍）
 
 ## 四、排版规范
 
-- 标题层级 ≤ 4 层，段落单段 ≤ 5 行，列表嵌套 ≤ 2 层，Grid ≤ 3 列
-- 文档开头用 `<callout>` front-load 结论。
+- 标题层级、段落长度、列表嵌套和 Grid 列数应以可读性为准，避免过深层级和过宽分栏
+- 文档开头可以是结论、背景、摘要、问题陈述、目录或直接正文，不强制使用 `<callout>`
 
-## 五、丰富度自检
+## 五、质量自检
 
-生成内容后必须自检，**未达标时主动优化**：
+生成内容后可以从以下角度自检，但不要把这些项当作硬性比例或固定模板：
 
-| 指标 | 达标标准 |
+| 指标 | 自检问题 |
 |-|-|
-| 富 block 密度 | ≥ 40%（非纯文本 block 数 ÷ 总 block 数） |
-| 元素多样性 | ≥ 3 种不同 block 类型 |
-| 连续纯文本 | ≤ 3 段连续 `<p>` |
-| 章节丰富度 | 每 h1/h2 ≥ 1 个非纯文本 block |
-| 开头 callout | 必须 |
-| 视觉节奏 | 不同主题章节间有 `<hr/>` |
+| 信息表达 | 当前结构是否符合用户目标，而不是套用固定报告模板？ |
+| 阅读负担 | 是否有段落过长、层级过深、表格过宽或组件过多的问题？ |
+| 风格匹配 | 是否延续了用户给定样例或已有文档风格？ |
+| 组件必要性 | callout、grid、table、whiteboard 等是否真的提升理解？ |
+| 保真度 | 改写时是否保留了原文事实、引用、图片、附件和资源块？ |