ErisPulse ErisPulse
インタラクティブ版で開く →
このページのセクション
静的ミラーです。内容はインタラクティブ版が正となります インタラクティブ版で開く →

Kookプラットフォームの特徴ドキュメント

KookAdapterは、Kook(開黒啦)Bot WebSocketプロトコルに基づいて構築されたアダプターであり、Kookのすべての機能モジュールを統合し、一貫したイベント処理とメッセージ操作のインターフェースを提供します。


ドキュメント情報

  • 対応モジュールバージョン: 4.3.2
  • 維持者: ShanFish
  • 最終更新日: 2026-11-10

基本情報

  • プラットフォーム概要: Kook(元開黒啦)は、テキスト、音声、ビデオ通信をサポートするコミュニティプラットフォームであり、完全なBot開発インターフェースを提供します。
  • アダプター名: KookAdapter
  • 多アカウント対応: 複数のKook Botを同時に設定できます。
  • 接続方式: WebSocket長接続(Kookゲートウェイ経由)
  • 認証方式: Bot Tokenを用いた認証
  • 鏈式修飾対応: .Reply()、.At()、.AtAll()などの修飾メソッドをチェーンで使用できます。
  • OneBot12互換: OneBot12形式のメッセージ送信をサポートします。

設定説明

KookAdapterは複数アカウントの設定に対応しており、各アカウントは独立したKook Botに対応します。

# config.toml
# アカウント1
[KookAdapter.accounts.default]
token = "YOUR_BOT_TOKEN"     # Kook Bot Token(必須、形式: Bot xxx/xxx)
bot_id = ""                   # BotのユーザーID(オプション、未記入の場合はtokenから解析)
compress = true               # WebSocket圧縮の有効化(オプション、デフォルトはtrue)
enabled = true                # アカウントの有効化(オプション、デフォルトはtrue)

# アカウント2
[KookAdapter.accounts.bot2]
token = "ANOTHER_BOT_TOKEN"
bot_id = ""
enabled = true

旧設定の互換性: 旧の単一アカウントの[KookAdapter]設定(tokenを含む)が検出された場合、自動的にaccounts.defaultに移行されます。

各アカウントの設定項目説明:

  • token: Kook BotのToken(必須)、Kook開発者センターから取得、形式はBot xxx/xxx
  • bot_id: BotのユーザーID(オプション)、未記入の場合はtokenから自動解析されます。正確性を確保するため、手動で記入することを推奨します。
  • compress: WebSocketデータ圧縮の有効化(オプション、デフォルトはtrue)、有効化するとzlibでデータを解凍します。
  • enabled: アカウントの有効化(オプション、デフォルトはtrue)

API環境:

  • Kook APIの基本アドレス: https://www.kookapp.cn/api/v3
  • WebSocketゲートウェイはAPIを介して動的に取得: POST /gateway/index

標準化対応(4.3.2)

イベントとアカウント

  • イベント self.account_id 注入: すべてのイベントに発生元のアカウント名が注入され、複数アカウント下ではevent.reply()は自動的に該当アカウントで応答されます。

Api署名対応

動作 署名 説明
get_channel_info (guild_id, channel_id) 新しい署名guild_idが最初のパラメータに;1つの位置パラメータのみ渡された場合、旧署名(channel_idと見なす)を互換します。
get_channel_member_list (guild_id, channel_id) 同上互換ルール
get_guild_info / get_guild_list - dataはguild_id / guild_nameなどのフィールドを使用(旧group_*フィールドは破壊しないように保持)

エラーコード規格

エラーコードはSDKの標準化に従い、Kookプラットフォームの元のエラーコード(401xx/4xxxxなど)は直接retcodeとして使用されません:

retcode 説明
0 成功(成功応答messageは空文字列)
33001 ネットワークエラー(リクエスト異常、アカウントAPIインスタンスが初期化されていないなど)
34100 プラットフォームエラー(Kookが0以外のcodeを返した場合;元の応答はkook_rawに保持され、元のcodeはkook_codeフィールドに別途保存)
10002 不支持の動作(get_guild_member_info / get_guild_member_list / set_guild_name / leave_guild / leave_channelは明示的に返す;未知のAPIエンドポイントは例外を投げず、統一して10002を返す)

v5範式更新(4.1.0)

