xhs-skill

This skill is a merged version of

xhs-*

, designed to allow users to start using it with just one command:

clawhub install xhs-skill

Constraints:

All browser interactions (open page/click/input/upload/screenshot/login/export) must be delegated to
```
agent-browser-stealth
```
.
It is prohibited to write/maintain publishing orchestration scripts (such as
```
publish_from_payload
```
) in this repository; publishing actions must be executed by
```
agent-browser-stealth
```
within the session.
```
agent-browser
```
is prohibited (old channel disabled, unified use of
```
agent-browser-stealth
```
).
All sensitive data (cookies, exported files, screenshots) can only be stored in the local
```
data/
```
directory, and must not be pasted into chats.

Hard Execution Constraints (Stability):

Concurrent operations are prohibited in the same
```
agent-browser-stealth
```
session (execute serially), otherwise it may easily trigger false failures with
```
os error 35
```
.
The ref of
```
snapshot
```
will drift:
```
snapshot -i
```
must be re-captured before and after key actions, with secondary positioning fallback using
```
placeholder/role/text
```
.
Scanning the QR code does not equal successful login; post-verification must be performed (see Section A "Login Success Criteria" below).

Installation

bash

clawhub install xhs-skill
cd skills/xhs-skill
npm i

Note:

npm i

is only for the local CLI built into this skill (QR code decoding, cookies tools). If you don't need to decode QR codes/convert cookies, you can also use

agent-browser-stealth

alone to complete scanning and export.

Local Directory Convention

It is recommended to prepare the following in the working directory where you run commands:

```
data/xhs_login_qr.png
```
: Screenshot of the login page QR code (PNG)
```
data/raw_cookies.json
```
: Exported raw cookies (JSON)
```
data/xhs_cookies.json
```
: Normalized cookies (JSON)
```
data/exports/<YYYY-MM-DD>/
```
: Exported data (CSV/XLSX/screenshots)
```
data/assets/<YYYY-MM-DD>/
```
: Icons/visual materials for note publishing and source records

bash

mkdir -p data

A. Login (QR Code) and Save Cookies

Objective: Log in to Xiaohongshu Creator Center and export cookies to avoid frequent repeated logins.

Use
```
agent-browser-stealth
```
to open the login page:

```
https://creator.xiaohongshu.com/login
```
If the default display is "Phone/Verification Code Login", click "Scan QR Code" to switch to the QR code view

Let
```
agent-browser-stealth
```
take a screenshot of the QR code and save it as
```
data/xhs_login_qr.png
```
(Optional) Use the local CLI to decode the QR code text and print the ASCII QR code:

bash

node ./bin/xhs-skill.mjs qr show --in ./data/xhs_login_qr.png

OpenClaw Return Specification (Mandatory):

It is prohibited to only return the file path (e.g., only
```
data/xhs_login_qr.png
```
).
You must first execute
```
node ./bin/xhs-skill.mjs qr show --in ./data/xhs_login_qr.png
```
, then directly send the output QR code text + ASCII QR code to the user.
If the session supports image rendering, attach the absolute path of the QR code screenshot (or image attachment) as a supplement.
After sending the QR code, you must pause and wait for the user to confirm "Scanned" before proceeding with cookie export.

Recommended Return Template:

text

Please scan this QR code with the Xiaohongshu App to log in.
QR Code Text: <qr_text>
<ASCII QR>

After scanning and logging in with the Xiaohongshu App, export cookies to
```
data/raw_cookies.json
```
(without using DevTools):

bash

agent-browser-stealth cookies --json > ./data/raw_cookies.json

Normalize cookies and save to
```
data/xhs_cookies.json
```
:

bash

node ./bin/xhs-skill.mjs cookies normalize --in ./data/raw_cookies.json --out ./data/xhs_cookies.json
node ./bin/xhs-skill.mjs cookies status --in ./data/xhs_cookies.json

