dsh-shlr-bilitoolkit 0.1.26 → 0.1.28

package/AGENTS.md

@@ -5,9 +5,16 @@
 **必须调用 bili_gen_qr，并把返回的二维码图片展示给用户扫码**——用 qrDataUrl 以 Markdown 图片 `![qr](<qrDataUrl>)` 渲染（或引用 qrImageUrl / qrImagePath）。
 禁止只给链接、用 ASCII、让用户自己跑命令。用户确认后调 bili_login_status 完成登录。
 
-## 多步查询
-需要多个 B 站数据时（如「视频详情 + 热评 + UP主资料」），尽量在一段代码里完成，不要连续调用多个工具：
-- 独立的只读调用用 `Promise.all` 并发；写操作保持逐条 `await`。
+## 能力按需加载
+除常驻工具（bili_gen_qr / bili_login_status / bili_recommend / bili_video_detail / bili_search / bili_open）外，其它 B 站能力默认**懒加载**：
+1. 先调 `bili_open()`（不带参数）看有哪些分组、每组含哪些工具；
+2. 再 `bili_open({ group: "comment" })` 或直接 `bili_open({ tool: "bili_comment_list" })` 打开；
+3. **下一轮起**该组工具才可调用。打开的组会一直保留，不会被回收。
+
+## 多步查询走 run_code（省 token）
+需要多个 B 站数据时（如「视频详情 + 热评 + UP主资料」），写进 `run_code` 一段代码里完成，不要连续调用多个工具：
+- 独立的只读调用用 `Promise.all` 并发；写操作保持逐条 `await`（串行，也避免风控）。
+- **只 `return` / `console.log` 你需要的字段**——中间工具的完整返回不会进对话，能大幅减少 token。
 
 ## 其它
 写操作（点赞 / 收藏 / 投币 / 关注 / 评论 / 私信 / 三连 / 发动态 / 改资料）会真实修改账号状态，执行前先与用户确认。

package/README.md

@@ -1,6 +1,6 @@
 # dsh-shlr-bilitoolkit
 
-0.1.15-0.1.19为工具懒加载版
+0.1.28 起默认恢复「工具懒加载」（按需开组，`BILI_LAZY=0` 可关）
 
 B 站（哔哩哔哩）接口封装的 **TypeScript** 移植版，作为 [dsh](https://dshmp.com)（DeepSeek Harness）插件提供「视频 / 搜索 / 空间」等读取能力。
 
@@ -80,7 +80,7 @@ const [ups, _] = await client.space.videos(574115689, 1, 10);
 - **数据目录**：Cookie / 缓存 / 二维码 / 设备号统一放在一个目录里，默认 `bili_data/`（相对 dsh 工作目录），避免散落污染工作目录。可用 `BILI_DATA_DIR` 改目录；`BILI_COOKIE_FILE` / `BILI_CACHE_FILE` / `BILI_QR_FILE` / `BILI_DEVICE_FILE` 可精确指定单个文件。设备号（私信 `dev_id`）会落盘到 `bili_data/bili_device.json`，跨重启保持稳定，避免被 B 站当成新设备触发风控。兼容旧版：若新目录还没有 Cookie、而旧位置（`./bili_cookies.json`）有，会继续沿用旧的。
 - **扫码登录（独立获取 Cookie）**：运行 `npm run login`，终端会打印 ASCII 二维码，用「哔哩哔哩」App 扫码并确认后，Cookie 自动写入 `bili_data/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_data/bili_cache.json`），用临时文件 + 原子替换落盘、文件损坏会自动自愈。冷启动或跨进程时直接复用，避免每次都请求 `nav` 接口；密钥过期或失效时 `refresh()` 会重新拉取并覆盖缓存。若签名反复报 `-403/-352`，可调用 `bili_cache_clear` 强制清空缓存后重试（不影响 Cookie / 登录态）。
-- **计费 / 缓存与懒加载**：默认**稳定注册全部工具**，让 prompt 前缀保持不变、最大化 DeepSeek 前缀缓存命中（未命中价 ≈ 命中价 50 倍，中途改工具列表反而更贵）。列表类工具默认**精简返回**（`full=true` 取全量）。如确认提供商不做前缀缓存、想极致压缩每轮 schema，设 `BILI_LAZY=1` 开启懒加载（常驻核心 + `bili_open` 按需开组，下一轮生效）。
+- **计费 / 缓存与懒加载**：默认**按需加载（懒加载）**——49 个工具 schema 约 5200 token，常驻太占上下文窗口；默认只注册「常驻核心 + `bili_open`」约 700 token，其余 `bili_open({ group })` 按需开组（下一轮生效），且**开过不回收**、前缀很快稳定、持续吃缓存命中。`BILI_LAZY=0` 退回全量注册（前缀稳定、命中最大化，适合不在意窗口）；`BILI_LAZY_EVICT=1` 可按 LRU 限制同时开组数（上限 `BILI_LAZY_EVICT_MAX`，默认 3）。列表类工具默认**精简返回**（`full=true` 取全量）。
 
 > **给 Agent 的约定**：仓库根目录的 [`AGENTS.md`](./AGENTS.md) 写明了登录流程——需要登录时必须调用 `bili_gen_qr` 并把二维码**图片**展示给用户，而不是只给链接或 ASCII。把这份 `AGENTS.md` 放到 dsh 的工作目录（或确保你的 dsh 会读取它），agent 就会按约定输出登录二维码。
 

package/dist/apis/dynamic.d.ts

@@ -8,7 +8,6 @@ import { Dynamic } from "../models.js";
 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]>;

