dsh-shlr-bilitoolkit 0.1.28 → 0.1.30

package/AGENTS.md

@@ -2,14 +2,17 @@
 
 ## 登录（务必遵守）
 用户要登录 B 站，或任何操作返回未登录（-101 / 未登录 / CookieError）时：
-**必须调用 bili_gen_qr，并把返回的二维码图片展示给用户扫码**——用 qrDataUrl 以 Markdown 图片 `![qr](<qrDataUrl>)` 渲染（或引用 qrImageUrl / qrImagePath）。
-禁止只给链接、用 ASCII、让用户自己跑命令。用户确认后调 bili_login_status 完成登录。
+1. 先 `bili_open({ group: "auth" })` 打开登录组（**下一轮起**才可用）；
+2. **必须调用 bili_gen_qr，并把返回的二维码图片展示给用户扫码**——用 qrDataUrl 以 Markdown 图片 `![qr](<qrDataUrl>)` 渲染（或引用 qrImageUrl / qrImagePath）；
+3. 用户扫码确认后调 `bili_login_status` 完成登录。
+
+禁止只给链接、用 ASCII、让用户自己跑命令。
 
 ## 能力按需加载
-除常驻工具（bili_gen_qr / bili_login_status / bili_recommend / bili_video_detail / bili_search / bili_open）外，其它 B 站能力默认**懒加载**：
+除常驻工具（`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. **下一轮起**该组工具才可调用。打开的组会一直保留，不会被回收。
+3. **下一轮起**该组工具才可调用。同时最多保留 3 组，超出会关掉最久没用的——顺序使用不同领域时不受影响，只有频繁在 4+ 个领域间往返才需要重新开组。
 
 ## 多步查询走 run_code（省 token）
 需要多个 B 站数据时（如「视频详情 + 热评 + UP主资料」），写进 `run_code` 一段代码里完成，不要连续调用多个工具：

package/README.md

@@ -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 / 登录态）。
-- **计费 / 缓存与懒加载**：默认**按需加载（懒加载）**——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` 取全量）。
+- **计费 / 缓存与懒加载**：默认**按需加载（懒加载）**——49 个工具 schema 约 5200 token，常驻太占上下文窗口；默认只注册「常驻核心 3 个 + `bili_open`」约 540 token，其余 `bili_open({ group })` 按需开组（下一轮生效）。登录工具在 `auth` 组（未登录时先 `bili_open({ group: "auth" })` 再 `bili_gen_qr`）。同时最多保留 **3 组**（LRU，超出关掉最久未用的）——前缀被压在「核心 + 3 组」约 1800 token 以内；顺序使用不同领域时 LRU 自然轮换、不产生额外开销。`BILI_LAZY=0` 退回全量注册（前缀稳定、命中最大化，适合不在意窗口）；`BILI_LAZY_EVICT=0` 可改成完全不淘汰；`BILI_LAZY_EVICT_MAX` 可调组数上限（默认 3）。列表类工具默认**精简返回**（`full=true` 取全量）。
 
 > **给 Agent 的约定**：仓库根目录的 [`AGENTS.md`](./AGENTS.md) 写明了登录流程——需要登录时必须调用 `bili_gen_qr` 并把二维码**图片**展示给用户，而不是只给链接或 ASCII。把这份 `AGENTS.md` 放到 dsh 的工作目录（或确保你的 dsh 会读取它），agent 就会按约定输出登录二维码。
 

package/dist/dsh.js

@@ -1139,18 +1139,15 @@ export const TOOLS = [
 let toolsRegistry = null;
 const openGroups = new Map();
 const groupLru = [];
-// 同时最多保留几组（仅 BILI_LAZY_EVICT=1 时生效）。默认不淘汰：开过就留着，
-// 前缀很快稳定、持续吃缓存命中；反复淘汰会不停改工具列表、造成缓存未命中。
+// 同时最多保留几组，超出关掉最久未用的（LRU）。默认 3：
+// 单个任务通常只用到 1-2 个能力领域；顺序做完一个再开下一个时 LRU 自然轮换，不会横跳。
+// 只有真的在 4+ 个领域间快速往返才会触发淘汰（代价=重新 bili_open，+1 轮）。
+// 想完全不淘汰设 BILI_LAZY_EVICT=0，想更宽设 BILI_LAZY_EVICT_MAX。
 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",
-    "bili_login_status",
-    "bili_recommend",
-    "bili_video_detail",
-    "bili_search",
-];
+const EVICT_GROUPS = process.env.BILI_LAZY_EVICT !== "0" && process.env.BILI_LAZY_EVICT !== "false";
+// 常驻核心：只留最高频的读取。登录工具（gen_qr / login_status）是一次性操作，
+// 放在 auth 懒加载组里，省 ~283 token/轮；AGENTS.md 与 bili_open 描述会引导模型先开组。
+export const CORE_IDS = ["bili_recommend", "bili_video_detail", "bili_search"];
 // 能力分组（group -> 提示 + 工具 id）。核心工具也会出现在所属组里，便于目录展示，
 // 但打开时不会重复注册（见 bili_open 里的 CORE_IDS 判断）。
 export const GROUPS = {
@@ -1169,6 +1166,7 @@ export const GROUPS = {
     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"] },
+    auth: { hint: "登录：生成扫码二维码 / 查询登录态（未登录或要登录时先开本组）", ids: ["bili_gen_qr", "bili_login_status"] },
     misc: { hint: "维护：清空本地缓存", ids: ["bili_cache_clear"] },
 };
 const TOOL_BY_ID = new Map(TOOLS.map((t) => [t.id, t]));
@@ -1224,7 +1222,7 @@ function buildDef(tool) {
 const lazyTools = [
     {
         id: "bili_open",
-        description: "B 站能力开关。不带参数调用=列出所有能力分组；带 group（分组名）或 tool（工具名）调用=打开该组，打开后下一轮起可调用。同时最多保留 3 组，超出自动关闭最久未用的。",
+        description: "B 站能力开关。不带参数调用=列出所有能力分组；带 group（分组名）或 tool（工具名）调用=打开该组，打开后下一轮起可调用。同时最多保留 3 组，超出自动关闭最久未用的。登录相关在 auth 组（未登录 / 要登录时先 bili_open({ group: \"auth\" })）。",
         parameters: {
             type: "object",
             properties: {

package/package.json

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