qqbot-md-sdk 0.1.0__py3-none-any.whl

qgbot/__init__.py

@@ -0,0 +1,59 @@
+"""qgbot —— QQ 官方机器人 Markdown 消息构造 SDK。
+
+只做一件事：把 QQ 官方机器人那套 markdown 语法、键盘 JSON 和素材上传流程包装成可组合的
+Python API，让插件不用手拼字符串字面量。
+
+设计边界：
+- **不碰网络**。素材上传只算签名、组请求、解响应，实际 HTTP 由调用方注入的 transport 完成。
+- **不依赖框架**。纯标准库，任何框架（NoneBot / 自研 / 裸 requests）都能直接 import。
+- **不做语法校验**。平台限制（标题层级、按钮数量等）通过常量暴露，由调用方自己控制，
+  SDK 不擅自截断或改写用户的内容。
+
+    from qgbot import md
+
+    text = md.render(
+        md.title("今日运势", level=1),
+        md.quote("宜：出门走走"),
+        md.image("https://example.com/a.png", width=200, height=200),
+        md.mention("user_openid"),
+    )
+"""
+
+from . import md
+from .keyboard import (
+    MAX_ROWS,
+    STYLE_BLUE,
+    STYLE_GREY,
+    Button,
+    Keyboard,
+    callback,
+    command,
+    link,
+    make_keyboard,
+)
+from .media import MediaError, MediaImage, Transport, delete_image, upload_image
+from .message import Message, markdown_payload, markdown_with_keyboard
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MAX_ROWS",
+    "STYLE_BLUE",
+    "STYLE_GREY",
+    "Button",
+    "Keyboard",
+    "MediaError",
+    "MediaImage",
+    "Message",
+    "Transport",
+    "callback",
+    "command",
+    "delete_image",
+    "link",
+    "make_keyboard",
+    "markdown_payload",
+    "markdown_with_keyboard",
+    "md",
+    "upload_image",
+    "__version__",
+]

qgbot/keyboard.py

