Skip to content

Commit 9a0e86e

Browse files
fangshuyu-768fangshuyu-768
committed
docs: reorganize lark doc skill navigation
1 parent 1c92ed8 commit 9a0e86e

3 files changed

Lines changed: 122 additions & 18 deletions

File tree

‎skills/lark-doc/SKILL.md‎

Lines changed: 15 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,21 @@ lark-cli docs +create --api-version v2 --content '<title>标题</title><p>内容
2121
lark-cli docs +update --api-version v2 --doc "文档URL或token" --command append --content '<p>内容</p>'
2222
```
2323

24-
## 前置条件 — 执行操作前必读
24+
## 操作入口 — 执行操作前必读
2525

26-
**CRITICAL — 执行对应操作前，MUST 先用 Read 工具读取以下文件，缺一不可：**
26+
**CRITICAL — 先根据用户意图查 [`lark-doc-operation-matrix.md`](references/lark-doc-operation-matrix.md)，再读取该操作对应的必读 reference。**
27+
28+
矩阵把“用户意图 → 首选命令 → 必读文件 → 注意事项”集中维护，避免只凭记忆选择参数或遗漏格式规则。
29+
30+
**所有操作通用前置：** MUST 先读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，了解认证、权限处理、全局参数、安全规则和路径限制。
31+
32+
常用必读文件：
2733
1. [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) — 认证、权限处理、全局参数（所有操作通用）
28-
2. **读取文档（`docs +fetch --api-version v2`）** → 必读 [`lark-doc-fetch.md`](references/lark-doc-fetch.md)（`--scope` / `--detail` 选择、局部读取策略、`<fragment>` / `<excerpt>` 输出结构）
29-
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)
30-
4. **需要使用 callout、grid、table、whiteboard 等富 block 时** → 参考 [`lark-doc-style.md`](references/style/lark-doc-style.md) 的元素能力说明。该文件不是固定模板或强制排版规范；除非用户明确要求美化、重排版或特定风格，不要为了“达标”主动套用固定结构。
34+
2. [`lark-doc-command-index.md`](references/lark-doc-command-index.md) — docs 命令按语义分组的索引（正文、正文素材、文档级资源、搜索、画板桥接）
35+
3. [`lark-doc-operation-matrix.md`](references/lark-doc-operation-matrix.md) — 每类用户意图的首选命令、必读 reference 和注意事项
36+
4. **读取文档（`docs +fetch --api-version v2`）** → 必读 [`lark-doc-fetch.md`](references/lark-doc-fetch.md)（`--scope` / `--detail` 选择、局部读取策略、`<fragment>` / `<excerpt>` 输出结构）
37+
5. **创建或编辑文档内容** → 必读 [`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)
38+
6. **需要使用 callout、grid、table、whiteboard 等富 block 时** → 参考 [`lark-doc-style.md`](references/style/lark-doc-style.md) 的元素能力说明。该文件不是固定模板或强制排版规范；除非用户明确要求美化、重排版或特定风格，不要为了“达标”主动套用固定结构。
3139

3240
**未读完以上文件就执行相应操作会导致参数选择错误或格式错误。**
3341

@@ -60,20 +68,9 @@ lark-cli docs +update --api-version v2 --doc "文档URL或token" --command appen
6068
| `<vc-transcribe-tab vc-node-id="...">` | `vc-node-id` -> note_id | [`lark-note`](../lark-note/SKILL.md)：先 `note +detail --note-id <vc-node-id>` |
6169
| `<synced_reference src-token="..." src-block-id="...">` | `src-token` -> doc_token, `src-block-id` -> block_id | 用 `docs +fetch --api-version v2` 读取 src-token 文档，定位 block |
6270

63-
## Shortcuts（推荐优先使用）
64-
65-
Shortcut 是对常用操作的高级封装（`lark-cli docs +<verb> [flags]`）。有 Shortcut 的操作优先使用。
71+
## 命令索引
6672

