riba2534/feishu-cli-slides

飞书 Slides 演示文稿技能

通过 feishu-cli slides 创建空白演示文稿，并把本地图片以 slide_file 媒体形式上传到该演示文稿， 返回的 file_token 可直接在 slide XML 中作为 <img src="..."> 引用。

feishu-cli：如尚未安装，请前往 riba2534/feishu-cli 获取安装方式。

范围声明：本技能只覆盖「创建空白演示文稿」+「上传媒体」两个最小可用动作。如需在已有 演示文稿里做复杂 slide 编辑（block insert/replace 等），目前 CLI 未实现，请改走 官方 lark-slides 客户端或 OpenAPI 直调。

核心概念

两种产物分别是什么

| 命令 | 调用的 API | 产物 | 用途 | |------|------------|------|------| | slides create | POST /open-apis/slides_ai/v1/xml_presentations | xml_presentation_id | 后续所有 slides 操作的 ID（不是普通 docx token） | | slides media-upload | POST /open-apis/drive/v1/medias/upload_all (parent_type=slide_file) | file_token | 可直接放进 slide XML 的 <img src="..."> |

关键约束：

• slide_file 是 slides 后端唯一接受的 parent_type（lark-cli 实测：slide_image / slides_image / slides_file 都会被拒）
• parent_node 必须传 xml_presentation_id（而不是 docx token 或 file_token）
• 上传走单分片 upload_all，不支持 upload_prepare 多分片，所以单文件硬限 20 MB

XML 模板格式（create 内部）

slides create 在 CLI 内部用 --title/--width/--height 拼成最小可用 XML 模板再 POST：

<presentation xmlns="http://www.larkoffice.com/sml/2.0" width="960" height="540">
  <title>演示文稿标题</title>
</presentation>

当前版本不暴露 --xml-file 参数让你直接传整个 presentation XML——只能通过 --title/--width/--height 影响这个最小模板。如需复杂初始内容，先 create 拿到 xml_presentation_id，再走 lark-slides 或后续 CLI 扩展。

前置条件

• 认证：默认走 App Token（租户身份），通过 --user-access-token 或 FEISHU_USER_ACCESS_TOKEN 可切换 User Token（推荐用 User Token，以个人身份创建，便于后续直接在飞书里编辑）
• 权限： | 命令 | 所需 scope | |------|-----------| | slides create | slides:presentation:create 或 slides:presentation:write_only | | slides media-upload | docs:document.media:upload |
• 预检：feishu-cli auth check --scope "slides:presentation:create docs:document.media:upload"

命令速查

1. slides create — 创建空白演示文稿

# 最简用法（默认尺寸 960x540，title="Untitled"）
feishu-cli slides create

# 指定标题
feishu-cli slides create --title "Q2 OKR"

# 自定义宽高（像素）
feishu-cli slides create --title "Wide Deck" --width 1920 --height 1080

# JSON 输出（脚本接力时常用，方便 jq 取 xml_presentation_id）
feishu-cli slides create --title "Demo" --output json

# 以用户身份创建（推荐，演示文稿归属个人）
feishu-cli slides create --title "Demo" --user-access-token <u-xxx>

关键参数：

| 参数 | 说明 | 默认值 | |------|------|--------| | --title, -t | 演示文稿标题 | Untitled | | --width | 幻灯片宽度（像素） | 960 | | --height | 幻灯片高度（像素） | 540 | | --output, -o | 输出格式（留空 = 文本摘要，json = JSON） | 文本摘要 | | --user-access-token | 显式传 User Token | 不传走 App Token |

两层默认值分工：--title 在 cobra flag 注册时默认为空字符串、--width/--height 注册为 0 （见 cmd/slides_create.go:78-80）；运行时由 client 层（internal/client/slides.go:49-58） 把空 title 注入为 Untitled、把非正数尺寸注入为标准 16:9 的 960x540。所以「未传」≠「传 0」≠「报错」， 三者最终都会走到同一个默认值。

返回：

Slides 演示文稿已创建：
  xml_presentation_id: <id>
  title:               Q2 OKR
  revision_id:         1

xml_presentation_id 就是后续 media-upload --presentation-token 要传的值。

2. slides media-upload — 上传媒体到演示文稿

# 上传封面图
feishu-cli slides media-upload \
  --file ./cover.png \
  --presentation-token <xml_presentation_id>

# JSON 输出，方便 jq 接力拿 file_token
feishu-cli slides media-upload \
  --file ./cover.png \
  --presentation-token <xml_presentation_id> \
  --output json

