dsh-shlr-bilitoolkit 0.1.16 → 0.1.18

package/AGENTS.md

@@ -1,10 +1,10 @@
-（Agent 必读）
+# AGENTS.md — dsh-shlr-bilitoolkit（Agent 必读）
 
 ## 登录（务必遵守）
-用户要登录 B 站，或任何操作返回未登录（`-101` / `未登录` / `CookieError`）时：
-**必须调用 `bili_gen_qr`，并把返回的二维码图片展示给用户扫码**——用 `qrDataUrl` 以 Markdown 图片 `![qr](<qrDataUrl>)` 渲染（或引用 `qrImageUrl` / `qrImagePath`）。
-
-禁止：只给链接、用 ASCII/文本二维码、让用户自己跑命令。用户扫码确认后调用 `bili_login_status` 完成登录并保存 Cookie。
+用户要登录 B 站，或任何操作返回未登录（-101 / 未登录 / CookieError）时：
+**必须调用 bili_gen_qr，并把返回的二维码图片展示给用户扫码**——用 qrDataUrl 以 Markdown 图片 `![qr](<qrDataUrl>)` 渲染（或引用 qrImageUrl / qrImagePath）。
+禁止只给链接、用 ASCII、让用户自己跑命令。用户确认后调 bili_login_status 完成登录。
 
 ## 其它
-全部能力见各 `bili_*` 工具描述；写操作会真实修改账号状态，执行前先与用户确认。
+- 非常驻的 B 站能力懒加载：`bili_open()` 看分组，`bili_open({ group })` 打开（下一轮生效）。
+- 写操作会真实修改账号状态，执行前先与用户确认。

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,186 @@ 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_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"] },
+    misc: { hint: "维护：清空本地缓存", ids: ["bili_cache_clear"] },
+};
+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_open",
+        description: "B 站能力开关。不带参数调用=列出所有能力分组；带 group（分组名）或 tool（工具名）调用=打开该组，打开后下一轮起可调用。同时最多保留 3 组，超出自动关闭最久未用的。",
+        parameters: {
+            type: "object",
+            properties: {
+                group: { type: "string", description: "分组名（不带参调用可列出）" },
+                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 (a.group == null && a.tool == null) {
+                return {
+                    groups: Object.entries(GROUPS).map(([name, g]) => ({
+                        group: name,
+                        hint: g.hint,
+                        tools: g.ids,
+                        open: openGroups.has(name),
+                    })),
+                    how: "带 group 或 tool 再次调用本工具即可打开；同时最多保留 3 组。",
+                };
+            }
+            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: "该组工具已打开，下一轮起可调用。" };
+        },
+    },
+];
+/** 用最可用的注册入口注册一个内部工具。 */
+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.16",
+  "version": "0.1.18",
   "description": "深海猎人专用B站接口工具箱 dsh 插件。",
   "type": "module",
   "main": "dist/dsh.js",