| name | lark-doc |
| version | 1.0.0 |
| description | 飞书云文档：创建和编辑飞书文档。从 Markdown 创建文档、获取文档内容、更新文档（追加/覆盖/替换/插入/删除）、上传和下载文档中的图片和文件、搜索云空间文档。当用户需要创建或编辑飞书文档、读取文档内容、在文档中插入图片、搜索云空间文档时使用；如果用户是想按名称或关键词先定位电子表格、报表等云空间对象，也优先使用本 skill 的 docs +search 做资源发现。 |
| metadata | {"requires":{"bins":["lark-cli"]},"cliHelp":"lark-cli docs --help"} |
docs (v1)
CRITICAL — 开始前 MUST 先用 Read 工具读取 ../lark-shared/SKILL.md，其中包含认证、权限处理
核心概念
文档类型与 Token
飞书开放平台中，不同类型的文档有不同的 URL 格式和 Token 处理方式。在进行文档操作（如添加评论、下载文件等）时，必须先获取正确的 file_token。
文档 URL 格式与 Token 处理
| URL 格式 | 示例 | Token 类型 | 处理方式 |
|---|
/docx/ | https://example.larksuite.com/docx/doxcnxxxxxxxxx | file_token | URL 路径中的 token 直接作为 file_token 使用 |
/doc/ | https://example.larksuite.com/doc/doccnxxxxxxxxx | file_token | URL 路径中的 token 直接作为 file_token 使用 |
/wiki/ | https://example.larksuite.com/wiki/wikcnxxxxxxxxx | wiki_token | ⚠️ 不能直接使用，需要先查询获取真实的 obj_token |
/sheets/ | https://example.larksuite.com/sheets/shtcnxxxxxxxxx | file_token | URL 路径中的 token 直接作为 file_token 使用 |
/drive/folder/ | https://example.larksuite.com/drive/folder/fldcnxxxx | folder_token | URL 路径中的 token 作为文件夹 token 使用 |
Wiki 链接特殊处理（关键！）
知识库链接（/wiki/TOKEN）背后可能是云文档、电子表格、多维表格等不同类型的文档。不能直接假设 URL 中的 token 就是 file_token，必须先查询实际类型和真实 token。
处理流程
-
使用 wiki.spaces.get_node 查询节点信息
lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'
-
从返回结果中提取关键信息
node.obj_type：文档类型（docx/doc/sheet/bitable/slides/file/mindnote）node.obj_token：真实的文档 token（用于后续操作）node.title：文档标题
-
根据 obj_type 使用对应的 API
| obj_type | 说明 | 使用的 API |
|---|
docx | 新版云文档 | drive file.comments.*、docx.* |
doc | 旧版云文档 | drive file.comments.* |
sheet | 电子表格 | sheets.* |
bitable | 多维表格 | bitable.* |
slides | 幻灯片 | drive.* |
file | 文件 | drive.* |
mindnote | 思维导图 | drive.* |
查询示例
lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'
返回结果示例：
{
"node": {
"obj_type": "docx",
"obj_token": "xxxx",
"title": "标题",
"node_type": "origin",
"space_id": "12345678910"
}
}
资源关系
Wiki Space (知识空间)
└── Wiki Node (知识库节点)
├── obj_type: docx (新版文档)
│ └── obj_token (真实文档 token)
├── obj_type: doc (旧版文档)
│ └── obj_token (真实文档 token)
├── obj_type: sheet (电子表格)
│ └── obj_token (真实文档 token)
├── obj_type: bitable (多维表格)
│ └── obj_token (真实文档 token)
└── obj_type: file/slides/mindnote
└── obj_token (真实文档 token)
Drive Folder (云空间文件夹)
└── File (文件/文档)
└── file_token (直接使用)
绘图需求识别与挖掘
用户很少主动提"画板"——默认使用飞书画板承载图表，命中以下任一信号即触发：
- 用户提到图表类型：架构图、流程图、时序图、组织图、路线图、对比图、鱼骨图、飞轮图、思维导图等
- 用户表达可视化意图：画一下、梳理关系、画个流程、给我一个图、方便汇报等
- 文档主题涉及结构关系、流程走向、时间线、数据对比
以下场景不加图：用户明确拒绝、合同/法律条款/合规声明等严谨连续文本、原样转录任务。
[!CAUTION]
命中后，MUST 先读取 references/lark-doc-whiteboard.md 并严格按其流程执行。
绝对禁止用 whiteboard-cli 渲染 PNG 后通过 docs +media-insert 插入文档——图表必须通过 lark-cli whiteboard +update 写入画板 block，这是唯一合法路径。
快速决策
- 用户说“看一下文档里的图片/附件/素材”“预览素材”，优先用
lark-cli docs +media-preview。
- 用户明确说“下载素材”，再用
lark-cli docs +media-download。
- 如果目标明确是画板 / whiteboard / 画板缩略图，只能用
lark-cli docs +media-download --type whiteboard，不要用 +media-preview。
- 用户说“找一个表格”“按名称搜电子表格”“找报表”“最近打开的表格”，先用
lark-cli docs +search 做资源发现。
docs +search 不是只搜文档 / Wiki；结果里会直接返回 SHEET 等云空间对象。- 拿到 spreadsheet URL / token 后，再切到
lark-sheets 做对象内部读取、筛选、写入等操作。
- 用户说“给文档加评论”“查看评论”“回复评论”“给评论加表情 / reaction”“删除评论表情 / reaction”，不要留在
lark-doc，直接切到 lark-drive 处理。
常见格式错误（docs +create / +update 的 markdown 陷阱）
| 错误模式 | 现象 | 修复 |
|---|
| Callout 内嵌代码块（````` ``` ````） | 报错 "Callout does not support Code block type" | 把代码块移到 Callout 外面。Callout 只支持文本、列表、标题、待办、引用 |
| Callout 内嵌表格 | 静默丢弃或报错 | 表格移到 Callout 外部 |
| Markdown 表格中内容含格式化语法（加粗、代码等） | 解析失败 | 改用 <lark-table> 增强表格语法 |
--format json 用于 shortcut 命令 | 报 "unknown flag: --format" | shortcut（+create、+search 等）默认输出 json，删掉 --format json 参数 |
| 长 markdown 内容直接用 shell 变量传参 | shell 长度限制或转义问题 | 先写入 .md 文件，用 --markdown "$(cat file.md)" 传入。仍失败则分段创建（先 +create 骨架，再 +update --mode append 追加段落） |
补充说明
docs +search 除了搜索文档 / Wiki，也承担“先定位云空间对象，再切回对应业务 skill 操作”的资源发现入口角色；当用户口头说“表格 / 报表”时，也优先从这里开始。
Shortcuts（推荐优先使用）
Shortcut 是对常用操作的高级封装（lark-cli docs +<verb> [flags]）。有 Shortcut 的操作优先使用。
| Shortcut | 说明 |
|---|
+search | Search Lark docs, Wiki, and spreadsheet files (Search v2: doc_wiki/search) |
+create | Create a Lark document |
+fetch | Fetch Lark document content |
+update | Update a Lark document |
+media-insert | Insert a local image or file at the end of a Lark document (4-step orchestration + auto-rollback) |
+media-download | Download document media or whiteboard thumbnail (auto-detects extension) |
+whiteboard-update | Alias of whiteboard +update. Update an existing whiteboard with DSL, Mermaid or PlantUML. Prefer whiteboard +update; refer to lark-whiteboard skill for details. |
