@jackwener/opencli 1.7.21 → 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 '@jackwener/opencli/errors';
+import './messages.js';
+import './reply.js';
+import { getRegistry } from '@jackwener/opencli/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 '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/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/messages.js

@@ -0,0 +1,91 @@
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/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,
+};

package/clis/xianyu/reply.js

@@ -0,0 +1,82 @@
+import { ArgumentError, AuthRequiredError, CommandExecutionError, selectorError } from '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { buildChatUrl, buildClickInboxConversationEvaluate, buildExtractChatStateEvaluate, buildSendMessageEvaluate, normalizeRank, requireClickResult, requireEvaluateObject, requireText } from './im.js';
+import { normalizeNumericId } from './utils.js';
+
+cli({
+    site: 'xianyu',
+    name: 'reply',
+    access: 'write',
+    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: 'text', required: true, help: 'Message text to send' },
+        { name: 'rank', type: 'int', default: 0, help: 'Conversation rank from xianyu inbox; clicks the visible row instead of requiring IDs' },
+    ],
+    columns: ['status', 'peer_name', 'item_title', 'price', 'location', 'message'],
+    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 reply accepts either item_id/user_id or --rank, not both');
+        }
+        if (rank === 0 && hasItemId !== hasUserId) {
+            throw new ArgumentError('xianyu reply requires both item_id and user_id, or --rank from xianyu inbox');
+        }
+        if (rank === 0 && !hasItemId && !hasUserId) {
+            throw new ArgumentError('xianyu reply 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 text = requireText(kwargs.text, 'xianyu reply --text');
+        const url = hasIds ? buildChatUrl(itemId, userId) : '';
+        if (hasIds) {
+            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)), 'reply rank click');
+            await page.wait(2);
+        }
+        const state = requireEvaluateObject(await page.evaluate(buildExtractChatStateEvaluate()), 'reply');
+        if (state?.requiresAuth) {
+            throw new AuthRequiredError('www.goofish.com', 'Xianyu reply requires a logged-in browser session');
+        }
+        if (!state?.can_input) {
+            throw selectorError('闲鱼聊天输入框', '未找到可用的聊天输入框，请确认该会话页已正确加载');
+        }
+        const sent = requireEvaluateObject(await page.evaluate(buildSendMessageEvaluate(text)), 'reply send');
+        if (!sent?.ok) {
+            throw new CommandExecutionError(`Xianyu reply did not observe the sent message: ${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: url || '',
+            item_url: state.item_url || '',
+        }];
+    },
+});
+
+export const __test__ = {
+    buildChatUrl,
+    buildSendMessageEvaluate,
+};

package/clis/xiaohongshu/creator-note-detail.js

@@ -9,6 +9,7 @@
  * Requires: logged into creator.xiaohongshu.com in Chrome.
  */
 import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
 const NOTE_DETAIL_DATETIME_RE = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$/;
 const NOTE_DETAIL_METRICS = [
     { label: '曝光数', section: '基础数据' },
@@ -337,7 +338,7 @@ cli({
         const rows = await fetchCreatorNoteDetailRows(page, noteId);
         const hasCoreMetric = rows.some((row) => row.section !== '笔记信息' && row.value);
         if (!hasCoreMetric) {
-            throw new Error('No note detail data found. Check note_id and login status for creator.xiaohongshu.com.');
+            throw new EmptyResultError('xiaohongshu creator-note-detail', 'No note detail data found. Check note_id and login status for creator.xiaohongshu.com.');
         }
         return rows;
     },

package/clis/xiaohongshu/creator-note-detail.test.js

@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
+import { EmptyResultError } from '@jackwener/opencli/errors';
 import { getRegistry } from '@jackwener/opencli/registry';
 import { appendAudienceRows, appendTrendRows, parseCreatorNoteDetailDomData, parseCreatorNoteDetailText } from './creator-note-detail.js';
 import './creator-note-detail.js';
@@ -288,4 +289,14 @@ describe('xiaohongshu creator-note-detail', () => {
         expect(page.wait).toHaveBeenCalledWith(expect.objectContaining({ time: expect.any(Number) }));
         expect(page.wait.mock.calls.length).toBeGreaterThanOrEqual(4);
     });
+    it('throws EmptyResultError when the detail page exposes no metrics', async () => {
+        const cmd = getRegistry().get('xiaohongshu/creator-note-detail');
+        const page = createPageMock(undefined);
+        page.evaluate = vi.fn()
+            .mockResolvedValueOnce(null)
+            .mockResolvedValueOnce('笔记数据详情\n暂无数据')
+            .mockResolvedValue(null);
+
+        await expect(cmd.func(page, { 'note-id': 'demo-note-id' })).rejects.toBeInstanceOf(EmptyResultError);
+    });
 });

package/clis/xiaohongshu/creator-notes-summary.js

@@ -5,6 +5,7 @@
  * returns one summary row per note, suitable for quick review or downstream JSON use.
  */
 import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
 import { fetchCreatorNotes } from './creator-notes.js';
 import { fetchCreatorNoteDetailRows } from './creator-note-detail.js';
 function findDetailValue(rows, metric) {
@@ -61,7 +62,7 @@ cli({
         const limit = kwargs.limit || 3;
         const notes = await fetchCreatorNotes(page, limit);
         if (!notes.length) {
-            throw new Error('No notes found. Are you logged into creator.xiaohongshu.com?');
+            throw new EmptyResultError('xiaohongshu creator-notes-summary', 'No notes found. Ensure you are logged into creator.xiaohongshu.com and the account has published notes.');
         }
         const results = [];
         for (const [index, note] of notes.entries()) {

package/clis/xiaohongshu/creator-notes-summary.test.js

@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
+import { EmptyResultError } from '@jackwener/opencli/errors';
 import { summarizeCreatorNote } from './creator-notes-summary.js';
 import { getRegistry } from '@jackwener/opencli/registry';
 import * as creatorNotesModule from './creator-notes.js';
@@ -84,4 +85,10 @@ describe('xiaohongshu creator-notes-summary', () => {
         expect(page.wait).toHaveBeenCalledWith(expect.objectContaining({ time: expect.any(Number) }));
         expect(page.wait.mock.calls).toHaveLength(1);
     });
+    it('throws EmptyResultError when there are no notes to summarize', async () => {
+        const cmd = getRegistry().get('xiaohongshu/creator-notes-summary');
+        vi.spyOn(creatorNotesModule, 'fetchCreatorNotes').mockResolvedValue([]);
+
+        await expect(cmd.func({ wait: vi.fn() }, { limit: 2 })).rejects.toBeInstanceOf(EmptyResultError);
+    });
 });

package/clis/xiaohongshu/creator-notes.js

@@ -8,6 +8,7 @@
  * Requires: logged into creator.xiaohongshu.com in Chrome.
  */
 import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
 const DATE_LINE_RE = /^发布于 (\d{4}年\d{2}月\d{2}日 \d{2}:\d{2})$/;
 const METRIC_LINE_RE = /^\d+$/;
 const VISIBILITY_LINE_RE = /可见$/;
@@ -210,7 +211,7 @@ cli({
         const limit = kwargs.limit || 20;
         const notes = await fetchCreatorNotes(page, limit);
         if (!Array.isArray(notes) || notes.length === 0) {
-            throw new Error('No notes found. Are you logged into creator.xiaohongshu.com?');
+            throw new EmptyResultError('xiaohongshu creator-notes', 'No notes found. Ensure you are logged into creator.xiaohongshu.com and the account has published notes.');
         }
         return notes
             .slice(0, limit)

package/clis/xiaohongshu/creator-notes.test.js

@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
+import { EmptyResultError } from '@jackwener/opencli/errors';
 import { getRegistry } from '@jackwener/opencli/registry';
 import { parseCreatorNoteIdsFromHtml, parseCreatorNotesText } from './creator-notes.js';
 import './creator-notes.js';
@@ -189,4 +190,15 @@ describe('xiaohongshu creator-notes', () => {
             'dddddddddddddddddddddddd',
         ]);
     });
+    it('throws EmptyResultError when the creator account has no notes', async () => {
+        const cmd = getRegistry().get('xiaohongshu/creator-notes');
+        const page = createPageMock(undefined);
+        page.evaluate = vi.fn()
+            .mockResolvedValueOnce(undefined)
+            .mockResolvedValueOnce(undefined)
+            .mockResolvedValueOnce([])
+            .mockResolvedValueOnce({ text: '', html: '' });
+
+        await expect(cmd.func(page, { limit: 1 })).rejects.toBeInstanceOf(EmptyResultError);
+    });
 });

package/clis/xiaohongshu/creator-stats.js

@@ -8,6 +8,7 @@
  * Requires: logged into creator.xiaohongshu.com in Chrome.
  */
 import { cli, Strategy } from '@jackwener/opencli/registry';
+import { EmptyResultError } from '@jackwener/opencli/errors';
 cli({
     site: 'xiaohongshu',
     name: 'creator-stats',
@@ -52,7 +53,7 @@ cli({
         }
         const stats = data.data[period];
         if (!stats) {
-            throw new Error(`No data for period "${period}". Available: ${Object.keys(data.data).join(', ')}`);
+            throw new EmptyResultError('xiaohongshu creator-stats', `No data for period "${period}". Available: ${Object.keys(data.data).join(', ')}`);
         }
         // Format daily trend as sparkline-like summary
         const formatTrend = (list) => {