qqbotsdk-guild-py 2.0.0__py3-none-any.whl

qqbotsdk/api/guild/messages.py

@@ -0,0 +1,126 @@
+from qqbotsdk.api.core import session
+from qqbotsdk.model.guild.messages import (
+    CreateDmsRequest,
+    CreateDmsResponse,
+    GetChannelMessagesResponse,
+    GetChannelReactionUsersRequest,
+    GetChannelReactionUsersResponse,
+    SendChannelMessagesRequest,
+    SendChannelMessagesResponse,
+    SendDmsMessagesRequest,
+    SendDmsMessagesResponse,
+)
+
+
+async def send_channel_messages(
+    channel_id: str,
+    payload: SendChannelMessagesRequest,
+) -> SendChannelMessagesResponse:
+    async with session.post(
+        f"/channels/{channel_id}/messages",
+        json=payload.model_dump(exclude_none=True),
+    ) as resp:
+        result = await resp.json()
+
+    return SendChannelMessagesResponse.model_validate(result)
+
+
+async def recall_channel_messages(
+    channel_id: str,
+    message_id: str,
+    hide_tip: bool = False,
+) -> None:
+    async with session.delete(
+        f"/channels/{channel_id}/messages/{message_id}",
+        params={"hidetip": str(hide_tip).lower()},
+    ) as resp:
+        await resp.json()
+
+
+async def get_channel_messages(
+    channel_id: str,
+    message_id: str,
+) -> GetChannelMessagesResponse:
+    async with session.get(
+        f"/channels/{channel_id}/messages/{message_id}",
+    ) as resp:
+        result = await resp.json()
+
+    return GetChannelMessagesResponse.model_validate(result)
+
+
+async def put_channel_reaction(
+    channel_id: str,
+    message_id: str,
+    emoji_type: int,
+    emoji_id: str,
+) -> None:
+    async with session.put(
+        f"/channels/{channel_id}/messages/{message_id}/reactions/{emoji_type}/{emoji_id}",
+    ) as resp:
+        await resp.json()
+
+
+async def delete_channel_reaction(
+    channel_id: str,
+    message_id: str,
+    emoji_type: int,
+    emoji_id: str,
+) -> None:
+    async with session.delete(
+        f"/channels/{channel_id}/messages/{message_id}/reactions/{emoji_type}/{emoji_id}",
+    ) as resp:
+        await resp.json()
+
+
+async def get_channel_reaction_users(
+    channel_id: str,
+    message_id: str,
+    emoji_type: int,
+    emoji_id: str,
+    payload: GetChannelReactionUsersRequest,
+) -> GetChannelReactionUsersResponse:
+    async with session.get(
+        f"/channels/{channel_id}/messages/{message_id}/reactions/{emoji_type}/{emoji_id}",
+        params=payload.model_dump(exclude_none=True),
+    ) as resp:
+        result = await resp.json()
+
+    return GetChannelReactionUsersResponse.model_validate(result)
+
+
+async def create_dms(
+    payload: CreateDmsRequest,
+) -> CreateDmsResponse:
+    async with session.post(
+        "/users/@me/dms",
+        json=payload.model_dump(exclude_none=True),
+    ) as resp:
+        result = await resp.json()
+
+    return CreateDmsResponse.model_validate(result)
+
+
+async def send_dms_messages(
+    guild_id: str,
+    payload: SendDmsMessagesRequest,
+) -> SendDmsMessagesResponse:
+    async with session.post(
+        f"/dms/{guild_id}/messages",
+        json=payload.model_dump(exclude_none=True),
+    ) as resp:
+        result = await resp.json()
+
+    return SendDmsMessagesResponse.model_validate(result)
+
+
+async def recall_dms_messages(
+    guild_id: str,
+    message_id: str,
+    hide_tip: bool = False,
+) -> None:
+    async with session.delete(
+        f"/dms/{guild_id}/messages/{message_id}",
+        params={"hidetip": str(hide_tip).lower()},
+    ) as resp:
+        await resp.json()

qqbotsdk/model/guild/agent.md

