xiaohongshu-auto-posting

# Xiaohongshu Auto-Posting (XHS Auto-Posting)

> End-to-end Xiaohongshu content operation: topic discovery → style reference → writing → publishing → performance tracking.

## Language

All process output to user (progress updates, questions, status notifications) follows the user's language.

## Objective

Automate a complete Xiaohongshu content operation cycle for a configured product: discover high-engagement pain-point topics via search, collect writing style references, generate platform-native content aligned with the style fingerprint, publish with user approval, and track post-publish performance metrics.

## Prerequisites

- Xiaohongshu creator center (`creator.xiaohongshu.com`) already logged in on a configured stealth browser (browser ID stored in `session_state.json`)
- `workspaces/xhs-posting/` workspace (auto-created on first run)

## Pre-execution Checks

### 1. Tool Readiness

If browser-act has been confirmed available in the current session → skip this step.

Invoke `browser-act` via Skill tool to load usage. If installation or configuration issues arise, follow its guidance to resolve then retry.

### 2. Login Verification

Covered in Phase 0.5 — login check is deferred until session state is loaded (Phase 0.2) and the browser is opened. If the user triggers Phase 6 directly (standalone tracking mode), still complete Phase 0.2 and Phase 0.5 first.

### 3. Session Lifecycle

Each execution generates a unique session name (`xhs-<YYYYMMDD>-<HHMM>`) to avoid cross-conversation conflicts. The session is opened once in Phase 0.5 and closed at the end of the workflow. All commands in this Skill reference the session via `$SESSION` — the actual name is determined at runtime.

---

## Runtime Workspace

All runtime files (config, drafts, publish records, screenshots) are written to **the user's working directory (CWD)** under `workspaces/xhs-posting/`. This directory is auto-created on first run.

```
workspaces/xhs-posting/          ← relative to user CWD
├── session_state.json            # account & product config
├── config/
│   └── keywords.json             # keyword pool
├── tracking/
│   └── published.json            # published note records
├── reports/                      # performance reports
└── <YYYY-MM-DD>/                 # per-run date directory
    ├── topics/
    ├── selected_topics.json
    ├── style_fingerprint.json
    ├── drafts/
    └── replies/
```

---

## Quick Start

```
/xiaohongshu-auto-posting
```

Standalone triggers (jump directly to the corresponding phase, skipping Phase 0–4):
- `"track performance"` / `"see data"` / `"data collection"` → Phase 6 performance tracking
- `"settings"` / `"switch account"` / `"update keywords"` → Phase 0 configuration wizard

---

## Operational Rules

Three rules that apply to every browser-act session. Violating any one causes silent failures or long hangs. Full details in `references/phase5-publish.md §0`.

**Rule 1 — Never pipe browser-act output directly**

Redirect state output to a temp file, then grep the file. Piping may background the command when output contains multi-byte characters, making the result unavailable synchronously.

```bash
# WRONG
browser-act --session $SESSION state | grep "Publish"
# CORRECT
browser-act --session $SESSION state > /tmp/s.txt 2>&1 && grep "Publish" /tmp/s.txt
```

**Rule 2 — Escape all non-ASCII content before passing to eval --stdin**

Non-ASCII literals (Chinese, emoji) in JS source cause encoding errors in the subprocess pipeline. Escape to `\uXXXX` first:

```python
def to_ascii_js(s):
    return ''.join(r'\u{:04x}'.format(ord(c)) if ord(c) > 127 else c for c in s)
js = to_ascii_js(open('tmp/script.js', encoding='utf-8').read())
subprocess.run([..., 'eval', '--stdin'], input=js.encode('ascii'), ...)
```

**Rule 3 — Use `click`, not `eval`, for actions that trigger navigation**

`eval` hangs (~30 s timeout) when the callback causes a page redirect. Always use `browser-act --session $SESSION click <index>` for the publish button, then verify the URL immediately after.

---

## Phase 0 — Initialization

### 0.1 Tool Check

Run `browser-act browser list`:
- Command not found → run `uv tool upgrade browser-act-cli || uv tool install browser-act-cli --python 3.12`, then continue
- Returns normally → continue

### 0.2 Session State Load

Read `workspaces/xhs-posting/session_state.json`:
- File does not exist, or `browser_id` is empty → proceed to **0.3 First-time Configuration Wizard**
- File exists and `browser_id` is non-empty → load and display current config, ask user to confirm or modify

`session_state.json` structure:

```json
{
  "browser_id": "",
  "account": {
    "nickname": "",
    "profile": ""
  },
  "product": {
    "name": "",
    "tagline": "",
    "url": "",
    "install_cmd": ""
  },
  "keywords_file": "workspaces/xhs-posting/config/keywords.json",
  "posting": {
    "daily_limit": 1,
    "min_interval_hours": 6,
    "last_posted_at": null
  }
}
```

### 0.3 First-time Configuration Wizard (when file does not exist or browser_id is empty)

**Step 1: Browser Selection**

Run `browser-act browser list`, then:

**When existing browsers are present**: display all browsers (id / name / type / desc / proxy), ask the user which one to use for posting:

```
Existing browsers:

#1  id=xxx  name="xxx"  type=stealth  desc="xxx"  proxy=XX
#2  id=xxx  name="xxx"  type=chrome   desc="xxx"

Select a browser number to use for posting, or enter "new" to create one:
>
```

**When no browsers exist, or user enters "new"**:

1. Load advanced guide: `browser-act get-skills advanced`
2. Ask the user:
   - Browser name (custom, e.g. "xhs-poster")
   - Proxy requirements (needed? region or custom URL?)
3. Create the browser following the advanced guide's Confirmation Gate protocol
4. Record the new browser ID, continue to Step 2

**Step 2: Product & Keyword Configuration**

Ask the user:
1. Product name (brand keyword, used in tags and body)
2. Product tagline (one-sentence descri