@jackwener/opencli 1.7.22 → 1.8.1

package/clis/zhihu/question.test.js

@@ -12,13 +12,15 @@ describe('zhihu question', () => {
             // user-requested `--limit 3` is enforced by the dedup loop's
             // `answers.length >= answerLimit` break, not by the fetch URL.
             expect(js).toContain('questions/2021881398772981878/answers?limit=20');
+            expect(js).toContain('content,url,voteup_count');
             expect(js).toContain("credentials: 'include'");
             return {
                 data: [
                     {
+                        id: '2036567240334653053',
                         author: { name: 'alice' },
                         voteup_count: 12,
-                        content: 'Hello Zhihu',
+                        content: '<p>&#34;Hello&#34; &#x26; Zhihu</p>',
                     },
                 ],
             };
@@ -27,22 +29,95 @@ describe('zhihu question', () => {
         await expect(cmd.func(page, { id: '2021881398772981878', limit: 3 })).resolves.toEqual([
             {
                 rank: 1,
+                id: '2036567240334653053',
                 author: 'alice',
                 votes: 12,
-                content: 'Hello Zhihu',
+                url: 'https://www.zhihu.com/question/2021881398772981878/answer/2036567240334653053',
+                content: '"Hello" & Zhihu',
             },
         ]);
         expect(goto).toHaveBeenCalledWith('https://www.zhihu.com/question/2021881398772981878');
         expect(evaluate).toHaveBeenCalledTimes(1);
     });
+    it('prefers the answer URL when extracting large answer IDs', async () => {
+        const cmd = getRegistry().get('zhihu/question');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({
+                data: [
+                    {
+                        id: 2036567240334653000,
+                        url: 'https://www.zhihu.com/api/v4/answers/2036567240334653053',
+                        author: { name: 'alice' },
+                        voteup_count: 12,
+                        content: '<p>precise id</p>',
+                    },
+                ],
+                paging: { is_end: true },
+            }),
+        };
+        await expect(cmd.func(page, { id: '2021881398772981878', limit: 1 })).resolves.toEqual([
+            {
+                rank: 1,
+                id: '2036567240334653053',
+                author: 'alice',
+                votes: 12,
+                url: 'https://www.zhihu.com/question/2021881398772981878/answer/2036567240334653053',
+                content: 'precise id',
+            },
+        ]);
+    });
+    it('deduplicates paginated answers by precise answer URL identity', async () => {
+        const cmd = getRegistry().get('zhihu/question');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({
+                data: [
+                    {
+                        id: 2036567240334653000,
+                        url: 'https://www.zhihu.com/api/v4/answers/2036567240334653053',
+                        author: { name: 'alice' },
+                        voteup_count: 12,
+                        content: '<p>first precise id</p>',
+                    },
+                    {
+                        id: 2036567240334653000,
+                        url: 'https://www.zhihu.com/api/v4/answers/2036567240334653054',
+                        author: { name: 'bob' },
+                        voteup_count: 8,
+                        content: '<p>second precise id</p>',
+                    },
+                ],
+                paging: { is_end: true },
+            }),
+        };
+        await expect(cmd.func(page, { id: '2021881398772981878', limit: 2 })).resolves.toEqual([
+            {
+                rank: 1,
+                id: '2036567240334653053',
+                author: 'alice',
+                votes: 12,
+                url: 'https://www.zhihu.com/question/2021881398772981878/answer/2036567240334653053',
+                content: 'first precise id',
+            },
+            {
+                rank: 2,
+                id: '2036567240334653054',
+                author: 'bob',
+                votes: 8,
+                url: 'https://www.zhihu.com/question/2021881398772981878/answer/2036567240334653054',
+                content: 'second precise id',
+            },
+        ]);
+    });
     it('follows paging.next until the requested limit is reached', async () => {
         const cmd = getRegistry().get('zhihu/question');
         const goto = vi.fn().mockResolvedValue(undefined);
         const evaluate = vi.fn()
             .mockResolvedValueOnce({
                 data: [
-                    { id: 'a1', author: { name: 'alice' }, voteup_count: 12, content: '<p>first</p>' },
-                    { id: 'a2', author: { name: 'bob' }, voteup_count: 8, content: '<p>second</p>' },
+                    { id: '101', author: { name: 'alice' }, voteup_count: 12, content: '<p>first</p>' },
+                    { id: '102', author: { name: 'bob' }, voteup_count: 8, content: '<p>second</p>' },
                 ],
                 paging: {
                     is_end: false,
@@ -51,16 +126,16 @@ describe('zhihu question', () => {
             })
             .mockResolvedValueOnce({
                 data: [
-                    { id: 'a2', author: { name: 'bob duplicate' }, voteup_count: 8, content: '<p>duplicate</p>' },
-                    { id: 'a3', author: { name: 'carol' }, voteup_count: 5, content: '<p>third</p>' },
+                    { id: '102', author: { name: 'bob duplicate' }, voteup_count: 8, content: '<p>duplicate</p>' },
+                    { id: '103', author: { name: 'carol' }, voteup_count: 5, content: '<p>third</p>' },
                 ],
                 paging: { is_end: true },
             });
         const page = { goto, evaluate };
         await expect(cmd.func(page, { id: '2021881398772981878', limit: 3 })).resolves.toEqual([
-            { rank: 1, author: 'alice', votes: 12, content: 'first' },
-            { rank: 2, author: 'bob', votes: 8, content: 'second' },
-            { rank: 3, author: 'carol', votes: 5, content: 'third' },
+            { rank: 1, id: '101', author: 'alice', votes: 12, url: 'https://www.zhihu.com/question/2021881398772981878/answer/101', content: 'first' },
+            { rank: 2, id: '102', author: 'bob', votes: 8, url: 'https://www.zhihu.com/question/2021881398772981878/answer/102', content: 'second' },
+            { rank: 3, id: '103', author: 'carol', votes: 5, url: 'https://www.zhihu.com/question/2021881398772981878/answer/103', content: 'third' },
         ]);
         expect(evaluate).toHaveBeenCalledTimes(2);
         expect(evaluate.mock.calls[1][0]).toContain('offset=80');
@@ -73,7 +148,7 @@ describe('zhihu question', () => {
             return {
                 data: [
                     {
-                        id: 'a1',
+                        id: '101',
                         author: { name: 'newest' },
                         voteup_count: 1,
                         content: '<p>created order</p>',
@@ -84,10 +159,37 @@ describe('zhihu question', () => {
         });
         const page = { goto, evaluate };
         await expect(cmd.func(page, { id: '2021881398772981878', limit: 1, sort: 'created' })).resolves.toEqual([
-            { rank: 1, author: 'newest', votes: 1, content: 'created order' },
+            { rank: 1, id: '101', author: 'newest', votes: 1, url: 'https://www.zhihu.com/question/2021881398772981878/answer/101', content: 'created order' },
         ]);
         expect(goto).toHaveBeenCalledWith('https://www.zhihu.com/question/2021881398772981878/answers/updated');
     });
+    it('does not emit a fake answer URL for malformed answer IDs', async () => {
+        const cmd = getRegistry().get('zhihu/question');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({
+                data: [
+                    {
+                        id: 'not-an-id',
+                        author: { name: 'alice' },
+                        voteup_count: 12,
+                        content: '<p>malformed id</p>',
+                    },
+                ],
+                paging: { is_end: true },
+            }),
+        };
+        await expect(cmd.func(page, { id: '2021881398772981878', limit: 1 })).resolves.toEqual([
+            {
+                rank: 1,
+                id: '',
+                author: 'alice',
+                votes: 12,
+                url: '',
+                content: 'malformed id',
+            },
+        ]);
+    });
     it('maps auth-like answer failures to AuthRequiredError', async () => {
         const cmd = getRegistry().get('zhihu/question');
         const page = {

package/clis/zhihu/search.js

@@ -1,54 +1,206 @@
-import { cli } from '@jackwener/opencli/registry';
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import { stripHtml } from './text.js';
+
+function itemKey(item) {
+    const obj = item.object || {};
+    if (obj.id != null) return `${obj.type || ''}:${obj.id}`;
+    return null;
+}
+
+function itemUrl(obj) {
+    const id = obj.id == null ? '' : String(obj.id);
+    if (obj.type === 'answer') {
+        const questionId = obj.question?.id == null ? '' : String(obj.question.id);
+        return questionId && id ? `https://www.zhihu.com/question/${questionId}/answer/${id}` : '';
+    }
+    if (obj.type === 'article') {
+        return id ? `https://zhuanlan.zhihu.com/p/${id}` : '';
+    }
+    if (obj.type === 'question') {
+        return id ? `https://www.zhihu.com/question/${id}` : '';
+    }
+    return '';
+}
+
+function normalizeSearchUrl(url) {
+    if (typeof url !== 'string' || !url) return '';
+    try {
+        const parsed = new URL(url);
+        if (parsed.hostname === 'api.zhihu.com' && parsed.pathname === '/search_v3') {
+            return `https://www.zhihu.com/api/v4/search_v3${parsed.search}`;
+        }
+        if (parsed.hostname === 'www.zhihu.com' && parsed.pathname === '/api/v4/search_v3') {
+            return parsed.toString();
+        }
+    } catch {
+        return '';
+    }
+    return '';
+}
+
+const MAX_LIMIT = 1000;
+const PAGE_SIZE = 20;
+const TYPES = ['all', 'answer', 'article', 'question'];
+
+function parseLimit(value) {
+    const limit = Number(value ?? 10);
+    if (!Number.isInteger(limit) || limit <= 0 || limit > MAX_LIMIT) {
+        throw new ArgumentError(`zhihu search --limit must be a positive integer no greater than ${MAX_LIMIT}`, 'Use a normal-sized limit to avoid slow requests or Zhihu risk controls');
+    }
+    return limit;
+}
+
+function requireQuery(value) {
+    const query = String(value || '').trim();
+    if (!query) {
+        throw new ArgumentError('zhihu search query must not be empty', 'Example: opencli zhihu search codex');
+    }
+    return query;
+}
+
+function requireType(value) {
+    const type = String(value || 'all');
+    if (!TYPES.includes(type)) {
+        throw new ArgumentError(`zhihu search --type must be one of: ${TYPES.join(', ')}`, 'Example: opencli zhihu search codex --type answer');
+    }
+    return type;
+}
+
+function unwrapEvaluateResult(payload) {
+    if (payload && typeof payload === 'object' && 'data' in payload && 'session' in payload) return payload.data;
+    return payload;
+}
+
+function requireSearchPayload(data, url) {
+    const payload = unwrapEvaluateResult(data);
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        throw new CommandExecutionError('Zhihu search returned malformed payload');
+    }
+    if (payload.__httpError) {
+        const status = payload.__httpError;
+        if (status === 401 || status === 403) {
+            throw new AuthRequiredError('www.zhihu.com', 'Failed to fetch search results from Zhihu');
+        }
+        throw new CommandExecutionError(`Zhihu search request failed${status ? ` (HTTP ${status})` : ''}`, 'Try again later or rerun with -v for more detail');
+    }
+    if (payload.__fetchError) {
+        throw new CommandExecutionError('Zhihu search request failed', String(payload.__fetchError));
+    }
+    if (!Array.isArray(payload.data)) {
+        throw new CommandExecutionError('Zhihu search returned malformed data list', `URL: ${url}`);
+    }
+    if (!payload.paging || typeof payload.paging !== 'object') {
+        throw new CommandExecutionError('Zhihu search returned malformed paging data', `URL: ${url}`);
+    }
+    return payload;
+}
+
+function normalizeResultItem(item) {
+    if (!item || typeof item !== 'object' || item.type !== 'search_result' || !item.object || typeof item.object !== 'object') {
+        return null;
+    }
+    const obj = item.object;
+    if (obj.type !== 'answer' && obj.type !== 'article' && obj.type !== 'question') return null;
+    const key = itemKey(item);
+    const url = itemUrl(obj);
+    const question = obj.question || {};
+    const title = stripHtml(obj.title || question.name || question.title || '');
+    if (!key || !url || !title) {
+        throw new CommandExecutionError('Zhihu search returned malformed result row identity');
+    }
+    return {
+        item,
+        key,
+        row: {
+            title,
+            type: obj.type,
+            author: obj.author?.name || '',
+            votes: obj.voteup_count || 0,
+            url,
+        },
+    };
+}
+
 cli({
     site: 'zhihu',
     name: 'search',
     access: 'read',
     description: '知乎搜索',
     domain: 'www.zhihu.com',
+    strategy: Strategy.COOKIE,
     args: [
         { name: 'query', required: true, positional: true, help: 'Search query' },
-        { name: 'limit', type: 'int', default: 10, help: 'Number of results' },
+        { name: 'limit', type: 'int', default: 10, help: 'Number of results (max 1000; use normal-sized requests)' },
+        { name: 'type', default: 'all', choices: TYPES, help: 'Result type: all, answer, article, or question' },
     ],
     columns: ['rank', 'title', 'type', 'author', 'votes', 'url'],
-    pipeline: [
-        { navigate: 'https://www.zhihu.com' },
-        { evaluate: `(async () => {
-  const strip = (html) => (html || '').replace(/<[^>]+>/g, '').replace(/&nbsp;/g, ' ').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&').replace(/<em>/g, '').replace(/<\\/em>/g, '').trim();
-  const keyword = \${{ args.query | json }};
-  const limit = \${{ args.limit }};
-  var fetchLimit = Math.max(limit * 3, 30);
-  const res = await fetch('https://www.zhihu.com/api/v4/search_v3?q=' + encodeURIComponent(keyword) + '&t=general&offset=0&limit=' + fetchLimit, {
-    credentials: 'include'
-  });
-  const d = await res.json();
-  return (d?.data || [])
-    .filter(item => item.object && (item.object.type === 'answer' || item.object.type === 'article' || item.object.type === 'question'))
-    .map(item => {
-      const obj = item.object || {};
-      const q = obj.question || {};
-      return {
-        type: obj.type,
-        title: strip(obj.title || q.name || ''),
-        excerpt: strip(obj.excerpt || '').substring(0, 100),
-        author: obj.author?.name || '',
-        votes: obj.voteup_count || 0,
-        url: obj.type === 'answer'
-          ? 'https://www.zhihu.com/question/' + q.id + '/answer/' + obj.id
-          : obj.type === 'article'
-          ? 'https://zhuanlan.zhihu.com/p/' + obj.id
-          : 'https://www.zhihu.com/question/' + obj.id,
-      };
-    });
-})()
-` },
-        { map: {
-                rank: '${{ index + 1 }}',
-                title: '${{ item.title }}',
-                type: '${{ item.type }}',
-                author: '${{ item.author }}',
-                votes: '${{ item.votes }}',
-                url: '${{ item.url }}',
-            } },
-        { limit: '${{ args.limit }}' },
-    ],
+    func: async (page, kwargs) => {
+        const query = requireQuery(kwargs.query);
+        const resultLimit = parseLimit(kwargs.limit);
+        const type = requireType(kwargs.type);
+        await page.goto('https://www.zhihu.com');
+        let url = 'https://www.zhihu.com/api/v4/search_v3'
+            + `?q=${encodeURIComponent(query)}&t=general&offset=0&limit=${PAGE_SIZE}`;
+        const results = [];
+        const seen = new Set();
+        const visited = new Set();
+        while (url && results.length < resultLimit && !visited.has(url)) {
+            visited.add(url);
+            const data = requireSearchPayload(await page.evaluate(`
+      (async () => {
+        try {
+          const r = await fetch(${JSON.stringify(url)}, { credentials: 'include' });
+          if (!r.ok) return { __httpError: r.status };
+          return await r.json();
+        } catch (err) {
+          return { __fetchError: err?.message || String(err) };
+        }
+      })()
+    `), url);
+            for (const item of data.data) {
+                const rawType = item?.object?.type;
+                if (type !== 'all' && rawType && rawType !== type) continue;
+                const normalized = normalizeResultItem(item);
+                if (!normalized) continue;
+                if (type !== 'all' && normalized.row.type !== type) continue;
+                if (seen.has(normalized.key)) continue;
+                seen.add(normalized.key);
+                results.push(normalized.row);
+                if (results.length >= resultLimit) break;
+            }
+            if (results.length >= resultLimit) break;
+            if (data.paging?.is_end) break;
+            const next = normalizeSearchUrl(data.paging?.next);
+            if (!next) {
+                throw new CommandExecutionError('Zhihu search pagination returned malformed next URL');
+            }
+            if (visited.has(next)) {
+                throw new CommandExecutionError('Zhihu search pagination returned a repeated next URL');
+            }
+            url = next;
+        }
+        if (results.length === 0) {
+            throw new EmptyResultError('zhihu search', `No ${type === 'all' ? '' : `${type} `}results found for "${query}"`);
+        }
+        return results.map((row, i) => {
+            return {
+                rank: i + 1,
+                ...row,
+            };
+        });
+    },
 });
+
+export const __test__ = {
+    stripHtml,
+    itemKey,
+    itemUrl,
+    normalizeSearchUrl,
+    parseLimit,
+    requireQuery,
+    requireType,
+    unwrapEvaluateResult,
+    requireSearchPayload,
+    normalizeResultItem,
+};

package/clis/zhihu/search.test.js

@@ -0,0 +1,198 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './search.js';
+
+const {
+    normalizeSearchUrl,
+    requireSearchPayload,
+    normalizeResultItem,
+} = await import('./search.js').then((m) => m.__test__);
+
+describe('zhihu search', () => {
+    it('returns search_result entries from the Zhihu search API', async () => {
+        const cmd = getRegistry().get('zhihu/search');
+        expect(cmd?.func).toBeTypeOf('function');
+        const goto = vi.fn().mockResolvedValue(undefined);
+        const evaluate = vi.fn().mockImplementation(async (js) => {
+            expect(js).toContain('/api/v4/search_v3');
+            expect(js).toContain('limit=20');
+            expect(js).toContain("credentials: 'include'");
+            return {
+                data: [
+                    {
+                        type: 'hot_timing',
+                        object: {
+                            type: 'hot_timing',
+                            content_items: [
+                                { object: { id: 'discussion-1', type: 'article', title: 'discussion' } },
+                            ],
+                        },
+                    },
+                    {
+                        type: 'search_result',
+                        object: {
+                            id: 'a1',
+                            type: 'answer',
+                            author: { name: 'alice' },
+                            voteup_count: 12,
+                            question: { id: 'q1', name: '<em>Codex</em> &#34;question&#34;' },
+                        },
+                    },
+                    {
+                        type: 'search_result',
+                        object: {
+                            id: 'p1',
+                            type: 'article',
+                            title: '<em>Codex</em> article',
+                            author: { name: 'bob' },
+                            voteup_count: 7,
+                        },
+                    },
+                ],
+                paging: { is_end: true },
+            };
+        });
+        const page = { goto, evaluate };
+        await expect(cmd.func(page, { query: 'codex', limit: 2 })).resolves.toEqual([
+            {
+                rank: 1,
+                title: 'Codex "question"',
+                type: 'answer',
+                author: 'alice',
+                votes: 12,
+                url: 'https://www.zhihu.com/question/q1/answer/a1',
+            },
+            {
+                rank: 2,
+                title: 'Codex article',
+                type: 'article',
+                author: 'bob',
+                votes: 7,
+                url: 'https://zhuanlan.zhihu.com/p/p1',
+            },
+        ]);
+        expect(goto).toHaveBeenCalledWith('https://www.zhihu.com');
+        expect(evaluate).toHaveBeenCalledTimes(1);
+    });
+
+    it('follows paging.next until the requested limit is reached', async () => {
+        const cmd = getRegistry().get('zhihu/search');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn()
+                .mockResolvedValueOnce({
+                    data: [
+                        { type: 'search_result', object: { id: 'a1', type: 'answer', question: { id: 'q1', name: 'first' } } },
+                        { type: 'search_result', object: { id: 'a2', type: 'answer', question: { id: 'q2', name: 'second' } } },
+                    ],
+                    paging: {
+                        is_end: false,
+                        next: 'https://api.zhihu.com/search_v3?offset=20&q=codex',
+                    },
+                })
+                .mockResolvedValueOnce({
+                    data: [
+                        { type: 'search_result', object: { id: 'a2', type: 'answer', question: { id: 'q2', name: 'duplicate' } } },
+                        { type: 'search_result', object: { id: 'q3', type: 'question', title: 'third' } },
+                    ],
+                    paging: { is_end: true },
+                }),
+        };
+        await expect(cmd.func(page, { query: 'codex', limit: 3 })).resolves.toEqual([
+            { rank: 1, title: 'first', type: 'answer', author: '', votes: 0, url: 'https://www.zhihu.com/question/q1/answer/a1' },
+            { rank: 2, title: 'second', type: 'answer', author: '', votes: 0, url: 'https://www.zhihu.com/question/q2/answer/a2' },
+            { rank: 3, title: 'third', type: 'question', author: '', votes: 0, url: 'https://www.zhihu.com/question/q3' },
+        ]);
+        expect(page.evaluate).toHaveBeenCalledTimes(2);
+        expect(page.evaluate.mock.calls[1][0]).toContain('https://www.zhihu.com/api/v4/search_v3?offset=20&q=codex');
+    });
+
+    it('filters by result type', async () => {
+        const cmd = getRegistry().get('zhihu/search');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({
+                data: [
+                    { type: 'search_result', object: { id: 'a1', type: 'answer' } },
+                    { type: 'search_result', object: { id: 'p1', type: 'article', title: 'article' } },
+                ],
+                paging: { is_end: true },
+            }),
+        };
+        await expect(cmd.func(page, { query: 'codex', limit: 2, type: 'article' })).resolves.toEqual([
+            { rank: 1, title: 'article', type: 'article', author: '', votes: 0, url: 'https://zhuanlan.zhihu.com/p/p1' },
+        ]);
+    });
+
+    it('maps auth-like failures to AuthRequiredError', async () => {
+        const cmd = getRegistry().get('zhihu/search');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({ __httpError: 403 }),
+        };
+        await expect(cmd.func(page, { query: 'codex', limit: 3 })).rejects.toBeInstanceOf(AuthRequiredError);
+    });
+
+    it('preserves non-auth fetch failures as typed execution errors', async () => {
+        const cmd = getRegistry().get('zhihu/search');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({ __httpError: 500 }),
+        };
+        await expect(cmd.func(page, { query: 'codex', limit: 3 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('rejects invalid input before navigation', async () => {
+        const cmd = getRegistry().get('zhihu/search');
+        const page = { goto: vi.fn(), evaluate: vi.fn() };
+        await expect(cmd.func(page, { query: '', limit: 1 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(cmd.func(page, { query: 'codex', limit: 0 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(cmd.func(page, { query: 'codex', limit: 1001 })).rejects.toBeInstanceOf(ArgumentError);
+        await expect(cmd.func(page, { query: 'codex', limit: 1, type: 'video' })).rejects.toBeInstanceOf(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+        expect(page.evaluate).not.toHaveBeenCalled();
+    });
+
+    it('unwraps Browser Bridge envelopes and fails typed on malformed payloads', () => {
+        const payload = { data: [], paging: { is_end: true } };
+        expect(requireSearchPayload({ session: {}, data: payload }, 'https://www.zhihu.com/api/v4/search_v3')).toBe(payload);
+        expect(() => requireSearchPayload(null, 'url')).toThrow(CommandExecutionError);
+        expect(() => requireSearchPayload({ data: null, paging: { is_end: true } }, 'url')).toThrow(CommandExecutionError);
+        expect(() => requireSearchPayload({ data: [], paging: null }, 'url')).toThrow(CommandExecutionError);
+        expect(() => requireSearchPayload({ __fetchError: 'network down' }, 'url')).toThrow(CommandExecutionError);
+    });
+
+    it('fails typed on malformed supported result rows instead of emitting blank identity rows', () => {
+        expect(() => normalizeResultItem({ type: 'search_result', object: { type: 'answer', id: 'a1', question: { name: 'missing question id' } } }))
+            .toThrow(CommandExecutionError);
+        expect(() => normalizeResultItem({ type: 'search_result', object: { type: 'article', id: 'p1' } }))
+            .toThrow(CommandExecutionError);
+        expect(normalizeResultItem({ type: 'hot_timing', object: { type: 'article', id: 'p1' } })).toBe(null);
+    });
+
+    it('rejects malformed pagination next URLs and reports valid empty result separately', async () => {
+        expect(normalizeSearchUrl('https://api.zhihu.com/search_v3?offset=20&q=codex'))
+            .toBe('https://www.zhihu.com/api/v4/search_v3?offset=20&q=codex');
+        expect(normalizeSearchUrl('https://evil.example/search_v3?offset=20')).toBe('');
+
+        const cmd = getRegistry().get('zhihu/search');
+        const malformedNextPage = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({
+                data: [],
+                paging: { is_end: false, next: 'https://evil.example/search_v3?offset=20' },
+            }),
+        };
+        await expect(cmd.func(malformedNextPage, { query: 'codex', limit: 3 }))
+            .rejects.toBeInstanceOf(CommandExecutionError);
+
+        const emptyPage = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({ data: [], paging: { is_end: true } }),
+        };
+        await expect(cmd.func(emptyPage, { query: 'codex', limit: 3 }))
+            .rejects.toBeInstanceOf(EmptyResultError);
+    });
+});

package/clis/zhihu/text.js

@@ -0,0 +1,29 @@
+function decodeEntity(codePoint) {
+    return Number.isInteger(codePoint) && codePoint >= 0 && codePoint <= 0x10FFFF
+        ? String.fromCodePoint(codePoint)
+        : null;
+}
+
+export function stripHtml(html, { preserveBlocks = false } = {}) {
+    if (!html) return '';
+    let text = String(html);
+    if (preserveBlocks) {
+        text = text
+            .replace(/<br\s*\/?\s*>/gi, '\n')
+            .replace(/<\/(?:p|div|h[1-6]|li|blockquote)>/gi, '\n\n');
+    }
+    return text
+        .replace(/<[^>]+>/g, '')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&amp;/g, '&')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&#(\d+);/g, (entity, value) => decodeEntity(Number(value)) ?? entity)
+        .replace(/&#x([0-9a-f]+);/gi, (entity, value) => decodeEntity(Number.parseInt(value, 16)) ?? entity)
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+
+export const __test__ = { decodeEntity };