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

nonebot_plugin_github_release/store.py

@@ -0,0 +1,147 @@
+"""状态与订阅的持久化（JSON，原子写入）。
+
+- `state.json`：每个仓库的推送基线
+- `subscriptions.json`：哪个群订阅了哪个仓库
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set
+
+from .config import Config
+
+
+def resolve_data_dir(cfg: Config) -> Path:
+    """插件数据目录：优先用 nonebot-plugin-localstore，退化为 data/<插件名>。"""
+    if cfg.gh_watch_data_dir:
+        return Path(cfg.gh_watch_data_dir).expanduser()
+    try:
+        import nonebot_plugin_localstore as store
+
+        return store.get_plugin_data_dir()
+    except Exception:  # noqa: BLE001 - 没装 localstore 或未初始化时退化
+        return Path("data") / "github_release"
+
+
+def state_path(data_dir: Path) -> Path:
+    return data_dir / "state.json"
+
+
+def subscriptions_path(data_dir: Path) -> Path:
+    return data_dir / "subscriptions.json"
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+@dataclass
+class RepoState:
+    """单个仓库的监控状态。"""
+
+    initialized: bool = False
+    pushed: List[str] = field(default_factory=list)
+    latest: Optional[str] = None
+    last_check: Optional[str] = None
+    last_ok: Optional[str] = None
+    last_error: Optional[str] = None
+    last_source: Optional[str] = None
+
+    def copy(self) -> "RepoState":
+        return RepoState(
+            initialized=self.initialized,
+            pushed=list(self.pushed),
+            latest=self.latest,
+            last_check=self.last_check,
+            last_ok=self.last_ok,
+            last_error=self.last_error,
+            last_source=self.last_source,
+        )
+
+    @classmethod
+    def from_dict(cls, raw: Any) -> "RepoState":
+        if not isinstance(raw, dict):
+            return cls()
+        pushed = raw.get("pushed")
+        return cls(
+            initialized=bool(raw.get("initialized")),
+            pushed=[str(tag) for tag in pushed if isinstance(tag, str)]
+            if isinstance(pushed, list)
+            else [],
+            latest=raw.get("latest") or None,
+            last_check=raw.get("last_check") or None,
+            last_ok=raw.get("last_ok") or None,
+            last_error=raw.get("last_error") or None,
+            last_source=raw.get("last_source") or None,
+        )
+
+
+def _atomic_write_json(path: Path, payload: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(path.name + ".tmp")
+    tmp.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def _load_json(path: Path) -> Any:
+    if not path.exists():
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+
+
+def load_states(path: Path) -> Dict[str, RepoState]:
+    """读取所有仓库状态；文件缺失或损坏时返回空表。"""
+    raw = _load_json(path)
+    if not isinstance(raw, dict):
+        return {}
+    repos = raw.get("repos")
+    source = repos if isinstance(repos, dict) else raw
+    return {
+        str(name): RepoState.from_dict(value)
+        for name, value in source.items()
+        if isinstance(name, str)
+    }
+
+
+def save_states(path: Path, states: Dict[str, RepoState]) -> None:
+    payload = {"repos": {name: asdict(state) for name, state in sorted(states.items())}}
+    for value in payload["repos"].values():
+        value["pushed"] = sorted(set(value["pushed"]))
+    _atomic_write_json(path, payload)
+
+
+def load_subscriptions(path: Path) -> Dict[str, Set[int]]:
+    """读取「仓库 → 订阅群」映射。"""
+    raw = _load_json(path)
+    if not isinstance(raw, dict):
+        return {}
+    result: Dict[str, Set[int]] = {}
+    for repo, groups in raw.items():
+        if not isinstance(repo, str) or not isinstance(groups, list):
+            continue
+        parsed: Set[int] = set()
+        for item in groups:
+            try:
+                parsed.add(int(item))
+            except (TypeError, ValueError):
+                continue
+        if parsed:
+            result[repo] = parsed
+    return result
+
+
+def save_subscriptions(path: Path, subscriptions: Dict[str, Set[int]]) -> None:
+    payload = {
+        repo: sorted(groups)
+        for repo, groups in sorted(subscriptions.items())
+        if groups
+    }
+    _atomic_write_json(path, payload)

nonebot_plugin_github_release/versions.py

@@ -0,0 +1,52 @@
+"""版本号解析与「正式版」判定。"""
+
+from __future__ import annotations
+
+import re
+from typing import NamedTuple, Optional
+
+# 兼容 `v0.1.5`、`dsh-v0.1.5`、`dsh-v0.1.5-rc.1` 这几种 tag 写法
+_TAG_RE = re.compile(
+    r"^(?:[^0-9]*?)v?(\d+)\.(\d+)\.(\d+)"
+    r"(?:-([0-9A-Za-z.\-]+))?"
+    r"(?:\+[0-9A-Za-z.\-]+)?$"
+)
+
+
+class Version(NamedTuple):
+    """语义化版本。"""
+
+    major: int
+    minor: int
+    patch: int
+    prerelease: Optional[str]
+
+    @property
+    def is_stable(self) -> bool:
+        """没有预发布后缀才算正式版。"""
+        return self.prerelease is None
+
+    @property
+    def core(self) -> str:
+        return f"{self.major}.{self.minor}.{self.patch}"
+
+
+def parse_version(tag: str) -> Optional[Version]:
+    """解析 tag 中的版本号，解析不出来返回 None。"""
+    match = _TAG_RE.match((tag or "").strip())
+    if match is None:
+        return None
+    major, minor, patch, prerelease = match.groups()
+    return Version(int(major), int(minor), int(patch), prerelease)
+
+
+def is_stable_release(tag: str, *, prerelease_flag: bool = False) -> bool:
+    """判断是否为正式版。
+
+    两个条件同时满足才算正式版：GitHub 没有标记为 prerelease，且 tag 中没有
+    预发布后缀。解析不出版本号的 tag（例如 `nightly`）一律不算，避免误报。
+    """
+    if prerelease_flag:
+        return False
+    version = parse_version(tag)
+    return bool(version and version.is_stable)

nonebot_plugin_github_release/watch.py

@@ -0,0 +1,198 @@
+"""定时检查 + 推送。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional, Set, Tuple
+
+import nonebot
+from nonebot.adapters.onebot.v11 import Bot as OneBotV11Bot
+from nonebot.adapters.onebot.v11 import Message, MessageSegment
+from nonebot.log import logger
+
+from .card import render_card
+from .config import Config, load_config
+from .models import Release
+from .plan import plan, select_releases
+from .render import render_release
+from .source import ReleaseFetchError, fetch_releases
+from .store import (
+    RepoState,
+    load_states,
+    load_subscriptions,
+    now_iso,
+    resolve_data_dir,
+    save_states,
+    state_path,
+    subscriptions_path,
+)
+
+
+@dataclass
+class CheckResult:
+    """一次检查的结果。"""
+
+    status: str
+    detail: str
+    repo_count: int = 0
+    pushed: List[str] = field(default_factory=list)
+    failed: List[str] = field(default_factory=list)
+    errors: List[str] = field(default_factory=list)
+
+
+def effective_subscriptions(
+    cfg: Config, stored: Dict[str, Set[int]]
+) -> Dict[str, Set[int]]:
+    """配置里的默认订阅 + 群内动态订阅。
+
+    `GH_WATCH_REPOS × GH_WATCH_GROUPS` 的组合等价于「这些群都订阅这些仓库」。
+    """
+    result: Dict[str, Set[int]] = {repo: set(groups) for repo, groups in stored.items()}
+    default_groups = set(cfg.gh_watch_groups)
+    for repo in cfg.gh_watch_repos:
+        result.setdefault(repo, set()).update(default_groups)
+    return {repo: groups for repo, groups in result.items() if groups}
+
+
+async def build_announce_message(release: Release, repo: str, cfg: Config) -> "str | Message":
+    """构造要发送的消息：优先卡片图，失败回退纯文本。"""
+    if cfg.gh_watch_send_image:
+        png = await render_card(
+            release,
+            repo=repo,
+            max_chars=cfg.gh_watch_card_max_chars,
+            show_reactions=cfg.gh_watch_card_show_reactions,
+            cut_foreign=cfg.gh_watch_body_language != "all",
+            width=cfg.gh_watch_card_width,
+            body_max_height=cfg.gh_watch_card_max_height,
+        )
+        if png is not None:
+            stage = "预发布" if release.prerelease else "正式版"
+            # 图片里的链接点不了，附一行文字方便复制
+            caption = f"【{repo} {stage}】{release.title}\n完整公告：{release.url}"
+            return Message(MessageSegment.image(png)) + f"\n{caption}"
+
+    return render_release(
+        release,
+        repo=repo,
+        tz_name=cfg.gh_watch_timezone,
+        max_chars=cfg.gh_watch_max_chars,
+        strip_mentions=cfg.gh_watch_strip_mentions,
+        cut_foreign=cfg.gh_watch_body_language != "all",
+    )
+
+
+async def push_to_groups(
+    message: "str | Message", groups: Iterable[int]
+) -> Tuple[List[int], List[str]]:
+    """推送消息，返回 (成功的群, 错误信息)。"""
+    try:
+        bots = [
+            bot for bot in nonebot.get_bots().values() if isinstance(bot, OneBotV11Bot)
+        ]
+    except Exception as exc:  # pragma: no cover - 依赖运行时状态
+        return [], [f"获取机器人实例失败：{exc.__class__.__name__}: {exc}"]
+
+    if not bots:
+        return [], ["当前没有已连接的 OneBot V11 机器人"]
+
+    succeeded: List[int] = []
+    errors: List[str] = []
+    for group_id in groups:
+        for bot in bots:
+            try:
+                await bot.send_group_msg(group_id=int(group_id), message=message)
+            except Exception as exc:  # noqa: BLE001 - 发送失败原因很多，统一记录
+                errors.append(
+                    f"群 {group_id} 推送失败（bot {bot.self_id}）："
+                    f"{exc.__class__.__name__}: {exc}"
+                )
+                continue
+            succeeded.append(int(group_id))
+            break
+    return succeeded, errors
+
+
+async def check_once(cfg: Optional[Config] = None) -> CheckResult:
+    """遍历所有订阅的仓库，把新 release 推到对应的群。"""
+    cfg = cfg or load_config()
+    data_dir = resolve_data_dir(cfg)
+    states_file = state_path(data_dir)
+    states = load_states(states_file)
+    subscriptions = effective_subscriptions(cfg, load_subscriptions(subscriptions_path(data_dir)))
+
+    if not subscriptions:
+        return CheckResult(
+            status="no-repo",
+            detail="没有任何订阅：在群里发 /gh订阅 owner/repo，或配置 GH_WATCH_REPOS",
+        )
+
+    pushed: List[str] = []
+    failed: List[str] = []
+    errors: List[str] = []
+    limit = max(1, cfg.gh_watch_max_per_round)
+
+    for repo, groups in sorted(subscriptions.items()):
+        state = states.get(repo) or RepoState()
+        try:
+            fetched = await fetch_releases(cfg, repo)
+        except ReleaseFetchError as exc:
+            state.last_check = now_iso()
+            state.last_error = str(exc)
+            states[repo] = state
+            save_states(states_file, states)
+            errors.append(f"{repo}：{exc}")
+            logger.warning(f"[gh-release] {repo} 拉取失败：{exc}")
+            continue
+
+        announcements = select_releases(
+            fetched.releases,
+            include_prerelease=cfg.gh_watch_include_prerelease,
+            require_body=cfg.gh_watch_require_body,
+        )
+        state, pending = plan(state, announcements)
+        state.last_check = now_iso()
+        state.last_ok = now_iso()
+        state.last_error = None
+        state.last_source = fetched.source
+        if announcements:
+            state.latest = announcements[-1].tag
+        states[repo] = state
+        save_states(states_file, states)
+
+        for release in pending[:limit]:
+            message = await build_announce_message(release, repo, cfg)
+            succeeded, send_errors = await push_to_groups(message, groups)
+            errors.extend(send_errors)
+            for error in send_errors:
+                logger.warning(f"[gh-release] {error}")
+            if succeeded:
+                state.pushed = sorted(set(state.pushed) | {release.tag})
+                states[repo] = state
+                save_states(states_file, states)
+                pushed.append(f"{repo} {release.tag}")
+                logger.success(f"[gh-release] 已推送 {repo} {release.tag} 到 {len(succeeded)} 个群")
+            else:
+                failed.append(f"{repo} {release.tag}")
+
+    if pushed:
+        detail = "已推送 " + "、".join(pushed)
+        if failed or errors:
+            detail += f"（{len(failed)} 条失败、{len(errors)} 条错误）"
+        status = "pushed"
+    elif errors:
+        status = "error"
+        detail = "；".join(errors[:3])
+    else:
+        status = "no-update"
+        detail = f"没有新 release（监控 {len(subscriptions)} 个仓库）"
+
+    return CheckResult(
+        status=status,
+        detail=detail,
+        repo_count=len(subscriptions),
+        pushed=pushed,
+        failed=failed,
+        errors=errors,
+    )