5.1 It is recommended to use a script for post-verification (executable gatekeeper):

bash

# Example: First let agent-browser-stealth record the current URL and the URL after backend detection
CURRENT_URL="$(agent-browser-stealth get url)"
agent-browser-stealth open https://creator.xiaohongshu.com/creator/home
PROBE_FINAL_URL="$(agent-browser-stealth get url)"

node ./scripts/verify_login.mjs \
  --cookies ./data/xhs_cookies.json \
  --current-url "$CURRENT_URL" \
  --probe-final-url "$PROBE_FINAL_URL" \
  --json

Both of the following 2 conditions must be met to report "Login Completed" (
```
web_session
```
is no longer a hard dependency):
The current URL has left
```
/login
```
The creator backend page is accessible, and there is no 401/redirect to login
Bonus: The cookies contain a "session-like cookie" (e.g.,
```
web_session
```
, or a cookie name containing
```
session
```
). Even without it, it may still work, but stability will be worse.
If any mandatory condition is not met, you must report "Login Failed/Incomplete" and retry the login process; false success reports are prohibited.

json

{
  "task": "xhs_login",
  "ok": true,
  "checks": {
    "left_login": true,
    "backend_not_rejected": true,
    "has_session_like_cookie": true
  },
  "artifacts": {
    "qr_png": "data/xhs_login_qr.png",
    "raw_cookies": "data/raw_cookies.json",
    "normalized_cookies": "data/xhs_cookies.json"
  }
}

When failed,

ok=false

, and the failed items are returned (e.g., still in

/login

, or probe redirects); outputting "Completed" is prohibited.

(Optional) Generate
```
Cookie:
```
header:

bash

node ./bin/xhs-skill.mjs cookies to-header --in ./data/xhs_cookies.json

Failure Fallback:

QR code decoding failed: Usually because the QR code view was not switched to or the QR code is too small; let
```
agent-browser-stealth
```
zoom in and re-screenshot (still as PNG).
Cookie normalization failed: Keep the original
```
data/raw_cookies.json
```
, and expand the compatibility branch later.

A1. Anti-blocking/Throttling Operation Specifications (Mandatory)

Core Conclusion: Xiaohongshu's risk control mainly focuses on "rhythm + fingerprint + behavior + IP + account weight". The tool itself is not the main cause; the usage method is.

Mandatory Strategies:

Human-like Rhythm:

Continuous clicks/fills without pauses are prohibited; random pauses (recommended
```
1.2s~7s
```
) must be added between key actions.
For input, prioritize
```
type --delay
```
(character by character) to avoid full instant
```
fill
```
.

Fixed Fingerprint:

When running the publishing process, prioritize fixing
```
--profile
```
and enabling
```
--headed
```
.
It is recommended to reuse the same profile directory for the same account for a long time; do not create a temporary environment every time.

Publishing Frequency Gatekeeper:

Default
```
24h <= 3
```
posts for the same profile.
Default minimum interval between two posts is
```
30
```
minutes.
If the gatekeeper is triggered, the process must be aborted; forced publishing is not allowed.

Pre-publishing Warm-up Behavior:

First perform a short normal browse (stay on homepage/creator backend + scroll), then enter the publishing page.
"Submit immediately after opening the page" is prohibited.

Network and Device:

Data center IPs/frequent proxy switching are prohibited.
Prioritize home network or mobile hotspot; try to keep the device/IP stable for the same account.

Handling After Throttling:

Throttling: Stop automation, return to manual normal use for
```
3~7
```
days.
Account banned: Only appeal is available; when switching accounts, you must also replace
```
profile + IP + device environment
```
.

B. Publish Notes (Image/Video)

Input (Provided by User):

Note type: Image/Video
Title, body, tags (required)
Topic (required; must be "Today's Hot Topic" for hot topic publishing)
Image/video path (absolute local path preferred)
Icon/visual material requirements (optional): Keywords, style (flat/skeuomorphic/linear), main color, transparent background or not
Hot topic source (required): Source name, source URL, source date (
```
YYYY-MM-DD
```
)

