@jackwener/opencli 1.7.18 → 1.7.19

package/clis/zhihu/answer-detail.test.js

@@ -0,0 +1,330 @@
+import { describe, expect, it, vi } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import { ArgumentError, AuthRequiredError, CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
+import './answer-detail.js';
+import { __test__ as helpers } from './answer-detail.js';
+
+describe('zhihu answer-detail', () => {
+    it('registers as a cookie read command', () => {
+        const cmd = getRegistry().get('zhihu/answer-detail');
+        expect(cmd).toBeDefined();
+        expect(cmd.access).toBe('read');
+        expect(cmd.strategy).toBe('cookie');
+    });
+
+    it('fetches a single answer by numeric id and returns one row', async () => {
+        const cmd = getRegistry().get('zhihu/answer-detail');
+        const goto = vi.fn().mockResolvedValue(undefined);
+        const evaluate = vi.fn().mockImplementation(async (js) => {
+            // The adapter must call the `/api/v4/answers/<id>` endpoint
+            // (not the question→answers listing) and request the rich
+            // include set so the row carries content + counts + question.
+            expect(js).toContain('/api/v4/answers/1937205528846655537?include=content');
+            expect(js).toContain('voteup_count');
+            expect(js).toContain('comment_count');
+            expect(js).toContain('question');
+            expect(js).toContain("credentials: 'include'");
+            return {
+                // Real Zhihu API returns `id` as a JSON number, which
+                // *loses precision* in browser JSON.parse for ids
+                // above 2^53 (Number.MAX_SAFE_INTEGER). The adapter
+                // must not trust this field for the canonical id —
+                // it must anchor the row id to the parsed input
+                // instead. We pass a deliberately wrong value below
+                // to lock that contract in.
+                id: 0,
+                author: { name: 'Ricky' },
+                voteup_count: 1234,
+                comment_count: 56,
+                created_time: 1700000000,
+                updated_time: 1700001000,
+                content: '<p>这是<strong>第一段</strong></p><br/><p>第二段。</p>',
+                question: { id: 630517537, title: '回想自己的人生阅历，你最想教给孩子们的一个道理是什么？' },
+            };
+        });
+        const page = { goto, evaluate };
+        const rows = await cmd.func(page, { id: '1937205528846655537', 'max-content': 0 });
+        expect(rows).toHaveLength(1);
+        expect(rows[0]).toMatchObject({
+            id: '1937205528846655537',
+            author: 'Ricky',
+            votes: 1234,
+            comments: 56,
+            question_id: '630517537',
+            question_title: '回想自己的人生阅历，你最想教给孩子们的一个道理是什么？',
+            url: 'https://www.zhihu.com/question/630517537/answer/1937205528846655537',
+            created_at: '2023-11-14T22:13:20.000Z',
+            updated_at: '2023-11-14T22:30:00.000Z',
+        });
+        // Block-level tags should become real newlines, not be collapsed flat.
+        expect(rows[0].content).toBe('这是第一段\n\n第二段。');
+        expect(goto).toHaveBeenCalledWith('https://www.zhihu.com/answer/1937205528846655537');
+    });
+
+    it('accepts a full Zhihu answer URL as id, preserving full id precision', async () => {
+        const cmd = getRegistry().get('zhihu/answer-detail');
+        const evaluate = vi.fn().mockResolvedValue({
+            // Same precision-loss trap as above: `data.id` from the
+            // real API would round to `1937205528846655500`. Pass a
+            // wrong value here to assert the adapter ignores it and
+            // anchors to the parsed URL instead.
+            id: 0,
+            author: { name: 'Ricky' },
+            voteup_count: 1,
+            comment_count: 0,
+            content: '<p>hello</p>',
+            // The input question id is the string-safe source of truth
+            // when API JSON numeric ids have already lost precision.
+            question: { id: 2021881398772981800, title: 'Q' },
+        });
+        const page = { goto: vi.fn().mockResolvedValue(undefined), evaluate };
+        const rows = await cmd.func(page, {
+            id: 'https://www.zhihu.com/question/2021881398772981878/answer/1937205528846655537',
+            'max-content': 0,
+        });
+        expect(rows[0].id).toBe('1937205528846655537');
+        expect(rows[0].question_id).toBe('2021881398772981878');
+        expect(rows[0].url).toBe('https://www.zhihu.com/question/2021881398772981878/answer/1937205528846655537');
+        expect(evaluate.mock.calls[0][0]).toContain('/api/v4/answers/1937205528846655537?');
+    });
+
+    it('accepts the typed-target form answer:<qid>:<aid>', async () => {
+        const cmd = getRegistry().get('zhihu/answer-detail');
+        const evaluate = vi.fn().mockResolvedValue({
+            id: 999,
+            author: { name: 'bob' },
+            voteup_count: 0,
+            comment_count: 0,
+            content: '<p>x</p>',
+            question: { id: 0, title: 'Q' },
+        });
+        const page = { goto: vi.fn().mockResolvedValue(undefined), evaluate };
+        const rows = await cmd.func(page, { id: 'answer:2021881398772981878:999', 'max-content': 0 });
+        expect(rows[0].id).toBe('999');
+        expect(rows[0].question_id).toBe('2021881398772981878');
+        expect(evaluate.mock.calls[0][0]).toContain('/api/v4/answers/999?');
+    });
+
+    it('uses the redirected canonical URL as question id source for bare answer ids', async () => {
+        const cmd = getRegistry().get('zhihu/answer-detail');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            getCurrentUrl: vi.fn().mockResolvedValue('https://www.zhihu.com/question/2021881398772981878/answer/999'),
+            evaluate: vi.fn().mockResolvedValue({
+                id: 999,
+                author: { name: 'bob' },
+                voteup_count: 0,
+                comment_count: 0,
+                content: '<p>x</p>',
+                question: { id: 2021881398772981800, title: 'Q' },
+            }),
+        };
+        const rows = await cmd.func(page, { id: '999', 'max-content': 0 });
+        expect(rows[0].question_id).toBe('2021881398772981878');
+        expect(rows[0].url).toBe('https://www.zhihu.com/question/2021881398772981878/answer/999');
+    });
+
+    it('uses API question url as a string-safe fallback when the browser URL is unavailable', async () => {
+        const cmd = getRegistry().get('zhihu/answer-detail');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({
+                id: 999,
+                author: { name: 'bob' },
+                voteup_count: 0,
+                comment_count: 0,
+                content: '<p>x</p>',
+                question: {
+                    id: 2021881398772981800,
+                    url: 'https://www.zhihu.com/api/v4/questions/2021881398772981878',
+                    title: 'Q',
+                },
+            }),
+        };
+        const rows = await cmd.func(page, { id: '999', 'max-content': 0 });
+        expect(rows[0].question_id).toBe('2021881398772981878');
+    });
+
+    it('returns the full stripped body when --max-content is 0 (default)', async () => {
+        const cmd = getRegistry().get('zhihu/answer-detail');
+        const longBody = 'x'.repeat(5000);
+        const evaluate = vi.fn().mockResolvedValue({
+            id: 1,
+            author: { name: 'a' },
+            voteup_count: 0,
+            comment_count: 0,
+            content: `<p>${longBody}</p>`,
+            question: { id: 2, title: 'Q' },
+        });
+        const page = { goto: vi.fn().mockResolvedValue(undefined), evaluate };
+        const rows = await cmd.func(page, { id: '1', 'max-content': 0 });
+        expect(rows[0].content.length).toBe(5000);
+    });
+
+    it('respects --max-content as an opt-in cap', async () => {
+        const cmd = getRegistry().get('zhihu/answer-detail');
+        const longBody = 'x'.repeat(5000);
+        const evaluate = vi.fn().mockResolvedValue({
+            id: 1,
+            author: { name: 'a' },
+            voteup_count: 0,
+            comment_count: 0,
+            content: `<p>${longBody}</p>`,
+            question: { id: 2, title: 'Q' },
+        });
+        const page = { goto: vi.fn().mockResolvedValue(undefined), evaluate };
+        const rows = await cmd.func(page, { id: '1', 'max-content': 100 });
+        expect(rows[0].content.length).toBe(100);
+    });
+
+    it('falls back to bare /answer/<id> URL when the response is missing question metadata', async () => {
+        const cmd = getRegistry().get('zhihu/answer-detail');
+        const evaluate = vi.fn().mockResolvedValue({
+            id: 42,
+            author: { name: 'alice' },
+            voteup_count: 0,
+            comment_count: 0,
+            content: '<p>orphan answer</p>',
+            // no `question` field at all
+        });
+        const page = { goto: vi.fn().mockResolvedValue(undefined), evaluate };
+        const rows = await cmd.func(page, { id: '42', 'max-content': 0 });
+        expect(rows[0].question_id).toBe('');
+        expect(rows[0].question_title).toBe('');
+        expect(rows[0].url).toBe('https://www.zhihu.com/answer/42');
+    });
+
+    it('maps 401/403 to AuthRequiredError', async () => {
+        const cmd = getRegistry().get('zhihu/answer-detail');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({ __httpError: 403 }),
+        };
+        await expect(cmd.func(page, { id: '1', 'max-content': 0 })).rejects.toBeInstanceOf(AuthRequiredError);
+    });
+
+    it('maps 404 to EmptyResultError', async () => {
+        const cmd = getRegistry().get('zhihu/answer-detail');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({ __httpError: 404 }),
+        };
+        await expect(cmd.func(page, { id: '1', 'max-content': 0 })).rejects.toBeInstanceOf(EmptyResultError);
+    });
+
+    it('maps other HTTP failures to CommandExecutionError', async () => {
+        const cmd = getRegistry().get('zhihu/answer-detail');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({ __httpError: 500 }),
+        };
+        await expect(cmd.func(page, { id: '1', 'max-content': 0 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('treats a null evaluate response as a fetch error', async () => {
+        const cmd = getRegistry().get('zhihu/answer-detail');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue(null),
+        };
+        await expect(cmd.func(page, { id: '1', 'max-content': 0 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('wraps browser navigation failures as CommandExecutionError', async () => {
+        const cmd = getRegistry().get('zhihu/answer-detail');
+        const page = {
+            goto: vi.fn().mockRejectedValue(new Error('navigation failed')),
+            evaluate: vi.fn(),
+        };
+        await expect(cmd.func(page, { id: '1', 'max-content': 0 })).rejects.toBeInstanceOf(CommandExecutionError);
+        expect(page.evaluate).not.toHaveBeenCalled();
+    });
+
+    it('wraps malformed JSON responses as CommandExecutionError', async () => {
+        const cmd = getRegistry().get('zhihu/answer-detail');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({ __malformedJson: 'Unexpected token <' }),
+        };
+        await expect(cmd.func(page, { id: '1', 'max-content': 0 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('rejects in-band error payloads instead of returning empty success rows', async () => {
+        const cmd = getRegistry().get('zhihu/answer-detail');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({ error: { message: 'not found' } }),
+        };
+        await expect(cmd.func(page, { id: '1', 'max-content': 0 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('rejects payloads missing answer content instead of fabricating a row', async () => {
+        const cmd = getRegistry().get('zhihu/answer-detail');
+        const page = {
+            goto: vi.fn().mockResolvedValue(undefined),
+            evaluate: vi.fn().mockResolvedValue({ id: 1, author: { name: 'ghost' } }),
+        };
+        await expect(cmd.func(page, { id: '1', 'max-content': 0 })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+
+    it('rejects non-numeric answer ids before navigation', async () => {
+        const cmd = getRegistry().get('zhihu/answer-detail');
+        const page = { goto: vi.fn(), evaluate: vi.fn() };
+        await expect(cmd.func(page, { id: "abc'; alert(1); //", 'max-content': 0 })).rejects.toBeInstanceOf(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+        expect(page.evaluate).not.toHaveBeenCalled();
+    });
+
+    it('rejects negative --max-content before navigation', async () => {
+        const cmd = getRegistry().get('zhihu/answer-detail');
+        const page = { goto: vi.fn(), evaluate: vi.fn() };
+        await expect(cmd.func(page, { id: '1', 'max-content': -5 })).rejects.toBeInstanceOf(ArgumentError);
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+
+    it('rejects invalid URL identities before navigation', async () => {
+        const cmd = getRegistry().get('zhihu/answer-detail');
+        const page = { goto: vi.fn(), evaluate: vi.fn() };
+        for (const id of [
+            'https://example.com/foo/bar',
+            'http://www.zhihu.com/question/10/answer/123',
+            'https://www.zhihu.com/question/10/answer/123/extra',
+            'https://www.zhihu.com.evil.com/question/10/answer/123',
+            'https://user:pass@www.zhihu.com/question/10/answer/123',
+        ]) {
+            await expect(cmd.func(page, { id, 'max-content': 0 })).rejects.toBeInstanceOf(ArgumentError);
+        }
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+});
+
+describe('zhihu answer-detail helpers', () => {
+    it('stripHtml drops tags and decodes common entities', () => {
+        const out = helpers.stripHtml('<p>hi&nbsp;there &amp; you</p><p>second</p>');
+        expect(out).toBe('hi there & you\n\nsecond');
+    });
+
+    it('stripHtml maps <br> to single newline', () => {
+        expect(helpers.stripHtml('a<br>b<br/>c')).toBe('a\nb\nc');
+    });
+
+    it('parseAnswerTarget handles exact input shapes', () => {
+        expect(helpers.parseAnswerTarget('123')).toEqual({ answerId: '123', questionId: '' });
+        expect(helpers.parseAnswerTarget('answer:10:123')).toEqual({ answerId: '123', questionId: '10' });
+        expect(helpers.parseAnswerTarget('https://www.zhihu.com/question/10/answer/123')).toEqual({ answerId: '123', questionId: '10' });
+        expect(helpers.parseAnswerTarget('https://zhihu.com/answer/123?utm=1#x')).toEqual({ answerId: '123', questionId: '' });
+        expect(helpers.parseAnswerTarget('http://www.zhihu.com/question/10/answer/123')).toBeNull();
+        expect(helpers.parseAnswerTarget('https://www.zhihu.com/question/10/answer/123/extra')).toBeNull();
+    });
+
+    it('extractAnswerId keeps the legacy helper contract for tests', () => {
+        expect(helpers.extractAnswerId('123')).toBe('123');
+        expect(helpers.extractAnswerId('answer:10:123')).toBe('123');
+        expect(helpers.extractAnswerId('https://www.zhihu.com/question/10/answer/123')).toBe('123');
+        expect(helpers.extractAnswerId('https://www.zhihu.com/answer/123')).toBe('123');
+        expect(helpers.extractAnswerId('  123  ')).toBe('123');
+        expect(helpers.extractAnswerId('')).toBeNull();
+        expect(helpers.extractAnswerId('not-an-id')).toBeNull();
+        expect(helpers.extractAnswerId('https://example.com/answer/123')).toBeNull();
+    });
+});

package/clis/zhihu/question.js

@@ -9,6 +9,9 @@ function stripHtml(html) {
         .replace(/&/g, '&')
         .trim();
 }
+
+const MAX_LIMIT = 1000;
+
 cli({
     site: 'zhihu',
     name: 'question',
@@ -18,7 +21,8 @@ cli({
     strategy: Strategy.COOKIE,
     args: [
         { name: 'id', required: true, positional: true, help: 'Question ID (numeric)' },
-        { name: 'limit', type: 'int', default: 5, help: 'Number of answers' },
+        { name: 'limit', type: 'int', default: 5, help: 'Number of answers (max 1000; use normal-sized requests)' },
+        { name: 'sort', default: 'default', choices: ['default', 'created'], help: 'Answer order: default or created' },
     ],
     columns: ['rank', 'author', 'votes', 'content'],
     func: async (page, kwargs) => {
@@ -28,23 +32,53 @@ cli({
             throw new CliError('INVALID_INPUT', 'Question ID must be numeric', 'Example: opencli zhihu question 123456789');
         }
         const answerLimit = Number(limit);
-        await page.goto(`https://www.zhihu.com/question/${questionId}`);
-        const url = `https://www.zhihu.com/api/v4/questions/${questionId}/answers?limit=${answerLimit}&offset=0&sort_by=default&include=data[*].content,voteup_count,comment_count,author`;
-        const data = await page.evaluate(`
+        if (!Number.isInteger(answerLimit) || answerLimit <= 0 || answerLimit > MAX_LIMIT) {
+            throw new CliError('INVALID_INPUT', `Limit must be a positive integer no greater than ${MAX_LIMIT}`, 'Use a normal-sized limit to avoid slow requests or Zhihu risk controls');
+        }
+        const sort = String(kwargs.sort || 'default');
+        if (sort !== 'default' && sort !== 'created') {
+            throw new CliError('INVALID_INPUT', 'Sort must be one of: default, created', 'Example: opencli zhihu question 123456789 --sort created');
+        }
+        await page.goto(sort === 'created'
+            ? `https://www.zhihu.com/question/${questionId}/answers/updated`
+            : `https://www.zhihu.com/question/${questionId}`);
+        // Zhihu caps `limit` at 20 per request, so always ask for the API
+        // maximum. The pagination loop below trims to `answerLimit` via the
+        // `answers.length >= answerLimit` break, so a smaller --limit only
+        // costs one over-fetched page worth of bandwidth and never silently
+        // clamps the user-requested count.
+        const ZHIHU_PAGE_SIZE = 20;
+        let url = `https://www.zhihu.com/api/v4/questions/${questionId}/answers?limit=${ZHIHU_PAGE_SIZE}&offset=0&sort_by=${sort}&include=data[*].content,voteup_count,comment_count,author`;
+        const answers = [];
+        const seen = new Set();
+        const visited = new Set();
+        while (url && answers.length < answerLimit && !visited.has(url)) {
+            visited.add(url);
+            const data = await page.evaluate(`
       (async () => {
         const r = await fetch(${JSON.stringify(url)}, { credentials: 'include' });
         if (!r.ok) return { __httpError: r.status };
         return await r.json();
       })()
     `);
-        if (!data || data.__httpError) {
-            const status = data?.__httpError;
-            if (status === 401 || status === 403) {
-                throw new AuthRequiredError('www.zhihu.com', 'Failed to fetch question data from Zhihu');
+            if (!data || data.__httpError) {
+                const status = data?.__httpError;
+                if (status === 401 || status === 403) {
+                    throw new AuthRequiredError('www.zhihu.com', 'Failed to fetch question data from Zhihu');
+                }
+                throw new CliError('FETCH_ERROR', status ? `Zhihu question answers request failed (HTTP ${status})` : 'Zhihu question answers request failed', 'Try again later or rerun with -v for more detail');
+            }
+            for (const item of data.data || []) {
+                const key = item.id == null ? `${item.author?.name || 'anonymous'}:${item.content || ''}` : String(item.id);
+                if (seen.has(key)) continue;
+                seen.add(key);
+                answers.push(item);
+                if (answers.length >= answerLimit) break;
             }
-            throw new CliError('FETCH_ERROR', status ? `Zhihu question answers request failed (HTTP ${status})` : 'Zhihu question answers request failed', 'Try again later or rerun with -v for more detail');
+            if (data.paging?.is_end) break;
+            url = typeof data.paging?.next === 'string' ? data.paging.next : '';
         }
-        return (data.data || []).map((item, i) => ({
+        return answers.map((item, i) => ({
             rank: i + 1,
             author: item.author?.name || 'anonymous',
             votes: item.voteup_count || 0,

package/clis/zhihu/question.test.js

@@ -8,7 +8,10 @@ describe('zhihu question', () => {
         expect(cmd?.func).toBeTypeOf('function');
         const goto = vi.fn().mockResolvedValue(undefined);
         const evaluate = vi.fn().mockImplementation(async (js) => {
-            expect(js).toContain('questions/2021881398772981878/answers?limit=3');
+            // Per-request page size is the Zhihu API maximum (20). The
+            // 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("credentials: 'include'");
             return {
                 data: [
@@ -32,6 +35,59 @@ describe('zhihu question', () => {
         expect(goto).toHaveBeenCalledWith('https://www.zhihu.com/question/2021881398772981878');
         expect(evaluate).toHaveBeenCalledTimes(1);
     });
+    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>' },
+                ],
+                paging: {
+                    is_end: false,
+                    next: 'https://www.zhihu.com/api/v4/questions/2021881398772981878/answers?limit=2&offset=80&sort_by=default',
+                },
+            })
+            .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>' },
+                ],
+                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' },
+        ]);
+        expect(evaluate).toHaveBeenCalledTimes(2);
+        expect(evaluate.mock.calls[1][0]).toContain('offset=80');
+    });
+    it('supports created-time sorting', async () => {
+        const cmd = getRegistry().get('zhihu/question');
+        const goto = vi.fn().mockResolvedValue(undefined);
+        const evaluate = vi.fn().mockImplementation(async (js) => {
+            expect(js).toContain('sort_by=created');
+            return {
+                data: [
+                    {
+                        id: 'a1',
+                        author: { name: 'newest' },
+                        voteup_count: 1,
+                        content: '<p>created order</p>',
+                    },
+                ],
+                paging: { is_end: true },
+            };
+        });
+        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' },
+        ]);
+        expect(goto).toHaveBeenCalledWith('https://www.zhihu.com/question/2021881398772981878/answers/updated');
+    });
     it('maps auth-like answer failures to AuthRequiredError', async () => {
         const cmd = getRegistry().get('zhihu/question');
         const page = {
@@ -69,4 +125,25 @@ describe('zhihu question', () => {
         expect(page.goto).not.toHaveBeenCalled();
         expect(page.evaluate).not.toHaveBeenCalled();
     });
+    it('rejects invalid limits before navigation', async () => {
+        const cmd = getRegistry().get('zhihu/question');
+        const page = { goto: vi.fn(), evaluate: vi.fn() };
+        await expect(cmd.func(page, { id: '2021881398772981878', limit: 0 })).rejects.toBeInstanceOf(CliError);
+        expect(page.goto).not.toHaveBeenCalled();
+        expect(page.evaluate).not.toHaveBeenCalled();
+    });
+    it('rejects excessive limits before navigation', async () => {
+        const cmd = getRegistry().get('zhihu/question');
+        const page = { goto: vi.fn(), evaluate: vi.fn() };
+        await expect(cmd.func(page, { id: '2021881398772981878', limit: 1001 })).rejects.toBeInstanceOf(CliError);
+        expect(page.goto).not.toHaveBeenCalled();
+        expect(page.evaluate).not.toHaveBeenCalled();
+    });
+    it('rejects invalid sort before navigation', async () => {
+        const cmd = getRegistry().get('zhihu/question');
+        const page = { goto: vi.fn(), evaluate: vi.fn() };
+        await expect(cmd.func(page, { id: '2021881398772981878', limit: 1, sort: 'unknown' })).rejects.toBeInstanceOf(CliError);
+        expect(page.goto).not.toHaveBeenCalled();
+        expect(page.evaluate).not.toHaveBeenCalled();
+    });
 });

package/clis/zhihu/recommend.js

@@ -0,0 +1,103 @@
+import { cli, Strategy } from '@jackwener/opencli/registry';
+import { AuthRequiredError, CliError } from '@jackwener/opencli/errors';
+
+function normalizeUrl(item) {
+    const target = item.target || {};
+    const id = target.id == null ? '' : String(target.id);
+    if (target.type === 'answer') {
+        const questionId = target.question?.id == null ? '' : String(target.question.id);
+        return questionId && id ? `https://www.zhihu.com/question/${questionId}/answer/${id}` : '';
+    }
+    if (target.type === 'article') {
+        return id ? `https://zhuanlan.zhihu.com/p/${id}` : '';
+    }
+    if (target.type === 'question') {
+        return id ? `https://www.zhihu.com/question/${id}` : '';
+    }
+    return '';
+}
+
+function normalizeTitle(item) {
+    const target = item.target || {};
+    if (target.type === 'answer') return target.question?.title || '';
+    return target.title || target.question?.title || '';
+}
+
+const MAX_LIMIT = 1000;
+
+cli({
+    site: 'zhihu',
+    name: 'recommend',
+    access: 'read',
+    description: '知乎首页推荐',
+    domain: 'www.zhihu.com',
+    strategy: Strategy.COOKIE,
+    args: [
+        { name: 'limit', type: 'int', default: 20, help: 'Number of items to return (max 1000; use normal-sized requests)' },
+    ],
+    columns: ['rank', 'type', 'title', 'author', 'votes', 'url'],
+    func: async (page, kwargs) => {
+        const itemLimit = Number(kwargs.limit ?? 20);
+        if (!Number.isInteger(itemLimit) || itemLimit <= 0 || itemLimit > MAX_LIMIT) {
+            throw new CliError('INVALID_INPUT', `Limit must be a positive integer no greater than ${MAX_LIMIT}`, 'Use a normal-sized limit to avoid slow requests or Zhihu risk controls');
+        }
+        await page.goto('https://www.zhihu.com');
+        let url = 'https://www.zhihu.com/api/v3/feed/topstory/recommend?limit=10&desktop=true';
+        const items = [];
+        const seen = new Set();
+        const visited = new Set();
+        while (url && items.length < itemLimit && !visited.has(url)) {
+            visited.add(url);
+            const data = await page.evaluate(`
+      (async () => {
+        const r = await fetch(${JSON.stringify(url)}, { credentials: 'include' });
+        if (!r.ok) return { __httpError: r.status };
+        return await r.json();
+      })()
+    `);
+            if (!data || data.__httpError) {
+                const status = data?.__httpError;
+                if (status === 401 || status === 403) {
+                    throw new AuthRequiredError('www.zhihu.com', 'Failed to fetch Zhihu recommendations');
+                }
+                throw new CliError('FETCH_ERROR', status ? `Zhihu recommendations request failed (HTTP ${status})` : 'Zhihu recommendations request failed', 'Try again later or rerun with -v for more detail');
+            }
+            for (const item of data.data || []) {
+                const target = item.target || {};
+                // Dedup key uses semantic identity (type:targetId) and falls
+                // back to the feed cursor id when no target id exists. We avoid
+                // synthesizing a sentinel like 'unknown' for missing type
+                // because that would collapse distinct typed items into the
+                // same bucket. When no id is available at all we keep the row
+                // and skip dedup — surfacing potentially-duplicate items beats
+                // silently dropping them.
+                const targetId = target.id;
+                let key = null;
+                if (targetId != null) {
+                    key = `${target.type ?? ''}:${targetId}`;
+                } else if (item.id != null) {
+                    key = `__feed:${item.id}`;
+                }
+                if (key != null) {
+                    if (seen.has(key)) continue;
+                    seen.add(key);
+                }
+                items.push(item);
+                if (items.length >= itemLimit) break;
+            }
+            if (data.paging?.is_end) break;
+            url = typeof data.paging?.next === 'string' ? data.paging.next : '';
+        }
+        return items.map((item, i) => {
+            const target = item.target || {};
+            return {
+                rank: i + 1,
+                type: target.type || item.type || '',
+                title: normalizeTitle(item),
+                author: target.author?.name || '',
+                votes: target.voteup_count ?? target.reaction?.statistics?.like_count ?? 0,
+                url: normalizeUrl(item),
+            };
+        });
+    },
+});