docs: reorganize lark doc skill navigation

Author: fangshuyu-768

skills/lark-doc/SKILL.md

@@ -21,15 +21,15 @@ lark-cli docs +create --api-version v2 --content '<title>标题</title><p>内容
 lark-cli docs +update --api-version v2 --doc "文档URL或token" --command append --content '<p>内容</p>'
 ```
 
-## 前置条件 — 执行操作前必读
+## 操作入口 — 执行操作前必读
 
-**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` 选择、局部读取策略、`<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.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) 的元素能力说明。该文件不是固定模板或强制排版规范；除非用户明确要求美化、重排版或特定风格，不要为了“达标”主动套用固定结构。
+**CRITICAL — 先根据操作大类查 [`lark-doc-operation-guide.md`](references/lark-doc-operation-guide.md)，再读取该操作对应的必读 reference。**
 
-**未读完以上文件就执行相应操作会导致参数选择错误或格式错误。**
+操作 guide 把“操作大类 → 必读 reference → 条件加读 → 命令作用域”集中维护，避免只凭记忆选择参数或遗漏格式规则。
+
+**所有操作通用前置：** MUST 先读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，了解认证、权限处理、全局参数、安全规则和路径限制。
+
+**未读完 guide 中对应操作的必读文件就执行操作会导致参数选择错误或格式错误。**
 
 > **格式选择规则（全局）：**
 > - **创建 / 导入场景**（`docs +create`，或 `docs +update --command append/overwrite` 的整段写入）：XML 和 Markdown 都可以。用户提供 `.md` 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；否则默认 XML（可用 callout、grid、checkbox 等富 block）。
@@ -60,20 +60,9 @@ lark-cli docs +update --api-version v2 --doc "文档URL或token" --command appen
 | `<vc-transcribe-tab vc-node-id="...">` | `vc-node-id` -> note_id | [`lark-note`](../lark-note/SKILL.md)：先 `note +detail --note-id <vc-node-id>` |
 | `<synced_reference src-token="..." src-block-id="...">` | `src-token` -> doc_token, `src-block-id` -> block_id | 用 `docs +fetch --api-version v2` 读取 src-token 文档，定位 block |
 
-## Shortcuts（推荐优先使用）
-
-Shortcut 是对常用操作的高级封装（`lark-cli docs +<verb> [flags]`）。有 Shortcut 的操作优先使用。
+## 命令索引
 
-| Shortcut | 说明 |
-|----------|------|
-| [`+create`](references/lark-doc-create.md) | Create a Lark document (XML / Markdown) |
-| [`+fetch`](references/lark-doc-fetch.md) | Fetch Lark document content (XML / Markdown / im-markdown; `im-markdown` only after fetch for `lark-im`) |
-| [`+update`](references/lark-doc-update.md) | Update a Lark document (str_replace / block_insert_after / block_replace / ...) |
-| [`+media-insert`](references/lark-doc-media-insert.md) | Insert a local image or file at the end of a Lark document (4-step orchestration + auto-rollback). Prefer `--from-clipboard` when the image is already on the system clipboard (screenshots, copy from Feishu/browser); use `--file` only for on-disk sources. |
-| [`+media-download`](references/lark-doc-media-download.md) | Download document media or whiteboard thumbnail (auto-detects extension) |
-| [`+media-preview`](references/lark-doc-media-preview.md) | Preview document media file (auto-detects extension) |
-| [`+resource-download` / `+resource-update` / `+resource-delete`](references/lark-doc-resource-cover.md) | Download, update, or delete a Docx cover image resource with `--type cover` |
-| [`+whiteboard-update`](../lark-whiteboard/references/lark-whiteboard-update.md) | Alias of `whiteboard +update`. Update an existing whiteboard with DSL, Mermaid or PlantUML. Prefer `whiteboard +update`; refer to lark-whiteboard skill for details. |
+Shortcut 是对常用操作的高级封装（`lark-cli docs +<verb> [flags]`）。有 Shortcut 的操作优先使用。命令语义分组、作用域和操作前置关系统一维护在 [`lark-doc-operation-guide.md`](references/lark-doc-operation-guide.md)。
 
 ## 不在本 Skill 范围
 

skills/lark-doc/references/lark-doc-operation-guide.md

@@ -0,0 +1,82 @@
+# lark-doc 操作入口 Guide
+
+本文件维护执行前的入口判断：先用“操作大类前置”确定必读 reference，再用“命令作用域”确认应走正文、素材、资源还是画板桥接能力。具体参数、示例和工作流仍以各 reference 为准。
+
+所有操作都默认先读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)，了解认证、权限、安全规则、全局参数和路径限制。
+
+## 操作大类前置
+
+| 操作大类 | 触发场景 | 必读 reference | 条件加读 |
+|-|-|-|-|
+| 读取文档 | 浏览、总结、摘取正文、定位 block、获取直达链接、提取素材或嵌入对象 token | [`lark-doc-fetch.md`](lark-doc-fetch.md) | 需要 Markdown 输出或基于 Markdown 更新时读 [`lark-doc-md.md`](lark-doc-md.md) |
+| 创建文档 | 新建 Docx/Wiki 文档，含短文档、长文档骨架、Markdown 导入 | [`lark-doc-create.md`](lark-doc-create.md), [`lark-doc-xml.md`](lark-doc-xml.md) | 用户提供 `.md` 或明确要求 Markdown 时读 [`lark-doc-md.md`](lark-doc-md.md)；长文档读 [`style/lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md)；需要根据题材组织文档时读 [`style/topics/topic-router.md`](style/topics/topic-router.md)；需要富 block 或美化时读 [`style/lark-doc-style.md`](style/lark-doc-style.md) |
+| 编辑文档 | 替换、插入、删除、移动、复制、追加、覆盖、改写、润色、重排版 | [`lark-doc-update.md`](lark-doc-update.md), [`lark-doc-xml.md`](lark-doc-xml.md) | 用户明确要求 Markdown 或需 Markdown 跨行匹配时读 [`lark-doc-md.md`](lark-doc-md.md)；改写/润色读 [`style/lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md)；需要富 block 或美化时读 [`style/lark-doc-style.md`](style/lark-doc-style.md) |
+| 正文素材 | 插入、预览或下载正文图片/附件，下载画板缩略图 | 对应操作的 [`lark-doc-media-insert.md`](lark-doc-media-insert.md) / [`lark-doc-media-preview.md`](lark-doc-media-preview.md) / [`lark-doc-media-download.md`](lark-doc-media-download.md) | 需要从文档中提取素材 token 时先读 [`lark-doc-fetch.md`](lark-doc-fetch.md) |
+| 文档级资源 | 下载、更新或删除 Docx 封面图 | [`lark-doc-resource-cover.md`](lark-doc-resource-cover.md) | 无；封面不是正文 `<img>`，不要走 `+media-*` |
+| 画板协作 | 新增 Mermaid/SVG 画板，或更新已有画板 | [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) | 插入新的 `<whiteboard>` block 时读 [`lark-doc-xml.md`](lark-doc-xml.md)；更新已有复杂画板时读 [`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md)；需要美化/结构化表达时读 [`style/lark-doc-style.md`](style/lark-doc-style.md) |
+| 嵌入对象下钻 | 正文中出现 `<sheet>`、`<bitable>`、`<cite file-type=...>`、`<vc-transcribe-tab>`、`<synced_reference>` 等 | [`lark-doc-fetch.md`](lark-doc-fetch.md) | 按对象类型切到 [`../../lark-sheets/SKILL.md`](../../lark-sheets/SKILL.md)、[`../../lark-base/SKILL.md`](../../lark-base/SKILL.md)、[`../../lark-note/SKILL.md`](../../lark-note/SKILL.md) 或继续用 `docs +fetch` 读取源文档 |
+| 非本 skill | 评论、评论回复、reaction、权限、云空间文件管理、导入导出 | 对应目标 skill | 评论/云空间管理走 [`../../lark-drive/SKILL.md`](../../lark-drive/SKILL.md)；表格/Base 内部数据走 sheets/base |
+
+## 命令作用域
+
+不要用命令名是否带 `+` 判断语义；正文内容、正文素材、文档级资源和画板桥接是不同作用域。Shortcut 是高级封装，有 Shortcut 的操作优先使用。
+
+| 命令 | 类别 | 作用域 | 说明 |
+|-|-|-|-|
+| `docs +create` | workflow | document content | 创建 Docx/Wiki 文档，默认 XML |
+| `docs +fetch` | workflow | document content | 读取正文结构、block id、媒体/资源 token、嵌入对象引用 |
+| `docs +update` | workflow | document content | 修改正文 block 或全文 |
+| `docs +media-insert` | media | body block | 在正文中插入图片或附件 |
+| `docs +media-preview` | media | body asset | 预览正文图片或附件素材 |
+| `docs +media-download` | media | body asset / whiteboard thumbnail | 下载正文图片、附件或画板缩略图 |
+| `docs +resource-download --type cover` | resource/meta | document cover | 下载 Docx 封面图资源 |
+| `docs +resource-update --type cover` | resource/meta | document cover | 更新 Docx 封面图资源 |
+| `docs +resource-delete --type cover` | resource/meta | document cover | 删除 Docx 封面图资源 |
+| `docs +whiteboard-update` | bridge | whiteboard | `whiteboard +update` 的 docs alias；已有画板更新优先按 lark-whiteboard 流程执行 |
+
+## 作用域边界
+
+### document content
+
+正文内容树。包括标题、段落、列表、表格、callout、grid、正文中的 `<img>` / `<source>` / `<whiteboard>` / `<sheet>` 等 block 或行内节点。
+
+- 读取：`docs +fetch`
+- 创建：`docs +create`
+- 修改：`docs +update`
+- 格式：XML 默认，Markdown 仅在用户明确要求或导入 `.md` 时使用
+
+### body media
+
+正文里的图片、附件、画板缩略图等素材。正文素材来自正文 block 或资源 token，不等同于文档封面。
+
+- 插入图片/附件：`docs +media-insert`
+- 预览图片/附件：`docs +media-preview`
+- 下载图片/附件/画板缩略图：`docs +media-download`
+
+### document resource/meta
+
+文档级资源或元信息，不属于正文 block。当前 docs resource shortcut 重点覆盖 Docx 封面图。
+
+- 封面图下载：`docs +resource-download --type cover`
+- 封面图更新：`docs +resource-update --type cover`
+- 封面图删除：`docs +resource-delete --type cover`
+
+封面图不是正文里的 `<img>`，不要用 `+media-insert` 或 `+media-download --token <cover.token>` 手动拼步骤。
+
+### bridge
+
+跨 skill 协作入口。`docs +whiteboard-update` 是已有画板更新的 alias；复杂画板查询、导出、渲染验证和写入以 [`lark-whiteboard`](../../lark-whiteboard/SKILL.md) 的流程为准。
+
+## 格式选择
+
+- **创建 / 导入场景**：XML 和 Markdown 都可以。用户提供 `.md` 本地文件、或明确说“导入 Markdown”时直接用 Markdown；否则默认 XML。
+- **精准编辑场景**：`str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `block_move_after` 等局部精修优先 XML。
+- **Markdown 限制**：Markdown 不携带 block ID，也无样式。需要按 block ID 定位时，先用 `docs +fetch --detail with-ids` 局部获取目标段落。
+- **富 block**：callout、grid、table、whiteboard 等结构化表达由内容和用户意图决定；不要为了“丰富”强行套用固定结构。
+
+## 校验要点
+
+- 写操作后，如继续 block 级操作，按 [`lark-doc-update.md`](lark-doc-update.md) 的“Block ID 生命周期”判断是否需要重新 fetch。
+- `overwrite` / `block_replace` / `block_delete` 后不要复用受影响旧 ID。
+- 插入 / 复制新块后，要操作新块必须重新 fetch 获取新 block ID。
+- 正文素材走 `+media-*`；文档封面走 `+resource-* --type cover`。

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

@@ -19,30 +19,31 @@
 ### 步骤一：规划与初始创建（串行）
 
 1. 分析用户需求：受众、目的、范围
-2. 设计大纲：根据任务自然选择结构。可以是短文、纪要、FAQ、方案、报告、清单或其他形式；不要默认套固定章节、固定开头或固定富 block 配比
-3. `docs +create --api-version v2` 创建文档。长文档可**只建骨架**：标题 + 各级标题 + 每节一句占位摘要；短文档可以一次写入完整内容
+2. 如需从零组织文档且用户未指定固定模板，先读 [`topics/topic-router.md`](topics/topic-router.md) 判断题材；命中题材后加读对应题材指引，再设计大纲
+3. 设计大纲：根据任务自然选择结构。可以是短文、纪要、FAQ、方案、报告、清单或其他形式；不要默认套固定章节、固定开头或固定富 block 配比
+4. `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）
 