Publishing Hard Gatekeepers (Mandatory):

First organize the publishing materials into
```
data/publish_payload.json
```
(example):

json

{
  "topic": "Today's Hot Topic: xxxx",
  "source": {
    "name": "CCTV News",
    "url": "https://example.com/news",
    "date": "2026-02-12",
    "evidence_snippet": "On February 12, this media report mentioned:......",
    "key_facts": ["Key Fact 1 (including numbers/dates/source mentions)", "Key Fact 2 (including numbers/dates/source mentions)"]
  },
  "post": {
    "title": "Example title within 20 characters",
    "body": "Body with no less than 80 words......",
    "tags": ["#HotTopic", "#TodayNews", "#XiaohongshuOperation"],
    "real_topics": ["#ArtificialIntelligence", "#AII资讯", "#TechnologyObservation"],
    "media": ["/abs/path/cover.png", "/abs/path/card_1.png"]
  }
}

Must execute the verification script before publishing:

bash

# Normal mode
node ./scripts/verify_publish_payload.mjs --in ./data/publish_payload.json --policy ./config/verify_publish_policy.json --tag-registry ./data/tag_registry.json --min-registry-tags 12 --require-source-evidence on --strict-anti-ai on --json

# Today's Hot Topic mode (mandatory source.date = today)
node ./scripts/verify_publish_payload.mjs --in ./data/publish_payload.json --policy ./config/verify_publish_policy.json --tag-registry ./data/tag_registry.json --min-registry-tags 12 --require-source-evidence on --strict-anti-ai on --mode hot --json

Must execute the content review script (layered rules + AI) before publishing:

bash

node ./scripts/review_publish_payload.mjs --in ./data/publish_payload.json --policy ./config/review_policy.json --taxonomy ./config/review_taxonomy.json --ai-provider auto --require-ai off --mode hot --json

Only when both verification and review results are
```
ok=true
```
can you enter the publishing page and click "Publish/Submit". The verification policy is in
```
./config/verify_publish_policy.json
```
, the review policy is in
```
./config/review_policy.json
```
, and the layered risk path is in
```
./config/review_taxonomy.json
```
.
If any gatekeeper fails, the process must be aborted and prompt the user to supplement; "Direct publishing with only screenshots" is prohibited.

Prohibited Links (Mandatory):

Any links or domain name forms (
```
http/https
```
,
```
www.
```
,
```
xxx.com/.cn/...
```
) are prohibited in titles/bodies/tags. Otherwise, there is a risk of account banning.
If content generation encounters difficulties or verification fails: It is better to abort than to "publish a random note".

Anti-AI Detection and Real Tags (Mandatory):

We do not guarantee "100% not detected as AI"; the goal is to significantly reduce the risk.
The body must have "personal perspective + specific fact signals (numbers/dates/source mentions)", and avoid template-style language.
Before publishing, you must pass the
```
review_publish_payload
```
review gatekeeper, requiring
```
decision=pass
```
, and output
```
risk_path
```
, evidence, and
```
review_queue
```
for recheck.
```
source.evidence_snippet
```
and
```
source.key_facts
```
are required, and must be traceable to source facts.
Both tags and
```
post.real_topics
```
must come from the real topic pool
```
data/tag_registry.json
```
; self-created tags are prohibited.
Automatically appending
```
#tags
```
to the body to pretend to be topics is prohibited.
Before publishing, you must manually select at least 3 real topics on the Xiaohongshu publishing page, then let
```
agent-browser-stealth
```
execute the final click to publish.

Example: Prepare a real tag pool (recommended to update daily):

bash

