@jackwener/opencli 1.7.12 → 1.7.13

package/clis/uisdc/news.test.js

@@ -0,0 +1,66 @@
+import { JSDOM } from 'jsdom';
+import { describe, expect, it, vi } from 'vitest';
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { uisdcNewsCommand, __test__ } from './news.js';
+
+function runBrowserScript(html, script, url = 'https://www.uisdc.com/news') {
+    const dom = new JSDOM(html, { url, runScripts: 'outside-only' });
+    return dom.window.eval(script);
+}
+
+function makePage(evaluateResult) {
+    return {
+        goto: vi.fn().mockResolvedValue(undefined),
+        evaluate: vi.fn().mockResolvedValue(evaluateResult),
+    };
+}
+
+describe('uisdc/news', () => {
+    it('registers stable URL in columns', () => {
+        expect(uisdcNewsCommand.access).toBe('read');
+        expect(uisdcNewsCommand.columns).toEqual(['rank', 'title', 'summary', 'url']);
+    });
+
+    it('validates limit before browser navigation', async () => {
+        const page = makePage({ ok: true, rows: [] });
+        await expect(uisdcNewsCommand.func(page, { limit: 0 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(uisdcNewsCommand.func(page, { limit: 51 })).rejects.toBeInstanceOf(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+
+    it('extracts rows from the UISDC news DOM', async () => {
+        const html = `
+          <div class="news-list">
+            <div class="news-item">
+              <div class="item-content">
+                <div class="dubao-items">
+                  <div class="dubao-item">
+                    <a href="/article-1"><span class="dubao-title"> AI design news </span></a>
+                    <div class="dubao-content"> summary text </div>
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+        `;
+        const payload = runBrowserScript(html, __test__.buildExtractUisdcNewsJs());
+        const page = makePage(payload);
+
+        const rows = await uisdcNewsCommand.func(page, { limit: 10 });
+
+        expect(page.goto).toHaveBeenCalledWith('https://www.uisdc.com/news', { waitUntil: 'load', settleMs: 3000 });
+        expect(rows).toEqual([{
+            rank: 1,
+            title: 'AI design news',
+            summary: 'summary text',
+            url: 'https://www.uisdc.com/article-1',
+        }]);
+    });
+
+    it('maps selector drift and empty rows to typed errors', async () => {
+        await expect(uisdcNewsCommand.func(makePage({ ok: false, reason: 'selector-missing' }), { limit: 1 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+        await expect(uisdcNewsCommand.func(makePage({ ok: true, rows: [{ title: '', url: '' }] }), { limit: 1 }))
+            .rejects.toBeInstanceOf(EmptyResultError);
+    });
+});

package/clis/wanfang/search.js

@@ -14,7 +14,6 @@ cli({
         { name: 'limit', type: 'int', default: 10, help: '返回结果数量 (max 20)' },
     ],
     columns: ['rank', 'title', 'authors', 'source', 'year', 'type', 'cited', 'url'],
-    navigateBefore: false,
     func: async (page, kwargs) => {
         const limit = clampInt(kwargs.limit, 10, 1, 20);
         const query = requireNonEmptyQuery(kwargs.query);

package/clis/web/read.js

@@ -18,6 +18,7 @@ import { downloadArticle } from '@jackwener/opencli/download/article-download';
 
 const NETWORK_IDLE_QUIET_MS = 1000;
 const NETWORK_IDLE_POLL_MS = 500;
+const MIN_NON_STRUCTURAL_IFRAME_TEXT_CHARS = 50;
 
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
@@ -31,7 +32,7 @@ function boolish(value) {
 
 function normalizeFrameMode(value) {
     const mode = String(value || 'same-origin').toLowerCase();
-    if (['same-origin', 'none'].includes(mode)) return mode;
+    if (['same-origin', 'all-same-origin', 'none'].includes(mode)) return mode;
     return 'same-origin';
 }
 
@@ -144,6 +145,7 @@ function buildRenderAwareExtractorJs(options) {
     return `
       (() => {
         const frameMode = ${JSON.stringify(options.frames)};
+        const minNonStructuralIframeTextChars = ${MIN_NON_STRUCTURAL_IFRAME_TEXT_CHARS};
         const result = {
           title: '',
           author: '',
@@ -188,6 +190,7 @@ function buildRenderAwareExtractorJs(options) {
         const collectEmptyContainers = (root, scope, baseUrl) => {
           const likely = 'table, tbody, ul[id], ol[id], div[id], section[id], [class*="grid"], [class*="data"], [class*="list"], [id*="grid"], [id*="data"], [id*="list"]';
           root.querySelectorAll?.(likely).forEach((el) => {
+            if (scope === 'main' && el.closest?.('[data-opencli-iframe-source]')) return;
             const id = el.getAttribute('id') || '';
             const cls = el.getAttribute('class') || '';
             const name = [id, cls].join(' ').toLowerCase();
@@ -202,6 +205,29 @@ function buildRenderAwareExtractorJs(options) {
             });
           });
         };
+        const hasDataContainerSignal = (root) => {
+          const likely = 'table, tbody, ul[id], ol[id], [id*="grid"], [id*="data"], [id*="list"], [id*="content"], [id*="result"], [class*="grid"], [class*="data"], [class*="list"], [class*="content"], [class*="result"]';
+          return !!root.querySelector?.(likely);
+        };
+        const shouldIncludeExternalFrame = (frameBody) => {
+          // Outside-content iframes are less trusted than placeholders inside
+          // contentEl. Long plain text is the fallback for simple same-origin
+          // frames that lack article/table/list structure.
+          if (textLen(frameBody) >= minNonStructuralIframeTextChars) return true;
+          if (frameBody.querySelector?.('article, main, [role="main"], table, tbody, ul li, ol li')) return true;
+          return hasDataContainerSignal(frameBody);
+        };
+        const buildFrameSection = (frameBody, desc, fallbackLabel) => {
+          absolutizeTree(frameBody, desc.src || window.location.href);
+          collectEmptyContainers(frameBody, 'iframe', desc.src);
+          const section = document.createElement('section');
+          section.setAttribute('data-opencli-iframe-source', desc.src);
+          const heading = document.createElement('h2');
+          heading.textContent = '来自 iframe: ' + (desc.src || fallbackLabel);
+          section.appendChild(heading);
+          Array.from(frameBody.childNodes).forEach(node => section.appendChild(node));
+          return section;
+        };
 
         const ogTitle = document.querySelector('meta[property="og:title"]');
         if (ogTitle) result.title = ogTitle.getAttribute('content')?.trim() || '';
@@ -252,28 +278,32 @@ function buildRenderAwareExtractorJs(options) {
 
         const originalFrames = Array.from(contentEl.querySelectorAll('iframe'));
         const clonedFrames = Array.from(clone.querySelectorAll('iframe'));
+        const clonedFrameByOriginal = new Map();
+        originalFrames.forEach((frame, index) => {
+          const cloned = clonedFrames[index];
+          if (cloned) clonedFrameByOriginal.set(frame, cloned);
+        });
         const allFrames = Array.from(document.querySelectorAll('iframe'));
-        result.diagnostics.frames = allFrames.map(describeFrame);
+        const frameDescriptions = new Map();
+        allFrames.forEach((frame, index) => frameDescriptions.set(frame, describeFrame(frame, index)));
+        const getFrameDescription = (frame, fallbackIndex) => frameDescriptions.get(frame) || describeFrame(frame, fallbackIndex);
+        result.diagnostics.frames = allFrames.map(frame => frameDescriptions.get(frame));
 
-        if (frameMode === 'same-origin') {
-          originalFrames.forEach((frame, index) => {
-            const cloned = clonedFrames[index];
-            if (!cloned) return;
-            const desc = describeFrame(frame, index);
+        if (frameMode === 'same-origin' || frameMode === 'all-same-origin') {
+          allFrames.forEach((frame, index) => {
+            const insideContent = contentEl.contains(frame);
+            const cloned = insideContent ? clonedFrameByOriginal.get(frame) : null;
+            if (insideContent && !cloned) return;
+            const desc = getFrameDescription(frame, index);
             if (!desc.sameOrigin || !desc.accessible) return;
             try {
               const doc = frame.contentDocument;
               if (!doc?.body) return;
               const frameBody = doc.body.cloneNode(true);
-              absolutizeTree(frameBody, desc.src || window.location.href);
-              collectEmptyContainers(frameBody, 'iframe', desc.src);
-              const section = document.createElement('section');
-              section.setAttribute('data-opencli-iframe-source', desc.src);
-              const heading = document.createElement('h2');
-              heading.textContent = '来自 iframe: ' + (desc.src || frame.getAttribute('src') || ('#' + index));
-              section.appendChild(heading);
-              Array.from(frameBody.childNodes).forEach(node => section.appendChild(node));
-              cloned.replaceWith(section);
+              if (frameMode !== 'all-same-origin' && !insideContent && !shouldIncludeExternalFrame(frameBody)) return;
+              const section = buildFrameSection(frameBody, desc, frame.getAttribute('src') || ('#' + index));
+              if (insideContent) cloned.replaceWith(section);
+              else clone.appendChild(section);
               result.diagnostics.includedFrameCount += 1;
             } catch {}
           });
@@ -376,7 +406,7 @@ const command = cli({
         { name: 'wait', type: 'int', default: 3, help: 'Seconds to wait after page load' },
         { name: 'wait-for', valueRequired: true, help: 'CSS selector to wait for in the main document or same-origin iframes' },
         { name: 'wait-until', default: 'domstable', choices: ['domstable', 'networkidle'], help: 'Readiness policy after navigation: domstable or networkidle' },
-        { name: 'frames', default: 'same-origin', choices: ['same-origin', 'none'], help: 'Iframe handling mode: same-origin or none' },
+        { name: 'frames', default: 'same-origin', choices: ['same-origin', 'all-same-origin', 'none'], help: 'Iframe handling mode: relevant same-origin, all-same-origin, or none' },
         { name: 'diagnose', type: 'boolean', default: false, help: 'Print render diagnostics (frames, empty containers, XHR/API-like requests) to stderr' },
         { name: 'stdout', type: 'boolean', default: false, help: 'Print markdown to stdout instead of saving to a file' },
     ],

package/clis/web/read.test.js

@@ -165,6 +165,18 @@ describe('web/read stdout behavior', () => {
         expect(page.evaluate.mock.calls[0]?.[0]).toContain('const frameMode = "none"');
     });
 
+    it('passes --frames all-same-origin into the extractor', async () => {
+        await read.func(page, {
+            url: 'https://example.com/article',
+            output: '/tmp/out',
+            'download-images': false,
+            frames: 'all-same-origin',
+            stdout: false,
+        });
+
+        expect(page.evaluate.mock.calls[0]?.[0]).toContain('const frameMode = "all-same-origin"');
+    });
+
     it('fails fast when --wait-until networkidle is requested but capture is unavailable', async () => {
         page.startNetworkCapture.mockResolvedValue(false);
 
@@ -217,7 +229,7 @@ describe('web/read render-aware helpers', () => {
         `, { url: 'https://example.com/main.html', runScripts: 'outside-only' });
         const frame = dom.window.document.querySelector('iframe');
         frame.contentDocument.open();
-        frame.contentDocument.write('<body><table id="gridHd"><tr><th>Name</th></tr></table><ul id="gridDatas"><li>Station A 42</li></ul></body>');
+        frame.contentDocument.write('<body><table id="gridHd"><tr><th>Name</th></tr></table><ul id="gridDatas"></ul><p>Station A 42</p></body>');
         frame.contentDocument.close();
 
         const result = dom.window.eval(__test__.buildRenderAwareExtractorJs({ frames: 'same-origin' }));
@@ -226,6 +238,94 @@ describe('web/read render-aware helpers', () => {
         expect(result.contentHtml).toContain('data-opencli-iframe-source="https://example.com/frame.html"');
         expect(result.contentHtml).toContain('来自 iframe: https://example.com/frame.html');
         expect(result.contentHtml).toContain('Station A 42');
+        expect(result.diagnostics.emptyContainers).toEqual(expect.arrayContaining([
+            expect.objectContaining({ scope: 'iframe', id: 'gridDatas', url: 'https://example.com/frame.html' }),
+        ]));
+        expect(result.diagnostics.emptyContainers.every(item => item.scope === 'iframe')).toBe(true);
+    });
+
+    it('merges readable same-origin iframes outside the selected content element', () => {
+        const dom = new JSDOM(`
+          <main>
+            <h1>Main Article</h1>
+            <p>${'Main content '.repeat(30)}</p>
+          </main>
+          <aside>
+            <iframe id="outside" src="/outside.html"></iframe>
+          </aside>
+        `, { url: 'https://example.com/main.html', runScripts: 'outside-only' });
+        const frame = dom.window.document.querySelector('iframe');
+        frame.contentDocument.open();
+        frame.contentDocument.write(`<body><h1>Outside Frame</h1><p>${'Frame data '.repeat(12)}</p></body>`);
+        frame.contentDocument.close();
+
+        const result = dom.window.eval(__test__.buildRenderAwareExtractorJs({ frames: 'same-origin' }));
+
+        expect(result.diagnostics.includedFrameCount).toBe(1);
+        expect(result.contentHtml).toContain('data-opencli-iframe-source="https://example.com/outside.html"');
+        expect(result.contentHtml).toContain('Outside Frame');
+        expect(result.contentHtml).toContain('Frame data');
+    });
+
+    it('keeps short data-like iframes outside the selected content element', () => {
+        const dom = new JSDOM(`
+          <main>
+            <h1>Main Article</h1>
+            <p>${'Main content '.repeat(30)}</p>
+          </main>
+          <iframe id="data-frame" src="/data.html"></iframe>
+        `, { url: 'https://example.com/main.html', runScripts: 'outside-only' });
+        const frame = dom.window.document.querySelector('iframe');
+        frame.contentDocument.open();
+        frame.contentDocument.write('<body><table id="gridHd"><tr><th>水位</th></tr><tr><td>42</td></tr></table><ul id="gridDatas"></ul></body>');
+        frame.contentDocument.close();
+
+        const result = dom.window.eval(__test__.buildRenderAwareExtractorJs({ frames: 'same-origin' }));
+
+        expect(result.diagnostics.includedFrameCount).toBe(1);
+        expect(result.contentHtml).toContain('42');
+        expect(result.diagnostics.emptyContainers).toEqual(expect.arrayContaining([
+            expect.objectContaining({ scope: 'iframe', id: 'gridDatas', url: 'https://example.com/data.html' }),
+        ]));
+        expect(result.diagnostics.emptyContainers.every(item => item.scope === 'iframe')).toBe(true);
+    });
+
+    it('skips short non-structural iframes outside the selected content element', () => {
+        const dom = new JSDOM(`
+          <main>
+            <h1>Main Article</h1>
+            <p>${'Main content '.repeat(30)}</p>
+          </main>
+          <iframe id="tiny-frame" src="/tiny.html"></iframe>
+        `, { url: 'https://example.com/main.html', runScripts: 'outside-only' });
+        const frame = dom.window.document.querySelector('iframe');
+        frame.contentDocument.open();
+        frame.contentDocument.write('<body><p>tiny note</p></body>');
+        frame.contentDocument.close();
+
+        const result = dom.window.eval(__test__.buildRenderAwareExtractorJs({ frames: 'same-origin' }));
+
+        expect(result.diagnostics.includedFrameCount).toBe(0);
+        expect(result.contentHtml).not.toContain('tiny note');
+    });
+
+    it('includes short non-structural iframes in all-same-origin mode', () => {
+        const dom = new JSDOM(`
+          <main>
+            <h1>Main Article</h1>
+            <p>${'Main content '.repeat(30)}</p>
+          </main>
+          <iframe id="status-frame" src="/status.html"></iframe>
+        `, { url: 'https://example.com/main.html', runScripts: 'outside-only' });
+        const frame = dom.window.document.querySelector('iframe');
+        frame.contentDocument.open();
+        frame.contentDocument.write('<body><div>Online: 42°C</div></body>');
+        frame.contentDocument.close();
+
+        const result = dom.window.eval(__test__.buildRenderAwareExtractorJs({ frames: 'all-same-origin' }));
+
+        expect(result.diagnostics.includedFrameCount).toBe(1);
+        expect(result.contentHtml).toContain('Online: 42°C');
     });
 
     it('marks API-like network entries as interesting and ignores static assets', () => {

package/clis/weixin/create-draft.js

@@ -179,13 +179,13 @@ export const createDraftCommand = cli({
     strategy: Strategy.COOKIE,
     browser: true,
     navigateBefore: false,
-    timeoutSeconds: 180,
     args: [
         { name: 'title', required: true, help: '文章标题 (最长64字)' },
         { name: 'content', required: true, positional: true, help: '文章正文' },
         { name: 'author', help: '作者名 (最长8字)' },
         { name: 'cover-image', help: '封面图片路径 (会先上传到正文再设为封面)' },
         { name: 'summary', help: '文章摘要' },
+        { name: 'timeout', type: 'int', required: false, default: 180, help: 'Max seconds for the overall command (default: 180)' },
     ],
     columns: ['status', 'detail'],
 

package/clis/weixin/drafts.js

@@ -12,9 +12,9 @@ export const draftsCommand = cli({
     strategy: Strategy.COOKIE,
     browser: true,
     navigateBefore: false,
-    timeoutSeconds: 60,
     args: [
         { name: 'limit', type: 'int', default: 10, help: '最多显示条数' },
+        { name: 'timeout', type: 'int', required: false, default: 60, help: 'Max seconds for the overall command (default: 60)' },
     ],
     columns: ['Index', 'Title', 'Time'],
 

package/clis/weixin/drafts.test.js

@@ -3,6 +3,7 @@ import { AuthRequiredError, EmptyResultError } from '@jackwener/opencli/errors';
 import { getRegistry } from '@jackwener/opencli/registry';
 import './create-draft.js';
 import './drafts.js';
+import './search.js';
 
 function createPageMock(overrides = {}) {
     return {
@@ -18,7 +19,10 @@ describe('weixin command registration', () => {
         const registry = getRegistry();
         const values = [...registry.values()];
         expect(values.find(c => c.site === 'weixin' && c.name === 'create-draft')).toBeDefined();
-        expect(values.find(c => c.site === 'weixin' && c.name === 'drafts')).toBeDefined();
+        const draftsCommand = values.find(c => c.site === 'weixin' && c.name === 'drafts');
+        expect(draftsCommand).toBeDefined();
+        expect(draftsCommand.args.find((arg) => arg.name === 'timeout')).toMatchObject({ type: 'int', default: 60 });
+        expect(values.find(c => c.site === 'weixin' && c.name === 'search')).toBeDefined();
     });
 });
 

package/clis/weixin/search.js

@@ -0,0 +1,157 @@
+import { ArgumentError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+
+const SOGOU_WEIXIN_DOMAIN = 'weixin.sogou.com';
+const DEFAULT_PAGE = 1;
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 10;
+
+function normalizePositiveInteger(value, name, defaultValue, maxValue) {
+    if (value === undefined || value === null)
+        return defaultValue;
+    const text = String(value).trim();
+    if (!/^\d+$/.test(text)) {
+        throw new ArgumentError(`weixin search --${name} must be a positive integer`, `Pass --${name} as a whole number${maxValue ? ` from 1 to ${maxValue}` : ' greater than 0'}.`);
+    }
+    const parsed = Number(text);
+    if (!Number.isSafeInteger(parsed) || parsed < 1 || (maxValue && parsed > maxValue)) {
+        throw new ArgumentError(`weixin search --${name} is out of range`, `Pass --${name} as a whole number${maxValue ? ` from 1 to ${maxValue}` : ' greater than 0'}.`);
+    }
+    return parsed;
+}
+
+function normalizePage(page) {
+    return normalizePositiveInteger(page, 'page', DEFAULT_PAGE);
+}
+
+function normalizeLimit(limit) {
+    return normalizePositiveInteger(limit, 'limit', DEFAULT_LIMIT, MAX_LIMIT);
+}
+
+function buildSearchUrl(query, pageNo) {
+    const searchUrl = new URL('https://weixin.sogou.com/weixin');
+    searchUrl.searchParams.set('query', query);
+    searchUrl.searchParams.set('type', '2');
+    searchUrl.searchParams.set('page', String(pageNo));
+    searchUrl.searchParams.set('ie', 'utf8');
+    return searchUrl.toString();
+}
+
+function buildExtractSearchResultsEvaluate() {
+    return String.raw`(() => {
+        const clean = (value) => {
+            return (value || '')
+                .replace(/\s+/g, ' ')
+                .replace(/<!--red_beg-->|<!--red_end-->/g, '')
+                .replace(/document\.write\(timeConvert\('\d+'\)\)/g, '')
+                .trim();
+        };
+
+        const absolutize = (href) => {
+            if (!href) return '';
+            try {
+                return new URL(href, window.location.origin).toString();
+            } catch {
+                return href;
+            }
+        };
+
+        const bodyText = clean(document.body && document.body.innerText);
+        const blocked = /验证码|安全验证|异常访问|访问过于频繁|请输入验证码/.test(bodyText);
+        const empty = /没有找到相关的微信文章|未找到相关|暂无相关|没有找到/.test(bodyText)
+            || Boolean(document.querySelector('.no-result, .no_result, .s-noresult'));
+        const cards = Array.from(document.querySelectorAll('.news-list li'));
+        const extracted = cards.map((item) => {
+            const linkEl = item.querySelector('h3 a[href]');
+            const summaryEl = item.querySelector('p.txt-info');
+            const timeEl = item.querySelector('.s-p .s2');
+            return {
+                title: clean(linkEl && linkEl.textContent),
+                url: absolutize(linkEl && linkEl.getAttribute('href')),
+                summary: clean(summaryEl && summaryEl.textContent),
+                publish_time: clean(timeEl && timeEl.textContent),
+            };
+        });
+        const rows = extracted.filter((row) => row.title && row.url);
+
+        return {
+            blocked,
+            empty,
+            cardCount: cards.length,
+            invalidCount: extracted.length - rows.length,
+            rows,
+        };
+    })()`;
+}
+
+cli({
+    site: 'weixin',
+    name: 'search',
+    access: 'read',
+    description: '使用搜狗微信搜索公众号文章；如需导出正文 Markdown，请使用 weixin download 处理公众号文章链接',
+    domain: SOGOU_WEIXIN_DOMAIN,
+    strategy: Strategy.PUBLIC,
+    browser: true,
+    args: [
+        { name: 'query', positional: true, required: true, help: '搜索关键词；如需正文 Markdown，请使用 weixin download 处理公众号文章链接' },
+        { name: 'page', type: 'int', default: 1, help: '结果页码，从 1 开始' },
+        { name: 'limit', type: 'int', default: 10, help: '返回条数，最大 10' },
+    ],
+    columns: ['rank', 'page', 'title', 'url', 'summary', 'publish_time'],
+    func: async (page, kwargs) => {
+        const query = String(kwargs.query ?? '').trim();
+        if (!query) {
+            throw new ArgumentError('A search query is required.', 'Pass a non-empty keyword to search Weixin articles via Sogou.');
+        }
+
+        const pageNo = normalizePage(kwargs.page);
+        const limit = normalizeLimit(kwargs.limit);
+        const searchUrl = buildSearchUrl(query, pageNo);
+
+        let payload;
+        try {
+            await page.goto(searchUrl);
+            await page.wait(2);
+            payload = await page.evaluate(buildExtractSearchResultsEvaluate());
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new CommandExecutionError('weixin search failed while loading Sogou results', detail);
+        }
+
+        if (!payload || typeof payload !== 'object' || !Array.isArray(payload.rows)) {
+            throw new CommandExecutionError('weixin search returned an unreadable browser payload', 'Sogou Weixin may have changed its result page structure.');
+        }
+        if (payload.blocked) {
+            throw new CommandExecutionError('Sogou Weixin blocked this search request', 'Open weixin.sogou.com in Chrome and complete any verification before retrying.');
+        }
+        if (payload.invalidCount > 0) {
+            throw new CommandExecutionError('Sogou Weixin returned article cards without required title or URL', 'The result page structure may have changed; refusing to return a partial result set.');
+        }
+
+        const rows = payload.rows;
+        if (rows.length === 0 && payload.empty) {
+            throw new EmptyResultError('weixin search', 'Try a different keyword or a different page number.');
+        }
+        if (rows.length === 0) {
+            throw new CommandExecutionError('weixin search did not expose article result cards', 'Sogou Weixin may have changed its selectors or returned a transient shell page.');
+        }
+
+        return rows.slice(0, limit).map((row, index) => ({
+            rank: (pageNo - 1) * 10 + index + 1,
+            page: pageNo,
+            title: row.title,
+            url: row.url,
+            summary: row.summary,
+            publish_time: row.publish_time,
+        }));
+    },
+});
+
+export const __test__ = {
+    MAX_LIMIT,
+    normalizePage,
+    normalizeLimit,
+    buildSearchUrl,
+    buildExtractSearchResultsEvaluate,
+};