feishu-docx-powerwrite

Feishu Docx PowerWrite

OpenClaw のツールを使って、見栄えの良い Feishu Docx を確実に作成します。

ツールの選択

ツール	使用する場合	備考
feishu_doc(action="create")	新しいドキュメントを作成する	doc_token を返します
feishu_doc(action="write")	最初の内容を書き込む	ドキュメント全体を上書きします
feishu_doc(action="append")	後続の内容を追加する	1 回につき ≤1500 字
feishu_table.py	ネイティブの表を挿入する	Markdown の表はサポートされていません

⚠️ 使用しないでください create_feishu_doc ツール — JSON parse bug があり、失敗します。

基本的なワークフロー

1. ドキュメントの作成 + 書き込み

feishu_doc(action="create", title="标题")
→ 拿到 doc_token
feishu_doc(action="append", doc_token=xxx, content="第一段...")
feishu_doc(action="append", doc_token=xxx, content="第二段...")

2. 分割して書き込む場合のルール

• append 1 回につき ≤1500 字（超えると 400 エラーになります）
• 長いレポートは 4～5 回に分けて append します
• 章ごとに自然な単位で分割し、段落の途中で切らないでください

3. 表の書き込み

Markdown の表を feishu_doc append で書き込むと、断片的なテキストにばらばらになります（Table block type はスキップされます）。

正しい方法：feishu_table.py スクリプトを使ってネイティブの表を作成します。

python3 workspace/tools/feishu_table.py

コードからの呼び出し：

from feishu_table import create_table
create_table(doc_token, [
    ["列1", "列2", "列3"],   # 表头
    ["数据1", "数据2", "数据3"],
], header_bold=True)

4. $ 記号の処理

Feishu は $...$ を LaTeX 数式としてレンダリングします。ドル記号を含む内容を書き込む場合：

• ❌ $82.78 → 数式として解析されます
• ✅ 82.78美元 または USD 82.78

Markdown の書式設定に関するベストプラクティス

正しくレンダリングされる書式

• # ## ### 見出しレベル
• - 箇条書き + ネストには 2 つのスペースでインデント
• 1. 2. 3. 番号付きリスト
• ```code``` コードブロック
• **加粗** *斜体*
• --- 水平線
• 短い段落（各段落 3～5 行）

避けるべき書式

• Markdown の表（| col |）→ ネイティブの表を使用
• 長すぎる段落 → 短く分割
• $ 記号 → 文字に置き換える
• 深くネストしたリスト（3 階層超）→ フラット化する

長いドキュメントの作成パターン

サブエージェントで検索 + メインセッションで執筆

• サブエージェントが検索とデータ収集を担当します
• メインセッションがデータを統合してレポートを作成します
• 理由：sub-agent の maxTokens 制限（16k）により、長文を作成できず、content パラメーターも途中で切り詰められます

サブエージェントでの執筆が必須の場合

• タスクの説明で「分割して書き込み、各ブロックを 3000 字以下にする」と明記します
• exec heredoc を使ってローカルファイルに分割して書き込み、その後 Feishu にアップロードします

コンテキストの管理

長いドキュメントの作成では、session context が肥大化します：

• 大量のテキスト処理はサブエージェントに分離します
• exec コマンドの出力は tail/head で行数を制限します
• 長いドキュメントを書き終えた後、gateway の再起動が必要になる可能性があることを知らせます

権限の設定

新しいドキュメントはデフォルトで「インターネット上でリンクを知っている人がアクセス可能」に設定されます：

feishu_perm(action="add", token=doc_token, type="docx",
            member_type="openchat", member_id="oc_xxx", perm="view")

よくあるエラー

エラー	原因	解決方法
append が 400 を返す	1 回の内容が長すぎます	1 回につき ≤1500 字
表が断片的なテキストになる	Markdown の表はサポートされていません	feishu_table.py を使用
$ が数式になる	LaTeX として解析されます	「ドル」または「USD」を使用
create_feishu_doc が失敗する	ツールに bug があります	feishu_doc create + append を使用
sub-agent の書き込みが空になる	maxTokens による切り詰め	メインセッションで書くか、分割して書き込む
上流で 400 bad request が発生する	context が大きすぎます	gateway を再起動