@@ -0,0 +1,245 @@
+"""QQ 官方机器人的按钮 / 键盘构造。
+
+平台结构（发给 `keyboard` 字段）：
+
+    {
+      "content": {
+        "rows": [
+          {"buttons": [ {...}, {...} ]},
+          {"buttons": [ {...} ]}
+        ]
+      }
+    }
+
+单个按钮：
+
+    {
+      "id": "1",
+      "render_data": {"label": "显示文字", "visited_label": "点过之后", "style": 1},
+      "action": {"type": 2, "data": "指令", "permission": {"type": 2}}
+    }
+
+`action.type` 的取值：
+- 0 链接跳转，`data` 是 URL
+- 1 回调，点后平台推送 `INTERACTION_CREATE` 事件，`data` 是回调值
+- 2 指令，点后填入输入框（配 `enter: true` 则直接发送）
+- 4 订阅（`subscribe_data`）
+
+`permission.type` 的取值：
+- 0 指定用户，配 `specify_user_ids`
+- 1 仅管理员
+- 2 所有人
+- 3 指定身份组，配 `specify_role_ids`
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+# 按钮样式：0 灰色线框，1 蓝色线框
+STYLE_GREY = 0
+STYLE_BLUE = 1
+
+# 平台限制：键盘最多 5 行
+MAX_ROWS = 5
+# 每行最多 5 个按钮（平台未明确写死，但超过这个数会挤在一起，实际上按 3 个最舒服）
+MAX_BUTTONS_PER_ROW = 5
+
+# action.type
+ACTION_URL = 0
+ACTION_CALLBACK = 1
+ACTION_COMMAND = 2
+ACTION_SUBSCRIBE = 4
+
+# permission.type
+PERM_USER = 0
+PERM_ADMIN = 1
+PERM_EVERYONE = 2
+PERM_ROLE = 3
+
+
+@dataclass
+class Button:
+    """一个按钮。
+
+    用工厂函数 `link()` / `callback()` / `command()` 构造，比直接拼 dict 安全。
+    """
+
+    label: str
+    action_type: int
+    data: str = ""
+    visited_label: str = ""
+    style: int = STYLE_BLUE
+    enter: bool = False
+    reply: bool = False
+    permission: dict[str, Any] = field(default_factory=lambda: {"type": PERM_EVERYONE})
+    click_limit: int | None = None
+    unsupport_tips: str = ""
+    subscribe_data: dict[str, Any] | None = None
+    button_id: str = ""
+
+    def to_dict(self, index: int = 0) -> dict[str, Any]:
+        """转成平台要求的按钮结构。
+
+        `index` 用于在未显式指定 id 时生成一个稳定标识——平台要求按钮 id 在同一条消息
+        内唯一，重名会导致后一个覆盖前一个的点击状态。
+        """
+        render_data: dict[str, Any] = {
+            "label": self.label,
+            "visited_label": self.visited_label or self.label,
+            "style": self.style,
+        }
+        action: dict[str, Any] = {
+            "type": self.action_type,
+            "data": self.data,
+            "permission": self.permission,
+        }
+        if self.enter:
+            action["enter"] = True
+        if self.reply:
+            action["reply"] = True
+        if self.click_limit is not None:
+            action["click_limit"] = int(self.click_limit)
+        if self.unsupport_tips:
+            action["unsupport_tips"] = self.unsupport_tips
+        if self.subscribe_data is not None:
+            action["subscribe_data"] = self.subscribe_data
+
+        return {
+            "id": self.button_id or str(index),
+            "render_data": render_data,
+            "action": action,
+        }
+
+
+@dataclass
+class Keyboard:
+    """键盘：若干行，每行若干按钮。"""
+
+    rows: list[list[Button]] = field(default_factory=list)
+    font_size: str = ""  # "small" / "medium" / "large"
+
+    def add_row(self, *buttons: Button) -> Keyboard:
+        """追加一行。链式调用。"""
+        if buttons:
+            self.rows.append(list(buttons))
+        return self
+
+    def to_dict(self) -> dict[str, Any]:
+        """转成平台要求的 keyboard 结构。
+
+        超过 `MAX_ROWS` 的行会被丢弃——平台只认前 5 行，多出来的不会渲染。
+        这里截断而不是抛错：调用方可能批量生成按钮，硬失败会让整条消息发不出去。
+        """
+        counter = 0
+        rows = []
+        for row in self.rows[:MAX_ROWS]:
+            buttons = []
+            for btn in row[:MAX_BUTTONS_PER_ROW]:
+                buttons.append(btn.to_dict(counter))
+                counter += 1
+            if buttons:
+                rows.append({"buttons": buttons})
+
+        content: dict[str, Any] = {"rows": rows}
+        if self.font_size:
+            content["style"] = {"font_size": self.font_size}
+        return {"content": content}
+
+    def __bool__(self) -> bool:
+        """空键盘转成 False，方便调用方判断要不要带 keyboard 字段。"""
+        return any(row for row in self.rows)
+
+
+def link(label: str, url: str, *, visited_label: str = "", style: int = STYLE_BLUE) -> Button:
+    """跳转按钮：点击打开链接或客户端能识别的 scheme。"""
+    return Button(
+        label=label, action_type=ACTION_URL, data=url,
+        visited_label=visited_label, style=style,
+    )
+
+
+def callback(
+    label: str, value: str, *, visited_label: str = "", style: int = STYLE_BLUE,
+) -> Button:
+    """回调按钮：点击后平台推送 `INTERACTION_CREATE` 事件，`value` 原样带回来。"""
+    return Button(
+        label=label, action_type=ACTION_CALLBACK, data=value,
+        visited_label=visited_label, style=style,
+    )
+
+
+def command(
+    label: str,
+    command_text: str,
+    *,
+    visited_label: str = "",
+    style: int = STYLE_BLUE,
+    enter: bool = True,
+    reply: bool = False,
+) -> Button:
+    """指令按钮：点击后把指令填入输入框；`enter=True` 时直接发送。
+
+    `enter` 默认 True——用户的预期是"点一下就执行"，还要再按一次发送键会很烦。
+    `reply=True` 会让指令以"回复当前消息"的形式发出。
+    """
+    return Button(
+        label=label, action_type=ACTION_COMMAND, data=command_text,
+        visited_label=visited_label, style=style, enter=enter, reply=reply,
+    )
+
+
+def for_users(button: Button, user_ids: list[str]) -> Button:
+    """把按钮限定为只有指定用户可点。"""
+    button.permission = {"type": PERM_USER, "specify_user_ids": [str(u) for u in user_ids]}
+    return button
+
+
+def for_admins(button: Button) -> Button:
+    """把按钮限定为仅管理员可点。"""
+    button.permission = {"type": PERM_ADMIN}
+    return button
+
+
+def for_roles(button: Button, role_ids: list[str]) -> Button:
+    """把按钮限定为只有指定身份组可点（仅频道场景有效）。"""
+    button.permission = {"type": PERM_ROLE, "specify_role_ids": [str(r) for r in role_ids]}
+    return button
+
+
+def rows_of(buttons: list[Button], per_row: int = 3) -> list[list[Button]]:
+    """把一串按钮按每行 `per_row` 个切分成行。"""
+    per_row = max(1, min(MAX_BUTTONS_PER_ROW, int(per_row)))
+    return [buttons[i:i + per_row] for i in range(0, len(buttons), per_row)]
+
+
+def make_keyboard(*buttons: Button, per_row: int = 3, font_size: str = "") -> Keyboard:
+    """一次性构造键盘：按 `per_row` 自动分行。"""
+    return Keyboard(rows=rows_of(list(buttons), per_row), font_size=font_size)
+
+
+__all__ = [
+    "ACTION_CALLBACK",
+    "ACTION_COMMAND",
+    "ACTION_SUBSCRIBE",
+    "ACTION_URL",
+    "MAX_BUTTONS_PER_ROW",
+    "MAX_ROWS",
+    "PERM_ADMIN",
+    "PERM_EVERYONE",
+    "PERM_ROLE",
+    "PERM_USER",
+    "STYLE_BLUE",
+    "STYLE_GREY",
+    "Button",
+    "Keyboard",
+    "callback",
+    "command",
+    "for_admins",
+    "for_roles",
+    "for_users",
+    "make_keyboard",
+    "link",
+    "rows_of",
+]

qgbot/md.py

@@ -0,0 +1,246 @@
+"""QQ 官方机器人 Markdown 语法构造器。
+
+平台支持的语法（来自官方文档）：
+- 标题 `#` ~ `##`
+- 粗体 `**`、下划线加粗 `__`、斜体 `_` / `*`、
+  粗斜体 `***`、删除线 `~~`
+- 链接 `[文字](url)`、自动链接 `<url>`
+- 图片 `![描述 #宽px #高px](url)`，尺寸写在 alt 文本里
+- 有序 / 无序列表，二级缩进 4 空格
+- 引用块 `>`
+- 分隔线 `***`
+- 多个空行要用零宽空格 `​` 单独成行
+
+**与标准 Markdown 的差异**：图片尺寸必须写在 alt 里，不写就按原图尺寸铺满，长图会把
+消息撑得极大。`image()` 因此默认要求显式宽高，避免误用。
+
+**正文里的小指令按钮**（`<qqbot-cmd-input>`）也在这个模块：它本质是嵌在 markdown 字符串里
+的标签，不是独立元素。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from urllib.parse import quote as urlquote
+
+# 零宽空格：平台用它表示"再来一个空行"。直接写两个 `\n` 只会被合并成一个。
+ZERO_WIDTH_SPACE = "​"
+
+# 标题最高只到二级，更深层级平台不渲染
+MAX_TITLE_LEVEL = 2
+
+
+def text(content: str) -> str:
+    """普通文本。原样返回，只做类型归一。"""
+    return str(content)
+
+
+def title(content: str, level: int = 1) -> str:
+    """标题。`level` 取 1 或 2，超出范围会被夹到边界值。
+
+    平台只支持两级标题，传 3 不会被渲染成三级，而是直接当正文处理——
+    与其让用户困惑，不如夹到合法范围并保持视觉层次。
+    """
+    level = max(1, min(MAX_TITLE_LEVEL, int(level)))
+    return f"{'#' * level} {content}"
+
+
+def bold(content: str) -> str:
+    return f"**{content}**"
+
+
+def italic(content: str) -> str:
+    return f"_{content}_"
+
+
+def bold_italic(content: str) -> str:
+    return f"***{content}***"
+
+
+def underline(content: str) -> str:
+    """下划线加粗（平台语法是 `__`，不是常见的 `<u>`）。"""
+    return f"__{content}__"
+
+
+def strike(content: str) -> str:
+    return f"~~{content}~~"
+
+
+def link(label: str, url: str) -> str:
+    """行内链接。"""
+    return f"[{label}]({url})"
+
+
+def autolink(url: str) -> str:
+    """自动链接：平台会自己把 URL 变成可点击的链接。"""
+    return f"<{url}>"
+
+
+def image(url: str, width: int, height: int, alt: str = "text") -> str:
+    """图片。尺寸必须显式给出。
+
+    QQ 按 alt 里的 `#宽px #高px` 决定显示尺寸；不给就按原图铺满，一张 1080×1920 的图
+    会把消息撑满整屏。宽高传 0 或负数时抛错，逼调用方做决定而不是默默出问题。
+
+    图片 URL 必须公网可访问。本地图片要先传到平台素材库，再用 `qqbot-media://` 引用，
+    这里不做上传。
+    """
+    width, height = int(width), int(height)
+    if width <= 0 or height <= 0:
+        raise ValueError(f"图片尺寸必须为正数，收到 {width}x{height}")
+    return f"![{alt} #{width}px #{height}px]({url})"
+
+
+def media(media_id: str, width: int = 0, height: int = 0, alt: str = "text") -> str:
+    """引用平台上已上传的素材（`qqbot-media://` scheme）。
+
+    `media_id` 是素材上传接口返回的 ID。不传尺寸时按原图显示，需要控制大小就补宽高。
+    """
+    if width and height:
+        return f"![{alt} #{int(width)}px #{int(height)}px](qqbot-media://{media_id})"
+    return f"![{alt}](qqbot-media://{media_id})"
+
+
+def ordered(items: Iterable[str], level: int = 1) -> str:
+    """有序列表。`level=2` 时整块缩进 4 空格。"""
+    indent = "    " * (int(level) - 1)
+    return "\n".join(f"{indent}{i}. {item}" for i, item in enumerate(items, start=1))
+
+
+def unordered(items: Iterable[str], level: int = 1) -> str:
+    """无序列表。`level=2` 时整块缩进 4 空格。"""
+    indent = "    " * (int(level) - 1)
+    return "\n".join(f"{indent}- {item}" for item in items)
+
+
+def quote(content: str, lines: int = 1) -> str:
+    """引用块。多行内容每行都会加上 `>` 前缀。
+
+    `lines` 参数保留给「空一行再引用」的排版需求：平台要求引用块与上一段正文之间
+    有空行，这里不自动加（见 `blank()`），由调用方决定间距。
+    """
+    body = "\n".join(f"> {line}" for line in str(content).splitlines())
+    return body
+
+
+def divider() -> str:
+    """水平分隔线。平台语法是 `***`，不是 `---`。"""
+    return "***"
+
+
+def blank(count: int = 1) -> str:
+    """空行。
+
+    平台会把连续 `\n` 合并，真正想要多个空行要在中间插入零宽空格行。
+    这里返回的内容需要调用方用 `render()` 拼接，`render` 会自动处理分隔。
+    """
+    return "\n".join([ZERO_WIDTH_SPACE] * max(1, int(count)))
+
+
+def cmd_input(command: str, show: str | None = None, reference: bool = False) -> str:
+    """正文里的「小指令按钮」，点击等同于在输入框填入并发送该指令。
+
+    `show` 是按钮上显示的文字，不传就显示指令本身。
+    `reference=False` 表示点击时不引用当前消息；绝大多数场景都不需要引用。
+
+    参数里的引号、`&` 等会被 URL 编码——不编码的话平台解析标签属性时会截断。
+    """
+    encoded_command = urlquote(command, safe="")
+    encoded_show = urlquote(show or command, safe="")
+    ref = "true" if reference else "false"
+    return f'<qqbot-cmd-input text="{encoded_command}" show="{encoded_show}" reference="{ref}" />'
+
+
+def cmd_enter(command: str, show: str | None = None) -> str:
+    """正文里的「回车发送」按钮：点击后直接发送，不经过输入框。
+
+    与 `cmd_input` 的区别是少了"填入输入框"这一步，适合确认类操作。
+
+    **群聊与文字子频道不可用**——平台限制，只能在单聊里用。
+    """
+    encoded_command = urlquote(command, safe="")
+    encoded_show = urlquote(show or command, safe="")
+    return f'<qqbot-cmd-enter text="{encoded_command}" show="{encoded_show}" />'
+
+
+def mention(user_id: str) -> str:
+    """@ 某个用户。
+
+    `user_id` 的含义随场景变化：
+    - 群聊：成员的 `member_openid`
+    - 文字子频道：用户的 `user_openid`
+
+    **群聊里 @ 用户只在 markdown 消息中有效**，纯文本消息不支持。
+
+    旧的 `<@id>` 写法平台已标记废弃，这里生成的是新的 `<qqbot-at-user>` 标签。
+    """
+    uid = str(user_id or "").strip()
+    if not uid:
+        raise ValueError("mention 需要非空的用户 id")
+    return f'<qqbot-at-user id="{uid}" />'
+
+
+def mention_everyone() -> str:
+    """@ 全体成员。
+
+    两个硬限制：
+    - 机器人必须是群管理员
+    - **每个群每个自然日只能 @ 一次**
+
+    第二条容易踩坑——超出后平台直接拒收整条消息，而不是只忽略这个标签。
+    """
+    return "<qqbot-at-everyone />"
+
+
+def channel(channel_id: str) -> str:
+    """跳转到子频道（仅频道场景，且必须是当前频道下的子频道）。"""
+    return f"<#{channel_id}>"
+
+
+def emoji(emoji_id: str) -> str:
+    """引用系统表情（仅频道场景，且只支持 type=1 的表情）。"""
+    return f"<emoji:{emoji_id}>"
+
+
+def join(*parts: str) -> str:
+    """把多段 markdown 用换行拼起来，跳过空段。"""
+    return "\n".join(str(p) for p in parts if p)
+
+
+def render(*parts: str) -> str:
+    """把多段内容拼成完整 markdown 正文。
+
+    每个参数之间用单个换行分隔，空字符串和 None 会被跳过。
+    需要空行请显式插入 `blank()`。
+    """
+    return join(*parts)
+
+
+__all__ = [
+    "MAX_TITLE_LEVEL",
+    "ZERO_WIDTH_SPACE",
+    "autolink",
+    "blank",
+    "bold",
+    "bold_italic",
+    "channel",
+    "cmd_enter",
+    "cmd_input",
+    "emoji",
+    "divider",
+    "image",
+    "italic",
+    "join",
+    "link",
+    "media",
+    "mention",
+    "mention_everyone",
+    "ordered",
+    "quote",
+    "render",
+    "strike",
+    "text",
+    "title",
+    "underline",
+    "unordered",
+]

