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

qqbotsdk/api/guild/agent.md

@@ -0,0 +1,33 @@
+# agent.md — qqbotsdk/api/guild（频道域接口）
+
+适用范围：`packages/qqbotsdk-guild/src/qqbotsdk/api/guild/**`（`channel.py`、`guild.py`、`member.py`、`messages.py`、`content.py`）。
+
+## MUST（必须做）
+
+- MUST 使用频道域路径：`/guilds/{guild_id}/...`、`/channels/{channel_id}/...`、`/users/@me/...`、`/dms/...`。
+- MUST 对**同路径不同载荷**的接口保持区分，不要合并成一个函数：
+  - 全员禁言 `PATCH /guilds/{guild_id}/mute`（`MuteRequest`，无响应体）；
+  - 批量禁言同路径（`MuteMembersRequest` → `MuteMembersResponse`）；
+  - 单人禁言 `PATCH /guilds/{guild_id}/members/{user_id}/mute`（`MuteRequest`，无响应体）。
+- MUST 让无响应体的接口（权限修改、禁言、撤回、上麦/下麦、表情表态、公告删除等）返回 `None`，但仍读取响应。
+- MUST 遵循顶层 `api/agent.md` 的请求骨架与命名约定。
+
+## SHOULD（应当做）
+
+- SHOULD 对权限接口复用同一个请求模型（`UpdateChannelPermissionsRequest` 同时服务成员权限与身份组权限）。
+- SHOULD 把 MIME/文件相关处理留在调用方，api 层只做薄映射。
+
+## MUST NOT（禁止做）
+
+- MUST NOT 在本目录实现子频道公告（官方已废弃，见包级 `agent.md`）。
+- MUST NOT 把 `guild_id`/`channel_id` 塞进请求模型。
+- MUST NOT 手写鉴权头或自建会话；一律用 `qqbotsdk.api.core.session`。
+- MUST NOT 在接口里吞异常或做重试。
+
+## 自检
+
+```powershell
+cd D:\QQBotSDK
+.venv\Scripts\ruff.exe check packages\qqbotsdk-guild\src\qqbotsdk\api
+.venv\Scripts\pyright.exe
+```

qqbotsdk/api/guild/channel.py

