feishu-cli-slides

Lark Slides プレゼンテーションスキル

feishu-cli slides で空白のプレゼンテーションを作成し、ローカル画像を slide_file メディアとしてそのプレゼンテーションにアップロードします。 返された file_token は、スライド XML 内で <img src="..."> として直接参照できます。

feishu-cli：まだインストールしていない場合は、riba2534/feishu-cli でインストール方法を確認してください。

対象範囲：このスキルが対象とするのは、「空白のプレゼンテーションの作成」と「メディアのアップロード」の2つの最小限の操作のみです。既存の プレゼンテーションで複雑なスライド編集（block の挿入／置換など）が必要な場合、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	スライド 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 内部）

CLI 内部では、slides create が --title/--width/--height を使って最小限の XML テンプレートを組み立て、POST します。

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

現在のバージョンでは、presentation XML 全体を直接渡す --xml-file パラメーターは公開されていません。変更できるのは、この最小テンプレートに対する --title/--width/--height のみです。 複雑な初期コンテンツが必要な場合は、まず create で xml_presentation_id を取得してから、lark-slides または今後拡張される CLI をご利用ください。

前提条件

• 認証：デフォルトでは App Token（テナント ID）を使用します。--user-access-token または FEISHU_USER_ACCESS_TOKEN を使うと User Token に切り替えられます（個人として作成でき、後から Feishu で直接編集しやすいため、User Token の使用を推奨します）
• 権限：

  コマンド	必要なスコープ
  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 を使用

デフォルト値は2つの層で設定：cobra flag の登録時、--title のデフォルト値は空文字列、--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

別のツールに切り替えるケース

ケース	使用するツール
既存のプレゼンテーションでスライドや block を挿入／変更／削除する	lark-slides（公式 CLI）または OpenAPI の slides_ai/v1/... 編集インターフェイスを直接呼び出す
presentation XML テンプレート全体を直接渡す	--xml-file はまだ公開されていないため、CLI の拡張を待つか、OpenAPI を直接呼び出す
20 MB を超える単一メディアファイル	小さな画像に分割するか、Feishu クライアントから直接アップロードする
markdown／docx を slides に変換する	現在はサポートされていません。まず docx に変換し、その後 Feishu クライアントからエクスポートすることをおすすめします
通常のドキュメント（プレゼンテーションではない）にメディアをアップロードする	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 と App Token：デフォルトは App Token（Bot ID）です。プレゼンテーションは Bot の所有となり、一般のユーザーは Feishu 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