lark-event

Lark Events

前提条件： 認証、--as user/bot の切り替え、Permission denied の処理、安全ルールについて、まず ../lark-shared/SKILL.md をお読みください。

コアコマンド

コマンド	目的
lark-cli event list [--json]	購読可能なすべての EventKey を一覧表示します
lark-cli event schema <EventKey> [--json]	EventKey のパラメーターと出力スキーマを表示します
lark-cli event consume <EventKey> [flags]	ブロッキングで消費し、イベントを NDJSON 形式で stdout に出力します
lark-cli event status [--json] [--fail-on-orphan]	ローカルバスデーモンの状態を確認します
lark-cli event stop [--all] [--force]	バスデーモンを停止します

共通フラグ

フラグ	説明
--param key=value / -p	業務パラメーター（複数指定可能。複数値はカンマ区切り）。不明なキーが指定されると、使用可能な名前をその場で一覧表示して失敗します
--jq <expr>	各イベントをフィルター／変換する jq 式。出力が空の場合、そのイベントはスキップされます
--max-events N	N 件のイベントを受信した後に終了します。デフォルトの 0 は無制限です
--timeout D	期間 D（例：30s、2m）経過後に終了します。デフォルトの 0 はタイムアウトなしです。--max-events と --timeout のうち、先に条件を満たした方が適用されます
--output-dir <dir>	各イベントをファイルとして書き込みます（相対パスのみ。パストラバーサルを防止します）
--quiet	準備完了／終了マーカーと、イベントごとの stderr 診断メッセージ（ドロップ警告を含む）を抑制します。イベントの損失が見えなくなる可能性があります。AI は使用しないでください — 準備完了と整合性を示すシグナルが失われます
--as user|bot|auto	セッションの ID（lark-shared を参照）

例

# Default: stream every event for the key (no filter, no projection)
lark-cli event consume im.message.receive_v1 --as bot

# List every EventKey of one domain (the authoritative, always-current catalog)
lark-cli event list --domain vc --json

# Grab one sample event to inspect payload shape
lark-cli event consume im.message.receive_v1 --max-events 1 --timeout 30s --as bot

# Run for 10 minutes then auto-exit
lark-cli event consume im.message.receive_v1 --timeout 10m --as bot

# Consume multiple EventKeys concurrently (one shape per process, no dispatcher)
lark-cli event consume im.message.receive_v1          --as bot > receive.ndjson &
lark-cli event consume im.message.reaction.created_v1 --as bot > reaction.ndjson &
wait

呼び出しフロー

1. lark-cli event list --json → 使用可能なキーを選択します。--domain <d> を指定すると、ドメインを 1 つに絞れます。ドメインは application、approval、board、card、im、minutes、task、vc です。不明なドメインを指定すると、ヒントに使用可能な値が表示され、失敗します。
2. lark-cli event schema <key> --json → resolved_output_schema と jq_root_path を読み取り、フィールドのパスを確認します
3. lark-cli event consume <key> [--jq '<expr>'] → イベントを受信します

サブプロセスの仕様

準備完了マーカー

event consume は stderr に固定行 [event] ready event_key=<key> を出力します。親プロセスは、この行が現れるまで stderr の出力を待ってから、stdout の読み取りを開始してください。 sleep による代替は行わないでください。

stdin の EOF = 正常終了

event consume は stdin のクローズをシャットダウンシグナルとして扱います（AI のサブプロセス呼び出し元向けに実装されています）。ただし、上限を設定した実行では例外です。--max-events または --timeout が設定されている（> 0）場合、stdin の EOF は無視され、設定した上限、タイムアウト、または SIGTERM によってのみ終了します。 上限のない実行では、< /dev/null／nohup／systemd のデフォルトの StandardInput=null により、即座に正常終了します（stderr の reason: signal）。上限のない実行を継続するには、次のいずれかを行います。

