@sovovs/bycli 1.8.0

package/clis/xianyu/im.test.js

@@ -0,0 +1,253 @@
+import { JSDOM } from 'jsdom';
+import { describe, expect, it } from 'vitest';
+import {
+    buildChatUrl,
+    buildExtractChatStateEvaluate,
+    buildExtractInboxEvaluate,
+    buildSendMessageEvaluate,
+    normalizeLimit,
+    normalizeRank,
+} from './im.js';
+import { ArgumentError, CommandExecutionError } from '@sovovs/bycli/errors';
+import './messages.js';
+import './reply.js';
+import { getRegistry } from '@sovovs/bycli/registry';
+
+async function runBrowserScript(html, script, { url = 'https://www.goofish.com/im', beforeEval } = {}) {
+    const dom = new JSDOM(html, { url, runScripts: 'outside-only' });
+    beforeEval?.(dom.window);
+    return dom.window.eval(script);
+}
+
+describe('xianyu im shared helpers', () => {
+    it('strictly validates limits and ranks before browser side effects', () => {
+        expect(normalizeLimit(undefined, 20, 100)).toBe(20);
+        expect(normalizeLimit('', 20, 100)).toBe(20);
+        expect(normalizeLimit('100', 20, 100)).toBe(100);
+        expect(() => normalizeLimit(0, 20, 100)).toThrow(ArgumentError);
+        expect(() => normalizeLimit(3.8, 20, 100)).toThrow(ArgumentError);
+        expect(() => normalizeLimit(999, 20, 100)).toThrow(ArgumentError);
+        expect(normalizeRank(undefined)).toBe(0);
+        expect(normalizeRank(1)).toBe(1);
+        expect(() => normalizeRank(0)).toThrow(ArgumentError);
+        expect(() => normalizeRank('1.5')).toThrow(ArgumentError);
+    });
+
+    it('extracts recent inbox conversations from visible IM rows', async () => {
+        const result = await runBrowserScript(`
+            <main>
+              <a href="/im?itemId=10001&peerUserId=90001" class="conversation unread">
+                <div class="name">张三</div>
+                <div class="title">MacBook Pro 14</div>
+                <div class="money">¥5999</div>
+                <div class="message">还在吗？</div>
+                <span class="badge">2</span>
+              </a>
+              <a href="https://www.goofish.com/im?itemId=10002&peerUserId=90002" class="conversation">
+                <div class="name">李四</div>
+                <div class="title">iPhone 15</div>
+                <div class="message">明天能发货</div>
+              </a>
+            </main>
+        `, buildExtractInboxEvaluate(10));
+
+        expect(result.requiresAuth).toBe(false);
+        expect(result.items).toEqual([
+            {
+                peer_name: '张三',
+                peer_user_id: '90001',
+                item_id: '10001',
+                item_title: 'MacBook Pro 14',
+                price: '¥5999',
+                last_message: '还在吗？',
+                unread: true,
+                unread_count: 2,
+                url: 'https://www.goofish.com/im?itemId=10001&peerUserId=90001',
+                row_index: 0,
+            },
+            {
+                peer_name: '李四',
+                peer_user_id: '90002',
+                item_id: '10002',
+                item_title: 'iPhone 15',
+                price: '',
+                last_message: '明天能发货',
+                unread: false,
+                unread_count: 0,
+                url: 'https://www.goofish.com/im?itemId=10002&peerUserId=90002',
+                row_index: 1,
+            },
+        ]);
+    });
+
+    it('extracts inbox conversations from the real virtualized conversation row shape', async () => {
+        const result = await runBrowserScript(`
+            <main>
+              <div id="conv-list-scrollable">
+                <div class="rc-virtual-list">
+                  <div class="rc-virtual-list-holder">
+                    <div class="rc-virtual-list-holder-inner">
+                      <div class="conversation-item--abc">
+                        <div>
+                          <div><span><sup title="3"><span>3</span></sup></span></div>
+                          <div>
+                            <div><div>通知消息</div></div>
+                            <div>订单即将自动确认收货</div>
+                            <div>3小时前</div>
+                          </div>
+                        </div>
+                      </div>
+                      <div class="conversation-item--abc">
+                        <div>
+                          <div>
+                            <div><div>隔壁猫小小</div></div>
+                            <div>亲，喜欢可以拍下，有问题留言哦～会尽快回复</div>
+                            <div>21小时前</div>
+                          </div>
+                        </div>
+                      </div>
+                    </div>
+                  </div>
+                </div>
+              </div>
+            </main>
+        `, buildExtractInboxEvaluate(10));
+
+        expect(result.items).toEqual([
+            expect.objectContaining({
+                peer_name: '通知消息',
+                last_message: '订单即将自动确认收货',
+                unread: true,
+                unread_count: 3,
+            }),
+            expect.objectContaining({
+                peer_name: '隔壁猫小小',
+                last_message: '亲，喜欢可以拍下，有问题留言哦～会尽快回复',
+                unread: false,
+            }),
+        ]);
+    });
+
+    it('extracts all visible messages for a specific chat', async () => {
+        const state = await runBrowserScript(`
+            <main>
+              <textarea></textarea>
+              <button>发送</button>
+              <div class="message-topbar"><span class="text1">张三</span><span class="text2">(90001)</span></div>
+              <a href="/item?id=10001"><span class="title">MacBook Pro 14</span><span class="money">¥5999</span></a>
+              <div id="message-list-scrollable">
+                <div class="bubble">你好</div>
+                <div class="message">还在吗？</div>
+                <div class="msg">在的</div>
+              </div>
+            </main>
+        `, buildExtractChatStateEvaluate());
+
+        expect(state.peer_name).toBe('张三');
+        expect(state.peer_masked_id).toBe('90001');
+        expect(state.item_title).toBe('MacBook Pro 14');
+        expect(state.messages).toEqual([
+            { index: 1, text: '你好' },
+            { index: 2, text: '还在吗？' },
+            { index: 3, text: '在的' },
+        ]);
+        expect(state.visible_messages).toEqual(['你好', '还在吗？', '在的']);
+    });
+
+    it('extracts messages from the real Xianyu message-row shape', async () => {
+        const state = await runBrowserScript(`
+            <main>
+              <textarea></textarea>
+              <button>发 送</button>
+              <div id="message-list-scrollable">
+                <div class="message-list-reverse--x">
+                  <div class="message-row--a">
+                    <div class="ant-dropdown-trigger message-content--b">
+                      <div class="message-text--c message-text-right--d"><span>我发出的消息</span></div>
+                      <div class="read-status-text--e">已读</div>
+                    </div>
+                  </div>
+                  <div class="message-row--a">
+                    <div class="ant-dropdown-trigger message-content--b">
+                      <div class="message-text--c message-text-left--d"><span>对方回复</span></div>
+                    </div>
+                  </div>
+                </div>
+              </div>
+            </main>
+        `, buildExtractChatStateEvaluate());
+
+        expect(state.can_send).toBe(true);
+        expect(state.messages).toEqual([
+            { index: 1, text: '我发出的消息' },
+            { index: 2, text: '对方回复' },
+        ]);
+    });
+
+
+    it('registers reply as an explicit write command', () => {
+        const command = getRegistry().get('xianyu/reply');
+        expect(command?.access).toBe('write');
+        expect(command?.columns).toEqual(['status', 'peer_name', 'item_title', 'price', 'location', 'message']);
+    });
+
+    it('builds chat URLs and requires post-submit message evidence', async () => {
+        expect(buildChatUrl('10001', '90001')).toBe('https://www.goofish.com/im?itemId=10001&peerUserId=90001');
+
+        let clicked = false;
+        const result = await runBrowserScript(`
+            <textarea></textarea>
+            <button>发送</button>
+            <div id="message-list-scrollable"></div>
+        `, buildSendMessageEvaluate('你好'), {
+            beforeEval(window) {
+                window.document.querySelector('button').addEventListener('click', () => {
+                    clicked = true;
+                    const row = window.document.createElement('div');
+                    row.className = 'message-row';
+                    row.innerHTML = '<div class="message-text">你好</div>';
+                    window.document.querySelector('#message-list-scrollable').append(row);
+                });
+            },
+        });
+
+        expect(result).toEqual({ ok: true });
+        expect(clicked).toBe(true);
+
+        await expect(runBrowserScript('<textarea></textarea><button>发送</button>', buildSendMessageEvaluate('没证据'), {
+            beforeEval(window) {
+                window.setTimeout = (fn) => {
+                    fn();
+                    return 0;
+                };
+            },
+        }))
+            .resolves.toEqual({ ok: false, reason: 'send-postcondition-timeout' });
+    });
+
+    it('requires an explicit conversation target for messages and reply', async () => {
+        const messages = getRegistry().get('xianyu/messages');
+        const reply = getRegistry().get('xianyu/reply');
+        const page = {
+            goto: () => { throw new Error('should not navigate'); },
+            wait: () => {},
+            evaluate: () => ({}),
+        };
+
+        await expect(messages.func(page, { limit: 1 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(reply.func(page, { text: 'hello' })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(messages.func(page, { item_id: '10001', user_id: '90001', rank: 1 })).rejects.toBeInstanceOf(ArgumentError);
+    });
+
+    it('treats malformed evaluate payloads as command failures', async () => {
+        const messages = getRegistry().get('xianyu/messages');
+        const page = {
+            goto: () => {},
+            wait: () => {},
+            evaluate: () => null,
+        };
+
+        await expect(messages.func(page, { item_id: '10001', user_id: '90001', limit: 1 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+});

package/clis/xianyu/inbox.js

@@ -0,0 +1,96 @@
+import { AuthRequiredError, CommandExecutionError, EmptyResultError } from '@sovovs/bycli/errors';
+import { cli, Strategy } from '@sovovs/bycli/registry';
+import {
+    buildClickInboxConversationEvaluate,
+    buildExtractInboxEvaluate,
+    buildInboxUrl,
+    buildReadCurrentConversationUrlEvaluate,
+    DEFAULT_INBOX_LIMIT,
+    MAX_INBOX_LIMIT,
+    normalizeLimit,
+    requireClickResult,
+    requireEvaluateObject,
+} from './im.js';
+
+cli({
+    site: 'xianyu',
+    name: 'inbox',
+    access: 'read',
+    description: '列出闲鱼最近私信会话',
+    domain: 'www.goofish.com',
+    strategy: Strategy.COOKIE,
+    navigateBefore: false,
+    browser: true,
+    args: [
+        { name: 'limit', type: 'int', default: DEFAULT_INBOX_LIMIT, help: 'Number of conversations to return' },
+        { name: 'unread-only', type: 'bool', default: false, help: 'Return only conversations with unread messages' },
+        { name: 'resolve-ids', type: 'bool', default: false, help: 'Click each visible conversation to resolve item_id and peer_user_id from the chat URL' },
+    ],
+    columns: ['rank', 'peer_name', 'peer_user_id', 'item_id', 'item_title', 'price', 'last_message', 'unread', 'unread_count', 'url'],
+    func: async (page, kwargs) => {
+        const limit = normalizeLimit(kwargs.limit, DEFAULT_INBOX_LIMIT, MAX_INBOX_LIMIT, 'inbox --limit');
+        const unreadOnly = Boolean(kwargs['unread-only']);
+        const resolveIds = Boolean(kwargs['resolve-ids']);
+        let currentUrl = '';
+        if (page.getCurrentUrl) {
+            try {
+                currentUrl = await page.getCurrentUrl();
+            } catch {
+                currentUrl = '';
+            }
+        }
+        if (!/https:\/\/www\.goofish\.com\/im\b/.test(currentUrl)) {
+            await page.goto(buildInboxUrl());
+        }
+        await page.wait(4);
+        const payload = requireEvaluateObject(await page.evaluate(buildExtractInboxEvaluate(limit)), 'inbox');
+        if (payload?.requiresAuth) {
+            throw new AuthRequiredError('www.goofish.com', 'Xianyu inbox requires a logged-in browser session');
+        }
+        if (payload?.blocked) {
+            throw new AuthRequiredError('www.goofish.com', 'Xianyu inbox is blocked by verification or risk control');
+        }
+        if (!Array.isArray(payload.items)) {
+            throw new CommandExecutionError('Xianyu inbox returned malformed conversation list');
+        }
+        const items = payload.items;
+        if (!items.length) {
+            throw new EmptyResultError('xianyu inbox', 'No Xianyu inbox conversations were found');
+        }
+        let conversations = items.slice(0, limit);
+        if (unreadOnly) {
+            conversations = conversations.filter((item) => Boolean(item.unread));
+        }
+        if (resolveIds) {
+            for (const item of conversations) {
+                if (item.item_id && item.peer_user_id) continue;
+                const rowIndex = Number(item.row_index);
+                if (!Number.isInteger(rowIndex) || rowIndex < 0) continue;
+                requireClickResult(await page.evaluate(buildClickInboxConversationEvaluate(rowIndex)), 'inbox resolve-ids click');
+                await page.wait(1);
+                const current = requireEvaluateObject(await page.evaluate(buildReadCurrentConversationUrlEvaluate()), 'inbox current-url');
+                item.item_id = current?.item_id || item.item_id || '';
+                item.peer_user_id = current?.peer_user_id || item.peer_user_id || '';
+                item.url = current?.url || item.url || '';
+            }
+        }
+        return conversations.map((item, index) => ({
+            rank: index + 1,
+            peer_name: item.peer_name || '',
+            peer_user_id: item.peer_user_id || '',
+            item_id: item.item_id || '',
+            item_title: item.item_title || '',
+            price: item.price || '',
+            last_message: item.last_message || '',
+            unread: Boolean(item.unread),
+            unread_count: Number(item.unread_count || 0),
+            url: item.url || '',
+        }));
+    },
+});
+
+export const __test__ = {
+    buildInboxUrl,
+    buildExtractInboxEvaluate,
+    normalizeLimit,
+};

package/clis/xianyu/item.js

@@ -0,0 +1,153 @@
+import { AuthRequiredError, EmptyResultError, selectorError } from '@sovovs/bycli/errors';
+import { cli, Strategy } from '@sovovs/bycli/registry';
+import { normalizeNumericId } from './utils.js';
+function buildItemUrl(itemId) {
+    return `https://www.goofish.com/item?id=${encodeURIComponent(itemId)}`;
+}
+function buildFetchItemEvaluate(itemId) {
+    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',
+    access: 'read',
+    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));
+        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 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/clis/xianyu/item.test.js

@@ -0,0 +1,56 @@
+import { describe, expect, it, vi } from 'vitest';
+import { AuthRequiredError, EmptyResultError } from '@sovovs/bycli/errors';
+import { getRegistry } from '@sovovs/bycli/registry';
+import { __test__ } from './item.js';
+import './item.js';
+function createPageMock(evaluateResult) {
+    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),
+    };
+}
+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 SELECTOR code for true mtop initialization failures', async () => {
+        const page = createPageMock({ error: 'mtop-not-ready' });
+        await expect(command.func(page, { item_id: '1040754408976' })).rejects.toMatchObject({ code: 'SELECTOR' });
+    });
+});

package/clis/xianyu/messages.js

@@ -0,0 +1,91 @@
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@sovovs/bycli/errors';
+import { cli, Strategy } from '@sovovs/bycli/registry';
+import {
+    buildChatUrl,
+    buildClickInboxConversationEvaluate,
+    buildExtractChatStateEvaluate,
+    DEFAULT_MESSAGE_LIMIT,
+    MAX_MESSAGE_LIMIT,
+    normalizeLimit,
+    normalizeRank,
+    requireClickResult,
+    requireEvaluateObject,
+} from './im.js';
+import { normalizeNumericId } from './utils.js';
+
+cli({
+    site: 'xianyu',
+    name: 'messages',
+    access: 'read',
+    description: '读取指定闲鱼私信会话的最近聊天内容',
+    domain: 'www.goofish.com',
+    strategy: Strategy.COOKIE,
+    navigateBefore: false,
+    browser: true,
+    args: [
+        { name: 'item_id', positional: true, help: '闲鱼商品 item_id' },
+        { name: 'user_id', positional: true, help: '聊一聊对方的 user_id / peerUserId' },
+        { name: 'limit', type: 'int', default: DEFAULT_MESSAGE_LIMIT, help: 'Number of visible messages to return' },
+        { name: 'rank', type: 'int', default: 0, help: 'Conversation rank from xianyu inbox; clicks the visible row instead of requiring IDs' },
+    ],
+    columns: ['index', 'peer_name', 'item_title', 'message', 'item_id', 'peer_user_id', 'url'],
+    func: async (page, kwargs) => {
+        const hasItemId = kwargs.item_id != null && kwargs.item_id !== '';
+        const hasUserId = kwargs.user_id != null && kwargs.user_id !== '';
+        const rank = normalizeRank(kwargs.rank);
+        if (rank > 0 && (hasItemId || hasUserId)) {
+            throw new ArgumentError('xianyu messages accepts either item_id/user_id or --rank, not both');
+        }
+        if (rank === 0 && hasItemId !== hasUserId) {
+            throw new ArgumentError('xianyu messages requires both item_id and user_id, or --rank from xianyu inbox');
+        }
+        if (rank === 0 && !hasItemId && !hasUserId) {
+            throw new ArgumentError('xianyu messages requires item_id/user_id or --rank from xianyu inbox');
+        }
+        const hasIds = hasItemId && hasUserId;
+        const itemId = hasIds ? normalizeNumericId(kwargs.item_id, 'item_id', '1038951278192') : '';
+        const userId = hasIds ? normalizeNumericId(kwargs.user_id, 'user_id', '3650092411') : '';
+        const limit = normalizeLimit(kwargs.limit, DEFAULT_MESSAGE_LIMIT, MAX_MESSAGE_LIMIT, 'messages --limit');
+        let url = '';
+        if (hasIds) {
+            url = buildChatUrl(itemId, userId);
+            await page.goto(url);
+        } else {
+            if (!page.getCurrentUrl || !/https:\/\/www\.goofish\.com\/im\b/.test(await page.getCurrentUrl())) {
+                await page.goto('https://www.goofish.com/im');
+            }
+        }
+        await page.wait(2);
+        if (rank > 0) {
+            requireClickResult(await page.evaluate(buildClickInboxConversationEvaluate(rank - 1)), 'messages rank click');
+            await page.wait(2);
+        }
+        const state = requireEvaluateObject(await page.evaluate(buildExtractChatStateEvaluate(limit)), 'messages');
+        if (state?.requiresAuth) {
+            throw new AuthRequiredError('www.goofish.com', 'Xianyu messages requires a logged-in browser session');
+        }
+        if (!Array.isArray(state.messages)) {
+            throw new CommandExecutionError('Xianyu messages returned malformed message list');
+        }
+        const messages = state.messages;
+        if (!messages.length) {
+            throw new EmptyResultError('xianyu messages', 'No visible messages were found in this Xianyu conversation');
+        }
+        return messages.slice(-limit).map((message, index) => ({
+            index: index + 1,
+            peer_name: state.peer_name || '',
+            item_title: state.item_title || '',
+            message: message.text || '',
+            item_id: itemId,
+            peer_user_id: userId,
+            url: url || '',
+        }));
+    },
+});
+
+export const __test__ = {
+    buildChatUrl,
+    buildExtractChatStateEvaluate,
+    normalizeLimit,
+    normalizeRank,
+};