关键参数：

| 参数 | 说明 | 必填 | |------|------|------| | --file | 本地图片路径（≤ 20 MB） | 是 | | --presentation-token | 目标演示文稿的 xml_presentation_id | 是 | | --output, -o | 输出格式（留空 = 文本摘要，json = JSON） | 否 | | --user-access-token | 显式传 User Token | 否 |

返回：

图片上传成功：
  file_token:      <token>
  file_name:       cover.png
  size:            123456 bytes
  presentation_id: <xml_presentation_id>

提示: 在 slide XML 中可用作 <img src="<token>"/>

典型工作流

工作流 A：创建 + 上传封面图（端到端）

# 1. 创建空白演示文稿
PRES_ID=$(feishu-cli slides create --title "Q2 OKR" --output json | jq -r '.xml_presentation_id')

# 2. 上传封面图，拿到 file_token
FILE_TOKEN=$(feishu-cli slides media-upload \
  --file ./cover.png \
  --presentation-token "$PRES_ID" \
  --output json | jq -r '.file_token')

# 3. 现在 $FILE_TOKEN 可以拼到 slide XML 的 <img src="..."> 里
echo "presentation: $PRES_ID, cover: $FILE_TOKEN"

工作流 B：批量上传一组图片

PRES_ID=$(feishu-cli slides create --title "Photo Deck" --output json | jq -r '.xml_presentation_id')

for img in ./assets/*.png; do
  feishu-cli slides media-upload \
    --file "$img" \
    --presentation-token "$PRES_ID" \
    --output json | jq -r '"\(.file_name) -> \(.file_token)"'
done

何时转用其他工具

| 场景 | 改走 | |------|------| | 在已有演示文稿里插入/修改/删除 slide 或 block | lark-slides（官方 CLI）或 OpenAPI 直调 slides_ai/v1/... 编辑接口 | | 直接传整个 presentation XML 模板 | 暂未暴露 --xml-file，等 CLI 扩展或 OpenAPI 直调 | | 单文件 > 20 MB 的媒体 | 拆分小图，或直接走飞书客户端上传 | | 把 markdown / docx 转成 slides | 暂不支持，建议先转 docx 再用飞书客户端导出 | | 普通文档（不是演示文稿）上传媒体 | 走 feishu-cli-drive 技能（drive upload） |

注意事项

• parent_type 不要乱改：源码里硬编码 slide_file，且经 lark-cli 实测唯一可用值。 自己改成 slide_image / slides_image / slides_file 都会被服务端拒绝
• 20 MB 上限不可绕过：upload_prepare 多分片接口不接受 parent_type=slide_file， CLI 在 client 侧也做了 20 MB 硬检查，超过会在本地直接报错（不会发请求）
• xml_presentation_id ≠ docx token：这是 slides 模块独立的标识符，不要拿去当 docx:document_id 或 drive:file_token 用
• User Token vs App Token：默认 App Token（Bot 身份），演示文稿归 Bot 所有，普通人在 飞书 UI 里看不到。推荐传 --user-access-token 让产物归个人，能直接在「我的空间」找到
• 图片格式：常见 png/jpg/jpeg/gif/webp 等，由 medias/upload_all 自动推断 MIME

错误排查

| 错误 | 原因 | 解决 | |------|------|------| | --file 不能为空 / --presentation-token 不能为空 | 必填参数缺失 | 检查命令行参数 | | 读取文件失败 / --file 必须是普通文件 | 路径错或不是 regular file | 检查路径、不要传符号链接到目录 | | 文件 X 大小 Y 字节超过 slides 上传限制（20 MB） | 文件超过 20 MB | 压缩 / 切分，slides 后端硬限不可绕过 | | 创建 slides 失败: code=99991663, msg=... | scope 不够 | auth check --scope "slides:presentation:create" 然后重新 auth login --domain slides --recommend | | 创建 slides 失败: HTTP 400, body: ...invalid xml_presentation... | XML 模板异常（一般 title 含未转义字符触发） | CLI 已做 XML escape，若仍出现请 issue | | 上传报 parent_type invalid 或类似 | 走的不是 slide_file（如直接 curl 调 medias/upload_all 时传错） | 用 CLI 而不是手敲 curl，CLI 已锁定 slide_file |

参考

• API 文档：飞书开放平台「智能演示」/「云文档 - 素材」
• 代码：cmd/slides_create.go / cmd/slides_media_upload.go / internal/client/slides.go
• 上游 PR：feishu-cli#135