@jackwener/opencli 1.4.0 → 1.5.0

package/src/clis/weixin/download.ts

@@ -54,6 +54,113 @@ export function normalizeWechatUrl(raw: string): string {
   return s;
 }
 
+/**
+ * Format a WeChat article timestamp as a UTC+8 datetime string.
+ * Accepts either Unix seconds or milliseconds.
+ */
+export function formatWechatTimestamp(rawTimestamp: string): string {
+  const ts = Number.parseInt(rawTimestamp, 10);
+  if (!Number.isFinite(ts) || ts <= 0) return '';
+
+  const timestampMs = rawTimestamp.length === 13 ? ts : ts * 1000;
+  const d = new Date(timestampMs);
+  const pad = (n: number): string => String(n).padStart(2, '0');
+  const utc8 = new Date(d.getTime() + 8 * 3600 * 1000);
+
+  return (
+    `${utc8.getUTCFullYear()}-` +
+    `${pad(utc8.getUTCMonth() + 1)}-` +
+    `${pad(utc8.getUTCDate())} ` +
+    `${pad(utc8.getUTCHours())}:` +
+    `${pad(utc8.getUTCMinutes())}:` +
+    `${pad(utc8.getUTCSeconds())}`
+  );
+}
+
+/**
+ * Extract the raw create_time value from supported WeChat inline script formats.
+ */
+export function extractWechatCreateTimeValue(htmlStr: string): string {
+  const jsDecodeMatch = htmlStr.match(
+    /create_time\s*:\s*JsDecode\('([^']+)'\)(?=[\s,;}]|$)/,
+  );
+  if (jsDecodeMatch) return jsDecodeMatch[1];
+
+  const directValueMatch = htmlStr.match(
+    /create_time\s*[:=]\s*(?:"([^"]+)"|'([^']+)'|([0-9A-Za-z]+))(?=[\s,;}]|$)/,
+  );
+  if (!directValueMatch) return '';
+
+  return directValueMatch[1] || directValueMatch[2] || directValueMatch[3] || '';
+}
+
+/**
+ * Extract the publish time from DOM text first, then fall back to numeric create_time values.
+ */
+export function extractWechatPublishTime(
+  publishTimeText: string | null | undefined,
+  htmlStr: string,
+): string {
+  const normalizedPublishTime = (publishTimeText || '').trim();
+  if (normalizedPublishTime) return normalizedPublishTime;
+
+  const rawCreateTime = extractWechatCreateTimeValue(htmlStr);
+  if (!/^\d{10}$|^\d{13}$/.test(rawCreateTime)) return '';
+
+  return formatWechatTimestamp(rawCreateTime);
+}
+
+/**
+ * Build a self-contained helper for execution inside page.evaluate().
+ */
+export function buildExtractWechatPublishTimeJs(): string {
+  return `(${function extractWechatPublishTimeInPage(
+    publishTimeText: string | null | undefined,
+    htmlStr: string,
+  ) {
+    function formatWechatTimestamp(rawTimestamp: string) {
+      const ts = Number.parseInt(rawTimestamp, 10);
+      if (!Number.isFinite(ts) || ts <= 0) return '';
+
+      const timestampMs = rawTimestamp.length === 13 ? ts : ts * 1000;
+      const d = new Date(timestampMs);
+      const pad = (n: number) => String(n).padStart(2, '0');
+      const utc8 = new Date(d.getTime() + 8 * 3600 * 1000);
+
+      return (
+        `${utc8.getUTCFullYear()}-` +
+        `${pad(utc8.getUTCMonth() + 1)}-` +
+        `${pad(utc8.getUTCDate())} ` +
+        `${pad(utc8.getUTCHours())}:` +
+        `${pad(utc8.getUTCMinutes())}:` +
+        `${pad(utc8.getUTCSeconds())}`
+      );
+    }
+
+    function extractWechatCreateTimeValue(html: string) {
+      const jsDecodeMatch = html.match(
+        /create_time\s*:\s*JsDecode\('([^']+)'\)(?=[\s,;}]|$)/,
+      );
+      if (jsDecodeMatch) return jsDecodeMatch[1];
+
+      const directValueMatch = html.match(
+        /create_time\s*[:=]\s*(?:"([^"]+)"|'([^']+)'|([0-9A-Za-z]+))(?=[\s,;}]|$)/,
+      );
+      if (!directValueMatch) return '';
+
+      return directValueMatch[1] || directValueMatch[2] || directValueMatch[3] || '';
+    }
+
+    const normalizedPublishTime = (publishTimeText || '').trim();
+    if (normalizedPublishTime) return normalizedPublishTime;
+
+    const rawCreateTime = extractWechatCreateTimeValue(htmlStr);
+    if (!/^\d{10}$|^\d{13}$/.test(rawCreateTime)) return '';
+
+    return formatWechatTimestamp(rawCreateTime);
+  }.toString()})`;
+}
+
 // ============================================================
 // CLI Registration
 // ============================================================
