@jackwener/opencli 1.7.2 → 1.7.4

package/clis/xiaohongshu/comments.test.js

@@ -27,7 +27,7 @@ function createPageMock(evaluateResult) {
 }
 describe('xiaohongshu comments', () => {
     const command = getRegistry().get('xiaohongshu/comments');
-    it('returns ranked comment rows', async () => {
+    it('returns ranked comment rows for signed full URLs', async () => {
         const page = createPageMock({
             loginWall: false,
             results: [
@@ -35,22 +35,32 @@ describe('xiaohongshu comments', () => {
                 { author: 'Bob', text: 'Very helpful', likes: 0, time: '2024-01-02', is_reply: false, reply_to: '' },
             ],
         });
-        const result = (await command.func(page, { 'note-id': '69aadbcb000000002202f131', limit: 5 }));
-        expect(page.goto.mock.calls[0][0]).toContain('/search_result/69aadbcb000000002202f131');
+        const signedUrl = 'https://www.xiaohongshu.com/search_result/69aadbcb000000002202f131?xsec_token=abc&xsec_source=pc_search';
+        const result = (await command.func(page, { 'note-id': signedUrl, limit: 5 }));
+        expect(page.goto.mock.calls[0][0]).toBe(signedUrl);
         expect(result).toHaveLength(2);
         expect(result[0]).toMatchObject({ rank: 1, author: 'Alice', text: 'Great note!', likes: 10 });
         expect(result[1]).toMatchObject({ rank: 2, author: 'Bob', text: 'Very helpful', likes: 0 });
     });
-    it('preserves full /explore/ URL as-is for navigation', async () => {
+    it('rejects bare note IDs before browser navigation', async () => {
+        const page = createPageMock({ loginWall: false, results: [] });
+        await expect(command.func(page, { 'note-id': '69aadbcb000000002202f131', limit: 5 })).rejects.toMatchObject({
+            code: 'ARGUMENT',
+            message: expect.stringContaining('signed URL'),
+            hint: expect.stringContaining('xsec_token'),
+        });
+        expect(page.goto).not.toHaveBeenCalled();
+    });
+    it('preserves signed /explore/ URL as-is for navigation', async () => {
         const page = createPageMock({
             loginWall: false,
             results: [{ author: 'Alice', text: 'Nice', likes: 1, time: '2024-01-01', is_reply: false, reply_to: '' }],
         });
         await command.func(page, {
-            'note-id': 'https://www.xiaohongshu.com/explore/69aadbcb000000002202f131',
+            'note-id': 'https://www.xiaohongshu.com/explore/69aadbcb000000002202f131?xsec_token=abc&xsec_source=pc_search',
             limit: 5,
         });
-        expect(page.goto.mock.calls[0][0]).toContain('/explore/69aadbcb000000002202f131');
+        expect(page.goto.mock.calls[0][0]).toContain('/explore/69aadbcb000000002202f131?xsec_token=abc');
     });
     it('preserves full search_result URL with xsec_token for navigation', async () => {
         const page = createPageMock({
@@ -61,13 +71,54 @@ describe('xiaohongshu comments', () => {
         await command.func(page, { 'note-id': fullUrl, limit: 5 });
         expect(page.goto.mock.calls[0][0]).toBe(fullUrl);
     });
+    it('preserves signed /user/profile/<user>/<note> URLs for navigation', async () => {
+        const page = createPageMock({
+            loginWall: false,
+            results: [{ author: 'Alice', text: 'Nice', likes: 1, time: '2024-01-01', is_reply: false, reply_to: '' }],
+        });
+        const fullUrl = 'https://www.xiaohongshu.com/user/profile/user123/69aadbcb000000002202f131?xsec_token=abc&xsec_source=pc_user';
+        await command.func(page, { 'note-id': fullUrl, limit: 5 });
+        expect(page.goto.mock.calls[0][0]).toBe(fullUrl);
+    });
     it('throws AuthRequiredError when login wall is detected', async () => {
         const page = createPageMock({ loginWall: true, results: [] });
-        await expect(command.func(page, { 'note-id': 'abc123', limit: 5 })).rejects.toThrow('Note comments require login');
+        await expect(command.func(page, {
+            'note-id': 'https://www.xiaohongshu.com/search_result/abc123?xsec_token=tok',
+            limit: 5,
+        })).rejects.toThrow('Note comments require login');
+    });
+    it('throws SECURITY_BLOCK with retry guidance when a full URL comments page is blocked', async () => {
+        const page = createPageMock({
+            pageUrl: 'https://www.xiaohongshu.com/website-login/error?error_code=300031',
+            securityBlock: true,
+            loginWall: false,
+            results: [],
+        });
+        await expect(command.func(page, {
+            'note-id': 'https://www.xiaohongshu.com/search_result/69aadbcb000000002202f131?xsec_token=abc&xsec_source=pc_search',
+            limit: 5,
+        })).rejects.toMatchObject({
+            code: 'SECURITY_BLOCK',
+            hint: expect.stringContaining('Try again later'),
+        });
     });
     it('returns empty array when no comments are found', async () => {
         const page = createPageMock({ loginWall: false, results: [] });
-        await expect(command.func(page, { 'note-id': 'abc123', limit: 5 })).resolves.toEqual([]);
+        await expect(command.func(page, {
+            'note-id': 'https://www.xiaohongshu.com/search_result/abc123?xsec_token=tok',
+            limit: 5,
+        })).resolves.toEqual([]);
+    });
+    it('uses condition-based comment scrolling instead of a fixed blind loop', async () => {
+        const page = createPageMock({ loginWall: false, results: [] });
+        await command.func(page, {
+            'note-id': 'https://www.xiaohongshu.com/search_result/abc123?xsec_token=tok',
+            limit: 5,
+        });
+        const script = page.evaluate.mock.calls[0][0];
+        expect(script).toContain("const beforeCount = scroller.querySelectorAll('.parent-comment').length");
+        expect(script).toContain("const afterCount = scroller.querySelectorAll('.parent-comment').length");
+        expect(script).toContain('if (afterCount <= beforeCount) break');
     });
     it('respects the limit for top-level comments', async () => {
         const manyComments = Array.from({ length: 10 }, (_, i) => ({
@@ -79,7 +130,10 @@ describe('xiaohongshu comments', () => {
             reply_to: '',
         }));
         const page = createPageMock({ loginWall: false, results: manyComments });
-        const result = (await command.func(page, { 'note-id': 'abc123', limit: 3 }));
+        const result = (await command.func(page, {
+            'note-id': 'https://www.xiaohongshu.com/search_result/abc123?xsec_token=tok',
+            limit: 3,
+        }));
         expect(result).toHaveLength(3);
         expect(result[0].rank).toBe(1);
         expect(result[2].rank).toBe(3);
@@ -92,7 +146,10 @@ describe('xiaohongshu comments', () => {
                 { author: 'Bob', text: 'Very helpful', likes: 0, time: '2024-01-02', is_reply: false, reply_to: '' },
             ],
         });
-        const result = (await command.func(page, { 'note-id': 'abc123', limit: -3 }));
+        const result = (await command.func(page, {
+            'note-id': 'https://www.xiaohongshu.com/search_result/abc123?xsec_token=tok',
+            limit: -3,
+        }));
         expect(result).toHaveLength(1);
         expect(result[0]).toMatchObject({ rank: 1, author: 'Alice' });
     });
@@ -107,7 +164,7 @@ describe('xiaohongshu comments', () => {
                 ],
             });
             const result = (await command.func(page, {
-                'note-id': 'abc123', limit: 50, 'with-replies': true,
+                'note-id': 'https://www.xiaohongshu.com/search_result/abc123?xsec_token=tok', limit: 50, 'with-replies': true,
             }));
             expect(result).toHaveLength(3);
             expect(result[0]).toMatchObject({ author: 'Alice', is_reply: false, reply_to: '' });
@@ -130,7 +187,7 @@ describe('xiaohongshu comments', () => {
             });
             // Limit to 2 top-level comments — should include A + 2 replies + B = 4 rows
             const result = (await command.func(page, {
-                'note-id': 'abc123', limit: 2, 'with-replies': true,
+                'note-id': 'https://www.xiaohongshu.com/search_result/abc123?xsec_token=tok', limit: 2, 'with-replies': true,
             }));
             expect(result).toHaveLength(4);
             expect(result.map((r) => r.author)).toEqual(['A', 'A1', 'A2', 'B']);

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

@@ -253,6 +253,7 @@ async function captureNoteDetailPayload(page, noteId) {
     let captured = 0;
     // Try to fetch each API endpoint through the page context (uses the browser's cookies)
     for (const { suffix, key } of DETAIL_API_ENDPOINTS) {
+        await page.wait({ time: 0.5 + Math.random() });
         const apiUrl = `${suffix}?note_id=${noteId}`;
         try {
             const data = await page.evaluate(`
@@ -325,6 +326,7 @@ cli({
     domain: 'creator.xiaohongshu.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    navigateBefore: false,
     args: [
         { name: 'note-id', positional: true, type: 'string', required: true, help: 'Note ID (from creator-notes or note-detail page URL)' },
     ],

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

@@ -256,4 +256,36 @@ describe('xiaohongshu creator-note-detail', () => {
             { section: '互动数据', metric: '分享数', value: '0', extra: '粉丝占比 0%' },
         ]);
     });
+    it('waits between creator detail API fetches to avoid burst traffic', async () => {
+        const cmd = getRegistry().get('xiaohongshu/creator-note-detail');
+        const domData = {
+            title: '示例笔记',
+            infoText: '示例笔记\n2026-03-19 12:00\n切换笔记',
+            sections: [
+                {
+                    title: '基础数据',
+                    metrics: [
+                        { label: '曝光数', value: '100', extra: '粉丝占比 10%' },
+                        { label: '观看数', value: '50', extra: '粉丝占比 20%' },
+                        { label: '封面点击率', value: '12%', extra: '粉丝 11%' },
+                        { label: '平均观看时长', value: '30秒', extra: '粉丝 31秒' },
+                        { label: '涨粉数', value: '2', extra: '' },
+                    ],
+                },
+                {
+                    title: '互动数据',
+                    metrics: [
+                        { label: '点赞数', value: '8', extra: '粉丝占比 25%' },
+                        { label: '评论数', value: '1', extra: '粉丝占比 0%' },
+                        { label: '收藏数', value: '3', extra: '粉丝占比 50%' },
+                        { label: '分享数', value: '0', extra: '粉丝占比 0%' },
+                    ],
+                },
+            ],
+        };
+        const page = createPageMock([domData, null, null, null, null]);
+        await cmd.func(page, { 'note-id': 'demo-note-id' });
+        expect(page.wait).toHaveBeenCalledWith(expect.objectContaining({ time: expect.any(Number) }));
+        expect(page.wait.mock.calls.length).toBeGreaterThanOrEqual(4);
+    });
 });

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

@@ -50,6 +50,7 @@ cli({
     domain: 'creator.xiaohongshu.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    navigateBefore: false,
     args: [
         { name: 'limit', type: 'int', default: 3, help: 'Number of recent notes to summarize' },
     ],
@@ -63,6 +64,9 @@ cli({
         }
         const results = [];
         for (const [index, note] of notes.entries()) {
+            if (index > 0) {
+                await page.wait({ time: 1 + Math.random() * 2 });
+            }
             if (!note.id) {
                 results.push({
                     rank: index + 1,

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

@@ -1,5 +1,8 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { summarizeCreatorNote } from './creator-notes-summary.js';
+import { getRegistry } from '@jackwener/opencli/registry';
+import * as creatorNotesModule from './creator-notes.js';
+import * as creatorDetailModule from './creator-note-detail.js';
 import './creator-notes-summary.js';
 describe('xiaohongshu creator-notes-summary', () => {
     it('summarizes note list row and detail rows into one compact row', () => {
@@ -46,4 +49,39 @@ describe('xiaohongshu creator-notes-summary', () => {
             url: 'https://creator.xiaohongshu.com/statistics/note-detail?noteId=cccccccccccccccccccccccc',
         });
     });
+    it('waits between note detail fetches after the first note', async () => {
+        const cmd = getRegistry().get('xiaohongshu/creator-notes-summary');
+        const page = {
+            wait: vi.fn().mockResolvedValue(undefined),
+        };
+        vi.spyOn(creatorNotesModule, 'fetchCreatorNotes').mockResolvedValue([
+            {
+                id: 'aaaaaaaaaaaaaaaaaaaaaaaa',
+                title: 'n1',
+                date: '2026年03月18日 20:01',
+                views: 1,
+                likes: 1,
+                collects: 1,
+                comments: 1,
+                url: 'u1',
+            },
+            {
+                id: 'bbbbbbbbbbbbbbbbbbbbbbbb',
+                title: 'n2',
+                date: '2026年03月19日 20:01',
+                views: 2,
+                likes: 2,
+                collects: 2,
+                comments: 2,
+                url: 'u2',
+            },
+        ]);
+        vi.spyOn(creatorDetailModule, 'fetchCreatorNoteDetailRows').mockResolvedValue([
+            { section: '笔记信息', metric: 'published_at', value: '2026-03-18 20:01', extra: '' },
+            { section: '基础数据', metric: '观看数', value: '1', extra: '' },
+        ]);
+        await cmd.func(page, { limit: 2 });
+        expect(page.wait).toHaveBeenCalledWith(expect.objectContaining({ time: expect.any(Number) }));
+        expect(page.wait.mock.calls).toHaveLength(1);
+    });
 });

package/clis/xiaohongshu/creator-notes.js

@@ -200,6 +200,7 @@ cli({
     domain: 'creator.xiaohongshu.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    navigateBefore: false,
     args: [
         { name: 'limit', type: 'int', default: 20, help: 'Number of notes to return' },
     ],

package/clis/xiaohongshu/creator-profile.js

@@ -15,6 +15,7 @@ cli({
     domain: 'creator.xiaohongshu.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    navigateBefore: false,
     args: [],
     columns: ['field', 'value'],
     func: async (page, _kwargs) => {

package/clis/xiaohongshu/creator-stats.js

@@ -15,6 +15,7 @@ cli({
     domain: 'creator.xiaohongshu.com',
     strategy: Strategy.COOKIE,
     browser: true,
+    navigateBefore: false,
     args: [
         {
             name: 'period',

package/clis/xiaohongshu/download.js

@@ -2,14 +2,14 @@
  * Xiaohongshu download — download images and videos from a note.
  *
  * Usage:
- *   opencli xiaohongshu download <note-id-or-url> --output ./xhs
+ *   opencli xiaohongshu download <signed-note-url-or-shortlink> --output ./xhs
  *
- * Accepts a bare note ID, a full xiaohongshu.com URL (with xsec_token),
- * or a short link (http://xhslink.com/...).
+ * Accepts a full xiaohongshu.com URL with xsec_token or an xhslink short link.
  */
 import { cli, Strategy } from '@jackwener/opencli/registry';
 import { formatCookieHeader } from '@jackwener/opencli/download';
 import { downloadMedia } from '@jackwener/opencli/download/media-download';
+import { CliError } from '@jackwener/opencli/errors';
 import { buildNoteUrl, parseNoteId } from './note-helpers.js';
 cli({
     site: 'xiaohongshu',
@@ -17,8 +17,9 @@ cli({
     description: '下载小红书笔记中的图片和视频',
     domain: 'www.xiaohongshu.com',
     strategy: Strategy.COOKIE,
+    navigateBefore: false,
     args: [
-        { name: 'note-id', positional: true, required: true, help: 'Note ID, full URL, or short link' },
+        { name: 'note-id', positional: true, required: true, help: 'Full Xiaohongshu note URL with xsec_token, or xhslink short link' },
         { name: 'output', default: './xiaohongshu-downloads', help: 'Output directory' },
     ],
     columns: ['index', 'type', 'status', 'size'],
@@ -26,12 +27,17 @@ cli({
         const rawInput = String(kwargs['note-id']);
         const output = kwargs.output;
         const noteId = parseNoteId(rawInput);
-        await page.goto(buildNoteUrl(rawInput));
+        await page.goto(buildNoteUrl(rawInput, { allowShortLink: true, commandName: 'xiaohongshu download' }));
+        await page.wait({ time: 1 + Math.random() * 2 });
         // Extract note info and media URLs
         const data = await page.evaluate(`
       (() => {
+        const bodyText = document.body?.innerText || '';
         const result = {
           noteId: '${noteId}',
+          pageUrl: location.href,
+          securityBlock: /安全限制|访问链接异常/.test(bodyText)
+            || /website-login\\/error|error_code=300017|error_code=300031/.test(location.href),
           title: '',
           author: '',
           media: []
@@ -44,9 +50,9 @@ cli({
           seenMedia.add(key);
           result.media.push({ type, url });
         };
-        const locationMatch = (location.pathname || '').match(/\\/(?:explore|note|search_result|discovery\\/item)\\/([a-f0-9]+)/i);
+        const locationMatch = (location.pathname || '').match(/\\/(?:explore|note|search_result|discovery\\/item)\\/([a-f0-9]+)|\\/user\\/profile\\/[^/?#]+\\/([a-f0-9]+)/i);
         if (locationMatch) {
-          result.noteId = locationMatch[1];
+          result.noteId = locationMatch[1] || locationMatch[2];
         }
 
         // Get title
@@ -148,6 +154,11 @@ cli({
         return result;
       })()
     `);
+        if (data?.securityBlock) {
+            throw new CliError('SECURITY_BLOCK', 'Xiaohongshu security block: the note detail page was blocked by risk control.', /^https?:\/\//.test(rawInput)
+                ? 'The page may be temporarily restricted. Try again later or from a different session.'
+                : 'Try using a full URL from search results (with xsec_token) instead of a bare note ID.');
+        }
         if (!data || !data.media || data.media.length === 0) {
             return [{ index: 0, type: '-', status: 'failed', size: 'No media found' }];
         }

package/clis/xiaohongshu/download.test.js

@@ -70,4 +70,46 @@ describe('xiaohongshu download', () => {
             filenamePrefix: '69bc166f000000001a02069a',
         }));
     });
+    it('uses canonical note id for signed user profile note URLs', async () => {
+        const page = createPageMock({
+            noteId: '',
+            media: [{ type: 'image', url: 'https://ci.xiaohongshu.com/example.jpg' }],
+        });
+        const fullUrl = 'https://www.xiaohongshu.com/user/profile/user123/69bc166f000000001a02069a?xsec_token=abc&xsec_source=pc_user';
+        await command.func(page, { 'note-id': fullUrl, output: './out' });
+        expect(page.goto.mock.calls[0][0]).toBe(fullUrl);
+        expect(mockDownloadMedia).toHaveBeenCalledWith([{ type: 'image', url: 'https://ci.xiaohongshu.com/example.jpg' }], expect.objectContaining({
+            subdir: '69bc166f000000001a02069a',
+            filenamePrefix: '69bc166f000000001a02069a',
+        }));
+    });
+    it('rejects bare note IDs before browser navigation', async () => {
+        const page = createPageMock({
+            noteId: '69bc166f000000001a02069a',
+            media: [],
+        });
+        await expect(command.func(page, { 'note-id': '69bc166f000000001a02069a', output: './out' })).rejects.toMatchObject({
+            code: 'ARGUMENT',
+            message: expect.stringContaining('signed URL'),
+            hint: expect.stringContaining('xsec_token'),
+        });
+        expect(page.goto).not.toHaveBeenCalled();
+        expect(mockDownloadMedia).not.toHaveBeenCalled();
+    });
+    it('throws SECURITY_BLOCK with retry guidance for blocked full URLs', async () => {
+        const page = createPageMock({
+            pageUrl: 'https://www.xiaohongshu.com/website-login/error?error_code=300031',
+            securityBlock: true,
+            noteId: '69bc166f000000001a02069a',
+            media: [],
+        });
+        await expect(command.func(page, {
+            'note-id': 'https://www.xiaohongshu.com/explore/69bc166f000000001a02069a?xsec_token=abc&xsec_source=pc_search',
+            output: './out',
+        })).rejects.toMatchObject({
+            code: 'SECURITY_BLOCK',
+            hint: expect.stringContaining('Try again later'),
+        });
+        expect(mockDownloadMedia).not.toHaveBeenCalled();
+    });
 });

package/clis/xiaohongshu/navigation.test.js

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+import { getRegistry } from '@jackwener/opencli/registry';
+import './note.js';
+import './comments.js';
+import './download.js';
+import './search.js';
+import './user.js';
+import './publish.js';
+import './creator-notes.js';
+import './creator-note-detail.js';
+import './creator-notes-summary.js';
+import './creator-profile.js';
+import './creator-stats.js';
+
+describe('xiaohongshu navigateBefore hardening', () => {
+    const expectedFalse = [
+        'xiaohongshu/note',
+        'xiaohongshu/comments',
+        'xiaohongshu/download',
+        'xiaohongshu/search',
+        'xiaohongshu/user',
+        'xiaohongshu/publish',
+        'xiaohongshu/creator-notes',
+        'xiaohongshu/creator-note-detail',
+        'xiaohongshu/creator-notes-summary',
+        'xiaohongshu/creator-profile',
+        'xiaohongshu/creator-stats',
+    ];
+    it.each(expectedFalse)('%s sets navigateBefore=false', (name) => {
+        const cmd = getRegistry().get(name);
+        expect(cmd).toBeDefined();
+        expect(cmd.navigateBefore).toBe(false);
+    });
+});

package/clis/xiaohongshu/note-helpers.js

@@ -1,25 +1,59 @@
+import { ArgumentError } from '@jackwener/opencli/errors';
+
 /** Side-effect-free helpers shared by xiaohongshu note and comments commands. */
 /** Extract a bare note ID from a full URL or raw ID string. */
 export function parseNoteId(input) {
     const trimmed = input.trim();
-    const match = trimmed.match(/\/(?:explore|note|search_result)\/([a-f0-9]+)/);
-    return match ? match[1] : trimmed;
+    const match = trimmed.match(/\/(?:explore|note|search_result|discovery\/item)\/([a-f0-9]+)|\/user\/profile\/[^/?#]+\/([a-f0-9]+)/i);
+    return match ? (match[1] || match[2]) : trimmed;
 }
+
+export const XHS_SIGNED_URL_HINT = 'Pass a full Xiaohongshu note URL with xsec_token from search results or user/profile context.';
+
+function isShortLink(input) {
+    return /^https?:\/\/xhslink\.com\//i.test(input);
+}
+
+function isXiaohongshuHost(hostname) {
+    const normalized = hostname.toLowerCase();
+    return normalized === 'xiaohongshu.com' || normalized.endsWith('.xiaohongshu.com');
+}
+
+function isSupportedNotePath(pathname) {
+    return /^\/(?:explore|note|search_result|discovery\/item)\/[a-f0-9]+(?:[/?#]|$)/i.test(pathname)
+        || /^\/user\/profile\/[^/?#]+\/[a-f0-9]+(?:[/?#]|$)/i.test(pathname);
+}
+
 /**
  * Build the best navigation URL for a note.
  *
- * XHS blocks direct `/explore/<id>` access without a valid `xsec_token`.
- * When the user passes a full URL (from search results), we preserve it
- * so the browser navigates with the token intact. For bare IDs we now use
- * `/search_result/<id>` which works without xsec_token when cookies are present.
+ * XHS note detail pages now require a valid signed URL for reliable access.
+ * Bare note IDs no longer resolve deterministically, so callers must provide
+ * a full note URL with xsec_token or, for downloads only, an xhslink short link.
  */
-export function buildNoteUrl(input) {
+export function buildNoteUrl(input, options = {}) {
+    const { allowShortLink = false, commandName = 'xiaohongshu note' } = options;
     const trimmed = input.trim();
+    const message = `${commandName} now requires a full signed URL`;
+    const hint = allowShortLink
+        ? `${XHS_SIGNED_URL_HINT} For downloads, xhslink short links are also supported.`
+        : XHS_SIGNED_URL_HINT;
+
     if (/^https?:\/\//.test(trimmed)) {
-        // Full URL — navigate as-is; the browser will follow any redirects
-        return trimmed;
+        if (isShortLink(trimmed)) {
+            if (allowShortLink)
+                return trimmed;
+            throw new ArgumentError(message, hint);
+        }
+        try {
+            const url = new URL(trimmed);
+            const xsecToken = url.searchParams.get('xsec_token')?.trim();
+            if (isXiaohongshuHost(url.hostname) && isSupportedNotePath(url.pathname) && xsecToken) {
+                return trimmed;
+            }
+        }
+        catch { }
+        throw new ArgumentError(message, hint);
     }
-    // Use /search_result/<id> instead of /explore/<id> — works without xsec_token
-    // when the user is logged in via cookies (which is always the case with opencli).
-    return `https://www.xiaohongshu.com/search_result/${trimmed}`;
+    throw new ArgumentError(message, hint);
 }

package/clis/xiaohongshu/note.js

@@ -4,12 +4,10 @@
  * Extracts title, author, description text, and engagement metrics
  * (likes, collects, comment count) via DOM extraction.
  *
- * Supports both bare note IDs and full URLs (with xsec_token).
- * Bare IDs now use /search_result/<id> which works without xsec_token
- * when the user is logged in via cookies.
+ * Requires a full Xiaohongshu note URL with xsec_token.
  */
 import { cli, Strategy } from '@jackwener/opencli/registry';
-import { AuthRequiredError, EmptyResultError } from '@jackwener/opencli/errors';
+import { AuthRequiredError, CliError, EmptyResultError } from '@jackwener/opencli/errors';
 import { parseNoteId, buildNoteUrl } from './note-helpers.js';
 cli({
     site: 'xiaohongshu',
@@ -17,20 +15,24 @@ cli({
     description: '获取小红书笔记正文和互动数据',
     domain: 'www.xiaohongshu.com',
     strategy: Strategy.COOKIE,
+    navigateBefore: false,
     args: [
-        { name: 'note-id', required: true, positional: true, help: 'Note ID or full URL (preserves xsec_token for access)' },
+        { name: 'note-id', required: true, positional: true, help: 'Full Xiaohongshu note URL with xsec_token' },
     ],
     columns: ['field', 'value'],
     func: async (page, kwargs) => {
         const raw = String(kwargs['note-id']);
         const noteId = parseNoteId(raw);
-        const url = buildNoteUrl(raw);
+        const url = buildNoteUrl(raw, { commandName: 'xiaohongshu note' });
         await page.goto(url);
-        await page.wait(3);
+        await page.wait({ time: 2 + Math.random() * 3 });
         const data = await page.evaluate(`
       (() => {
-        const loginWall = /登录后查看|请登录/.test(document.body.innerText || '')
-        const notFound = /页面不见了|笔记不存在|无法浏览/.test(document.body.innerText || '')
+        const bodyText = document.body?.innerText || ''
+        const loginWall = /登录后查看|请登录/.test(bodyText)
+        const notFound = /页面不见了|笔记不存在|无法浏览/.test(bodyText)
+        const securityBlock = /安全限制|访问链接异常/.test(bodyText)
+          || /website-login\\/error|error_code=300017|error_code=300031/.test(location.href)
 
         const clean = (el) => (el?.textContent || '').replace(/\\s+/g, ' ').trim()
 
@@ -53,12 +55,17 @@ cli({
           if (t) tags.push(t)
         })
 
-        return { loginWall, notFound, title, desc, author, likes, collects, comments, tags }
+        return { pageUrl: location.href, securityBlock, loginWall, notFound, title, desc, author, likes, collects, comments, tags }
       })()
     `);
         if (!data || typeof data !== 'object') {
             throw new EmptyResultError('xiaohongshu/note', 'Unexpected evaluate response');
         }
+        if (data.securityBlock) {
+            throw new CliError('SECURITY_BLOCK', 'Xiaohongshu security block: the note detail page was blocked by risk control.', /^https?:\/\//.test(raw)
+                ? 'The page may be temporarily restricted. Try again later or from a different session.'
+                : 'Try using a full URL from search results (with xsec_token) instead of a bare note ID.');
+        }
         if (data.loginWall) {
             throw new AuthRequiredError('www.xiaohongshu.com', 'Note content requires login');
         }