このアダプターはv5範式の対応を完了しました(段階的なアップグレード、API互換性あり):

  • BaseConverter継承: 転換器の共通フィールドはフレームワークbuild_base_eventで構築されます。
  • Api DSL: 標準Apiアクションのマッピング(以下を参照)
  • 標準 keyboard 段: {"type": "keyboard", "data": {"rows": [[{"label", "type": "callback|link", "data"}]]}} テキスト+キーボードは自動的にKookカードメッセージ(section + action-group)に組み合わされます;.Keyboard(rows)修飾子は汎用構造を受け入れます。
  • spawn_background 任務の帰属: 接続タスクはruntime.spawn_backgroundを使用します。
  • フレームワークのソフト依存: ErisPulse>=2.7.1の実行時検出と警告;起動時にバージョンログを出力します。

標準Apiアクション

from ErisPulse import sdk
kook = sdk.adapter.get("kook")

result = await kook.Api.get_self_info()              # GET /users/@me
result = await kook.Api.get_user_info(user_id)       # POST /user/view
result = await kook.Api.get_guild_info(guild_id)     # POST /guild/view(dataにguild_id / guild_nameを使用)
result = await kook.Api.get_guild_list()             # POST /guild/list
result = await kook.Api.get_channel_info(guild_id, channel_id)  # POST /channel/view(新しい署名guild_idが最初のパラメータ)
result = await kook.Api.get_channel_list(guild_id)   # POST /channel/list
await kook.Api.delete_message(msg_id)                # POST /message/delete
result = await kook.Api.Using("main").get_self_info()

ボタン(keyboard)

rows = [[{"label": "選択肢A", "type": "callback", "data": "vote:A"},
         {"label": "公式サイト",  "type": "link",     "data": "https://example.com"}]]
await kook.Send.To("channel", channel_id).Keyboard(rows).Text("選択してください")
# テキストとボタンは自動的にKookカードメッセージ(section + action-group)に組み合わされます。

# ボタンクリックのコールバック(標準フィールド)
from ErisPulse.Core.Event import notice

@notice.on_notice()
async def handle_button(event):
    if event.get("platform") == "kook" and event.get("button_data"):
        data = event["button_data"]

支援するメッセージ送信タイプ

すべての送信メソッドはチェーン式構文で実現されます。例えば:

from ErisPulse.Core import adapter
kook = adapter.get("kook")

await kook.Send.To("group", channel_id).Text("Hello World!")

支援する送信タイプは以下の通りです:

  • .Text(text: str):純粋なテキストメッセージを送信します。
  • .Image(file: bytes | str):画像メッセージを送信します。ファイルパス、URL、バイナリデータに対応します。
  • .Video(file: bytes | str):ビデオメッセージを送信します。ファイルパス、URL、バイナリデータに対応します。
  • .File(file: bytes | str, filename: str = None):ファイルメッセージを送信します。ファイルパス、URL、バイナリデータに対応します。
  • .Voice(file: bytes | str):音声メッセージを送信します。ファイルパス、URL、バイナリデータに対応します。
  • .Markdown(text: str):KMarkdown形式のメッセージを送信します。
  • .Card(card_data: dict):カードメッセージ(CardMessage)を送信します。
  • .MergeForward(nodes, title="合併チャット記録"):合併転送メッセージを送信します(カードにレンダリング:タイトルheader + 各メッセージごとにsection、KMDエスケープ、≤40ノード)。
  • .Raw_ob12(message: List[Dict], **kwargs):OneBot12形式のメッセージを送信します。

鏈式修飾メソッド(組み合わせ使用可能)

修飾メソッドはselfを返すため、チェーンで呼び出すことができます。最終的な送信メソッドの前に呼び出す必要があります:

  • .Reply(message_id: str):指定したメッセージに返信(引用)します。
  • .At(user_id: str):指定したユーザーを@します。複数回呼び出すことで複数のユーザーを@できます。
  • .AtAll():全員を@します。

鏈式呼び出しの例

# 基本的な送信
await kook.Send.To("group", channel_id).Text("Hello")

# メッセージの返信
await kook.Send.To("group", channel_id).Reply(msg_id).Text("返信メッセージ")

# ユーザーを@する
await kook.Send.To("group", channel_id).At("user_id").Text("こんにちは")