• EOF にならない入力元を stdin に渡す：< <(tail -f /dev/null)
• または上限を設定して実行する：--max-events N／--timeout D

終了コードと理由

終了時、stderr の最後の行には [event] exited — received N event(s) in Xs (reason: ...) が出力されます。

終了コード	理由	トリガー
0	reason: limit	--max-events に到達
0	reason: timeout	--timeout に到達
0	reason: signal	Ctrl+C / SIGTERM / stdin EOF（stdin EOF は上限のない実行にのみ適用）
1	stderr に JSON エラーエンベロープ	消費前のセットアップ中に Lark API のビジネス上の失敗が発生（例：サブスクリプションの作成／削除）
2	stderr に JSON エラーエンベロープ（exited 行なし）	検証エラー（不明な EventKey、不正な --param / --jq、別のバスがすでに接続済み）
3	stderr に JSON エラーエンベロープ	認証エラー（トークンがない、スコープが不足）
4 / 5	stderr に JSON エラーエンベロープ	ネットワーク／内部エラー（バスの起動、ハンドシェイク、ファイル I/O）

起動時および実行時のエラーは、stderr に構造化された JSON エンベロープを出力します：{"ok":false,"error":{"type","subtype","param","message","hint",...}}（エンベロープには、トップレベルに identity / _notice の兄弟フィールドが含まれる場合もあります）。分岐には error.type / error.subtype を解析し（例：missing_scope には missing_scopes のリストが含まれます）、問題のあるフラグの特定には error.param を、復旧方法の確認には error.hint を使用してください。メッセージテキストに対する正規表現マッチングは使用しないでください。

オーケストレーターでは、reason: limit/timeout/signal（いずれも終了コード 0）は「ビジネス上の完了」として扱い、ゼロ以外は「失敗」として扱ってください。

kill -9 は使用しないでください

サーバー側のサブスクリプションを登録し、終了時に登録解除する PreConsume を持つ EventKey（minutes、vc、board のキー）の消費プロセスに対して、kill -9 は使用しないでください。kill -9 では OAPI の登録解除が実行されず、サーバー側のサブスクリプションが残ります（再起動時に「subscription already exists」と表示される、イベントが重複して配信されるなどの症状が発生します）。登録解除の処理がない永続的な関係としてサブスクリプションを保持するキー（task、approval のキー）ではこのような問題は起きませんが、どのキーでも SIGTERM を送るか stdin を閉じる方法で終了するのが適切です。

consume 1 回につき EventKey は 1 つ（複数キーの場合はシェルも複数）

このコマンドに指定できる位置引数はちょうど 1 つです。k1,k2 とワイルドカードはサポートされていません。N 個のキーをリッスンするには、N 個のサブプロセスが必要です。これは意図的な仕様です：

• プロセスごとに stdout の形式が 1 つなので、AI にディスパッチャーロジックは不要
• 障害を分離可能（一方のキーの失敗が他のキーに影響しない）
• キーごとに --as / --jq / --max-events / --timeout を個別に設定可能

N 個のコンシューマーはすべて 1 つのバスデーモン（UDS ローカル IPC）を共有するため、オーバーヘッドは小さいです

スキーマを使った jq の記述

--jq を記述する際の信頼できる情報源は event schema <key> --json です。確認するポイントは 4 つあります。

（1）フィールドの開始位置 — jq_root_path を確認します

• 値が "." → フィールドはトップレベルにあります。.chat_id と記述します
• 値が ".event" → フィールドは V2 エンベロープ内にあります。.event.chat_id と記述します

（2）フィールド一覧と型 — resolved_output_schema.properties.<name> を確認します

各フィールドには type / description があり、一部には format もあります。抜粋（event schema im.message.receive_v1 --json の出力）：

{
  "chat_id":     {"type":"string", "format":"chat_id",      "description":"Chat ID, prefixed with oc_"},
  "sender_id":   {"type":"string", "format":"open_id",      "description":"Sender open_id, prefixed with ou_"},
  "create_time": {"type":"string", "format":"timestamp_ms", "description":"Send time as ms-epoch string"}
}

