@jackwener/opencli 1.6.1 → 1.6.2

package/src/clis/amazon/rankings.ts

@@ -0,0 +1,312 @@
+import { CommandExecutionError } from '../../errors.js';
+import { Strategy, type CliOptions } from '../../registry.js';
+import type { IPage } from '../../types.js';
+import {
+  assertUsableState,
+  buildProvenance,
+  cleanText,
+  extractAsin,
+  extractCategoryNodeId,
+  extractReviewCountFromCardText,
+  firstMeaningfulLine,
+  gotoAndReadState,
+  isRankingPaginationUrl,
+  normalizeProductUrl,
+  parsePriceText,
+  parseRatingValue,
+  parseReviewCount,
+  resolveRankingUrl,
+  toAbsoluteAmazonUrl,
+  uniqueNonEmpty,
+  type AmazonRankingListType,
+} from './shared.js';
+
+export interface RankingCardPayload {
+  rank_text?: string | null;
+  asin?: string | null;
+  title?: string | null;
+  href?: string | null;
+  price_text?: string | null;
+  rating_text?: string | null;
+  review_count_text?: string | null;
+  card_text?: string | null;
+}
+
+interface RankingPagePayload {
+  href?: string;
+  title?: string;
+  list_title?: string;
+  category_title?: string;
+  category_path?: string[];
+  cards?: RankingCardPayload[];
+  page_links?: string[];
+  visible_category_links?: Array<{
+    title?: string | null;
+    url?: string | null;
+    node_id?: string | null;
+  }>;
+}
+
+interface RankingCommandDefinition {
+  commandName: string;
+  listType: AmazonRankingListType;
+  description: string;
+}
+
+interface RankingNormalizeContext {
+  listType: AmazonRankingListType;
+  rankFallback: number;
+  listTitle: string | null;
+  sourceUrl: string;
+  categoryTitle: string | null;
+  categoryUrl: string | null;
+  categoryPath: string[];
+  visibleCategoryLinks: Array<{ title: string; url: string; node_id: string | null }>;
+}
+
+function parseRank(rawRank: string | null | undefined, fallback: number): number {
+  const normalized = cleanText(rawRank);
+  const match = normalized.match(/(\d{1,4})/);
+  if (!match) return fallback;
+  const parsed = Number.parseInt(match[1], 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function normalizeVisibleCategoryLinks(
+  links: RankingPagePayload['visible_category_links'],
+): Array<{ title: string; url: string; node_id: string | null }> {
+  const normalized = (links ?? [])
+    .map((entry) => ({
+      title: cleanText(entry?.title),
+      url: toAbsoluteAmazonUrl(entry?.url) ?? '',
+      node_id: cleanText(entry?.node_id) || extractCategoryNodeId(entry?.url) || null,
+    }))
+    .filter((entry) => Boolean(entry.title) && Boolean(entry.url));
+
+  const seen = new Set<string>();
+  const deduped: Array<{ title: string; url: string; node_id: string | null }> = [];
+  for (const entry of normalized) {
+    if (seen.has(entry.url)) continue;
+    seen.add(entry.url);
+    deduped.push(entry);
+  }
+  return deduped;
+}
+
+export function normalizeRankingCandidate(
+  candidate: RankingCardPayload,
+  context: RankingNormalizeContext,
+): Record<string, unknown> {
+  const productUrl = normalizeProductUrl(candidate.href);
+  const asin = extractAsin(candidate.asin ?? '') ?? extractAsin(productUrl ?? '') ?? null;
+  const title = cleanText(candidate.title) || firstMeaningfulLine(candidate.card_text);
+  const price = parsePriceText(cleanText(candidate.price_text) || candidate.card_text);
+  const ratingText = cleanText(candidate.rating_text) || null;
+  const reviewCountText = cleanText(candidate.review_count_text)
+    || extractReviewCountFromCardText(candidate.card_text)
+    || null;
+  const provenance = buildProvenance(context.sourceUrl);
+  const categoryUrl = context.categoryUrl || context.sourceUrl;
+
+  return {
+    list_type: context.listType,
+    rank: parseRank(candidate.rank_text, context.rankFallback),
+    asin,
+    title: title || null,
+    product_url: productUrl,
+    price_text: price.price_text,
+    price_value: price.price_value,
+    currency: price.currency,
+    rating_text: ratingText,
+    rating_value: parseRatingValue(ratingText),
+    review_count_text: reviewCountText,
+    review_count: parseReviewCount(reviewCountText),
+    list_title: context.listTitle,
+    category_title: context.categoryTitle,
+    category_url: categoryUrl,
+    category_node_id: extractCategoryNodeId(categoryUrl),
+    category_path: context.categoryPath,
+    visible_category_links: context.visibleCategoryLinks,
+    ...provenance,
+  };
+}
+
+async function readRankingPage(
+  page: IPage,
+  listType: AmazonRankingListType,
+  url: string,
+): Promise<RankingPagePayload> {
+  const state = await gotoAndReadState(page, url, 2500, listType);
+  assertUsableState(state, listType);
+
+  return await page.evaluate(`
+    (() => ({
+      href: window.location.href,
+      title: document.title || '',
+      list_title:
+        document.querySelector('#zg_banner_text')?.textContent
+        || document.querySelector('h1')?.textContent
+        || '',
+      category_title:
+        document.querySelector('#zg_browseRoot .zg_selected')?.textContent
+        || document.querySelector('#wayfinding-breadcrumbs_feature_div ul li:last-child')?.textContent
+        || document.querySelector('#wayfinding-breadcrumbs_container ul li:last-child')?.textContent
+        || '',
+      category_path: Array.from(document.querySelectorAll(
+        '#zg_browseRoot ul li a, #zg_browseRoot ul li span, ' +
+        '#wayfinding-breadcrumbs_feature_div ul li a, #wayfinding-breadcrumbs_feature_div ul li span.a-list-item, ' +
+        '#wayfinding-breadcrumbs_container ul li a, #wayfinding-breadcrumbs_container ul li span.a-list-item'
+      ))
+        .map((entry) => (entry.textContent || '').trim())
+        .filter(Boolean),
+      cards: Array.from(document.querySelectorAll(
+        '.p13n-sc-uncoverable-faceout, .zg-grid-general-faceout, [data-asin][class*="p13n"]'
+      )).map((card) => ({
+        rank_text:
+          card.querySelector('.zg-bdg-text')?.textContent
+          || card.querySelector('[class*="rank"]')?.textContent
+          || '',
+        asin:
+          card.getAttribute('data-asin')
+          || card.getAttribute('id')
+          || '',
+        title:
+          card.querySelector('[class*="line-clamp"]')?.textContent
+          || card.querySelector('img')?.getAttribute('alt')
+          || card.querySelector('a[href*="/dp/"]')?.textContent
+          || '',
+        href:
+          card.querySelector('a[href*="/dp/"], a[href*="/gp/product/"]')?.href
+          || '',
+        price_text:
+          card.querySelector('.a-price .a-offscreen')?.textContent
+          || card.querySelector('.a-color-price')?.textContent
+          || '',
+        rating_text:
+          card.querySelector('[aria-label*="out of 5 stars"]')?.getAttribute('aria-label')
+          || '',
+        review_count_text:
+          card.querySelector('a[href*="#customerReviews"]')?.textContent
+          || card.querySelector('.a-size-small')?.textContent
+          || '',
+        card_text: card.innerText || '',
+      })),
+      page_links: Array.from(document.querySelectorAll('.a-pagination a[href], li.a-normal a[href], li.a-selected a[href]'))
+        .map((anchor) => anchor.href || '')
+        .filter(Boolean),
+      visible_category_links: Array.from(document.querySelectorAll(
+        '#zg_browseRoot a[href], #zg-left-col a[href], [class*="zg-browse"] a[href]'
+      )).map((anchor) => ({
+        title: (anchor.textContent || '').trim(),
+        url: anchor.href || '',
+        node_id:
+          anchor.getAttribute('data-node-id')
+          || anchor.dataset?.nodeid
+          || '',
+      }))
+        .filter((entry) => entry.title && entry.url),
+    }))()
+  `) as RankingPagePayload;
+}
+
+function createEmptyResultHint(commandName: string): string {
+  return [
+    `Open the same Amazon ${commandName} page in shared Chrome and verify ranked items are visible.`,
+    'If the page shows a robot check, clear it manually and retry.',
+  ].join(' ');
+}
+
+export function createRankingCliOptions(definition: RankingCommandDefinition): CliOptions {
+  return {
+    site: 'amazon',
+    name: definition.commandName,
+    description: definition.description,
+    domain: 'amazon.com',
+    strategy: Strategy.COOKIE,
+    navigateBefore: false,
+    args: [
+      {
+        name: 'input',
+        positional: true,
+        help: 'Ranking URL or supported Amazon path. Omit to use the list root.',
+      },
+      {
+        name: 'limit',
+        type: 'int',
+        default: 100,
+        help: 'Maximum number of ranked items to return (default 100)',
+      },
+    ],
+    columns: ['list_type', 'rank', 'asin', 'title', 'price_text', 'rating_value', 'review_count'],
+    func: async (page, kwargs) => {
+      const limit = Math.max(1, Number(kwargs.limit) || 100);
+      const initialUrl = resolveRankingUrl(definition.listType, typeof kwargs.input === 'string' ? kwargs.input : undefined);
+
+      const queue = [initialUrl];
+      const visited = new Set<string>();
+      const seenEntityKeys = new Set<string>();
+      const results: Record<string, unknown>[] = [];
+      let listTitle: string | null = null;
+
+      while (queue.length > 0 && results.length < limit) {
+        const nextUrl = queue.shift()!;
+        if (visited.has(nextUrl)) continue;
+        visited.add(nextUrl);
+
+        const payload = await readRankingPage(page, definition.listType, nextUrl);
+        const sourceUrl = cleanText(payload.href) || nextUrl;
+        listTitle = cleanText(payload.list_title) || cleanText(payload.title) || listTitle;
+        const categoryPath = uniqueNonEmpty(payload.category_path ?? []);
+        const categoryTitle = cleanText(payload.category_title)
+          || (categoryPath.length > 0 ? categoryPath[categoryPath.length - 1] : '');
+        const visibleCategoryLinks = normalizeVisibleCategoryLinks(payload.visible_category_links);
+        const cards = payload.cards ?? [];
+
+        for (const card of cards) {
+          const normalized = normalizeRankingCandidate(card, {
+            listType: definition.listType,
+            rankFallback: results.length + 1,
+            listTitle,
+            sourceUrl,
+            categoryTitle: categoryTitle || null,
+            categoryUrl: sourceUrl,
+            categoryPath,
+            visibleCategoryLinks,
+          });
+
+          const dedupeKey = cleanText(String(normalized.asin ?? ''))
+            || cleanText(String(normalized.product_url ?? ''));
+          if (dedupeKey && seenEntityKeys.has(dedupeKey)) continue;
+          if (dedupeKey) seenEntityKeys.add(dedupeKey);
+
+          results.push(normalized);
+          if (results.length >= limit) break;
+        }
+
+        const pageLinks = uniqueNonEmpty(payload.page_links ?? []);
+        for (const href of pageLinks) {
+          const absolute = toAbsoluteAmazonUrl(href);
+          if (!absolute || !isRankingPaginationUrl(definition.listType, absolute)) continue;
+          if (!visited.has(absolute) && !queue.includes(absolute)) {
+            queue.push(absolute);
+          }
+        }
+      }
+
+      if (results.length === 0) {
+        throw new CommandExecutionError(
+          `amazon ${definition.commandName} did not expose any ranked items`,
+          createEmptyResultHint(definition.commandName),
+        );
+      }
+
+      return results.slice(0, limit);
+    },
+  };
+}
+
+export const __test__ = {
+  parseRank,
+  normalizeVisibleCategoryLinks,
+  normalizeRankingCandidate,
+};

package/src/clis/amazon/shared.test.ts

@@ -34,4 +34,20 @@ describe('amazon shared helpers', () => {
     expect(__test__.resolveBestsellersUrl('/Best-Sellers/zgbs')).toBe('https://www.amazon.com/Best-Sellers/zgbs');
     expect(() => __test__.resolveBestsellersUrl('desk shelf organizer')).toThrow('amazon bestsellers expects a best sellers URL or /zgbs path');
   });
+
+  it('resolves and validates all ranking list URLs', () => {
+    expect(__test__.resolveRankingUrl('new_releases')).toBe('https://www.amazon.com/gp/new-releases');
+    expect(__test__.resolveRankingUrl('movers_shakers')).toBe('https://www.amazon.com/gp/movers-and-shakers');
+    expect(__test__.resolveRankingUrl('new_releases', '/gp/new-releases/kitchen')).toBe('https://www.amazon.com/gp/new-releases/kitchen');
+    expect(__test__.resolveRankingUrl(
+      'bestsellers',
+      'https://www.amazon.com/Best-Sellers/zgbs/ref=zg_bsnr_tab_bs',
+    )).toBe('https://www.amazon.com/Best-Sellers/zgbs');
+    expect(() => __test__.resolveRankingUrl('movers_shakers', 'https://example.com/gp/movers-and-shakers')).toThrow('Invalid Amazon URL');
+  });
+
+  it('extracts category node id from URL best effort', () => {
+    expect(__test__.extractCategoryNodeId('https://www.amazon.com/Best-Sellers-Home-Kitchen/zgbs/home-garden/3744371')).toBe('3744371');
+    expect(__test__.extractCategoryNodeId('https://www.amazon.com/s?k=desk+organizer&rh=n%3A1064954')).toBe('1064954');
+  });
 });