@@ -0,0 +1,36 @@
+# agent.md — qqbotsdk/model/guild（频道域模型与事件）
+
+适用范围：`packages/qqbotsdk-guild/src/qqbotsdk/model/guild/**`（`channel.py`、`guild.py`、`member.py`、`messages.py`、`content.py`，以及 `event.py`、`event_message.py`、`event_member.py`、`event_forum.py`、`event_audio.py`）。
+
+## MUST（必须做）
+
+- MUST 优先复用已有对象模型（`Guild`、`Channel`、`Member`、`User`、`Role`、`MessageEmbed`、`MessageArk`、`MessageAuthor`），事件体里出现这些对象时直接引用，不要复制字段。
+- MUST 对**需要容错**的字段保持 `int`/`str`：`Channel.type` / `sub_type` / `private_type` / `speak_permission`，以及事件里的 `channel_type`（文档 `2=音视频`、`5=直播` 与 `10005` 两处冲突）。在 `description` 里列出取值，不要用 `Literal` 关死。
+- MUST 对封闭枚举用 `Literal`：`announces_type`（0/1）、`AudioControlRequest.status`（0-3）、`PutChannelThreadRequest.format`（1-4）、`RemoveGuildMemberRequest.delete_history_msg_days`（-1/0/3/7/15/30）。
+- MUST 在事件模型里只建模事件体 `d`，并维护 `EVENT_MODELS` + `parse_event(payload)`（契约见 `qqbotsdk/src/qqbotsdk/model/event/agent.md`）；新增事件必须同时更新注册表与 `__all__`。
+- MUST 用 `BeforeValidator` 之类把示例里的**整型 ID 归一化为字符串**（`guild_id`/`channel_id`/`author_id`/`emoji_info.id` 等），保证文档示例与真实报文都能解析。
+- MUST 给分页参数加边界：`limit` 的 `le=100`（频道列表）/`le=400`（成员与身份组成员）。
+
+## SHOULD（应当做）
+
+- SHOULD 让响应模型的字段默认可选；频道文档的「返回包」示例比字段表更全时，以示例为准补充可选字段（如 `tts`/`pinned`/`type`/`flags`）。
+- SHOULD 用 `EventMessage` 这类继承自响应模型的子类承载事件专有字段（`member`、`mentions`、`seq`），而不是把事件字段塞回响应模型。
+- SHOULD 让论坛富文本按 `RichObject` 数组建模（`EventThreadInfo` 等）；表格里写 `string` 而示例是数组时，以示例为准并在说明里注明。
+
+## MUST NOT（禁止做）
+
+- MUST NOT 加回子频道公告相关模型（官方已废弃）。
+- MUST NOT 用 `Literal` 收窄 `Channel.type` 这类需要向前兼容的字段。
+- MUST NOT 让事件模型继承字段类型不兼容的父类（pyright strict 会报 `reportIncompatibleVariableOverride`）；需要覆盖时新建独立模型。
+- MUST NOT 在事件模型里放业务逻辑或发消息。
+- MUST NOT 在 `EventMessage` 之外重复定义消息/用户/成员结构。
+
+## 自检
+
+```powershell
+cd D:\QQBotSDK
+.venv\Scripts\ruff.exe check packages\qqbotsdk-guild\src\qqbotsdk\model
+.venv\Scripts\pyright.exe
+```
+
+事件回归：每个事件文档页的示例 `d` 先直接 `model_validate`，再包成整帧走 `GatewayPayload` → `parse_event`，两路都断言字段值；并断言 `EVENT_MODELS` 与官方 intents 清单一致（当前 40 个）。

qqbotsdk/model/guild/channel.py

