qqbot-channel

QQ チャンネル API リクエストガイド

この Skill は QQ チャンネル（Guild/Channel）の操作のみを扱います。 チャンネル ID は数字のみで構成され、API パスは /guilds/... および /channels/... です。

qqbot_platform_api は QQ オープンプラットフォームの統合 HTTP API ゲートウェイで、認証 Token を自動的に補完します。HTTP メソッド、API パス、リクエストボディ、クエリパラメーターを指定するだけで、チャンネル関連のインターフェースを呼び出せます。

---

🔀 対象範囲（必読）

QQ チャンネルは Discord に似たコミュニティ製品で、階層構造は チャンネル（Guild） → 子チャンネル（Channel） です。

階層	中国語名	英語	API パス	ID 形式
最上位	チャンネル	Guild	/guilds/{guild_id}	数字のみ（例：123456）
2 番目	子チャンネル	Channel	/channels/{channel_id}	数字のみ（例：789012）

主な特徴：

• チャンネル内に複数の子チャンネル（テキスト、音声、フォーラム、ライブ配信など）を作成できます
• 投稿、告知、スケジュールなどの機能に対応しています
• チャンネルメンバーは /guilds/{guild_id}/members で管理します
• ID は数字のみの形式で、API パスは /guilds/ または /channels/ で始まります

トリガーキーワード：チャンネル、子チャンネル、guild、channel、投稿、スケジュール、告知、フォーラム、チャンネルメンバー

📚 詳細なリファレンスドキュメント

各インターフェースの全パラメーターの説明、戻り値の構造、列挙値の定義：

• references/api_references.md

---

🔧 ツールのパラメーター

パラメーター	型	必須	説明
method	string	はい	HTTP メソッド：GET、POST、PUT、PATCH、DELETE
path	string	はい	API パス（ドメイン名を含まない）。例：/guilds/{guild_id}/channels。プレースホルダーは実際の値に置き換える必要があります
body	object	いいえ	リクエストボディの JSON（POST/PUT/PATCH で使用）
query	object	いいえ	URL クエリパラメーターのキーと値のペア。値は文字列型です

ベース URL：https://api.sgroup.qq.com、認証ヘッダー Authorization: QQBot {token} はツールによって自動的に補完されます。

---

⭐ インターフェース早見表

チャンネル（Guild）

操作	メソッド	パス	パラメーターの説明
チャンネル一覧を取得	GET	/users/@me/guilds	query：before、after、limit（最大100）
チャンネル API 権限を取得	GET	/guilds/{guild_id}/api_permission	—

子チャンネル（Channel）

操作	メソッド	パス	パラメーターの説明
子チャンネル一覧を取得	GET	/guilds/{guild_id}/channels	—
子チャンネルの詳細を取得	GET	/channels/{channel_id}	—
子チャンネルを作成	POST	/guilds/{guild_id}/channels	body：name*、type*、position*、sub_type、parent_id、private_type、private_user_ids、speak_permission、application_id
子チャンネルを変更	PATCH	/channels/{channel_id}	body：name、position、parent_id、private_type、speak_permission（少なくとも1つ）
子チャンネルを削除	DELETE	/channels/{channel_id}	⚠️ 元に戻せません

子チャンネルのタイプ（type）：0=テキスト、2=音声、4=グループ（position≥2）、10005=ライブ配信、10006=アプリケーション、10007=フォーラム

メンバー（Member）

操作	メソッド	パス	パラメーターの説明
メンバー一覧を取得	GET	/guilds/{guild_id}/members	query：after（初回は0を指定）、limit（1～400）
メンバーの詳細を取得	GET	/guilds/{guild_id}/members/{user_id}	—
ロールメンバー一覧を取得	GET	/guilds/{guild_id}/roles/{role_id}/members	query：start_index（初回は0を指定）、limit（1～400）
オンラインメンバー数を取得	GET	/channels/{channel_id}/online_nums	—

告知（Announces）

操作	メソッド	パス	パラメーターの説明
告知を作成	POST	/guilds/{guild_id}/announces	body：message_id、channel_id、announces_type（0=メンバー、1=歓迎）、recommend_channels（最大3件）
告知を削除	DELETE	/guilds/{guild_id}/announces/{message_id}	message_id に all を設定するとすべて削除されます

フォーラム（Forum）— プライベートドメインのボットのみ

操作	メソッド	パス	パラメーターの説明
投稿一覧を取得	GET	/channels/{channel_id}/threads	—
投稿の詳細を取得	GET	/channels/{channel_id}/threads/{thread_id}	—
投稿を公開	PUT	/channels/{channel_id}/threads	body：title*、content*、format（1=テキスト、2=HTML、3=Markdown、4=JSON、デフォルトは3）
投稿を削除	DELETE	/channels/{channel_id}/threads/{thread_id}	⚠️ 元に戻せません
コメントを投稿	POST	/channels/{channel_id}/threads/{thread_id}/comment	body：thread_author*、content*、thread_create_time、image

スケジュール（Schedule）

