dsh-shlr-bilitoolkit 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
-
-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.
+# dsh-shlr-bilitoolkit
+
+B 站（哔哩哔哩）接口封装的 **TypeScript** 移植版，作为 [dsh](https://dshmp.com)（DeepSeek Harness）插件提供「视频 / 搜索 / 空间」等读取能力。
+
+> 本项目从原 Python 工具箱（`bili/`）完整移植而来，覆盖视频、搜索、空间、评论、私信、互动（点赞/收藏/投币/关注/三连）、动态、专栏、关注关系、消息中心、个人资料与扫码登录，并作为 [dsh](https://dshmp.com)（DeepSeek Harness）插件提供上述能力。
+
+## 目录结构
+
+```
+dsh-shlr-bilitoolkit/
+├── src/
+│   ├── client.ts        # BiliClient：Session / Cookie / 请求 / 节流 / 重试 / 风控 / 表单编码
+│   ├── wbi.ts           # WbiSigner：w_rid / wts 签名（含官方 mixin_key 算法）
+│   ├── errors.ts        # BiliApiError / CaptchaRequired / CookieError
+│   ├── models.ts        # Video / Article / Comment / PrivateMessage / RelationUser /
+│   │                    #   Dynamic / Notice / User / Page / PlayInfo / Subtitle / Collection
+│   ├── formatting.ts    # 播放量、时长、HTML 清理等展示格式化
+│   ├── pagination.ts    # iterPages：统一翻页异步生成器
+│   ├── endpoints.ts     # 所有接口 URL 常量
+│   ├── apis/
+│   │   ├── video.ts     # 推荐流 / 详情 / 分P / 播放地址 / 字幕
+│   │   ├── search.ts    # 搜索视频 / 用户
+│   │   ├── space.ts     # 空间信息 / 投稿 / 合集
+│   │   ├── comment.ts   # 评论：视频/动态/专栏 的读取与发表/回复/删除
+│   │   ├── message.ts   # 私信：发送 / 撤回 / 记录 / 未读
+│   │   ├── interact.ts  # 点赞 / 收藏 / 投币 / 关注 / 三连
+│   │   ├── dynamic.ts   # 动态：关注流 / 空间 / 发布 / 转发 / 点赞 / 删除
+│   │   ├── article.ts   # 专栏：详情 / UP 主列表
+│   │   ├── relation.ts  # 关注 / 粉丝 / 统计
+│   │   ├── notify.ts    # 消息中心：未读 / 回复我的 / @我的 / 收到的赞
+│   │   ├── profile.ts   # 个人资料：读取 / 改签名 / 改昵称性别生日
+│   │   ├── auth.ts      # 扫码登录（generate / poll / wait / login）
+│   │   └── download.ts  # 下载与 ffmpeg 合并工具
+│   ├── dsh.ts           # dsh 插件入口：apply(ctx) + 工具列表
+│   └── index.ts         # 对外导出
+├── tests/               # 离线单测（wbi 签名、格式化、模型）
+├── cordis.patch.yml     # dsh bundle 的配置补丁
+├── dsh-manifest.json    # 市场目录收录清单（schema v1）
+├── package.json         # 含 dsh.bundle.patch 声明
+└── tsconfig.json
+```
+
+## 构建与测试
+
+```bash
+npm install
+npm run typecheck      # tsc --noEmit
+npm test               # 离线单测（node --test + tsx）
+npm run build          # 产出 dist/
+```
+
+> 说明：`tsconfig` 使用 `moduleResolution: Bundler`，相对导入不带扩展名，适合被 dsh 运行时（基于打包器的 cordis 应用）消费。若要在原生 Node ESM 下直接 `node dist/index.js`，需改用 `NodeNext` 并补 `.js` 扩展名。
+
+## 当作库用
+
+```ts
+import { BiliClient } from "dsh-shlr-bilitoolkit";
+
+const client = new BiliClient({ cookieFile: "bili_cookies.json" });
+await client.loadCookies();
+
+const videos = await client.video.recommend(2, 10);
+const detail = await client.video.detail("BV1xx411c7mD");
+const text   = await client.video.subtitleText("BV1xx411c7mD"); // 字幕纯文本
+const [videos2, total] = await client.search.videos("孤独摇滚");
+const info = await client.space.info(574115689);
+const [ups, _] = await client.space.videos(574115689, 1, 10);
+```
+
+## 作为 dsh 插件
+
+- 包名 `dsh-shlr-bilitoolkit`（符合 `dsh-` 前缀约定），`package.json` 里声明了 `dsh.bundle.patch: ./cordis.patch.yml`，因此会被 dsh 识别为插件而非普通库。
+- 入口 `src/dsh.ts` 导出 `apply(ctx)`，注册一组工具（读取为主，写操作明确标注「需登录 / 谨慎」）：
+  - 读取：`bili_recommend` / `bili_video_detail` / `bili_video_subtitle` / `bili_search_video` / `bili_search_user` / `bili_space_info` / `bili_space_videos` / `bili_article_view` / `bili_article_list` / `bili_dynamic_feed` / `bili_dynamic_space` / `bili_comment_list` / `bili_relation_followings` / `bili_relation_followers` / `bili_notify_unread` / `bili_notify_replies` / `bili_fav_folders`
+  - 写操作：`bili_like` / `bili_follow` / `bili_favorite` / `bili_send_comment` / `bili_send_message` / `bili_triple`（均会真实修改账号状态，需登录）
+  - 辅助：`bili_login_status`（查登录态）/ `bili_gen_qr`（生成扫码登录二维码）/ `bili_cache_clear`（清空本地缓存）
+- 工具读取 `BILI_COOKIE_FILE`（默认 `bili_cookies.json`）作为登录态。
+- **扫码登录（独立获取 Cookie）**：运行 `npm run login`，终端会打印 ASCII 二维码，用「哔哩哔哩」App 扫码并确认后，Cookie 自动写入 `bili_cookies.json`。也可在对话里先调 `bili_login_status` 查登录态、调 `bili_gen_qr` 拿二维码链接与可直接展示的 `ascii` 二维码。写操作（点赞 / 收藏 / 投币 / 关注 / 评论 / 私信 / 三连）都依赖该 Cookie 中的 `SESSDATA` / `bili_jct`。
+- **缓存持久化**：除 Cookie 外，客户端还会把 WBI 签名密钥（`B 站每天轮换`）、`bvid→aid` 映射这类稳定 / 带 TTL 的数据写入本地 JSON 缓存（`BILI_CACHE_FILE`，默认 `bili_cache.json`），用临时文件 + 原子替换落盘、文件损坏会自动自愈。冷启动或跨进程时直接复用，避免每次都请求 `nav` 接口；密钥过期或失效时 `refresh()` 会重新拉取并覆盖缓存。若签名反复报 `-403/-352`，可调用 `bili_cache_clear` 强制清空缓存后重试（不影响 Cookie / 登录态）。
+
+安装到 dsh（任选其一，取决于你的发行方式）：
+
+```bash
+dsh plugin --profile <name> add dsh-shlr-bilitoolkit          # 已发布到 npm
+dsh plugin --profile <name> add github:your-name/dsh-shlr-bilitoolkit#<ref>
+```
+
+> 插件入口已对齐 **官方 DeepSeek Harness（cordis 体系）** 的约定：模块导出 `name` / `inject = ["tools"]` / `apply(ctx)`，并在 `apply` 内用官方 `ctx.tools.register(defineTool({ name, description, parameters, output, execute }))` 注册每个工具（`defineTool` 来自 `@deepseek-ai/dsh-tools`，由宿主提供、插件不打包，保证单实例）。`parameters` 用官方简化 schema（`{ 参数名: { type, required, description, enum? } }`），工具返回规范 JSON 值，由 `output.render` 转成面向模型的文本。`cordis.patch.yml` 是官方组合包配置层（`- insert: - id: bili  name: dsh-shlr-bilitoolkit`，按包名解析到 `main` 入口）。若你的 dsh 版本较旧、没有 `ctx.tools`，`apply` 仍保留了 `ctx.registerTool` / `ctx.services.tools.register` 的回退路径。
+
+## 与原 Python 版的对应关系
+
+| Python | TS |
+| --- | --- |
+| `bili/client.py` | `src/client.ts` |
+| `bili/wbi.py` | `src/wbi.ts` |
+| `bili/video.py` | `src/apis/video.ts` |
+| `bili/search.py` | `src/apis/search.ts` |
+| `bili/space.py` | `src/apis/space.ts` |
+| `bili/comment.py` | `src/apis/comment.ts` |
+| `bili/message.py` | `src/apis/message.ts` |
+| `bili/interact.py` | `src/apis/interact.ts` |
+| `bili/dynamic.py` | `src/apis/dynamic.ts` |
+| `bili/article.py` | `src/apis/article.ts` |
+| `bili/relation.py` | `src/apis/relation.ts` |
+| `bili/notify.py` | `src/apis/notify.ts` |
+| `bili/profile.py` | `src/apis/profile.ts` |
+| `bili/auth.py` | `src/apis/auth.ts` |
+| `bili/download.py` | `src/apis/download.ts` |
+| `bili/models.py` | `src/models.ts` |
+| `bili/formatting.py` | `src/formatting.ts` |
+| `bili/pagination.py` | `src/pagination.ts` |
+
+约定保持一致：`client.xxx.yyy()` 调用风格、`iter_*` 异步生成器、`toDict()` 导出、WBI 签名算法与密钥 6 小时缓存（已落地到 `bili_cache.json`，跨进程复用）。
+
+## 与原 Python 版的差异 / 已知限制
+
+- **写接口为表单编码**：原 Python 用 `requests` 的 `data=` 默认表单；本包的 `client.post` 默认把对象编码为 `application/x-www-form-urlencoded`，仅动态点赞等少数接口显式走 JSON（`jsonBody=true`）。
+- **下载 / ffmpeg**：`src/apis/download.ts` 提供 `downloadUrl` / `mergeWithFfmpeg`，为纯工具函数，未接入 dsh 工具（下载行为在 dsh 里通常不合适）。
+
+## 风控说明
+
+本包内置与原 Python 版一致的基础降风控策略：请求节流（默认 0.6s + 0~0.4s 抖动）、GET 退避重试、写操作不重试、HTTP 412 / `-412` 立即停手、WBI 签名。但单账号操作量上限、避免短时间切 IP/UA 等仍需使用习惯配合。

package/cordis.patch.yml

@@ -0,0 +1,13 @@
+# dsh 组合包的配置层：当某个 profile 把本包列为 bundle 时，这一层会被叠加应用。
+#
+# 按官方约定，插件行用「包名」引用本包（name: dsh-shlr-bilitoolkit），
+# Node 据此解析到 main（dist/dsh.js）。该入口导出 name / inject / apply，
+# 由 Cordis 加载并调用 apply(ctx)，apply 内部再用 ctx.tools.register(defineTool(...))
+# 注册每个工具。
+#
+# 字段说明：
+#   id   - 该插件行在本配置层中的唯一标识
+#   name - 包名（不是相对源码路径），由 Node 模块解析定位到 main
+- insert:
+  - id: bili
+    name: dsh-shlr-bilitoolkit

package/dist/apis/article.d.ts

@@ -0,0 +1,12 @@
+/** 专栏：详情、UP 主专栏列表。 */
+import type { BiliClient } from "../client";
+import { Article } from "../models";
+export declare function parseArticleId(value: unknown): number;
+export declare class ArticleAPI {
+    private client;
+    constructor(client: BiliClient);
+    private static headers;
+    view(articleId: unknown): Promise<Article>;
+    listByUser(mid: number, page?: number, pageSize?: number, sort?: string): Promise<[Article[], number]>;
+    iterUser(mid: number, pageSize?: number, sort?: string, maxPages?: number): AsyncGenerator<Article, any, any>;
+}

package/dist/apis/article.js

@@ -0,0 +1,49 @@
+/** 专栏：详情、UP 主专栏列表。 */
+import * as endpoints from "../endpoints";
+import { BiliApiError } from "../errors";
+import { Article } from "../models";
+import { iterPages } from "../pagination";
+const _ARTICLE_ID = /cv(\d+)/i;
+const _NUMBER = /(\d+)/;
+export function parseArticleId(value) {
+    if (typeof value === "number")
+        return value;
+    const text = String(value ?? "").trim();
+    const match = _ARTICLE_ID.exec(text) ?? _NUMBER.exec(text);
+    if (!match)
+        throw new Error(`无法识别专栏 id: ${value}`);
+    return Number(match[1]);
+}
+export class ArticleAPI {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    static headers(cvid) {
+        return { Referer: `https://www.bilibili.com/read/cv${cvid}` };
+    }
+    async view(articleId) {
+        const cvid = parseArticleId(articleId);
+        const payload = await this.client.get(endpoints.ARTICLE_VIEW, { id: cvid }, ArticleAPI.headers(cvid));
+        const article = Article.fromApi(payload?.data);
+        if (!article.id)
+            throw new BiliApiError("未找到该专栏");
+        return article;
+    }
+    async listByUser(mid, page = 1, pageSize = 30, sort = "publish_time") {
+        const payload = await this.client.getSigned(endpoints.SPACE_ARTICLE, { mid: Number(mid), pn: page, ps: pageSize, sort }, { Referer: `https://space.bilibili.com/${mid}/article` });
+        const data = payload?.data ?? {};
+        const articles = [];
+        for (const item of data.articles ?? []) {
+            const article = Article.fromApi(item);
+            if (article.id)
+                articles.push(article);
+        }
+        const total = Number(data.count ?? articles.length);
+        return [articles, total];
+    }
+    iterUser(mid, pageSize = 30, sort = "publish_time", maxPages) {
+        const fetch = (page) => this.listByUser(mid, page, pageSize, sort);
+        return iterPages(fetch, maxPages);
+    }
+}

package/dist/apis/auth.d.ts

@@ -0,0 +1,20 @@
+/** 扫码登录：生成二维码、轮询状态。
+
+终端 ASCII 二维码渲染依赖 qrcode 库，dsh 环境通常不需要，故只保留
+generate / poll / wait / login 的核心流程；如需在终端展示二维码，可另行
+调用 qrcode 库对 generate 返回的 url 进行渲染。
+*/
+import type { BiliClient } from "../client";
+export declare const QR_STATUS_SUCCESS = 0;
+export declare const QR_STATUS_EXPIRED = 86038;
+export declare const QR_STATUS_WAITING = 86101;
+export declare const QR_STATUS_SCANNED = 86090;
+export declare class QrCodeLogin {
+    private client;
+    private pollInterval;
+    constructor(client: BiliClient, pollInterval?: number);
+    generate(): Promise<[string, string]>;
+    poll(qrcodeKey: string): Promise<[number, string]>;
+    wait(qrcodeKey: string): Promise<boolean>;
+    login(attempts?: number): Promise<boolean>;
+}

package/dist/apis/auth.js

@@ -0,0 +1,83 @@
+/** 扫码登录：生成二维码、轮询状态。
+
+终端 ASCII 二维码渲染依赖 qrcode 库，dsh 环境通常不需要，故只保留
+generate / poll / wait / login 的核心流程；如需在终端展示二维码，可另行
+调用 qrcode 库对 generate 返回的 url 进行渲染。
+*/
+import * as endpoints from "../endpoints";
+import { BiliApiError } from "../errors";
+import { sleep } from "../util";
+export const QR_STATUS_SUCCESS = 0;
+export const QR_STATUS_EXPIRED = 86038;
+export const QR_STATUS_WAITING = 86101;
+export const QR_STATUS_SCANNED = 86090;
+export class QrCodeLogin {
+    client;
+    pollInterval;
+    constructor(client, pollInterval = 2) {
+        this.client = client;
+        this.pollInterval = pollInterval;
+    }
+    async generate() {
+        const payload = await this.client.get(endpoints.QRCODE_GENERATE);
+        const data = payload?.data ?? {};
+        const url = data.url;
+        const key = data.qrcode_key;
+        if (!url || !key)
+            throw new BiliApiError("二维码接口返回数据不完整");
+        return [url, key];
+    }
+    async poll(qrcodeKey) {
+        const payload = await this.client.get(endpoints.QRCODE_POLL, {
+            qrcode_key: qrcodeKey,
+        });
+        const data = payload?.data ?? {};
+        const code = data.code;
+        return [
+            code !== null && code !== undefined ? Number(code) : -1,
+            String(data.message ?? ""),
+        ];
+    }
+    async wait(qrcodeKey) {
+        let lastCode = null;
+        while (true) {
+            const [code, message] = await this.poll(qrcodeKey);
+            if (code === QR_STATUS_SUCCESS)
+                return true;
+            if (code === QR_STATUS_EXPIRED)
+                return false;
+            if (code !== lastCode) {
+                if (code === QR_STATUS_SCANNED) {
+                    // 已扫码，等待手机确认
+                }
+                else if (code === QR_STATUS_WAITING) {
+                    // 等待扫码
+                }
+                else {
+                    return false;
+                }
+                lastCode = code;
+            }
+            await sleep(this.pollInterval * 1000);
+        }
+    }
+    async login(attempts = 3) {
+        for (let attempt = 1; attempt <= attempts; attempt++) {
+            let url;
+            let key;
+            try {
+                [url, key] = await this.generate();
+            }
+            catch (exc) {
+                if (exc instanceof BiliApiError)
+                    return false;
+                throw exc;
+            }
+            if (await this.wait(key)) {
+                await this.client.saveCookies();
+                return true;
+            }
+        }
+        return false;
+    }
+}

package/dist/apis/comment.d.ts

@@ -0,0 +1,37 @@
+/** 评论相关接口：视频 / 动态 / 专栏的评论，发表 / 回复 / 删除。
+
+B 站评论是「type + oid」的通用模型：
+- 视频：type=1，oid=aid
+- 动态：type 由动态的 comment_type 决定，oid 取 comment_id
+- 专栏：type=12，oid=cvid
+*/
+import type { BiliClient } from "../client";
+import { Comment } from "../models";
+export declare class CommentAPI {
+    private client;
+    constructor(client: BiliClient);
+    private static sortValue;
+    private static videoHeaders;
+    private static dynamicHeaders;
+    private static articleHeaders;
+    private dynamicTarget;
+    private list;
+    private send;
+    private replies;
+    private delete;
+    listVideo(bvid: string, page?: number, pageSize?: number, sort?: string | number): Promise<[Comment[], number]>;
+    iterVideo(bvid: string, pageSize?: number, sort?: string | number, maxPages?: number): AsyncGenerator<Comment, any, any>;
+    sendVideo(bvid: string, message: string, root?: number | null, parent?: number | null): Promise<Comment>;
+    replyVideo(bvid: string, rootRpid: number, message: string, parentRpid?: number | null): Promise<Comment>;
+    repliesVideo(bvid: string, rootRpid: number, page?: number, pageSize?: number): Promise<[Comment[], number]>;
+    deleteVideo(bvid: string, rpid: number): Promise<void>;
+    listDynamic(dynamicId: string | number, page?: number, pageSize?: number, sort?: string | number): Promise<[Comment[], number]>;
+    iterDynamic(dynamicId: string | number, pageSize?: number, sort?: string | number, maxPages?: number): AsyncGenerator<Comment, any, any>;
+    sendDynamic(dynamicId: string | number, message: string, root?: number | null, parent?: number | null): Promise<Comment>;
+    repliesDynamic(dynamicId: string | number, rootRpid: number, page?: number, pageSize?: number): Promise<[Comment[], number]>;
+    deleteDynamic(dynamicId: string | number, rpid: number): Promise<void>;
+    listArticle(articleId: unknown, page?: number, pageSize?: number, sort?: string | number): Promise<[Comment[], number]>;
+    sendArticle(articleId: unknown, message: string, root?: number | null, parent?: number | null): Promise<Comment>;
+    repliesArticle(articleId: unknown, rootRpid: number, page?: number, pageSize?: number): Promise<[Comment[], number]>;
+    deleteArticle(articleId: unknown, rpid: number): Promise<void>;
+}

package/dist/apis/comment.js

@@ -0,0 +1,164 @@
+/** 评论相关接口：视频 / 动态 / 专栏的评论，发表 / 回复 / 删除。
+
+B 站评论是「type + oid」的通用模型：
+- 视频：type=1，oid=aid
+- 动态：type 由动态的 comment_type 决定，oid 取 comment_id
+- 专栏：type=12，oid=cvid
+*/
+import * as endpoints from "../endpoints";
+import { BiliApiError } from "../errors";
+import { Comment } from "../models";
+import { iterPages } from "../pagination";
+import { parseArticleId } from "./article";
+const SORT_BY_NAME = { time: 0, like: 1, reply: 2 };
+export class CommentAPI {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    static sortValue(sort) {
+        if (typeof sort === "string") {
+            if (!(sort in SORT_BY_NAME)) {
+                throw new Error(`sort 只支持 ${Object.keys(SORT_BY_NAME)} 或 0/1/2`);
+            }
+            return SORT_BY_NAME[sort];
+        }
+        return Number(sort);
+    }
+    static videoHeaders(bvid) {
+        return { Referer: `https://www.bilibili.com/video/${bvid}/` };
+    }
+    static dynamicHeaders(dynamicId) {
+        return { Referer: `https://t.bilibili.com/${dynamicId}` };
+    }
+    static articleHeaders(cvid) {
+        return { Referer: `https://www.bilibili.com/read/cv${cvid}` };
+    }
+    async dynamicTarget(dynamicId) {
+        const dynamic = await this.client.dynamic.detail(dynamicId);
+        if (!dynamic.commentType || !dynamic.commentId) {
+            throw new BiliApiError("该动态没有可用的评论信息");
+        }
+        return [dynamic.commentType, dynamic.commentId];
+    }
+    async list(oid, type, page, pageSize, sort, headers) {
+        const payload = await this.client.get(endpoints.REPLY_LIST, {
+            type,
+            oid,
+            pn: page,
+            ps: pageSize,
+            sort: CommentAPI.sortValue(sort),
+        }, headers);
+        const data = payload?.data ?? {};
+        const comments = (data.replies ?? [])
+            .map((r) => Comment.fromApi(r))
+            .filter((c) => c !== null);
+        const total = (data.page ?? {}).count ?? comments.length;
+        return [comments, total];
+    }
+    async send(oid, type, message, root, parent, headers) {
+        message = (message || "").trim();
+        if (!message)
+            throw new Error("评论内容不能为空");
+        const form = {
+            type,
+            oid,
+            message,
+            csrf: this.client.csrf,
+            plat: 1,
+        };
+        if (root)
+            form["root"] = root;
+        if (parent)
+            form["parent"] = parent;
+        const payload = await this.client.post(endpoints.REPLY_ADD, form, headers);
+        const data = payload?.data ?? {};
+        if (!data.rpid) {
+            throw new BiliApiError("评论接口未返回 rpid，可能被风控拦截");
+        }
+        return Comment.fromApi(data);
+    }
+    async replies(oid, type, rootRpid, page, pageSize, headers) {
+        const payload = await this.client.get(endpoints.REPLY_REPLY, { type, oid, root: Number(rootRpid), pn: page, ps: pageSize }, headers);
+        const data = payload?.data ?? {};
+        const comments = (data.replies ?? [])
+            .map((i) => Comment.fromApi(i))
+            .filter((c) => c !== null);
+        const total = (data.page ?? {}).count ?? comments.length;
+        return [comments, total];
+    }
+    async delete(oid, type, rpid, headers) {
+        await this.client.post(endpoints.REPLY_DEL, { type, oid, rpid, csrf: this.client.csrf }, headers);
+    }
+    // ------------------------------------------------------------------ 视频
+    async listVideo(bvid, page = 1, pageSize = 20, sort = "time") {
+        CommentAPI.sortValue(sort); // 先校验，避免参数错误时还去请求 aid
+        const aid = await this.client.video.resolveAid(bvid);
+        return this.list(aid, 1, page, pageSize, sort, CommentAPI.videoHeaders(bvid));
+    }
+    iterVideo(bvid, pageSize = 20, sort = "time", maxPages) {
+        const fetch = (page) => this.listVideo(bvid, page, pageSize, sort);
+        return iterPages(fetch, maxPages);
+    }
+    async sendVideo(bvid, message, root, parent) {
+        if (!(message || "").trim())
+            throw new Error("评论内容不能为空");
+        const aid = await this.client.video.resolveAid(bvid);
+        return this.send(aid, 1, message, root, parent, CommentAPI.videoHeaders(bvid));
+    }
+    async replyVideo(bvid, rootRpid, message, parentRpid) {
+        return this.sendVideo(bvid, message, rootRpid, parentRpid ?? rootRpid);
+    }
+    async repliesVideo(bvid, rootRpid, page = 1, pageSize = 20) {
+        const aid = await this.client.video.resolveAid(bvid);
+        return this.replies(aid, 1, rootRpid, page, pageSize, CommentAPI.videoHeaders(bvid));
+    }
+    async deleteVideo(bvid, rpid) {
+        const aid = await this.client.video.resolveAid(bvid);
+        await this.delete(aid, 1, rpid, CommentAPI.videoHeaders(bvid));
+    }
+    // ------------------------------------------------------------------ 动态
+    async listDynamic(dynamicId, page = 1, pageSize = 20, sort = "time") {
+        CommentAPI.sortValue(sort);
+        const [commentType, oid] = await this.dynamicTarget(dynamicId);
+        return this.list(Number(oid), commentType, page, pageSize, sort, CommentAPI.dynamicHeaders(dynamicId));
+    }
+    iterDynamic(dynamicId, pageSize = 20, sort = "time", maxPages) {
+        const fetch = (page) => this.listDynamic(dynamicId, page, pageSize, sort);
+        return iterPages(fetch, maxPages);
+    }
+    async sendDynamic(dynamicId, message, root, parent) {
+        if (!(message || "").trim())
+            throw new Error("评论内容不能为空");
+        const [commentType, oid] = await this.dynamicTarget(dynamicId);
+        return this.send(Number(oid), commentType, message, root, parent, CommentAPI.dynamicHeaders(dynamicId));
+    }
+    async repliesDynamic(dynamicId, rootRpid, page = 1, pageSize = 20) {
+        const [commentType, oid] = await this.dynamicTarget(dynamicId);
+        return this.replies(Number(oid), commentType, rootRpid, page, pageSize, CommentAPI.dynamicHeaders(dynamicId));
+    }
+    async deleteDynamic(dynamicId, rpid) {
+        const [commentType, oid] = await this.dynamicTarget(dynamicId);
+        await this.delete(Number(oid), commentType, rpid, CommentAPI.dynamicHeaders(dynamicId));
+    }
+    // ------------------------------------------------------------------ 专栏
+    async listArticle(articleId, page = 1, pageSize = 20, sort = "time") {
+        CommentAPI.sortValue(sort);
+        const cvid = parseArticleId(articleId);
+        return this.list(cvid, 12, page, pageSize, sort, CommentAPI.articleHeaders(cvid));
+    }
+    async sendArticle(articleId, message, root, parent) {
+        if (!(message || "").trim())
+            throw new Error("评论内容不能为空");
+        const cvid = parseArticleId(articleId);
+        return this.send(cvid, 12, message, root, parent, CommentAPI.articleHeaders(cvid));
+    }
+    async repliesArticle(articleId, rootRpid, page = 1, pageSize = 20) {
+        const cvid = parseArticleId(articleId);
+        return this.replies(cvid, 12, rootRpid, page, pageSize, CommentAPI.articleHeaders(cvid));
+    }
+    async deleteArticle(articleId, rpid) {
+        const cvid = parseArticleId(articleId);
+        await this.delete(cvid, 12, rpid, CommentAPI.articleHeaders(cvid));
+    }
+}

package/dist/apis/download.d.ts

@@ -0,0 +1,8 @@
+/** 播放流下载与 ffmpeg 合并。
+
+DASH 流的视频和音频是分开的，下载后需要合并；没有 ffmpeg 时保留两个文件。
+这些是不依赖 BiliClient 的纯工具函数，可在 Node 环境直接使用。
+*/
+export declare function safeFilename(text: string, fallback?: string): string;
+export declare function downloadUrl(url: string, destPath: string, referer?: string): Promise<void>;
+export declare function mergeWithFfmpeg(videoPath: string, audioPath: string, outputPath: string): Promise<void>;

package/dist/apis/download.js

@@ -0,0 +1,60 @@
+/** 播放流下载与 ffmpeg 合并。
+
+DASH 流的视频和音频是分开的，下载后需要合并；没有 ffmpeg 时保留两个文件。
+这些是不依赖 BiliClient 的纯工具函数，可在 Node 环境直接使用。
+*/
+import { createWriteStream } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import * as path from "node:path";
+import { spawn } from "node:child_process";
+import axios from "axios";
+import { BiliApiError } from "../errors";
+const CHUNK_SIZE = 1 << 20;
+const UNSAFE_FILENAME = /[\\/:*?"<>|]/;
+export function safeFilename(text, fallback = "video") {
+    const cleaned = (text || "")
+        .trim()
+        .replace(UNSAFE_FILENAME, "_")
+        .replace(/^[. ]+|[. ]+$/g, "");
+    return cleaned || fallback;
+}
+export async function downloadUrl(url, destPath, referer) {
+    await mkdir(path.dirname(destPath), { recursive: true });
+    const headers = {};
+    if (referer)
+        headers["Referer"] = referer;
+    const response = await axios.get(url, {
+        headers,
+        responseType: "stream",
+        timeout: 30_000,
+    });
+    await new Promise((resolve, reject) => {
+        const writer = createWriteStream(destPath);
+        response.data.pipe(writer);
+        writer.on("finish", resolve);
+        writer.on("error", reject);
+        response.data.on("error", reject);
+    });
+}
+export async function mergeWithFfmpeg(videoPath, audioPath, outputPath) {
+    const ffmpeg = process.env.FFMPEG_PATH || "ffmpeg";
+    await new Promise((resolve, reject) => {
+        const proc = spawn(ffmpeg, [
+            "-y",
+            "-i",
+            videoPath,
+            "-i",
+            audioPath,
+            "-c",
+            "copy",
+            outputPath,
+        ]);
+        proc.on("error", reject);
+        proc.on("close", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new BiliApiError(`ffmpeg 合并失败（退出码 ${code}）`));
+        });
+    });
+}

package/dist/apis/dynamic.d.ts

@@ -0,0 +1,23 @@
+/** 动态：关注动态流、用户空间动态，以及发布 / 转发 / 点赞 / 删除。
+
+读取走网页版 polymer 接口，需要登录态。写操作（publish / repost / thumb /
+delete）都是公开行为，受风控和人机验证限制，使用前请自行确认。
+*/
+import type { BiliClient } from "../client";
+import { Dynamic } from "../models";
+export declare class DynamicAPI {
+    private client;
+    constructor(client: BiliClient);
+    private _detailCache;
+    detail(dynamicId: string | number): Promise<Dynamic>;
+    feed(page?: number, offset?: string, type?: string): Promise<[Dynamic[], string, boolean]>;
+    space(uid: number, offset?: string): Promise<[Dynamic[], string, boolean, number]>;
+    iterFeed(maxPages?: number, type?: string): AsyncGenerator<Dynamic>;
+    iterSpace(uid: number, maxPages?: number): AsyncGenerator<Dynamic>;
+    publish(text: string, atUids?: number[], ctrl?: any[], closeComment?: boolean): Promise<string>;
+    repost(dynamicId: string | number, text?: string): Promise<string>;
+    thumb(dynamicId: string | number, liked?: boolean): Promise<void>;
+    delete(dynamicId: string | number): Promise<void>;
+    private static dynamicId;
+    private static parseItems;
+}