nonebot-plugin-github-release 0.1.0__py3-none-any.whl

nonebot_plugin_github_release/config.py

@@ -0,0 +1,70 @@
+"""插件配置，全部可用 `.env` 里的 `GH_WATCH_*` 覆盖。"""
+
+from __future__ import annotations
+
+from typing import List
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Config(BaseModel):
+    """配置项。"""
+
+    model_config = ConfigDict(extra="ignore")
+
+    # 默认监控并推送的仓库（owner/repo）。群里也能用 /gh订阅 动态加
+    gh_watch_repos: List[str] = Field(default_factory=list)
+
+    # 默认接收推送的群。与上面的仓库做组合：每个群都订阅每个仓库
+    gh_watch_groups: List[int] = Field(default_factory=list)
+
+    # 轮询间隔（分钟）
+    gh_watch_interval_minutes: int = 10
+
+    # 展示时间使用的时区
+    gh_watch_timezone: str = "Asia/Shanghai"
+
+    # 是否连 alpha / beta / rc 一起推
+    gh_watch_include_prerelease: bool = True
+
+    # 没有正文的 release 不算公告，不推
+    gh_watch_require_body: bool = True
+
+    # GitHub Token（可选，提高 API 限额）
+    gh_watch_github_token: str = ""
+
+    # 代理（可选，留空则沿用环境变量）
+    gh_watch_proxy: str = ""
+
+    # 文本推送的正文上限
+    gh_watch_max_chars: int = 600
+
+    # /gh公告 查询时的正文上限
+    gh_watch_query_max_chars: int = 1200
+
+    # 每个仓库每轮最多推几条
+    gh_watch_max_per_round: int = 3
+
+    # 正文里的 @贡献者 是否去掉（只影响文本推送，卡片里保留）
+    gh_watch_strip_mentions: bool = True
+
+    # 中英双语公告只保留中文段（值改成 all 则两段都保留）
+    gh_watch_body_language: str = "zh"
+
+    # 是否发送渲染好的卡片图片（需要 nonebot-plugin-htmlrender + chromium）
+    gh_watch_send_image: bool = True
+
+    gh_watch_card_width: int = 900
+    gh_watch_card_max_height: int = 1500
+    gh_watch_card_max_chars: int = 2400
+    gh_watch_card_show_reactions: bool = True
+
+    # 数据目录，默认交给 nonebot-plugin-localstore 管
+    gh_watch_data_dir: str = ""
+
+
+def load_config() -> Config:
+    """从 NoneBot 全局配置读取插件配置。"""
+    import nonebot
+
+    return nonebot.get_plugin_config(Config)

nonebot_plugin_github_release/latest.py

@@ -0,0 +1,60 @@
+"""按需查询公告（给 /gh公告 用）：只读不写，带短时缓存。"""
+
+from __future__ import annotations
+
+import time
+from typing import Dict, List, Tuple
+
+from .config import Config
+from .models import Release
+from .plan import select_releases
+from .render import format_local_time
+from .source import fetch_releases
+
+_CACHE_TTL_SECONDS = 60.0
+_cache: Dict[str, Tuple[float, List[Release], str]] = {}
+
+
+def _cache_key(cfg: Config, repo: str) -> str:
+    return "|".join(
+        [repo, str(cfg.gh_watch_include_prerelease), str(cfg.gh_watch_require_body)]
+    )
+
+
+def clear_cache() -> None:
+    _cache.clear()
+
+
+async def fetch_announcements(
+    cfg: Config, repo: str, *, use_cache: bool = True
+) -> Tuple[List[Release], str]:
+    """拉取某个仓库的 release 列表（按发布时间升序），返回 (列表, 数据源)。"""
+    key = _cache_key(cfg, repo)
+    now = time.monotonic()
+    if use_cache:
+        cached = _cache.get(key)
+        if cached is not None and now - cached[0] < _CACHE_TTL_SECONDS:
+            return cached[1], cached[2]
+
+    fetched = await fetch_releases(cfg, repo)
+    releases = select_releases(
+        fetched.releases,
+        include_prerelease=cfg.gh_watch_include_prerelease,
+        require_body=cfg.gh_watch_require_body,
+    )
+    _cache[key] = (now, releases, fetched.source)
+    return releases, fetched.source
+
+
+def render_list(releases: List[Release], *, repo: str, tz_name: str) -> str:
+    """把若干条 release 渲染成简表。"""
+    lines = [f"【{repo} 最近 {len(releases)} 条】"]
+    for release in releases:
+        stage = "预发布" if release.prerelease else "正式版"
+        when = format_local_time(release.published_at, tz_name)
+        lines.append(f"· {release.title}（{stage}｜{when}）")
+        if release.url:
+            lines.append(f"  {release.url}")
+    lines.append("")
+    lines.append(f"发 /gh公告 {repo} 看最新一条全文")
+    return "\n".join(lines)