@@ -0,0 +1,177 @@
+from pydantic import Field, RootModel
+
+from qqbotsdk.model.core import QQBotBaseModel, QQBotRequestModel
+
+
+class Channel(QQBotBaseModel):
+    id: str = Field(
+        ...,
+        description="子频道 ID",
+    )
+    guild_id: str | None = Field(
+        default=None,
+        description="所属频道 ID",
+    )
+    name: str | None = Field(
+        default=None,
+        description="子频道名",
+    )
+    type: int | None = Field(
+        default=None,
+        description="子频道类型：0=文字，2=语音，4=分组，10005=直播，10006=应用，10007=论坛",
+    )
+    sub_type: int | None = Field(
+        default=None,
+        description="子频道子类型：0=闲聊，1=公告，2=攻略，3=开黑",
+    )
+    position: int | None = Field(
+        default=None,
+        description="排序值，从 1 开始",
+    )
+    parent_id: str | None = Field(
+        default=None,
+        description="所属分组 ID，仅对子频道有效，对子频道分组（type=4）无效",
+    )
+    owner_id: str | None = Field(
+        default=None,
+        description="创建人 ID",
+    )
+    private_type: int | None = Field(
+        default=None,
+        description="私密类型：0=公开，1=群主管理员可见，2=群主管理员+指定成员",
+    )
+    speak_permission: int | None = Field(
+        default=None,
+        description="发言权限：0=无效，1=所有人，2=群主管理员+指定成员",
+    )
+    application_id: str | None = Field(
+        default=None,
+        description="应用子频道标识",
+    )
+    permissions: str | None = Field(
+        default=None,
+        description="用户拥有的子频道权限位图",
+    )
+
+
+class GetChannelResponse(Channel):
+    pass
+
+
+class GetGuildChannelsResponse(RootModel[list[Channel]]):
+    pass
+
+
+class CreateChannelRequest(QQBotRequestModel):
+    name: str | None = Field(
+        default=None,
+        description="子频道名称",
+    )
+    type: int | None = Field(
+        default=None,
+        description="子频道类型：0=文字，2=语音，4=分组，10005=直播，10006=应用，10007=论坛",
+    )
+    sub_type: int | None = Field(
+        default=None,
+        description="子频道子类型：0=闲聊，1=公告，2=攻略，3=开黑",
+    )
+    position: int | None = Field(
+        default=None,
+        description="排序值；分组类型（type=4）必须 >= 2",
+    )
+    parent_id: str | None = Field(
+        default=None,
+        description="所属分组 ID",
+    )
+    private_type: int | None = Field(
+        default=None,
+        description="私密类型：0=公开，1=群主管理员可见，2=群主管理员+指定成员",
+    )
+    private_user_ids: list[str] | None = Field(
+        default=None,
+        description="私密成员 ID 列表",
+    )
+    speak_permission: int | None = Field(
+        default=None,
+        description="发言权限：0=无效，1=所有人，2=群主管理员+指定成员",
+    )
+    application_id: str | None = Field(
+        default=None,
+        description="应用子频道 AppID，仅应用子频道需要",
+    )
+
+
+class CreateChannelResponse(Channel):
+    pass
+
+
+class UpdateChannelRequest(QQBotRequestModel):
+    name: str | None = Field(
+        default=None,
+        description="子频道名",
+    )
+    position: int | None = Field(
+        default=None,
+        description="排序值",
+    )
+    parent_id: str | None = Field(
+        default=None,
+        description="所属分组 ID",
+    )
+    private_type: int | None = Field(
+        default=None,
+        description="私密类型：0=公开，1=群主管理员可见，2=群主管理员+指定成员",
+    )
+    speak_permission: int | None = Field(
+        default=None,
+        description="发言权限：0=无效，1=所有人，2=群主管理员+指定成员",
+    )
+
+
+class UpdateChannelResponse(Channel):
+    pass
+
+
+class GetChannelOnlineNumsResponse(QQBotBaseModel):
+    online_nums: int | None = Field(
+        default=None,
+        description="子频道在线成员数",
+    )
+
+
+class ChannelPermissions(QQBotBaseModel):
+    channel_id: str | None = Field(
+        default=None,
+        description="子频道 ID",
+    )
+    user_id: str | None = Field(
+        default=None,
+        description="用户 ID",
+    )
+    role_id: str | None = Field(
+        default=None,
+        description="身份组 ID",
+    )
+    permissions: str | None = Field(
+        default=None,
+        description="字符串形式的权限位图",
+    )
+
+
+class GetChannelPermissionsResponse(ChannelPermissions):
+    pass
+
+
+class GetChannelRolePermissionsResponse(ChannelPermissions):
+    pass
+
+
+class UpdateChannelPermissionsRequest(QQBotRequestModel):
+    add: str | None = Field(
+        default=None,
+        description="字符串形式的位图，表示赋予的权限",
+    )
+    remove: str | None = Field(
+        default=None,
+        description="字符串形式的位图，表示删除的权限",
+    )