package/dist/apis/dynamic.js

@@ -26,19 +26,15 @@ export class DynamicAPI {
     client;
     constructor(client) {
         this.client = client;
-        this._detailCache = {};
     }
-    _detailCache;
     async detail(dynamicId) {
-        const id = String(Math.floor(Number(dynamicId)));
-        const cached = this._detailCache[id];
-        if (cached)
-            return cached;
+        // 动态 id 常超出 JS 安全整数范围（>2^53），绝不能过 Number，否则丢精度、接口报 4101105
+        // 不做内存缓存：动态可能被删/改，缓存会返回脏数据，而它只省 HTTP、不省 LLM token。
+        const id = String(dynamicId);
         const payload = await this.client.get(endpoints.DYNAMIC_DETAIL, { id, features: FEATURES }, { Referer: `https://t.bilibili.com/${id}` });
         const dynamic = Dynamic.fromApi((payload?.data ?? {}).item);
         if (!dynamic)
             throw new BiliApiError("未找到该动态");
-        this._detailCache[id] = dynamic;
         return dynamic;
     }
     async feed(page = 1, offset, type = "all") {
@@ -182,7 +178,7 @@ export class DynamicAPI {
     }
     async repost(dynamicId, text = "") {
         const form = {
-            dynamic_id: String(Math.floor(Number(dynamicId))),
+            dynamic_id: String(dynamicId),
             content: text || "",
             csrf: this.client.csrf,
             csrf_token: this.client.csrf,
@@ -192,7 +188,7 @@ export class DynamicAPI {
     }
     async thumb(dynamicId, liked = true) {
         const body = JSON.stringify({
-            dyn_id_str: String(Math.floor(Number(dynamicId))),
+            dyn_id_str: String(dynamicId),
             up: liked ? 1 : 2,
         });
         await this.client.post(endpoints.DYNAMIC_THUMB, body, {

package/dist/dsh.js

@@ -1139,7 +1139,10 @@ export const TOOLS = [
 let toolsRegistry = null;
 const openGroups = new Map();
 const groupLru = [];
-const MAX_OPEN_GROUPS = 3;
+// 同时最多保留几组（仅 BILI_LAZY_EVICT=1 时生效）。默认不淘汰：开过就留着，
+// 前缀很快稳定、持续吃缓存命中；反复淘汰会不停改工具列表、造成缓存未命中。
+const MAX_OPEN_GROUPS = Number(process.env.BILI_LAZY_EVICT_MAX ?? 3) || 3;
+const EVICT_GROUPS = process.env.BILI_LAZY_EVICT === "1" || process.env.BILI_LAZY_EVICT === "true";
 // 常驻核心：登录链路必须随时可用 + 最常用的几个读取
 export const CORE_IDS = [
     "bili_gen_qr",
@@ -1258,10 +1261,14 @@ const lazyTools = [
                 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);
+            // 默认不淘汰（单调累加）：前缀稳定、持续吃缓存命中。
+            // 仅在 BILI_LAZY_EVICT=1 时按 LRU 淘汰，限制同时开组数。
+            if (EVICT_GROUPS) {
+                while (groupLru.length >= MAX_OPEN_GROUPS) {
+                    const oldest = groupLru.shift();
+                    if (oldest)
+                        closeGroup(oldest);
+                }
             }
             const disposers = [];
             const loaded = [];
@@ -1306,12 +1313,11 @@ export function apply(ctx) {
     // 捕获工具注册表，供懒加载模式下的 bili_open 动态注册
     toolsRegistry =
         ctx?.tools && typeof ctx.tools.register === "function" ? ctx.tools : null;
-    // 默认：稳定注册全部工具——让 prompt 前缀保持不变、最大化 DeepSeek 前缀缓存命中。
-    // （缓存未命中价 ≈ 命中价 50 倍；工具 schema 在前缀里是命中价、成本可忽略，
-    //   中途改工具列表反而造成未命中、更贵。）只有确认提供商不做前缀缓存、
-    //   想极致压缩每轮 schema 时，才用 BILI_LAZY=1 开启懒加载。
+    // 默认开懒加载（理由见上方「懒加载」注释）：49 个工具约 5200 token 常驻太占窗口，
+    // 按需加载后默认前缀只剩「核心 + bili_open」约 700 token。
+    // BILI_LAZY=0 可强制全量注册（前缀稳定、缓存命中最大化，适合不在意窗口的场景）。
     const lazyEnabled = !!toolsRegistry &&
-        (process.env.BILI_LAZY === "1" || process.env.BILI_LAZY === "true");
+        !(process.env.BILI_LAZY === "0" || process.env.BILI_LAZY === "false");
     if (!lazyEnabled) {
         for (const t of TOOLS)
             registerOne(ctx, t);

package/package.json

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