ai_wht_wechat/backend/QUICK_START.md

# 快速开始指南

## 问题说明

如果您在使用 `xhs_publish.py` 时遇到 JSON 解析错误：

```bash
python xhs_publish.py --cookies '[...]' --title "标题" --content "内容"
# 错误: JSON解析失败: Expecting property name enclosed in double quotes
```

这是因为命令行中的 JSON 字符串转义问题。

## 解决方案

我们提供了 **3 种简单的使用方式**：

---

## 方式 1：快速发布脚本（推荐）⭐

使用 `quick_publish.py`，无需处理 JSON 转义。

### 用法

```bash
python quick_publish.py "标题" "内容" "图片1,图片2,图片3" "标签1,标签2"
```

### Windows PowerShell 用法

**在 Windows PowerShell 中，强烈推荐使用此方式，避免 JSON 转义问题：**

```powershell
python quick_publish.py "测试笔记" "这是测试内容" "https://picsum.photos/800/600,https://picsum.photos/800/600" "测试,自动化"
```

### 参数说明

1. **标题**（必需）
2. **内容**（必需）
3. **图片**（可选）- 用逗号分隔，支持本地路径和网络 URL
4. **标签**（可选）- 用逗号分隔

### 示例

**1. 发布纯文字**
```bash
python quick_publish.py "测试笔记" "这是测试内容" "" "测试,自动化"
```

**2. 使用网络图片**
```bash
python quick_publish.py "测试笔记" "这是测试内容" "https://picsum.photos/800/600,https://picsum.photos/800/600" "测试,图片"
```

**3. 使用本地图片**
```bash
python quick_publish.py "测试笔记" "这是测试内容" "D:/image1.jpg,D:/image2.jpg" "测试"
```

**4. 混合使用**
```bash
python quick_publish.py "测试笔记" "这是测试内容" "https://picsum.photos/800/600,D:/local.jpg" "测试"
```

### Cookie 文件

脚本默认从 `cookies.json` 读取 Cookie。

如果 Cookie 在其他文件，可以指定：
```bash
python quick_publish.py "标题" "内容" "图片" "标签" "my_cookies.json"
```

---

## 方式 2：配置文件发布

### 步骤 1：准备 Cookie 文件

将您的 Cookie 保存为 `test_cookies.json`（已为您创建）。

### 步骤 2：创建配置文件

创建 `my_publish.json`：

```json
{
  "cookies": "@test_cookies.json",
  "title": "💧夏日必备！2元一杯的柠檬水竟然这么好喝？",
  "content": "今天给大家分享一个超级实惠的夏日饮品！",
  "images": [
    "https://picsum.photos/800/600?random=1",
    "https://picsum.photos/800/600?random=2"
  ],
  "tags": ["夏日清爽", "饮品", "柠檬水"]
}
```

### 步骤 3：执行发布

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

---

## 方式 3：使用命令行参数（支持Cookie文件）⭐

### 用法

```bash
# Cookie 使用文件路径（推荐）
python xhs_publish.py --cookies test_cookies.json --title "标题" --content "内容" --images '["https://picsum.photos/800/600"]' --tags '["标签1"]'

# Cookie 使用 JSON 字符串（需要转义，不推荐）
python xhs_publish.py --cookies '[{...}]' --title "标题" --content "内容"
```

### 参数说明

- `--cookies`: **Cookie JSON 字符串 或 Cookie 文件路径**（推荐使用文件路径）
- `--title`: 标题
- `--content`: 内容
- `--images`: 图片列表的 JSON 字符串（可选）
- `--tags`: 标签列表的 JSON 字符串（可选）

### 示例

**1. 使用 Cookie 文件（推荐）**
```bash
python xhs_publish.py --cookies test_cookies.json --title "测试笔记" --content "这是测试内容" --images '["https://picsum.photos/800/600"]' --tags '["测试","自动化"]'
```

**2. 只发布文字**
```bash
python xhs_publish.py --cookies test_cookies.json --title "纯文字笔记" --content "这是一条纯文字笔记"
```

## 方式 4：Python 脚本调用

