@skills-store/rednote 0.1.13 → 0.1.15

package/README.md

@@ -36,10 +36,10 @@ For most tasks, run commands in this order:
 rednote env
 rednote browser create --name seller-main --browser chrome --port 9222
 rednote browser connect --instance seller-main
-rednote login --instance seller-main
-rednote status --instance seller-main
-rednote search --instance seller-main --keyword 护肤
-rednote interact --instance seller-main --url "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" --like --collect --comment "写得真好"
+rednote login
+rednote status
+rednote search --keyword 护肤
+rednote interact --url "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" --like --collect --comment "写得真好"
 ```
 
 ## Commands
@@ -68,7 +68,7 @@ Use `env` first when checking installation, runtime info, or storage paths.
 ### `status`
 
 ```bash
-rednote status --instance seller-main
+rednote status
 ```
 
 Use `status` to confirm whether an instance exists, is running, and appears logged in.
@@ -76,7 +76,7 @@ Use `status` to confirm whether an instance exists, is running, and appears logg
 ### `check-login`
 
 ```bash
-rednote check-login --instance seller-main
+rednote check-login
 ```
 
 Use `check-login` when you only want to verify whether the session is still valid.
@@ -84,7 +84,7 @@ Use `check-login` when you only want to verify whether the session is still vali
 ### `login`
 
 ```bash
-rednote login --instance seller-main
+rednote login
 ```
 
 Use `login` after `browser connect` if the instance is not authenticated yet.
@@ -92,32 +92,59 @@ Use `login` after `browser connect` if the instance is not authenticated yet.
 ### `home`
 
 ```bash
-rednote home --instance seller-main --format md --save
+rednote home --format md --save
 ```
 
 Use `home` when you want the current home feed and optionally want to save it to disk.
 
+The terminal output always uses the compact summary format below, even when `--format json` is selected:
+
+```text
+id=<database nanoid>
+title=<post title>
+like=<liked count>
+
+id=...
+title=...
+like=...
+```
+
+Captured home feed posts are upserted into `~/.skills-router/rednote/main.db` (the same path returned by `rednote env`). They are stored in the `rednote_posts` table, and the printed `id` is that table's `nanoid(16)` primary key.
+
 ### `search`
 
 ```bash
-rednote search --instance seller-main --keyword 护肤
-rednote search --instance seller-main --keyword 护肤 --format json --save ./output/search.jsonl
+rednote search --keyword 护肤
+rednote search --keyword 护肤 --format json --save ./output/search.jsonl
 ```
 
 Use `search` for keyword-based note lookup.
 
+The terminal output always uses the compact summary format below, even when `--format json` is selected:
+
+```text
+id=<database nanoid>
+title=<post title>
+like=<liked count>
+```
+
+Captured search results are also upserted into `~/.skills-router/rednote/main.db` in the `rednote_posts` table. The printed `id` can be passed directly to `get-feed-detail --id`.
+
 ### `get-feed-detail`
 
 ```bash
-rednote get-feed-detail --instance seller-main --url "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy"
+rednote get-feed-detail --id <nanoid>
+rednote get-feed-detail --url "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy"
 ```
 
-Use `get-feed-detail` when you already have a Xiaohongshu note URL.
+Use `get-feed-detail` when you already have a Xiaohongshu note URL, or when you have a database `id` returned by `home` or `search`. With `--id`, the CLI looks up the saved URL from `~/.skills-router/rednote/main.db` and then navigates with that raw URL.
+
+Captured note details and comments are also upserted into `~/.skills-router/rednote/main.db` in `rednote_post_details` and `rednote_post_comments`.
 
 ### `get-profile`
 
 ```bash
-rednote get-profile --instance seller-main --id USER_ID
+rednote get-profile --id USER_ID
 ```
 
 Use `get-profile` when you want author or account profile information.
@@ -126,8 +153,8 @@ Use `get-profile` when you want author or account profile information.
 ### `interact`
 
 ```bash
