@jackwener/opencli 1.6.0 → 1.6.2

package/src/clis/twitter/search.test.ts

@@ -153,15 +153,98 @@ describe('twitter search command', () => {
     expect(pushStateCall).toContain('f=top');
   });
 
+  it('falls back to search input when pushState fails twice', async () => {
+    const command = getRegistry().get('twitter/search');
+    expect(command?.func).toBeTypeOf('function');
+
+    const evaluate = vi.fn()
+      .mockResolvedValueOnce(undefined)     // pushState attempt 1
+      .mockResolvedValueOnce('/explore')    // pathname check 1 — not /search
+      .mockResolvedValueOnce(undefined)     // pushState attempt 2
+      .mockResolvedValueOnce('/explore')    // pathname check 2 — still not /search
+      .mockResolvedValueOnce({ ok: true })  // search input fallback succeeds
+      .mockResolvedValueOnce('/search');    // pathname check after fallback
+
+    const page = {
+      goto: vi.fn().mockResolvedValue(undefined),
+      wait: vi.fn().mockResolvedValue(undefined),
+      installInterceptor: vi.fn().mockResolvedValue(undefined),
+      evaluate,
+      autoScroll: vi.fn().mockResolvedValue(undefined),
+      getInterceptedRequests: vi.fn().mockResolvedValue([
+        {
+          data: {
+            search_by_raw_query: {
+              search_timeline: {
+                timeline: {
+                  instructions: [
+                    {
+                      type: 'TimelineAddEntries',
+                      entries: [
+                        {
+                          entryId: 'tweet-99',
+                          content: {
+                            itemContent: {
+                              tweet_results: {
+                                result: {
+                                  rest_id: '99',
+                                  legacy: {
+                                    full_text: 'fallback works',
+                                    favorite_count: 3,
+                                    created_at: 'Wed Apr 02 12:00:00 +0000 2026',
+                                  },
+                                  core: {
+                                    user_results: {
+                                      result: {
+                                        core: { screen_name: 'bob' },
+                                      },
+                                    },
+                                  },
+                                  views: { count: '5' },
+                                },
+                              },
+                            },
+                          },
+                        },
+                      ],
+                    },
+                  ],
+                },
+              },
+            },
+          },
+        },
+      ]),
+    };
+
+    const result = await command!.func!(page as any, { query: 'test fallback', filter: 'top', limit: 5 });
+
+    expect(result).toEqual([
+      {
+        id: '99',
+        author: 'bob',
+        text: 'fallback works',
+        created_at: 'Wed Apr 02 12:00:00 +0000 2026',
+        likes: 3,
+        views: '5',
+        url: 'https://x.com/i/status/99',
+      },
+    ]);
+    // 6 evaluate calls: 2x pushState + 2x pathname check + 1x fallback + 1x pathname check
+    expect(evaluate).toHaveBeenCalledTimes(6);
+    expect(page.autoScroll).toHaveBeenCalled();
+  });
+
   it('throws with the final path after both attempts fail', async () => {
     const command = getRegistry().get('twitter/search');
     expect(command?.func).toBeTypeOf('function');
 
     const evaluate = vi.fn()
-      .mockResolvedValueOnce(undefined)
-      .mockResolvedValueOnce('/explore')
-      .mockResolvedValueOnce(undefined)
-      .mockResolvedValueOnce('/login');
+      .mockResolvedValueOnce(undefined)   // pushState attempt 1
+      .mockResolvedValueOnce('/explore')  // pathname check 1
+      .mockResolvedValueOnce(undefined)   // pushState attempt 2
+      .mockResolvedValueOnce('/login')    // pathname check 2
+      .mockResolvedValueOnce({ ok: false }); // search input fallback
 
     const page = {
       goto: vi.fn().mockResolvedValue(undefined),
@@ -177,6 +260,6 @@ describe('twitter search command', () => {
       .toThrow('Final path: /login');
     expect(page.autoScroll).not.toHaveBeenCalled();
     expect(page.getInterceptedRequests).not.toHaveBeenCalled();
-    expect(evaluate).toHaveBeenCalledTimes(4);
+    expect(evaluate).toHaveBeenCalledTimes(5);
   });
 });

package/src/clis/twitter/search.ts

@@ -3,16 +3,19 @@ import { cli, Strategy } from '../../registry.js';
 import type { IPage } from '../../types.js';
 
 /**
- * Trigger Twitter search SPA navigation and retry once on transient failures.
+ * Trigger Twitter search SPA navigation with fallback strategies.
  *
- * Twitter/X sometimes keeps the page on /explore for a short period even after
- * pushState + popstate. A second attempt is enough for the intermittent cases
- * reported in issue #353 while keeping the flow narrowly scoped.
+ * Primary: pushState + popstate (works in most environments).
+ * Fallback: Type into the search input and press Enter when pushState fails
+ *   intermittently (e.g. due to Twitter A/B tests or timing races — see #690).
+ *
+ * Both strategies preserve the JS context so the fetch interceptor stays alive.
  */
 async function navigateToSearch(page: Pick<IPage, 'evaluate' | 'wait'>, query: string, filter: string): Promise<void> {
   const searchUrl = JSON.stringify(`/search?q=${encodeURIComponent(query)}&f=${filter}`);
   let lastPath = '';
 
+  // Strategy 1 (primary): pushState + popstate with retry
   for (let attempt = 1; attempt <= 2; attempt++) {
     await page.evaluate(`
       (() => {
@@ -20,7 +23,12 @@ async function navigateToSearch(page: Pick<IPage, 'evaluate' | 'wait'>, query: s
         window.dispatchEvent(new PopStateEvent('popstate', { state: {} }));
       })()
     `);
-    await page.wait({ selector: '[data-testid="primaryColumn"]' });
+
+    try {
+      await page.wait({ selector: '[data-testid="primaryColumn"]' });
+    } catch {
+      // selector timeout — fall through to path check or next attempt
+    }
 
     lastPath = String(await page.evaluate('() => window.location.pathname') || '');
     if (lastPath.startsWith('/search')) {
@@ -32,6 +40,61 @@ async function navigateToSearch(page: Pick<IPage, 'evaluate' | 'wait'>, query: s
     }
   }
 
+  // Strategy 2 (fallback): Use the search input on /explore.
+  // The nativeSetter + Enter approach triggers Twitter's own form handler,
+  // performing SPA navigation without a full page reload.
+  const queryStr = JSON.stringify(query);
+  const navResult = await page.evaluate(`(async () => {
+    try {
+      const input = document.querySelector('[data-testid="SearchBox_Search_Input"]');
+      if (!input) return { ok: false };
+
+      input.focus();
+      await new Promise(r => setTimeout(r, 300));
+
+      const nativeSetter = Object.getOwnPropertyDescriptor(
+        window.HTMLInputElement.prototype, 'value'
+      )?.set;
+      if (!nativeSetter) return { ok: false };
+      nativeSetter.call(input, ${queryStr});
+      input.dispatchEvent(new Event('input', { bubbles: true }));
+      input.dispatchEvent(new Event('change', { bubbles: true }));
+      await new Promise(r => setTimeout(r, 500));
+
+      input.dispatchEvent(new KeyboardEvent('keydown', {
+        key: 'Enter', code: 'Enter', keyCode: 13, bubbles: true
+      }));
+
+      return { ok: true };
+    } catch {
+      return { ok: false };
+    }
+  })()`);
+
+  if (navResult?.ok) {
+    try {
+      await page.wait({ selector: '[data-testid="primaryColumn"]' });
+    } catch {
+      // fall through to path check
+    }
+    lastPath = String(await page.evaluate('() => window.location.pathname') || '');
+    if (lastPath.startsWith('/search')) {
+      if (filter === 'live') {
+        await page.evaluate(`(() => {
+          const tabs = document.querySelectorAll('[role="tab"]');
+          for (const tab of tabs) {
+            if (tab.textContent.includes('Latest') || tab.textContent.includes('最新')) {
+              tab.click();
+              return;
+            }
+          }
+        })()`);
+        await page.wait(2);
+      }
+      return;
+    }
+  }
+
   throw new CommandExecutionError(
     `SPA navigation to /search failed. Final path: ${lastPath || '(empty)'}. Twitter may have changed its routing.`,
   );

package/src/clis/xianyu/chat.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+import { __test__ } from './chat.js';
+
+describe('xianyu chat helpers', () => {
+  it('builds goofish im urls from ids', () => {
+    expect(__test__.buildChatUrl('1038951278192', '3650092411')).toBe(
+      'https://www.goofish.com/im?itemId=1038951278192&peerUserId=3650092411',
+    );
+  });
+
+  it('normalizes numeric ids', () => {
+    expect(__test__.normalizeNumericId('1038951278192', 'item_id', '1038951278192')).toBe('1038951278192');
+    expect(__test__.normalizeNumericId(3650092411, 'user_id', '3650092411')).toBe('3650092411');
+  });
+
+  it('rejects non-numeric ids', () => {
+    expect(() => __test__.normalizeNumericId('abc', 'item_id', '1038951278192')).toThrow();
+    expect(() => __test__.normalizeNumericId('3650092411x', 'user_id', '3650092411')).toThrow();
+  });
+});

package/src/clis/xianyu/chat.ts

@@ -0,0 +1,175 @@
+import { AuthRequiredError, SelectorError } from '../../errors.js';
+import { cli, Strategy } from '../../registry.js';
+import { normalizeNumericId } from './utils.js';
+
+function buildChatUrl(itemId: string, peerUserId: string): string {
+  return `https://www.goofish.com/im?itemId=${encodeURIComponent(itemId)}&peerUserId=${encodeURIComponent(peerUserId)}`;
+}
+
+function buildExtractChatStateEvaluate(): string {
+  return `
+    (() => {
+      const clean = (value) => (value || '').replace(/\\s+/g, ' ').trim();
+      const bodyText = document.body?.innerText || '';
+      const requiresAuth = /请先登录|登录后/.test(bodyText);
+
+      const textarea = document.querySelector('textarea');
+      const sendButton = Array.from(document.querySelectorAll('button'))
+        .find((btn) => clean(btn.textContent || '') === '发送');
+      const topbar = document.querySelector('[class*="message-topbar"]');
+      const itemCard = Array.from(document.querySelectorAll('a[href*="/item?id="]'))
+        .find((el) => el.closest('main'));
+      const itemTitleNode =
+        document.querySelector('[class*="container"] [class*="title"]')
+        || document.querySelector('[class*="item-main-info"] [class*="desc"]')
+        || document.querySelector('[class*="headSkuInfo"]')
+        || itemCard?.querySelector('[class*="title"]')
+        || itemCard?.previousElementSibling?.querySelector?.('[class*="title"]');
+
+      const messageRoot = document.querySelector('#message-list-scrollable');
+      const visibleMessages = Array.from(
+        (messageRoot || document).querySelectorAll('[class*="message"], [class*="msg"], [class*="bubble"]')
+      ).map((el) => clean(el.textContent || ''))
+        .filter(Boolean)
+        .filter((text) => !['发送', '闲鱼号', '立即购买'].includes(text))
+        .filter((text) => !/^消息\\d*\\+?$/.test(text))
+        .slice(-20);
+
+      return {
+        requiresAuth,
+        title: clean(document.title || ''),
+        peer_name: clean(topbar?.querySelector('[class*="text1"]')?.textContent || ''),
+        peer_masked_id: clean(topbar?.querySelector('[class*="text2"]')?.textContent || '').replace(/^\\(|\\)$/g, ''),
+        item_title: clean(itemTitleNode?.textContent || ''),
+        item_url: itemCard?.href || '',
+        price: clean(itemCard?.querySelector('[class*="money"]')?.textContent || ''),
+        location: clean(itemCard?.querySelector('[class*="delivery"] + [class*="delivery"], [class*="delivery"]:last-child')?.textContent || ''),
+        can_input: Boolean(textarea && !textarea.disabled),
+        can_send: Boolean(sendButton),
+        visible_messages: visibleMessages,
+      };
+    })()
+  `;
+}
+
+function buildSendMessageEvaluate(text: string): string {
+  return `
+    (() => {
+      const clean = (value) => (value || '').replace(/\\s+/g, ' ').trim();
+      const textarea = document.querySelector('textarea');
+      if (!textarea || textarea.disabled) {
+        return { ok: false, reason: 'input-not-found' };
+      }
+
+      const setter = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value')?.set;
+      if (!setter) {
+        return { ok: false, reason: 'textarea-setter-not-found' };
+      }
+
+      textarea.focus();
+      setter.call(textarea, ${JSON.stringify(text)});
+      textarea.dispatchEvent(new Event('input', { bubbles: true }));
+      textarea.dispatchEvent(new Event('change', { bubbles: true }));
+
+      const sendButton = Array.from(document.querySelectorAll('button'))
+        .find((btn) => clean(btn.textContent || '') === '发送');
+      if (!sendButton) {
+        return { ok: false, reason: 'send-button-not-found' };
+      }
+
+      sendButton.click();
+      return { ok: true };
+    })()
+  `;
+}
+
+cli({
+  site: 'xianyu',
+  name: 'chat',
+  description: '打开闲鱼聊一聊会话，并可选发送消息',
+  domain: 'www.goofish.com',
+  strategy: Strategy.COOKIE,
+  navigateBefore: false,
+  browser: true,
+  args: [
+    { name: 'item_id', required: true, positional: true, help: '闲鱼商品 item_id' },
+    { name: 'user_id', required: true, positional: true, help: '聊一聊对方的 user_id / peerUserId' },
+    { name: 'text', help: 'Message to send after opening the chat' },
+  ],
+  columns: ['status', 'peer_name', 'item_title', 'price', 'location', 'message'],
+  func: async (page, kwargs) => {
+    const itemId = normalizeNumericId(kwargs.item_id, 'item_id', '1038951278192');
+    const userId = normalizeNumericId(kwargs.user_id, 'user_id', '3650092411');
+    const url = buildChatUrl(itemId, userId);
+    const text = String(kwargs.text || '').trim();
+
+    await page.goto(url);
+    await page.wait(2);
+
+    const state = await page.evaluate(buildExtractChatStateEvaluate()) as {
+      requiresAuth?: boolean;
+      title?: string;
+      peer_name?: string;
+      peer_masked_id?: string;
+      item_title?: string;
+      item_url?: string;
+      price?: string;
+      location?: string;
+      can_input?: boolean;
+      can_send?: boolean;
+      visible_messages?: string[];
+    };
+
+    if (state?.requiresAuth) {
+      throw new AuthRequiredError('www.goofish.com', 'Xianyu chat requires a logged-in browser session');
+    }
+
+    if (!state?.can_input) {
+      throw new SelectorError('闲鱼聊天输入框', '未找到可用的聊天输入框，请确认该会话页已正确加载');
+    }
+
+    if (!text) {
+      return [{
+        status: 'ready',
+        peer_name: state.peer_name || '',
+        item_title: state.item_title || '',
+        price: state.price || '',
+        location: state.location || '',
+        message: (state.visible_messages || []).slice(-1)[0] || '',
+        peer_user_id: userId,
+        item_id: itemId,
+        url,
+        item_url: state.item_url || '',
+      }];
+    }
+
+    const sent = await page.evaluate(buildSendMessageEvaluate(text)) as {
+      ok?: boolean;
+      reason?: string;
+    };
+
+    if (!sent?.ok) {
+      throw new SelectorError('闲鱼发送按钮', `消息发送失败：${sent?.reason || 'unknown-reason'}`);
+    }
+
+    await page.wait(1);
+
+    return [{
+      status: 'sent',
+      peer_name: state.peer_name || '',
+      item_title: state.item_title || '',
+      price: state.price || '',
+      location: state.location || '',
+      message: text,
+      peer_user_id: userId,
+      item_id: itemId,
+      url,
+      item_url: state.item_url || '',
+    }];
+  },
+});
+
+export const __test__ = {
+  normalizeNumericId,
+  buildChatUrl,
+};

package/src/clis/xianyu/item.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it, vi } from 'vitest';
+import { AuthRequiredError, EmptyResultError, SelectorError } from '../../errors.js';
+import { getRegistry } from '../../registry.js';
+import type { IPage } from '../../types.js';
+import { __test__ } from './item.js';
+import './item.js';
+
+function createPageMock(evaluateResult: unknown): 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([]),
+    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(''),
+    waitForCapture: vi.fn().mockResolvedValue(undefined),
+  } as IPage;
+}
+
+describe('xianyu item helpers', () => {
+  it('normalizes numeric item ids', () => {
+    expect(__test__.normalizeNumericId('1040754408976', 'item_id', '1040754408976')).toBe('1040754408976');
+    expect(__test__.normalizeNumericId(1040754408976, 'item_id', '1040754408976')).toBe('1040754408976');
+  });
+
+  it('builds item urls', () => {
+    expect(__test__.buildItemUrl('1040754408976')).toBe(
+      'https://www.goofish.com/item?id=1040754408976',
+    );
+  });
+
+  it('rejects invalid item ids', () => {
+    expect(() => __test__.normalizeNumericId('abc', 'item_id', '1040754408976')).toThrow();
+  });
+});
+
+describe('xianyu item command', () => {
+  const command = getRegistry().get('xianyu/item');
+
+  it('throws AuthRequiredError on login wall before mtop is available', async () => {
+    const page = createPageMock({ error: 'auth-required' });
+    await expect(command!.func!(page, { item_id: '1040754408976' })).rejects.toBeInstanceOf(AuthRequiredError);
+  });
+
+  it('throws EmptyResultError on verification or risk-control pages', async () => {
+    const page = createPageMock({ error: 'blocked' });
+    await expect(command!.func!(page, { item_id: '1040754408976' })).rejects.toBeInstanceOf(EmptyResultError);
+  });
+
+  it('keeps SelectorError for true mtop initialization failures', async () => {
+    const page = createPageMock({ error: 'mtop-not-ready' });
+    await expect(command!.func!(page, { item_id: '1040754408976' })).rejects.toBeInstanceOf(SelectorError);
+  });
+});