@@ -0,0 +1,129 @@
+from qqbotsdk.api.core import session
+from qqbotsdk.model.guild.channel import (
+    CreateChannelRequest,
+    CreateChannelResponse,
+    GetChannelOnlineNumsResponse,
+    GetChannelPermissionsResponse,
+    GetChannelResponse,
+    GetChannelRolePermissionsResponse,
+    GetGuildChannelsResponse,
+    UpdateChannelPermissionsRequest,
+    UpdateChannelRequest,
+    UpdateChannelResponse,
+)
+
+
+async def get_channel(
+    channel_id: str,
+) -> GetChannelResponse:
+    async with session.get(
+        f"/channels/{channel_id}",
+    ) as resp:
+        result = await resp.json()
+
+    return GetChannelResponse.model_validate(result)
+
+
+async def get_guild_channels(
+    guild_id: str,
+) -> GetGuildChannelsResponse:
+    async with session.get(
+        f"/guilds/{guild_id}/channels",
+    ) as resp:
+        result = await resp.json()
+
+    return GetGuildChannelsResponse.model_validate(result)
+
+
+async def create_channel(
+    guild_id: str,
+    payload: CreateChannelRequest,
+) -> CreateChannelResponse:
+    async with session.post(
+        f"/guilds/{guild_id}/channels",
+        json=payload.model_dump(exclude_none=True),
+    ) as resp:
+        result = await resp.json()
+
+    return CreateChannelResponse.model_validate(result)
+
+
+async def update_channel(
+    channel_id: str,
+    payload: UpdateChannelRequest,
+) -> UpdateChannelResponse:
+    async with session.patch(
+        f"/channels/{channel_id}",
+        json=payload.model_dump(exclude_none=True),
+    ) as resp:
+        result = await resp.json()
+
+    return UpdateChannelResponse.model_validate(result)
+
+
+async def delete_channel(
+    channel_id: str,
+) -> None:
+    async with session.delete(
+        f"/channels/{channel_id}",
+    ) as resp:
+        await resp.json()
+
+
+async def get_channel_online_nums(
+    channel_id: str,
+) -> GetChannelOnlineNumsResponse:
+    async with session.get(
+        f"/channels/{channel_id}/online_nums",
+    ) as resp:
+        result = await resp.json()
+
+    return GetChannelOnlineNumsResponse.model_validate(result)
+
+
+async def get_channel_permissions(
+    channel_id: str,
+    user_id: str,
+) -> GetChannelPermissionsResponse:
+    async with session.get(
+        f"/channels/{channel_id}/members/{user_id}/permissions",
+    ) as resp:
+        result = await resp.json()
+
+    return GetChannelPermissionsResponse.model_validate(result)
+
+
+async def get_channel_role_permissions(
+    channel_id: str,
+    role_id: str,
+) -> GetChannelRolePermissionsResponse:
+    async with session.get(
+        f"/channels/{channel_id}/roles/{role_id}/permissions",
+    ) as resp:
+        result = await resp.json()
+
+    return GetChannelRolePermissionsResponse.model_validate(result)
+
+
+async def update_channel_permissions(
+    channel_id: str,
+    user_id: str,
+    payload: UpdateChannelPermissionsRequest,
+) -> None:
+    async with session.put(
+        f"/channels/{channel_id}/members/{user_id}/permissions",
+        json=payload.model_dump(exclude_none=True),
+    ) as resp:
+        await resp.json()
+
+
+async def update_channel_role_permissions(
+    channel_id: str,
+    role_id: str,
+    payload: UpdateChannelPermissionsRequest,
+) -> None:
+    async with session.put(
+        f"/channels/{channel_id}/roles/{role_id}/permissions",
+        json=payload.model_dump(exclude_none=True),
+    ) as resp:
+        await resp.json()

qqbotsdk/api/guild/content.py

