@zhin.js/plugin-bilibili 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @zhin.js/plugin-bilibili
+
+## 0.1.1
+
+### Patch Changes
+
+- c67e43d: 取消某 UP 主的最后一个订阅时，同步清理 watcher 中该 UP 的退避记录，避免已退订 UID 的条目残留。
+- e40899f: Adapters now project group owners and admins onto the canonical `sender.roles` names `owner` / `admin` (Telegram creator/administrator, KOOK guild owner and admin-permission roles, Lark chat owner/managers, QQ official guild owner/admin identities). KOOK numeric role ids moved from `roles` to `permissions` (`role:<id>`). `@zhin.js/command` exports `canManageConversation` ("private chat or owner/admin/master"), now shared by the Bilibili and earthquake subscription commands; Roulette lets owners and admins toggle the mute penalty and cancel a game.
+- 66fc5dd: Add `@zhin.js/plugin-bilibili`: per-conversation Bilibili live-start and UP dynamic subscriptions (`bili sub|unsub|list|live`), a conservative scheduled watcher with jitter, exponential backoff, baseline-first dedupe and WBI signing, database persistence with an in-memory fallback, and read-only agent tools `bili_live_status` / `bili_list_subscriptions`. In groups and channels `bili sub` / `bili unsub` are limited to the group owner, admins and the bot master; private chats can manage their own subscriptions.
+- Updated dependencies [1a11207]
+- Updated dependencies [9943df6]
+  - @zhin.js/tool@1.1.8
+  - @zhin.js/skill@1.1.8

package/README.md

