codingsamss/xiaohongshu-session-reader

Xiaohongshu Session Reader

Scope

• Reuse local Chrome logged-in session only.
• Prefer HTTP/API extraction for stability and speed.
• Use Codex Chrome plugin when HTTP/API path is blocked and visible logged-in browser state is needed.
• Use Playwright only when explicitly requested/enabled and Chrome plugin cannot complete the fallback.
• Support:
  • profile card titles (for 谁是卧底词组 collection)
  • note detail (title/desc/author)
  • comments when API permits; otherwise explicit fallback signal
• Do not forge identity, bypass captcha, or brute-force anti-bot checks.

Prerequisite Check

Before extraction:

python3 --version

Fallback-only prerequisite:

codex mcp get playwright-ext  # only for explicit Playwright fallback

Workflow

1. Run HTTP-first reader:

python3 <skill_dir>/scripts/xhs_http_reader.py \
  --url "<xhslink_or_xiaohongshu_url>" \
  --mode auto \
  --max-items 40 \
  --max-comments 20 \
  --pretty

2. If response has fallback.required=false, use returned data directly.
3. If response has fallback.required=true, switch to Codex Chrome plugin fallback:
   • profile: open profile page and read visible card titles.
   • note comments: open note detail and read comments from DOM snapshot.
   • use Playwright only if the user explicitly asks for it and playwright-ext is enabled.
4. Normalize four-word groups with scripts/undercover_parser.py.
5. Persist progress in .cache/xhs_undercover_progress.json for batch tasks.

Block Handling Rules

• If HTTP returns captcha or risk code (for example 300011), do not keep retrying aggressively.
• Degrade once to Chrome plugin fallback and continue extraction.
• If Chrome plugin fallback also lands on captcha/login gate, request user to refresh local login session.
• Never claim detail/comments were obtained via HTTP when response marks fallback required.

Output Contract

Use this structure:

{
  "source": "<xhs link>",
  "captured_at": "YYYY-MM-DD",
  "groups": [
    { "id": 1, "words": ["词A", "词B", "词B", "词B"], "odd": "词A" }
  ]
}

If confidence is low, add note for manual verification.

Resources

• HTTP-first reader: scripts/xhs_http_reader.py
• Cookie exporter (fallback tooling): scripts/export_xhs_cookies.py
• DOM fallback reference: references/extraction-checklist.md
• Group parser: scripts/undercover_parser.py