@@ -0,0 +1,214 @@
+from qqbotsdk.api.core import session
+from qqbotsdk.model.guild.content import (
+    AudioControlRequest,
+    CreateChannelScheduleRequest,
+    CreateChannelScheduleResponse,
+    CreateGuildAnnounceRequest,
+    CreateGuildAnnounceResponse,
+    DeleteChannelThreadResponse,
+    GetChannelPinsResponse,
+    GetChannelScheduleResponse,
+    GetChannelSchedulesRequest,
+    GetChannelSchedulesResponse,
+    GetChannelThreadResponse,
+    GetChannelThreadsResponse,
+    PutChannelThreadRequest,
+    PutChannelThreadResponse,
+    UpdateChannelScheduleRequest,
+    UpdateChannelScheduleResponse,
+)
+
+
+async def create_guild_announce(
+    guild_id: str,
+    payload: CreateGuildAnnounceRequest,
+) -> CreateGuildAnnounceResponse:
+    async with session.post(
+        f"/guilds/{guild_id}/announces",
+        json=payload.model_dump(exclude_none=True),
+    ) as resp:
+        result = await resp.json()
+
+    return CreateGuildAnnounceResponse.model_validate(result)
+
+
+async def delete_guild_announce(
+    guild_id: str,
+    message_id: str,
+) -> None:
+    async with session.delete(
+        f"/guilds/{guild_id}/announces/{message_id}",
+    ) as resp:
+        await resp.json()
+
+
+async def pin_channel_message(
+    channel_id: str,
+    message_id: str,
+) -> GetChannelPinsResponse:
+    async with session.put(
+        f"/channels/{channel_id}/pins/{message_id}",
+    ) as resp:
+        result = await resp.json()
+
+    return GetChannelPinsResponse.model_validate(result)
+
+
+async def unpin_channel_message(
+    channel_id: str,
+    message_id: str,
+) -> None:
+    async with session.delete(
+        f"/channels/{channel_id}/pins/{message_id}",
+    ) as resp:
+        await resp.json()
+
+
+async def get_channel_pins(
+    channel_id: str,
+) -> GetChannelPinsResponse:
+    async with session.get(
+        f"/channels/{channel_id}/pins",
+    ) as resp:
+        result = await resp.json()
+
+    return GetChannelPinsResponse.model_validate(result)
+
+
+async def get_channel_schedules(
+    channel_id: str,
+    payload: GetChannelSchedulesRequest,
+) -> GetChannelSchedulesResponse:
+    async with session.get(
+        f"/channels/{channel_id}/schedules",
+        params=payload.model_dump(exclude_none=True),
+    ) as resp:
+        result = await resp.json()
+
+    return GetChannelSchedulesResponse.model_validate(result)
+
+
+async def get_channel_schedule(
+    channel_id: str,
+    schedule_id: str,
+) -> GetChannelScheduleResponse:
+    async with session.get(
+        f"/channels/{channel_id}/schedules/{schedule_id}",
+    ) as resp:
+        result = await resp.json()
+
+    return GetChannelScheduleResponse.model_validate(result)
+
+
+async def create_channel_schedule(
+    channel_id: str,
+    payload: CreateChannelScheduleRequest,
+) -> CreateChannelScheduleResponse:
+    async with session.post(
+        f"/channels/{channel_id}/schedules",
+        json=payload.model_dump(exclude_none=True),
+    ) as resp:
+        result = await resp.json()
+
+    return CreateChannelScheduleResponse.model_validate(result)
+
+
+async def update_channel_schedule(
+    channel_id: str,
+    schedule_id: str,
+    payload: UpdateChannelScheduleRequest,
+) -> UpdateChannelScheduleResponse:
+    async with session.patch(
+        f"/channels/{channel_id}/schedules/{schedule_id}",
+        json=payload.model_dump(exclude_none=True),
+    ) as resp:
+        result = await resp.json()
+
+    return UpdateChannelScheduleResponse.model_validate(result)
+
+
+async def delete_channel_schedule(
+    channel_id: str,
+    schedule_id: str,
+) -> None:
+    async with session.delete(
+        f"/channels/{channel_id}/schedules/{schedule_id}",
+    ) as resp:
+        await resp.json()
+
+
+async def control_channel_audio(
+    channel_id: str,
+    payload: AudioControlRequest,
+) -> None:
+    async with session.post(
+        f"/channels/{channel_id}/audio",
+        json=payload.model_dump(exclude_none=True),
+    ) as resp:
+        await resp.json()
+
+
+async def put_channel_mic(
+    channel_id: str,
+) -> None:
+    async with session.put(
+        f"/channels/{channel_id}/mic",
+    ) as resp:
+        await resp.json()
+
+
+async def delete_channel_mic(
+    channel_id: str,
+) -> None:
+    async with session.delete(
+        f"/channels/{channel_id}/mic",
+    ) as resp:
+        await resp.json()
+
+
+async def get_channel_threads(
+    channel_id: str,
+) -> GetChannelThreadsResponse:
+    async with session.get(
+        f"/channels/{channel_id}/threads",
+    ) as resp:
+        result = await resp.json()
+
+    return GetChannelThreadsResponse.model_validate(result)
+
+
+async def get_channel_thread(
+    channel_id: str,
+    thread_id: str,
+) -> GetChannelThreadResponse:
+    async with session.get(
+        f"/channels/{channel_id}/threads/{thread_id}",
+    ) as resp:
+        result = await resp.json()
+
+    return GetChannelThreadResponse.model_validate(result)
+
+
+async def put_channel_thread(
+    channel_id: str,
+    payload: PutChannelThreadRequest,
+) -> PutChannelThreadResponse:
+    async with session.put(
+        f"/channels/{channel_id}/threads",
+        json=payload.model_dump(exclude_none=True),
+    ) as resp:
+        result = await resp.json()
+
+    return PutChannelThreadResponse.model_validate(result)
+
+
+async def delete_channel_thread(
+    channel_id: str,
+    thread_id: str,
+) -> DeleteChannelThreadResponse:
+    async with session.delete(
+        f"/channels/{channel_id}/threads/{thread_id}",
+    ) as resp:
+        result = await resp.json()
+
+    return DeleteChannelThreadResponse.model_validate(result)