package/src/clis/xianyu/item.ts

@@ -0,0 +1,172 @@
+import { AuthRequiredError, EmptyResultError, SelectorError } from '../../errors.js';
+import { cli, Strategy } from '../../registry.js';
+import { normalizeNumericId } from './utils.js';
+
+function buildItemUrl(itemId: string): string {
+  return `https://www.goofish.com/item?id=${encodeURIComponent(itemId)}`;
+}
+
+function buildFetchItemEvaluate(itemId: string): string {
+  return `
+    (async () => {
+      const clean = (value) => String(value ?? '').replace(/\\s+/g, ' ').trim();
+      const extractRetCode = (ret) => {
+        const first = Array.isArray(ret) ? ret[0] : '';
+        return clean(first).split('::')[0] || '';
+      };
+
+      const waitFor = async (predicate, timeoutMs = 5000) => {
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+          if (predicate()) return true;
+          await new Promise((r) => setTimeout(r, 150));
+        }
+        return false;
+      };
+
+      const bodyText = document.body?.innerText || '';
+      if (/请先登录|登录后/.test(bodyText)) {
+        return { error: 'auth-required' };
+      }
+
+      if (/验证码|安全验证|异常访问/.test(bodyText)) {
+        return { error: 'blocked' };
+      }
+
+      await waitFor(() => window.lib?.mtop?.request);
+      if (!window.lib || !window.lib.mtop || typeof window.lib.mtop.request !== 'function') {
+        return { error: 'mtop-not-ready' };
+      }
+
+      let response;
+      try {
+        response = await window.lib.mtop.request({
+          api: 'mtop.taobao.idle.pc.detail',
+          data: { itemId: ${JSON.stringify(itemId)} },
+          type: 'POST',
+          v: '1.0',
+          dataType: 'json',
+          needLogin: false,
+          needLoginPC: false,
+          sessionOption: 'AutoLoginOnly',
+          ecode: 0,
+        });
+      } catch (error) {
+        const ret = error?.ret || [];
+        return {
+          error: 'mtop-request-failed',
+          error_code: extractRetCode(ret),
+          error_message: clean(Array.isArray(ret) ? ret.join(' | ') : error?.message || error),
+        };
+      }
+
+      const retCode = extractRetCode(response?.ret || []);
+      if (retCode && retCode !== 'SUCCESS') {
+        return {
+          error: 'mtop-response-error',
+          error_code: retCode,
+          error_message: clean((response?.ret || []).join(' | ')),
+        };
+      }
+
+      const data = response?.data || {};
+      const item = data.itemDO || {};
+      const seller = data.sellerDO || {};
+      const labels = Array.isArray(item.itemLabelExtList) ? item.itemLabelExtList : [];
+      const findLabel = (name) => labels.find((label) => clean(label.propertyText) === name)?.text || '';
+      const images = Array.isArray(item.imageInfos)
+        ? item.imageInfos.map((entry) => entry?.url).filter(Boolean)
+        : [];
+
+      return {
+        item_id: clean(item.itemId || ${JSON.stringify(itemId)}),
+        title: clean(item.title || ''),
+        description: clean(item.desc || ''),
+        price: clean('¥' + (item.soldPrice || item.defaultPrice || '')).replace(/^¥\\s*$/, ''),
+        original_price: clean(item.originalPrice || ''),
+        want_count: String(item.wantCnt ?? ''),
+        collect_count: String(item.collectCnt ?? ''),
+        browse_count: String(item.browseCnt ?? ''),
+        status: clean(item.itemStatusStr || ''),
+        condition: clean(findLabel('成色')),
+        brand: clean(findLabel('品牌')),
+        category: clean(findLabel('分类')),
+        location: clean(seller.publishCity || seller.city || ''),
+        seller_name: clean(seller.nick || seller.uniqueName || ''),
+        seller_id: String(seller.sellerId || ''),
+        seller_score: clean(seller.xianyuSummary || ''),
+        reply_ratio_24h: clean(seller.replyRatio24h || ''),
+        reply_interval: clean(seller.replyInterval || ''),
+        item_url: ${JSON.stringify(buildItemUrl(itemId))},
+        seller_url: seller.sellerId ? 'https://www.goofish.com/personal?userId=' + seller.sellerId : '',
+        image_count: String(images.length),
+        image_urls: images,
+      };
+    })()
+  `;
+}
+
+cli({
+  site: 'xianyu',
+  name: 'item',
+  description: '查看闲鱼商品详情',
+  domain: 'www.goofish.com',
+  strategy: Strategy.COOKIE,
+  navigateBefore: false,
+  browser: true,
+  args: [
+    { name: 'item_id', required: true, positional: true, help: '闲鱼商品 item_id' },
+  ],
+  columns: ['item_id', 'title', 'price', 'condition', 'brand', 'location', 'seller_name', 'want_count'],
+  func: async (page, kwargs) => {
+    const itemId = normalizeNumericId(kwargs.item_id, 'item_id', '1040754408976');
+
+    await page.goto(buildItemUrl(itemId));
+    await page.wait(2);
+
+    const result = await page.evaluate(buildFetchItemEvaluate(itemId)) as {
+      error?: string;
+      error_code?: string;
+      error_message?: string;
+      title?: string;
+      item_id?: string;
+    } & Record<string, unknown>;
+
+    if (result?.error === 'auth-required') {
+      throw new AuthRequiredError('www.goofish.com', 'Xianyu item detail requires a logged-in browser session');
+    }
+
+    if (result?.error === 'blocked') {
+      throw new EmptyResultError('xianyu item', 'Xianyu item detail is blocked by verification or risk control');
+    }
+
+    if (result?.error === 'mtop-not-ready') {
+      throw new SelectorError('window.lib.mtop', '闲鱼页面未完成初始化，无法调用商品详情接口');
+    }
+
+    if (!result || typeof result !== 'object') {
+      throw new EmptyResultError('xianyu item', '闲鱼商品详情接口未返回有效数据');
+    }
+
+    const errorCode = String(result.error_code || '');
+    const errorMessage = String(result.error_message || '');
+    if (/FAIL_SYS_SESSION_EXPIRED|SESSION_EXPIRED|FAIL_SYS/.test(errorCode) || /FAIL_SYS_SESSION_EXPIRED|SESSION_EXPIRED/.test(errorMessage)) {
+      throw new AuthRequiredError('www.goofish.com', 'Xianyu item detail requires a logged-in browser session');
+    }
+
+    if (result.error) {
+      throw new EmptyResultError('xianyu item', errorMessage || `Xianyu item detail request failed: ${result.error}`);
+    }
+
+    if (!String(result.title || '').trim()) {
+      throw new EmptyResultError('xianyu item', 'No item detail was returned for the specified item_id');
+    }
+
+    return [result];
+  },
+});
+
+export const __test__ = {
+  normalizeNumericId,
+  buildItemUrl,
+};

package/src/clis/xianyu/search.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { __test__ } from './search.js';
+
+describe('xianyu search helpers', () => {
+  it('normalizes limit into supported range', () => {
+    expect(__test__.normalizeLimit(undefined)).toBe(20);
+    expect(__test__.normalizeLimit(0)).toBe(1);
+    expect(__test__.normalizeLimit(3.8)).toBe(3);
+    expect(__test__.normalizeLimit(999)).toBe(__test__.MAX_LIMIT);
+  });
+
+  it('builds search URLs with encoded queries', () => {
+    expect(__test__.buildSearchUrl('笔记本电脑')).toBe(
+      'https://www.goofish.com/search?q=%E7%AC%94%E8%AE%B0%E6%9C%AC%E7%94%B5%E8%84%91',
+    );
+  });
+
+  it('extracts item ids from detail URLs', () => {
+    expect(__test__.itemIdFromUrl('https://www.goofish.com/item?id=954988715389&categoryId=126854525')).toBe('954988715389');
+    expect(__test__.itemIdFromUrl('https://www.goofish.com/search?q=test')).toBe('');
+  });
+});