-rednote interact --instance seller-main --url "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" --like --collect
-rednote interact --instance seller-main --url "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" --like --collect --comment "写得真好"
+rednote interact --id <nanoid> --like --collect
+rednote interact --id <nanoid> --like --collect --comment "写得真好"
 ```
 
 Use `interact` when you want the single entrypoint for note operations such as like, collect, and comment in one command. Use `--comment TEXT` for replies; there is no standalone `comment` command.
@@ -137,335 +164,14 @@ Use `interact` when you want the single entrypoint for note operations such as l
 - `--instance NAME` selects the browser instance for account-scoped commands.
 - `--format json` is best for scripting.
 - `--format md` is best for direct reading.
-- `--save` is useful for `home` and `search` when you want saved output.
+- `--save` is useful for `home` and `search` when you want the raw post array written to disk.
 - `--keyword` is required for `search`.
-- `--url` is required for `get-feed-detail`.
+- `home` and `search` always print `id/title/like` summaries to stdout; `--format json` only changes the saved file payload.
+- `get-feed-detail` accepts either `--url URL` or `--id ID`.
 - `--id` is required for `get-profile`.
 - `--url` is required for `interact`; at least one of `--like`, `--collect`, or `--comment TEXT` must be provided.
 - replies are sent with `interact --comment TEXT`.
 
-## JSON success shapes
-
-Use these shapes as the success model when a command returns JSON.
-
-### Shared note item
-
-`home`, `search`, and `profile.notes` share the normalized `RednotePost` shape:
-
-```json
-{
-  "id": "string",
-  "modelType": "string",
-  "xsecToken": "string|null",
-  "url": "string",
-  "noteCard": {
-    "type": "string|null",
-    "displayTitle": "string|null",
-    "cover": {
-      "urlDefault": "string|null",
-      "urlPre": "string|null",
-      "url": "string|null",
-      "fileId": "string|null",
-      "width": "number|null",
-      "height": "number|null",
-      "infoList": [{ "imageScene": "string|null", "url": "string|null" }]
-    },
-    "user": {
-      "userId": "string|null",
-      "nickname": "string|null",
-      "nickName": "string|null",
-      "avatar": "string|null",
-      "xsecToken": "string|null"
-    },
-    "interactInfo": {
-      "liked": "boolean",
-      "likedCount": "string|null",
-      "commentCount": "string|null",
-      "collectedCount": "string|null",
-      "sharedCount": "string|null"
-    },
-    "cornerTagInfo": [{ "type": "string|null", "text": "string|null" }],
-    "imageList": [{ "width": "number|null", "height": "number|null", "infoList": [{ "imageScene": "string|null", "url": "string|null" }] }],
-    "video": { "duration": "number|null" }
-  }
-}
-```
-
-### `env --format json`
-
-`env` is the main exception: it returns a raw environment object instead of `{ "ok": true, ... }`.
-
-```json
-{
-  "packageRoot": "string",
-  "homeDir": "string",
-  "platform": "string",
-  "nodeVersion": "string",
-  "storageHome": "string",
-  "storageRoot": "string",
-  "instancesDir": "string",
-  "instanceStorePath": "string",
-  "legacyPackageInstancesDir": "string"
-}
-```
-
-### Browser commands
-
-`browser list`:
-
-```json
-{
-  "lastConnect": { "scope": "default|custom", "name": "string", "browser": "chrome|edge|chromium|brave" } | null,
-  "instances": [{
-    "type": "chrome|edge|chromium|brave",
-    "name": "string",
-    "executablePath": "string",
-    "userDataDir": "string",
-    "exists": true,
-    "inUse": false,
-    "pid": "number|null",
-    "lockFiles": ["string"],
-    "matchedProcess": { "pid": "number", "name": "string", "cmdline": "string" } | null,
-    "staleLock": false,
-    "remotePort": "number|null",
-    "scope": "default|custom",
-    "instanceName": "string",
-    "createdAt": "string|null",
-    "lastConnect": false
-  }]
-}
-```
-
-`browser create`:
-
-```json
-{
-  "ok": true,
-  "instance": {
-    "name": "string",
-    "browser": "chrome|edge|chromium|brave",
-    "userDataDir": "string",
-    "createdAt": "string",
-    "remoteDebuggingPort": "number|undefined"
-  }
-}
-```
-
-`browser connect`:
-
-```json
-{
-  "ok": true,
-  "type": "chrome|edge|chromium|brave",
-  "executablePath": "string",
-  "userDataDir": "string",
-  "remoteDebuggingPort": "number",
-  "wsUrl": "string",
-  "pid": "number|null"
-}
-```
-
-`browser remove`:
-
-```json
-{
-  "ok": true,
-  "removedInstance": {
-    "name": "string",
-    "browser": "chrome|edge|chromium|brave",
-    "userDataDir": "string",
-    "createdAt": "string",
-    "remoteDebuggingPort": "number|undefined"
-  },
-  "removedDir": true,
-  "closedPids": ["number"]
-}
-```
-
-### Session and account commands
-
-`status`:
-
-```json
-{
-  "ok": true,
-  "instance": {
-    "scope": "default|custom",
-    "name": "string",
-    "browser": "chrome|edge|chromium|brave",
-    "source": "argument|last-connect|single-instance",
-    "status": "running|stopped|missing|stale-lock",
-    "exists": true,
-    "inUse": false,
-    "pid": "number|null",
-    "remotePort": "number|null",
-    "userDataDir": "string",
-    "createdAt": "string|null",
-    "lastConnect": false
-  },
-  "rednote": {
-    "loginStatus": "logged-in|logged-out|unknown",
-    "lastLoginAt": "string|null"
-  }
-}
-```
-
-`check-login`:
-
-```json
-{
-  "ok": true,
-  "rednote": {
-    "loginStatus": "logged-in|logged-out|unknown",
-    "lastLoginAt": "string|null",
-    "needLogin": false,
-    "checkedAt": "string"
-  }
-}
-```
-
-`login`:
-
-```json
-{
-  "ok": true,
-  "rednote": {
-    "loginClicked": true,
-    "pageUrl": "string",
-    "waitingForPhoneLogin": true,
-    "qrCodePath": "string|null",
-    "message": "string"
-  }
-}
-```
-
-### Feed and profile commands
-
-`home --format json`:
-
-```json
-{
-  "ok": true,
-  "home": {
-    "pageUrl": "string",
-    "fetchedAt": "string",
-    "total": "number",
-    "posts": ["RednotePost"],
-    "savedPath": "string|undefined"
-  }
-}
-```
-
-`search --format json`:
-
-```json
-{
-  "ok": true,
-  "search": {
-    "keyword": "string",
-    "pageUrl": "string",
-    "fetchedAt": "string",
-    "total": "number",
-    "posts": ["RednotePost"],
-    "savedPath": "string|undefined"
-  }
-}
-```
-
-`get-feed-detail --format json`:
-
-```json
-{
-  "ok": true,
-  "detail": {
-    "fetchedAt": "string",
-    "total": "number",
-    "items": [{
-      "url": "string",
-      "note": {
-        "noteId": "string|null",
-        "title": "string|null",
-        "desc": "string|null",
-        "type": "string|null",
-        "interactInfo": {
-          "liked": "boolean|null",
-          "likedCount": "string|null",
-          "commentCount": "string|null",
-          "collected": "boolean|null",
-          "collectedCount": "string|null",
-          "shareCount": "string|null",
-          "followed": "boolean|null"
-        },
-        "tagList": [{ "name": "string|null" }],
-        "imageList": [{ "urlDefault": "string|null", "urlPre": "string|null", "width": "number|null", "height": "number|null" }],
-        "video": { "url": "string|null", "raw": "unknown" } | null,
-        "raw": "unknown"
-      },
-      "comments": [{
-        "id": "string|null",
-        "content": "string|null",
-        "userId": "string|null",
-        "nickname": "string|null",
-        "likedCount": "string|null",
-        "subCommentCount": "number|null",
-        "raw": "unknown"
-      }]
-    }]
-  }
-}
-```
-
-`get-profile --format json`:
-
-```json
-{
-  "ok": true,
-  "profile": {
-    "userId": "string",
-    "url": "string",
-    "fetchedAt": "string",
-    "user": {
-      "userId": "string|null",
-      "nickname": "string|null",
-      "desc": "string|null",
-      "avatar": "string|null",
-      "ipLocation": "string|null",
-      "gender": "string|null",
-      "follows": "string|number|null",
-      "fans": "string|number|null",
-      "interaction": "string|number|null",
-      "tags": ["string"],
-      "raw": "unknown"
-    },
-    "notes": ["RednotePost"],
-    "raw": {
-      "userPageData": "unknown",
-      "notes": "unknown"
-    }
-  }
-}
-```
-
-### Action commands
-
-`publish`:
-
-```json
-{
-  "ok": true,
-  "message": "string"
-}
-```
-
-`interact`:
-
-```json
-{
-  "ok": true,
-  "message": "string"
-}
-```
-
 ## Storage
 
 The CLI stores browser instances and metadata under:

package/dist/index.js

@@ -20,7 +20,7 @@ Commands:
   check-login [--instance NAME]
   login [--instance NAME]
   publish [--instance NAME]
-  interact [--instance NAME] --url URL [--like] [--collect] [--comment TEXT]
+  interact [--instance NAME] [--id ID | --url URL] [--like] [--collect] [--comment TEXT]
   home [--instance NAME] [--format md|json] [--save [PATH]]
   search [--instance NAME] --keyword TEXT [--format md|json] [--save [PATH]]
   get-feed-detail [--instance NAME] --url URL [--format md|json]
@@ -32,7 +32,7 @@ Examples:
   npx -y @skills-store/rednote browser connect --instance seller-main
   npx -y @skills-store/rednote env
   npx -y @skills-store/rednote publish --instance seller-main --type video --video ./note.mp4 --title 标题 --content 描述
-  npx -y @skills-store/rednote interact --instance seller-main --url "https://www.xiaohongshu.com/explore/xxx?xsec_token=yyy" --like --collect --comment "写得真好"
+  npx -y @skills-store/rednote interact --instance seller-main --id NOTE_ID --like --collect --comment "写得真好"
   npx -y @skills-store/rednote search --instance seller-main --keyword 护肤
 `);
 }