qqbotsdk/api/guild/guild.py

@@ -0,0 +1,68 @@
+from qqbotsdk.api.core import session
+from qqbotsdk.model.guild.guild import (
+    CreateApiPermissionDemandRequest,
+    CreateApiPermissionDemandResponse,
+    GetGuildApiPermissionsResponse,
+    GetGuildMessageSettingResponse,
+    GetGuildResponse,
+    GetMeGuildsRequest,
+    GetMeGuildsResponse,
+)
+
+
+async def get_guild(
+    guild_id: str,
+) -> GetGuildResponse:
+    async with session.get(
+        f"/guilds/{guild_id}",
+    ) as resp:
+        result = await resp.json()
+
+    return GetGuildResponse.model_validate(result)
+
+
+async def get_me_guilds(
+    payload: GetMeGuildsRequest,
+) -> GetMeGuildsResponse:
+    async with session.get(
+        "/users/@me/guilds",
+        params=payload.model_dump(exclude_none=True),
+    ) as resp:
+        result = await resp.json()
+
+    return GetMeGuildsResponse.model_validate(result)
+
+
+async def get_guild_message_setting(
+    guild_id: str,
+) -> GetGuildMessageSettingResponse:
+    async with session.get(
+        f"/guilds/{guild_id}/message/setting",
+    ) as resp:
+        result = await resp.json()
+
+    return GetGuildMessageSettingResponse.model_validate(result)
+
+
+async def get_guild_api_permissions(
+    guild_id: str,
+) -> GetGuildApiPermissionsResponse:
+    async with session.get(
+        f"/guilds/{guild_id}/api_permission",
+    ) as resp:
+        result = await resp.json()
+
+    return GetGuildApiPermissionsResponse.model_validate(result)
+
+
+async def create_api_permission_demand(
+    guild_id: str,
+    payload: CreateApiPermissionDemandRequest,
+) -> CreateApiPermissionDemandResponse:
+    async with session.post(
+        f"/guilds/{guild_id}/api_permission/demand",
+        json=payload.model_dump(exclude_none=True),
+    ) as resp:
+        result = await resp.json()
+
+    return CreateApiPermissionDemandResponse.model_validate(result)

qqbotsdk/api/guild/member.py

