dsh-shlr-bilitoolkit 0.1.15 → 0.1.17

package/AGENTS.md

@@ -7,4 +7,5 @@
 禁止：只给链接、用 ASCII/文本二维码、让用户自己跑命令。用户扫码确认后调用 `bili_login_status` 完成登录并保存 Cookie。
 
 ## 其它
-全部能力见各 `bili_*` 工具描述；写操作会真实修改账号状态，执行前先与用户确认。
+- 除常驻工具外，其它 B 站能力默认懒加载：先 `bili_catalog` 看分组，再 `bili_open(group)` 打开（下一轮生效），用完可 `bili_close` 释放。
+- 写操作会真实修改账号状态，执行前先与用户确认。

package/README.md

@@ -0,0 +1,98 @@
+# dsh-shlr-bilitoolkit
+
+B 站（哔哩哔哩）接口封装的 **TypeScript** 移植版，作为 [dsh](https://dshmp.com)（DeepSeek Harness）插件提供「视频 / 搜索 / 空间 / 专栏 / 动态 / 评论 / 关注 / 消息中心」等读取能力，以及点赞、收藏、投币、关注、评论、私信、三连、发动态等写操作。
+
+> 本项目从原 Python 工具箱（`bili/`）完整移植而来，并作为 dsh（cordis 体系）插件提供上述能力。
+
+## 安装
+
+```bash
+# 已发布到 npm
+dsh plugin --profile <name> add dsh-shlr-bilitoolkit@latest
+
+# 本地开发 / 试运行
+npm install
+npm run build
+```
+
+本地登录（独立获取 Cookie，终端打印 ASCII 二维码）：
+
+```bash
+npm install && npm run login
+# 或指定 Cookie 文件
+BILI_COOKIE_FILE=./my_cookies.json npm run login
+```
+
+## 插件入口
+
+对齐官方 cordis 规范：`src/dsh.ts` 导出 `name` / `inject = ["tools"]` / `apply(ctx)`，在 `apply` 内用官方 `ctx.tools.register(defineTool({ name, description, parameters, output, execute }))` 注册每个工具。`defineTool` 来自 `@deepseek-ai/dsh-tools`，由宿主提供、插件不打包（保证单实例），已在 `peerDependencies` 声明。`cordis.patch.yml` 为组合包配置层（`- insert: - id: bili  name: dsh-shlr-bilitoolkit`，按包名解析到 `main`）。较旧、没有 `ctx.tools` 的 dsh 仍保留 `ctx.registerTool` / `ctx.services.tools.register` 回退。
+
+## 工具清单
+
+同类能力已用参数合并（`type` / `target` / `action` / `list`），**功能未减少**。
+
+- **读取**：
+  `bili_recommend` · `bili_video_detail` · `bili_video_subtitle` · `bili_search` · `bili_space_info` · `bili_space_videos` · `bili_article_view` · `bili_article_list` · `bili_dynamic_feed` · `bili_dynamic_space` · `bili_comment_list` · `bili_relation_list` · `bili_notify_unread` · `bili_notify_list` · `bili_fav_folders` · `bili_video_pagelist` · `bili_video_playurl` · `bili_video_status` · `bili_space_collections` · `bili_space_collection` · `bili_fav_folder_videos` · `bili_dynamic_detail` · `bili_message_unread` · `bili_message_history` · `bili_relation_stat` · `bili_user_following` · `bili_profile_info` · `bili_comment_replies`
+- **写操作**（均会真实修改账号状态，需登录）：
+  `bili_like` · `bili_follow` · `bili_favorite` · `bili_send_message` · `bili_triple` · `bili_dynamic_publish` · `bili_dynamic_repost` · `bili_coin` · `bili_fav_folder_create` · `bili_fav_folder_delete` · `bili_dynamic_like` · `bili_dynamic_delete` · `bili_comment_send` · `bili_comment_reply` · `bili_comment_delete` · `bili_comment_like` · `bili_message_recall` · `bili_profile_update`
+- **辅助**：`bili_login_status`（查登录态）· `bili_gen_qr`（生成登录二维码）· `bili_cache_clear`（清空本地缓存）
+
+合并工具的公共参数约定：
+
+| 工具 | 参数 |
+| --- | --- |
+| `bili_search` | `type=video\|user`，`order`（仅视频） |
+| `bili_relation_list` | `type=followings\|followers` |
+| `bili_notify_list` | `type=replies\|ats\|likes` |
+| `bili_favorite` | `action=add\|remove` |
+| `bili_video_subtitle` | `list=true` 时列字幕轨，否则取正文 |
+| `bili_comment_*` | `target=video\|dynamic\|article`，`id`（bvid / 动态 id / 专栏 cv 号） |
+| `bili_profile_update` | `uname` / `sex` / `birthday` / `sign`（至少一项） |
+
+## 数据目录
+
+Cookie / 缓存 / 二维码 / 设备号统一放在一个目录，默认 `bili_data/`（相对 dsh 工作目录），避免散落污染工作目录：
+
+| 文件 | 用途 |
+| --- | --- |
+| `bili_cookies.json` | 登录 Cookie（`SESSDATA` / `bili_jct`） |
+| `bili_cache.json` | WBI 签名密钥 + `bvid→aid` 缓存（原子写、损坏自愈） |
+| `bili_qrcode.png` | 最近一次生成的登录二维码 |
+| `bili_device.json` | 私信设备号 `dev_id`（跨重启稳定，降低风控） |
+
+可用环境变量：`BILI_DATA_DIR`（改目录）、`BILI_COOKIE_FILE` / `BILI_CACHE_FILE` / `BILI_QR_FILE` / `BILI_DEVICE_FILE`（精确指定单个文件）。兼容旧版：若新目录还没有 Cookie、而旧位置 `./bili_cookies.json` 有，会继续沿用。
+
+## 给 Agent 的约定
+
+仓库根目录的 [`AGENTS.md`](./AGENTS.md) 约定：需要登录时必须调用 `bili_gen_qr` 并把二维码**图片**展示给用户（而非只给链接或 ASCII）。把该 `AGENTS.md` 放到 dsh 工作目录，agent 即会遵守。
+
+## 目录结构
+
+```
+src/
+  client.ts      BiliClient：Session / Cookie / 请求 / 节流 / 重试 / 风控 / 表单编码
+  wbi.ts         WbiSigner：w_rid / wts 签名（官方 mixin_key 算法，密钥落盘缓存 6h）
+  cache.ts       JsonCache：本地 JSON 缓存（TTL / 原子写 / 损坏自愈）
+  errors.ts      BiliApiError / CaptchaRequired / CookieError
+  models.ts      纯数据模型 + toDict()
+  formatting.ts  播放量 / 时长 / HTML 清理等展示格式化
+  pagination.ts  iterPages：统一分页异步生成器
+  endpoints.ts   所有接口 URL 常量
+  apis/          video / search / space / comment / message / interact / dynamic /
+                 article / relation / notify / profile / auth / download
+  dsh.ts         dsh 插件入口：apply(ctx) + 工具清单
+  index.ts       对外导出
+tests/           离线单测（wbi 签名、格式化、缓存、lossless JSON 等）
+cordis.patch.yml dsh 组合包配置层
+scripts/login.ts npm run login 扫码登录脚本
+```
+
+## 与原 Python 版的差异 / 已知限制
+
+- **写接口为表单编码**：`client.post` 默认把对象编码为 `application/x-www-form-urlencoded`，仅动态点赞等少数接口显式走 JSON（`jsonBody=true`）。
+- **动态仅支持纯文字**：带图 / 投票 / 预约的富动态需额外图片上传流程，暂未实现。
+- **下载 / ffmpeg**：`src/apis/download.ts` 为纯工具函数，未接入 dsh 工具。
+
+## 风控说明
+
+内置与原 Python 版一致的基础降风控策略：请求节流（默认 0.6s + 0~0.4s 抖动）、GET 退避重试、写操作不重试、HTTP 412 / `-412` 立即停手、WBI 签名。但单账号操作量上限、避免短时间切 IP/UA 等仍需使用习惯配合。设备号 `dev_id` 已落盘保持稳定。

package/dist/dsh.d.ts

@@ -31,6 +31,11 @@ export interface DshTool {
  */
 export declare function toLosslessJson(value: unknown): unknown;
 export declare const TOOLS: DshTool[];
+export declare const CORE_IDS: string[];
+export declare const GROUPS: Record<string, {
+    hint: string;
+    ids: string[];
+}>;
 export declare function apply(ctx: any): void;
 export * from "./index.js";
 export { BiliClient, Video, User, Page, PlayInfo, Subtitle, Collection };

package/dist/dsh.js

@@ -1066,49 +1066,204 @@ export const TOOLS = [
         },
     },
 ];