nonebot_plugin_github_release/models.py

@@ -0,0 +1,64 @@
+"""数据模型。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+
+def parse_time(value: Any) -> datetime:
+    """解析 GitHub 返回的时间，失败时退化为当前时间（UTC）。"""
+    if isinstance(value, str) and value:
+        try:
+            return datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except ValueError:
+            pass
+    return datetime.now(timezone.utc)
+
+
+@dataclass(frozen=True)
+class Release:
+    """一条 GitHub Release。"""
+
+    tag: str
+    name: str
+    url: str
+    body: str
+    published_at: datetime
+    prerelease: bool
+    draft: bool = False
+    # 以下字段只有走 GitHub API 时才有；atom 源拿不到，用于渲染卡片
+    author_login: str = ""
+    author_avatar_url: str = ""
+    reactions: Optional[Dict[str, int]] = None
+
+    @property
+    def title(self) -> str:
+        return self.name or self.tag
+
+    @classmethod
+    def from_github(cls, data: dict) -> Optional["Release"]:
+        tag = str(data.get("tag_name") or "").strip()
+        if not tag:
+            return None
+        author = data.get("author") or {}
+        raw_reactions = data.get("reactions") or {}
+        reactions = {
+            str(key): int(value)
+            for key, value in raw_reactions.items()
+            if isinstance(value, int)
+        } or None
+        return cls(
+            tag=tag,
+            name=str(data.get("name") or tag).strip(),
+            url=str(data.get("html_url") or "").strip(),
+            body=str(data.get("body") or ""),
+            # 草稿没有 published_at，退回 created_at
+            published_at=parse_time(data.get("published_at") or data.get("created_at")),
+            prerelease=bool(data.get("prerelease")),
+            draft=bool(data.get("draft")),
+            author_login=str(author.get("login") or ""),
+            author_avatar_url=str(author.get("avatar_url") or ""),
+            reactions=reactions,
+        )

nonebot_plugin_github_release/plan.py

@@ -0,0 +1,47 @@
+"""纯逻辑：筛选要推的 release、算待推送列表。不依赖 NoneBot，方便单测。"""
+
+from __future__ import annotations
+
+from typing import List, Sequence, Tuple
+
+from .models import Release
+from .store import RepoState
+
+
+def select_releases(
+    releases: Sequence[Release],
+    *,
+    include_prerelease: bool = True,
+    require_body: bool = True,
+) -> List[Release]:
+    """挑出需要推送的 release，按发布时间升序。
+
+    - 草稿（draft）永远不推
+    - `require_body=True`（默认）时，没有正文的不算公告
+    - `include_prerelease=False` 时，alpha / beta / rc 一律不推
+    """
+    selected: List[Release] = []
+    for release in releases:
+        if not release.tag or release.draft:
+            continue
+        if require_body and not release.body.strip():
+            continue
+        if not include_prerelease and release.prerelease:
+            continue
+        selected.append(release)
+    return sorted(selected, key=lambda release: release.published_at)
+
+
+def plan(state: RepoState, releases: Sequence[Release]) -> Tuple[RepoState, List[Release]]:
+    """算待推送列表并返回更新后的状态。
+
+    首次运行只把当前 release 记为基线（不补推历史）；之后返回所有「还没推过的」。
+    """
+    new_state = state.copy()
+    tags = {release.tag for release in releases}
+    if not state.initialized:
+        new_state.initialized = True
+        new_state.pushed = sorted(set(state.pushed) | tags)
+        return new_state, []
+    pushed = set(state.pushed)
+    return new_state, [release for release in releases if release.tag not in pushed]

nonebot_plugin_github_release/render.py

@@ -0,0 +1,174 @@
+"""把 release 正文渲染成群消息文本。"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+from functools import lru_cache
+from typing import List, Optional
+from zoneinfo import ZoneInfo
+
+from .models import Release
+
+_HTML_TAG_RE = re.compile(r"<[^>]+>")
+_HTML_HEADING_RE = re.compile(r"<h[1-6][^>]*>(.*?)</h[1-6]>", re.IGNORECASE | re.DOTALL)
+_HTML_LI_RE = re.compile(r"<li\b[^>]*>", re.IGNORECASE)
+_HTML_BR_RE = re.compile(r"<br\s*/?>", re.IGNORECASE)
+_HTML_BLOCK_RE = re.compile(
+    r"</?(?:p|div|ul|ol|section|article|blockquote|table|tr|td)\b[^>]*>",
+    re.IGNORECASE,
+)
+# atom 源整篇可能挤在一行，先在块级标签后补换行（保留标签本身给后面的清洗用）
+_HTML_BLOCK_BREAK_RE = re.compile(
+    r"</(?:p|div|h[1-6]|li|ul|ol|blockquote|section|article|tr|td)\s*>",
+    re.IGNORECASE,
+)
+_MD_HEADING_RE = re.compile(r"^#{1,6}\s*(.+?)\s*$")
+_MD_LINK_RE = re.compile(r"\[([^\]]+)\]\([^)]+\)")
+_MENTION_RE = re.compile(r"(^|[\s。，、：；）】」!?！？])(@[A-Za-z0-9][A-Za-z0-9._-]*)")
+_BULLET_PREFIXES = ("- ", "* ", "+ ")
+
+# 英文段落的起始标记（中英双语公告的分界）
+_EN_ANCHOR_RE = re.compile(
+    r"""^\s*(?:
+        <h[1-6][^>]*id=["'](?:user-content-)?en(?:-[^"']*)?["'][^>]*>
+        | <h[1-6][^>]*>\s*(?:<a[^>]*>\s*)?english\b
+        | \#{1,6}\s*english\b
+        | \[english\]\(
+    )""",
+    re.IGNORECASE | re.VERBOSE,
+)
+# 顶部的语言切换行：[中文](#cn) | [English](#en)，或剥掉标签后的「中文 | English」
+_LANG_SWITCH_RE = re.compile(
+    r"^\s*\[?中文\]?(?:\([^)]*\))?\s*\|\s*\[?(?:English|EN)\]?(?:\([^)]*\))?\s*$",
+    re.IGNORECASE,
+)
+
+
+def clean_body(
+    text: str, *, strip_mentions: bool = True, cut_foreign: bool = False
+) -> str:
+    """把 Markdown / HTML 清洗成适合展示的纯文本。
+
+    `cut_foreign=True` 时，遇到中英双语正文只保留前半部分（中文段），
+    并丢掉顶部的「中文 | English」切换行。
+    """
+    if cut_foreign:
+        text = cut_foreign_section(text)
+    text = _HTML_BLOCK_BREAK_RE.sub(lambda match: match.group(0) + "\n", text or "")
+    text = _HTML_LI_RE.sub("\n· ", text)
+    text = _HTML_BR_RE.sub("\n", text)
+    text = _HTML_BLOCK_RE.sub("\n", text)
+    text = _HTML_HEADING_RE.sub(
+        lambda match: f"\n▍{_HTML_TAG_RE.sub('', match.group(1)).strip()}\n", text
+    )
+    text = _HTML_TAG_RE.sub("", text)
+    text = _MD_LINK_RE.sub(r"\1", text)
+
+    output: List[str] = []
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line:
+            output.append("")
+            continue
+        heading = _MD_HEADING_RE.match(line)
+        if heading is not None:
+            line = f"▍{heading.group(1)}"
+        elif line.startswith(_BULLET_PREFIXES):
+            line = "· " + line[2:].strip()
+        line = line.replace("`", "").replace("**", "")
+        if strip_mentions:
+            line = _MENTION_RE.sub(r"\1", line)
+        output.append(line.rstrip())
+
+    result = re.sub(r"\n{3,}", "\n\n", "\n".join(output)).strip()
+    # 中英双语公告用 --- 分隔，落在末尾就是噪音
+    return re.sub(r"(?:\n\s*(?:-{3,}|\*{3,}|_{3,})\s*)+\s*$", "", result).strip()
+
+
+def cut_foreign_section(body: str) -> str:
+    """只保留中英双语正文的前半部分（中文段）。
+
+    必须在其它清洗之前调用——清洗会把 `<h3 id="en-x">English</h3>` 变成
+    `▍English`，那时就认不出分界了。
+    """
+    body = _HTML_BLOCK_BREAK_RE.sub(lambda match: match.group(0) + "\n", body or "")
+    lines: List[str] = []
+    for raw in body.splitlines():
+        if _EN_ANCHOR_RE.match(raw.strip()):
+            break
+        plain = _HTML_TAG_RE.sub("", raw).strip()
+        if _LANG_SWITCH_RE.match(plain):
+            continue
+        lines.append(raw)
+    return "\n".join(lines)
+
+
+def truncate_text(text: str, max_chars: int) -> str:
+    """按行截断，尽量不破坏行结构。"""
+    if max_chars <= 0 or len(text) <= max_chars:
+        return text
+    kept: List[str] = []
+    total = 0
+    for line in text.splitlines():
+        if total + len(line) + 1 > max_chars:
+            break
+        kept.append(line)
+        total += len(line) + 1
+    if not kept:
+        return text[:max_chars].rstrip() + "…"
+    return "\n".join(kept).rstrip() + "\n…（正文较长，完整内容见下方链接）"
+
+
+@lru_cache(maxsize=8)
+def resolve_timezone(name: str) -> timezone:
+    """解析时区名，失败退回 UTC（Windows 上需要 tzdata）。"""
+    try:
+        return ZoneInfo(name)  # type: ignore[return-value]
+    except Exception:
+        return timezone.utc
+
+
+def format_local_time(moment: Optional[datetime], tz_name: str) -> str:
+    if moment is None:
+        return "-"
+    if moment.tzinfo is None:
+        moment = moment.replace(tzinfo=timezone.utc)
+    return moment.astimezone(resolve_timezone(tz_name)).strftime("%Y-%m-%d %H:%M")
+
+
+def format_iso_local(value: Optional[str], tz_name: str) -> str:
+    if not value:
+        return "-"
+    try:
+        moment = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return value
+    return format_local_time(moment, tz_name)
+
+
+def render_release(
+    release: Release,
+    *,
+    repo: str,
+    tz_name: str = "Asia/Shanghai",
+    max_chars: int = 600,
+    strip_mentions: bool = True,
+    cut_foreign: bool = True,
+) -> str:
+    """渲染纯文本推送内容。"""
+    body = truncate_text(
+        clean_body(release.body, strip_mentions=strip_mentions, cut_foreign=cut_foreign),
+        max_chars,
+    )
+    stage = "预发布" if release.prerelease else "正式版"
+
+    parts = [f"【{repo} {stage}】{release.title}"]
+    published = format_local_time(release.published_at, tz_name)
+    if published != "-":
+        parts.append(f"发布时间：{published}")
+    if body:
+        parts.append(body)
+    if release.url:
+        parts.append(f"完整公告：{release.url}")
+    return "\n".join(parts)