# 複数のユーザーを@する
await kook.Send.To("group", channel_id).At("user1").At("user2").Text("複数のユーザー@")

# 全員を@する
await kook.Send.To("group", channel_id).AtAll().Text("お知らせ")

# 組み合わせ
await kook.Send.To("group", channel_id).Reply(msg_id).At("user_id").Text("複合メッセージ")

OneBot12メッセージのサポート

アダプターはOneBot12形式のメッセージ送信をサポートし、プラットフォーム間のメッセージ互換性を確保します:

# OneBot12形式のメッセージを送信
ob12_msg = [{"type": "text", "data": {"text": "Hello"}}]
await kook.Send.To("group", channel_id).Raw_ob12(ob12_msg)

# 鏈式修飾と組み合わせる
ob12_msg = [{"type": "text", "data": {"text": "返信メッセージ"}}]
await kook.Send.To("group", channel_id).Reply(msg_id).Raw_ob12(ob12_msg)

# Raw_ob12でmentionとreplyメッセージセグメントを使用
ob12_msg = [
    {"type": "text", "data": {"text": "Hello "}},
    {"type": "mention", "data": {"user_id": "user_id"}},
    {"type": "reply", "data": {"message_id": "msg_id"}}
]
await kook.Send.To("group", channel_id).Raw_ob12(ob12_msg)

追加操作メソッド

メッセージ送信以外にも、Kookアダプターは以下の操作をサポートします:

# メッセージの編集(KMarkdown type=9とCardMessage type=10のみサポート)
await kook.Send.To("group", channel_id).Edit(msg_id, "**更新後の内容**")

# メッセージの撤回
await kook.Send.To("group", channel_id).Recall(msg_id)

# ファイルのアップロード(ファイルURLの取得)
result = await kook.Send.Upload("C:/path/to/file.jpg")
file_url = result["data"]["url"]

送信メソッドの戻り値

すべての送信メソッドはTaskオブジェクトを返し、直接awaitして送信結果を取得できます。返り値はErisPulseアダプターの標準化された返り値規格に従います:

{
    "status": "ok",           // 実行状態: "ok" または "failed"
    "retcode": 0,             // 返り値コード(0が成功、プラットフォームエラーは34100)
    "data": {...},            // 応答データ
    "message_id": "xxx",      // メッセージID
    "message": "",            // エラー情報(成功応答は空文字列)
    "kook_raw": {...},        // 元の応答データ
    "kook_code": 0            // Kookの元のcode(エラー時は保存)
}

エラーコードの説明

retcode 説明
0 成功
33001 ネットワークエラー(リクエスト異常、アカウントAPIインスタンスが初期化されていないなど)
34100 プラットフォームエラー(Kookが0以外のcodeを返した場合、元の応答はkook_rawに保持され、元のcodeはkook_codeに保存)
10002 不支持の動作(「標準化対応(4.3.2)」のエラーコード規格を参照)

特有のイベントタイプ

platform=="kook"の検証が必要です。このプラットフォームの特性を使用するには。

核心的な違い

  1. チャンネルシステム: Kookはサーバー(Guild)とチャンネル(Channel)の2層構造を使用し、チャンネルがメッセージの基本的な送信先です。
  2. メッセージタイプ: Kookはテキスト(1)、画像(2)、ビデオ(3)、ファイル(4)、音声(8)、KMarkdown(9)、カードメッセージ(10)など、多様なメッセージタイプをサポートします。
  3. プライベートメッセージシステム: Kookはチャンネルメッセージとプライベートメッセージを区別し、異なるAPIエンドポイントを使用します。
  4. メッセージ番号: KookのWebSocketはsn番号を使用してメッセージの順序性を保証し、メッセージの一時保存と乱序の再配置をサポートします。
  5. メッセージの編集と撤回: KMarkdownとCardMessageの既送信メッセージの編集とメッセージの撤回をサポートします。

拡張フィールド

  • すべての特有のフィールドはkook_前接辞で識別されます。
  • 元のデータはkook_rawフィールドに保持されます。
  • kook_raw_typeは元のKookメッセージタイプ番号を識別します(例: 1はテキスト、255は通知イベント)。
  • イベントself.account_idはイベントを発生させたアカウント名です(複数アカウント下ではevent.reply()は該当アカウントで自動的に受理されます)。

特殊フィールドの例