@@ -1,3 +1,137 @@
-# Temporary Holding Version
+# @zhin.js/plugin-bilibili
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+订阅 B 站（哔哩哔哩）UP 主的**开播提醒**和**新动态**，推送到订阅所在的私聊、群聊或频道。与平台无关：任何接入了 OutboundHost 的适配器都可以用。
+
+Subscribe to Bilibili live starts and UP dynamics per conversation. Platform-agnostic: works with any adapter that exposes the OutboundHost. English below.
+
+## 安装
+
+```bash
+pnpm exec zhin install @zhin.js/plugin-bilibili
+```
+
+对应的 `zhin.config.yml`：
+
+```yaml
+configVersion: 2
+plugins:
+  bilibili: "@zhin.js/plugin-bilibili"
+bilibili:
+  pollCron: "0 * * * * *"   # 每 60 秒一轮
+  jitterMs: 15000            # 每轮随机延迟 0–15 秒
+  # cookie: ${BILIBILI_COOKIE}  # 可选，风控严格时再配
+```
+
+推送需要 Runtime 提供 Schedule（定时任务）和 Outbound（主动发消息）；订阅持久化需要配置数据库，没有数据库时订阅只保存在内存里，重启即丢失。
+
+## 配置
+
+| 字段 | 默认值 | 说明 |
+| --- | --- | --- |
+| `pollCron` | `0 * * * * *` | 轮询频率（6 段 Cron），默认每 60 秒 |
+| `jitterMs` | `15000` | 每轮开始前的随机延迟上限，避免整点并发 |
+| `requestGapMs` | `1500` | 同一轮里相邻两个 UP 主的动态请求间隔 |
+| `maxBackoffMinutes` | `30` | 失败后指数退避（1、2、4… 分钟）的上限；风控响应退避更久 |
+| `maxPerChannel` | `20` | 每个会话最多订阅多少个 UP 主 |
+| `timeout` | `10000` | 单次 HTTP 请求超时（毫秒） |
+| `live` / `dynamic` | `true` | 分别开关开播轮询和动态轮询 |
+| `cookie` | `""` | 可选 Cookie（如 `SESSDATA=...`）。写成 `${BILIBILI_COOKIE}`，把值放进 `.env`，不要提交到仓库 |
+
+## 命令
+
+| 命令 | 说明 |
+| --- | --- |
+| `bili sub <uid> [all\|live\|dynamic]` | 订阅 UP 主，`uid` 也可以是空间链接；类型默认 `all`（开播 + 动态），也可写 `直播` / `动态`。对已订阅的 UP 主再执行一次可修改类型 |
+| `bili unsub <uid>` | 取消当前会话的订阅 |
+| `bili list` | 查看当前会话的订阅，以及正在退避的请求 |
+| `bili live <房间号>` | 查询直播间状态，支持 `https://live.bilibili.com/...` 链接 |
+
+订阅按「适配器 + 机器人账号 + 会话」隔离，不同群互不影响。
+
+### 权限
+
+- 群聊和频道里，`bili sub` / `bili unsub` 只有**群主、群管理员或机器人主人**（`role(owner,admin,master)`）能用，其他成员会收到提示，订阅不会改动。
+- 私聊里任何人都可以订阅、取消自己这个私聊会话。
+- `bili list`、`bili live` 是只读命令，不限制。
+
+角色来自适配器给出的平台无关身份 `sender.role`（如 icqq / OneBot 的 `owner`、`admin`，以及主人账号的 `master`），判断用的是命令路由同一套内置 permit 检查。适配器拿不到群角色时，群里只有机器人主人能管理订阅。
+
+## AI 工具
+
+技能 `bilibili` 提供两个只读工具：
+
+- `bili_live_status`：按直播间号或 UID 查询是否在播。
+- `bili_list_subscriptions`：列出全部订阅。
+
+订阅的增删只走聊天命令。
+
+## 工作原理
+
+- **开播**：所有被订阅的 UP 主合并成一次批量请求（`get_status_info_by_uids`，无需登录）。从「未开播 / 轮播」变为「直播中」，或者开播时间变化（说明是新的一场）时推送一次。
+- **动态**：逐个请求 UP 主空间动态（`x/polymer/web-dynamic/v1/feed/space`，带 WBI 签名和匿名 `buvid3`），按发布时间和已推送 ID 双重去重；置顶的旧动态不会推送，单个 UP 主每轮最多推 3 条。直播推荐类动态交给开播提醒处理。
+- **首次观察只记基线**：新订阅或重启后的第一轮不推送历史内容。
+- **降级**：接口返回格式变了、风控（`-352`、`-412`、`-799`、HTTP 412）或网络错误时，不会让定时任务失败，只在日志里提示并对该来源指数退避，`bili list` 里能看到恢复时间。风控时会丢弃缓存的 WBI 密钥和设备 ID，下次重新获取。
+
+## 数据库
+
+| 表 | 用途 |
+| --- | --- |
+| `bilibili_subscriptions` | 订阅：`uid`、`uname`、`kinds`、会话地址、创建人 |
+| `bilibili_watch_state` | 每个 UP 主的开播状态、动态游标、最近推送过的动态 ID |
+
+取消最后一个订阅时会清掉对应 UP 主的游标。
+
+## 注意事项
+
+- 这些都是 B 站网页端的非公开接口，随时可能变化。动态接口对匿名请求和机房 IP 风控很严：可能返回 412 / -352，也可能悄悄返回空列表。插件把空列表当成「本轮没拿到」，不会据此建立基线或推送旧内容；超过 6 小时的动态只记为已读、不推送。长期拿不到动态时，可以配置登录后的 `cookie`，或只开 `live`。
+- 请保持保守的轮询频率，不要把 `pollCron` 调到几秒一次。
+
+---
+
+## English
+
+### Install
+
+```bash
+pnpm exec zhin install @zhin.js/plugin-bilibili
+```
+
+```yaml
+configVersion: 2
+plugins:
+  bilibili: "@zhin.js/plugin-bilibili"
+bilibili:
+  pollCron: "0 * * * * *"
+  # cookie: ${BILIBILI_COOKIE}
+```
+
+Pushing needs the Schedule and Outbound hosts; persistence needs a configured database (otherwise subscriptions are kept in memory).
+
+### Commands
+
+- `bili sub <uid> [all|live|dynamic]`: subscribe the current conversation (uid or space URL). Running it again changes the kind.
+- `bili unsub <uid>`: unsubscribe.
+- `bili list`: list subscriptions and sources currently backing off.
+- `bili live <room>`: show a live room's status (room id or URL).
+
+**Permissions:** in groups and channels, `bili sub` / `bili unsub` are limited to the group owner, group admins and the bot master (`role(owner,admin,master)`); other members get a notice and nothing changes. In private chat anyone can manage their own conversation. `bili list` and `bili live` are read-only and unrestricted. Roles come from the adapter's platform-agnostic `sender.role` and are checked with the same built-in permit checker the command router uses; if an adapter does not report group roles, only the bot master can manage group subscriptions.
+
+### Configuration
+
+`pollCron` (default every 60s), `jitterMs` (random delay before each poll), `requestGapMs`, `maxBackoffMinutes`, `maxPerChannel`, `timeout`, `live`, `dynamic`, and an optional `cookie` that should be referenced as `${BILIBILI_COOKIE}` from `.env`.
+
+### How it works
+
+Live status is polled in one batched, unauthenticated request; a push happens on the offline→live transition or when a new session start time appears. Dynamics are fetched per UP from the WBI-signed space feed with an anonymous `buvid3` cookie, deduplicated by publish time and pushed IDs; old pinned items are ignored and at most 3 items per UP are pushed per tick. The first observation only records a baseline. Payload changes, risk control (`-352`, `-412`, `-799`, HTTP 412) and network errors never fail the scheduled job: the affected source backs off exponentially and `bili list` shows when it will retry.
+
+### Caveats
+
+These are undocumented Bilibili web endpoints and may change. The dynamic feed is aggressively risk-controlled for anonymous and datacenter clients: it may answer 412 / -352 or silently return an empty list. Empty answers are never used as a baseline, and dynamics older than 6 hours are marked seen without being pushed. Configure a logged-in `cookie`, or enable `live` only, if dynamics keep failing.
+
+## AI tools
+
+`bili_live_status` and `bili_list_subscriptions` (skill `bilibili`), both read-only.
+
+## License
+
+MIT

