飛書ドキュメント書き込み

Docx API を介して飛書クラウドドキュメントにコンテンツを書き込みます。飛書ドキュメントはブロックツリーモデルを使用しており、生の Markdown は受け入れません。

ベース URL: https://open.feishu.cn/open-apis/docx/v1

認証とトークン取得

feishu_skills のルートディレクトリから共有スクリプトを実行します。

TOKEN="$(./scripts/get_feishu_token.sh)"

リクエストヘッダーはすべて Authorization: Bearer ${TOKEN} を使用します。

ビジネスインターフェースがトークン無効、期限切れ、または 401 を返した場合、強制的に更新した後、元のリクエストを一度だけ再試行します。

TOKEN="$(./scripts/get_feishu_token.sh --force-refresh)"

環境変数:

• FEISHU_APP_ID
• FEISHU_APP_SECRET

ローカルキャッシュ: ./.feishu_token_cache.json（期限切れでなければ直接再利用、デフォルトでは 5 分前に更新）

推奨方法：変換 API

飛書は公式の Markdown → Blocks 変換エンドポイントを提供しています。

POST /documents/{document_id}/convert

{
  "content": "# 标题\n\n正文\n\n- 列表项",
  "content_type": "markdown"
}

✅ 手動で Block JSON を構築する必要がなく、標準 Markdown をサポートしています。 ⚠️ 飛書固有のブロック（Callout など）はサポートしていません — 手動で作成する必要があります。

ブロックタイプ

ブロックの作成

POST /documents/{document_id}/blocks/{block_id}/children?document_revision_id=-1

{
  "children": [...],
  "index": 0
}

• block_id: 親ブロックの ID（ルートノードには document_id を使用）
• index: 挿入位置（0=先頭、-1=末尾）

ブロックの削除

親ブロックの下にある指定範囲の子ブロックを削除します。

DELETE /documents/{document_id}/blocks/{block_id}/children/batch_delete?document_revision_id=-1

{
  "start_index": 3,
  "end_index": 4
}

• block_id: 操作対象の親ブロック ID
• start_index: 開始子ブロックのインデックス（含む）
• end_index: 終了子ブロックのインデックス（含まない）
• ⚠️ このインターフェースは DELETE であり、POST ではありません。

ブロックの例

テキスト:

{"block_type": 2, "text": {"elements": [{"text_run": {"content": "段落"}}]}}

見出し:

{"block_type": 3, "heading1": {"elements": [{"text_run": {"content": "标题"}}]}}

コードブロック:

{
  "block_type": 14,
  "code": {
    "style": {"language": 1},
    "elements": [{"text_run": {"content": "console.log('hello')"}}]
  }
}

Mermaid 描画ブロック（プラグインブロック）:

{
  "block_type": 40,
  "add_ons": {
    "component_type_id": "blk_631fefbbae02400430b8f9f4",
    "record": "{\"data\":\"flowchart TD\\nA-->B\",\"theme\":\"default\",\"view\":\"codeChart\"}"
  }
}

• block_type = 40 はプラグインブロックを表します。
• component_type_id = blk_631fefbbae02400430b8f9f4 は Mermaid 描画に使用できます。
• record は文字列化された JSON で、現在検証済みのフィールドは次のとおりです。
  • data: Mermaid ソースコード
  • theme: 通常は default を使用します。
  • view: 通常は codeChart を使用します。
• ドキュメントにすでに手動で「本文描画」形式の Mermaid が挿入されている場合、そのブロックを優先的に読み込み、その component_type_id/theme/view を再利用します。

ハイライトブロック（Callout）:

{
  "block_type": 19,
  "callout": {
    "background_color": 1,
    "border_color": 1,
    "emoji_id": "bulb"
  },
  "children": [
    {"block_type": 2, "text": {"elements": [{"text_run": {"content": "提示内容"}}]}}
  ]
}

画像（2ステップ）:

1. プレースホルダーの作成：{"block_type": 27, "image": {}}
2. アップロード：PUT /documents/{document_id}/blocks/{block_id}/image

テキストスタイル

{
  "text_run": {
    "content": "样式文本",
    "text_element_style": {
      "bold": true,
      "italic": true,
      "strikethrough": true,
      "underline": true,
      "inline_code": true,
      "background_color": 1,
      "text_color": 1
    }
  }
}

並行処理

飛書ドキュメントは複数人での共同作業をサポートしており、並行処理に対応する必要があります。

1. 最新のリビジョンを取得: GET /documents/{document_id}
2. リビジョン付きで書き込み: ?document_revision_id={revision}
3. 競合時に再試行（HTTP 409）

Mermaid 推奨フロー

ユーザーが「本文描画形式で Mermaid を統一する」と要求した場合、通常のテキストブロックやコードブロック内の ```mermaid を直接書き込まないでください。

推奨される順序：

1. まず、ターゲットドキュメントのすべてのブロックを読み込み、手動で調整された Mermaid 描画ブロックがすでに存在するかどうかを確認します。
2. 存在する場合、そのブロックの以下を読み込みます。
   • block_type
   • add_ons.component_type_id
   • add_ons.record
3. 同じ描画ブロック構造を再利用して新しい図を作成し、code ブロックを書き続けないでください。
4. 新しい図の作成が成功した後、古い Mermaid コードブロックを削除し、ドキュメント内に2つのコンテンツセットが同時に残るのを避けます。

適用シナリオ：

• ユーザーが特定の Mermaid 図を手動で理想的なスタイルに変更し、「他の図もこの形式に変更してほしい」と要求した場合。
• 複数のフローチャートを同じ Docx 内で一貫した視覚効果に保つ必要がある場合。

実践的なアドバイス

1. 通常の構造にはテキストブロック/見出しブロックを優先的に使用します。
2. コード表示には block_type = 14 を使用します。
3. フローチャート表示には Mermaid プラグインブロックを優先的に使用し、```mermaid を最終的な表示形式としないでください。
4. 古い図を置き換える際は、まず新しいブロックを挿入し、次に古いブロックを削除して、コンテンツの損失を避けます。
5. 一括置換に関わる場合、まず親ブロックの children の順序を読み込み、次に index に従って正確に削除します。

ベストプラクティス

1. 変換 API を優先的に使用します（開発を簡素化します）。
2. ブロックを一括作成します（API 呼び出しを減らします）。
3. 並行処理の競合を処理します（revision パラメータを使用します）。
4. 画像を2ステップで処理します（プレースホルダー + アップロード）。
5. Mermaid 図は既存のプラグインブロック形式を優先的に再利用します。