# チャンネルテキストメッセージ
{
  "type": "message",
  "detail_type": "group",
  "user_id": "ユーザーID",
  "group_id": "チャンネルID",
  "channel_id": "チャンネルID",
  "message_id": "メッセージID",
  "self": {
    "platform": "kook",
    "user_id": "BotID",
    "account_id": "default"
  },
  "kook_raw": {...},
  "kook_raw_type": "1",
  "message": [
    {"type": "text", "data": {"text": "Hello"}}
  ],
  "alt_message": "Hello"
}

# 画像付きメッセージ
{
  "type": "message",
  "detail_type": "group",
  "user_id": "ユーザーID",
  "group_id": "チャンネルID",
  "channel_id": "チャンネルID",
  "message_id": "メッセージID",
  "kook_raw": {...},
  "kook_raw_type": "2",
  "message": [
    {"type": "image", "data": {"file": "画像URL", "url": "画像URL"}}
  ],
  "alt_message": "画像の内容"
}

# KMarkdownメッセージ
{
  "type": "message",
  "detail_type": "group",
  "user_id": "ユーザーID",
  "group_id": "チャンネルID",
  "message_id": "メッセージID",
  "kook_raw": {...},
  "kook_raw_type": "9",
  "message": [
    {"type": "text", "data": {"text": "解析後の純粋なテキスト"}}
  ]
}

# カードメッセージ
{
  "type": "message",
  "detail_type": "group",
  "user_id": "ユーザーID",
  "group_id": "チャンネルID",
  "message_id": "メッセージID",
  "kook_raw": {...},
  "kook_raw_type": "10",
  "message": [
    {"type": "json", "data": {"data": "カードのJSON内容"}}
  ]
}

# プライベートメッセージ
{
  "type": "message",
  "detail_type": "private",
  "user_id": "ユーザーID",
  "message_id": "メッセージID",
  "kook_raw": {...},
  "kook_raw_type": "1",
  "message": [
    {"type": "text", "data": {"text": "プライベートメッセージの内容"}}
  ]
}

メッセージセグメントタイプ

Kookのメッセージタイプはtypeフィールドに基づいて対応するメッセージセグメントに自動変換されます:

Kook type 変換タイプ 説明
1 text テキストメッセージ
2 image 画像メッセージ
3 video ビデオメッセージ
4 file ファイルメッセージ
8 record 音声メッセージ
9 text KMarkdownメッセージ(純粋なテキスト内容を抽出)
10 json カードメッセージ(元のJSON)

メッセージセグメントの構造例:

{
  "type": "image",
  "data": {
    "file": "画像URL",
    "url": "画像URL"
  }
}

Mentionメッセージセグメント

メッセージに@情報が含まれている場合、メッセージセグメントの前にmentionメッセージセグメントが挿入されます:

{
  "type": "mention",
  "data": {
    "user_id": "@されたユーザーID"
  }
}

mention_allメッセージセグメント

メッセージが全員を@している場合、mention_allメッセージセグメントが挿入されます:

{
  "type": "mention_all",
  "data": {}
}

WebSocket接続

接続フロー

  1. Bot Tokenを使用してPOST /gateway/indexを呼び出し、WebSocketゲートウェイアドレスを取得します。
  2. WebSocketゲートウェイに接続します。
  3. HELLO(s=1)シグナルを受信し、接続状態を検証します。
  4. ハートビートループを開始します(PING、s=2、30秒ごとに1回)、現在のsnを含みます。
  5. メッセージイベント(s=0)を受信し、sn番号を使用して順序性を保証します。
  6. ハートビート応答PONG(s=3)を受信します。

シグナルタイプ

シグナル s値 説明
HELLO 1 サーバーの歓迎シグナル、接続成功後に受信します
PING 2 クライアントのハートビート、30秒ごとに送信し、現在のsnを含みます
PONG 3 ハートビート応答
RESUME 4 接続の再開シグナル、snを含みセッションを再開します
RECONNECT 5 サーバーが再接続を要求するシグナル、再びゲートウェイを取得する必要があります
RESUME_ACK 6 RESUME成功応答

断線再接続

  • 接続が異常断線した場合、アダプターは自動的に再接続を試みます。
  • 以前にsn > 0があった場合、まずRESUME(s=4)を試みます。
  • RESUMEに失敗した場合、snとメッセージキューをリセットし、完全な新接続(HELLOフロー)を行います。
  • RECONNECT(s=5)シグナルを受信した場合、状態をクリアして再接続します。