（3）フィールドの意味 — format タグを確認します

Lark が定義した意味タグです（JSON Schema の標準 format ではありません）。よく使われる値は open_id / chat_id / message_id / timestamp_ms / email です。同じ文字列型でも意味が異なるフィールドを区別し、API で逆引きしたり、形式を変換したりするために使います。

（4）デコード済みの状態 — フィールドの description を確認します

event consume は Process フックを実行し、ペイロードの一部フィールドを事前にデコードすることがあります（V2 エンベロープのフラット化、.content のプレーンテキストへの変換など）。この動作は raw OAPI とは異なります。jq を記述する前に、必ずフィールドの description を確認してください。特に content / data / body / payload などの汎用的なフィールド名に注意してください。

重要な理由：すでにデコード済みのテキストフィールドに無条件で fromjson を適用すると、すべてのイベントで jq エラーが発生し、イベントが黙って破棄されます。コンシューマーは動作しているように見えて何も出力せず、stderr の奥に WARN が 1 行だけ表示されます。（これは一般的な動作です。jq の実行時エラーが発生すると、1 行の WARN とともにそのイベントがスキップされますが、ループは中断されません。）

スキーマを省略しないでください：jq で event schema --json の出力を抽出する際に、properties から .description を取り除かないでください。フィールドがすでにデコード済みかどうかを示すのがこの情報です。キーだけでなく、プロパティオブジェクト全体を出力してください。

---

補足：--param で指定できるパラメーターもスキーマに記載されています。params セクションには name / type / required / enum / default / description が記載されています。セクションがない場合、このキーは --param を受け付けません。

トピック一覧

トピック	リファレンス	内容
アプリケーション	references/lark-event-application.md	application.bot.menu_v6（カスタムボットメニューのプッシュイベントを含む）など、Application EventKey の一覧 + フラット化された event_key / operator フィールド + jq レシピ
承認	references/lark-event-approval.md	2 つの Approval EventKey（approval.instance.status_changed_v4、approval.task.status_changed_v4）の一覧 + 任意指定／複数指定が可能な subscription_type の事前登録 + ユーザー認証サブスクリプションのライフサイクル + フラット出力フィールドのリファレンス
IM	references/lark-event-im.md	12 個の IM EventKey の一覧 + 形式に関する注意（フラット形式と V2 エンベロープ）+ im.message.receive_v1 のフィールドに関する注意点（sender_id は open_id のみ、.content は interactive カードを除いてプレーンテキスト）+ よく使う jq レシピ（chat_type / message_type / sender によるフィルタリング）。card.action.trigger については、../lark-im/references/lark-im-card-action-reply.md も参照
タスク	references/lark-event-task.md	1 つの Task EventKey（task.task.update_user_access_v2）の一覧 + Native V2 エンベロープ形式 + task のコミットタイプ + ユーザー／ボットのサブスクリプションに関する注意
VC	references/lark-event-vc.md	7 個の VC EventKey（ミーティングのライフサイクル participant_meeting_started/joined/ended_v1、vc.note.generated_v1、録画の recording_started/transcript_generated/ended_v1）の一覧 + フィールドリファレンス + ソースタイプの意味。最新の一覧は常に lark-cli event list --domain vc --json で確認できます
議事録	references/lark-event-minutes.md	1 つの Minutes EventKey（minutes.minute.generated_v1）の一覧 + フィールドリファレンス + ソースタイプの意味（ミーティングのみ）
ホワイトボード	references/lark-event-whiteboard.md	1 つの Board EventKey（board.whiteboard.updated_v1）の一覧 + ホワイトボードごとのサブスクリプションモデル（-p whiteboard_id=<token> が必要）+ ペイロードフィールドのリファレンス（whiteboard_id / operator_ids のトリプル ID）