fix(xhs): tighten note detail capture matching

jackwener · jackwener · commit b02e7e38a507 · 2026-05-25T14:26:59.000+08:00
diff --git a/clis/xiaohongshu/creator-note-detail.js b/clis/xiaohongshu/creator-note-detail.js
@@ -9,7 +9,7 @@
  * Requires: logged into creator.xiaohongshu.com in Chrome.
  */
 import { cli, Strategy } from '@jackwener/opencli/registry';
-import { EmptyResultError } from '@jackwener/opencli/errors';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
 const NOTE_DETAIL_DATETIME_RE = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$/;
 const NOTE_DETAIL_METRICS = [
     { label: '曝光数', section: '基础数据' },
@@ -251,10 +251,84 @@ const DETAIL_API_ENDPOINTS = [
 ];
 const CAPTURE_POLL_ATTEMPTS = 20;
 const CAPTURE_POLL_INTERVAL_S = 0.5;
-// Capture the dashboard's signed /api/galaxy/* responses on window.__xhsCapture
+function detailApiEndpointForUrl(url) {
+    if (!url)
+        return null;
+    try {
+        const parsed = new URL(String(url), 'https://creator.xiaohongshu.com');
+        return DETAIL_API_ENDPOINTS.find((endpoint) => parsed.pathname === endpoint.suffix) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function findCapturedUrl(captureMap, suffix) {
+    return Object.keys(captureMap).find((url) => detailApiEndpointForUrl(url)?.suffix === suffix);
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function assertOptionalArray(payload, key, suffix) {
+    if (key in payload && !Array.isArray(payload[key])) {
+        throw new CommandExecutionError(`xiaohongshu creator-note-detail: signed API ${suffix} returned malformed ${key}`);
+    }
+}
+function assertOptionalPlainObject(payload, key, suffix) {
+    if (key in payload && !isPlainObject(payload[key])) {
+        throw new CommandExecutionError(`xiaohongshu creator-note-detail: signed API ${suffix} returned malformed ${key}`);
+    }
+}
+function validateCapturedPayload(payload, endpoint) {
+    const suffix = endpoint.suffix;
+    if (!isPlainObject(payload)) {
+        throw new CommandExecutionError(`xiaohongshu creator-note-detail: signed API ${suffix} returned a malformed payload`);
+    }
+    if (endpoint.key === 'noteBase') {
+        assertOptionalPlainObject(payload, 'hour', suffix);
+        assertOptionalPlainObject(payload, 'day', suffix);
+    }
+    if (endpoint.key === 'audienceSource') {
+        assertOptionalArray(payload, 'source', suffix);
+    }
+    if (endpoint.key === 'audienceSourceDetail') {
+        for (const key of ['gender', 'age', 'city', 'interest']) {
+            assertOptionalArray(payload, key, suffix);
+        }
+    }
+    return payload;
+}
+function parseCapturedJson(capture, endpoint) {
+    const suffix = endpoint.suffix;
+    if (!capture || typeof capture !== 'object') {
+        throw new CommandExecutionError(`xiaohongshu creator-note-detail: malformed capture for ${suffix}`);
+    }
+    if (capture.ok !== true) {
+        throw new CommandExecutionError(`xiaohongshu creator-note-detail: signed API ${suffix} returned HTTP ${capture.status ?? 'non-2xx'}`);
+    }
+    if (typeof capture.body !== 'string') {
+        throw new CommandExecutionError(`xiaohongshu creator-note-detail: signed API ${suffix} returned a non-text body`);
+    }
+    try {
+        const envelope = JSON.parse(capture.body);
+        const payload = isPlainObject(envelope) && Object.hasOwn(envelope, 'data') ? envelope.data : envelope;
+        return validateCapturedPayload(payload, endpoint);
+    }
+    catch {
+        throw new CommandExecutionError(`xiaohongshu creator-note-detail: signed API ${suffix} returned invalid JSON or payload shape`);
+    }
+}
+// Capture the dashboard's signed datacenter/note responses on window.__xhsCapture
 // since a direct fetch() from page.evaluate bypasses the x-s signing and gets 406.
 async function installXhsFetchCaptureHook(page) {
     await page.evaluate(`(() => {
+    const targetPaths = ${JSON.stringify(DETAIL_API_ENDPOINTS.map((endpoint) => endpoint.suffix))};
+    const shouldCapture = (url) => {
+      try {
+        return targetPaths.includes(new URL(String(url), window.location.origin).pathname);
+      } catch (_) {
+        return false;
+      }
+    };
     // Reset the buffer every call so stale captures from a previous run on
     // the same tab cannot leak into the current navigation's harvest.
     window.__xhsCapture = {};
@@ -265,7 +339,7 @@ async function installXhsFetchCaptureHook(page) {
       const resp = await origFetch.apply(this, args);
       try {
         const url = typeof args[0] === 'string' ? args[0] : (args[0] && args[0].url) || '';
-        if (url.includes('/api/galaxy/')) {
+        if (shouldCapture(url)) {
           resp.clone().text().then((body) => {
             try { window.__xhsCapture[url] = { status: resp.status, ok: resp.ok, body }; } catch (_) {}
           }).catch(() => {});
@@ -284,7 +358,7 @@ async function installXhsFetchCaptureHook(page) {
       };
       xhr.addEventListener('load', () => {
         try {
-          if (capturedUrl.includes('/api/galaxy/')) {
+          if (shouldCapture(capturedUrl)) {
             window.__xhsCapture[capturedUrl] = { status: xhr.status, ok: xhr.status >= 200 && xhr.status < 300, body: xhr.responseText };
           }
         } catch (_) {}
@@ -314,25 +388,27 @@ async function captureNoteDetailPayload(page, noteId) {
     let captureMap = {};
     for (let i = 0; i < CAPTURE_POLL_ATTEMPTS; i++) {
         await page.wait(CAPTURE_POLL_INTERVAL_S);
-        const raw = await page.evaluate('JSON.stringify(window.__xhsCapture || {})');
-        captureMap = typeof raw === 'string' ? JSON.parse(raw) : {};
-        const captured = wantedSuffixes.filter((suffix) => Object.keys(captureMap).some((url) => url.includes(suffix)));
+        let raw;
+        try {
+            raw = await page.evaluate('JSON.stringify(window.__xhsCapture || {})');
+            captureMap = typeof raw === 'string' ? JSON.parse(raw) : {};
+        }
+        catch {
+            throw new CommandExecutionError('xiaohongshu creator-note-detail: failed to read signed datacenter/note capture buffer');
+        }
+        if (!captureMap || typeof captureMap !== 'object' || Array.isArray(captureMap)) {
+            throw new CommandExecutionError('xiaohongshu creator-note-detail: malformed signed datacenter/note capture buffer');
+        }
+        const captured = wantedSuffixes.filter((suffix) => findCapturedUrl(captureMap, suffix));
         if (captured.length === wantedSuffixes.length)
             break;
     }
     const payload = {};
-    for (const { suffix, key } of DETAIL_API_ENDPOINTS) {
-        const matchUrl = Object.keys(captureMap).find((url) => url.includes(suffix));
+    for (const endpoint of DETAIL_API_ENDPOINTS) {
+        const matchUrl = findCapturedUrl(captureMap, endpoint.suffix);
         if (!matchUrl)
             continue;
-        const capture = captureMap[matchUrl];
-        if (!capture || !capture.ok)
-            continue;
-        try {
-            const json = JSON.parse(capture.body);
-            payload[key] = json.data ?? json;
-        }
-        catch { }
+        payload[endpoint.key] = parseCapturedJson(captureMap[matchUrl], endpoint);
     }
     return Object.keys(payload).length > 0 ? payload : null;
 }
@@ -370,7 +446,7 @@ export async function fetchCreatorNoteDetailRows(page, noteId) {
     // the fetch+XHR hook and SPA-navigates to /statistics/note-detail under
     // it, which is what surfaces the audience / trend rows.
     await page.goto('https://creator.xiaohongshu.com/statistics');
-    const apiPayload = await captureNoteDetailPayload(page, noteId).catch(() => null);
+    const apiPayload = await captureNoteDetailPayload(page, noteId);
     const domData = await captureNoteDetailDomData(page).catch(() => null);
     let rows = parseCreatorNoteDetailDomData(domData, noteId);
     if (rows.length === 0) {
diff --git a/clis/xiaohongshu/creator-note-detail.test.js b/clis/xiaohongshu/creator-note-detail.test.js
@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
-import { EmptyResultError } from '@jackwener/opencli/errors';
+import { CommandExecutionError, EmptyResultError } from '@jackwener/opencli/errors';
 import { getRegistry } from '@jackwener/opencli/registry';
 import { appendAudienceRows, appendTrendRows, parseCreatorNoteDetailDomData, parseCreatorNoteDetailText } from './creator-note-detail.js';
 import './creator-note-detail.js';
@@ -303,6 +303,141 @@ describe('xiaohongshu creator-note-detail', () => {
         const captureProbeCalls = page.evaluate.mock.calls.filter(([script]) => String(script).includes('JSON.stringify(window.__xhsCapture'));
         expect(captureProbeCalls.length).toBeGreaterThanOrEqual(1);
     });
+    it('matches signed API captures by exact pathname so source/detail cannot shadow source', 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%' },
+                    ],
+                },
+            ],
+        };
+        const detailCapture = [
+            'https://creator.xiaohongshu.com/api/galaxy/creator/datacenter/note/audience/source/detail?note_id=demo-note-id',
+            {
+                status: 200,
+                ok: true,
+                body: JSON.stringify({ data: { gender: [{ title: '女性', value: 64 }] } }),
+            },
+        ];
+        const sourceCapture = [
+            'https://creator.xiaohongshu.com/api/galaxy/creator/datacenter/note/audience/source?note_id=demo-note-id',
+            {
+                status: 200,
+                ok: true,
+                body: JSON.stringify({
+                    data: {
+                        source: [
+                            {
+                                title: '首页推荐',
+                                value_with_double: 88.8,
+                                info: { imp_count: 1000, view_count: 400, interaction_count: 20 },
+                            },
+                        ],
+                    },
+                }),
+            },
+        ];
+        const baseCapture = [
+            'https://creator.xiaohongshu.com/api/galaxy/creator/datacenter/note/base?note_id=demo-note-id',
+            {
+                status: 200,
+                ok: true,
+                body: JSON.stringify({ data: { hour: { view_list: [{ date: new Date('2026-03-19T12:00:00+08:00').getTime(), count: 7 }] } } }),
+            },
+        ];
+        const trendCapture = [
+            'https://creator.xiaohongshu.com/api/galaxy/creator/datacenter/note/analyze/audience/trend?note_id=demo-note-id',
+            {
+                status: 200,
+                ok: true,
+                body: JSON.stringify({ data: { no_data: false, no_data_tip_msg: '趋势可用' } }),
+            },
+        ];
+        for (const orderedCaptures of [
+            [detailCapture, sourceCapture, baseCapture, trendCapture],
+            [sourceCapture, detailCapture, baseCapture, trendCapture],
+        ]) {
+            const captureMap = Object.fromEntries(orderedCaptures);
+            const page = createPageMock(undefined);
+            page.evaluate = vi.fn(async (script) => {
+                const s = String(script);
+                if (s.includes('window.__xhsCapture =')) return undefined;
+                if (s.includes('history.pushState')) return undefined;
+                if (s.includes('JSON.stringify(window.__xhsCapture')) return JSON.stringify(captureMap);
+                if (s.includes("document.querySelector('.note-title')")) return domData;
+                return undefined;
+            });
+            const result = await cmd.func(page, { 'note-id': 'demo-note-id' });
+            expect(result).toEqual(expect.arrayContaining([
+                { section: '观看来源', metric: '首页推荐', value: '88.8%', extra: '曝光 1000 · 观看 400 · 互动 20' },
+                { section: '观众画像', metric: '性别/女性', value: '64%', extra: '' },
+                { section: '趋势数据', metric: '按小时/观看数', value: '1 points', extra: '03-19 12:00=7' },
+            ]));
+        }
+    });
+    it('throws a typed error when a captured signed API returns non-2xx', async () => {
+        const cmd = getRegistry().get('xiaohongshu/creator-note-detail');
+        const captureMap = {
+            'https://creator.xiaohongshu.com/api/galaxy/creator/datacenter/note/base?note_id=demo-note-id': {
+                status: 406,
+                ok: false,
+                body: '{"msg":"not acceptable"}',
+            },
+        };
+        const page = createPageMock(undefined);
+        page.evaluate = vi.fn(async (script) => {
+            const s = String(script);
+            if (s.includes('window.__xhsCapture =')) return undefined;
+            if (s.includes('history.pushState')) return undefined;
+            if (s.includes('JSON.stringify(window.__xhsCapture')) return JSON.stringify(captureMap);
+            return null;
+        });
+        await expect(cmd.func(page, { 'note-id': 'demo-note-id' })).rejects.toBeInstanceOf(CommandExecutionError);
+    });
+    it('throws a typed error for wrong-shaped signed API payloads instead of falling back to DOM rows', 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%' },
+                    ],
+                },
+            ],
+        };
+        for (const body of [
+            JSON.stringify({ data: null }),
+            JSON.stringify({ data: [] }),
+            JSON.stringify({ data: { source: {} } }),
+        ]) {
+            const captureMap = {
+                'https://creator.xiaohongshu.com/api/galaxy/creator/datacenter/note/audience/source?note_id=demo-note-id': {
+                    status: 200,
+                    ok: true,
+                    body,
+                },
+            };
+            const page = createPageMock(undefined);
+            page.evaluate = vi.fn(async (script) => {
+                const s = String(script);
+                if (s.includes('window.__xhsCapture =')) return undefined;
+                if (s.includes('history.pushState')) return undefined;
+                if (s.includes('JSON.stringify(window.__xhsCapture')) return JSON.stringify(captureMap);
+                if (s.includes("document.querySelector('.note-title')")) return domData;
+                return null;
+            });
+            await expect(cmd.func(page, { 'note-id': 'demo-note-id' })).rejects.toBeInstanceOf(CommandExecutionError);
+        }
+    });
     it('throws EmptyResultError when the detail page exposes no metrics', async () => {
         const cmd = getRegistry().get('xiaohongshu/creator-note-detail');
         const page = createPageMock(undefined);