```python
import asyncio
import json
from xhs_publish import XHSPublishService

async def publish_my_note():
    # 读取 Cookie
    with open('test_cookies.json', 'r') as f:
        cookies = json.load(f)
    
    # 创建发布服务
    publisher = XHSPublishService(cookies)
    
    # 发布笔记
    result = await publisher.publish(
        title="测试笔记",
        content="这是测试内容",
        images=[
            "https://picsum.photos/800/600?random=1",
            "https://picsum.photos/800/600?random=2"
        ],
        tags=["测试", "自动化"]
    )
    
    print(json.dumps(result, ensure_ascii=False, indent=2))

# 运行
asyncio.run(publish_my_note())
```

---

## 完整示例

### 使用您提供的 Cookie

Cookie 已保存到 `test_cookies.json`，现在可以直接发布：

```bash
# 方式 1：快速发布（推荐）
cd backend
python quick_publish.py "测试笔记" "这是一条测试笔记，使用网络图片自动发布" "https://picsum.photos/800/600,https://picsum.photos/800/600" "测试,自动化" test_cookies.json
```

### 输出示例

```
==================================================
快速发布小红书笔记
==================================================
标题: 测试笔记
内容: 这是一条测试笔记，使用网络图片自动发布
图片: 2 张
  1. https://picsum.photos/800/600
  2. https://picsum.photos/800/600
标签: ['测试', '自动化']
Cookie: test_cookies.json
==================================================

正在处理 2 张图片...
  正在下载图片 [1]: https://picsum.photos/800/600
  ✅ 下载成功: image_0_xxx.jpg (45.2KB)
  正在下载图片 [2]: https://picsum.photos/800/600
  ✅ 下载成功: image_1_xxx.jpg (52.8KB)

成功处理 2/2 张图片

1. 初始化浏览器...
浏览器初始化成功

2. 验证登录状态...
✅ 登录状态有效

3. 开始发布笔记...
[...]

==================================================
发布结果:
{
  "success": true,
  "message": "笔记发布成功",
  "url": "https://www.xiaohongshu.com/explore/..."
}
==================================================

✅ 发布成功！
📎 笔记链接: https://www.xiaohongshu.com/explore/...
```

---

## 常见问题

### Q: 为什么会出现 JSON 解析错误？

A: 在命令行中直接使用 JSON 字符串时，Shell 会对引号进行特殊处理，导致解析失败。建议使用：
- **方式 1**：`quick_publish.py`（无需处理 JSON）
- **方式 2**：配置文件（JSON 在文件中）

### Q: Cookie 从哪里获取？

A: 三种方式：
1. 使用 `xhs_cli.py login` 登录获取
2. 从浏览器开发者工具复制
3. 使用现有的 Cookie JSON

### Q: 图片支持哪些格式？

A: 
- **本地文件**：JPG、PNG、GIF、WEBP
- **网络 URL**：HTTP/HTTPS 链接
- **混合使用**：可以同时使用本地和网络图片

### Q: 如何验证 Cookie 是否有效？

A: 使用快速发布脚本，会自动验证：
```bash
python quick_publish.py "测试" "测试内容" "" ""
```

如果 Cookie 失效，会提示：
```
❌ 发布失败: Cookie已失效或未登录
```

---

## 进阶使用

### 批量发布

创建脚本 `batch_publish.py`：

```python
import asyncio
from quick_publish import quick_publish

async def main():
    articles = [
        {
            "title": "文章1",
            "content": "内容1",
            "images": ["https://picsum.photos/800/600"],
            "tags": ["标签1"]
        },
        {
            "title": "文章2",
            "content": "内容2",
            "images": ["https://picsum.photos/800/600"],
            "tags": ["标签2"]
        }
    ]
    
    for article in articles:
        result = await quick_publish(**article)
        print(f"发布结果: {result['success']}")
        await asyncio.sleep(60)  # 间隔60秒

asyncio.run(main())
```

---

## 总结

✅ **推荐使用 `quick_publish.py`**
- 无需处理 JSON 转义
- 参数简单直观
- 自动读取 Cookie 文件

现在您可以尝试使用快速发布脚本了！🚀