-4. Spawn Agent 并行撰写各章节。每个 Agent 需收到：
+5. Spawn Agent 并行撰写各章节。每个 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. 评估内容是否满足用户目标：事实是否完整、结构是否清楚、语气是否匹配、是否保留必要素材
-7. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断是否有段落适合用图表达。重要信息优先画板化，记录需要插图的章节、推荐画板类型、mermaid/SVG 路径和用于画图的源内容
+6. `docs +fetch --api-version v2 --detail with-ids` 获取文档，审查整体效果
+7. 评估内容是否满足用户目标：事实是否完整、结构是否清楚、语气是否匹配、是否保留必要素材
+8. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断是否有段落适合用图表达。重要信息优先画板化，记录需要插图的章节、推荐画板类型、mermaid/SVG 路径和用于画图的源内容
 
 ### 步骤四：画板处理与润色（并行 Agent）
 
-8. **优先处理步骤三识别出的画板需求**：
+9. **优先处理步骤三识别出的画板需求**：
    参考 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md)中的方式，插入图表画板。
-9. Spawn 内容改写 Agent 定向润色：
+10. Spawn 内容改写 Agent 定向润色：
    - 文字密集且不易读时，优先拆段、改列表、增加小标题或调整顺序；只有确实存在行列数据、并列对比或强提醒信息时，才考虑 `<table>` / `<grid>` / `<callout>`
    - 需要明显分隔的主题可补充 `<hr/>`，不强制章节间都使用
    - 本地图片使用 `docs +media-insert` 插入