package/src/clis/amazon/shared.ts

@@ -5,6 +5,8 @@ export const SITE = 'amazon';
 export const DOMAIN = 'amazon.com';
 export const HOME_URL = 'https://www.amazon.com/';
 export const BESTSELLERS_URL = 'https://www.amazon.com/Best-Sellers/zgbs';
+export const NEW_RELEASES_URL = 'https://www.amazon.com/gp/new-releases';
+export const MOVERS_SHAKERS_URL = 'https://www.amazon.com/gp/movers-and-shakers';
 export const SEARCH_URL_PREFIX = 'https://www.amazon.com/s?k=';
 export const PRODUCT_URL_PREFIX = 'https://www.amazon.com/dp/';
 export const DISCUSSION_URL_PREFIX = 'https://www.amazon.com/product-reviews/';
@@ -28,6 +30,40 @@ const ROBOT_TEXT_PATTERNS = [
   'To discuss automated access to Amazon data please contact',
 ];
 
+export type AmazonRankingListType = 'bestsellers' | 'new_releases' | 'movers_shakers';
+
+interface AmazonRankingSpec {
+  commandName: string;
+  rootUrl: string;
+  pathPattern: RegExp;
+  invalidInputMessage: string;
+  invalidInputHint: string;
+}
+
+const AMAZON_RANKING_SPECS: Record<AmazonRankingListType, AmazonRankingSpec> = {
+  bestsellers: {
+    commandName: 'bestsellers',
+    rootUrl: BESTSELLERS_URL,
+    pathPattern: /(?:^|\/)zgbs(?:\/|$)/i,
+    invalidInputMessage: 'amazon bestsellers expects a best sellers URL or /zgbs path',
+    invalidInputHint: 'Example: opencli amazon bestsellers https://www.amazon.com/Best-Sellers/zgbs',
+  },
+  new_releases: {
+    commandName: 'new-releases',
+    rootUrl: NEW_RELEASES_URL,
+    pathPattern: /\/gp\/new-releases(?:\/|$)/i,
+    invalidInputMessage: 'amazon new-releases expects a new releases URL or /gp/new-releases path',
+    invalidInputHint: 'Example: opencli amazon new-releases https://www.amazon.com/gp/new-releases',
+  },
+  movers_shakers: {
+    commandName: 'movers-shakers',
+    rootUrl: MOVERS_SHAKERS_URL,
+    pathPattern: /\/gp\/movers-and-shakers(?:\/|$)/i,
+    invalidInputMessage: 'amazon movers-shakers expects a movers-and-shakers URL or /gp/movers-and-shakers path',
+    invalidInputHint: 'Example: opencli amazon movers-shakers https://www.amazon.com/gp/movers-and-shakers',
+  },
+};
+
 export interface ProvenanceFields {
   source_url: string;
   fetched_at: string;
@@ -115,23 +151,105 @@ export function buildDiscussionUrl(input: string): string {
   return `${DISCUSSION_URL_PREFIX}${asin}`;
 }
 
-export function resolveBestsellersUrl(input?: string): string {
+function getRankingSpec(listType: AmazonRankingListType): AmazonRankingSpec {
+  return AMAZON_RANKING_SPECS[listType];
+}
+
+export function isSupportedRankingPath(listType: AmazonRankingListType, inputUrl: string): boolean {
+  try {
+    const url = new URL(inputUrl);
+    return getRankingSpec(listType).pathPattern.test(url.pathname);
+  } catch {
+    return false;
+  }
+}
+
+export function resolveRankingUrl(listType: AmazonRankingListType, input?: string): string {
+  const spec = getRankingSpec(listType);
   const normalized = cleanText(input);
-  if (!normalized) return BESTSELLERS_URL;
-  if (normalized === 'root') return BESTSELLERS_URL;
+  if (!normalized || normalized === 'root') return spec.rootUrl;
+
+  let candidateUrl: string;
   if (normalized.startsWith('/')) {
-    return new URL(normalized, HOME_URL).toString();
+    candidateUrl = new URL(normalized, HOME_URL).toString();
+  } else if (/^https?:\/\//i.test(normalized)) {
+    candidateUrl = canonicalizeAmazonUrl(normalized);
+  } else if (normalized.includes('amazon.') && normalized.includes('/')) {
+    candidateUrl = canonicalizeAmazonUrl(`https://${normalized.replace(/^\/+/, '')}`);
+  } else {
+    throw new ArgumentError(spec.invalidInputMessage, spec.invalidInputHint);
   }
-  if (/^https?:\/\//i.test(normalized)) {
-    return canonicalizeAmazonUrl(normalized);
+
+  if (!isSupportedRankingPath(listType, candidateUrl)) {
+    throw new ArgumentError(spec.invalidInputMessage, spec.invalidInputHint);
   }
-  if (normalized.includes('/zgbs/')) {
-    return canonicalizeAmazonUrl(`https://${normalized.replace(/^\/+/, '')}`);
+  return normalizeRankingInputUrl(candidateUrl);
+}
+
+function normalizeRankingInputUrl(inputUrl: string): string {
+  try {
+    const url = new URL(inputUrl);
+    const normalizedPathSegments = url.pathname
+      .split('/')
+      .filter(Boolean)
+      .filter((segment) => !/^ref=/i.test(segment));
+    url.pathname = `/${normalizedPathSegments.join('/')}`;
+    url.hash = '';
+    // Ranking pages are frequently shared with tracking refs that can land on unstable variants.
+    // Dropping ref keeps the canonical ranking path while preserving useful params (for example pg=2).
+    url.searchParams.delete('ref');
+    return url.toString();
+  } catch {
+    return inputUrl;
   }
-  throw new ArgumentError(
-    'amazon bestsellers expects a best sellers URL or /zgbs path',
-    'Example: opencli amazon bestsellers https://www.amazon.com/Best-Sellers/zgbs',
-  );
+}
+
+export function isRankingPaginationUrl(listType: AmazonRankingListType, inputUrl: string): boolean {
+  const absolute = toAbsoluteAmazonUrl(inputUrl);
+  if (!absolute || !isSupportedRankingPath(listType, absolute)) return false;
+
+  try {
+    const url = new URL(absolute);
+    const ref = cleanText(url.searchParams.get('ref')).toLowerCase();
+    // pg= query param is the most reliable pagination indicator across all ranking lists
+    return url.searchParams.has('pg')
+      || /(?:^|_)pg(?:_|$)/.test(ref)
+      // Amazon ranking pagination refs: zg_bs_pg_ (bestsellers), zg_bsnr_pg_ (new releases), zg_bsms_pg_ (movers & shakers)
+      || /zg_bs(?:nr|ms)?_pg_/.test(ref);
+  } catch {
+    return false;
+  }
+}
+
+export function extractCategoryNodeId(inputUrl: string | null | undefined): string | null {
+  const absolute = toAbsoluteAmazonUrl(inputUrl);
+  if (!absolute) return null;
+
+  try {
+    const url = new URL(absolute);
+
+    for (const key of ['node', 'nodeid', 'nodeId', 'browseNode']) {
+      const value = cleanText(url.searchParams.get(key));
+      if (/^\d{4,}$/.test(value)) return value;
+    }
+
+    const rhValue = cleanText(url.searchParams.get('rh'));
+    const rhMatch = decodeURIComponent(rhValue).match(/(?:^|,)\s*n:(\d{4,})(?:,|$)/i);
+    if (rhMatch) return rhMatch[1];
+
+    const pathMatches = [...url.pathname.matchAll(/\/(\d{4,})(?=\/|$)/g)];
+    if (pathMatches.length > 0) {
+      return pathMatches[pathMatches.length - 1][1];
+    }
+  } catch {
+    return null;
+  }
+
+  return null;
+}
+
+export function resolveBestsellersUrl(input?: string): string {
+  return resolveRankingUrl('bestsellers', input);
 }
 
 export function canonicalizeAmazonUrl(input: string): string {
@@ -305,6 +423,10 @@ export const __test__ = {
   buildProductUrl,
   buildDiscussionUrl,
   resolveBestsellersUrl,
+  resolveRankingUrl,
+  isSupportedRankingPath,
+  isRankingPaginationUrl,
+  extractCategoryNodeId,
   parsePriceText,
   parseRatingValue,
   parseReviewCount,

package/src/clis/bilibili/comments.test.ts

@@ -4,7 +4,8 @@ const { mockApiGet } = vi.hoisted(() => ({
   mockApiGet: vi.fn(),
 }));
 
-vi.mock('./utils.js', () => ({
+vi.mock('./utils.js', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('./utils.js')>()),
   apiGet: mockApiGet,
 }));
 
@@ -58,8 +59,8 @@ describe('bilibili comments', () => {
   it('throws when aid cannot be resolved', async () => {
     mockApiGet.mockResolvedValueOnce({ data: {} }); // no aid
 
-    await expect(command!.func!({} as any, { bvid: 'BV_invalid', limit: 5 })).rejects.toThrow(
-      'Cannot resolve aid for bvid: BV_invalid',
+    await expect(command!.func!({} as any, { bvid: 'BVinvalid123', limit: 5 })).rejects.toThrow(
+      'Cannot resolve aid for bvid: BVinvalid123',
     );
   });
 

package/src/clis/bilibili/comments.ts

@@ -4,7 +4,7 @@
  */
 
 import { cli, Strategy } from '../../registry.js';
-import { apiGet } from './utils.js';
+import { apiGet, resolveBvid } from './utils.js';
 
 cli({
   site: 'bilibili',
@@ -18,7 +18,7 @@ cli({
   ],
   columns: ['rank', 'author', 'text', 'likes', 'replies', 'time'],
   func: async (page, kwargs) => {
-    const bvid = String(kwargs.bvid).trim();
+    const bvid = await resolveBvid(kwargs.bvid);
     const limit = Math.min(Number(kwargs.limit) || 20, 50);
 
     // Resolve bvid → aid (required by reply API)

package/src/clis/bilibili/download.ts

@@ -11,6 +11,7 @@
 import { cli, Strategy } from '../../registry.js';
 import { checkYtdlp, sanitizeFilename } from '../../download/index.js';
 import { downloadMedia } from '../../download/media-download.js';
+import { resolveBvid } from './utils.js';
 
 cli({
   site: 'bilibili',
@@ -25,7 +26,7 @@ cli({
   ],
   columns: ['bvid', 'title', 'status', 'size'],
   func: async (page, kwargs) => {
-    const bvid = kwargs.bvid;
+    const bvid = await resolveBvid(kwargs.bvid);
     const output = kwargs.output;
     const quality = kwargs.quality;
 

package/src/clis/bilibili/subtitle.test.ts

@@ -6,7 +6,8 @@ const { mockApiGet } = vi.hoisted(() => ({
   mockApiGet: vi.fn(),
 }));
 
-vi.mock('./utils.js', () => ({
+vi.mock('./utils.js', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('./utils.js')>()),
   apiGet: mockApiGet,
 }));
 

package/src/clis/bilibili/subtitle.ts

@@ -1,7 +1,7 @@
 import { cli, Strategy } from '../../registry.js';
 import { AuthRequiredError, CommandExecutionError, EmptyResultError, SelectorError } from '../../errors.js';
 import type { IPage } from '../../types.js';
-import { apiGet } from './utils.js';
+import { apiGet, resolveBvid } from './utils.js';
 
 cli({
   site: 'bilibili',
@@ -15,8 +15,9 @@ cli({
   columns: ['index', 'from', 'to', 'content'],
   func: async (page: IPage | null, kwargs: any) => {
     if (!page) throw new CommandExecutionError('Browser session required for bilibili subtitle');
+    const bvid = await resolveBvid(kwargs.bvid);
     // 1. 先前往视频详情页 (建立有鉴权的 Session，且这里不需要加载完整个视频)
-    await page.goto(`https://www.bilibili.com/video/${kwargs.bvid}/`);
+    await page.goto(`https://www.bilibili.com/video/${bvid}/`);
 
     // 2. 利用 __INITIAL_STATE__ 获取基础信息，拿 CID
     const cid = await page.evaluate(`(async () => {
@@ -31,7 +32,7 @@ cli({
     // 3. 在 Node 端使用 apiGet 获取带 Wbi 签名的字幕列表
     // 之前纯靠 evaluate 里的 fetch 会失败，因为 B 站 /wbi/ 开头的接口强校验 w_rid，未签名直接被风控返回 403 HTML
     const payload = await apiGet(page, '/x/player/wbi/v2', {
-      params: { bvid: kwargs.bvid, cid },
+      params: { bvid, cid },
       signed: true, // 开启 wbi_sign 自动签名
     });
 

package/src/clis/bilibili/utils.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { resolveBvid } from './utils.js';
+
+describe('resolveBvid', () => {
+  it('passes through a valid BV ID', async () => {
+    expect(await resolveBvid('BV1MV9NBtENN')).toBe('BV1MV9NBtENN');
+  });
+
+  it('passes through BV ID with surrounding whitespace', async () => {
+    expect(await resolveBvid('  BV1MV9NBtENN  ')).toBe('BV1MV9NBtENN');
+  });
+
+  it('handles non-string input via String() coercion', async () => {
+    expect(await resolveBvid('BV123abc' as any)).toBe('BV123abc');
+  });
+
+  it('rejects invalid input that cannot be resolved', async () => {
+    // A random string that b23.tv won't resolve — should timeout or fail
+    await expect(resolveBvid('not-a-valid-code-99999')).rejects.toThrow();
+  });
+});

package/src/clis/bilibili/utils.ts

@@ -2,9 +2,36 @@
  * Bilibili shared helpers: WBI signing, authenticated fetch, nav data, UID resolution.
  */
 
+import https from 'node:https';
 import type { IPage } from '../../types.js';
 import { AuthRequiredError, EmptyResultError } from '../../errors.js';
 
+/**
+ * Resolve Bilibili short URL / short code to BV ID.
+ * Supports: BV1MV9NBtENN, XYzsqGa, b23.tv/XYzsqGa, https://b23.tv/XYzsqGa
+ */
+export function resolveBvid(input: unknown): Promise<string> {
+  const trimmed = String(input).trim();
+  if (/^BV[A-Za-z0-9]+$/i.test(trimmed)) {
+    return Promise.resolve(trimmed);
+  }
+  const shortCode = trimmed.replace(/^https?:\/\//, '').replace(/^(www\.)?b23\.tv\//, '');
+  const url = 'https://b23.tv/' + shortCode;
+  return new Promise((resolve, reject) => {
+    const req = https.get(url, (res) => {
+      const location = res.headers.location;
+      if (location) {
+        const match = location.match(/\/video\/(BV[A-Za-z0-9]+)/);
+        if (match) { res.resume(); resolve(match[1]); return; }
+      }
+      res.resume();
+      reject(new Error(`Cannot resolve BV ID from short URL: ${trimmed}`));
+    });
+    req.on('error', reject);
+    req.setTimeout(5000, () => { req.destroy(); reject(new Error(`Timeout resolving short URL: ${trimmed}`)); });
+  });
+}
+
 const MIXIN_KEY_ENC_TAB = [
   46,47,18,2,53,8,23,32,15,50,10,31,58,3,45,35,27,43,5,49,
   33,9,42,19,29,28,14,39,12,38,41,13,37,48,7,16,24,55,40,

package/src/clis/douban/marks.ts

@@ -50,7 +50,7 @@ async function fetchMarks(
 ): Promise<DoubanMark[]> {
   const marks: DoubanMark[] = [];
   let offset = 0;
-  const pageSize = 30;
+  const pageSize = 15;
   
   while (true) {
     const url = `https://movie.douban.com/people/${uid}/${status}?start=${offset}&sort=time&rating=all&filter=all&mode=grid`;