drive (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 (直接使用)

一般的な操作のトークン要件

コメント機能の境界（重要！）

• drive +add-comment は2つのモードをサポートしています。
• 全文コメント：--selection-with-ellipsis / --block-id が渡されない場合にデフォルトで有効になります。--full-comment を明示的に渡すこともできます。docx、古いバージョンの doc URL、および最終的に doc/docx に解決される wiki URL をサポートします。
• 部分コメント：--selection-with-ellipsis または --block-id が渡された場合に有効になります。docx、および最終的に docx に解決される wiki URL のみをサポートします。
• drive +add-comment の --content には reply_elements JSON 配列文字列を渡す必要があります。例：--content '[{"type":"text","text":"正文"}]'。
• wiki が解析後に doc/docx でない場合、+add-comment を使用しないでください。
• より低レベルでコメント V2 プロトコルを直接呼び出す必要がある場合は、ネイティブ API を使用します。まず lark-cli schema drive.file.comments.create_v2 を実行し、次に lark-cli drive file.comments create_v2 ... を実行します。全文コメントは anchor を省略し、部分コメントは anchor.block_id を渡します。

コメントの照会と統計基準（重要！）

• ドキュメントコメントを照会する際は、drive file.comments list を使用します。
• drive file.comments list が返す items は「コメントカード」のリストとして理解されるべきであり、各 item はユーザーインターフェースに表示される1枚のコメントカードに対応し、フラットなインタラクションメッセージリストではありません。
• サーバー側のセマンティクスでは、最初のコメントが作成されると同時に、そのカード内の最初の返信も作成されます。したがって、本文を実際に保持しているのは各 item.reply_list.replies であり、その最初の返信はユーザーの視点から見ると、そのカード内の「コメント自体」です。
• ユーザーが「コメント数」または「コメントカード数」を統計したい場合、items の長さを統計すれば十分です。全量統計の場合は、すべてのコメントページングで返される items の長さを累積します。
• ユーザーが「返信数」を統計したい場合、ユーザーの視点からは各コメントカード内の最初のコメントを除外すべきであり、統計基準はすべての item.reply_list.replies の長さの合計から items の長さを引いたものです。
• ユーザーが「総インタラクション数」を統計したい場合、すべての item.reply_list.replies の長さの合計を統計すれば十分です。この基準には各コメントカード内の最初のコメントが含まれます。
• ある item.has_more=true の場合、そのコメントカードの下にさらに多くの返信が現在の返信に含まれていないことを意味します。この場合、drive file.comment.replys list を呼び出してすべて取得し、その後、全量返信数 / 総インタラクション数を統計する必要があります。

コメントのビジネス特性とガイダンス（重要！）

コメントの並べ替えガイダンス

• ドキュメントには通常複数のコメントがあり、コメントは create_time（作成時間）で並べ替えられます。
• 重要：ユーザーが「最新コメント」、「最後のコメント」、「最も古いコメント」を明確に言及した場合にのみ、create_time に基づいて並べ替える必要があります。
  • まずすべてのコメントを取得する必要があります（ページング処理で全データを取得する）。1ページだけ取得して並べ替えることはできません。
  • 「最新コメント」 / 「最後のコメント」：create_time の降順で並べ替え、最初の1件を取得します。
  • 「最も古いコメント」：create_time の昇順で並べ替え、最初の1件を取得します。
• ユーザーが「最初のコメント」とだけ言った場合、drive file.comments list が返す最初のコメントをそのまま使用すればよく、追加の並べ替えは不要です。

コメント返信の制限

• コメント返信を追加する前に、以下の制限があるか確認してください。
• 全文コメントは返信をサポートしていません：is_whole=true のコメント（全文コメント）には返信を追加できません。このようなコメントに遭遇した場合は、ユーザーに「全文コメントは返信をサポートしていません」と伝えるべきです。
• 解決済みのコメントは返信をサポートしていません：is_solved=true のコメントには返信を追加できません。このようなコメントに遭遇した場合は、ユーザーに「このコメントは解決済みのため、返信できません」と伝えるべきです。
• 注意：ユーザーが特定のコメントに返信しようとしたが、そのコメントが上記の制限により返信できない場合、返信できないことを伝えるだけで十分です。ユーザーの期待に反する可能性があるため、自動的に他の返信可能なコメントを探さないでください。

一括照会とリスト照会の選択

• drive file.comments batch_query の使用は、コメント ID が既知の場合の一括照会であり、具体的なコメント ID のリストを渡す必要があります。
• drive file.comments list の使用は、コメントリストをページングで取得するために使用され、コメント総数の統計、すべてのコメントの走査、または「最新/最後の N 件のコメント」などのシナリオに適しています。

典型的なエラーと解決策

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

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

API Resources

`