ai_wht_wechat/backend/XHS_PUBLISH_README.md

# 小红书笔记发布脚本使用说明

## 功能介绍

`xhs_publish.py` 是一个用于自动发布小红书笔记的 Python 脚本，支持通过 Cookie 认证，自动完成图文笔记发布。

## 环境准备

### 1. 安装依赖

```bash
cd backend
pip install -r requirements.txt
```

主要依赖：
- playwright (浏览器自动化)
- asyncio (异步处理)

### 2. 安装浏览器驱动

```bash
playwright install chromium
```

## 使用方式

### 方式一：使用配置文件（推荐）

#### 1. 准备配置文件

复制 `publish_config_example.json` 并修改为实际参数：

```json
{
  "cookies": [
    {
      "name": "a1",
      "value": "your_cookie_value_here",
      "domain": ".xiaohongshu.com",
      "path": "/",
      "expires": -1,
      "httpOnly": false,
      "secure": false,
      "sameSite": "Lax"
    }
  ],
  "title": "笔记标题",
  "content": "笔记内容",
  "images": [
    "D:/path/to/image1.jpg",
    "D:/path/to/image2.jpg"
  ],
  "tags": [
    "标签1",
    "标签2"
  ]
}
```

#### 2. 执行发布

```bash
python xhs_publish.py --config publish_config.json
```

### 方式二：命令行参数

```bash
python xhs_publish.py \
  --cookies '[{"name":"a1","value":"xxx","domain":".xiaohongshu.com"}]' \
  --title "笔记标题" \
  --content "笔记内容" \
  --images '["D:/image1.jpg","D:/image2.jpg"]' \
  --tags '["标签1","标签2"]'
```

## 参数说明

### cookies (必需)

Cookie 数组，每个 Cookie 对象包含以下字段：

- `name`: Cookie 名称
- `value`: Cookie 值
- `domain`: 域名（通常为 `.xiaohongshu.com`）
- `path`: 路径（通常为 `/`）
- `expires`: 过期时间（-1 表示会话 Cookie）
- `httpOnly`: 是否仅 HTTP
- `secure`: 是否安全
- `sameSite`: 同站策略（Lax/Strict/None）

**重要 Cookie（必需）：**
- `a1`: 用户身份认证
- `webId`: 设备标识
- `web_session`: 会话信息

### title (必需)

笔记标题，字符串类型。

**示例：**
```
"💧夏日必备！2元一杯的柠檬水竟然这么好喝？"
```

### content (必需)

笔记正文内容，字符串类型，支持换行符 `\n`。

**示例：**
```
"今天给大家分享一个超级实惠的夏日饮品！\n\n蜜雪冰城的柠檬水只要2元一杯，性价比真的太高了！"
```

### images (可选)

图片文件路径数组，支持本地绝对路径。

**要求：**
- 图片必须是本地文件
- 支持 jpg、png、gif 等格式
- 最多上传 9 张图片
- 建议尺寸：800x600 或更高

**示例：**
```json
[
  "D:/project/Work/ai_xhs/backend/temp_uploads/image1.jpg",
  "D:/project/Work/ai_xhs/backend/temp_uploads/image2.jpg"
]
```

### tags (可选)

标签数组，会自动添加 `#` 前缀。

**示例：**
```json
["夏日清爽", "饮品", "柠檬水"]
```

## 获取 Cookie 的方法

### 方法一：使用登录脚本

```bash
python xhs_cli.py login <手机号> <验证码>
```

登录成功后会自动保存 Cookie 到 `cookies.json` 文件。

### 方法二：浏览器手动获取

1. 在浏览器中登录小红书网页版
2. 打开开发者工具（F12）
3. 切换到 Network（网络）标签
4. 刷新页面
5. 找到任意请求，查看 Request Headers
6. 复制 Cookie 字段内容
7. 使用在线工具或脚本转换为 JSON 格式

### 方法三：使用 Cookie 注入验证

```bash
python xhs_cli.py inject_cookies '<cookies_json>'
```

## 返回结果

### 成功示例

```json
{
  "success": true,
  "message": "笔记发布成功",
  "url": "https://www.xiaohongshu.com/explore/xxxx"
}
```

### 失败示例

```json
{
  "success": false,
  "error": "Cookie已失效或未登录"
}
```

## 注意事项

### 1. Cookie 有效期

- Cookie 会在一段时间后失效
- 需要定期重新登录获取新 Cookie
- 建议使用 Cookie 注入验证接口检查状态

### 2. 图片上传

- 确保图片文件存在且可访问
- 图片路径使用绝对路径
- Windows 系统路径使用 `/` 或 `\\` 分隔符

### 3. 发布限制

- 小红书可能有发布频率限制
- 建议控制发布间隔，避免被限流
- 内容需符合小红书社区规范

### 4. 错误处理

常见错误及解决方法：

- **"Cookie已失效"**: 重新登录获取新 Cookie
- **"图片文件不存在"**: 检查图片路径是否正确
- **"未找到发布按钮"**: 小红书页面结构可能变化，需要更新选择器
- **"输入内容失败"**: 等待时间不足，增加延迟时间

## 与 Go 后端集成

在 Go 后端中调用此脚本：

```go
import (
    "os/exec"
    "encoding/json"
)

// 发布笔记
func PublishNote(cookies []Cookie, title, content string, images, tags []string) error {
    // 构造配置文件
    config := map[string]interface{}{
        "cookies": cookies,
        "title":   title,
        "content": content,
        "images":  images,
        "tags":    tags,
    }
    
    // 保存到临时文件
    configFile := "temp_publish_config.json"
    data, _ := json.Marshal(config)
    ioutil.WriteFile(configFile, data, 0644)
    
    // 调用 Python 脚本
    cmd := exec.Command("python", "backend/xhs_publish.py", "--config", configFile)
    output, err := cmd.CombinedOutput()
    if err != nil {
        return err
    }
    
    // 解析结果
    var result map[string]interface{}
    json.Unmarshal(output, &result)
    
    if !result["success"].(bool) {
        return errors.New(result["error"].(string))
    }
    
    return nil
}
```

## 开发调试

### 启用浏览器可视模式

修改 `xhs_login.py` 中的 `headless` 参数：

```python
self.browser = await self.playwright.chromium.launch(
    headless=False,  # 改为 False 可以看到浏览器操作过程
    args=['--disable-blink-features=AutomationControlled']
)
```

### 查看详细日志

脚本会在控制台输出详细的执行日志，包括：
- 浏览器初始化
- 登录状态验证
- 图片上传进度
- 内容输入状态
- 发布结果

## 常见问题

### Q: 为什么上传图片后没有显示？

A: 可能是图片上传时间较长，脚本已经增加了等待时间。如果仍有问题，可以调整 `xhs_login.py` 中的等待时间。

### Q: 如何批量发布多条笔记？

A: 准备多个配置文件，使用循环调用脚本：

```bash
for config in publish_config_*.json; do
    python xhs_publish.py --config "$config"
    sleep 60  # 间隔60秒
done
```

### Q: Cookie 多久失效？

A: 小红书 Cookie 通常在 7-30 天后失效，具体取决于 Cookie 的过期时间设置。

## 技术支持

如有问题，请查看：
1. 脚本执行日志
2. 小红书页面结构是否变化
3. Cookie 是否有效
4. 图片文件是否存在