package/commands/bili/list/index.js

@@ -0,0 +1,26 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { channelSourceError, extractChannelInfo, subscriptionScope } from "../../../lib/channel.js";
+import { bilibiliRuntimeToken } from "../../../lib/runtime.js";
+import { getBiliSubs } from "../../../lib/store.js";
+const KIND_TEXT = { all: '开播+动态', live: '开播', dynamic: '动态' };
+export default defineCommand({
+    description: '查看当前会话的 B 站订阅',
+    async execute({ input, use }) {
+        const runtime = use(bilibiliRuntimeToken);
+        const Subs = getBiliSubs(runtime.db);
+        if (!Subs)
+            return 'B 站订阅数据库尚未就绪，请稍后重试';
+        const channel = extractChannelInfo(input);
+        if (!channel)
+            return channelSourceError(input);
+        const rows = await Subs.select().where(subscriptionScope(channel));
+        if (rows.length === 0)
+            return '当前会话没有订阅任何 UP 主\n使用 bili sub <uid> 添加订阅';
+        const lines = rows.map((row, index) => `${index + 1}. ${String(row.uname || '(未知)')}（UID ${String(row.uid)}）· ${KIND_TEXT[String(row.kinds)] ?? '开播+动态'}`);
+        const status = runtime.watcher.backoffStatus();
+        if (status.length > 0)
+            lines.push('', '暂停中的请求：', ...status);
+        return `当前订阅 (${rows.length}/${runtime.config.maxPerChannel})：\n${lines.join('\n')}`;
+    },
+});

package/commands/bili/live/index.js

@@ -0,0 +1,31 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { BiliApiError, parseRoomId } from "../../../lib/api.js";
+import { formatRoom } from "../../../lib/format.js";
+import { bilibiliRuntimeToken } from "../../../lib/runtime.js";
+export default defineCommand({
+    description: '查询 B 站直播间状态',
+    params: { room: { type: 'string', description: '直播间号或直播间链接' } },
+    async execute({ params, use }) {
+        const roomId = parseRoomId(String(params.room ?? ''));
+        if (!roomId)
+            return '请提供直播间号或链接，格式：bili live <房间号>';
+        const { client } = use(bilibiliRuntimeToken);
+        try {
+            const room = await client.getRoomInfo(roomId);
+            let uname = '';
+            let liveTime = 0;
+            if (room.uid) {
+                const info = (await client.getLiveStatus([room.uid]).catch(() => new Map())).get(room.uid);
+                uname = info?.uname ?? '';
+                liveTime = info?.liveTime ?? 0;
+            }
+            return formatRoom(room, uname, liveTime);
+        }
+        catch (error) {
+            if (error instanceof BiliApiError && error.kind === 'not_found')
+                return `直播间 ${roomId} 不存在`;
+            return `查询失败：${error.message}`;
+        }
+    },
+});

