feishu-doc-writer

Lark ドキュメントへの書き込み

Docx API を使用して、Lark クラウドドキュメントにコンテンツを書き込みます。Lark ドキュメントは Block ツリーモデルを使用しており、Markdown をそのまま受け付けません。

Base URL: https://open.feishu.cn/open-apis/docx/v1

認証と Token の取得

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

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

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

ビジネス API が無効な Token、期限切れ、または 401 を返した場合は、強制的に更新してから元のリクエストを 1 回だけ再試行します。

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

環境変数:

• FEISHU_APP_ID
• FEISHU_APP_SECRET

ローカルキャッシュ: ./.feishu_token_cache.json（有効期限内であればそのまま再利用し、デフォルトでは 5 分前に更新します）

---

推奨方法：変換 API

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

POST /documents/{document_id}/convert

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

✅ Block JSON を手動で構築する必要がなく、標準 Markdown に対応しています
⚠️ Lark 固有のブロック（Callout など）には対応していないため、手動で作成する必要があります

---

Block の種類

block_type	名称	JSON Key	説明
1	ページ	page	ドキュメントのルートノード
2	テキスト	text	段落
3-11	見出し1-9	heading1-heading9	-
12	箇条書き	bullet	各項目が個別の block になります
13	番号付きリスト	ordered	-
14	コードブロック	code	style.language の指定が必要です
15	引用	quote	-
17	ToDo	todo	style.done を指定します
19	ハイライトブロック	callout	Lark 固有のコンテナブロック
22	区切り線	divider	-
27	画像	image	2 ステップ：プレースホルダーを作成してアップロード
31	表	table	-

---

Blocks の作成

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

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

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

Blocks の削除

親 Block の下にある指定範囲の子 Block を削除します。

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

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

• block_id: 操作対象の親 Block の ID
• start_index: 開始する子 Block のインデックス（含む）
• end_index: 終了する子 Block のインデックス（含まない）
• ⚠️ この API は DELETE であり、POST ではありません

---

Block の例

テキスト:

{"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 が手動で挿入されている場合は、まずその Block を読み取り、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
    }
  }
}

---

並行処理

Lark ドキュメントは複数人での共同編集に対応しているため、並行処理への対応が必要です。

1. 最新の revision を取得: GET /documents/{document_id}
2. revision を指定して書き込み: ?document_revision_id={revision}
3. 競合が発生した場合は再試行（HTTP 409）

---

Mermaid の推奨手順

ユーザーから「本文绘图格式统一 Mermaid」と依頼された場合は、通常のテキストブロックやコードブロック内の ```mermaid をそのまま書き込まないでください。

推奨される手順：

1. まず対象ドキュメントのすべての Block を読み取り、手動で調整された Mermaid 描画ブロックがすでに存在するか確認します
2. 存在する場合は、その Block の次の項目を読み取ります。
   • 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. 古い図を置き換える場合は、コンテンツの消失を防ぐため、新しい Block を挿入してから古い Block を削除します
5. 一括置換を行う場合は、まず親 Block の children の順序を読み取り、index を指定して正確に削除します

---

ベストプラクティス

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