package/dist/rednote/env.js

@@ -28,6 +28,7 @@ function renderEnvironmentMarkdown() {
         `- Package Root: ${info.packageRoot}`,
         `- Storage Home: ${info.storageHome}`,
         `- Storage Root: ${info.storageRoot}`,
+        `- Database: ${info.databasePath}`,
         `- Instances Dir: ${info.instancesDir}`,
         `- Instance Store: ${info.instanceStorePath}`,
         `- Legacy Package Instances: ${info.legacyPackageInstancesDir}`,

package/dist/rednote/getFeedDetail.js

@@ -3,20 +3,23 @@ import * as cheerio from 'cheerio';
 import { parseArgs } from 'node:util';
 import vm from 'node:vm';
 import { runCli } from '../utils/browser-cli.js';
+import { simulateMouseMove, simulateMousePresence, simulateMouseWheel } from '../utils/mouse-helper.js';
 import { resolveStatusTarget } from './status.js';
 import { createRednoteSession, disconnectRednoteSession, ensureRednoteLoggedIn } from './checkLogin.js';
 import { ensureJsonSavePath, renderJsonSaveSummary, resolveJsonSavePath, writeJsonFile } from './output-format.js';
+import { findPersistedPostUrlByRecordId, initializeRednoteDatabase, persistFeedDetail } from './persistence.js';
 function printGetFeedDetailHelp() {
     process.stdout.write(`rednote get-feed-detail
 
 Usage:
-  npx -y @skills-store/rednote get-feed-detail [--instance NAME] --url URL [--url URL] [--comments [COUNT]] [--format md|json] [--save PATH]
-  node --experimental-strip-types ./scripts/rednote/getFeedDetail.ts --instance NAME --url URL [--url URL] [--comments [COUNT]] [--format md|json] [--save PATH]
-  bun ./scripts/rednote/getFeedDetail.ts --instance NAME --url URL [--url URL] [--comments [COUNT]] [--format md|json] [--save PATH]
+  npx -y @skills-store/rednote get-feed-detail [--instance NAME] [--url URL] [--url URL] [--id ID] [--id ID] [--comments [COUNT]] [--format md|json] [--save PATH]
+  node --experimental-strip-types ./scripts/rednote/getFeedDetail.ts --instance NAME [--url URL] [--url URL] [--id ID] [--id ID] [--comments [COUNT]] [--format md|json] [--save PATH]
+  bun ./scripts/rednote/getFeedDetail.ts --instance NAME [--url URL] [--url URL] [--id ID] [--id ID] [--comments [COUNT]] [--format md|json] [--save PATH]
 
 Options:
   --instance NAME   Optional. Defaults to the saved lastConnect instance
-  --url URL         Required. Xiaohongshu explore url, repeatable
+  --url URL         Optional. Xiaohongshu explore url, repeatable
+  --id ID           Optional. Database record id from home/search output, repeatable
   --comments [COUNT]  Optional. Include comment data. When COUNT is provided, scroll \`.note-scroller\` until COUNT comments, the end, or timeout
   --format FORMAT   Output format: md | json. Default: md
   --save PATH       Required when --format json is used. Saves the selected result array as JSON
@@ -46,6 +49,7 @@ function parseCommentsValue(value) {
 export function parseGetFeedDetailCliArgs(argv) {
     const values = {
         urls: [],
+        ids: [],
         format: 'md',
         comments: undefined,
         help: false
@@ -80,6 +84,19 @@ export function parseGetFeedDetailCliArgs(argv) {
             index += 1;
             continue;
         }
+        if (withEquals?.key === '--id') {
+            values.ids.push(withEquals.value);
+            continue;
+        }
+        if (arg === '--id') {
+            const nextArg = argv[index + 1];
+            if (!nextArg || nextArg.startsWith('-')) {
+                throw new Error('Missing required option value: --id');
+            }
+            values.ids.push(nextArg);
+            index += 1;
+            continue;
+        }
         if (withEquals?.key === '--format') {
             values.format = withEquals.value;
             continue;
@@ -138,20 +155,6 @@ function validateFeedDetailUrl(url) {
         throw error;
     }
 }
-function normalizeFeedDetailUrl(url) {
-    try {
-        const parsed = new URL(url);
-        if (!parsed.searchParams.has('xsec_source')) {
-            parsed.searchParams.set('xsec_source', 'pc_feed');
-        }
-        return parsed.toString();
-    } catch (error) {
-        if (error instanceof TypeError) {
-            throw new Error(`url is not valid: ${url}`);
-        }
-        throw error;
-    }
-}
 async function getOrCreateXiaohongshuPage(session) {
     return session.page;
 }
@@ -179,7 +182,10 @@ async function scrollCommentsContainer(page, targetCount, getCount) {
         return;
     }
     await container.scrollIntoViewIfNeeded().catch(()=>{});
-    await container.hover().catch(()=>{});
+    await simulateMouseMove(page, {
+        locator: container,
+        settleMs: 100
+    }).catch(()=>{});
     const getMetrics = async ()=>await container.evaluate((element)=>{
             const htmlElement = element;
             const atBottom = htmlElement.scrollTop + htmlElement.clientHeight >= htmlElement.scrollHeight - 8;
@@ -202,8 +208,12 @@ async function scrollCommentsContainer(page, targetCount, getCount) {
         }
         const beforeCount = getCount();
         const delta = Math.max(Math.floor(beforeMetrics.clientHeight * 0.85), 480);
-        await page.mouse.wheel(0, delta).catch(()=>{});
-        await page.waitForTimeout(900);
+        await simulateMouseWheel(page, {
+            locator: container,
+            deltaY: delta,
+            moveBeforeScroll: false,
+            settleMs: 900
+        }).catch(()=>{});
         const afterMetrics = await getMetrics();
         await page.waitForTimeout(400);
         const afterCount = getCount();
@@ -298,7 +308,7 @@ function renderDetailMarkdown(items, includeComments = false) {
         return lines.join('\n');
     }).join('\n\n---\n\n')}\n`;
 }
-async function captureFeedDetail(page, targetUrl, commentsOption = undefined) {
+async function captureFeedDetail(page, targetUrl, commentsOption = undefined, instanceName) {
     const includeComments = hasCommentsEnabled(commentsOption);
     const commentsTarget = typeof commentsOption === 'number' ? commentsOption : null;
     let note = null;
@@ -342,6 +352,7 @@ async function captureFeedDetail(page, targetUrl, commentsOption = undefined) {
         await page.goto(targetUrl, {
             waitUntil: 'domcontentloaded'
         });
+        await simulateMousePresence(page);
         const deadline = Date.now() + 15_000;
         while(Date.now() < deadline){
             if (note && commentsLoaded) {
@@ -355,7 +366,7 @@ async function captureFeedDetail(page, targetUrl, commentsOption = undefined) {
         if (includeComments && commentsTarget) {
             await scrollCommentsContainer(page, commentsTarget, ()=>getCommentCount(commentsMap));
         }
-        return {
+        const item = {
             url: targetUrl,
             note: normalizeDetailNote(note),
             ...includeComments ? {
@@ -364,17 +375,28 @@ async function captureFeedDetail(page, targetUrl, commentsOption = undefined) {
                 ])
             } : {}
         };
+        if (instanceName) {
+            await persistFeedDetail({
+                instanceName,
+                url: targetUrl,
+                note: item.note,
+                rawNote: note,
+                rawComments: includeComments ? [
+                    ...commentsMap.values()
+                ] : []
+            });
+        }
+        await simulateMousePresence(page);
+        return item;
     } finally{
         page.off('response', handleResponse);
     }
 }
-export async function getFeedDetails(session, urls, commentsOption = undefined) {
+export async function getFeedDetails(session, urls, commentsOption = undefined, instanceName) {
     const page = await getOrCreateXiaohongshuPage(session);
     const items = [];
     for (const url of urls){
-        const normalizedUrl = normalizeFeedDetailUrl(url);
-        validateFeedDetailUrl(normalizedUrl);
-        items.push(await captureFeedDetail(page, normalizedUrl, commentsOption));
+        items.push(await captureFeedDetail(page, url, commentsOption, instanceName));
     }
     return {
         ok: true,
@@ -385,6 +407,25 @@ export async function getFeedDetails(session, urls, commentsOption = undefined)
         }
     };
 }
+async function resolveFeedDetailUrls(values, instanceName) {
+    const urls = [
+        ...values.urls
+    ];
+    if (values.ids.length === 0) {
+        return urls;
+    }
+    if (!instanceName) {
+        throw new Error('The --id option requires an instance-backed session.');
+    }
+    for (const id of values.ids){
+        const url = await findPersistedPostUrlByRecordId(instanceName, id);
+        if (!url) {
+            throw new Error(`No saved post url found for id: ${id}`);
+        }
+        urls.push(url);
+    }
+    return urls;
+}
 function selectFeedDetailOutput(result) {
     return result.detail.items;
 }
@@ -400,6 +441,7 @@ function writeFeedDetailOutput(result, values) {
 }
 export async function runGetFeedDetailCommand(values = {
     urls: [],
+    ids: [],
     format: 'md'
 }) {
     if (values.help) {
@@ -407,14 +449,16 @@ export async function runGetFeedDetailCommand(values = {
         return;
     }
     ensureJsonSavePath(values.format, values.savePath);
-    if (values.urls.length === 0) {
-        throw new Error('Missing required option: --url');
+    if (values.urls.length === 0 && values.ids.length === 0) {
+        throw new Error('Missing required option: --url or --id');
     }
+    await initializeRednoteDatabase();
     const target = resolveStatusTarget(values.instance);
     const session = await createRednoteSession(target);
     try {
         await ensureRednoteLoggedIn(target, 'fetching feed detail', session);
-        const result = await getFeedDetails(session, values.urls, values.comments);
+        const urls = await resolveFeedDetailUrls(values, target.instanceName);
+        const result = await getFeedDetails(session, urls, values.comments, target.instanceName);
         writeFeedDetailOutput(result, values);
     } finally{
         await disconnectRednoteSession(session);