package/commands/bili/sub/index.js

@@ -0,0 +1,68 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { canManageConversation, defineCommand } from 'zhin.js/command';
+import { BiliApiError, parseUid } from "../../../lib/api.js";
+import { channelSourceError, extractChannelInfo, subscriptionScope } from "../../../lib/channel.js";
+import { bilibiliRuntimeToken } from "../../../lib/runtime.js";
+import { SUBSCRIPTION_PERMISSION_DENIED_MESSAGE } from "../../../lib/permission.js";
+import { getBiliSubs, parseKinds } from "../../../lib/store.js";
+const KIND_TEXT = { all: '开播 + 动态', live: '开播', dynamic: '动态' };
+export default defineCommand({
+    description: '订阅 B 站 UP 主的开播和动态推送（群聊限群主、管理员或机器人主人）',
+    params: {
+        uid: { type: 'string', description: 'UP 主 UID 或空间链接' },
+        kind: { type: 'string', default: 'all', description: 'all（默认）/ live / dynamic' },
+    },
+    async execute({ params, input, use, adapter, scene, sender }) {
+        const runtime = use(bilibiliRuntimeToken);
+        const Subs = getBiliSubs(runtime.db);
+        if (!Subs)
+            return 'B 站订阅数据库尚未就绪，请稍后重试';
+        const uid = parseUid(String(params.uid ?? ''));
+        if (!uid)
+            return '请提供 UP 主 UID 或空间链接，格式：bili sub <uid> [all|live|dynamic]';
+        const kinds = parseKinds(String(params.kind ?? 'all'));
+        if (!kinds)
+            return '订阅类型只能是 all、live 或 dynamic';
+        const channel = extractChannelInfo(input);
+        if (!channel)
+            return channelSourceError(input);
+        if (!canManageConversation({ adapter, scene, sender }))
+            return SUBSCRIPTION_PERMISSION_DENIED_MESSAGE;
+        const scope = subscriptionScope(channel);
+        const existing = await Subs.select().where({ uid, ...scope });
+        if (existing.length > 0) {
+            if (existing[0].kinds === kinds)
+                return '当前会话已订阅该 UP 主，无需重复添加';
+            await Subs.update({ kinds }).where({ uid, ...scope });
+            return `已将 ${String(existing[0].uname || uid)} 的订阅改为：${KIND_TEXT[kinds]}`;
+        }
+        const current = await Subs.select().where(scope);
+        if (current.length >= runtime.config.maxPerChannel) {
+            return `当前会话订阅数已达上限 (${runtime.config.maxPerChannel})，请先取消一些`;
+        }
+        let uname = '';
+        try {
+            uname = (await runtime.client.getUserCard(uid)).name;
+        }
+        catch (error) {
+            if (error instanceof BiliApiError && error.kind === 'not_found')
+                return `找不到 UID 为 ${uid} 的用户`;
+            // Lookup is cosmetic; subscribe anyway and let the watcher fill gaps.
+        }
+        await Subs.insert({
+            uid,
+            uname,
+            kinds,
+            ...scope,
+            creator_id: channel.senderId,
+            created_at: new Date().toISOString(),
+        });
+        await runtime.watcher.baseline(uid).catch(() => undefined);
+        const notes = [];
+        if (!runtime.outbound)
+            notes.push('⚠ 未接入 OutboundHost，暂时无法主动推送');
+        if (!runtime.persistent)
+            notes.push('⚠ 未配置数据库，订阅在重启后会丢失');
+        return [`订阅成功：${uname || uid}（UID ${uid}），类型：${KIND_TEXT[kinds]}`, ...notes].join('\n');
+    },
+});

package/commands/bili/unsub/index.js

