From cb54bea00d3186e384ada1338ec90458b6400f65 Mon Sep 17 00:00:00 2001 From: fangshuyu-768 Date: Tue, 23 Jun 2026 18:27:36 +0800 Subject: [PATCH] docs(lark-doc): refine rich block, path, and block ID guidance (#1508) --- skills/lark-doc/SKILL.md | 10 ++++------ skills/lark-doc/references/lark-doc-create.md | 4 ++-- skills/lark-doc/references/lark-doc-update.md | 14 ++++++++++---- skills/lark-doc/references/lark-doc-whiteboard.md | 6 +++--- .../references/style/lark-doc-create-workflow.md | 2 +- skills/lark-doc/references/style/lark-doc-style.md | 10 +++++----- .../references/style/lark-doc-update-workflow.md | 2 +- 7 files changed, 26 insertions(+), 22 deletions(-) diff --git a/skills/lark-doc/SKILL.md b/skills/lark-doc/SKILL.md index 634c83462..88caa685b 100644 --- a/skills/lark-doc/SKILL.md +++ b/skills/lark-doc/SKILL.md @@ -26,7 +26,7 @@ lark-cli docs +update --api-version v2 --doc "文档URL或token" --command appen **CRITICAL — 执行对应操作前，MUST 先用 Read 工具读取以下文件，缺一不可：** 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` 选择、局部读取策略、`` / `` 输出结构） -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) +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.md`](references/lark-doc-update.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) 的元素能力说明。该文件不是固定模板或强制排版规范；除非用户明确要求美化、重排版或特定风格，不要为了“达标”主动套用固定结构。 **未读完以上文件就执行相应操作会导致参数选择错误或格式错误。** @@ -36,11 +36,9 @@ lark-cli docs +update --api-version v2 --doc "文档URL或token" --command appen > - **精准编辑场景**（`docs +update` 的 `str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `block_move_after` 等局部精修指令）：优先使用 XML（`--doc-format xml`，即默认值）。XML 能稳定表达 block 结构和样式，局部精修更可控；不要因为 Markdown 更简单就自行切换。 ## 快速决策 -- 用户需要“某个 block 的直达链接 / 锚点链接”时：返回 `文档基础 URL#block_id`。如果当前只有文档 URL 没有 block_id，先用 `docs +fetch --detail with-ids` 拿到目标 block 的 id -- 例： - - 已知文档 URL = `https://xxx.feishu.cn/docx/doxcn123` - - 已知 block_id = `blkcn456` - - 应返回 `https://xxx.feishu.cn/docx/doxcn123#blkcn456` +- 先判定任务路径：找文档 / 导入导出走 [`lark-drive`](../lark-drive/SKILL.md)；只读 / 摘要用 `docs +fetch` 默认 `simple`；明确旧文本 → 新文本直接 `str_replace`；只有 block 链接、评论锚点、插入 / 替换 / 删除 / 移动才局部 fetch `with-ids`；保真改写已有内容才读 `full` +- block 直达链接格式：`文档基础 URL#block_id`；没有 block_id 时局部 fetch `with-ids` +- 连续执行多个文档写操作时，必须按 [`lark-doc-update.md`](references/lark-doc-update.md) 的「Block ID 生命周期」判断旧 block ID 是否还能复用；`overwrite` / `block_replace` / `block_delete` 后不要复用受影响的旧 ID，插入 / 复制后要重新 fetch 才能拿到新 block ID - 用户需要在文档内**创建、复制或移动**资源块（画板、电子表格、多维表格等）时，必须先读取 [`lark-doc-xml.md`](references/lark-doc-xml.md) 的「三、资源块」章节 - 写文档时，由内容和用户意图决定表达形式；流程、架构、路线图、关键指标等信息可以使用画板，但不要默认把重要信息都画板化 - 新增画板必须隔离到 SubAgent：简单图由 SubAgent 直接插入 `完整 SVG`，不读 `lark-whiteboard`；复杂图才由主 Agent 先建 ``，再启动 SubAgent 读取 `lark-whiteboard` 写入 diff --git a/skills/lark-doc/references/lark-doc-create.md b/skills/lark-doc/references/lark-doc-create.md index 8dd86be32..f0f6e548a 100644 --- a/skills/lark-doc/references/lark-doc-create.md +++ b/skills/lark-doc/references/lark-doc-create.md @@ -4,7 +4,7 @@ > 1. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)） > 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)。该文件是表达组件参考，不是固定模板。** +> **需要富 block 或用户明确要求美化/重排版时，再参考 [`lark-doc-style.md`](style/lark-doc-style.md)。** > > **未读完以上文件就生成内容会导致格式错误。** @@ -74,7 +74,7 @@ lark-cli docs +create --api-version v2 --doc-format markdown --content $'# 项 ## 最佳实践 - 文档标题从内容中自动提取：XML 使用 ``；Markdown 使用文档开头唯一的一级标题（`# 标题`），正文从 `##` 开始。不要在内容开头重复写标题，也不要在 Markdown 正文中使用多个一级标题。 -- **创建较长的文档时只建骨架**：`--content` 仅传标题 + 各级 heading + 简短占位摘要；正文留给后续 `block_insert_after --block-id <章节标题 block_id>` 分段追加。一次性塞超长 `--content` 既容易触发参数限制，调试也更难。 +- **较长文档**：参考 [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) 先建骨架再分段写入；短文档可一次写完整内容。 - **表达形式**：由用户目标和内容决定。需要结构化表达时可参考 [`lark-doc-style.md`](style/lark-doc-style.md)，但不要默认套用固定开头、固定富 block 比例或固定图表 ## 参考 diff --git a/skills/lark-doc/references/lark-doc-update.md b/skills/lark-doc/references/lark-doc-update.md index 6c91db02c..537264de7 100644 --- a/skills/lark-doc/references/lark-doc-update.md +++ b/skills/lark-doc/references/lark-doc-update.md @@ -5,7 +5,7 @@ > 1. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)） > 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 或用户明确要求美化/重排版时，再参考 [`lark-doc-style.md`](style/lark-doc-style.md)。** > > **未读完以上文件就生成内容会导致格式错误。** @@ -44,6 +44,15 @@ | `append` | ⚠️ 在文档**末尾**追加内容（等价于 `block_insert_after --block-id -1`）。**不适用于逐章填充**——逐章写入请用 `block_insert_after` 并指定对应标题的 `--block-id` | `--content` | | `block_move_after` | 移动已有 block 到指定位置 | `--block-id` `--src-block-ids` | +## Block ID 生命周期 + +写操作后不要默认复用之前 fetch 到的 block ID： + +- `overwrite` / `block_replace` / `block_delete`：受影响旧 ID 失效，继续 block 级操作前重新 fetch +- `block_insert_after` / `append` / `block_copy_insert_after`：锚点 / 源 ID 通常保留，新内容是新 ID；要操作新内容先重新 fetch +- `block_move_after`：被移动 ID 通常保留，但位置、章节、range 语义变化；后续依赖位置时重新 fetch +- `str_replace`：简单行内替换通常不改变 ID；跨行 / 大段替换后如继续 block 级操作，先重新 fetch + ## 指令示例 ### str_replace — 全文文本替换 @@ -114,8 +123,6 @@ lark-cli docs +update --api-version v2 --doc "<doc_id>" --command block_replace --content '<p>替换后的段落内容</p>' ``` -> `block_replace` 由服务端执行整块替换，目标 block 的 ID 不保证在替换后继续可用。后续如果还要在替换后的块附近继续 `block_insert_after`、`range` 或其他 block 级操作，先重新 `docs +fetch --detail with-ids` 获取最新 block ID，不要复用旧 ID。 - ### block_delete — 删除指定 block ```bash @@ -237,7 +244,6 @@ lark-cli docs +update --api-version v2 --doc "<doc_id>" --command str_replace \ - **保护不可重建的内容**：图片、画板、电子表格等以 token 形式存储，替换时避开这些 block - **str_replace 的 replacement 支持富文本**：可以用行内标签 `<b>`、`<a>`、`<cite>`、`<latex>` 等替换普通文本为富文本 - **同一 block 只能被 replace 一次**：多次修改同一 block 请合并为一次 block_replace -- **block_replace 后重新获取 ID**：`block_replace` 成功后旧 block ID 不保证继续可用；继续做相邻块操作前，重新 `docs +fetch --detail with-ids` - **block_delete 支持批量**：用逗号分隔多个 block_id 一次删除 - **复杂结构重组**：将多个段落转换为 grid / table 等复杂布局时，分步操作比 overwrite 更安全： 1. 用 `block_insert_after` 在目标位置插入新的富文本结构 diff --git a/skills/lark-doc/references/lark-doc-whiteboard.md b/skills/lark-doc/references/lark-doc-whiteboard.md index a4d66409e..1048cd953 100644 --- a/skills/lark-doc/references/lark-doc-whiteboard.md +++ b/skills/lark-doc/references/lark-doc-whiteboard.md @@ -9,11 +9,11 @@ | `lark-doc` | 识别画板机会、使用 Mermaid/SVG 创建图表、调度 SubAgent、插入简单 SVG 画板或复杂空白画板 | 主 Agent 不直接创作画板内容； | | `lark-whiteboard` | 查询/导出已有画板；复杂图表生成（Mermaid/DSL/SVG 路由、场景选型、渲染验证）；写入已有/空白画板 | 仅特别复杂的图表或已有画板更新时由独立 SubAgent 读取 | -## 画板优先规则 +## 画板适用规则 -写文档时，重要信息优先画板化。遇到核心流程、系统架构、方案对比、风险链路、里程碑、指标趋势、因果归因、组织关系、能力分层等内容，不要只用段落或表格承载；除非内容只是一次性补充说明，否则应规划为画板。 +写文档时，核心流程、系统架构、方案对比、风险链路、里程碑、指标趋势、因果归因、组织关系、能力分层等内容，如果图示能明显降低理解成本，可以规划为画板；结构简单或文字更清楚的内容不必强行画板化。 -同一篇文档可以有多个画板。优先设计多个聚焦画板，而不是把所有信息塞进一张大图。 +同一篇文档可以有多个画板。确有多个独立图示点时，可拆成多个聚焦画板，而不是把所有信息塞进一张大图。 ## 文档与画板协同流程 diff --git a/skills/lark-doc/references/style/lark-doc-create-workflow.md b/skills/lark-doc/references/style/lark-doc-create-workflow.md index 1e22409d2..39a4d249d 100644 --- a/skills/lark-doc/references/style/lark-doc-create-workflow.md +++ b/skills/lark-doc/references/style/lark-doc-create-workflow.md @@ -43,7 +43,7 @@ 8. **优先处理步骤三识别出的画板需求**： 参考 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md)中的方式，插入图表画板。 9. Spawn 内容改写 Agent 定向润色： - - 文字密集且不易读的章节可转为 `<table>`/`<grid>`/`<callout>`，也可以拆段、改列表或保留纯文本 + - 文字密集且不易读时，优先拆段、改列表、增加小标题或调整顺序；只有确实存在行列数据、并列对比或强提醒信息时，才考虑 `<table>` / `<grid>` / `<callout>` - 需要明显分隔的主题可补充 `<hr/>`，不强制章节间都使用 - 本地图片使用 `docs +media-insert` 插入 diff --git a/skills/lark-doc/references/style/lark-doc-style.md b/skills/lark-doc/references/style/lark-doc-style.md index 1717ee88d..1a09a80f4 100644 --- a/skills/lark-doc/references/style/lark-doc-style.md +++ b/skills/lark-doc/references/style/lark-doc-style.md @@ -10,18 +10,18 @@ 2. **尊重用户风格**：用户给出样例、语气、结构或已有文档时，优先沿用；没有要求时不强行使用固定开头、固定章节或固定视觉组件 3. **适度结构化**：结构化 block 用于降低理解成本，不为了“丰富”而堆叠 4. **保持一致但不过度统一**：同类信息可使用相近表达，但允许因内容差异采用不同形式 -5. **重要信息画板化**：核心流程、架构、对比、风险、路线图、指标趋势等重要信息优先使用画板表达 +5. **图示服务理解**：流程、架构、对比、风险、路线图、指标趋势等内容在图示明显降低理解成本时，可使用画板表达 ## 二、元素选择指南 需要图表时，按类型选择插入方式：思维导图/时序图/类图/饼图/甘特图可用 `<whiteboard type="mermaid">` 直接内嵌；其他新图表可启动 SubAgent 插入 `<whiteboard type="svg">完整 SVG</whiteboard>`；只有编辑**已有**画板时才调用 **lark-whiteboard** skill。 -| 场景 | 推荐方案 | +| 场景 | 可选表达方式 | |--------------------------------------------|---------------------------------------| -| 需要突出的一小段结论 / 摘要 / 注意事项 | `<callout>`；是否使用 emoji 和颜色由文档语气决定 | -| 方案对比 / 优劣势 / Before vs After | `<grid>` 2 列分栏、`<table>` 或画板，按复杂度选择 | +| 少数需要视觉提醒的短句，如风险、限制、待确认事项或关键提醒 | 需要视觉提醒时可用 `<callout>`；普通结论、摘要或章节导语优先使用段落、列表、小标题或加粗 | +| 方案对比 / 优劣势 / Before vs After | 简短对比可用段落、列表或 `<grid>`；维度较多且需要逐项比较时再考虑 `<table>` 或画板 | | 简短低风险对比 | `<grid>` 2 列分栏 | -| 3+ 属性的结构化数据 / 指标表 | `<table>` + 表头背景色 | +| 需要按行列精确比较或查阅的数据，如指标、清单、字段说明、排期 | 可用 `<table>`；短要点、步骤、摘要或普通说明优先使用段落、列表或小标题 | | 任务清单 / 检查项 | `<checkbox>` | | 代码片段 | `<pre lang="x" caption="说明">` | | 引用 / 公式 | `<blockquote>` / `<latex>` | diff --git a/skills/lark-doc/references/style/lark-doc-update-workflow.md b/skills/lark-doc/references/style/lark-doc-update-workflow.md index ba6d3b83d..6ae8972ae 100644 --- a/skills/lark-doc/references/style/lark-doc-update-workflow.md +++ b/skills/lark-doc/references/style/lark-doc-update-workflow.md @@ -34,7 +34,7 @@ 参考 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md)中的方式，插入图表画板。 6. Spawn 内容改写 Agent 在不重叠的章节上并行改进，各 Agent 收到文档 token 和特定 block ID： - 沿用或轻微调整已有文档风格，除非用户要求彻底重排版 - - 可以通过重写段落、调整标题、拆分列表、补表格/分栏/callout 等方式提升可读性 + - 优先通过重写段落、调整标题、拆分列表或补充小标题提升可读性 - 富 block 是可选表达手段，不因固定比例而添加；画板类需求只走第 5 步 ### 步骤三：验证（串行）