dsh-shlr-bilitoolkit 0.1.13 → 0.1.14

package/AGENTS.md

@@ -1,4 +1,4 @@
-# AGENTS.md — dsh-bili-toolkit（Agent 必读）
+（Agent 必读）
 
 ## 登录（务必遵守）
 用户要登录 B 站，或任何操作返回未登录（`-101` / `未登录` / `CookieError`）时：

package/package.json

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

package/README.md

@@ -1,125 +0,0 @@
-# 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_video_pagelist` / `bili_video_subtitles` / `bili_video_playurl` / `bili_video_status` / `bili_space_collections` / `bili_space_collection` / `bili_fav_folder_videos` / `bili_dynamic_detail` / `bili_notify_ats` / `bili_notify_likes` / `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_comment` / `bili_send_message` / `bili_triple` / `bili_dynamic_publish` / `bili_dynamic_repost` / `bili_coin` / `bili_unfavorite` / `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_sign` / `bili_profile_update`（均会真实修改账号状态，需登录）
-  - 辅助：`bili_login_status`（查登录态）/ `bili_gen_qr`（生成扫码登录二维码）/ `bili_cache_clear`（清空本地缓存）
-- 工具读取 `BILI_COOKIE_FILE`（默认 `bili_data/bili_cookies.json`）作为登录态。
-- **数据目录**：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 / 登录态）。
-
-> **给 Agent 的约定**：仓库根目录的 [`AGENTS.md`](./AGENTS.md) 写明了登录流程——需要登录时必须调用 `bili_gen_qr` 并把二维码**图片**展示给用户，而不是只给链接或 ASCII。把这份 `AGENTS.md` 放到 dsh 的工作目录（或确保你的 dsh 会读取它），agent 就会按约定输出登录二维码。
-
-安装到 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 等仍需使用习惯配合。