@@ -0,0 +1,179 @@
+from qqbotsdk.api.core import session
+from qqbotsdk.model.guild.member import (
+    CreateGuildRoleRequest,
+    CreateGuildRoleResponse,
+    GetGuildMemberResponse,
+    GetGuildMembersRequest,
+    GetGuildMembersResponse,
+    GetGuildRolesResponse,
+    GetRoleMembersRequest,
+    GetRoleMembersResponse,
+    GuildMemberRoleRequest,
+    MuteMembersRequest,
+    MuteMembersResponse,
+    MuteRequest,
+    RemoveGuildMemberRequest,
+    UpdateGuildRoleRequest,
+    UpdateGuildRoleResponse,
+)
+
+
+async def get_guild_members(
+    guild_id: str,
+    payload: GetGuildMembersRequest,
+) -> GetGuildMembersResponse:
+    async with session.get(
+        f"/guilds/{guild_id}/members",
+        params=payload.model_dump(exclude_none=True),
+    ) as resp:
+        result = await resp.json()
+
+    return GetGuildMembersResponse.model_validate(result)
+
+
+async def get_guild_member(
+    guild_id: str,
+    user_id: str,
+) -> GetGuildMemberResponse:
+    async with session.get(
+        f"/guilds/{guild_id}/members/{user_id}",
+    ) as resp:
+        result = await resp.json()
+
+    return GetGuildMemberResponse.model_validate(result)
+
+
+async def remove_guild_member(
+    guild_id: str,
+    user_id: str,
+    payload: RemoveGuildMemberRequest,
+) -> None:
+    async with session.delete(
+        f"/guilds/{guild_id}/members/{user_id}",
+        json=payload.model_dump(exclude_none=True),
+    ) as resp:
+        await resp.json()
+
+
+async def get_guild_roles(
+    guild_id: str,
+) -> GetGuildRolesResponse:
+    async with session.get(
+        f"/guilds/{guild_id}/roles",
+    ) as resp:
+        result = await resp.json()
+
+    return GetGuildRolesResponse.model_validate(result)
+
+
+async def create_guild_role(
+    guild_id: str,
+    payload: CreateGuildRoleRequest,
+) -> CreateGuildRoleResponse:
+    async with session.post(
+        f"/guilds/{guild_id}/roles",
+        json=payload.model_dump(exclude_none=True),
+    ) as resp:
+        result = await resp.json()
+
+    return CreateGuildRoleResponse.model_validate(result)
+
+
+async def update_guild_role(
+    guild_id: str,
+    role_id: str,
+    payload: UpdateGuildRoleRequest,
+) -> UpdateGuildRoleResponse:
+    async with session.patch(
+        f"/guilds/{guild_id}/roles/{role_id}",
+        json=payload.model_dump(exclude_none=True),
+    ) as resp:
+        result = await resp.json()
+
+    return UpdateGuildRoleResponse.model_validate(result)
+
+
+async def delete_guild_role(
+    guild_id: str,
+    role_id: str,
+) -> None:
+    async with session.delete(
+        f"/guilds/{guild_id}/roles/{role_id}",
+    ) as resp:
+        await resp.json()
+
+
+async def get_role_members(
+    guild_id: str,
+    role_id: str,
+    payload: GetRoleMembersRequest,
+) -> GetRoleMembersResponse:
+    async with session.get(
+        f"/guilds/{guild_id}/roles/{role_id}/members",
+        params=payload.model_dump(exclude_none=True),
+    ) as resp:
+        result = await resp.json()
+
+    return GetRoleMembersResponse.model_validate(result)
+
+
+async def add_guild_member_role(
+    guild_id: str,
+    user_id: str,
+    role_id: str,
+    payload: GuildMemberRoleRequest,
+) -> None:
+    async with session.put(
+        f"/guilds/{guild_id}/members/{user_id}/roles/{role_id}",
+        json=payload.model_dump(exclude_none=True),
+    ) as resp:
+        await resp.json()
+
+
+async def remove_guild_member_role(
+    guild_id: str,
+    user_id: str,
+    role_id: str,
+    payload: GuildMemberRoleRequest,
+) -> None:
+    async with session.delete(
+        f"/guilds/{guild_id}/members/{user_id}/roles/{role_id}",
+        json=payload.model_dump(exclude_none=True),
+    ) as resp:
+        await resp.json()
+
+
+async def mute_guild(
+    guild_id: str,
+    payload: MuteRequest,
+) -> None:
+    async with session.patch(
+        f"/guilds/{guild_id}/mute",
+        json=payload.model_dump(exclude_none=True),
+    ) as resp:
+        await resp.json()
+
+
+async def mute_guild_members(
+    guild_id: str,
+    payload: MuteMembersRequest,
+) -> MuteMembersResponse:
+    async with session.patch(
+        f"/guilds/{guild_id}/mute",
+        json=payload.model_dump(exclude_none=True),
+    ) as resp:
+        result = await resp.json()
+
+    return MuteMembersResponse.model_validate(result)
+
+
+async def mute_guild_member(
+    guild_id: str,
+    user_id: str,
+    payload: MuteRequest,
+) -> None:
+    async with session.patch(
+        f"/guilds/{guild_id}/members/{user_id}/mute",
+        json=payload.model_dump(exclude_none=True),
+    ) as resp:
+        await resp.json()