qgbot/media.py

@@ -0,0 +1,268 @@
+"""素材上传：把本地图片变成平台可引用的 `qqbot-media://` 链接。
+
+**为什么需要它**：markdown 消息里的图片必须是公网 URL，让开放平台自己去拉。但插件生成的
+图片（渲染的卡片、表情包）只存在于本地磁盘，没有公网地址。旧办法是找个第三方图床传上去，
+现在开放平台自己提供了图库，传上去就能用 `qqbot-media://` 引用，不依赖外部服务。
+
+上传流程是**三步预签名**，不是一次 multipart：
+
+1. `POST /v2/media-images/prepare` — 声明文件名、大小、MIME、MD5、SHA1，
+   拿回 `upload_id` 和 COS 预签名地址
+2. `PUT <presigned_url>` — 把原始字节传上去，`Content-Type` 必须和声明的一致，
+   否则 COS 返回 403
+3. `POST /v2/media-images/complete` — 带上 `upload_id` 和 ETag 里的 MD5 收尾，
+   拿回最终的 `qqbot-media://image/v1/<token>`
+
+**设计取舍：本模块不发 HTTP。** SDK 只负责算签名、组装请求、解析响应，实际的网络调用由
+调用方注入一个 `transport`。这样：
+
+- SDK 不绑定 httpx / aiohttp / requests 中的任何一个
+- 测试不需要起 mock server
+- 调用方能复用自己框架的连接池、代理、重试策略
+
+    result = await upload_image(
+        data=png_bytes,
+        file_name="card.png",
+        transport=my_transport,   # 自己实现三个方法
+    )
+    text = md.image(result.url, 400, 300)
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+# 支持的图片格式与对应的 MIME。扩展名必须和 MIME 一致，平台会校验。
+SUPPORTED_TYPES: dict[str, str] = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+}
+
+# 单张图片上限 10 MB
+MAX_IMAGE_BYTES = 10 * 1024 * 1024
+# 每个机器人最多存 100 张，满了要先删
+MAX_IMAGES_PER_BOT = 100
+# 上传任务的存活时间：4 小时，超时未完成要重新 prepare
+UPLOAD_TASK_TTL_SECONDS = 4 * 3600
+# 图片的滑动有效期：90 天未被引用就过期，每次引用会重置
+IMAGE_TTL_SECONDS = 90 * 24 * 3600
+
+# prepare 接口路径
+PATH_PREPARE = "/v2/media-images/prepare"
+PATH_COMPLETE = "/v2/media-images/complete"
+PATH_LIST = "/v2/media-images"
+PATH_DELETE = "/v2/media-images/{image_id}/delete"
+
+# 错误码 → 可读原因
+ERROR_CODES: dict[int, str] = {
+    40035001: "不支持的图片格式",
+    40035002: "超过大小限制",
+    40035003: "上传任务不存在、已过期、不属于该机器人，或 MD5 不匹配",
+    40035007: "图片数量已达上限（100 张），请先删除",
+    40035008: "图片不存在",
+    40035009: "图片已过期或已删除",
+    40035010: "链接无效，或属于其他机器人",
+}
+
+
+class Transport(Protocol):
+    """调用方需实现的网络层。
+
+    三个方法都要能 await。返回值约定：
+
+    - `post_json(path, body)` → `(status_code, response_json)`
+    - `put_bytes(url, data, content_type)` → `(status_code, headers)`，
+      headers 需要能取到 `ETag` 或 `etag`（大小写不敏感由实现方处理）
+    - `delete(path)` → `(status_code, response_json)`
+    """
+
+    async def post_json(self, path: str, body: dict[str, Any]) -> tuple[int, dict[str, Any]]: ...
+
+    async def put_bytes(
+        self, url: str, data: bytes, content_type: str,
+    ) -> tuple[int, dict[str, str]]: ...
+
+    async def delete(self, path: str) -> tuple[int, dict[str, Any]]: ...
+
+
+class MediaError(Exception):
+    """上传失败。`code` 是平台错误码，`message` 是可直接展示的中文原因。"""
+
+    def __init__(self, code: int, message: str) -> None:
+        self.code = code
+        self.message = message
+        super().__init__(f"[{code}] {message}")
+
+
+@dataclass
+class MediaImage:
+    """上传成功后拿到的图片信息。"""
+
+    image_id: str
+    url: str
+    ttl: int = IMAGE_TTL_SECONDS
+    preview_url: str = ""
+
+    def to_markdown(self, width: int, height: int, alt: str = "text") -> str:
+        """直接转成 markdown 图片语法，省得调用方再拼一次。"""
+        return f"![{alt} #{int(width)}px #{int(height)}px]({self.url})"
+
+    def to_markdown_auto(self, alt: str = "text") -> str:
+        """不带尺寸的引用：平台按原图大小显示。"""
+        return f"![{alt}]({self.url})"
+
+
+def _digest(data: bytes) -> tuple[str, str]:
+    """算 MD5 和 SHA1。MD5 用于完整性校验，SHA1 用于幂等。"""
+    return hashlib.md5(data).hexdigest(), hashlib.sha1(data).hexdigest()
+
+
+def resolve_content_type(file_name: str) -> str:
+    """从扩展名推 MIME，不支持的格式直接抛错。
+
+    平台的校验是硬性的：扩展名和 Content-Type 对不上会拒收，所以这里不猜。
+    """
+    lowered = file_name.lower()
+    for ext, mime in SUPPORTED_TYPES.items():
+        if lowered.endswith(ext):
+            return mime
+    raise ValueError(
+        f"不支持的图片格式：{file_name}，仅支持 {', '.join(SUPPORTED_TYPES)}"
+    )
+
+
+def check_size(data: bytes) -> None:
+    """超出 10 MB 平台会拒收，提前拦下来省一次请求。"""
+    if len(data) > MAX_IMAGE_BYTES:
+        raise ValueError(
+            f"图片 {len(data) / 1024 / 1024:.1f} MB 超过上限 "
+            f"{MAX_IMAGE_BYTES / 1024 / 1024:.0f} MB"
+        )
+    if not data:
+        raise ValueError("图片内容为空")
+
+
+def build_prepare_body(data: bytes, file_name: str) -> dict[str, Any]:
+    """组装 prepare 请求体。"""
+    check_size(data)
+    md5, sha1 = _digest(data)
+    return {
+        "file_name": file_name,
+        "file_size": len(data),
+        "content_type": resolve_content_type(file_name),
+        "md5": md5,
+        "sha1": sha1,
+    }
+
+
+def _raise_for(status: int, body: dict[str, Any]) -> None:
+    """把平台的错误响应转成 MediaError。"""
+    if 200 <= status < 300:
+        return
+    code = int(body.get("code") or status)
+    message = ERROR_CODES.get(code) or str(body.get("message") or f"HTTP {status}")
+    raise MediaError(code, message)
+
+
+async def upload_image(
+    *,
+    data: bytes,
+    file_name: str,
+    transport: Transport,
+) -> MediaImage:
+    """完整的上传流程：prepare → PUT → complete。
+
+    `file_name` 必须带扩展名（png/jpg/jpeg/gif/webp），平台据此推断 MIME。
+
+    失败时抛 `MediaError`（平台拒绝）或 `ValueError`（本地校验不过）。
+    """
+    body = build_prepare_body(data, file_name)
+
+    status, prepared = await transport.post_json(PATH_PREPARE, body)
+    _raise_for(status, prepared)
+
+    upload_id = str(prepared.get("upload_id") or "")
+    presigned_url = str(prepared.get("presigned_url") or "")
+    if not upload_id or not presigned_url:
+        raise MediaError(-1, "prepare 响应缺少 upload_id 或 presigned_url")
+
+    # PUT 的 Content-Type 必须与 prepare 时声明的一致，否则 COS 直接 403
+    put_status, headers = await transport.put_bytes(
+        presigned_url, data, body["content_type"],
+    )
+    if not 200 <= put_status < 300:
+        raise MediaError(put_status, f"上传到对象存储失败（HTTP {put_status}）")
+
+    # ETag 里是带引号的 MD5，去掉引号才能和 prepare 时声明的一致
+    etag = ""
+    for key, value in headers.items():
+        if key.lower() == "etag":
+            etag = str(value).strip('"')
+            break
+    if not etag:
+        raise MediaError(-1, "对象存储未返回 ETag，无法校验完整性")
+
+    complete_status, completed = await transport.post_json(
+        PATH_COMPLETE, {"upload_id": upload_id, "md5": etag},
+    )
+    _raise_for(complete_status, completed)
+
+    url = str(completed.get("url") or "")
+    if not url:
+        raise MediaError(-1, "complete 响应缺少 url")
+
+    return MediaImage(
+        image_id=str(completed.get("image_id") or ""),
+        url=url,
+        ttl=int(completed.get("ttl") or IMAGE_TTL_SECONDS),
+        preview_url=str(completed.get("preview_url") or ""),
+    )
+
+
+async def delete_image(*, image_id: str, transport: Transport) -> bool:
+    """删除一张图，释放配额。已发送的消息不受影响。"""
+    path = PATH_DELETE.format(image_id=image_id)
+    status, body = await transport.delete(path)
+    _raise_for(status, body)
+    return True
+
+
+def parse_list_response(body: dict[str, Any]) -> tuple[list[MediaImage], str]:
+    """解析列表响应，返回 `(图片列表, 下一页游标)`。"""
+    images = [
+        MediaImage(
+            image_id=str(item.get("image_id") or ""),
+            url=str(item.get("url") or ""),
+            preview_url=str(item.get("preview_url") or ""),
+        )
+        for item in body.get("images") or []
+    ]
+    return images, str(body.get("next_cursor") or "")
+
+
+__all__ = [
+    "ERROR_CODES",
+    "IMAGE_TTL_SECONDS",
+    "MAX_IMAGES_PER_BOT",
+    "MAX_IMAGE_BYTES",
+    "PATH_COMPLETE",
+    "PATH_DELETE",
+    "PATH_LIST",
+    "PATH_PREPARE",
+    "SUPPORTED_TYPES",
+    "UPLOAD_TASK_TTL_SECONDS",
+    "MediaError",
+    "MediaImage",
+    "Transport",
+    "build_prepare_body",
+    "check_size",
+    "delete_image",
+    "parse_list_response",
+    "resolve_content_type",
+    "upload_image",
+]

qgbot/message.py

@@ -0,0 +1,76 @@
+"""把 markdown 正文与键盘组装成可直接发送的 payload。
+
+QQ 官方机器人发消息的 body 长这样（群聊 / 单聊）：
+
+    {
+      "msg_type": 2,
+      "markdown": {"content": "# 标题\\n正文"},
+      "keyboard": {"content": {"rows": [...]}},
+      "msg_id": "..."          # 被动回复必填，主动消息用 msg_seq
+    }
+
+`msg_type=2` 是 markdown。`msg_id` 是被动回复必须带上的那条消息的 id——不带就无法回复，
+只能走主动消息（有频次限制）。本模块只管组结构，消息 id 与频次由调用方处理。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .keyboard import Keyboard
+
+# 消息类型：2 = markdown
+MSG_TYPE_MARKDOWN = 2
+
+
+@dataclass
+class Message:
+    """一条待发送的 markdown 消息。
+
+        msg = Message("今日运势", keyboard=keyboard(cmd, link_btn))
+        payload = msg.to_payload(msg_id="xxx")
+
+    `content` 用 `md.render()` 拼好再传进来，本类不解析 markdown。
+    """
+
+    content: str
+    keyboard: Keyboard | None = None
+    # 平台限制：一条消息最多能带的按钮数，超过部分平台会整条拒收。
+    # 这里不主动截断（Keyboard 已限制 5 行），只是把限制暴露出来供调用方自查。
+
+    def to_payload(self, *, msg_id: str = "", msg_seq: int | None = None) -> dict[str, Any]:
+        """转成发送用的 body。
+
+        `msg_id` 是被动回复要回复的那条消息 id；`msg_seq` 用于同一条 msg_id 下连发多条
+        （此时必须递增，否则平台按重复消息丢弃）。
+        """
+        payload: dict[str, Any] = {
+            "msg_type": MSG_TYPE_MARKDOWN,
+            "markdown": {"content": self.content},
+        }
+        if self.keyboard:
+            payload["keyboard"] = self.keyboard.to_dict()
+        if msg_id:
+            payload["msg_id"] = str(msg_id)
+        if msg_seq is not None:
+            payload["msg_seq"] = int(msg_seq)
+        return payload
+
+
+def markdown_payload(content: str) -> dict[str, Any]:
+    """只要正文、不要键盘时的快捷构造。"""
+    return {"msg_type": MSG_TYPE_MARKDOWN, "markdown": {"content": content}}
+
+
+def markdown_with_keyboard(content: str, keyboard: Keyboard) -> dict[str, Any]:
+    """正文 + 键盘。`keyboard` 为空（所有行都空）时不带该字段。"""
+    return Message(content, keyboard=keyboard if keyboard else None).to_payload()
+
+
+__all__ = [
+    "MSG_TYPE_MARKDOWN",
+    "Message",
+    "markdown_payload",
+    "markdown_with_keyboard",
+]