nonebot_plugin_github_release/source.py

@@ -0,0 +1,170 @@
+"""拉取 GitHub 仓库的 release。
+
+两个数据源，自动兜底：
+
+1. GitHub Releases API（首选，字段完整，匿名限额 60 次/小时）
+2. `releases.atom`（网页订阅源，不限流，但拿不到表情计数等字段）
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List
+from xml.etree import ElementTree
+
+import httpx
+
+from .config import Config
+from .models import Release, parse_time
+from .versions import parse_version
+
+_USER_AGENT = "nonebot-plugin-github-release/0.1.0"
+_API_ROOT = "https://api.github.com"
+_ATOM_NS = {"atom": "http://www.w3.org/2005/Atom"}
+
+
+class ReleaseFetchError(RuntimeError):
+    """拉取失败。"""
+
+
+@dataclass
+class FetchResult:
+    """一次拉取的结果。"""
+
+    repo: str
+    releases: List[Release]
+    source: str  # "api" 或 "atom"
+
+
+def _client_kwargs(cfg: Config) -> Dict[str, Any]:
+    kwargs: Dict[str, Any] = {
+        "timeout": httpx.Timeout(20.0, connect=10.0),
+        "follow_redirects": True,
+    }
+    if cfg.gh_watch_proxy:
+        kwargs["proxy"] = cfg.gh_watch_proxy
+    return kwargs
+
+
+def _headers(cfg: Config, accept: str = "application/vnd.github+json") -> Dict[str, str]:
+    headers = {
+        "Accept": accept,
+        "User-Agent": _USER_AGENT,
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+    token = (cfg.gh_watch_github_token or "").strip()
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    return headers
+
+
+async def fetch_releases(
+    cfg: Config, repo: str, *, per_page: int = 30
+) -> FetchResult:
+    """拉取某个仓库最近的 release，API 不行就走 atom。"""
+    errors: List[str] = []
+    try:
+        return FetchResult(repo, await _fetch_from_api(cfg, repo, per_page=per_page), "api")
+    except ReleaseFetchError as exc:
+        errors.append(f"接口：{exc}")
+
+    try:
+        return FetchResult(repo, await _fetch_from_atom(cfg, repo), "atom")
+    except ReleaseFetchError as exc:
+        errors.append(f"订阅源：{exc}")
+
+    raise ReleaseFetchError("；".join(errors))
+
+
+async def _fetch_from_api(cfg: Config, repo: str, *, per_page: int = 30) -> List[Release]:
+    """走 Releases API。
+
+    注意不能用 `/releases/latest`——仓库只发预发布版时它会返回 404。
+    """
+    url = f"{_API_ROOT}/repos/{repo}/releases"
+    try:
+        async with httpx.AsyncClient(**_client_kwargs(cfg)) as client:
+            response = await client.get(
+                url,
+                params={"per_page": max(1, min(per_page, 100))},
+                headers=_headers(cfg),
+            )
+            response.raise_for_status()
+            payload = response.json()
+    except httpx.HTTPStatusError as exc:
+        status = exc.response.status_code
+        hint = ""
+        if status == 404:
+            hint = "（仓库不存在或没有 release 权限）"
+        elif status in (403, 429):
+            hint = "（可能触发了 GitHub 限流，可配置 GH_WATCH_GITHUB_TOKEN）"
+        raise ReleaseFetchError(f"HTTP {status}{hint}") from exc
+    except httpx.HTTPError as exc:
+        raise ReleaseFetchError(f"{exc.__class__.__name__}: {exc}") from exc
+    except ValueError as exc:
+        raise ReleaseFetchError(f"响应无法解析：{exc}") from exc
+
+    if not isinstance(payload, list):
+        raise ReleaseFetchError("返回了非预期的数据结构")
+
+    releases: List[Release] = []
+    for item in payload:
+        if isinstance(item, dict):
+            release = Release.from_github(item)
+            if release is not None:
+                releases.append(release)
+    return releases
+
+
+async def _fetch_from_atom(cfg: Config, repo: str) -> List[Release]:
+    """走 releases.atom（不限流）。"""
+    url = f"https://github.com/{repo}/releases.atom"
+    try:
+        async with httpx.AsyncClient(**_client_kwargs(cfg)) as client:
+            response = await client.get(
+                url, headers=_headers(cfg, "application/atom+xml")
+            )
+            response.raise_for_status()
+            payload = response.text
+    except httpx.HTTPStatusError as exc:
+        raise ReleaseFetchError(f"HTTP {exc.response.status_code}") from exc
+    except httpx.HTTPError as exc:
+        raise ReleaseFetchError(f"{exc.__class__.__name__}: {exc}") from exc
+
+    return parse_atom(payload)
+
+
+def parse_atom(payload: str) -> List[Release]:
+    """解析 releases.atom 文本。"""
+    try:
+        root = ElementTree.fromstring(payload)
+    except ElementTree.ParseError as exc:
+        raise ReleaseFetchError(f"订阅源不是合法 XML：{exc}") from exc
+
+    releases: List[Release] = []
+    for entry in root.findall("atom:entry", _ATOM_NS):
+        title = (entry.findtext("atom:title", default="", namespaces=_ATOM_NS) or "").strip()
+        link = entry.find("atom:link", _ATOM_NS)
+        href = (link.get("href") if link is not None else "") or ""
+        updated = entry.findtext("atom:updated", default="", namespaces=_ATOM_NS) or ""
+        content = entry.findtext("atom:content", default="", namespaces=_ATOM_NS) or ""
+
+        # href 形如 https://github.com/<owner>/<repo>/releases/tag/<tag>
+        tag = href.rstrip("/").rsplit("/", 1)[-1] if "/tag/" in href else title
+        if not tag:
+            continue
+        version = parse_version(tag)
+        releases.append(
+            Release(
+                tag=tag,
+                name=title or tag,
+                url=href,
+                body=content,
+                published_at=parse_time(updated),
+                # atom 不含 prerelease 标记，只能从版本号推断
+                prerelease=bool(version and not version.is_stable),
+            )
+        )
+    if not releases:
+        raise ReleaseFetchError("订阅源里没有可用条目")
+    return releases