nonebot_plugin_github_release-0.1.0.dist-info/METADATA

@@ -0,0 +1,109 @@
+Metadata-Version: 2.5
+Name: nonebot-plugin-github-release
+Version: 0.1.0
+Summary: 监控任意 GitHub 仓库的 release，把新版本推送到 QQ 群
+Project-URL: Homepage, https://github.com/NSQX13579/nonebot-plugin-github-release
+Project-URL: Repository, https://github.com/NSQX13579/nonebot-plugin-github-release
+Author-email: ns <102937666+NSQX13579@users.noreply.github.com>
+License: MIT License
+        
+        Copyright (c) 2026 ns
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: github,nonebot,nonebot2,release,watch
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.26
+Requires-Dist: nonebot-adapter-onebot>=2.4.0
+Requires-Dist: nonebot-plugin-apscheduler>=0.5.0
+Requires-Dist: nonebot-plugin-localstore>=0.7.0
+Requires-Dist: nonebot2>=2.4.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: tzdata; sys_platform == 'win32'
+Provides-Extra: image
+Requires-Dist: nonebot-plugin-htmlrender>=0.6.7; extra == 'image'
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# nonebot-plugin-github-release
+
+监控任意 GitHub 仓库的 release，把新版本推送到 QQ 群。按群订阅，每个群只收自己关心的仓库。
+
+本插件由 [nonebot-plugin-dsh-release](https://github.com/NSQX13579/nonebot-plugin-dsh-release) 改进而得。
+
+## 安装
+
+```bash
+pip install nonebot-plugin-github-release
+playwright install chromium        # 卡片图片需要，不装会自动回退纯文本
+```
+
+依赖 `nonebot-plugin-apscheduler`（定时）和 `nonebot-plugin-localstore`（数据目录），装包时会一并带上。
+
+## 配置
+
+`.env`（完整模板见 `.env.example`）：
+
+```dotenv
+# 监控哪些仓库（留空也行，直接在群里 /gh订阅 更灵活）
+GH_WATCH_REPOS=[]
+GH_WATCH_GROUPS=[]
+
+# 可选：匿名 API 限额 60 次/小时且按出口 IP 共享，多仓库建议配上
+GH_WATCH_GITHUB_TOKEN=
+```
+
+插件不带任何默认仓库——用群里的 `/gh订阅 owner/repo` 加，或者把上面的列表填上。
+
+## 指令
+
+| 指令 | 权限 | 说明 |
+| --- | --- | --- |
+| `/gh订阅 owner/repo` | 群管 | 本群订阅某个仓库 |
+| `/gh退订 owner/repo` | 群管 | 取消订阅 |
+| `/gh列表` | 所有人 | 看本群订阅了哪些仓库 |
+| `/gh公告 owner/repo` | 所有人 | 最新一条 release 全文 |
+| `/gh公告 owner/repo 5` | 所有人 | 列最近 5 条（最多 10） |
+| `/gh公告 owner/repo v1.2` | 所有人 | 按版本号检索 |
+| `/gh状态` | 所有人 | 推送状态 |
+| `/gh检查` | 超管 | 立刻检查一次，不等下一轮 |
+
+## 消息长什么样
+
+![示例](docs/card-example.png)
+
+图下面另附一行带链接的文字——图片里的地址点不了。卡片上的头像、发布时间、版本号、正文、表情计数都是 GitHub 的真实数据。
+
+**渲染出任何问题都会回退纯文本**（没装 htmlrender、没装 chromium、超时都算），只打一条警告日志，推送不受影响。
+
+## 行为说明
+
+- 数据源：Releases API 为主，被限流时自动切到不限流的 `releases.atom`
+- 首次运行只建推送基线，不会把历史 release 刷进群
+- 以 tag 去重，失败的不写进已推送列表，下一轮自然重试
+- 中英双语正文默认只保留中文段，`GH_WATCH_BODY_LANGUAGE=all` 可改成两段都留
+- `GH_WATCH_INCLUDE_PRERELEASE=False` 则只推正式版
+
+## License
+
+MIT

nonebot_plugin_github_release-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+nonebot_plugin_github_release/__init__.py,sha256=r0gyMcjx9Zp-FESRBdzm1qrPD6MwacRSspDc-m6qAFE,2261
+nonebot_plugin_github_release/card.py,sha256=iQGQkCLFCuNNMUCkBDJZB7R5CU3VRiIoX-3xDU_GoA8,12326
+nonebot_plugin_github_release/commands.py,sha256=hhjSEUjOWZ-Wo3EShBHOyKI5Kpu0T_iI8R0d_CKYvAY,9982
+nonebot_plugin_github_release/config.py,sha256=jX1kOBKTciNclKrx-HMhGd20bgVcLm5eVOLT3gHiyMI,2117
+nonebot_plugin_github_release/latest.py,sha256=kK30Y262aYogkKINlg0QfXYz8d-NEEipOccMtdQawqQ,1972
+nonebot_plugin_github_release/models.py,sha256=t6VNTclLlZNromcdsU8Lyq5JnBlh943KINRnZj83QeM,2031
+nonebot_plugin_github_release/plan.py,sha256=QJm5LqINleSyWwjSWW5dBRD1jgtvupSE2vNoq-Dicko,1648
+nonebot_plugin_github_release/render.py,sha256=rb8R8rdK7YaOOw-KKggpBfGHtR9tNMsQCWDTRRy8uM0,6004
+nonebot_plugin_github_release/source.py,sha256=mVAGwGslOSIeX_0JqAxf12JkBWqAmIw08hakDVGVTyM,5802
+nonebot_plugin_github_release/store.py,sha256=0fkqDbFHny0yZj3Zn-l6Dkbx3cWnYaNthhhV7-zPC9s,4520
+nonebot_plugin_github_release/versions.py,sha256=qBS2O8RPF5M4tLW-mFxCwX9GolFKEHugoH2ekjZZwjg,1492
+nonebot_plugin_github_release/watch.py,sha256=mBvdUuM3zVGoPuIOL5CPTSvEUAcV06lqMr5WjkRBhiY,7026
+nonebot_plugin_github_release-0.1.0.dist-info/METADATA,sha256=fcK9tVX2mOLxJAQGQgLNSIY7Q4hpD-ZyKJbmXIuqDMA,4655
+nonebot_plugin_github_release-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+nonebot_plugin_github_release-0.1.0.dist-info/licenses/LICENSE,sha256=0WfBnUlo5DQbHA5SAIVlDFlYbkIzl0OkjiI7DqTC7CA,1059
+nonebot_plugin_github_release-0.1.0.dist-info/RECORD,,

nonebot_plugin_github_release-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

nonebot_plugin_github_release-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ns
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.