xhs-ts（XHS TS 搜索）

---name: xhs-ts description: | Automate Xiaohongshu (小红书/RedNote) operations via Playwright CLI — search notes, publish image/video posts, interact (like/collect/comment/follow), scrape data, manage multiple accounts with isolated cookies and anti-detection. Use when user mentions 小红书, xhs, Xiaohongshu, RedNote, 红书, 小红书运营, or works with xhs-ts/ directory, or wants to login, search, publish, interact, scrape, or manage multiple Xiaohongshu accounts. license: MIT compatibility: opencode metadata: version: "0.1.1" homepage: "https://github.com/lv-saharan/skills/tree/main/xhs-ts" openclaw: emoji: "📕" requires: bins: [node, npx] install: - id: node kind: node packages: [playwright, tsx, commander, dotenv] label: "Install dependencies (playwright, tsx, commander, dotenv)"

Xiaohongshu Automation Skill (xhs-ts)

Quick Reference

All commands support --user <name> for multi-account operations. Usage: npm run <command> -- [args] -- [options] Example: npm run search -- "美食" -- --limit 10 --user "小号"

Gotchas

Authentication

1. Cookie expiry — Session cookies expire after ~30 days; NOT_LOGGED_IN → run npm run login
2. Comment requires phone binding — Unbound accounts get 评论受限: 绑定手机
3. URL must include xsec_token — Direct URLs may not work; use npm run search to get complete URLs

Anti-Detection

1. Rate limiting — Keep 2-5 second intervals between operations
2. Headless auto-detection — Linux servers (no DISPLAY) automatically force headless mode
3. QR code file path — Headless mode: QR saved to users/{user}/tmp/qr_login_*.png

Platform Limits

1. Short links not supported — xhslink.com URLs will fail; use full URLs
2. Publish detection risk — Xiaohongshu may block automated publishing; test with secondary account

Multi-User Management

xhs-ts supports multiple Xiaohongshu accounts with isolated cookies and temporary files.

Directory Structure

xhs-ts/
├── users/                    # Multi-user directory
│   ├── users.json            # User metadata (current user, version: 3)
│   ├── default/              # Default user
│   │   ├── user-data/        # Playwright persistent context (auto-saves cookies, localStorage)
│   │   ├── profile.json      # Unified Profile data (meta + connection)
│   │   ├── fingerprint.json  # Device fingerprint
│   │   └── tmp/              # Temporary files (QR codes)
│   └── {username}/           # Same structure as default/
│       ├── user-data/
│       ├── profile.json
│       ├── fingerprint.json
│       └── tmp/

Version 3 Changes: meta.json merged into profile.json with meta and connection fields.

User Selection Priority

--user <name>  >  users.json current  >  default

Commands

# List all users
npm run user

# Set current user
npm run user:use -- "小号"
# Or: npm run user -- --set-current "小号"

# Reset to default user
npm run user -- --set-default

# Clean up corrupted user data (when login fails with USER_DATA_CORRUPTED)
npm run user -- --cleanup '<用户名>'

# Login with specific user
npm run login -- --user "小号"

# Search with specific user
npm run search -- "美食" --user "小号"

Error Recovery: Corrupted User Data

When login fails with USER_DATA_CORRUPTED error, the output includes suggestCleanup: true:

{
  "error": true,
  "code": "USER_DATA_CORRUPTED",
  "suggestCleanup": true,
  "canCleanup": true,
  "hint": "用户数据可能已损坏。请运行 npm run user -- --cleanup <用户名> 清理后重新登录。"
}

Agent workflow:

1. Detect suggestCleanup: true in error output
2. Ask user: "用户数据可能已损坏，是否执行清理？"
3. If user confirms: run npm run user -- --cleanup <用户名>
4. After cleanup succeeds: run npm run login -- --user <用户名>

Safety check: Cleanup is blocked (canCleanup: false) if browser is running for that user. Close browser first with npm run browser -- --stop-user <用户名>.

Output Format

All commands output JSON to stdout. The toAgent field provides actionable instructions.

toAgent Format

ACTION[:TARGET][:HINT]

Channel-Specific Formatting

When toAgent is PARSE:notes, format output based on channel type:

完整格式规范、JSON 模板、回调处理见 references/channel-integration.md