cat > ./data/tag_registry.json <<'JSON'
{
  "updated_at": "2026-02-24",
  "source": {
    "platform": "xiaohongshu",
    "method": "manual_from_publish_topic_picker",
    "url": "https://creator.xiaohongshu.com/creator/publish"
  },
  "tags": ["#AIHotTopic", "#ArtificialIntelligence", "#IndustryObservation", "#TechnologyNews", "#AII资讯", "#TechnologyObservation"]
}
JSON

Publishing Execution Method (Only One):

This repository is only responsible for "data preparation + gatekeeper verification + review verification"; no publishing automation scripts are provided.
Browser actions must be executed serially by
```
agent-browser-stealth
```
: Open publishing page -> Upload materials -> Fill in title/body/tags -> Manually select real topics -> Manual confirmation of preview -> Click publish.
If any gatekeeper fails (
```
verify/review
```
is not
```
ok=true
```
), the process must be stopped before publishing; continuing to click submit is prohibited.

Publishing Reliability Checklist (Follow this to avoid "Seems published but actually not/fields not saved"):

Body line breaks: Normalize
```
\\n
```
to real line breaks (
```
text.replaceAll("\\\\n", "\n")
```
) before writing to the editor; immediately read back and verify that the body
```
innerText
```
does not contain the literal
```
\\n
```
.
After writing the title/body/tags, read back and verify: Title exists and
```
<= 20
```
characters; body is non-empty and meets length requirements; at least 3 tags, all starting with
```
#
```
, and from
```
tag_registry
```
.
In the read-back gatekeeper, also verify
```
post.real_topics
```
(>=3, and all hit
```
tag_registry
```
) to avoid "fake topics".
Body editing area: It may not be a normal input/textarea; first use
```
snapshot -i
```
to confirm the editable area, then write and read back for verification.
Publish button: There may be multiple "Publish" entries on the page; you must click the main button that is "visible + enabled + strictly matches the text"; after clicking, use URL/page status to confirm that it has redirected to the success/management page.
Image re-upload: If replacement is needed, first click "Clear" and select "Re-upload" in the pop-up; wait for the number of thumbnails to stabilize before proceeding.
Image size: Screenshots of
```
1280x720
```
will result in poor preview; use the gatekeeper to verify that images are vertical 3:4 (recommended
```
1242x1660
```
) before publishing.
Serial execution: Strictly serial in the same
```
agent-browser-stealth
```
session; use
```
sleep/wait
```
if necessary to avoid false failures with
```
os error 35
```
.

Publishing Success Closure (Mandatory):

After publishing/updating, return to the "Note Management" list page and confirm that the thumbnail/title has changed.
Re-open the edit page of the note, read back and verify:
```
title/body/imgCount/tags
```
all exist and meet the gatekeeper requirements (otherwise judge as failed and retry).

Material Preparation (Optional, saves users from finding icons/visuals themselves):

The user only provides "requirement description", for example:

"A red heart linear icon with transparent background"
"Light-colored sticker-style small icons suitable for beauty notes"

Use
```
agent-browser-stealth
```
to search and select 3-5 candidates (prioritize royalty-free/reusable sources). 2.1 Visual Material "Content Consistency" Gatekeeper (Highly Recommended):

Before saving the screenshot to the library, first use
```
agent-browser-stealth get title
```
/read
```
h1
```
to check that the page content indeed contains the target keywords (otherwise it may be a wrong click/wrong page).
For stronger consistency, use OCR (optional), but by default, first perform low-cost verification with
```
title/h1
```
.

Use
```
agent-browser-stealth
```
to directly take screenshots and save to:

data/assets/<YYYY-MM-DD>/icons/<name>.png

Append the source URL to:
```
data/assets/<YYYY-MM-DD>/sources.txt
```

Enter the publishing page, upload media as usual, and set a manual confirmation point before clicking "Publish/Submit" (confirm preview is correct before publishing).