67-
| Shortcut | 说明 |
68-
|----------|------|
69-
| [`+create`](references/lark-doc-create.md) | Create a Lark document (XML / Markdown) |
70-
| [`+fetch`](references/lark-doc-fetch.md) | Fetch Lark document content (XML / Markdown / im-markdown; `im-markdown` only after fetch for `lark-im`) |
71-
| [`+update`](references/lark-doc-update.md) | Update a Lark document (str_replace / block_insert_after / block_replace / ...) |
72-
| [`+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. |
73-
| [`+media-download`](references/lark-doc-media-download.md) | Download document media or whiteboard thumbnail (auto-detects extension) |
74-
| [`+media-preview`](references/lark-doc-media-preview.md) | Preview document media file (auto-detects extension) |
75-
| [`+resource-download` / `+resource-update` / `+resource-delete`](references/lark-doc-resource-cover.md) | Download, update, or delete a Docx cover image resource with `--type cover` |
76-
| [`+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. |
73+
Shortcut 是对常用操作的高级封装（`lark-cli docs +<verb> [flags]`）。有 Shortcut 的操作优先使用。命令语义分组、作用域和对应 reference 统一维护在 [`lark-doc-command-index.md`](references/lark-doc-command-index.md)；用户意图到首选命令和必读文件的映射统一维护在 [`lark-doc-operation-matrix.md`](references/lark-doc-operation-matrix.md)。
7774

7875
## 不在本 Skill 范围
7976

‎skills/lark-doc/references/lark-doc-command-index.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# lark-doc 命令语义索引
2+
3+
本文件按“命令作用域”组织 `lark-cli docs` 能力。不要用命令名是否带 `+` 判断语义；即使所有高层命令都以 shortcut 形式出现，正文内容、正文素材、文档级资源、搜索索引和画板桥接仍然是不同作用域。
4+
5+
执行具体操作前，继续查看 [`lark-doc-operation-matrix.md`](lark-doc-operation-matrix.md) 选择首选命令、必读 reference 和关键注意事项。
6+
7+
## 命令分组
8+
9+
| 命令 | 类别 | 作用域 | 说明 |
10+
|-|-|-|-|
11+
| `docs +create` | workflow | document content | 创建 Docx/Wiki 文档，默认 XML |
12+
| `docs +fetch` | workflow | document content | 读取正文结构、block id、媒体/资源 token、嵌入对象引用 |
13+
| `docs +update` | workflow | document content | 修改正文 block 或全文 |
14+
| `docs +media-insert` | media | body block | 在正文中插入图片或附件 |
15+
| `docs +media-preview` | media | body asset | 预览正文图片或附件素材 |
16+
| `docs +media-download` | media | body asset / whiteboard thumbnail | 下载正文图片、附件或画板缩略图 |
17+
| `docs +resource-download --type cover` | resource/meta | document cover | 下载 Docx 封面图资源 |
18+
| `docs +resource-update --type cover` | resource/meta | document cover | 更新 Docx 封面图资源 |
19+
| `docs +resource-delete --type cover` | resource/meta | document cover | 删除 Docx 封面图资源 |
20+
| `docs +whiteboard-update` | bridge | whiteboard | `whiteboard +update` 的 docs alias；已有画板更新优先按 lark-whiteboard 流程执行 |
21+
22+
## 作用域边界
23+
24+
### document content
25+
26+
正文内容树。包括标题、段落、列表、表格、callout、grid、正文中的 `<img>` / `<source>` / `<whiteboard>` / `<sheet>` 等 block 或行内节点。
27+
28+
- 读取：`docs +fetch`
29+
- 创建：`docs +create`
30+
- 修改：`docs +update`
31+
- 格式：XML 默认，Markdown 仅在用户明确要求或导入 `.md` 时使用
32+
33+
### body media
34+
35+
正文里的图片、附件、画板缩略图等素材。正文素材来自正文 block 或资源 token，不等同于文档封面。
36+
37+
- 插入图片/附件：`docs +media-insert`
38+
- 预览图片/附件：`docs +media-preview`
39+
- 下载图片/附件/画板缩略图：`docs +media-download`
40+
41+
### document resource/meta
42+
43+
文档级资源或元信息，不属于正文 block。当前 docs resource shortcut 重点覆盖 Docx 封面图。
44+
45+
- 封面图下载：`docs +resource-download --type cover`
46+
- 封面图更新：`docs +resource-update --type cover`
47+
- 封面图删除：`docs +resource-delete --type cover`
48+
49+
封面图不是正文里的 `<img>`，不要用 `+media-insert` 或 `+media-download --token <cover.token>` 手动拼步骤。
50+
51+
### bridge
52+
53+
跨 skill 协作入口。`docs +whiteboard-update` 是已有画板更新的 alias；复杂画板查询、导出、渲染验证和写入以 [`lark-whiteboard`](../../lark-whiteboard/SKILL.md) 的流程为准。
54+
55+
## 参考
56+
57+
- [`lark-doc-operation-matrix.md`](lark-doc-operation-matrix.md) — 用户意图到命令和必读文件的矩阵

‎skills/lark-doc/references/lark-doc-operation-matrix.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# lark-doc 操作矩阵
2+
3+
先用本矩阵把用户意图映射到命令、必读 reference 和关键注意事项，再执行命令。所有操作都默认先读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、权限、安全规则、全局参数和路径限制。
4+
5+
## 用户意图到操作路径
6+
7+
| 用户意图 | 首选命令 | 必读 reference | 可选 reference | 注意事项 |
8+
|-|-|-|-|-|
9+
| 浏览、总结或摘取文档内容 | `docs +fetch --api-version v2` | [`lark-doc-fetch.md`](lark-doc-fetch.md) | [`lark-doc-md.md`](lark-doc-md.md) | 只读/摘要默认 `--detail simple`；大文档优先用 `--scope outline/section/range/keyword` 局部读取 |
10+
| 获取 block 直达链接或定位锚点 | `docs +fetch --api-version v2 --detail with-ids` | [`lark-doc-fetch.md`](lark-doc-fetch.md) | | 拼接格式为 `文档基础 URL#block_id`；没有 block id 时先局部 fetch |
11+
| 创建短文档 | `docs +create --api-version v2` | [`lark-doc-create.md`](lark-doc-create.md), [`lark-doc-xml.md`](lark-doc-xml.md) 或 [`lark-doc-md.md`](lark-doc-md.md) | [`style/lark-doc-style.md`](style/lark-doc-style.md) | 默认 XML；用户提供 `.md` 或明确要求 Markdown 时用 Markdown |
12+
| 创建较长文档 | `docs +create --api-version v2` 建骨架，再 `docs +update --command block_insert_after` 分段 | [`lark-doc-create.md`](lark-doc-create.md), [`lark-doc-update.md`](lark-doc-update.md), [`style/lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md), [`lark-doc-xml.md`](lark-doc-xml.md) | [`style/lark-doc-style.md`](style/lark-doc-style.md), [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) | 先建标题骨架，再按章节 block id 分段写入；避免把超长正文一次塞进 `--content` |
13+
| 简单旧文本到新文本替换 | `docs +update --api-version v2 --command str_replace` | [`lark-doc-update.md`](lark-doc-update.md), [`lark-doc-xml.md`](lark-doc-xml.md) 或 [`lark-doc-md.md`](lark-doc-md.md) | | XML 模式只支持行内匹配；跨段/跨 block 使用 block 级操作或 Markdown 模式 |
14+
| 精准 block 级插入、替换、删除、移动或复制 | `docs +fetch` 定位 block id，再 `docs +update --command block_*` | [`lark-doc-fetch.md`](lark-doc-fetch.md), [`lark-doc-update.md`](lark-doc-update.md), [`lark-doc-xml.md`](lark-doc-xml.md) | [`style/lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) | 优先局部 fetch；连续写操作必须遵守 block id 生命周期，受影响 ID 不要复用 |
15+
| 改写、润色、补充或重排已有文档 | `docs +fetch` 局部读取，再 `docs +update` 精准修改 | [`lark-doc-fetch.md`](lark-doc-fetch.md), [`lark-doc-update.md`](lark-doc-update.md), [`style/lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md), [`lark-doc-xml.md`](lark-doc-xml.md) | [`style/lark-doc-style.md`](style/lark-doc-style.md), [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) | 精准手术优于全文覆盖；保留原文中的 @人、@文档、图片、附件、画板、sheet、bitable、synced_reference 等 token 和属性 |
16+
| 用户明确要求全文重建 | `docs +update --api-version v2 --command overwrite` | [`lark-doc-update.md`](lark-doc-update.md), [`lark-doc-xml.md`](lark-doc-xml.md) 或 [`lark-doc-md.md`](lark-doc-md.md) | [`style/lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) | `overwrite` 会清空文档后重写，可能丢失图片、评论等；只在用户明确要改整篇时使用 |
17+
| 追加整段内容到文档末尾 | `docs +update --api-version v2 --command append` | [`lark-doc-update.md`](lark-doc-update.md), [`lark-doc-xml.md`](lark-doc-xml.md) 或 [`lark-doc-md.md`](lark-doc-md.md) | | `append` 等价于末尾插入，不适合逐章填充；逐章写入用 `block_insert_after` |
18+
| 插入正文图片或附件 | `docs +media-insert` | [`lark-doc-media-insert.md`](lark-doc-media-insert.md) | [`lark-doc-fetch.md`](lark-doc-fetch.md) | 用户指定剪切板就用 `--from-clipboard`，指定路径就用 `--file`；不要把正文素材命令用于封面 |
19+
| 预览正文图片或附件素材 | `docs +media-preview` | [`lark-doc-media-preview.md`](lark-doc-media-preview.md) | [`lark-doc-fetch.md`](lark-doc-fetch.md) | 只想查看/预览时优先 preview；目标是画板缩略图时不要用 preview |
20+
| 下载正文图片、附件或画板缩略图 | `docs +media-download` | [`lark-doc-media-download.md`](lark-doc-media-download.md) | [`lark-doc-fetch.md`](lark-doc-fetch.md) | 明确“下载素材”或目标是 `<whiteboard>` 时使用；画板缩略图加 `--type whiteboard` |
21+
| 下载、更新或删除文档封面图 | `docs +resource-download/+resource-update/+resource-delete --type cover` | [`lark-doc-resource-cover.md`](lark-doc-resource-cover.md) | | 封面是文档级 resource/meta，不是正文 `<img>`；不要走 `+media-*` |
22+
| 新增 Mermaid 画板 | `docs +update` 写入 `<whiteboard type="mermaid">...</whiteboard>` | [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md), [`lark-doc-xml.md`](lark-doc-xml.md) | [`style/lark-doc-style.md`](style/lark-doc-style.md) | Mermaid 图由主 Agent 直接插入，无需读取 `lark-whiteboard` |
23+
| 新增 SVG 画板 | `docs +update` 写入 `<whiteboard type="svg">完整 SVG</whiteboard>` | [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md), [`lark-doc-xml.md`](lark-doc-xml.md) | [`style/lark-doc-style.md`](style/lark-doc-style.md) | SVG 插入隔离到 SubAgent；SVG 必须自包含，不引用外部资源 |
24+
| 更新已有画板 | `docs +fetch` 获取 `<whiteboard token="...">`，再 `docs +whiteboard-update` 或 `whiteboard +update` | [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md), [`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md) | | `docs +update` 不能直接编辑已有画板内容；复杂更新按 lark-whiteboard 流程写入 |
25+
| 文档中出现嵌入 sheet / bitable / cite doc | `docs +fetch` 提取 token 后切 skill | [`lark-doc-fetch.md`](lark-doc-fetch.md) | [`../lark-sheets/SKILL.md`](../../lark-sheets/SKILL.md), [`../lark-base/SKILL.md`](../../lark-base/SKILL.md) | 必须主动提取 token 并下钻读取内部数据，不能只呈现标签本身 |
26+
| 文档中出现 `vc-transcribe-tab` | `docs +fetch` 提取 `vc-node-id` 后切 `lark-note` | [`lark-doc-fetch.md`](lark-doc-fetch.md) | [`../lark-note/SKILL.md`](../../lark-note/SKILL.md) | `vc-node-id` 即 note_id，先 `note +detail --note-id <vc-node-id>` |
27+
| 文档评论、评论回复或 reaction | 切到 `lark-drive` | [`../../lark-drive/SKILL.md`](../../lark-drive/SKILL.md) | | 不属于本 skill 的正文编辑能力 |
28+
29+
## 格式选择
30+
31+
- **创建 / 导入场景**：XML 和 Markdown 都可以。用户提供 `.md` 本地文件、或明确说“导入 Markdown”时直接用 Markdown；否则默认 XML。
32+
- **精准编辑场景**：`str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `block_move_after` 等局部精修优先 XML。
33+
- **Markdown 限制**：Markdown 不携带 block ID，也无样式。需要按 block ID 定位时，先用 `docs +fetch --detail with-ids` 局部获取目标段落。
34+
- **富 block**：callout、grid、table、whiteboard 等结构化表达由内容和用户意图决定；不要为了“丰富”强行套用固定结构。
35+
36+
## 校验要点
37+
38+
- 写操作后，如继续 block 级操作，按 [`lark-doc-update.md`](lark-doc-update.md) 的“Block ID 生命周期”判断是否需要重新 fetch。
39+
- `overwrite` / `block_replace` / `block_delete` 后不要复用受影响旧 ID。
40+
- 插入 / 复制新块后，要操作新块必须重新 fetch 获取新 block ID。
41+
- 正文素材走 `+media-*`；文档封面走 `+resource-* --type cover`。
42+
43+
## 参考
44+
45+
- [`lark-doc-command-index.md`](lark-doc-command-index.md) — docs 命令语义索引
46+
- [`lark-doc-fetch.md`](lark-doc-fetch.md) — 读取正文
47+
- [`lark-doc-create.md`](lark-doc-create.md) — 创建文档
48+
- [`lark-doc-update.md`](lark-doc-update.md) — 更新正文
49+
- [`lark-doc-resource-cover.md`](lark-doc-resource-cover.md) — 封面资源
50+
- [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) — 文档与画板协作

0 commit comments

Comments
 (0)