@xzxzzx/bilibili-mcp 1.6.4 → 1.7.0

package/README.md

@@ -84,8 +84,9 @@ npx -y @xzxzzx/bilibili-mcp@latest check
   - [2. 评论总结 (`get_video_comments`)](#2-评论总结-get_video_comments)
   - [3. 视频转录 (`get_video_transcript`)](#3-视频转录-get_video_transcript)
   - [4. 视频元数据 (`get_video_metadata`)](#4-视频元数据-get_video_metadata)
-  - [5. 凭证助手工具](#5-凭证助手工具)
-  - [6. 行为说明与错误处理](#6-行为说明与错误处理)
+  - [5. 视频章节 (`get_video_chapters`)](#5-视频章节-get_video_chapters)
+  - [6. 凭证助手工具](#6-凭证助手工具)
+  - [7. 行为说明与错误处理](#7-行为说明与错误处理)
 - [📋 环境要求](#-环境要求)
 - [🚀 客户端接入方式](#-客户端接入方式)
 - [⚙️ 凭证配置](#️-凭证配置)
@@ -121,24 +122,34 @@ npx -y @xzxzzx/bilibili-mcp@latest check
 ### 3. 视频转录 (`get_video_transcript`)
 - 返回纯字幕文本，按行合并
 - 支持指定偏好语言（默认按 `zh-Hans` > `ai-zh` > `zh-CN` > `zh-Hant` > `en` 优先级选择）
+- 支持多P分集选择、时间戳输出和时间区间过滤
 - 可选参数：
   - `preferred_lang`: 偏好字幕语言代码
   - `fallback_to_description`: 字幕不可用时是否降级为视频描述（默认 `false`）
+  - `page`: 多P视频分集编号（从1开始的正整数）
+  - `include_timestamps`: 每行添加 `[HH:MM:SS --> HH:MM:SS]` 时间戳前缀
+  - `start_seconds` / `end_seconds`: 只返回与此区间重叠的字幕段
 - 默认不降级：无字幕时返回 `SUBTITLE_UNAVAILABLE` 错误
+- 时间戳/区间过滤与描述降级不兼容：请求 timed 输出时不会静默降级
 - Cookie 失效时始终返回 `COOKIE_EXPIRED`，不静默降级
 
 ### 4. 视频元数据 (`get_video_metadata`)
 - 返回视频标题、作者、时长、发布时间、描述、标签、播放/点赞/投币等统计信息
+- 返回多P分集列表（`pages`），含分集编号、CID、标题和时长
 - 不获取字幕或评论
-- 仅需 `bvid_or_url` 参数
 
-### 5. 凭证助手工具
+### 5. 视频章节 (`get_video_chapters`)
+- 返回 Bilibili 创作者/平台定义的视频章节（进度条分段），含章节标题和起止时间
+- 无章节时返回空列表（`chapters: []`），不推断章节
+- 可选参数 `page`：多P视频分集编号
+
+### 6. 凭证助手工具
 
 - `get_credential_setup_instructions`: 返回安全的 Bilibili Cookie 配置命令和说明。AI agent 安装此 MCP 后可调用此工具引导用户完成配置。
 - `check_bilibili_credentials`: 检查凭证是否已配置并处于登录状态，不返回任何 Cookie 值。配置缺失或失效时返回下一步操作指引。
 - `check_mcp_update`: 检查本地包版本与 npm latest 是否一致，并返回 `npx @latest` 或全局安装的安全更新指引。
 
-### 6. 行为说明与错误处理
+### 7. 行为说明与错误处理
 
 - **Cookie 过期智能检测**：当字幕获取为空时自动验证登录状态，区分“无字幕视频”与“凭证失效”，并抛出明确的 `COOKIE_EXPIRED` 错误，避免静默降级。
 
@@ -1232,9 +1243,10 @@ BILIBILI_DEDEUSERID=<your_dedeuserid>
 | 目标 | 推荐工具 | 返回重点 |
 |---|---|---|
 | 想让 AI 总结一个视频 | `get_video_info` | 字幕优先；无字幕时返回标题、简介、标签 |
-| 只想拿完整转录文本 | `get_video_transcript` | 纯字幕文本、语言、数据来源 |
-| 想查看标题、作者、播放量等结构化信息 | `get_video_metadata` | 标题、作者、时长、发布时间、标签、统计数据 |
+| 只想拿完整转录文本 | `get_video_transcript` | 纯字幕文本、语言、数据来源；支持时间戳和区间过滤 |
+| 想查看标题、作者、播放量等结构化信息 | `get_video_metadata` | 标题、作者、时长、发布时间、标签、统计数据、多P分集列表（`pages`） |
 | 想看观众反馈和热门评论 | `get_video_comments` | 热门评论、时间戳评论、可选回复 |
+| 想看视频章节/进度条分段 | `get_video_chapters` | 章节标题、起止时间；无章节时返回空列表 |
 | 让 agent 引导用户配置 Cookie | `get_credential_setup_instructions` | 安全配置步骤、推荐命令、注意事项 |
 | 检查 Cookie 是否已配置/登录 | `check_bilibili_credentials` | configured、source、logged_in、next_steps、next_steps_zh |
 | 检查 MCP 包是否需要更新 | `check_mcp_update` | current_version、latest_version、update_available、notes_zh、更新命令 |
@@ -1305,10 +1317,25 @@ BILIBILI_DEDEUSERID=<your_dedeuserid>
 }
 ```
 
-返回内容：`bvid`、`title`、`language`、`transcript`（按行合并）、`data_source`（`subtitle` 或 `description`）。
+返回内容：`bvid`、`title`、`language`、`transcript`（按行合并）、`data_source`（`subtitle` 或 `description`）、`page`（分集编号）。
 
 > 默认无字幕时返回 `SUBTITLE_UNAVAILABLE`。如需降级，设置 `fallback_to_description: true`。
 
+**定时区间转录示例**：
+
+```json
+{
+  "name": "get_video_transcript",
+  "arguments": {
+    "bvid_or_url": "BV1xx411c7mD",
+    "page": 1,
+    "include_timestamps": true,
+    "start_seconds": 120,
+    "end_seconds": 300
+  }
+}
+```
+
 ### `get_video_metadata`
 
 **适合**：想快速了解视频基本信息，不需要字幕或评论内容。
@@ -1324,7 +1351,24 @@ BILIBILI_DEDEUSERID=<your_dedeuserid>
 }
 ```
 
-返回内容：`bvid`、`title`、`author`、`duration`、`pubdate` / `pubdate_timestamp`、`description`、`tags` 和 `stats`（播放、点赞、投币、收藏、分享、评论、弹幕）。
+返回内容：`bvid`、`title`、`author`、`duration`、`pubdate` / `pubdate_timestamp`、`description`、`tags`、`pages`（多P分集列表）和 `stats`（播放、点赞、投币、收藏、分享、评论、弹幕）。
+
+### `get_video_chapters`
+
+**适合**：获取 Bilibili 创作者定义的视频章节，用于导航或定位。
+
+请求示例：
+
+```json
+{
+  "name": "get_video_chapters",
+  "arguments": {
+    "bvid_or_url": "BV1vL411G7N7"
+  }
+}
+```
+
+返回内容：`bvid`、`page`、`cid`、`title`、`chapters`（数组，每项含 `title`、`start_seconds`、`end_seconds`）。无章节时 `chapters` 为空数组。
 
 ### `get_video_info`
 

package/README_EN.md

@@ -84,8 +84,9 @@ After the MCP server is connected, if available, call get_credential_setup_instr
   - [2. Comment Summarization (`get_video_comments`)](#2-comment-summarization-get_video_comments)
   - [3. Video Transcript (`get_video_transcript`)](#3-video-transcript-get_video_transcript)
   - [4. Video Metadata (`get_video_metadata`)](#4-video-metadata-get_video_metadata)
-  - [5. Credential Helper Tools](#5-credential-helper-tools)
-  - [6. Behavior and Error Handling](#6-behavior-and-error-handling)
+  - [5. Video Chapters (`get_video_chapters`)](#5-video-chapters-get_video_chapters)
+  - [6. Credential Helper Tools](#6-credential-helper-tools)
+  - [7. Behavior and Error Handling](#7-behavior-and-error-handling)
 - [📋 Requirements](#-requirements)
 - [🚀 Client Setup](#-client-setup)
 - [⚙️ Credential Configuration](#-credential-configuration)
@@ -121,24 +122,34 @@ After the MCP server is connected, if available, call get_credential_setup_instr
 ### 3. Video Transcript (`get_video_transcript`)
 - Returns clean subtitle text, joined by newlines.
 - Supports preferred language selection (defaults to `zh-Hans` > `ai-zh` > `zh-CN` > `zh-Hant` > `en` priority).
+- Supports multi-Part selection, timestamp output, and time-range filtering.
 - Optional parameters:
   - `preferred_lang`: Preferred subtitle language code.
   - `fallback_to_description`: Fall back to video description if subtitles unavailable (default `false`).
+  - `page`: Multi-Part video page number (1-based positive integer).
+  - `include_timestamps`: Prefix each line with `[HH:MM:SS --> HH:MM:SS]`.
+  - `start_seconds` / `end_seconds`: Only return segments overlapping this range.
 - By default, returns `SUBTITLE_UNAVAILABLE` error when no subtitles exist.
+- Timestamps/range filtering is incompatible with description fallback.
 - Cookie expiration always returns `COOKIE_EXPIRED`, never silently falls back.
 
 ### 4. Video Metadata (`get_video_metadata`)
 - Returns video title, author, duration, publish date, description, tags, and stats (views, likes, coins, etc.).
+- Returns multi-Part listing (`pages`) with page number, CID, title, and duration.
 - Does not fetch subtitles or comments.
-- Only requires the `bvid_or_url` parameter.
 
-### 5. Credential Helper Tools
+### 5. Video Chapters (`get_video_chapters`)
+- Returns Bilibili creator-defined Chapter intervals (view_points) with title, start, and end seconds.
+- Returns empty `chapters` array when no Chapters exist; never infers Chapters.
+- Accepts optional `page` parameter for multi-Part videos.
+
+### 6. Credential Helper Tools
 
 - `get_credential_setup_instructions`: Returns safe setup commands for Bilibili Cookie configuration. AI agents installing this MCP can call this tool to guide users through setup.
 - `check_bilibili_credentials`: Checks whether credentials are configured and logged in without returning Cookie values. Returns next steps when credentials are missing or invalid.
 - `check_mcp_update`: Checks the local package version against npm latest and returns safe update guidance for `npx @latest` or global installs.
 
-### 6. Behavior and Error Handling
+### 7. Behavior and Error Handling
 
 - **Intelligent Cookie Expiration Detection**: Automatically verifies login status when subtitles are empty, distinguishing between "videos without subtitles" and "invalid credentials," and throwing a clear `COOKIE_EXPIRED` error to prevent silent degradation.
 
@@ -1232,9 +1243,10 @@ Do not share cookies with others. Do not paste them into public chats, issues, P
 | Goal | Recommended tool | What you get |
 |---|---|---|
 | Summarize a video | `get_video_info` | Subtitles first; falls back to title, description, tags |
-| Get clean transcript text | `get_video_transcript` | Plain subtitle text, language, data source |
-| See structured metadata | `get_video_metadata` | Title, author, duration, publish date, tags, stats |
+| Get clean transcript text | `get_video_transcript` | Plain subtitle text, language, data source; supports timestamps and range filtering |
+| See structured metadata | `get_video_metadata` | Title, author, duration, publish date, tags, stats, multi-Part listing |
 | View audience reactions | `get_video_comments` | Popular comments, timestamped highlights, optional replies |
+| See video Chapters | `get_video_chapters` | Chapter titles, start/end seconds; empty list when absent |
 | Guide users through Cookie setup | `get_credential_setup_instructions` | Safe setup steps, recommended commands, security notes |
 | Check whether Cookies are configured/logged in | `check_bilibili_credentials` | configured, source, logged_in, next_steps, next_steps_zh |
 | Check whether the MCP package needs an update | `check_mcp_update` | current_version, latest_version, update_available, notes_zh, update commands |
@@ -1305,10 +1317,25 @@ Request:
 }
 ```
 
-Returns: `bvid`, `title`, `language`, `transcript` (newline-joined), `data_source` (`subtitle` or `description`).
+Returns: `bvid`, `title`, `language`, `transcript` (newline-joined), `data_source` (`subtitle` or `description`), `page`.
 
 > Returns `SUBTITLE_UNAVAILABLE` when no subtitles exist. Set `fallback_to_description: true` to fall back.
 
+**Timed range example**:
+
+```json
+{
+  "name": "get_video_transcript",
+  "arguments": {
+    "bvid_or_url": "BV1xx411c7mD",
+    "page": 1,
+    "include_timestamps": true,
+    "start_seconds": 120,
+    "end_seconds": 300
+  }
+}
+```
+
 ### `get_video_metadata`
 
 **Best for**: quickly checking video basics without subtitles or comments.
@@ -1324,7 +1351,24 @@ Request:
 }
 ```
 
-Returns: `bvid`, `title`, `author`, `duration`, `pubdate` / `pubdate_timestamp`, `description`, `tags`, and `stats` (views, likes, coins, favorites, shares, replies, danmaku).
+Returns: `bvid`, `title`, `author`, `duration`, `pubdate` / `pubdate_timestamp`, `description`, `tags`, `pages` (multi-Part listing), and `stats` (views, likes, coins, favorites, shares, replies, danmaku).
+
+### `get_video_chapters`
+
+**Best for**: getting Bilibili creator-defined Chapter intervals for navigation.
+
+Request:
+
+```json
+{
+  "name": "get_video_chapters",
+  "arguments": {
+    "bvid_or_url": "BV1vL411G7N7"
+  }
+}
+```
+
+Returns: `bvid`, `page`, `cid`, `title`, `chapters` (array with `title`, `start_seconds`, `end_seconds`). Empty array when no Chapters exist.
 
 ### `get_video_info`
 

package/dist/bilibili/chapters.d.ts

@@ -0,0 +1,8 @@
+import type { VideoChaptersData } from "./types.js";
+/**
+ * 获取 Bilibili 提供的视频章节（进度条分段）。
+ * 无章节时返回 chapters: []。
+ * 播放器/网络错误向上传播，不静默吞掉。
+ */
+export declare function getVideoChaptersData(bvidOrUrl: string, page?: number): Promise<VideoChaptersData>;
+//# sourceMappingURL=chapters.d.ts.map

package/dist/bilibili/chapters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chapters.d.ts","sourceRoot":"","sources":["../../src/bilibili/chapters.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAe,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAKjE;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,iBAAiB,CAAC,CA2B5B"}

package/dist/bilibili/chapters.js

@@ -0,0 +1,35 @@
+// Bilibili 视频章节（view_points）检索
+import { getPlayerData, matchPartIdentity, resolvePartCid } from "./client.js";
+import { extractBVId } from "../utils/bvid.js";
+const MAX_CHAPTER_TITLE_LENGTH = 500;
+const MAX_CHAPTERS = 200;
+/**
+ * 获取 Bilibili 提供的视频章节（进度条分段）。
+ * 无章节时返回 chapters: []。
+ * 播放器/网络错误向上传播，不静默吞掉。
+ */
+export async function getVideoChaptersData(bvidOrUrl, page) {
+    const bvid = extractBVId(bvidOrUrl);
+    const { cid, pages, videoData } = await resolvePartCid(bvidOrUrl, page);
+    const { page: displayPage, title: displayTitle } = matchPartIdentity(cid, pages, videoData.title);
+    const playerData = await getPlayerData(bvid, cid);
+    const viewPoints = playerData?.view_points;
+    const chapters = [];
+    if (viewPoints && viewPoints.length > 0) {
+        for (const vp of viewPoints.slice(0, MAX_CHAPTERS)) {
+            chapters.push({
+                title: (vp.content || vp.title || "").slice(0, MAX_CHAPTER_TITLE_LENGTH),
+                start_seconds: vp.from,
+                end_seconds: vp.to,
+            });
+        }
+    }
+    return {
+        bvid,
+        page: displayPage,
+        cid,
+        title: displayTitle,
+        chapters,
+    };
+}
+//# sourceMappingURL=chapters.js.map

package/dist/bilibili/chapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chapters.js","sourceRoot":"","sources":["../../src/bilibili/chapters.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC/E,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG/C,MAAM,wBAAwB,GAAG,GAAG,CAAC;AACrC,MAAM,YAAY,GAAG,GAAG,CAAC;AAEzB;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,SAAiB,EACjB,IAAa;IAEb,MAAM,IAAI,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;IACpC,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,cAAc,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAExE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,iBAAiB,CAAC,GAAG,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC,CAAC;IAElG,MAAM,UAAU,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAClD,MAAM,UAAU,GAAG,UAAU,EAAE,WAAW,CAAC;IAC3C,MAAM,QAAQ,GAAkB,EAAE,CAAC;IAEnC,IAAI,UAAU,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxC,KAAK,MAAM,EAAE,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,EAAE,CAAC;YACnD,QAAQ,CAAC,IAAI,CAAC;gBACZ,KAAK,EAAE,CAAE,EAA8B,CAAC,OAAiB,IAAI,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,wBAAwB,CAAC;gBAC/G,aAAa,EAAE,EAAE,CAAC,IAAI;gBACtB,WAAW,EAAE,EAAE,CAAC,EAAE;aACnB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI;QACJ,IAAI,EAAE,WAAW;QACjB,GAAG;QACH,KAAK,EAAE,YAAY;QACnB,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/dist/bilibili/client.d.ts

@@ -1,4 +1,5 @@
 export { checkLoginStatus, fetchWithWBI, fetchWithoutWBI } from "./http.js";
-export { getSubtitleContent, getVideoInfo, getVideoSubtitle, } from "./video-api.js";
+export { getPlayerData, getSubtitleContent, getVideoInfo, getVideoSubtitle, } from "./video-api.js";
 export { getVideoComments } from "./comments-api.js";
+export { matchPartIdentity, normalizePages, resolvePartCid } from "./navigation.js";
 //# sourceMappingURL=client.d.ts.map

package/dist/bilibili/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/bilibili/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5E,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/bilibili/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5E,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/bilibili/client.js

@@ -1,5 +1,6 @@
 // B站 API 客户端 — 兼容性 re-export
 export { checkLoginStatus, fetchWithWBI, fetchWithoutWBI } from "./http.js";
-export { getSubtitleContent, getVideoInfo, getVideoSubtitle, } from "./video-api.js";
+export { getPlayerData, getSubtitleContent, getVideoInfo, getVideoSubtitle, } from "./video-api.js";
 export { getVideoComments } from "./comments-api.js";
+export { matchPartIdentity, normalizePages, resolvePartCid } from "./navigation.js";
 //# sourceMappingURL=client.js.map

package/dist/bilibili/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/bilibili/client.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAC7B,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5E,OAAO,EACL,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/bilibili/client.ts"],"names":[],"mappings":"AAAA,6BAA6B;AAC7B,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5E,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/bilibili/metadata.d.ts

@@ -1,6 +1,6 @@
 import type { VideoMetadataData } from "./types.js";
 /**
- * 获取视频元数据（不含字幕、评论）
+ * 获取视频元数据（不含字幕、评论），含多P pages 列表。
  */
 export declare function getVideoMetadataData(bvidOrUrl: string): Promise<VideoMetadataData>;
 //# sourceMappingURL=metadata.d.ts.map

package/dist/bilibili/metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/bilibili/metadata.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,iBAAiB,CAAC,CA8B5B"}
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/bilibili/metadata.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,iBAAiB,CAAC,CAgC5B"}

package/dist/bilibili/metadata.js

@@ -1,12 +1,13 @@
 // 视频元数据 wrapper
-import { getVideoInfo } from "./video-api.js";
+import { getVideoInfo, resolvePartCid } from "./client.js";
 import { extractBVId } from "../utils/bvid.js";
 /**
- * 获取视频元数据（不含字幕、评论）
+ * 获取视频元数据（不含字幕、评论），含多P pages 列表。
  */
 export async function getVideoMetadataData(bvidOrUrl) {
     const bvid = extractBVId(bvidOrUrl);
     const videoData = await getVideoInfo(bvid);
+    const { pages } = await resolvePartCid(bvidOrUrl, undefined, videoData);
     const pubdate_timestamp = videoData.pubdate
         ? videoData.pubdate
         : undefined;
@@ -22,6 +23,7 @@ export async function getVideoMetadataData(bvidOrUrl) {
         pubdate_timestamp,
         description: videoData.desc || "",
         tags: videoData.tag?.map((t) => t.tag_name) || [],
+        pages,
         stats: {
             view: videoData.stat?.view,
             like: videoData.stat?.like,

package/dist/bilibili/metadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../../src/bilibili/metadata.ts"],"names":[],"mappings":"AAAA,gBAAgB;AAChB,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG/C;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,SAAiB;IAEjB,MAAM,IAAI,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;IACpC,MAAM,SAAS,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC;IAE3C,MAAM,iBAAiB,GAAG,SAAS,CAAC,OAAO;QACzC,CAAC,CAAC,SAAS,CAAC,OAAO;QACnB,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,OAAO,GAAG,iBAAiB;QAC/B,CAAC,CAAC,IAAI,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE;QAClD,CAAC,CAAC,SAAS,CAAC;IAEd,OAAO;QACL,IAAI;QACJ,KAAK,EAAE,SAAS,CAAC,KAAK;QACtB,MAAM,EAAE,SAAS,CAAC,KAAK,EAAE,IAAI;QAC7B,QAAQ,EAAE,SAAS,CAAC,QAAQ;QAC5B,OAAO;QACP,iBAAiB;QACjB,WAAW,EAAE,SAAS,CAAC,IAAI,IAAI,EAAE;QACjC,IAAI,EAAE,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE;QACjD,KAAK,EAAE;YACL,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,IAAI;YAC1B,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,IAAI;YAC1B,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,IAAI;YAC1B,QAAQ,EAAE,SAAS,CAAC,IAAI,EAAE,QAAQ;YAClC,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,KAAK;YAC5B,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,KAAK;YAC5B,OAAO,EAAE,SAAS,CAAC,IAAI,EAAE,OAAO;SACjC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../../src/bilibili/metadata.ts"],"names":[],"mappings":"AAAA,gBAAgB;AAChB,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAG/C;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,SAAiB;IAEjB,MAAM,IAAI,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;IACpC,MAAM,SAAS,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,cAAc,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IAExE,MAAM,iBAAiB,GAAG,SAAS,CAAC,OAAO;QACzC,CAAC,CAAC,SAAS,CAAC,OAAO;QACnB,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,OAAO,GAAG,iBAAiB;QAC/B,CAAC,CAAC,IAAI,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE;QAClD,CAAC,CAAC,SAAS,CAAC;IAEd,OAAO;QACL,IAAI;QACJ,KAAK,EAAE,SAAS,CAAC,KAAK;QACtB,MAAM,EAAE,SAAS,CAAC,KAAK,EAAE,IAAI;QAC7B,QAAQ,EAAE,SAAS,CAAC,QAAQ;QAC5B,OAAO;QACP,iBAAiB;QACjB,WAAW,EAAE,SAAS,CAAC,IAAI,IAAI,EAAE;QACjC,IAAI,EAAE,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE;QACjD,KAAK;QACL,KAAK,EAAE;YACL,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,IAAI;YAC1B,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,IAAI;YAC1B,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,IAAI;YAC1B,QAAQ,EAAE,SAAS,CAAC,IAAI,EAAE,QAAQ;YAClC,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,KAAK;YAC5B,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,KAAK;YAC5B,OAAO,EAAE,SAAS,CAAC,IAAI,EAAE,OAAO;SACjC;KACF,CAAC;AACJ,CAAC"}

package/dist/bilibili/navigation.d.ts

@@ -0,0 +1,25 @@
+import { getVideoInfo } from "./video-api.js";
+import type { PartInfo, RawPageEntry } from "./types.js";
+/**
+ * 将 Bilibili 原始 pages 条目规范化为 PartInfo 列表。
+ */
+export declare function normalizePages(rawPages: RawPageEntry[] | undefined): PartInfo[];
+/**
+ * 根据可选 page 解析出目标 CID 和完整的 Part 列表。
+ * page 为 undefined 时使用 top-level videoData.cid。
+ * 接受可选的 preFetchedVideoData 以避免重复请求。
+ */
+export declare function resolvePartCid(bvidOrUrl: string, page?: number, preFetchedVideoData?: Awaited<ReturnType<typeof getVideoInfo>>): Promise<{
+    cid: number;
+    pages: PartInfo[];
+    videoData: Awaited<ReturnType<typeof getVideoInfo>>;
+}>;
+/**
+ * 在 Part 列表中匹配给定 CID 的条目，返回其 page 和 title。
+ * 无匹配时返回 page=1 和 fallbackTitle。
+ */
+export declare function matchPartIdentity(cid: number, pages: PartInfo[], fallbackTitle: string): {
+    page: number;
+    title: string;
+};
+//# sourceMappingURL=navigation.d.ts.map

package/dist/bilibili/navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/bilibili/navigation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEzD;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,SAAS,GAAG,QAAQ,EAAE,CAQ/E;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,MAAM,EACb,mBAAmB,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,GAC7D,OAAO,CAAC;IACT,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC;CACrD,CAAC,CAmBD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,QAAQ,EAAE,EACjB,aAAa,EAAE,MAAM,GACpB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAIjC"}

package/dist/bilibili/navigation.js

@@ -0,0 +1,49 @@
+// 共享 Part/CID 解析模块 — 所有 page 选择工具共用
+import { getVideoInfo } from "./video-api.js";
+import { extractBVId } from "../utils/bvid.js";
+import { ValidationError } from "../utils/errors.js";
+/**
+ * 将 Bilibili 原始 pages 条目规范化为 PartInfo 列表。
+ */
+export function normalizePages(rawPages) {
+    if (!rawPages || rawPages.length === 0)
+        return [];
+    return rawPages.map((p) => ({
+        page: p.page,
+        cid: p.cid,
+        title: p.part || `P${p.page}`,
+        duration: p.duration,
+    }));
+}
+/**
+ * 根据可选 page 解析出目标 CID 和完整的 Part 列表。
+ * page 为 undefined 时使用 top-level videoData.cid。
+ * 接受可选的 preFetchedVideoData 以避免重复请求。
+ */
+export async function resolvePartCid(bvidOrUrl, page, preFetchedVideoData) {
+    const bvid = extractBVId(bvidOrUrl);
+    const videoData = preFetchedVideoData ?? await getVideoInfo(bvid);
+    const pages = normalizePages(videoData.pages);
+    if (page !== undefined) {
+        if (!Number.isInteger(page) || page < 1) {
+            throw new ValidationError("page must be a positive integer");
+        }
+        const part = pages.find((p) => p.page === page);
+        if (!part) {
+            throw new ValidationError(`Page ${page} not found. Valid pages: ${pages.length > 0 ? `1-${pages.length}` : "none (single-Part video)"}`);
+        }
+        return { cid: part.cid, pages, videoData };
+    }
+    return { cid: videoData.cid, pages, videoData };
+}
+/**
+ * 在 Part 列表中匹配给定 CID 的条目，返回其 page 和 title。
+ * 无匹配时返回 page=1 和 fallbackTitle。
+ */
+export function matchPartIdentity(cid, pages, fallbackTitle) {
+    const match = pages.find((p) => p.cid === cid);
+    if (match)
+        return { page: match.page, title: match.title };
+    return { page: 1, title: fallbackTitle };
+}
+//# sourceMappingURL=navigation.js.map

package/dist/bilibili/navigation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.js","sourceRoot":"","sources":["../../src/bilibili/navigation.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGrD;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,QAAoC;IACjE,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAClD,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC1B,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,GAAG,EAAE,CAAC,CAAC,GAAG;QACV,KAAK,EAAE,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,IAAI,EAAE;QAC7B,QAAQ,EAAE,CAAC,CAAC,QAAQ;KACrB,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,SAAiB,EACjB,IAAa,EACb,mBAA8D;IAM9D,MAAM,IAAI,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;IACpC,MAAM,SAAS,GAAG,mBAAmB,IAAI,MAAM,YAAY,CAAC,IAAI,CAAC,CAAC;IAClE,MAAM,KAAK,GAAG,cAAc,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAE9C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,eAAe,CAAC,iCAAiC,CAAC,CAAC;QAC/D,CAAC;QACD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;QAChD,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,eAAe,CACvB,QAAQ,IAAI,4BAA4B,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,0BAA0B,EAAE,CAC9G,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAC7C,CAAC;IAED,OAAO,EAAE,GAAG,EAAE,SAAS,CAAC,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AAClD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,GAAW,EACX,KAAiB,EACjB,aAAqB;IAErB,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;IAC/C,IAAI,KAAK;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;IAC3D,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC;AAC3C,CAAC"}

package/dist/bilibili/subtitle.d.ts

@@ -11,16 +11,17 @@ export interface SubtitleData {
     };
 }
 /**
- * 获取纯视频转录文本（新 API）
+ * 获取纯视频转录文本
  *
  * 不自动降级到描述。如果字幕不可用：
  * - fallbackToDescription=false -> throw NoSubtitleError
  * - fallbackToDescription=true -> return description text
  * - COOKIE_EXPIRED 错误始终向上传播
+ * - 当 timestamps 或 range 被请求时，拒绝 description fallback
  */
-export declare function getVideoTranscriptData(bvidOrUrl: string, preferredLang?: string, fallbackToDescription?: boolean): Promise<VideoTranscriptData>;
+export declare function getVideoTranscriptData(bvidOrUrl: string, preferredLang?: string, fallbackToDescription?: boolean, page?: number, includeTimestamps?: boolean, startSeconds?: number, endSeconds?: number): Promise<VideoTranscriptData>;
 /**
  * 获取视频信息及字幕
  */
-export declare function getVideoInfoWithSubtitle(bvidOrUrl: string, preferredLang?: string): Promise<SubtitleData>;
+export declare function getVideoInfoWithSubtitle(bvidOrUrl: string, preferredLang?: string, page?: number): Promise<SubtitleData>;
 //# sourceMappingURL=subtitle.d.ts.map

package/dist/bilibili/subtitle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subtitle.d.ts","sourceRoot":"","sources":["../../src/bilibili/subtitle.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAIV,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,UAAU,GAAG,aAAa,CAAC;IACxC,UAAU,EAAE;QACV,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;CACH;AA0GD;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,aAAa,CAAC,EAAE,MAAM,EACtB,qBAAqB,UAAQ,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAwG9B;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,SAAS,EAAE,MAAM,EACjB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,YAAY,CAAC,CAkKvB"}
+{"version":3,"file":"subtitle.d.ts","sourceRoot":"","sources":["../../src/bilibili/subtitle.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAGV,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,UAAU,GAAG,aAAa,CAAC;IACxC,UAAU,EAAE;QACV,KAAK,EAAE,MAAM,CAAC;QACd,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;CACH;AAkID;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,MAAM,EACjB,aAAa,CAAC,EAAE,MAAM,EACtB,qBAAqB,CAAC,EAAE,OAAO,EAC/B,IAAI,CAAC,EAAE,MAAM,EACb,iBAAiB,CAAC,EAAE,OAAO,EAC3B,YAAY,CAAC,EAAE,MAAM,EACrB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,mBAAmB,CAAC,CAoI9B;AAED;;GAEG;AACH,wBAAsB,wBAAwB,CAC5C,SAAS,EAAE,MAAM,EACjB,aAAa,CAAC,EAAE,MAAM,EACtB,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,YAAY,CAAC,CAuJvB"}