メッセージ番号メカニズム

Kook WebSocketはsn(増加する番号)を使用してメッセージの順序性を保証します:

  • 各メッセージイベント(s=0)を受信するたびに、snが増加します。
  • 受信したメッセージのsnが連続していない場合、一時保存モードに入ります。
  • 一時保存エリアのメッセージはsn順に並べ替えられ、欠落したメッセージが到着した後に順序に従って処理されます。
  • 一時保存エリアがクリアされた後は、自動的に一時保存モードを終了します。

使用例

チャンネルメッセージの処理

from ErisPulse.Core.Event import message
from ErisPulse import sdk

kook = sdk.adapter.get("kook")

@message.on_message()
async def handle_group_msg(event):
    if event.get("platform") != "kook":
        return
    if event.get("detail_type") != "group":
        return

    text = event.get_text()
    channel_id = event.get("group_id")

    if text == "hello":
        await kook.Send.To("group", channel_id).Text("Hello!")

プライベートメッセージの処理

@message.on_message()
async def handle_private_msg(event):
    if event.get("platform") != "kook":
        return
    if event.get("detail_type") != "private":
        return

    text = event.get_text()
    user_id = event.get("user_id")

    await kook.Send.To("user", user_id).Text(f"あなたが言った: {text}")

通知イベントの処理(絵文字反応など)

from ErisPulse.Core.Event import notice

@notice.on_notice()
async def handle_notice(event):
    if event.get("platform") != "kook":
        return

    sub_type = event.get("sub_type")

    if sub_type == "added_reaction":
        emoji = event.get("emoji", {})
        user_id = event.get("user_id")
        msg_id = event.get("message_id")
        print(f"ユーザー {user_id} がメッセージ {msg_id} に絵文字反応を追加しました")

    elif sub_type == "deleted_reaction":
        emoji = event.get("emoji", {})
        user_id = event.get("user_id")
        msg_id = event.get("message_id")
        print(f"ユーザー {user_id} がメッセージ {msg_id} の絵文字反応を削除しました")

メディアメッセージの送信

# 画像送信(URL)
await kook.Send.To("group", channel_id).Image("https://example.com/image.png")

# 画像送信(バイナリ)
with open("image.png", "rb") as f:
    image_bytes = f.read()
await kook.Send.To("group", channel_id).Image(image_bytes)

# ビデオ送信
await kook.Send.To("group", channel_id).Video("https://example.com/video.mp4")

# ファイル送信
await kook.Send.To("group", channel_id).File("https://example.com/file.pdf", filename="document.pdf")

# 音声送信
await kook.Send.To("group", channel_id).Voice("https://example.com/voice.mp3")

KMarkdownとカードメッセージの送信

# KMarkdown
await kook.Send.To("group", channel_id).Markdown("**太字** *斜体* [リンク](https://example.com)")

# カードメッセージ
card = {
    "type": "card",
    "theme": "primary",
    "size": "lg",
    "modules": [
        {"type": "header", "text": {"type": "plain-text", "content": "タイトル"}},
        {"type": "section", "text": {"type": "kmarkdown", "content": "内容"}}
    ]
}
await kook.Send.To("group", channel_id).Card(card)

メッセージの編集と撤回

# メッセージ送信
result = await kook.Send.To("group", channel_id).Markdown("**元の内容**")
msg_id = result["data"]["msg_id"]

# メッセージの編集(KMarkdownとCardMessageのみサポート)
await kook.Send.To("group", channel_id).Edit(msg_id, "**更新後の内容**")

# メッセージの撤回
await kook.Send.To("group", channel_id).Recall(msg_id)

プライベートメッセージの編集と削除通知の処理

@notice.on_notice()
async def handle_private_notice(event):
    if event.get("platform") != "kook":
        return

    sub_type = event.get("sub_type")

    if sub_type == "updated_private_message":
        msg_id = event.get("message_id")
        content = event.get("content")
        print(f"プライベートメッセージが更新されました: {msg_id}, 新しい内容: {content}")

    elif sub_type == "deleted_private_message":
        msg_id = event.get("message_id")
        print(f"プライベートメッセージが削除されました: {msg_id}")