操作	メソッド	パス	パラメーターの説明
スケジュールを作成	POST	/channels/{channel_id}/schedules	body：{ schedule: { name*, start_timestamp*, end_timestamp*, jump_channel_id, remind_type } }
スケジュールを変更	PATCH	/channels/{channel_id}/schedules/{schedule_id}	body：{ schedule: { name*, start_timestamp*, end_timestamp*, jump_channel_id, remind_type } }
スケジュールを削除	DELETE	/channels/{channel_id}/schedules/{schedule_id}	⚠️ 元に戻せません

リマインダーのタイプ（remind_type）："0"=通知なし、"1"=開始時、"2"=5分前、"3"=15分前、"4"=30分前、"5"=60分前

* は必須パラメーターを示します

---

💡 呼び出し例

チャンネル一覧を取得

{
  "method": "GET",
  "path": "/users/@me/guilds",
  "query": { "limit": "100" }
}

获取子频道列表

{
  "method": "GET",
  "path": "/guilds/123456/channels"
}

创建子频道

{
  "method": "POST",
  "path": "/guilds/123456/channels",
  "body": {
    "name": "新频道",
    "type": 0,
    "position": 1,
    "sub_type": 0
  }
}

获取成员列表（分页）

{
  "method": "GET",
  "path": "/guilds/123456/members",
  "query": { "after": "0", "limit": "100" }
}

发表论坛帖子

{
  "method": "PUT",
  "path": "/channels/789012/threads",
  "body": {
    "title": "公告标题",
    "content": "# 标题\n\n公告内容",
    "format": 3
  }
}

创建日程

{
  "method": "POST",
  "path": "/channels/456789/schedules",
  "body": {
    "schedule": {
      "name": "周会",
      "start_timestamp": "1770733800000",
      "end_timestamp": "1770737400000",
      "remind_type": "2"
    }
  }
}

创建推荐子频道公告

{
  "method": "POST",
  "path": "/guilds/123456/announces",
  "body": {
    "announces_type": 0,
    "recommend_channels": [
      { "channel_id": "789012", "introduce": "欢迎来到攻略频道" }
    ]
  }
}

删除所有公告

{
  "method": "DELETE",
  "path": "/guilds/123456/announces/all"
}

---

🔄 常用操作流程

获取频道和子频道信息

1. GET /users/@me/guilds → 获取频道列表，拿到 guild_id
2. GET /guilds/{guild_id}/channels → 获取子频道列表，拿到 channel_id
3. GET /channels/{channel_id} → 获取子频道详情

论坛发帖 + 评论

1. GET /guilds/{guild_id}/channels → 找到论坛子频道（type=10007）
2. PUT /channels/{channel_id}/threads → 发表帖子
3. GET /channels/{channel_id}/threads → 获取帖子列表
4. GET /channels/{channel_id}/threads/{thread_id} → 获取帖子详情（含 author_id）
5. POST /channels/{channel_id}/threads/{thread_id}/comment → 发表评论

成员管理

1. GET /users/@me/guilds → 获取 guild_id
2. GET /guilds/{guild_id}/members?after=0&limit=100 → 获取成员列表
   翻页：用上次最后一个 user.id 作为 after，直到返回空数组
3. GET /guilds/{guild_id}/members/{user_id} → 获取指定成员详情

展示成员头像

成员详情返回的 user.avatar 是头像 URL，必须使用 Markdown 图片语法展示，让用户直接看到头像图片，而非纯文本链接：

成员信息：
· 昵称：{nick}
· 头像：
![头像]({user.avatar})

禁止将头像 URL 作为纯文本或超链接展示（如 查看头像），必须用 ![描述](URL) 语法内联显示。频道的 icon 字段同理。

---

🚨 错误码处理

错误码	说明	解决方案
401	Token 鉴权失败	检查 AppID 和 ClientSecret 配置
11241	频道 API 无权限	前往 QQ 开放平台申请权限，或调用 GET /guilds/{guild_id}/api_permission 查看可用权限
11242	仅私域机器人可用	需在 QQ 开放平台将机器人切换为私域模式
11243	需要管理频道权限	确保机器人拥有管理权限
11281	日程频率限制	单管理员/天限 10 次，单频道/天限 100 次
304023	推荐子频道超限	推荐子频道最多 3 条

---

⚠️ 注意事项

1. 适用范围：本 Skill 仅处理 QQ 频道（Guild/Channel）操作，API 路径以 /guilds/ 或 /channels/ 开头，ID 为纯数字
2. 路径中的占位符（如 {guild_id}、{channel_id}）必须替换为实际的纯数字 ID
3. query 参数的值必须为字符串类型，如 { "limit": "100" } 而非 { "limit": 100 }
4. 成员列表翻页时可能返回重复成员，需按 user.id 去重
5. 公告的两种类型（消息公告和推荐子频道公告）会互相顶替
6. 日程的时间戳为毫秒级字符串
7. 删除操作不可逆，请谨慎使用
8. 论坛操作仅私域机器人可用
9. 子频道分组（type=4）的 position 必须 >= 2
10. 日程操作有频率限制：单个管理员每天 10 次，单个频道每天 100 次
11. 头像/图标展示：成员 user.avatar 和频道 icon 等图片 URL 必须使用 Markdown 图片语法 ![描述](URL) 展示，禁止作为纯文本或超链接展示