-export function apply(ctx) {
-    for (const tool of TOOLS) {
-        const output = {
-            schema: { type: "object", additionalProperties: true },
-            render: tool.render ??
-                ((_args, value) => [{ type: "text", text: textOf(value) }]),
-        };
-        if (tool.presentationMeta) {
-            output.presentationMeta = tool.presentationMeta;
+let toolsRegistry = null;
+const openGroups = new Map();
+const groupLru = [];
+const MAX_OPEN_GROUPS = 3;
+// 常驻核心：登录链路必须随时可用 + 最常用的几个读取
+export const CORE_IDS = [
+    "bili_gen_qr",
+    "bili_login_status",
+    "bili_cache_clear",
+    "bili_recommend",
+    "bili_video_detail",
+    "bili_search",
+];
+// 能力分组（group -> 提示 + 工具 id）。核心工具也会出现在所属组里，便于目录展示，
+// 但打开时不会重复注册（见 bili_open 里的 CORE_IDS 判断）。
+export const GROUPS = {
+    video: {
+        hint: "视频：推荐 / 详情 / 字幕 / 分P / 播放地址 / 互动状态",
+        ids: ["bili_recommend", "bili_video_detail", "bili_video_subtitle", "bili_video_pagelist", "bili_video_playurl", "bili_video_status"],
+    },
+    search: { hint: "搜索视频或用户", ids: ["bili_search"] },
+    space: { hint: "用户空间：资料 / 投稿 / 合集", ids: ["bili_space_info", "bili_space_videos", "bili_space_collections", "bili_space_collection"] },
+    article: { hint: "专栏：详情 / 某用户的专栏列表", ids: ["bili_article_view", "bili_article_list"] },
+    dynamic: { hint: "动态：动态流 / 某用户动态 / 详情 / 发布 / 转发 / 点赞 / 删除", ids: ["bili_dynamic_feed", "bili_dynamic_space", "bili_dynamic_detail", "bili_dynamic_publish", "bili_dynamic_repost", "bili_dynamic_like", "bili_dynamic_delete"] },
+    comment: { hint: "评论：列表 / 发表 / 楼中楼 / 回复 / 删除 / 点赞（视频·动态·专栏）", ids: ["bili_comment_list", "bili_comment_send", "bili_comment_replies", "bili_comment_reply", "bili_comment_delete", "bili_comment_like"] },
+    social: { hint: "互动：点赞 / 投币 / 收藏·取消收藏 / 关注·取关 / 是否关注 / 三连", ids: ["bili_like", "bili_coin", "bili_favorite", "bili_follow", "bili_user_following", "bili_triple"] },
+    favorite: { hint: "收藏夹：列表 / 内容 / 新建 / 删除", ids: ["bili_fav_folders", "bili_fav_folder_videos", "bili_fav_folder_create", "bili_fav_folder_delete"] },
+    relation: { hint: "关注关系：关注/粉丝列表 / 关注粉丝统计", ids: ["bili_relation_list", "bili_relation_stat"] },
+    message: { hint: "私信：发送 / 未读 / 聊天记录 / 撤回", ids: ["bili_send_message", "bili_message_unread", "bili_message_history", "bili_message_recall"] },
+    notify: { hint: "消息中心：未读 / 回复·@·赞 列表", ids: ["bili_notify_unread", "bili_notify_list"] },
+    profile: { hint: "个人资料：查看 / 修改", ids: ["bili_profile_info", "bili_profile_update"] },
+};
+const TOOL_BY_ID = new Map(TOOLS.map((t) => [t.id, t]));
+function groupOfTool(id) {
+    for (const [g, def] of Object.entries(GROUPS)) {
+        if (def.ids.includes(id))
+            return g;
+    }
+    return "";
+}
+function closeGroup(group) {
+    const disposers = openGroups.get(group);
+    if (disposers)
+        for (const d of disposers) {
+            try {
+                d();
+            }
+            catch { /* ignore */ }
         }
-        const options = {
-            name: tool.id,
-            description: tool.description,
-            parameters: toDshParameters(tool.parameters),
-            output,
-            async execute(args) {
-                // 统一规整为无损 JSON，避免 toDict 里的 undefined / NaN 触发序列化错误
-                return toLosslessJson(await tool.handler(args));
+    openGroups.delete(group);
+    const i = groupLru.indexOf(group);
+    if (i >= 0)
+        groupLru.splice(i, 1);
+}
+/** 把一个内部 DshTool 编译成官方 defineTool 定义。 */
+function buildDef(tool) {
+    const output = {
+        schema: { type: "object", additionalProperties: true },
+        render: tool.render ??
+            ((_args, value) => [{ type: "text", text: textOf(value) }]),
+    };
+    if (tool.presentationMeta)
+        output.presentationMeta = tool.presentationMeta;
+    const options = {
+        name: tool.id,
+        description: tool.description,
+        parameters: toDshParameters(tool.parameters),
+        output,
+        async execute(args) {
+            return toLosslessJson(await tool.handler(args));
+        },
+    };
+    if (tool.presentResult)
+        options.presentResult = tool.presentResult;
+    return defineTool(options);
+}
+const lazyTools = [
+    {
+        id: "bili_catalog",
+        description: "列出 B 站能力分组与每组包含的工具。要用某个 B 站能力但不确定工具名时，先调本工具，再调 bili_open 打开对应分组（打开后下一轮起该组工具可调用）。",
+        parameters: { type: "object", properties: {} },
+        handler: async () => ({
+            groups: Object.entries(GROUPS).map(([name, g]) => ({
+                group: name,
+                hint: g.hint,
+                tools: g.ids,
+                open: openGroups.has(name),
+            })),
+            how: "bili_open({ group }) 或 bili_open({ tool }) 打开；bili_close({ group }) 关闭以节省上下文。",
+        }),
+    },
+    {
+        id: "bili_open",
+        description: "打开一组 B 站工具（group），或直接给工具名（tool）自动打开其所在组。打开后该组工具在下一轮即可调用。同时最多保留 3 组，超出会关闭最久未用的组。",
+        parameters: {
+            type: "object",
+            properties: {
+                group: { type: "string", description: "分组名（见 bili_catalog）" },
+                tool: { type: "string", description: "或直接给工具名，自动打开其所在组" },
             },
-        };
-        if (tool.presentResult) {
-            options.presentResult = tool.presentResult;
-        }
-        // 官方路径：ctx.tools.register(defineTool({...}))
-        const def = defineTool(options);
-        if (ctx?.tools?.register) {
-            ctx.tools.register(def);
-        }
-        else if (typeof ctx?.registerTool === "function") {
-            // 极少数运行时若用 registerTool，则回退到该接口
-            ctx.registerTool({
-                id: tool.id,
-                description: tool.description,
-                parameters: tool.parameters,
-                handler: tool.handler,
-            });
-        }
-        else if (ctx?.services?.tools?.register) {
-            ctx.services.tools.register(def);
-        }
-        else if (typeof ctx?.provide === "function") {
-            ctx.provide(`tools:${tool.id}`, tool);
-        }
+        },
+        handler: async (a) => {
+            if (!toolsRegistry) {
+                return { ok: false, message: "当前运行时不支持动态注册，懒加载不可用" };
+            }
+            let group = String(a.group ?? "").trim();
+            if (!group && a.tool)
+                group = groupOfTool(String(a.tool));
+            if (!group || !GROUPS[group]) {
+                return { ok: false, message: `未知分组/工具，可用分组：${Object.keys(GROUPS).join(", ")}` };
+            }
+            if (openGroups.has(group)) {
+                const i = groupLru.indexOf(group);
+                if (i >= 0)
+                    groupLru.splice(i, 1);
+                groupLru.push(group);
+                return { ok: true, group, alreadyOpen: true, tools: GROUPS[group].ids };
+            }
+            while (groupLru.length >= MAX_OPEN_GROUPS) {
+                const oldest = groupLru.shift();
+                if (oldest)
+                    closeGroup(oldest);
+            }
+            const disposers = [];
+            const loaded = [];
+            for (const id of GROUPS[group].ids) {
+                if (CORE_IDS.includes(id)) {
+                    loaded.push(id);
+                    continue;
+                }
+                const t = TOOL_BY_ID.get(id);
+                if (!t)
+                    continue;
+                try {
+                    const d = toolsRegistry.register(buildDef(t));
+                    if (typeof d === "function")
+                        disposers.push(d);
+                    loaded.push(id);
+                }
+                catch { /* 单个注册失败不影响其它 */ }
+            }
+            openGroups.set(group, disposers);
+            groupLru.push(group);
+            return { ok: true, group, tools: loaded, note: "该组工具已打开，下一轮起可调用。" };
+        },
+    },
+    {
+        id: "bili_close",
+        description: "关闭一组已打开的 B 站工具，释放上下文。不确定分组名先用 bili_catalog。",
+        parameters: {
+            type: "object",
+            properties: { group: { type: "string" } },
+            required: ["group"],
+        },
+        handler: async (a) => {
+            const group = String(a.group ?? "").trim();
+            if (!openGroups.has(group))
+                return { ok: false, message: "该组未打开" };
+            closeGroup(group);
+            return { ok: true, closed: group };
+        },
+    },
+];
+/** 用最可用的注册入口注册一个内部工具。 */
+function registerOne(ctx, tool) {
+    const def = buildDef(tool);
+    if (ctx?.tools?.register)
+        ctx.tools.register(def);
+    else if (typeof ctx?.registerTool === "function") {
+        ctx.registerTool({ id: tool.id, description: tool.description, parameters: tool.parameters, handler: tool.handler });
+    }
+    else if (ctx?.services?.tools?.register) {
+        ctx.services.tools.register(def);
+    }
+    else if (typeof ctx?.provide === "function") {
+        ctx.provide(`tools:${tool.id}`, tool);
+    }
+}
+export function apply(ctx) {
+    // 捕获工具注册表，供 bili_open 动态注册 / bili_close 卸载
+    toolsRegistry =
+        ctx?.tools && typeof ctx.tools.register === "function" ? ctx.tools : null;
+    // 懒加载机制工具始终注册
+    for (const t of lazyTools)
+        registerOne(ctx, t);
+    // BILI_LAZY=0 可强制关闭懒加载（全部注册），用于兜底
+    const lazyDisabled = process.env.BILI_LAZY === "0" || process.env.BILI_LAZY === "false";
+    if (!toolsRegistry || lazyDisabled) {
+        // 运行时不支持动态注册 / 手动关闭：退化为全部注册（功能完整，但不省 token）
+        for (const t of TOOLS)
+            registerOne(ctx, t);
+        return;
+    }
+    // 仅注册常驻核心，其余按需通过 bili_open 打开
+    for (const id of CORE_IDS) {
+        const t = TOOL_BY_ID.get(id);
+        if (t)
+            registerOne(ctx, t);
     }
 }
 // 同时导出库的全部公共 API（BiliClient / 各 API 类 / 模型等），

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-shlr-bilitoolkit",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "深海猎人专用B站接口工具箱 dsh 插件。",
   "type": "module",
   "main": "dist/dsh.js",