@karinjs/adapter-qqbot 3.0.7 → 3.1.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { AdapterBase, AdapterType, Contact, CreateGroupFolderResponse, DownloadFileOptions, DownloadFileResponse, ElementTypes, ForwardOptions, GetAiCharactersResponse, GetAtAllCountResponse, GetGroupFileListResponse, GetGroupFileSystemInfoResponse, GetGroupHighlightsResponse, GetGroupMuteListResponse, GetRkeyResponse, GroupInfo, GroupMemberInfo, LogMethodNames, Message, MessageResponse, NodeElement, QQGroupHonorInfo, SendMsgResults, Sender, UserInfo, karinToQQBot } from "node-karin";
+import { AxiosRequestConfig, AxiosResponse } from "node-karin/axios";
 import FormData from "form-data";
 //#region src/core/api/types.d.ts
 /** 上传富媒体文件场景 */
@@ -329,6 +330,497 @@ interface UploadMediaResponse {
   /** 发送消息的唯一ID，当srv_send_msg设置为true时返回 */
   id: string;
 }
+/** 自定义菜单按钮类型 */
+type MenuItemType = 'switch' | 'send_message' | 'link' | 'menu';
+/** 自定义菜单开关配置（仅 type=switch 时有效） */
+interface MenuSwitch {
+  /**
+   * 开关唯一标识
+   *
+   * 用户切换开关状态后会发送一条消息，消息 `ext` 字段中携带 `{switch_id}=1`；
+   * 关闭后不携带该标识。
+   */
+  switch_id?: string;
+  /** 开关的初始状态，true 默认打开 */
+  default?: boolean;
+}
+/** 自定义菜单二级菜单项（不支持再嵌套子菜单） */
+interface SubMenuItem {
+  /** 按钮名称，最多 14 个字符（约 7 个中文汉字） */
+  name?: string;
+  /** 按钮类型，二级菜单仅支持 send_message / link */
+  type?: Extract<MenuItemType, 'send_message' | 'link'>;
+  /** 发送的内容，仅 type=send_message 时有效，用户点击后自动填入输入框 */
+  send_message?: string;
+  /** 跳转链接，仅 type=link 时有效，必须以 https:// 开头 */
+  link?: string;
+}
+/** 自定义菜单一级菜单项 */
+interface MenuItem {
+  /** 按钮名称，最多 10 个字符（一个中文汉字算 2 个字符） */
+  name?: string;
+  /** 按钮类型 */
+  type?: MenuItemType;
+  /** 子菜单列表，仅 type=menu 时有效，最多 5 个 */
+  sub_menu_items?: SubMenuItem[];
+  /** 发送的内容，仅 type=send_message 时有效，用户点击后自动填入输入框 */
+  send_message?: string;
+  /** 跳转链接，仅 type=link 时有效，必须以 https:// 开头 */
+  link?: string;
+  /** 开关配置，仅 type=switch 时有效 */
+  switch?: MenuSwitch;
+}
+/** 自定义菜单配置 */
+interface Menu {
+  /** 菜单项列表，最多 10 个，按列表顺序从左到右展示 */
+  items?: MenuItem[];
+}
+/** 查询全局自定义菜单响应（GET /v2/menu） */
+interface GetMenuResponse {
+  /** 当前菜单的版本号 */
+  version: number;
+  /** 当前生效的菜单配置；未设置过菜单时该字段为空 */
+  menu?: Menu;
+}
+/** 修改全局自定义菜单响应（PUT /v2/menu） */
+interface UpdateMenuResponse {
+  /** 本次修改后的菜单版本号，可用于后续判断配置是否有变更 */
+  version: number;
+}
+/** 指令面板生效场景：c2c 单聊 / group 群聊 / channel 文字子频道 / dm 频道私信 */
+type PanelScope = 'c2c' | 'group' | 'channel' | 'dm';
+/** 指令面板作用范围：all 全局生效 / specific 指定用户或群生效 */
+type PanelTargetType = 'all' | 'specific';
+/** 指令面板元素类型 */
+type PanelItemType = 'command' | 'link';
+/** 指令面板元素 */
+interface PanelItem {
+  /**
+   * 元素名称，最多 14 个字符（约 7 个中文汉字）
+   *
+   * type=command 时用户点击后该内容会填入聊天输入框；type=link 时仅用于面板展示。
+   */
+  name?: string;
+  /** 元素描述，最多 30 个字符（约 15 个中文汉字），在面板中展示给用户 */
+  desc?: string;
+  /** 元素类型 */
+  type?: PanelItemType;
+  /** 是否仅管理员可操作，true 时仅频道/群管理员可点击 */
+  only_admin?: boolean;
+  /** 跳转链接，仅 type=link 时有效，必须以 https:// 开头 */
+  link?: string;
+}
+/** 指令面板配置内容 */
+interface Panel {
+  /** 面板元素列表，一个面板最多配置 20 个元素 */
+  items?: PanelItem[];
+  /** 面板备注，最多 255 个字符，不对用户展示 */
+  remark?: string;
+  /** 当前版本号 */
+  version?: number;
+}
+/** 查询指令面板列表查询参数（GET /v2/panels） */
+interface GetPanelListParams {
+  /** 生效场景，必填 */
+  scope: PanelScope;
+  /** 分页游标，首次请求不传或传空串，后续传上次响应的 next_cursor */
+  cursor?: string;
+  /** 每页拉取条数，默认 20，最大 50 */
+  limit?: number;
+}
+/** 指令面板记录 */
+interface PanelRecord {
+  /** 面板 ID */
+  panel_id: string;
+  /** 生效场景 */
+  scope: PanelScope;
+  /** 作用范围，仅 c2c/group 场景可能为 specific */
+  target_type: PanelTargetType;
+  /** 面板配置内容 */
+  panel: Panel;
+  /** 面板创建时间，RFC3339 格式 */
+  created_at?: string;
+  /** 面板更新时间，RFC3339 格式 */
+  updated_at?: string;
+  /** 面板版本号 */
+  version: number;
+}
+/** 查询指令面板列表响应（GET /v2/panels） */
+interface GetPanelListResponse {
+  /** 面板记录列表，按设置时间倒序排列 */
+  records: PanelRecord[];
+  /** 下一页游标，空串表示已到最后一页 */
+  next_cursor: string;
+  /** 是否已拉取到最后一页 */
+  is_end: boolean;
+}
+/** 创建指令面板请求体（POST /v2/panels） */
+interface CreatePanelRequest {
+  /** 生效场景，channel / dm 场景 target_type 只能为 all */
+  scope: PanelScope;
+  /** 作用范围，仅 c2c / group 场景支持 specific */
+  target_type?: PanelTargetType;
+  /** 用户 openid 列表，仅 c2c 场景且 target_type=specific 时有效，一次最多 20 个 */
+  user_openids?: string[];
+  /** 群 openid 列表，仅 group 场景且 target_type=specific 时有效，一次最多 20 个 */
+  group_openids?: string[];
+  /** 面板配置内容 */
+  panel: Panel;
+}
+/** 创建指令面板响应（POST /v2/panels） */
+interface CreatePanelResponse {
+  /** 新创建的面板 ID，后续修改、删除、查询详情均需使用此 ID */
+  panel_id: string;
+}
+/** 查询指令面板详情响应（GET /v2/panels/{panel_id}） */
+interface GetPanelResponse extends PanelRecord {
+  /** 关联的用户 openid 列表，仅 c2c 场景且 target_type=specific 时返回，最多 1000 条 */
+  user_openids?: string[];
+  /** 关联的群 openid 列表，仅 group 场景且 target_type=specific 时返回，最多 1000 条 */
+  group_openids?: string[];
+}
+/** 修改指令面板响应（PUT /v2/panels/{panel_id}） */
+interface UpdatePanelResponse {
+  /** 本次修改后的面板版本号 */
+  version: number;
+}
+/** 修改指令面板关联对象请求体（PUT /v2/panels/{panel_id}/target） */
+interface UpdatePanelTargetRequest {
+  /** 操作类型：add 添加关联对象 / del 移除关联对象 */
+  op: 'add' | 'del';
+  /** 用户 openid 列表，仅 c2c 场景有效，一次最多 20 个 */
+  user_openids?: string[];
+  /** 群 openid 列表，仅 group 场景有效，一次最多 20 个 */
+  group_openids?: string[];
+}
+/** 频道信息 */
+interface GuildInfo {
+  /** 频道 ID */
+  id: string;
+  /** 频道名称 */
+  name: string;
+  /** 频道头像 URL */
+  icon?: string;
+  /** 频道创建者 ID */
+  owner_id?: string;
+  /** 当前机器人是否为频道创建者 */
+  owner?: boolean;
+  /** 加入时间，ISO8601 格式 */
+  joined_at?: string;
+  /** 频道成员数 */
+  member_count?: number;
+  /** 频道成员上限 */
+  max_members?: number;
+  /** 频道简介 */
+  description?: string;
+}
+/** 获取机器人加入的频道列表查询参数（GET /users/@me/guilds） */
+interface GetGuildListParams {
+  /** 读取此 guild_id 之前的数据，设置时先反序再分页 */
+  before?: string;
+  /** 读取此 guild_id 之后的数据，与 before 同时设置时 after 无效 */
+  after?: string;
+  /** 每次拉取条数，默认 100，最大 100 */
+  limit?: number;
+}
+/** 子频道类型：0=文字，2=语音，4=分组，10005=直播，10006=应用，10007=论坛 */
+type ChannelType = 0 | 2 | 4 | 10005 | 10006 | 10007;
+/** 文字子频道子类型：0=闲聊，1=公告，2=攻略，3=开黑 */
+type ChannelSubType = 0 | 1 | 2 | 3;
+/** 子频道私密类型：0=公开，1=群主管理员可见，2=群主管理员+指定成员 */
+type ChannelPrivateType = 0 | 1 | 2;
+/** 子频道发言权限：0=无效，1=所有人，2=群主管理员+指定成员 */
+type ChannelSpeakPermission = 0 | 1 | 2;
+/** 子频道信息 */
+interface ChannelInfo {
+  /** 子频道 ID */
+  id: string;
+  /** 所属频道 ID */
+  guild_id: string;
+  /** 子频道名 */
+  name: string;
+  /** 子频道类型 */
+  type: ChannelType;
+  /** 子频道子类型（文字子频道） */
+  sub_type?: ChannelSubType;
+  /** 排序值，从 1 开始 */
+  position?: number;
+  /** 所属分组 ID（仅子频道有效） */
+  parent_id?: string;
+  /** 创建人 ID */
+  owner_id?: string;
+  /** 子频道私密类型 */
+  private_type?: ChannelPrivateType;
+  /** 子频道发言权限 */
+  speak_permission?: ChannelSpeakPermission;
+  /** 应用子频道标识 */
+  application_id?: string;
+  /** 用户拥有的子频道权限 */
+  permissions?: string;
+}
+/** 创建子频道请求体（POST /guilds/{guild_id}/channels） */
+interface CreateChannelRequest {
+  /** 子频道名称 */
+  name?: string;
+  /** 子频道类型 */
+  type?: ChannelType;
+  /** 子频道子类型 */
+  sub_type?: ChannelSubType;
+  /** 排序值（分组类型必须 >= 2） */
+  position?: number;
+  /** 所属分组 ID */
+  parent_id?: string;
+  /** 私密类型 */
+  private_type?: ChannelPrivateType;
+  /** 私密成员 ID 列表 */
+  private_user_ids?: string[];
+  /** 发言权限 */
+  speak_permission?: ChannelSpeakPermission;
+  /** 应用子频道 AppID */
+  application_id?: string;
+}
+/** 修改子频道请求体（PATCH /channels/{channel_id}），只需传入要修改的字段 */
+interface UpdateChannelRequest {
+  /** 子频道名 */
+  name?: string;
+  /** 排序 */
+  position?: number;
+  /** 分组 ID */
+  parent_id?: string;
+  /** 私密类型 */
+  private_type?: ChannelPrivateType;
+  /** 发言权限 */
+  speak_permission?: ChannelSpeakPermission;
+}
+/** 生成分享链接请求体（POST /v2/generate_url_link） */
+interface GenerateUrlLinkRequest {
+  /** 需要跳转的 URL */
+  url_link?: string;
+  /**
+   * 开发者自定义回调数据，最长 32 字符
+   *
+   * 用户通过该链接添加机器人时会透传回 `FRIEND_ADD` 事件的 `scene_param`。
+   */
+  callback_data?: string;
+}
+/** 生成分享链接响应（POST /v2/generate_url_link） */
+interface GenerateUrlLinkResponse {
+  /** 生成的分享链接 */
+  url_link: string;
+}
+/** 全员禁言模式：none 未开启 / always 始终禁言 / schedule 定时或周期性禁言 */
+type GroupMuteMode = 'none' | 'always' | 'schedule';
+/** 定时禁言规则 */
+interface MuteScheduleRule {
+  /** 任务 ID */
+  task_id: string;
+  /** 禁言开始时间（RFC3339 格式） */
+  start_at: string;
+  /** 禁言结束时间（RFC3339 格式） */
+  end_at: string;
+  /** 此规则是否启用 */
+  enabled: boolean;
+}
+/** 周期禁言规则 */
+interface MuteRecurringRule {
+  /** 任务 ID */
+  task_id: string;
+  /** 生效星期几列表，取值 1~7（1=周一，7=周日） */
+  weekdays: number[];
+  /** 时段开始时间，格式 HH:mm（北京时间） */
+  start_time: string;
+  /** 时段结束时间，格式 HH:mm（北京时间）；小于 start_time 表示跨天到次日 */
+  end_time: string;
+  /** 此规则是否启用 */
+  enabled: boolean;
+}
+/** 群级禁言规则（全员禁言配置） */
+interface GlobalMuteRule {
+  /** 全员禁言模式 */
+  mode: GroupMuteMode;
+  /** 定时禁言规则列表 */
+  schedule_rules?: MuteScheduleRule[];
+  /** 周期禁言规则列表 */
+  recurring_rules?: MuteRecurringRule[];
+}
+/** 成员禁言状态 */
+interface MemberMuteState {
+  /** 被禁言成员的 openid */
+  member_openid: string;
+  /** 禁言到期时间（RFC3339 格式） */
+  mute_expire_at: string;
+  /** 被禁言成员的昵称 */
+  username?: string;
+  /** 用户在应用/开放平台下的统一标识 */
+  union_openid?: string;
+}
+/** 查询群禁言状态响应（GET /v2/groups/{group_openid}/restrict_chat_setting） */
+interface GetGroupMuteSettingResponse {
+  /** 群级禁言规则 */
+  global_rule?: GlobalMuteRule;
+  /** 当前处于禁言中的用户列表（不含已过期） */
+  members?: MemberMuteState[];
+}
+/** 入群验证方式 */
+interface JoinRequestVerifyInfo {
+  /** 入群验证方式 */
+  method: 'verify_message' | 'admin_review_qa';
+  /** 验证消息内容，仅 method=verify_message 时可能携带 */
+  verify_message?: string;
+  /** 问答列表，仅 method=admin_review_qa 时可能携带 */
+  review_qa_list?: {
+    /** 管理员设置的问题 */
+    question: string;
+    /** 申请人填写的答案 */
+    answer: string;
+  }[];
+}
+/** 入群申请 */
+interface JoinRequest {
+  /** 申请 ID，需要在审批接口回传 */
+  join_request_id: string;
+  /** 安全提示语 */
+  risk_tips?: string;
+  /** 用户在应用/开放平台下的统一标识 */
+  union_openid?: string;
+  /** 申请人 openid */
+  member_openid: string;
+  /** 申请人昵称 */
+  username?: string;
+  /** 申请时间戳（RFC3339 格式） */
+  apply_at?: string;
+  /** 申请来源：self_apply 主动申请，invited 被邀请 */
+  apply_source?: 'self_apply' | 'invited';
+  /** 邀请人 openid（apply_source=invited 时有效） */
+  invited_by?: string;
+  /** 是否为机器人账号 */
+  bot?: boolean;
+  /** 用户入群验证方式 */
+  verify_info?: JoinRequestVerifyInfo;
+}
+/** 入群申请列表查询参数（GET /v2/groups/{group_openid}/join_request_list） */
+interface GetJoinRequestListParams {
+  /** 分页游标，首次请求可不传或传空串 */
+  cursor?: string;
+  /** 单页数量，默认 20，最大 100 */
+  limit?: number;
+}
+/** 入群申请列表响应（GET /v2/groups/{group_openid}/join_request_list） */
+interface GetJoinRequestListResponse {
+  /** 入群申请列表 */
+  list: JoinRequest[];
+  /** 下一页游标，空串表示已到末页 */
+  next_cursor: string;
+}
+/** 入群申请审批请求体（POST /v2/groups/{group_openid}/approval_join_request/{member_openid}） */
+interface ApprovalJoinRequestBody {
+  /** 审批动作：approve 通过，decline 拒绝 */
+  op: 'approve' | 'decline';
+  /** 申请 ID */
+  join_request_id?: string;
+  /** 拒绝理由，op=decline 时可填 */
+  reject_reason?: string;
+  /** 是否同时加入群黑名单，默认 false，op=decline 时可填 */
+  add_to_member_blacklist?: boolean;
+}
+/** 入群自动审批策略 */
+interface JoinApprovalStrategy {
+  /** 策略 ID */
+  strategy_id: string;
+  /** 关联的群 openid 列表（创建时使用 group_openids 时返回） */
+  group_openids?: string[];
+  /** 关联的 QQ 群号列表（创建时使用 group_ids 时返回） */
+  group_ids?: string[];
+  /** 白名单中的号码数量（估算，可能存在少量误差） */
+  whitelist_user_count?: number;
+  /** 策略是否启用：on 启用 / off 关闭 */
+  is_enable: 'on' | 'off';
+  /** 过期时间（RFC3339 格式） */
+  expire_at?: string;
+  /** 创建时间（RFC3339 格式） */
+  created_at?: string;
+  /** 最近更新时间（RFC3339 格式） */
+  updated_at?: string;
+  /** 策略备注 */
+  remark?: string;
+}
+/** 查询入群自动审批策略列表查询参数（GET /v2/groups/join_approval_strategy） */
+interface GetJoinApprovalStrategyListParams {
+  /** 分页游标，首次请求可不传或传空串 */
+  cursor?: string;
+  /** 单页数量，默认 20，最大 100 */
+  limit?: number;
+}
+/** 查询入群自动审批策略列表响应 */
+interface GetJoinApprovalStrategyListResponse {
+  /** 生效中的策略列表 */
+  strategies: JoinApprovalStrategy[];
+  /** 下一页游标，空串表示已到末页 */
+  next_cursor: string;
+}
+/** 创建入群自动审批策略请求体（POST /v2/groups/join_approval_strategy） */
+interface CreateJoinApprovalStrategyRequest {
+  /** 关联的群 openid 列表，最多 100 个；与 group_ids 互斥且二选一必填 */
+  group_openids?: string[];
+  /** 关联的 QQ 群号列表，最多 100 个；与 group_openids 互斥且二选一必填 */
+  group_ids?: string[];
+  /** 是否启用策略，默认 on */
+  is_enable?: 'on' | 'off';
+  /** 过期时间（RFC3339 格式），不传默认一年过期 */
+  expire_at?: string;
+  /** 策略备注，最多 255 个汉字 */
+  remark?: string;
+}
+/** 创建入群自动审批策略响应 */
+interface CreateJoinApprovalStrategyResponse {
+  /** 服务端生成的策略 ID */
+  strategy_id: string;
+  /** 是否启用 */
+  is_enable: 'on' | 'off';
+  /** 过期时间（RFC3339 格式） */
+  expire_at?: string;
+}
+/** 修改入群自动审批策略请求体（PATCH /v2/groups/join_approval_strategy/{strategy_id}） */
+interface UpdateJoinApprovalStrategyRequest {
+  /** 是否启用策略 */
+  is_enable?: 'on' | 'off';
+  /** 过期时间（RFC3339 格式） */
+  expire_at?: string;
+  /** 关联群增删操作；群标识形式须与创建时一致 */
+  group_action?: {
+    /** 操作类型：add 新增关联群，del 删除关联群 */
+    op: 'add' | 'del';
+    /** 待操作的群 openid 列表；与 group_ids 互斥 */
+    group_openids?: string[];
+    /** 待操作的 QQ 群号列表；与 group_openids 互斥 */
+    group_ids?: string[];
+  };
+  /** 策略备注，最多 255 个汉字 */
+  remark?: string;
+}
+/** 修改入群自动审批策略响应 */
+interface UpdateJoinApprovalStrategyResponse {
+  /** 是否启用 */
+  is_enable: 'on' | 'off';
+  /** 过期时间（RFC3339 格式） */
+  expire_at?: string;
+}
+/** 修改策略白名单号码请求体（POST /v2/groups/join_approval_strategy/{strategy_id}/whitelist_users） */
+interface UpdateWhitelistUsersRequest {
+  /** 操作类型：add 新增号码，del 删除号码 */
+  op: 'add' | 'del';
+  /** QQ 号码列表，单次最多 10000 个；使用字符串类型避免 JS 精度问题 */
+  whitelist_users: string[];
+}
+/** 修改策略白名单号码响应 */
+interface UpdateWhitelistUsersResponse {
+  /** 策略 ID */
+  strategy_id: string;
+  /** 操作后策略当前白名单号码数（估算） */
+  whitelist_user_count: number;
+  /** 策略更新时间（RFC3339 格式） */
+  updated_at?: string;
+}
 //#endregion
 //#region src/core/internal/axios.d.ts
 /**
@@ -338,16 +830,148 @@ declare const createAxiosInstance: (appId: string) => import("node-karin/axios")
 //#endregion
 //#region src/core/api/http.d.ts
 type AxiosInstance = ReturnType<typeof createAxiosInstance>;
+/**
+ * 单次请求的可选配置。
+ *
+ * 这是 axios 请求配置的常用子集；需要完整能力时用
+ * {@link Http.request} 或直接使用 `axios` 实例。
+ */
+interface RequestOptions {
+  /** 追加请求头，会与实例默认头合并 */
+  headers?: Record<string, string>;
+  /** 超时毫秒数，默认取实例配置（5500ms） */
+  timeout?: number;
+  /** query 参数，axios 会自动序列化后拼到 URL */
+  params?: Record<string, unknown>;
+  /** 中断信号 */
+  signal?: AbortSignal;
+  /** 响应类型，下载二进制时可传 `arraybuffer` */
+  responseType?: AxiosRequestConfig['responseType'];
+}
 /**
  * Http 基础类，子模块继承此类共享 axios 实例与错误格式化
+ *
+ * 各请求方法均为 `protected`，只供各领域 API 子类内部使用；
+ * 需要给下游插件开放的裸请求入口见 {@link RequestApi}。
  */
 declare class Http {
   readonly axios: AxiosInstance;
   constructor(axios: AxiosInstance);
-  protected get<T>(path: string): Promise<T>;
-  protected post<T>(path: string, body?: unknown, headers?: Record<string, string>, timeout?: number): Promise<T>;
-  protected put<T>(path: string, body?: unknown, headers?: Record<string, string>, timeout?: number): Promise<T>;
-  protected delete<T>(path: string): Promise<T>;
+  protected get<T>(path: string, options?: RequestOptions): Promise<T>;
+  protected post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+  protected put<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+  protected patch<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+  protected delete<T>(path: string, options?: RequestOptions): Promise<T>;
+  /**
+   * 任意 method 的裸请求，返回响应体。
+   *
+   * @param config axios 请求配置，`url` 相对 `baseURL`。
+   * @returns 响应体 `data`。
+   */
+  protected request<T>(config: AxiosRequestConfig): Promise<T>;
+  /**
+   * 任意 method 的裸请求，返回完整 axios 响应。
+   *
+   * 需要读取响应头或状态码时使用。
+   *
+   * @param config axios 请求配置，`url` 相对 `baseURL`。
+   * @returns 完整 axios 响应。
+   */
+  protected requestRaw<T>(config: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+}
+//#endregion
+//#region src/core/api/request.d.ts
+/**
+ * 裸请求入口，供下游插件直接调用官方 OpenAPI。
+ *
+ * {@link Http} 的请求方法是 `protected`，只供各领域 API 子类内部使用；
+ * 本类把同一套方法以 `public` 暴露出来，用于官方新接口尚未被适配器封装、
+ * 或需要传自定义参数的场景：
+ *
+ * ```ts
+ * const bot = e.bot as AdapterQQBot
+ *
+ * // GET，query 走 params
+ * const menu = await bot.super.request.get('/v2/menu')
+ * const list = await bot.super.request.get('/v2/panels', { params: { scope: 'group', limit: 20 } })
+ *
+ * // POST / PUT / PATCH / DELETE
+ * await bot.super.request.post(`/v2/groups/${groupId}/messages`, { content: 'hi', msg_type: 0 })
+ * await bot.super.request.put('/v2/menu', { menu })
+ *
+ * // 任意 method
+ * await bot.super.request.request({ method: 'POST', url: '/v2/xxx', data: {} })
+ * ```
+ *
+ * 与直接用 `bot.super.axios` 的区别：
+ * - 自动解包 `response.data`；
+ * - 失败时抛出的 Error 已带请求路径、脱敏请求体、QQ 错误码中文描述和 TraceID。
+ *
+ * 需要读响应头或状态码时用 {@link RequestApi.requestRaw}；
+ * 需要完全裸的 axios 时用 `bot.super.axios`。
+ *
+ * 路径相对官方 API baseURL，鉴权头由拦截器自动注入，无需自己传 Authorization。
+ */
+declare class RequestApi extends Http {
+  /**
+   * GET 请求。
+   *
+   * @param path 接口路径，相对 baseURL。
+   * @param options 可选配置（params / headers / timeout 等）。
+   * @returns 响应体。
+   */
+  get<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+  /**
+   * POST 请求。
+   *
+   * @param path 接口路径，相对 baseURL。
+   * @param body 请求体，默认空对象。
+   * @param options 可选配置（params / headers / timeout 等）。
+   * @returns 响应体。
+   */
+  post<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+  /**
+   * PUT 请求。
+   *
+   * @param path 接口路径，相对 baseURL。
+   * @param body 请求体，默认空对象。
+   * @param options 可选配置（params / headers / timeout 等）。
+   * @returns 响应体。
+   */
+  put<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+  /**
+   * PATCH 请求。
+   *
+   * @param path 接口路径，相对 baseURL。
+   * @param body 请求体，默认空对象。
+   * @param options 可选配置（params / headers / timeout 等）。
+   * @returns 响应体。
+   */
+  patch<T = unknown>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+  /**
+   * DELETE 请求。
+   *
+   * @param path 接口路径，相对 baseURL。
+   * @param options 可选配置（params / headers / timeout 等）。
+   * @returns 响应体。
+   */
+  delete<T = unknown>(path: string, options?: RequestOptions): Promise<T>;
+  /**
+   * 任意 method 的请求，返回响应体。
+   *
+   * @param config axios 请求配置，`url` 相对 baseURL。
+   * @returns 响应体。
+   */
+  request<T = unknown>(config: AxiosRequestConfig): Promise<T>;
+  /**
+   * 任意 method 的请求，返回完整 axios 响应。
+   *
+   * 需要读取响应头或状态码时使用。
+   *
+   * @param config axios 请求配置，`url` 相对 baseURL。
+   * @returns 完整 axios 响应。
+   */
+  requestRaw<T = unknown>(config: AxiosRequestConfig): Promise<AxiosResponse<T>>;
 }
 //#endregion
 //#region src/core/api/messages.d.ts
@@ -483,7 +1107,7 @@ declare class InteractionApi extends Http {
 //#endregion
 //#region src/core/api/meta.d.ts
 /**
- * 元信息接口：@me / dms / gateway
+ * 元信息接口：@me / dms / gateway / 分享链接
  */
 declare class MetaApi extends Http {
   /** 当前机器人详情 */
@@ -494,6 +1118,15 @@ declare class MetaApi extends Http {
   getGateway(): Promise<{
     url: string;
   }>;
+  /**
+   * 生成机器人分享链接
+   *
+   * 用于邀请用户添加机器人为好友；`callback_data`（最长 32 字符）会在用户通过该
+   * 链接添加机器人时透传到 `FRIEND_ADD` 事件的 `scene_param`。
+   *
+   * @param body 分享链接参数，均为可选
+   */
+  generateUrlLink(body?: GenerateUrlLinkRequest): Promise<GenerateUrlLinkResponse>;
 }
 //#endregion
 //#region src/core/api/groups.d.ts
@@ -523,12 +1156,249 @@ declare class GroupsApi extends Http {
   getGroupMember(groupOpenid: string, memberOpenid: string): Promise<QQGroupMemberResponse>;
   /**
    * 设置群成员禁言
+   *
+   * 机器人需拥有群管理员身份，平台限制最大禁言时长为 30 天。
+   *
    * @param groupOpenid 群 openid
    * @param memberOpenid 群成员 openid
    * @param op 操作: add 增加禁言，update 更新禁言到期时间，del 解除禁言
    * @param duration 禁言时间使用RFC3339 格式
    */
+  setGroupMute(groupOpenid: string, memberOpenid: string, op: 'add' | 'update' | 'del', duration: string): Promise<{}>;
+  /**
+   * 设置群成员禁言
+   * @deprecated 方法名拼写错误，请使用 {@link GroupsApi.setGroupMute}
+   */
   setGroupMetu(groupOpenid: string, memberOpenid: string, op: 'add' | 'update' | 'del', duration: string): Promise<{}>;
+  /**
+   * 查询群禁言状态
+   *
+   * 返回全员禁言模式（含定时 / 周期规则）与当前禁言中的成员列表（不含已过期）。
+   * 机器人需拥有群管理员身份。
+   *
+   * @param groupOpenid 群 openid
+   */
+  getGroupMuteSetting(groupOpenid: string): Promise<GetGroupMuteSettingResponse>;
+  /**
+   * 拉取入群申请列表
+   *
+   * 机器人需拥有群管理员身份。
+   *
+   * @param groupOpenid 群 openid
+   * @param params 分页参数，`limit` 默认 20、最大 100
+   */
+  getJoinRequestList(groupOpenid: string, params?: GetJoinRequestListParams): Promise<GetJoinRequestListResponse>;
+  /**
+   * 审批入群申请
+   *
+   * 机器人需拥有群管理员身份。
+   *
+   * @param groupOpenid 群 openid
+   * @param memberOpenid 申请人 openid
+   * @param body 审批动作，`op=decline` 时可附带拒绝理由与拉黑标记
+   */
+  approvalJoinRequest(groupOpenid: string, memberOpenid: string, body: ApprovalJoinRequestBody): Promise<{}>;
+}
+//#endregion
+//#region src/core/api/guilds.d.ts
+/**
+ * 频道 / 子频道接口
+ *
+ * 子频道的创建、修改、删除均需要管理员权限且属于私域接口，
+ * 操作成功后会触发 `CHANNEL_CREATE` / `CHANNEL_UPDATE` / `CHANNEL_DELETE` 事件。
+ */
+declare class GuildsApi extends Http {
+  /**
+   * 获取机器人加入的频道列表
+   *
+   * 官方文档响应体标注为 `{ guilds: [] }`，但示例与实际返回均为裸数组；
+   * 这里对两种形态都做兼容。
+   *
+   * @param params 分页参数，`limit` 默认 100、最大 100
+   */
+  getGuildList(params?: GetGuildListParams): Promise<GuildInfo[]>;
+  /**
+   * 获取频道详情
+   * @param guildId 频道 ID
+   */
+  getGuild(guildId: string): Promise<GuildInfo>;
+  /**
+   * 获取子频道列表
+   *
+   * 官方文档响应体标注为 `{ channels: [] }`，但示例与实际返回均为裸数组；
+   * 这里对两种形态都做兼容。
+   *
+   * @param guildId 频道 ID
+   */
+  getChannelList(guildId: string): Promise<ChannelInfo[]>;
+  /**
+   * 创建子频道（需要管理员权限，私域接口）
+   * @param guildId 频道 ID
+   * @param body 子频道配置
+   */
+  createChannel(guildId: string, body: CreateChannelRequest): Promise<ChannelInfo>;
+  /**
+   * 获取子频道详情
+   * @param channelId 子频道 ID
+   */
+  getChannel(channelId: string): Promise<ChannelInfo>;
+  /**
+   * 修改子频道（需要管理员权限，私域接口）
+   *
+   * 只需传入要修改的字段。
+   * @param channelId 子频道 ID
+   * @param body 待修改的字段
+   */
+  updateChannel(channelId: string, body: UpdateChannelRequest): Promise<ChannelInfo>;
+  /**
+   * 删除子频道（需要管理员权限，私域接口）
+   *
+   * 子频道删除后无法恢复。
+   * @param channelId 子频道 ID
+   */
+  deleteChannel(channelId: string): Promise<{}>;
+}
+//#endregion
+//#region src/core/api/menu.d.ts
+/**
+ * 全局自定义菜单接口
+ *
+ * 自定义菜单展示在机器人单聊窗口底部，仅支持 C2C（单聊）场景，
+ * 设置后对所有用户生效，不支持按用户维度区分。
+ *
+ * {@link https://bot.q.qq.com/wiki/develop/api-v2/server-inter/menu-panel/}
+ */
+declare class MenuApi extends Http {
+  /**
+   * 查询全局自定义菜单
+   *
+   * 未设置过菜单时响应的 `menu` 字段为空。
+   * @returns 当前生效的菜单配置与版本号
+   */
+  getMenu(): Promise<GetMenuResponse>;
+  /**
+   * 修改全局自定义菜单
+   *
+   * 传入后会覆盖原有的完整菜单配置；不传 `menu` 表示清空菜单。
+   * @param menu 菜单配置，最多 10 个一级菜单项
+   * @returns 本次修改后的菜单版本号
+   */
+  updateMenu(menu?: Menu): Promise<UpdateMenuResponse>;
+}
+//#endregion
+//#region src/core/api/panels.d.ts
+/**
+ * 指令面板接口
+ *
+ * 指令面板以面板形式展示指令或链接，支持 c2c（单聊）、group（群聊）、
+ * channel（文字子频道）、dm（频道私信）四种场景；其中 c2c / group 支持
+ * 按指定用户或群生效（target_type=specific），channel / dm 仅支持全局配置。
+ *
+ * 一个机器人最多创建 20 个指令面板。
+ *
+ * {@link https://bot.q.qq.com/wiki/develop/api-v2/server-inter/menu-panel/}
+ */
+declare class PanelsApi extends Http {
+  /**
+   * 查询指令面板列表
+   *
+   * 分页拉取指定场景下已生效的面板，按设置时间倒序排列。
+   * @param params 查询参数，`scope` 必填
+   * @returns 面板记录列表与分页游标
+   */
+  getPanelList(params: GetPanelListParams): Promise<GetPanelListResponse>;
+  /**
+   * 创建指令面板
+   * @param body 面板场景、作用范围与配置内容
+   * @returns 新创建的面板 ID
+   */
+  createPanel(body: CreatePanelRequest): Promise<CreatePanelResponse>;
+  /**
+   * 查询指令面板详情
+   *
+   * 返回面板完整配置，target_type=specific 时同时返回关联的用户 / 群 openid 列表。
+   * @param panelId 面板 ID
+   */
+  getPanel(panelId: string): Promise<GetPanelResponse>;
+  /**
+   * 修改指令面板
+   *
+   * 传入后会覆盖原有的面板元素列表和备注，不影响已关联的用户 / 群列表。
+   * @param panelId 面板 ID
+   * @param panel 面板配置内容
+   * @returns 本次修改后的面板版本号
+   */
+  updatePanel(panelId: string, panel: Panel): Promise<UpdatePanelResponse>;
+  /**
+   * 删除指令面板
+   *
+   * 删除后该面板不再对任何用户或群生效。
+   * @param panelId 面板 ID
+   */
+  deletePanel(panelId: string): Promise<{}>;
+  /**
+   * 修改指令面板关联对象
+   *
+   * c2c 场景操作 `user_openids`，group 场景操作 `group_openids`，一次最多 20 个；
+   * channel / dm 场景为全局配置，不支持此操作。
+   * @param panelId 面板 ID
+   * @param body 操作类型与关联对象列表
+   */
+  updatePanelTarget(panelId: string, body: UpdatePanelTargetRequest): Promise<{}>;
+}
+//#endregion
+//#region src/core/api/join-approval.d.ts
+/**
+ * 入群自动审批策略接口
+ *
+ * 策略把「关联群 + 白名单 QQ 号码」绑在一起，命中白名单的入群申请会自动审批通过。
+ * 规则仅在机器人拥有群管理员身份时才会实际运行；一个机器人最多 20 个策略。
+ */
+declare class JoinApprovalApi extends Http {
+  /**
+   * 查询入群自动审批策略列表
+   *
+   * 按创建时间倒序，支持分页。
+   * @param params 分页参数，`limit` 默认 20、最大 100
+   */
+  getStrategyList(params?: GetJoinApprovalStrategyListParams): Promise<GetJoinApprovalStrategyListResponse>;
+  /**
+   * 创建入群自动审批策略
+   *
+   * `group_openids` 与 `group_ids` 二选一必填，同时传入或均未传入都会报错。
+   * @param body 策略配置
+   */
+  createStrategy(body: CreateJoinApprovalStrategyRequest): Promise<CreateJoinApprovalStrategyResponse>;
+  /**
+   * 修改入群自动审批策略
+   *
+   * 可修改生效状态、失效时间、备注，或增删关联群；
+   * 增删关联群时的群标识形式必须与创建时一致。
+   * @param strategyId 策略 ID
+   * @param body 待修改的字段
+   */
+  updateStrategy(strategyId: string, body: UpdateJoinApprovalStrategyRequest): Promise<UpdateJoinApprovalStrategyResponse>;
+  /**
+   * 删除入群自动审批策略
+   * @param strategyId 策略 ID
+   */
+  deleteStrategy(strategyId: string): Promise<{}>;
+  /**
+   * 执行入群自动审批策略
+   *
+   * 对策略关联的全部群发起全量扫描，命中白名单号码的入群申请自动审批通过。
+   * 异步执行，约 10 分钟完成。
+   * @param strategyId 策略 ID
+   */
+  executeStrategy(strategyId: string): Promise<{}>;
+  /**
+   * 修改入群自动审批策略的白名单号码
+   *
+   * 单次最多 10000 个，策略号码上限 10W。
+   * @param strategyId 策略 ID
+   * @param body 操作类型与号码列表
+   */
+  updateWhitelistUsers(strategyId: string, body: UpdateWhitelistUsersRequest): Promise<UpdateWhitelistUsersResponse>;
 }
 //#endregion
 //#region src/core/api/index.d.ts
@@ -539,18 +1409,41 @@ declare class GroupsApi extends Http {
  * - messages：发送 / 撤回
  * - media：富媒体上传
  * - interaction：按钮回调 ack
- * - meta：@me / dms / gateway
- * - groups：群基础信息 / 机器人群内状态（白名单接口）
+ * - meta：@me / dms / gateway / 分享链接
+ * - groups：群基础信息 / 机器人群内状态 / 禁言 / 入群申请（部分为白名单接口）
+ * - guilds：频道与子频道的查询和增删改
+ * - menu：全局自定义菜单（仅单聊）
+ * - panels：指令面板
+ * - joinApproval：入群自动审批策略
+ * - request：裸请求入口，用于调用尚未封装的官方接口
  *
  * 请求体构造器 {@link buildQQMsg} / {@link buildGuildMsg} 独立导出，避免与 HTTP 调用耦合
  */
 declare class QQBotApi {
   readonly axios: AxiosInstance;
+  /**
+   * 裸请求入口，直接调用官方 OpenAPI。
+   *
+   * 官方新接口还没被适配器封装时可用它兜底，会自动带鉴权、解包 `data`、
+   * 格式化错误码：
+   *
+   * ```ts
+   * await bot.super.request.get('/v2/menu')
+   * await bot.super.request.post('/v2/xxx', { foo: 1 })
+   * ```
+   *
+   * @see {@link RequestApi}
+   */
+  readonly request: RequestApi;
   readonly messages: MessagesApi;
   readonly media: MediaApi;
   readonly interaction: InteractionApi;
   readonly meta: MetaApi;
   readonly groups: GroupsApi;
+  readonly guilds: GuildsApi;
+  readonly menu: MenuApi;
+  readonly panels: PanelsApi;
+  readonly joinApproval: JoinApprovalApi;
   /** 请求体构造器（静态便利） */
   readonly qq: {
     text(content: string): SendQQTextMessageRequest;
@@ -1145,6 +2038,13 @@ declare class AdapterQQBot extends AdapterBase implements AdapterType {
   groupKickMember(_groupId: string, _targetId: string, _rejectAddRequest?: boolean, _kickReason?: string): Promise<void>;
   /**
    * 禁言群成员
+   *
+   * 机器人需拥有群管理员身份；平台限制最大禁言时长为 30 天，
+   * 超出部分会被截断到 30 天而不是直接失败。
+   *
+   * @param _groupId 群 openid
+   * @param _targetId 群成员 openid
+   * @param duration 禁言时长（秒），传 0 或负数表示解除禁言
    */
   setGroupMute(_groupId: string, _targetId: string, duration: number): Promise<void>;
   /**
@@ -1182,12 +2082,18 @@ declare class AdapterQQBot extends AdapterBase implements AdapterType {
   /**
    * 获取群信息
    *
-   * 走官方 `GET /v2/groups/{group_openid}/info`（白名单接口）。
-   * 未开通权限（11253）或查询失败时降级为空结构并告警。
+   * QQ 群走官方 `GET /v2/groups/{group_openid}/info`（白名单接口）；传入的是频道
+   * ID 时退回 `GET /guilds/{guild_id}`，这样频道场景下的插件调用也能拿到名称和
+   * 人数。两者都不可用（如白名单未开通返回 11253）时降级为空结构并告警。
+   *
+   * @param _groupId 群 openid 或频道 ID。
    */
   getGroupInfo(_groupId: string, _noCache?: boolean): Promise<GroupInfo>;
   /**
    * 获取群列表
+   *
+   * 官方没有 QQ 群列表接口。频道列表可用 `bot.super.guilds.getGuildList()` 获取，
+   * 但频道在 Karin 里属于 guild 场景，与 QQ 群不是同一类会话，因此不在此处混用。
    */
   getGroupList(_refresh?: boolean): Promise<Array<GroupInfo>>;
   /**
@@ -1212,13 +2118,29 @@ declare class AdapterQQBot extends AdapterBase implements AdapterType {
    */
   setFriendApplyResult(_requestId: string, _isApprove: boolean, _remark?: string): Promise<void>;
   /**
-   * 设置申请加入群请求结果
+   * 审批入群申请。
+   *
+   * 走官方 `POST /v2/groups/{group_openid}/approval_join_request/{member_openid}`，
+   * 机器人需拥有群管理员身份。Karin 只透传 flag（`join_request_id`），群与申请人
+   * openid 由 `join-request-cache` 在收到申请事件时记录，因此仅支持审批本次运行
+   * 期间收到过的申请；历史申请请改用
+   * `bot.super.groups.getJoinRequestList()` + `bot.super.groups.approvalJoinRequest()`。
+   *
+   * @param requestId 申请 ID（Karin 请求事件的 flag）。
+   * @param isApprove 是否通过。
+   * @param denyReason 拒绝理由，仅拒绝时生效。
    */
-  setGroupApplyResult(_requestId: string, _isApprove: boolean, _denyReason?: string): Promise<void>;
+  setGroupApplyResult(requestId: string, isApprove: boolean, denyReason?: string): Promise<void>;
   /**
-   * 设置邀请加入群请求结果
+   * 设置邀请加入群请求结果。
+   *
+   * 机器人被邀请入群与用户主动申请入群在官方侧是同一条 `GROUP_JOIN_REQUEST`
+   * 事件，审批走同一个接口，因此直接复用 {@link AdapterQQBot.setGroupApplyResult}。
+   *
+   * @param requestId 申请 ID（Karin 请求事件的 flag）。
+   * @param isApprove 是否通过。
    */
-  setInvitedJoinGroupResult(_requestId: string, _isApprove: boolean): Promise<void>;
+  setInvitedJoinGroupResult(requestId: string, isApprove: boolean): Promise<void>;
   /**
    * 设置消息表情回应
    */
@@ -1283,6 +2205,15 @@ declare class AdapterQQBot extends AdapterBase implements AdapterType {
   getAtAllCount(_groupId: string): Promise<GetAtAllCountResponse>;
   /**
    * 获取群被禁言用户列表
+   *
+   * 走官方 `GET /v2/groups/{group_openid}/restrict_chat_setting`，只返回仍在
+   * 禁言中的成员（不含已过期）。机器人需拥有群管理员身份，无权限或查询失败时
+   * 降级为空数组并告警。
+   *
+   * `muteTime` 为禁言到期时间的 Unix 秒，而非剩余时长；全员禁言规则不在该返回
+   * 结构内，需要时请用 `bot.super.groups.getGroupMuteSetting()` 读取 `global_rule`。
+   *
+   * @param _groupId 群 openid
    */
   getGroupMuteList(_groupId: string): Promise<Array<GetGroupMuteListResponse>>;
   /**
@@ -1328,4 +2259,4 @@ declare class AdapterQQBot extends AdapterBase implements AdapterType {
   }>;
 }
 //#endregion
-export type { AdapterQQBot };
+export { type AdapterQQBot, type AxiosInstance, Http, QQBotApi, RequestApi, type RequestOptions };