skills/lark-doc/references/style/topics/meeting-notes.md

@@ -0,0 +1,20 @@
+# 会议纪要文档指引
+
+## 适用场景
+
+会议纪要、同步会记录、讨论结论、评审记录等需要沉淀共识和行动项的文档。
+
+## 结构建议
+
+- 会议信息：主题、时间、参会人
+- 背景或议题
+- 讨论要点
+- 已达成结论
+- 待办事项与负责人
+- 未决问题
+
+## 表达建议
+
+- 先写结论和行动项，再保留必要讨论过程。
+- 待办事项尽量写清负责人、截止时间和验收标准。
+- 已知 open_id 的人员使用 `<cite type="user" user-id="..."></cite>`。

skills/lark-doc/references/style/topics/project-plan.md

@@ -0,0 +1,20 @@
+# 项目计划文档指引
+
+## 适用场景
+
+项目计划、推进方案、排期、里程碑、跨团队协作方案等需要说明目标、范围、路径和风险的文档。
+
+## 结构建议
+
+- 背景与目标
+- 范围与不做事项
+- 里程碑与时间安排
+- 工作拆解与责任分工
+- 风险、依赖与应对
+- 下一步动作
+
+## 表达建议
+
+- 时间线、依赖关系和关键路径适合用表格或画板。
+- 不要虚构日期、负责人或指标；缺失信息标为待确认。
+- 风险和依赖要写出影响与应对，不只列名称。

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