Commands

Login

# QR code login (default)
npm run login

# Headless mode (QR saved to file)
npm run login -- --headless

# SMS login
npm run login -- --sms

# SMS login with phone number
npm run login -- --sms --phone "13800138000"

# Cookie string login (direct import)
npm run login -- --cookie-string "a1=xxx; webId=xxx; ..."

# Login with specific user
npm run login -- --user "小号"

Search

# Basic search
npm run search -- "美食探店"

# With filters
npm run search -- "美食探店" --limit 10 --sort hot --note-type image --time-range week

# Search followed users only
npm run search -- "美食探店" --scope following

Output formatting: For sending results to Feishu/WeChat, see references/channel-integration.md

Publish

# Publish image note
npm run publish -- --title "标题" --content "正文" --images "img1.jpg,img2.jpg"

# Publish video note
npm run publish -- --title "标题" --content "正文" --video "video.mp4"

# With tags
npm run publish -- --title "标题" --content "正文" --images "img1.jpg" --tags "美食,探店"

⚠️ Warning: Xiaohongshu may detect and block automated publishing. Use secondary account for testing.

Interact (Like, Collect, Comment, Follow)

All interact commands require:

• Login: Must be logged in
• Valid URL: URLs must include xsec_token parameter

Use npm run search to get complete URLs with tokens.

Like

# Single note
npm run like -- "https://www.xiaohongshu.com/explore/noteId?xsec_token=xxx"

# Multiple notes (batch)
npm run like -- "url1" "url2" "url3"

# Custom delay between likes (default: 2000ms)
npm run like -- "url1" "url2" --delay 3000

Collect (Bookmark)

# Single note
npm run collect -- "https://www.xiaohongshu.com/explore/noteId?xsec_token=xxx"

# Multiple notes (batch)
npm run collect -- "url1" "url2"

# Custom delay between collects (default: 2000ms)
npm run collect -- "url1" "url2" --delay 3000

Comment

# Comment on a note
npm run comment -- "https://www.xiaohongshu.com/explore/noteId?xsec_token=xxx" "评论内容"

# With specific user
npm run comment -- "url" "评论内容" --user "小号"

⚠️ Phone Binding Required: Accounts without phone number cannot comment. Error: 评论受限: 绑定手机

Follow

# Follow single user
npm run follow -- "https://www.xiaohongshu.com/user/profile/userId"

# Follow multiple users (batch)
npm run follow -- "url1" "url2"

# Custom delay between follows (default: 2000ms)
npm run follow -- "url1" "url2" --delay 3000

Scrape

Scrape Note

# Basic scrape
npm run scrape-note -- "https://www.xiaohongshu.com/explore/noteId?xsec_token=xxx"

# Include comments
npm run scrape-note -- "url" --comments --max-comments 50

Output: noteId, title, content, images, video, author, stats, tags, publishTime, location

Scrape User

# Basic scrape
npm run scrape-user -- "https://www.xiaohongshu.com/user/profile/userId"

# Include recent notes
npm run scrape-user -- "url" --notes --max-notes 24

Output: userId, name, avatar, bio, stats, tags, recentNotes

Browser Management

Browser instances run in detached mode and persist after CLI exits. Agent is responsible for closing idle browsers.

# Start browser instance
npm run browser -- --start
npm run browser -- --start --user "小号"
npm run browser -- --start --headless

# Show status (includes lastActivityAt timestamp)
npm run browser -- --status

# List saved connections
npm run browser -- --list

# Stop instances
npm run browser -- --stop-user "小号"  # Stop specific user
npm run browser -- --stop              # Stop all instances

Agent Responsibility: Check lastActivityAt from --status output. Close idle browsers (e.g., inactive for 20+ minutes) to free resources.

Agent Workflow

Typical User Requests

Error Handling Flow

1. 命令返回 NOT_LOGGED_IN → npm run login
2. 命令返回 USER_DATA_CORRUPTED → 询问用户 → npm run user -- --cleanup
3. 命令返回 RATE_LIMITED → 等待 30s → 重试
4. 浏览器空闲 20+ 分钟 → npm run browser -- --stop

Full error code reference: references/troubleshooting.md

References

• Installation Guide
• Configuration

• Channel Integration
• Troubleshooting