qqbot_md_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,98 @@
+Metadata-Version: 2.1
+Name: qqbot-md-sdk
+Version: 0.1.0
+Summary: QQ 官方机器人 Markdown 消息构造 SDK
+Keywords: qq,qqbot,markdown,keyboard,sdk
+Author: MimoKit
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Project-URL: Homepage, https://github.com/MimoKit/qgbot
+Project-URL: Repository, https://github.com/MimoKit/qgbot
+Project-URL: Issues, https://github.com/MimoKit/qgbot/issues
+Project-URL: Documentation, https://github.com/MimoKit/qgbot/tree/main/docs
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# qgbot
+
+_把 QQ 官方机器人那套 Markdown 语法和键盘 JSON，变成可组合的 Python 调用_
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-%E2%89%A53.10-3776ab)](https://www.python.org/)
+[![Docs](https://img.shields.io/badge/文档-中文-8f5db7)](https://docs.example.com/)
+
+写插件时不用再手拼 `<qqbot-cmd-input>` 和按钮 JSON —— 一句 `md.image(url, 400, 300)` 就够。
+
+</div>
+
+## 为什么需要它
+
+QQ 官方机器人的 markdown 跟标准 markdown 不是一回事。图片尺寸得写在 alt 文本里（`![x #200px #300px](url)`）、分隔线是 `***` 不是 `---`、下划线是 `__` 不是 `<u>`、连续换行会被合并所以要多空一行得插零宽空格、@ 用户的标签从 `<@id>` 换成了 `<qqbot-at-user id="" />`。这些细节散在文档各处，每个插件都要重复踩一遍。
+
+按钮是另一层麻烦：平台要一段嵌套 JSON，`action.type` 区分链接 / 回调 / 指令 / 订阅，`permission.type` 区分所有人 / 管理员 / 指定用户 / 指定身份组，手写容易把 `type` 和 `style` 搞混。
+
+图片还有第三层：markdown 里的图必须是公网 URL，平台自己去拉；插件渲染出来的卡片只存在本地磁盘。官方图库的上传是**三步预签名流程**——声明元信息拿预签名地址、PUT 原始字节、回传 ETag 里的 MD5 收尾——不是一次 multipart 提交。
+
+qgbot 把这三块分别封成 `md`、`keyboard`、`media`，再加一个 `message` 负责组装发送用的 payload。
+
+## 特性
+
+- **零依赖** —— 纯标准库实现，不引入任何运行时包，`pip install` 不拉任何东西
+- **不绑框架** —— 没有 NoneBot / 自研框架的 import，任何 Python 环境都能直接用
+- **不碰网络** —— 素材上传只算签名、组请求、解响应，HTTP 由调用方注入，复用你自己的连接池与重试策略
+- **语法对齐平台** —— 分隔线、下划线、图片尺寸、零宽空格、@ 标签这些与标准 md 不同的地方全部按官方语法生成
+- **限制可见** —— 标题只支持两级、键盘最多 5 行、图片 10 MB、图库 100 张，都以常量形式暴露
+- **结构可测** —— 89 个用例覆盖每一处语法与上传流程，不需要起 mock server
+
+## 模块一览
+
+| 模块 | 覆盖内容 |
+| --- | --- |
+| `qgbot.md` | 标题、六种文字样式、行内链接与自动链接、带尺寸图片、两种列表（含二级缩进）、引用块、分隔线、多空行、正文内联指令按钮、@ 用户与 @ 全体、频道子频道跳转与系统表情 |
+| `qgbot.keyboard` | 链接 / 回调 / 指令三类按钮，权限限定，按行切分，字号设置 |
+| `qgbot.media` | 图库上传三步流程，含签名计算、错误码映射、列表解析与删除 |
+| `qgbot.message` | markdown 正文与键盘合成发送 body，带 `msg_id` / `msg_seq` 被动回复字段 |
+
+```python
+from qgbot import md, command, make_keyboard, Message
+
+content = md.render(
+    md.title("今日运势"),
+    md.image("https://example.com/card.png", 400, 300),
+    md.mention("user_openid"),
+    md.quote("宜：出门走走"),
+)
+
+payload = Message(
+    content,
+    keyboard=make_keyboard(command("再抽一次", "今日运势")),
+).to_payload(msg_id="收到的那条消息id")
+```
+
+## 边界
+
+**不做网络请求。** 素材上传只算 MD5 / SHA1、组装请求体、解析响应，实际 HTTP 由调用方注入的 `Transport` 完成。这样 SDK 不绑定 httpx / aiohttp / requests 中的任何一个，测试也不必起 mock server。
+
+**不管鉴权。** AccessToken 的获取与刷新属于调用方，SDK 产出的 payload 里不含凭据。
+
+**不做语法校验。** 平台限制以常量与注释暴露，但 SDK 不主动改写用户内容。两处例外：标题层级会被夹到合法范围（传 3 得到 2），键盘超过 5 行会被截断（平台本身就不渲染，抛错反而让整条消息发不出去）。
+
+**不解析已有 markdown。** 只有构造，没有反向解析。
+
+## 环境要求
+
+- Python `>= 3.10`
+
+## 开源协议
+
+[MIT](LICENSE)

qqbot_md_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+qgbot/__init__.py,sha256=eKrSgBWbyRE1fdlupsFXtTelGoRSScgQTn5feIVPxD4,1673
+qgbot/keyboard.py,sha256=JlsequN2C9Qz-_6MkLdyC6IKQoh3-QqUXM8tHKzE48g,7613
+qgbot/md.py,sha256=lnz_4yvtMkJASZ_FZuiGBLb-6--pz_W4d3W_KTY0-a8,8262
+qgbot/media.py,sha256=-SBiRY67vUiX1iE0_Opkyzmv8JRo7Fc4SKZ3V-2vgjU,9254
+qgbot/message.py,sha256=f8TYd-9mnqCzU05PhYiszlJlWhwhE8xJ6e-2fV9VRUc,2580
+qqbot_md_sdk-0.1.0.dist-info/METADATA,sha256=LAw5jhGy0EcbadNoqc4NMrAiz5BCcyMvHMosfZDQt9Q,5098
+qqbot_md_sdk-0.1.0.dist-info/WHEEL,sha256=IuIk3wbaEnFH1cx75iM2R1CmliRI3dFLXTbRakgvgFQ,90
+qqbot_md_sdk-0.1.0.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+qqbot_md_sdk-0.1.0.dist-info/RECORD,,

qqbot_md_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: pdm-backend (2.5.0)
+Root-Is-Purelib: true
+Tag: py3-none-any

qqbot_md_sdk-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+
+[gui_scripts]
+