docs (v1)

重要 — 開始前に、認証、権限処理を含む ../lark-shared/SKILL.md を必ず Read ツールで読み込んでください。

コアコンセプト

ドキュメントタイプとトークン

飛書オープンプラットフォームでは、異なるタイプのドキュメントで URL 形式とトークン処理方法が異なります。ドキュメント操作（コメントの追加、ファイルのダウンロードなど）を行う際は、まず正しい file_token を取得する必要があります。

ドキュメント URL 形式とトークン処理

Wiki リンクの特殊処理（重要！）

ナレッジベースリンク（/wiki/TOKEN）の背後には、クラウドドキュメント、スプレッドシート、多次元テーブルなど、さまざまな種類のドキュメントが存在する可能性があります。URL 内のトークンが file_token であると直接仮定することはできません。まず実際のタイプと実際のトークンを照会する必要があります。

処理フロー

1. wiki.spaces.get_node を使用してノード情報を照会

   lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'

2. 返された結果から主要な情報を抽出

   • node.obj_type：ドキュメントタイプ（docx/doc/sheet/bitable/slides/file/mindnote）
   • node.obj_token：実際のドキュメントトークン（後続の操作で使用）
   • node.title：ドキュメントタイトル

3. obj_type に基づいて対応する API を使用

   obj_type	説明	使用する API
   docx	新しいバージョンのクラウドドキュメント	drive file.comments.*、docx.*
   doc	古いバージョンのクラウドドキュメント	drive file.comments.*
   sheet	スプレッドシート	sheets.*
   bitable	多次元テーブル	bitable.*
   slides	スライド	drive.*
   file	ファイル	drive.*
   mindnote	マインドマップ	drive.*

照会例

# wiki ノードを照会
lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'

返された結果の例：

{
   "node": {
      "obj_type": "docx",
      "obj_token": "xxxx",
      "title": "タイトル",
      "node_type": "origin",
      "space_id": "12345678910"
   }
}

リソース関係

Wiki Space (知識空間)
└── Wiki Node (知識庫ノード)
    ├── obj_type: docx (新版ドキュメント)
    │   └── obj_token (実際のドキュメントトークン)
    ├── obj_type: doc (旧版ドキュメント)
    │   └── obj_token (実際のドキュメントトークン)
    ├── obj_type: sheet (スプレッドシート)
    │   └── obj_token (実際のドキュメントトークン)
    ├── obj_type: bitable (多次元テーブル)
    │   └── obj_token (実際のドキュメントトークン)
    └── obj_type: file/slides/mindnote
        └── obj_token (実際のドキュメントトークン)

Drive Folder (クラウドスペースフォルダ)
└── File (ファイル/ドキュメント)
    └── file_token (直接使用)

重要事項：ホワイトボードの編集

⚠️ lark-doc skill は既存のホワイトボードコンテンツを直接編集できませんが、docs +update で空白のホワイトボードを新規作成できます。

シナリオ 1：docs +fetch でドキュメントコンテンツとホワイトボードトークンを取得済みの場合

ユーザーが docs +fetch でドキュメントコンテンツを取得済みで、ドキュメントにホワイトボードが含まれている場合（返された Markdown に <whiteboard token="xxx"/> タグが含まれる場合）、ユーザーに以下を案内してください。

1. ホワイトボードのトークンを記録する
2. ../lark-whiteboard/SKILL.md を参照して、ホワイトボードコンテンツの編集方法を確認する

   シナリオ 2：ホワイトボードを新規作成し、編集が必要な場合

   ユーザーが docs +update で空白のホワイトボードを新規作成し、編集が必要な場合： ステップ 1：空白のホワイトボード構文で作成する

• --markdown に直接 <whiteboard type="blank"></whiteboard> を渡します。
• 複数の空白のホワイトボードが必要な場合は、同じ --markdown 内で複数の whiteboard タグを繰り返します。 ステップ 2：応答からトークンを記録する
• docs +update が成功した後、応答フィールド data.board_tokens を読み取ります。
• data.board_tokens は新規作成されたホワイトボードのトークンリストであり、後続の編集ではこのトークンを直接使用します。 ステップ 3：編集を案内する
• 編集が必要なホワイトボードトークンを記録します。
• ../lark-whiteboard/SKILL.md を参照して、ホワイトボードコンテンツの編集方法を確認します。

  注意事項

• 既存のホワイトボードコンテンツは、lark-doc の docs +update では直接編集できません。
• ホワイトボードの編集には、専用の ../lark-whiteboard/SKILL.md を使用する必要があります。

迅速な意思決定

• ユーザーが「表を探す」「名前でスプレッドシートを検索する」「レポートを探す」「最近開いた表」と言った場合、まず lark-cli docs +search を使用してリソースを検出します。
• docs +search はドキュメント / Wiki のみを検索するわけではありません。結果には SHEET などのクラウドスペースオブジェクトが直接返されます。
• スプレッドシートの URL / トークンを取得した後、lark-sheets に切り替えてオブジェクト内部の読み取り、フィルタリング、書き込みなどの操作を行います。

補足説明

docs +search は、ドキュメント / Wiki の検索に加えて、「まずクラウドスペースオブジェクトを特定し、その後対応するビジネススキルに切り替えて操作する」というリソース検出の入り口の役割も果たします。ユーザーが口頭で「表 / レポート」と言った場合も、ここから優先的に開始します。

Shortcuts（優先的に使用することを推奨）

Shortcut は、一般的な操作を高度にカプセル化したものです（lark-cli docs +<verb> [flags]）。Shortcut がある操作は優先的に使用してください。