| name | lark-doc |
| version | 2.0.0 |
| channels | ["lark"] |
| trigger | 飞书文档|lark文档|docx|wiki|云文档|飞书云|doubao.com|知识库|知识空间|飞书页面 |
| description | 飞书云文档（Docx / Wiki 文档）：读取和编辑飞书文档内容。当用户给出文档 URL 或 token，或需要查看、创建、编辑文档、插入或下载文档图片附件时使用。文档中嵌入的电子表格、多维表格、画板，先用本 skill 提取 token 再切到对应 skill。当用户给出 doubao.com 的 /docx/ 或 /wiki/ URL/token 时，也应直接使用本 skill；路由依据是 URL 路径模式和 token，而不是域名。不负责文档评论管理，也不负责表格或 Base 的数据操作。 |
| metadata | {"requires":{"bins":["lark-cli"]},"cliHelp":"lark-cli docs --help; lark-cli docs +create --help; lark-cli docs +fetch --help; lark-cli docs +update --help; lark-cli docs +resource-download --help; lark-cli docs +resource-update --help; lark-cli docs +resource-delete --help"} |
docs
身份：文档操作默认使用 --as user。首次使用前执行 lark-cli auth login。
lark-cli docs +fetch --doc "文档URL或token"
lark-cli docs +create --content '<title>标题</title><p>内容</p>'
lark-cli docs +update --doc "文档URL或token" --command append --content '<p>内容</p>'
⚠️ 导出整篇文档到 .md 文件：必须用脚本，不能直接 shell 调 lark-cli（Ethan 专属）
只读/摘要/局部 用 docs +fetch（配合 --scope 局部读取，见下方必读）即可。但当目标是把整篇文档原样导出为本地 .md 文件时：
不要通过 shell 工具直接跑 lark-cli docs +fetch ... > out.md——Ethan 的 shell 工具有 8000 字符输出截断，大文档会丢内容。
必须用脚本，它内部用 subprocess 调 lark-cli（绕开截断），stdout 只输出文件路径：
python ~/.ethan/skills/lark-doc/scripts/fetch_doc.py "https://xxx.feishu.cn/docx/TOKEN" ./output.md
python ~/.ethan/skills/lark-doc/scripts/fetch_doc.py "https://xxx.feishu.cn/wiki/TOKEN" ./output.md
脚本会：拉取完整文档（不受截断影响）→ 获取文档基本信息（作者、创建/修改时间、原文链接，插到标题下方；需 drive:drive.metadata:readonly 权限，缺失则跳过并提示）→ 有 CDN 凭证则把图片上传换成公开 URL（检测：test -n "$CDN_ENDPOINT" && test -n "$CDN_ACCESS_KEY" && echo CDN_READY || echo CDN_MISSING，无则保留飞书链接并提示用户配置 upload-cdn skill；图片走 docs +media-download 认证下载而非直连 URL）→ 下载视频/附件到 ./media/ → 清洗残留 DocxXML 标签（<title>/<callout>/<cite> 转等价 markdown，<readonly-block type="isv"> 等无法导出的第三方交互块换成占位说明，其余组件标签转义避免 ProseMirror 吞标签）→ 写出 .md，stdout 只打印路径。
前置条件 — 执行操作前必读
CRITICAL — 执行对应操作前，MUST 先用 Read 工具读取以下文件，缺一不可：
../lark-shared/SKILL.md — 认证、权限处理、全局参数（所有操作通用）- 读取文档（
docs +fetch） → 必读 lark-doc-fetch.md（--scope / --detail 选择、局部读取策略、<fragment> / <excerpt> 输出结构）
- 创建或编辑文档内容 → 必读
lark-doc-xml.md（XML 语法规则，仅当用户明确要求 Markdown 时改读 lark-doc-md.md）和 lark-doc-style.md（元素选择、丰富度规则、颜色语义）；从零创建时加读 lark-doc-create-workflow.md；编辑已有文档时加读 lark-doc-update.md 和 lark-doc-update-workflow.md
未读完以上文件就执行相应操作会导致参数选择错误或格式错误。
格式选择规则（全局）：
- 创建 / 导入场景（
docs +create，或 docs +update --command append/overwrite 的整段写入）：XML 和 Markdown 都可以。用户提供 .md 本地文件、或明确说"导入 Markdown"时，直接用 Markdown；否则默认 XML（可用 callout、grid、checkbox 等富 block）。
- 精准编辑场景（
docs +update 的 str_replace / block_insert_after / block_replace / block_delete / block_move_after 等局部精修指令）：优先使用 XML（--doc-format xml，即默认值）。XML 能稳定表达 block 结构和样式，局部精修更可控；不要因为 Markdown 更简单就自行切换。
快速决策
- 用户要复制文档 / 创建文档副本 / 另存为副本时，切到
lark-drive，按其中的复制指引使用 lark-cli drive files copy；不要用 docs +fetch + docs +create 重建正文，也不要走 drive +export / drive +import。
- 先判定任务路径：找文档 / 导入导出走
lark-drive；只读 / 摘要用 docs +fetch 默认 simple；明确旧文本 → 新文本直接 str_replace；只有 block 链接、评论锚点、插入 / 替换 / 删除 / 移动才局部 fetch with-ids；保真改写已有内容才读 full
- block 直达链接格式：
文档基础 URL#block_id；没有 block_id 时局部 fetch with-ids
- 连续执行多个文档写操作时，必须按
lark-doc-update.md 的「Block ID 生命周期」判断旧 block ID 是否还能复用；overwrite / block_replace / block_delete 后不要复用受影响的旧 ID，插入 / 复制后要重新 fetch 才能拿到新 block ID
- 用户需要在文档内创建、复制或移动资源块（画板、电子表格、多维表格等）时，必须先读取
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
- 用户明确说"下载/更新/删除文档封面图" → 用
lark-cli docs +resource-download/+resource-update/+resource-delete --type cover
resource-* 目前仅支持 Docx 封面资源；其他图片、附件或素材请走 +media-*- 如果目标是画板/whiteboard/画板缩略图 → 只能用
lark-cli docs +media-download --type whiteboard（不要用 +media-preview）
- 拿到 spreadsheet URL/token 后 → 切到
lark-sheets 做对象内部操作
- 用户说"给文档加评论""查看评论""回复评论""给评论加/删除表情 reaction" → 切到
lark-drive 处理
- 文档内容中出现嵌入的
<sheet>、<bitable> 或 <cite file-type="sheets|bitable"> 标签时 → 必须主动提取 token 并切到对应技能下钻读取内部数据，不能只呈现标签本身
| 标签 / 属性 | 提取字段 | 切到技能 |
|---|
<sheet token="..." sheet-id="..."> | token -> spreadsheet_token, sheet-id | lark-sheets |
<bitable token="..." table-id="..."> | token -> app_token, table-id | lark-base |
<cite type="doc" file-type="sheets" token="..." sheet-id="..."> | 同 <sheet> | lark-sheets |
<cite type="doc" file-type="bitable" token="..." table-id="..."> | 同 <bitable> | lark-base |
<vc-transcribe-tab vc-node-id="..."> | vc-node-id -> note_id | lark-note：先 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 读取 src-token 文档，定位 block |
Shortcuts（推荐优先使用）
Shortcut 是对常用操作的高级封装（lark-cli docs +<verb> [flags]）。有 Shortcut 的操作优先使用。
| Shortcut | 说明 |
|---|
+create | Create a Lark document (XML / Markdown) |
+fetch | Fetch Lark document content (XML / Markdown / im-markdown; im-markdown only after fetch for lark-im) |
+update | Update a Lark document (str_replace / block_insert_after / block_replace / ...) |
+media-insert | 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 | Download document media or whiteboard thumbnail (auto-detects extension) |
+media-preview | Preview document media file (auto-detects extension) |
+resource-download / +resource-update / +resource-delete | Download, update, or delete a Docx cover image resource with --type cover |
+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. |
不在本 Skill 范围