@@ -0,0 +1,37 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { canManageConversation, defineCommand } from 'zhin.js/command';
+import { parseUid } from "../../../lib/api.js";
+import { channelSourceError, extractChannelInfo, subscriptionScope } from "../../../lib/channel.js";
+import { bilibiliRuntimeToken } from "../../../lib/runtime.js";
+import { SUBSCRIPTION_PERMISSION_DENIED_MESSAGE } from "../../../lib/permission.js";
+import { getBiliState, getBiliSubs } from "../../../lib/store.js";
+export default defineCommand({
+    description: '取消当前会话对某个 UP 主的订阅（群聊限群主、管理员或机器人主人）',
+    params: { uid: { type: 'string', description: 'UP 主 UID 或空间链接' } },
+    async execute({ params, input, use, adapter, scene, sender }) {
+        const runtime = use(bilibiliRuntimeToken);
+        const Subs = getBiliSubs(runtime.db);
+        if (!Subs)
+            return 'B 站订阅数据库尚未就绪，请稍后重试';
+        const uid = parseUid(String(params.uid ?? ''));
+        if (!uid)
+            return '请提供 UP 主 UID，格式：bili unsub <uid>';
+        const channel = extractChannelInfo(input);
+        if (!channel)
+            return channelSourceError(input);
+        if (!canManageConversation({ adapter, scene, sender }))
+            return SUBSCRIPTION_PERMISSION_DENIED_MESSAGE;
+        const scope = subscriptionScope(channel);
+        const existing = await Subs.select().where({ uid, ...scope });
+        if (existing.length === 0)
+            return '当前会话没有订阅该 UP 主';
+        await Subs.delete().where({ uid, ...scope });
+        // Drop the watcher cursor and backoff once nobody watches this UP any more.
+        const remaining = await Subs.select().where({ uid });
+        if (remaining.length === 0) {
+            await getBiliState(runtime.db)?.delete().where({ uid });
+            runtime.watcher.forget(uid);
+        }
+        return `已取消订阅：${String(existing[0].uname || uid)}`;
+    },
+});

package/lib/api.d.ts

@@ -0,0 +1,68 @@
+export declare const DEFAULT_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36";
+export type BiliErrorKind = 'risk' | 'not_found' | 'http' | 'shape' | 'network';
+export declare class BiliApiError extends Error {
+    readonly kind: BiliErrorKind;
+    readonly code: number | undefined;
+    constructor(kind: BiliErrorKind, message: string, code?: number);
+}
+export interface LiveInfo {
+    readonly uid: string;
+    readonly uname: string;
+    readonly roomId: string;
+    readonly title: string;
+    /** 0 = offline, 1 = live, 2 = replay carousel. */
+    readonly liveStatus: number;
+    /** Unix seconds of the current live start, 0 when unknown. */
+    readonly liveTime: number;
+    readonly cover: string;
+    readonly area: string;
+    readonly url: string;
+}
+export interface RoomInfo {
+    readonly uid: string;
+    readonly roomId: string;
+    readonly title: string;
+    readonly liveStatus: number;
+    readonly area: string;
+    readonly online: number;
+    readonly url: string;
+}
+export interface DynamicItem {
+    readonly id: string;
+    readonly author: string;
+    /** Unix seconds. */
+    readonly pubTs: number;
+    readonly type: string;
+    readonly pinned: boolean;
+    readonly summary: string;
+    readonly url: string;
+}
+export interface UserCard {
+    readonly uid: string;
+    readonly name: string;
+}
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export interface BiliClientOptions {
+    readonly timeout?: number;
+    readonly cookie?: string;
+    readonly fetch?: FetchLike;
+    readonly now?: () => number;
+}
+export declare class BiliClient {
+    #private;
+    constructor(options?: BiliClientOptions);
+    /** Forget cached device id and WBI key, e.g. after a risk-control response. */
+    resetSession(): void;
+    /** Batch live status by UP uid (no auth). */
+    getLiveStatus(uids: readonly string[]): Promise<Map<string, LiveInfo>>;
+    getRoomInfo(roomId: string): Promise<RoomInfo>;
+    getUserCard(uid: string): Promise<UserCard>;
+    /** Latest space dynamics of one UP (WBI signed). Newest first, as returned. */
+    getDynamics(uid: string): Promise<DynamicItem[]>;
+}
+/** Turn one raw feed item into a compact, push-ready record (undefined = skip). */
+export declare function parseDynamic(raw: unknown): DynamicItem | undefined;
+/** Accepts `123`, `UID:123`, `https://space.bilibili.com/123/...`. */
+export declare function parseUid(input: string): string | undefined;
+/** Accepts `21452505` or `https://live.bilibili.com/21452505`. */
+export declare function parseRoomId(input: string): string | undefined;