@@ -102,26 +209,13 @@ cli({
         const authorEl = document.querySelector('#js_name');
         result.author = authorEl ? authorEl.textContent.trim() : '';
 
-        // Publish time: extract create_time from script tags
-        const htmlStr = document.documentElement.innerHTML;
-        let timeMatch = htmlStr.match(/create_time\\s*:\\s*JsDecode\\('([^']+)'\\)/);
-        if (!timeMatch) timeMatch = htmlStr.match(/create_time\\s*:\\s*'(\\d+)'/);
-        if (!timeMatch) timeMatch = htmlStr.match(/create_time\\s*[:=]\\s*["']?(\\d+)["']?/);
-        if (timeMatch) {
-          const ts = parseInt(timeMatch[1], 10);
-          if (ts > 0) {
-            const d = new Date(ts * 1000);
-            const pad = n => String(n).padStart(2, '0');
-            const utc8 = new Date(d.getTime() + 8 * 3600 * 1000);
-            result.publishTime =
-              utc8.getUTCFullYear() + '-' +
-              pad(utc8.getUTCMonth() + 1) + '-' +
-              pad(utc8.getUTCDate()) + ' ' +
-              pad(utc8.getUTCHours()) + ':' +
-              pad(utc8.getUTCMinutes()) + ':' +
-              pad(utc8.getUTCSeconds());
-          }
-        }
+        // Publish time: prefer the rendered DOM text, then fall back to numeric create_time values.
+        const publishTimeEl = document.querySelector('#publish_time');
+        const extractWechatPublishTime = ${buildExtractWechatPublishTimeJs()};
+        result.publishTime = extractWechatPublishTime(
+          publishTimeEl ? publishTimeEl.textContent : '',
+          document.documentElement.innerHTML,
+        );
 
         // Content processing
         const contentEl = document.querySelector('#js_content');

package/src/clis/weread/book.ts

@@ -1,6 +1,6 @@
 import { cli, Strategy } from '../../registry.js';
 import type { IPage } from '../../types.js';
-import { fetchWithPage } from './utils.js';
+import { fetchPrivateApi } from './utils.js';
 
 cli({
   site: 'weread',
@@ -13,7 +13,7 @@ cli({
   ],
   columns: ['title', 'author', 'publisher', 'intro', 'category', 'rating'],
   func: async (page: IPage, args) => {
-    const data = await fetchWithPage(page, '/book/info', { bookId: args.bookId });
+    const data = await fetchPrivateApi(page, '/book/info', { bookId: args['book-id'] });
     // newRating is 0-1000 scale per community docs; needs runtime verification
     const rating = data.newRating ? `${(data.newRating / 10).toFixed(1)}%` : '-';
     return [{

package/src/clis/weread/commands.test.ts

@@ -0,0 +1,57 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const { mockFetchPrivateApi } = vi.hoisted(() => ({
+  mockFetchPrivateApi: vi.fn(),
+}));
+
+vi.mock('./utils.js', async () => {
+  const actual = await vi.importActual<typeof import('./utils.js')>('./utils.js');
+  return {
+    ...actual,
+    fetchPrivateApi: mockFetchPrivateApi,
+  };
+});
+
+import { getRegistry } from '../../registry.js';
+import './book.js';
+import './highlights.js';
+import './notes.js';
+
+describe('weread book-id positional args', () => {
+  const book = getRegistry().get('weread/book');
+  const highlights = getRegistry().get('weread/highlights');
+  const notes = getRegistry().get('weread/notes');
+
+  beforeEach(() => {
+    mockFetchPrivateApi.mockReset();
+  });
+
+  it('passes the positional book-id to book details', async () => {
+    mockFetchPrivateApi.mockResolvedValue({ title: 'Three Body', newRating: 880 });
+
+    await book!.func!({} as any, { 'book-id': '12345' });
+
+    expect(mockFetchPrivateApi).toHaveBeenCalledWith({}, '/book/info', { bookId: '12345' });
+  });
+
+  it('passes the positional book-id to highlights', async () => {
+    mockFetchPrivateApi.mockResolvedValue({ updated: [] });
+
+    await highlights!.func!({} as any, { 'book-id': 'abc', limit: 5 });
+
+    expect(mockFetchPrivateApi).toHaveBeenCalledWith({}, '/book/bookmarklist', { bookId: 'abc' });
+  });
+
+  it('passes the positional book-id to notes', async () => {
+    mockFetchPrivateApi.mockResolvedValue({ reviews: [] });
+
+    await notes!.func!({} as any, { 'book-id': 'xyz', limit: 5 });
+
+    expect(mockFetchPrivateApi).toHaveBeenCalledWith({}, '/review/list', {
+      bookId: 'xyz',
+      listType: '11',
+      mine: '1',
+      synckey: '0',
+    });
+  });
+});

package/src/clis/weread/highlights.ts

@@ -1,6 +1,6 @@
 import { cli, Strategy } from '../../registry.js';
 import type { IPage } from '../../types.js';
-import { fetchWithPage, formatDate } from './utils.js';
+import { fetchPrivateApi, formatDate } from './utils.js';
 
 cli({
   site: 'weread',
@@ -14,7 +14,7 @@ cli({
   ],
   columns: ['chapter', 'text', 'createTime'],
   func: async (page: IPage, args) => {
-    const data = await fetchWithPage(page, '/book/bookmarklist', { bookId: args.bookId });
+    const data = await fetchPrivateApi(page, '/book/bookmarklist', { bookId: args['book-id'] });
     const items: any[] = data?.updated ?? [];
     return items.slice(0, Number(args.limit)).map((item: any) => ({
       chapter: item.chapterName ?? '',

package/src/clis/weread/notebooks.ts

@@ -1,6 +1,6 @@
 import { cli, Strategy } from '../../registry.js';
 import type { IPage } from '../../types.js';
-import { fetchWithPage } from './utils.js';
+import { fetchPrivateApi } from './utils.js';
 
 cli({
   site: 'weread',
@@ -10,7 +10,7 @@ cli({
   strategy: Strategy.COOKIE,
   columns: ['title', 'author', 'noteCount', 'bookId'],
   func: async (page: IPage, _args) => {
-    const data = await fetchWithPage(page, '/user/notebooks');
+    const data = await fetchPrivateApi(page, '/user/notebooks');
     const books: any[] = data?.books ?? [];
     return books.map((item: any) => ({
       title: item.book?.title ?? '',

package/src/clis/weread/notes.ts

@@ -1,6 +1,6 @@
 import { cli, Strategy } from '../../registry.js';
 import type { IPage } from '../../types.js';
-import { fetchWithPage, formatDate } from './utils.js';
+import { fetchPrivateApi, formatDate } from './utils.js';
 
 cli({
   site: 'weread',
@@ -14,8 +14,8 @@ cli({
   ],
   columns: ['chapter', 'text', 'review', 'createTime'],
   func: async (page: IPage, args) => {
-    const data = await fetchWithPage(page, '/review/list', {
-      bookId: args.bookId,
+    const data = await fetchPrivateApi(page, '/review/list', {
+      bookId: args['book-id'],
       listType: '11',
       mine: '1',
       synckey: '0',

package/src/clis/weread/search.ts

@@ -12,15 +12,16 @@ cli({
     { name: 'query', positional: true, required: true, help: 'Search keyword' },
     { name: 'limit', type: 'int', default: 10, help: 'Max results' },
   ],
-  columns: ['rank', 'title', 'author', 'bookId'],
+  columns: ['rank', 'title', 'author', 'bookId', 'url'],
   func: async (_page, args) => {
-    const data = await fetchWebApi('/search/global', { keyword: args.keyword });
+    const data = await fetchWebApi('/search/global', { keyword: args.query });
     const books: any[] = data?.books ?? [];
     return books.slice(0, Number(args.limit)).map((item: any, i: number) => ({
       rank: i + 1,
       title: item.bookInfo?.title ?? '',
       author: item.bookInfo?.author ?? '',
       bookId: item.bookInfo?.bookId ?? '',
+      url: item.bookInfo?.bookId ? 'https://weread.qq.com/web/bookDetail/' + item.bookInfo.bookId : '',
     }));
   },
 });

package/src/clis/weread/shelf.ts

@@ -1,6 +1,6 @@
 import { cli, Strategy } from '../../registry.js';
 import type { IPage } from '../../types.js';
-import { fetchWithPage } from './utils.js';
+import { fetchPrivateApi } from './utils.js';
 
 cli({
   site: 'weread',
@@ -13,7 +13,7 @@ cli({
   ],
   columns: ['title', 'author', 'progress', 'bookId'],
   func: async (page: IPage, args) => {
-    const data = await fetchWithPage(page, '/shelf/sync', { synckey: '0', lectureSynckey: '0' });
+    const data = await fetchPrivateApi(page, '/shelf/sync', { synckey: '0', lectureSynckey: '0' });
     const books: any[] = data?.books ?? [];
     return books.slice(0, Number(args.limit)).map((item: any) => ({
       title: item.bookInfo?.title ?? item.title ?? '',

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

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { formatDate, fetchWebApi, fetchWithPage } from './utils.js';
+import { formatDate, fetchWebApi } from './utils.js';
 
 describe('formatDate', () => {
   it('formats a typical Unix timestamp in UTC+8', () => {
@@ -71,34 +71,3 @@ describe('fetchWebApi', () => {
     await expect(fetchWebApi('/search/global')).rejects.toThrow('Invalid JSON');
   });
 });
-
-describe('fetchWithPage', () => {
-  it('throws AUTH_REQUIRED on errcode -2010', async () => {
-    const mockPage = {
-      evaluate: vi.fn().mockResolvedValue({ errcode: -2010, errmsg: '用户不存在' }),
-    } as any;
-    await expect(fetchWithPage(mockPage, '/book/info')).rejects.toThrow('Not logged in');
-  });
-
-  it('throws API_ERROR on unknown errcode', async () => {
-    const mockPage = {
-      evaluate: vi.fn().mockResolvedValue({ errcode: -1, errmsg: 'unknown error' }),
-    } as any;
-    await expect(fetchWithPage(mockPage, '/book/info')).rejects.toThrow('unknown error');
-  });
-
-  it('returns data on success (errcode 0 or absent)', async () => {
-    const mockPage = {
-      evaluate: vi.fn().mockResolvedValue({ title: 'Test Book', errcode: 0 }),
-    } as any;
-    const result = await fetchWithPage(mockPage, '/book/info');
-    expect(result.title).toBe('Test Book');
-  });
-
-  it('throws FETCH_ERROR on HTTP error', async () => {
-    const mockPage = {
-      evaluate: vi.fn().mockResolvedValue({ _httpError: '403' }),
-    } as any;
-    await expect(fetchWithPage(mockPage, '/book/info')).rejects.toThrow('HTTP 403');
-  });
-});

package/src/clis/weread/utils.ts

@@ -3,16 +3,20 @@
  *
  * Two API domains:
  * - WEB_API (weread.qq.com/web/*): public, Node.js fetch
- * - API (i.weread.qq.com/*): private, browser page.evaluate with cookies
+ * - API (i.weread.qq.com/*): private, Node.js fetch with cookies from browser
  */
 
 import { CliError } from '../../errors.js';
-import type { IPage } from '../../types.js';
+import type { BrowserCookie, IPage } from '../../types.js';
 
 const WEB_API = 'https://weread.qq.com/web';
 const API = 'https://i.weread.qq.com';
 const UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36';
 
+function buildCookieHeader(cookies: BrowserCookie[]): string {
+  return cookies.map((cookie) => `${cookie.name}=${cookie.value}`).join('; ');
+}
+
 /**
  * Fetch a public WeRead web endpoint (Node.js direct fetch).
  * Used by search and ranking commands (browser: false).
@@ -36,29 +40,50 @@ export async function fetchWebApi(path: string, params?: Record<string, string>)
 }
 
 /**
- * Fetch a private WeRead API endpoint via browser page.evaluate.
- * Automatically carries cookies for authenticated requests.
+ * Fetch a private WeRead API endpoint with cookies extracted from the browser.
+ * The HTTP request itself runs in Node.js to avoid page-context CORS failures.
  */
-export async function fetchWithPage(page: IPage, path: string, params?: Record<string, string>): Promise<any> {
+export async function fetchPrivateApi(page: IPage, path: string, params?: Record<string, string>): Promise<any> {
   const url = new URL(`${API}${path}`);
   if (params) {
     for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
   }
   const urlStr = url.toString();
-  const data = await page.evaluate(`
-    async () => {
-      const res = await fetch(${JSON.stringify(urlStr)}, { credentials: "include" });
-      if (!res.ok) return { _httpError: String(res.status) };
-      try { return await res.json(); }
-      catch { return { _httpError: 'JSON parse error (status ' + res.status + ')' }; }
-    }
-  `);
-  if (data?._httpError) {
-    throw new CliError('FETCH_ERROR', `HTTP ${data._httpError} for ${path}`, 'WeRead API may be temporarily unavailable');
+
+  const cookies = await page.getCookies({ url: urlStr });
+  const cookieHeader = buildCookieHeader(cookies);
+
+  let resp: Response;
+  try {
+    resp = await fetch(urlStr, {
+      headers: {
+        'User-Agent': UA,
+        'Origin': 'https://weread.qq.com',
+        'Referer': 'https://weread.qq.com/',
+        ...(cookieHeader ? { 'Cookie': cookieHeader } : {}),
+      },
+    });
+  } catch (error) {
+    throw new CliError(
+      'FETCH_ERROR',
+      `Failed to fetch ${path}: ${error instanceof Error ? error.message : String(error)}`,
+      'WeRead API may be temporarily unavailable',
+    );
+  }
+
+  let data: any;
+  try {
+    data = await resp.json();
+  } catch {
+    throw new CliError('PARSE_ERROR', `Invalid JSON response for ${path}`, 'WeRead may have returned an HTML error page');
   }
-  if (data?.errcode === -2010) {
+
+  if (resp.status === 401 || data?.errcode === -2010) {
     throw new CliError('AUTH_REQUIRED', 'Not logged in to WeRead', 'Please log in to weread.qq.com in Chrome first');
   }
+  if (!resp.ok) {
+    throw new CliError('FETCH_ERROR', `HTTP ${resp.status} for ${path}`, 'WeRead API may be temporarily unavailable');
+  }
   if (data?.errcode != null && data.errcode !== 0) {
     throw new CliError('API_ERROR', data.errmsg ?? `WeRead API error ${data.errcode}`);
   }

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

@@ -0,0 +1,96 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { IPage } from '../../types.js';
+import { getRegistry } from '../../registry.js';
+import './comments.js';
+
+function createPageMock(evaluateResult: any): IPage {
+  return {
+    goto: vi.fn().mockResolvedValue(undefined),
+    evaluate: vi.fn().mockResolvedValue(evaluateResult),
+    snapshot: vi.fn().mockResolvedValue(undefined),
+    click: vi.fn().mockResolvedValue(undefined),
+    typeText: vi.fn().mockResolvedValue(undefined),
+    pressKey: vi.fn().mockResolvedValue(undefined),
+    scrollTo: vi.fn().mockResolvedValue(undefined),
+    getFormState: vi.fn().mockResolvedValue({ forms: [], orphanFields: [] }),
+    wait: vi.fn().mockResolvedValue(undefined),
+    tabs: vi.fn().mockResolvedValue([]),
+    closeTab: vi.fn().mockResolvedValue(undefined),
+    newTab: vi.fn().mockResolvedValue(undefined),
+    selectTab: vi.fn().mockResolvedValue(undefined),
+    networkRequests: vi.fn().mockResolvedValue([]),
+    consoleMessages: vi.fn().mockResolvedValue([]),
+    scroll: vi.fn().mockResolvedValue(undefined),
+    autoScroll: vi.fn().mockResolvedValue(undefined),
+    installInterceptor: vi.fn().mockResolvedValue(undefined),
+    getInterceptedRequests: vi.fn().mockResolvedValue([]),
+    getCookies: vi.fn().mockResolvedValue([]),
+    screenshot: vi.fn().mockResolvedValue(''),
+  };
+}
+
+describe('xiaohongshu comments', () => {
+  const command = getRegistry().get('xiaohongshu/comments');
+
+  it('returns ranked comment rows', async () => {
+    const page = createPageMock({
+      loginWall: false,
+      results: [
+        { author: 'Alice', text: 'Great note!', likes: 10, time: '2024-01-01' },
+        { author: 'Bob', text: 'Very helpful', likes: 0, time: '2024-01-02' },
+      ],
+    });
+
+    const result = (await command!.func!(page, { 'note-id': '69aadbcb000000002202f131', limit: 5 })) as any[];
+
+    expect((page.goto as any).mock.calls[0][0]).toContain('/explore/69aadbcb000000002202f131');
+    expect(result).toEqual([
+      { rank: 1, author: 'Alice', text: 'Great note!', likes: 10, time: '2024-01-01' },
+      { rank: 2, author: 'Bob', text: 'Very helpful', likes: 0, time: '2024-01-02' },
+    ]);
+    expect(result[0]).not.toHaveProperty('loginWall');
+  });
+
+  it('strips /explore/ prefix from full URL input', async () => {
+    const page = createPageMock({
+      loginWall: false,
+      results: [{ author: 'Alice', text: 'Nice', likes: 1, time: '2024-01-01' }],
+    });
+
+    await command!.func!(page, {
+      'note-id': 'https://www.xiaohongshu.com/explore/69aadbcb000000002202f131',
+      limit: 5,
+    });
+
+    expect((page.goto as any).mock.calls[0][0]).toContain('/explore/69aadbcb000000002202f131');
+  });
+
+  it('throws AuthRequiredError when login wall is detected', async () => {
+    const page = createPageMock({ loginWall: true, results: [] });
+
+    await expect(command!.func!(page, { 'note-id': 'abc123', limit: 5 })).rejects.toThrow(
+      'Note comments require login',
+    );
+  });
+
+  it('returns empty array when no comments are found', async () => {
+    const page = createPageMock({ loginWall: false, results: [] });
+
+    await expect(command!.func!(page, { 'note-id': 'abc123', limit: 5 })).resolves.toEqual([]);
+  });
+
+  it('respects the limit', async () => {
+    const manyComments = Array.from({ length: 10 }, (_, i) => ({
+      author: `User${i}`,
+      text: `Comment ${i}`,
+      likes: i,
+      time: '2024-01-01',
+    }));
+    const page = createPageMock({ loginWall: false, results: manyComments });
+
+    const result = (await command!.func!(page, { 'note-id': 'abc123', limit: 3 })) as any[];
+    expect(result).toHaveLength(3);
+    expect(result[0].rank).toBe(1);
+    expect(result[2].rank).toBe(3);
+  });
+});

package/src/clis/xiaohongshu/comments.ts

@@ -0,0 +1,81 @@
+/**
+ * Xiaohongshu comments — DOM extraction from note detail page.
+ * XHS API requires signed requests, so we scrape the rendered DOM instead.
+ */
+
+import { cli, Strategy } from '../../registry.js';
+import { AuthRequiredError, EmptyResultError } from '../../errors.js';
+
+cli({
+  site: 'xiaohongshu',
+  name: 'comments',
+  description: '获取小红书笔记评论（仅主评论，不含楼中楼）',
+  domain: 'www.xiaohongshu.com',
+  strategy: Strategy.COOKIE,
+  args: [
+    { name: 'note-id', required: true, positional: true, help: 'Note ID or full /explore/<id> URL' },
+    { name: 'limit', type: 'int', default: 20, help: 'Number of comments (max 50)' },
+  ],
+  columns: ['rank', 'author', 'text', 'likes', 'time'],
+  func: async (page, kwargs) => {
+    const limit = Math.min(Number(kwargs.limit) || 20, 50);
+    let noteId = String(kwargs['note-id']).trim();
+
+    // Accept full URLs: /explore/<id> or /note/<id>
+    const urlMatch = noteId.match(/\/explore\/([a-f0-9]+)/) || noteId.match(/\/note\/([a-f0-9]+)/);
+    if (urlMatch) noteId = urlMatch[1];
+
+    await page.goto(`https://www.xiaohongshu.com/explore/${noteId}`);
+    await page.wait(3);
+
+    const data = await page.evaluate(`
+      (async () => {
+        const wait = (ms) => new Promise(r => setTimeout(r, ms))
+
+        // Check login state
+        const loginWall = /登录后查看|请登录/.test(document.body.innerText || '')
+
+        // Scroll the note container to trigger comment loading
+        const scroller = document.querySelector('.note-scroller') || document.querySelector('.container')
+        if (scroller) {
+          for (let i = 0; i < 3; i++) {
+            scroller.scrollTo(0, scroller.scrollHeight)
+            await wait(1000)
+          }
+        }
+
+        const clean = (el) => (el?.textContent || '').replace(/\\s+/g, ' ').trim()
+
+        const results = []
+        const parents = document.querySelectorAll('.parent-comment')
+        for (const p of parents) {
+          const item = p.querySelector('.comment-item')
+          if (!item) continue
+
+          const author = clean(item.querySelector('.author-wrapper .name, .user-name'))
+          const text = clean(item.querySelector('.content, .note-text'))
+          // XHS shows text "赞" when likes = 0; only shows a number when > 0
+          const likesRaw = clean(item.querySelector('.count'))
+          const likes = /^\\d+$/.test(likesRaw) ? Number(likesRaw) : 0
+          const time = clean(item.querySelector('.date, .time'))
+
+          if (!text) continue
+          results.push({ author, text, likes, time })
+        }
+
+        return { loginWall, results }
+      })()
+    `);
+
+    if (!data || typeof data !== 'object') {
+      throw new EmptyResultError('xiaohongshu/comments', 'Unexpected evaluate response');
+    }
+
+    if ((data as any).loginWall) {
+      throw new AuthRequiredError('www.xiaohongshu.com', 'Note comments require login');
+    }
+
+    const results: any[] = (data as any).results ?? [];
+    return results.slice(0, limit).map((c: any, i: number) => ({ rank: i + 1, ...c }));
+  },
+});