qqbotsdk/model/guild/content.py

@@ -0,0 +1,285 @@
+from typing import Literal
+
+from pydantic import Field, RootModel
+
+from qqbotsdk.model.core import QQBotBaseModel, QQBotRequestModel
+from qqbotsdk.model.guild.member import Member
+
+
+class RecommendChannel(QQBotBaseModel):
+    channel_id: str | None = Field(
+        default=None,
+        description="推荐子频道 ID",
+    )
+    introduce: str | None = Field(
+        default=None,
+        description="推荐语",
+    )
+
+
+class CreateGuildAnnounceRequest(QQBotRequestModel):
+    channel_id: str | None = Field(
+        default=None,
+        description="子频道 ID，message_id 有值时必填",
+    )
+    message_id: str | None = Field(
+        default=None,
+        description="消息 ID，有值时创建消息类型的成员公告",
+    )
+    announces_type: Literal[0, 1] | None = Field(
+        default=None,
+        description="公告类别：0=成员公告，1=欢迎公告",
+    )
+    recommend_channels: list[RecommendChannel] | None = Field(
+        default=None,
+        description="推荐子频道列表，会一次全部替换；与消息类型公告互斥",
+    )
+
+
+class Announce(QQBotBaseModel):
+    guild_id: str | None = Field(
+        default=None,
+        description="频道 ID",
+    )
+    channel_id: str | None = Field(
+        default=None,
+        description="子频道 ID",
+    )
+    message_id: str | None = Field(
+        default=None,
+        description="消息 ID",
+    )
+    announces_type: int | None = Field(
+        default=None,
+        description="公告类别：0=成员公告，1=欢迎公告",
+    )
+    recommend_channels: list[RecommendChannel] | None = Field(
+        default=None,
+        description="推荐子频道列表",
+    )
+
+
+class CreateGuildAnnounceResponse(Announce):
+    pass
+
+
+class PinsMessage(QQBotBaseModel):
+    guild_id: str | None = Field(
+        default=None,
+        description="频道 ID",
+    )
+    channel_id: str | None = Field(
+        default=None,
+        description="子频道 ID",
+    )
+    message_ids: list[str] | None = Field(
+        default=None,
+        description="当前子频道内所有精华消息 ID",
+    )
+
+
+class GetChannelPinsResponse(PinsMessage):
+    pass
+
+
+class ScheduleInfo(QQBotBaseModel):
+    name: str | None = Field(
+        default=None,
+        description="日程名称",
+    )
+    description: str | None = Field(
+        default=None,
+        description="日程描述",
+    )
+    start_timestamp: str | None = Field(
+        default=None,
+        description="开始时间，毫秒级时间戳字符串",
+    )
+    end_timestamp: str | None = Field(
+        default=None,
+        description="结束时间，毫秒级时间戳字符串",
+    )
+    jump_channel_id: str | None = Field(
+        default=None,
+        description="跳转子频道 ID",
+    )
+    remind_type: str | None = Field(
+        default=None,
+        description="提醒类型：0=不提醒，1=开始时提醒，2=开始前 5 分钟提醒，3=开始前 15 分钟提醒，4=开始前 30 分钟提醒，5=开始前 60 分钟提醒",
+    )
+
+
+class CreateChannelScheduleRequest(QQBotRequestModel):
+    schedule: ScheduleInfo = Field(
+        ...,
+        description="日程对象，不需要带 id",
+    )
+
+
+class UpdateChannelScheduleRequest(QQBotRequestModel):
+    schedule: ScheduleInfo = Field(
+        ...,
+        description="日程对象，不需要带 id",
+    )
+
+
+class Schedule(QQBotBaseModel):
+    id: str | None = Field(
+        default=None,
+        description="日程 ID",
+    )
+    name: str | None = Field(
+        default=None,
+        description="日程名称",
+    )
+    description: str | None = Field(
+        default=None,
+        description="日程描述",
+    )
+    start_timestamp: str | None = Field(
+        default=None,
+        description="开始时间，毫秒级时间戳字符串",
+    )
+    end_timestamp: str | None = Field(
+        default=None,
+        description="结束时间，毫秒级时间戳字符串",
+    )
+    creator: Member | None = Field(
+        default=None,
+        description="创建者 member 信息",
+    )
+    jump_channel_id: str | None = Field(
+        default=None,
+        description="跳转子频道 ID",
+    )
+    remind_type: str | None = Field(
+        default=None,
+        description="提醒类型：0=不提醒，1=开始时提醒，2=开始前 5 分钟提醒，3=开始前 15 分钟提醒，4=开始前 30 分钟提醒，5=开始前 60 分钟提醒",
+    )
+
+
+class CreateChannelScheduleResponse(Schedule):
+    pass
+
+
+class UpdateChannelScheduleResponse(Schedule):
+    pass
+
+
+class GetChannelScheduleResponse(Schedule):
+    pass
+
+
+class GetChannelSchedulesRequest(QQBotRequestModel):
+    since: int | None = Field(
+        default=None,
+        description="起始时间戳（毫秒）；不传返回当天日程",
+    )
+
+
+class GetChannelSchedulesResponse(RootModel[list[Schedule]]):
+    pass
+
+
+class AudioControlRequest(QQBotRequestModel):
+    audio_url: str | None = Field(
+        default=None,
+        description="音频数据 URL，status=0 时传",
+    )
+    text: str | None = Field(
+        default=None,
+        description="状态文本，status=0 时传",
+    )
+    status: Literal[0, 1, 2, 3] = Field(
+        ...,
+        description="播放状态：0=开始，1=暂停，2=继续，3=停止",
+    )
+
+
+class ForumThreadInfo(QQBotBaseModel):
+    thread_id: str | None = Field(
+        default=None,
+        description="主帖 ID",
+    )
+    title: str | None = Field(
+        default=None,
+        description="帖子标题",
+    )
+    content: str | None = Field(
+        default=None,
+        description="帖子内容；format=4 时为 RichText 的 JSON 字符串",
+    )
+    date_time: str | None = Field(
+        default=None,
+        description="发表时间，ISO8601 格式",
+    )
+
+
+class ForumThread(QQBotBaseModel):
+    guild_id: str | None = Field(
+        default=None,
+        description="频道 ID",
+    )
+    channel_id: str | None = Field(
+        default=None,
+        description="子频道 ID",
+    )
+    author_id: str | None = Field(
+        default=None,
+        description="作者 ID",
+    )
+    thread_info: ForumThreadInfo | None = Field(
+        default=None,
+        description="主帖内容",
+    )
+
+
+class GetChannelThreadResponse(QQBotBaseModel):
+    thread: ForumThread | None = Field(
+        default=None,
+        description="帖子详情对象",
+    )
+
+
+class GetChannelThreadsResponse(QQBotBaseModel):
+    threads: list[ForumThread] | None = Field(
+        default=None,
+        description="帖子列表",
+    )
+    is_finish: int | None = Field(
+        default=None,
+        description="是否拉取完毕：0=否，1=是",
+    )
+
+
+class PutChannelThreadRequest(QQBotRequestModel):
+    title: str = Field(
+        ...,
+        description="帖子标题",
+    )
+    content: str = Field(
+        ...,
+        description="帖子内容；format=4 时参照 RichText 结构",
+    )
+    format: Literal[1, 2, 3, 4] = Field(
+        ...,
+        description="内容格式：1=纯文本，2=HTML，3=Markdown，4=RichText JSON",
+    )
+
+
+class ForumTaskResponse(QQBotBaseModel):
+    task_id: str | None = Field(
+        default=None,
+        description="异步任务 ID，结果经 FORUM_* 事件推送",
+    )
+
+
+class PutChannelThreadResponse(ForumTaskResponse):
+    create_time: str | None = Field(
+        default=None,
+        description="发帖时间戳，单位：秒",
+    )
+
+
+class DeleteChannelThreadResponse(ForumTaskResponse):
+    pass