catpaw-drive-core 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# catpaw-drive-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+用于分享链接识别、网盘目录、影视文件匹配、转存、播放解析和转存清理的 JavaScript 核心。支持夸克、百度、UC、115、123、迅雷、光鸭、移动、天翼；各盘能力和权限要求不同，不代表所有网盘支持相同画质或下载方式。
+
+首版 `0.1.0` 复用 CatPaw 当前正式 `2.2.4` 网盘引擎，发布 ESM、CommonJS、浏览器 IIFE 及 TypeScript 类型，无 npm 运行时依赖。公开包只提供混淆构建产物，不包含可读源码或 source map。混淆用于增加阅读成本，不能保证代码无法还原。
+
+## 安装与构建
+
+```sh
+npm install catpaw-drive-core@0.1.0
+```
+
+```js
+import { createDriveCore } from 'catpaw-drive-core';
+
+const core = createDriveCore({
+  namespace: 'your-module.pan',
+  http: Widget.http,
+  storage: Widget.storage,
+  // 该可选缓存仅用于当前模块自己的转存、令牌等状态，并按 namespace 隔离。
+  sharedCache: Widget.sharedCache,
+  // 共享账号入口由调用方选择，核心通过 getConfig 获取只读快照。
+  getConfig() {
+    try {
+      const raw = Widget.sharedCache.get('catpaw.drive-accounts.v1', 'credentials');
+      return typeof raw === 'string' ? JSON.parse(raw) : null;
+    } catch { return null; }
+  },
+});
+
+// 每次业务入口先绑定本模块的有效配置；账号非空优先，留空继承 getConfig。
+core.bind({});
+const share = core.parseShare({ url: 'https://drive.uc.cn/s/SHARE_ID', password: '' });
+if (!share) throw new Error('无法识别分享链接');
+if (!core.enabled(share.provider)) throw new Error('该网盘未启用');
+const link = core.encode({ action: 'detail', title: '作品标题', shares: [share] });
+const detail = await core.loadDetail(link);
+const episode = detail && !Array.isArray(detail) && detail.episodeItems?.[0];
+if (episode) {
+  const resources = await core.loadResource({ link: episode.link });
+  // 使用 resources 中的 url 及 headers/customHeaders 交给宿主播放。
+}
+```
+
+CommonJS 使用 `require('catpaw-drive-core')`。浏览器脚本 `dist/drive-core.global.js` 提供 `DriveCore` 全局对象。Rex 模块需要在构建阶段将 npm 包打入单文件，再使用原模块加密发布流程；仅安装 npm 包不会让 Rex 在运行时支持 npm import。
+
+## 宿主接口
+
+- `namespace`：必填，每个模块使用独立值，例如 `your-module.pan`，仅小写字母、数字、点和短横线，最多 96 字符。
+- `http.get(url, options)`、`http.post(url, body, options)`：必填，返回 Promise，结果含 `status`/`statusCode`、`data`、`headers`。请求配置沿用 Rex 风格的 `timeout`（通常按毫秒）；可选 `http.request` 接收 Rex 原生请求参数，其中 `timeout` 按秒传递。宿主有差异时请自行适配。
+- `storage.get(key)`、`storage.set(key, value)`：必填同步字符串存储。核心自动在 key 前加模块 namespace。
+- `sharedCache.get(namespace, key)`、`set(namespace, key, value)`：可选同步共享字符串缓存。自动加模块 namespace；未提供时使用实例内存缓存。
+- `getConfig()`：可选同步函数，返回 schemaVersion 1 的账号配置对象或 null，不要返回 Promise。账号只通过本函数读取，核心不会直接访问宿主的全局共享账号记录。
+- `tmdb.get(path, options)`：可选，用于可信影视别名和年份信息；由调用方实现。
+- `site`：可选的调用方 HTTP(S) origin，不含结尾斜杠，默认 `https://drive-core.invalid`。仅作为来源身份，不会自动进行网站搜索。
+
+转存根目录为 `drive-core.<namespace>`；每个模块只扫描自己的转存目录，不扫描现有 Rex 的 `ftv-cache`。namespace 应保持稳定，改名后原目录需由用户自行处理。
+
+同一业务调用内不要并行更换同一实例的账号。多个模块、独立账号和并行 session 使用独立实例及 namespace。
+
+## 账号配置
+
+`getConfig()` 对象至少包含：
+
+```json
+{
+  "schemaVersion": 1,
+  "revision": 1,
+  "quarkCookie": "",
+  "baiduCookie": "",
+  "cookie115": "",
+  "guangyaAuth": "{\"accessToken\":\"ACCESS\",\"refreshToken\":\"REFRESH\",\"deviceId\":\"DEVICE\"}",
+  "xunleiAuth": "",
+  "tianyiCookie": "",
+  "driveGuangyaEnabled": "enabled"
+}
+```
+
+光鸭、迅雷界面虽可分三个输入框，共享快照仍分别使用 `guangyaAuth`、`xunleiAuth` 字符串；值可以是访问令牌或整套 JSON。核心沿用现有凭证别名、迅雷 Web/App 识别和续期逻辑。
+
+`core.bind(params)` 接受本模块的 `quarkCookie`、`baiduCookie`、`cookie115`、`tianyiCookie`，以及 `guangyaAuth / guangyaRefreshToken / guangyaDeviceId`、`xunleiAuth / xunleiRefreshToken / xunleiDeviceId`。Cookie 非空优先，留空继承共享配置。光鸭、迅雷任一输入非空时使用本模块整套凭证，三项全空才继承；不会混用两个账号的令牌和设备号。`credentialSource: 'local'` 可停用共享账号继承。
+
+共享快照还可包含 `driveQuarkEnabled / driveBaiduEnabled / driveUcEnabled / drive115Enabled / drive123Enabled / driveXunleiEnabled / driveGuangyaEnabled / driveYidongEnabled / driveTianyiEnabled`，值为 `enabled` 或 `disabled`。迅雷、光鸭、移动、天翼默认关闭，其他五盘默认开启。配置本地账号不会自动启用关闭的网盘。
+
+`quarkQuality`、`maxShareCandidates`、`indexTimeoutSeconds` 等现有共享设置继续适用；配置变更需更新 revision，并在下次操作前重新 bind。令牌轮换保存到模块自己的会话存储，不回写共享账号配置。
+
+## API
+
+| 方法 | 用途 |
+|---|---|
+| `bind(params)` | 绑定当前模块配置和账号 |
+| `enabled(provider)` | 查询网盘开关 |
+| `parseShare({url,password?,note?})` | 识别分享；失败返回 null |
+| `encode(descriptor)` / `decode(link)` | 编解码当前引擎资源描述 |
+| `isLink(link)` | 判断是否当前资源链接前缀 |
+| `loadDetail(link)` | 读取分享目录和分集；播放描述可能返回资源数组 |
+| `loadResource(params, discovery?)` | 解析播放资源；自动选集可传 seriesName、type、year、season、episode |
+| `clear()` | 清理当前模块的目录缓存 |
+| `candidateLimit()` | 查询当前候选档位 |
+| `matchesSiteTitle(title, params)` | 使用共享标题匹配规则 |
+| `prepareDirectoryIdentity(year, params)` | 准备可信年份信息 |
+| `owner()` / `request(spec, request, owner?)` | 网站适配器共享当前预算与取消检查 |
+
+目录、转存和播放操作可能改变已登录网盘中的文件。`transferAutoCleanup` 默认关闭；启用后，夸克、迅雷和光鸭按两小时未使用时间清理本模块转存文件，并沿用来源引擎的**账号整个回收站清空行为**，其中包括其他模块或用户删除的内容。调用方应明确告知用户这一行为，谨慎启用。账号、播放地址和带认证信息的请求不得写入公开日志。
+
+## 网站发现由调用方提供
+
+core 不内置全盘或其他资源站点的搜索后端。已有模块自行完成搜索、详情和分享地址提取，再将标准化分享传入 core。需要复用自动匹配调度时，可传入 `discovery`：
+
+- `identity`：网站账号/来源的稳定身份，账号变化时更新。
+- `search(params)`：返回含 `title`、`provider` 和 `link` 的候选条目；link 可用 `core.encode(descriptor)` 生成。
+- `read(row, params)`：返回包含 title、shares 的 `action: 'detail'` 描述或 null。
+
+没有 discovery、也没有直接资源 link 时返回空结果，不向任何默认搜索网站请求。
+
+## 版本与有效期
+
+`version` 为 npm 包版本，`engineVersion` 为来源引擎版本。npm 核心包没有日历使用期限；构建时移除了来源引擎的到期检查。网盘令牌和播放地址自身的过期、续期与刷新规则继续正常执行。
+
+发布前验证以离线协议回放、混淆产物和 npm tarball 消费端检查为主，不保证真实账号、网盘权限、接口变化及宿主差异下所有播放均可用。pansoo、pioz 等模块需要其作者实际接入和验证，安装本包不会自动修改已有模块。
+
+## 使用授权
+
+包当前标记为 `UNLICENSED`，公开下载不授予开源许可证；集成和分发授权请联系作者 balge2019。