Skill v1.0.4
Automated scan100/100~1 modified, -2 removed
version: "1.0.4" name: feishu-cli-write description: >- 向飞书文档写入内容、创建新文档、新建空白文档。支持 doc import 从 Markdown 创建、 doc content-update 精准追加/覆盖/替换/插入/删除,doc add/update/delete 低层块操作, 以及图片/文件插入。当用户请求创建文档、写文档、更新文档、替换章节、插入章节、 删除章节、追加内容、覆盖文档、插入图片或文件时使用。 argument-hint: <title|document_id> [content] user-invocable: true allowed-tools: Bash(feishu-cli doc:), Bash(feishu-cli perm:), Bash(feishu-cli msg:), Bash(python3:), Write, Read
飞书文档写入
本技能负责创建和编辑飞书 docx。Markdown 文件导入创建文档也可直接用 feishu-cli-import;只读/导出走 feishu-cli-read / feishu-cli-export。
新建文档
feishu-cli doc create --title "文档标题" --output json
创建后如需交付给用户,先解析 owner:
- 优先读取
FEISHU_OWNER_EMAIL,其次读取~/.feishu-cli/config.yaml的owner_email。 - 解析到 owner 后授予
full_access:
``bash feishu-cli perm add <document_id> --doc-type docx --member-type email --member-id <owner_email> --perm full_access --notification ``
- 仅当
FEISHU_TRANSFER_OWNERSHIP=true或配置transfer_ownership: true时转移所有权:
``bash feishu-cli perm transfer-owner <document_id> --doc-type docx --member-type email --member-id <owner_email> --notification ``
- 未配置 owner 时,不要使用占位邮箱,提示用户设置
FEISHU_OWNER_EMAIL。
用 Markdown 创建文档
feishu-cli doc import /tmp/doc.md --title "标题" --upload-images
写入临时 Markdown 后先做编码检查:
python3 -c "d=open('/tmp/doc.md','rb').read(); assert b'\xef\xbf\xbd' not in d; d.decode('utf-8')"
doc import 已在 CLI 内校验非法 UTF-8 和 U+FFFD,但生成阶段仍建议先检查,避免把乱码写入云文档。
编辑已有文档
不要把 doc import --document-id 当成更新命令;它会把 Markdown 转成新块追加到文档末尾。已有文档编辑优先用 doc content-update。
| 用户意图 | 推荐模式 | |
|---|---|---|
| 在末尾新增内容 | append | |
| 完全重写文档 | overwrite | |
| 替换某个章节 | replace_range | |
| 全文查找替换 | replace_all | |
| 在某个章节前/后插入 | insert_before / insert_after | |
| 删除某个章节 | delete_range |
常用示例:
# 按标题替换章节feishu-cli doc content-update <document_id> --mode replace_range \--selection-by-title "## 旧章节" \--markdown-file /tmp/new-section.md# 在章节后插入feishu-cli doc content-update <document_id> --mode insert_after \--selection-by-title "## 目标章节" \--markdown "## 新增章节\n\n内容"# 追加到末尾feishu-cli doc content-update <document_id> --mode append \--markdown-file /tmp/append.md# 完全覆盖feishu-cli doc content-update <document_id> --mode overwrite \--markdown-file /tmp/full.md
关键规则:用户说“修改/替换/更新某段”时用 replace_range 或 replace_all,不要 append 导致重复。
Markdown 图片
doc import 默认上传图片;doc add / content-update 使用 --upload-images 上传 Markdown 中的本地/网络图片并回填 Image Block。
feishu-cli doc content-update <document_id> --mode append \--markdown-file /tmp/with-image.md \--upload-images
单独插入图片或文件用 doc media-insert:
feishu-cli doc media-insert <document_id> --file /path/to/image.png --type image --align center --caption "说明"feishu-cli doc media-insert <document_id> --file /path/to/report.pdf --type file
低层块操作
# doc add:默认 --content-type json;--source-type file/content;可指定父块和插入位置feishu-cli doc add <document_id> content.md --content-type markdown --upload-imagesfeishu-cli doc add <document_id> --content '[{"block_type":2,...}]' --source-type contentfeishu-cli doc add <document_id> doc.md --content-type markdown --block-id <parent_block_id> --index 0feishu-cli doc update <document_id> <block_id> --content-file update.json# doc delete:必须指定父块 ID + 索引范围(左闭右开),或用 --all 删全部子块;--force 跳过确认feishu-cli doc delete <document_id> <parent_block_id> --start 0 --end 3feishu-cli doc delete <document_id> <parent_block_id> --all --force# doc batch-update:默认 --source-type file;可传 --client-token(UUIDv4 幂等)和# --document-revision-id(乐观锁,默认 -1=最新;指定具体版本时如版本不匹配会失败)feishu-cli doc batch-update <document_id> updates.json --source-type filefeishu-cli doc batch-update <document_id> updates.json \--client-token "$(uuidgen)" \--document-revision-id -1
低层 JSON 需要熟悉飞书 Block 结构;普通章节编辑优先用 content-update。
doc add-board 添加画板块
向文档插入一个空画板块(block_type=43),返回 block_id 和 whiteboard_id,后续可用 feishu-cli board 系列命令操作画板内容。
| flag | 说明 | 默认 | |
|---|---|---|---|
--parent-id | 父块 ID | 空(文档根节点) | |
--index | 插入位置索引 | -1(末尾) | |
--output, -o | 输出格式 (json) | 文本 |
# 末尾添加,JSON 输出便于脚本提取 whiteboard_idfeishu-cli doc add-board <document_id> -o json# 指定父块和位置feishu-cli doc add-board <document_id> --parent-id <block_id> --index 0
doc add-callout 添加高亮块
向文档插入一个 Callout 高亮块(block_type=19),并自动写入文本内容(API 会自动生成空子块,CLI 已处理为直接更新而非额外创建)。
--callout-type | 背景色 | 视觉含义 | |
|---|---|---|---|
info(默认) | 蓝色(6) | 信息提示,灯泡图标 | |
warning | 黄色(4) | 警告提示 | |
error | 红色(2) | 错误提示 | |
success | 绿色(5) | 成功提示 |
注:CLI 当前仅暴露 4 种 type;如需 CAUTION(橙=3)/IMPORTANT(紫=7)等其他 6 色 Callout,请用 Markdown<callout type="CAUTION">...</callout>走doc import/content-update。
| flag | 说明 | 默认 | |
|---|---|---|---|
--callout-type | 类型 (info/warning/error/success) | info | |
--icon | 自定义图标(emoji shortcode,如 bulb fire) | 空 | |
--parent-id | 父块 ID | 空(文档根节点) | |
--index | 插入位置索引 | -1(末尾) | |
--output, -o | 输出格式 (json) | 文本 |
# 默认 info 蓝色feishu-cli doc add-callout <document_id> "这是一条提示信息"# 警告 + 自定义图标feishu-cli doc add-callout <document_id> "请注意" --callout-type warning --icon fire
表格
Markdown 表格导入 docx 时:
- 行数 > 9:CLI 创建 9 行初始表,再用
insert_table_row追加到同一 block。 - 列数 > 9:按列组拆分,保留首列作为标识。
- 行数极多(200+)时更适合用 Sheet:
feishu-cli sheet import-md report.md --title "报表"。
文档内已有表格结构操作:
feishu-cli doc table insert-row DOC_ID TABLE_BLOCK_ID --index 1 --count 2feishu-cli doc table delete-rows DOC_ID TABLE_BLOCK_ID --start 1 --end 3feishu-cli doc table merge-cells DOC_ID TABLE_BLOCK_ID --row-start 0 --row-end 2 --col-start 0 --col-end 3# 取消合并:指定合并区域内任一单元格的行/列索引feishu-cli doc table unmerge-cells DOC_ID TABLE_BLOCK_ID --row 0 --col 0
扩展语法
doc import / content-update 支持常见 Markdown,以及导出端生成的 HTML 扩展标签:
<mention-user id="ou_xxx"/><mention-doc token="doc_token_xxx" type="docx">标题</mention-doc><callout type="NOTE">内容</callout><grid cols="2"><column>左</column><column>右</column></grid>
Mermaid / PlantUML 会在导入时转为飞书画板;语法限制参考 ../feishu-cli-import/references/doc-guide.md。
验证
- 创建/更新后确认返回 document_id 或成功状态。
- 需要交付时确认 owner 权限已添加。
- 图片/表格/图表较多时查看命令输出中的成功统计。
- 重大覆盖操作前先确认用户明确要求
overwrite。