@@ -0,0 +1,19 @@
+# 汇报总结文档指引
+
+## 适用场景
+
+周报、月报、阶段总结、复盘、述职、项目汇报等需要向读者说明进展、结果、问题和下一步的文档。
+
+## 结构建议
+
+- 结论或总体状态
+- 关键进展与成果
+- 数据、事实或案例支撑
+- 问题、风险与原因
+- 下一步计划
+
+## 表达建议
+
+- 面向管理层时先给结论，再展开细节。
+- 有指标变化时说明口径，不要只堆数字。
+- 风险、阻塞和待决策事项可以用列表或 callout，但不要过度使用。

skills/lark-doc/references/style/topics/topic-router.md

@@ -0,0 +1,16 @@
+# 文档题材路由
+
+创建文档前，如果用户没有给定固定模板，先根据用户意图识别题材，再加读对应题材指引。题材指引用于帮助选择结构、语气和信息组织方式，不是强制模板。
+
+| 用户意图 / 信号 | 题材 | 加读指引 |
+|-|-|-|
+| 周报、月报、复盘、总结、汇报、述职 | 汇报总结 | [`report.md`](report.md) |
+| 会议纪要、会议总结、讨论记录、同步会 | 会议纪要 | [`meeting-notes.md`](meeting-notes.md) |
+| 项目计划、排期、里程碑、推进方案 | 项目计划 | [`project-plan.md`](project-plan.md) |
+
+## 规则
+
+- 用户明确指定题材、结构或模板时，优先用户指定。
+- 命中多个题材时，只选择主目标对应的 1 个题材，不组合多个指引。
+- 题材指引只提供结构和表达建议，不覆盖用户给出的事实、格式和语气要求。
+- 没有明显题材时，不强行套题材，按通用创建工作流执行。