xiaohongshu-publisher

# 小红书发布与运营技能

根据用户需求，自动完成小红书的内容发布或运营互动任务。

> 完整参数文档见 `references/params.md`  
> 常见错误与处理见 `references/troubleshooting.md`  
> 工作流规则与约束见 `references/runtime-rules.md`

---

## ⬇️ 安装（新环境首次运行必先执行）

`venv/` 和 `xhs_browser_data/` 不随 skill 迁移，可以即开即用。創建新环境请运行对应安装脚本：

```bash
# Linux/macOS（Openclaw 部署环境）
bash setup.sh

# Windows 本地调试
.\setup.ps1
```

安装完成后再执行后续步骤。

---

## 先决条件检查

在执行任何任务前，检查：

1. `venv/` 虚拟环境是否存在（不存在则先运行 setup.sh）。
2. `.env` 文件是否包含 `XHS_COOKIE`（发布任务必须）。
3. `xhs_browser_data/` 是否有登录数据（互动任务必须，否则先引导用户登录）。

---

## 工作流一：发布图文笔记

**触发条件**：用户提供图片路径、笔记标题和正文，要求发布到小红书。

### 第一步：验证 Cookie 有效

```bash
# Linux/macOS (Openclaw)
venv/bin/python scripts/publish_xhs.py --dry-run --title "验证" --images <任意图片路径>

# Windows
.\venv\Scripts\python.exe scripts\publish_xhs.py --dry-run --title "验证" --images <任意图片路径>
```

- 成功 → 进入第二步
- 失败 → 提示用户更新 `.env` 中的 `XHS_COOKIE`（见 `references/params.md`）

### 第二步：执行发布

```bash
# Linux/macOS （公开发布）
venv/bin/python scripts/publish_xhs.py \
  --title "笔记标题" \
  --desc "正文内容 #话题标签" \
  --images 封面.png 配图1.png \
  --public

# Windows
.\venv\Scripts\python.exe scripts\publish_xhs.py --title "笔记标题" --desc "正文" --images 封面.png --public
```

> **默认仅自己可见**，确认效果后再用 `--public` 公开。

### 第三步：确认发布结果

- 成功后终端会打印笔记 ID 和链接，汇报给用户。
- 失败则根据 `references/troubleshooting.md` 排查并上报错误原因。

---

## 工作流二：搜索与互动（评论）

**触发条件**：用户要求搜索某关键词、浏览帖子、或回复评论。

### 第一步：确认浏览器登录态

检查 `xhs_browser_data/` 是否存在。若不存在：

```bash
# Linux/macOS (Openclaw) - Open...

# 小红书自动化发布技能（Skill）

基于 [Auto-Redbook-Skills](https://github.com/comeonzhj/Auto-Redbook-Skills) 和 [xiaohongshu-ops-skill](https://github.com/Xiangyu-CAS/xiaohongshu-ops-skill) 两个开源项目核心思路构建，遵循标准 Skill 封装格式。

---

## 目录结构

```
xiaohongshu_mcp/          ← Skill 根目录
├── SKILL.md              # 🧠 技能主文件（工作流定义，AI 读此文件理解如何操作）
├── scripts/
│   ├── publish_xhs.py    # 📦 图文发布脚本（XHSPublisher 类）
│   └── interact_xhs.py   # 🖱️ 网页互动脚本（XHSInteractor 类）
├── references/
│   ├── params.md         # 参数说明 & Cookie 获取方法
│   ├── runtime-rules.md  # 操作规范与风控约束
│   └── troubleshooting.md# 常见错误排查
├── examples/
│   └── publish_example.py# 发布调用示例
├── venv/                 # Python 虚拟环境（已含所有依赖）
└── .env                  # 🔑 配置文件（需填写 Cookie，格式见 references/params.md）
```

> **⚠️ 注意：** 所有命令须使用虚拟环境中的 Python：`.\venv\Scripts\python.exe`

---

## 一、环境配置

### 配置 Cookie（发布模块用）

1. 用 Chrome/Edge 登录小红书网页版：[www.xiaohongshu.com](https://www.xiaohongshu.com)
2. 按 `F12` 打开开发者工具 → 切到 **Network** 标签页
3. 刷新页面后点击任意请求 → 在右侧 **Headers** 中找到 `cookie` 字段
4. 复制完整的 Cookie 字符串（很长，完整复制）
5. 在本项目根目录新建 `.env` 文件，内容如下：

```env
XHS_COOKIE=a1=xxx; web_session=yyy; 其他cookie字段...
```

> **关键字段**：Cookie 中必须包含 `a1` 和 `web_session`，否则发布签名会失败。

---

## 二、发布图文笔记（publisher_v2.py）

**功能**：通过小红书官方接口直接发布图文笔记，速度极快，无需打开浏览器。

### 命令参数说明

| 参数 | 必填 | 说明 |
|------|------|------|
| `--title` | ✅ | 笔记标题（不超过20字，超出自动截断） |
| `--desc` | 否 | 笔记正文内容（含话题标签等） |
| `--images` | ✅ | 图片路径，可多个，用空格分隔 |
| `--public` | 否 | 加此参数则公开发布；**不加则默认仅自己可见** |
| `--dry-run` | 否 | 仅验证 Cookie 连通性，不真实发布 |

###...