Process (All browser-side operations are completed by

agent-browser-stealth

Ensure logged in (complete Section A above, or have a valid login state).
Prepare and verify
```
data/publish_payload.json
```
(must be
```
ok=true
```
).
Open the publishing page (path changes are allowed).
Upload media (multiple images for image-text notes/video files and cover).
Fill in title/body/topics/tags:

Title must be
```
8~20
```
characters (if exceeding 20 characters, first crop or prompt the user to shorten it)
Body must be
```
>= 80
```
words
At least 3 tags, all starting with
```
#
```
```
post.real_topics
```
must be at least 3, and both tags and real topics must hit
```
data/tag_registry.json
```
(real topic pool)
"Direct publishing with only screenshot materials" (such as only containing
```
screenshot/login_qr
```
and other screenshot files) is prohibited
Do not assume the body editing area is a normal input; first use
```
snapshot -i
```
to locate the editable area
Refresh the ref before each click/fill to avoid ref drift and misoperation

Pause before clicking "Publish/Submit", and require the user to confirm the final preview. 6.1 Manually select at least 3 real topics before publishing, then let
```
agent-browser-stealth
```
click submit.
After publishing, record the result page URL; if failed, take a screenshot and record the error message.

Publishing Result Output Contract (JSON):

json

{
  "task": "xhs_publish",
  "ok": true,
  "result_url": "https://creator.xiaohongshu.com/....",
  "content_checks": {
    "title_len": 18,
    "body_len": 136,
    "tag_count": 3,
    "topic": "Today's Hot Topic: xxxx",
    "source_date": "2026-02-12"
  },
  "artifacts": {
    "payload_json": "data/publish_payload.json",
    "media_inputs": ["..."],
    "error_screenshot": null
  }
}

When publishing fails,

ok=false

, and return

error_message

error_screenshot

path, and unpassed

missing_checks

C. Export Creator Center Data (CSV/XLSX or Screenshots)

Objective: Export key data from the Creator Center to

data/exports/<YYYY-MM-DD>/

for subsequent analysis.

Confirm logged in.
Use
```
agent-browser-stealth
```
to enter the commonly used analysis pages of the Creator Center (dashboard/content analysis/fan analysis).
For each page:

Prioritize using the page's built-in export (if available) to
```
data/exports/<date>/
```
If no export is available: Save screenshots of key blocks to the same directory

Record: Export time range, caliber description, page URL.

Local CLI (Built into This Skill)

Commands:

node ./bin/xhs-skill.mjs qr show --in <pngPath>

node ./bin/xhs-skill.mjs cookies normalize --in <jsonPath> --out <outPath>

node ./bin/xhs-skill.mjs cookies status --in <cookiesJsonPath>

node ./bin/xhs-skill.mjs cookies to-header --in <cookiesJsonPath>

node ./scripts/verify_publish_payload.mjs --in <payloadJsonPath> --policy ./config/verify_publish_policy.json --tag-registry ./data/tag_registry.json --min-registry-tags 12 --require-source-evidence on --strict-anti-ai on [--mode hot]

node ./scripts/review_publish_payload.mjs --in <payloadJsonPath> --policy ./config/review_policy.json --taxonomy ./config/review_taxonomy.json --ai-provider auto --require-ai off [--mode hot]

D. Lightweight Release Process (Maintainers)

First run local gatekeepers:

```
npm run check:constraints
```
```
npm test
```

Check that changes only include expected files:
```
git status --short
```
Commit with Chinese Conventional Commit (example):

docs(skill): 补充发版前快速自检清单

Publish to ClawHub (patch):

clawhub sync --all --bump patch --changelog "docs: 补充发版前快速自检清单"

xhs-skill

NPX Install

Tags

SKILL.md Content (Chinese)

Installation

Local Directory Convention

A. Login (QR Code) and Save Cookies

A1. Anti-blocking/Throttling Operation Specifications (Mandatory)

B. Publish Notes (Image/Video)

C. Export Creator Center Data (CSV/XLSX or Screenshots)

Local CLI (Built into This Skill)

D. Lightweight Release Process (Maintainers)