dsh-shlr-bilitoolkit 0.1.15 → 0.1.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +98 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# dsh-shlr-bilitoolkit
|
|
2
|
+
|
|
3
|
+
B 站（哔哩哔哩）接口封装的 **TypeScript** 移植版，作为 [dsh](https://dshmp.com)（DeepSeek Harness）插件提供「视频 / 搜索 / 空间 / 专栏 / 动态 / 评论 / 关注 / 消息中心」等读取能力，以及点赞、收藏、投币、关注、评论、私信、三连、发动态等写操作。
|
|
4
|
+
|
|
5
|
+
> 本项目从原 Python 工具箱（`bili/`）完整移植而来，并作为 dsh（cordis 体系）插件提供上述能力。
|
|
6
|
+
|
|
7
|
+
## 安装
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
# 已发布到 npm
|
|
11
|
+
dsh plugin --profile <name> add dsh-shlr-bilitoolkit@latest
|
|
12
|
+
|
|
13
|
+
# 本地开发 / 试运行
|
|
14
|
+
npm install
|
|
15
|
+
npm run build
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
本地登录（独立获取 Cookie，终端打印 ASCII 二维码）：
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
npm install && npm run login
|
|
22
|
+
# 或指定 Cookie 文件
|
|
23
|
+
BILI_COOKIE_FILE=./my_cookies.json npm run login
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## 插件入口
|
|
27
|
+
|
|
28
|
+
对齐官方 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` 回退。
|
|
29
|
+
|
|
30
|
+
## 工具清单
|
|
31
|
+
|
|
32
|
+
同类能力已用参数合并（`type` / `target` / `action` / `list`），**功能未减少**。
|
|
33
|
+
|
|
34
|
+
- **读取**：
|
|
35
|
+
`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`
|
|
36
|
+
- **写操作**（均会真实修改账号状态，需登录）：
|
|
37
|
+
`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`
|
|
38
|
+
- **辅助**：`bili_login_status`（查登录态）· `bili_gen_qr`（生成登录二维码）· `bili_cache_clear`（清空本地缓存）
|
|
39
|
+
|
|
40
|
+
合并工具的公共参数约定：
|
|
41
|
+
|
|
42
|
+
| 工具 | 参数 |
|
|
43
|
+
| --- | --- |
|
|
44
|
+
| `bili_search` | `type=video\|user`，`order`（仅视频） |
|
|
45
|
+
| `bili_relation_list` | `type=followings\|followers` |
|
|
46
|
+
| `bili_notify_list` | `type=replies\|ats\|likes` |
|
|
47
|
+
| `bili_favorite` | `action=add\|remove` |
|
|
48
|
+
| `bili_video_subtitle` | `list=true` 时列字幕轨，否则取正文 |
|
|
49
|
+
| `bili_comment_*` | `target=video\|dynamic\|article`，`id`（bvid / 动态 id / 专栏 cv 号） |
|
|
50
|
+
| `bili_profile_update` | `uname` / `sex` / `birthday` / `sign`（至少一项） |
|
|
51
|
+
|
|
52
|
+
## 数据目录
|
|
53
|
+
|
|
54
|
+
Cookie / 缓存 / 二维码 / 设备号统一放在一个目录，默认 `bili_data/`（相对 dsh 工作目录），避免散落污染工作目录：
|
|
55
|
+
|
|
56
|
+
| 文件 | 用途 |
|
|
57
|
+
| --- | --- |
|
|
58
|
+
| `bili_cookies.json` | 登录 Cookie（`SESSDATA` / `bili_jct`） |
|
|
59
|
+
| `bili_cache.json` | WBI 签名密钥 + `bvid→aid` 缓存（原子写、损坏自愈） |
|
|
60
|
+
| `bili_qrcode.png` | 最近一次生成的登录二维码 |
|
|
61
|
+
| `bili_device.json` | 私信设备号 `dev_id`（跨重启稳定，降低风控） |
|
|
62
|
+
|
|
63
|
+
可用环境变量：`BILI_DATA_DIR`（改目录）、`BILI_COOKIE_FILE` / `BILI_CACHE_FILE` / `BILI_QR_FILE` / `BILI_DEVICE_FILE`（精确指定单个文件）。兼容旧版：若新目录还没有 Cookie、而旧位置 `./bili_cookies.json` 有，会继续沿用。
|
|
64
|
+
|
|
65
|
+
## 给 Agent 的约定
|
|
66
|
+
|
|
67
|
+
仓库根目录的 [`AGENTS.md`](./AGENTS.md) 约定：需要登录时必须调用 `bili_gen_qr` 并把二维码**图片**展示给用户（而非只给链接或 ASCII）。把该 `AGENTS.md` 放到 dsh 工作目录，agent 即会遵守。
|
|
68
|
+
|
|
69
|
+
## 目录结构
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
src/
|
|
73
|
+
client.ts BiliClient：Session / Cookie / 请求 / 节流 / 重试 / 风控 / 表单编码
|
|
74
|
+
wbi.ts WbiSigner：w_rid / wts 签名（官方 mixin_key 算法，密钥落盘缓存 6h）
|
|
75
|
+
cache.ts JsonCache：本地 JSON 缓存（TTL / 原子写 / 损坏自愈）
|
|
76
|
+
errors.ts BiliApiError / CaptchaRequired / CookieError
|
|
77
|
+
models.ts 纯数据模型 + toDict()
|
|
78
|
+
formatting.ts 播放量 / 时长 / HTML 清理等展示格式化
|
|
79
|
+
pagination.ts iterPages：统一分页异步生成器
|
|
80
|
+
endpoints.ts 所有接口 URL 常量
|
|
81
|
+
apis/ video / search / space / comment / message / interact / dynamic /
|
|
82
|
+
article / relation / notify / profile / auth / download
|
|
83
|
+
dsh.ts dsh 插件入口：apply(ctx) + 工具清单
|
|
84
|
+
index.ts 对外导出
|
|
85
|
+
tests/ 离线单测（wbi 签名、格式化、缓存、lossless JSON 等）
|
|
86
|
+
cordis.patch.yml dsh 组合包配置层
|
|
87
|
+
scripts/login.ts npm run login 扫码登录脚本
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## 与原 Python 版的差异 / 已知限制
|
|
91
|
+
|
|
92
|
+
- **写接口为表单编码**：`client.post` 默认把对象编码为 `application/x-www-form-urlencoded`，仅动态点赞等少数接口显式走 JSON（`jsonBody=true`）。
|
|
93
|
+
- **动态仅支持纯文字**：带图 / 投票 / 预约的富动态需额外图片上传流程，暂未实现。
|
|
94
|
+
- **下载 / ffmpeg**：`src/apis/download.ts` 为纯工具函数，未接入 dsh 工具。
|
|
95
|
+
|
|
96
|
+
## 风控说明
|
|
97
|
+
|
|
98
|
+
内置与原 Python 版一致的基础降风控策略：请求节流（默认 0.6s + 0~0.4s 抖动）、GET 退避重试、写操作不重试、HTTP 412 / `-412` 立即停手、WBI 签名。但单账号操作量上限、避免短时间切 IP/UA 等仍需使用习惯配合。设备号 `dev_id` 已落盘保持稳定。
|