autoUpload/docs/xhs_note_uploader_quickstart.md

# 小红书笔记上传器 - 快速开始指南

## 🚀 5分钟上手

### 第一步：安装依赖

```bash
cd /Users/yarrow/autoUpload
pip install -r requirements.txt
playwright install chromium
```

### 第二步：获取Cookie

```python
python examples/get_xiaohongshu_cookie.py
```

扫码登录后，Cookie会自动保存到 `cookies/xiaohongshu_note/account.json`

### 第三步：上传图文笔记

```python
import asyncio
from pathlib import Path
from uploader.xhs_note_uploader import XiaoHongShuImageNote

async def main():
    note = XiaoHongShuImageNote(
        title="我的第一条笔记✨",
        content="测试上传功能～",
        tags=["测试", "分享"],
        image_paths=["videos/demo.png"],
        publish_date=0,  # 0=立即发布
        account_file="cookies/xiaohongshu_note/account.json",
        headless=False  # 有头模式，可以看到浏览器操作
    )
    await note.main()

asyncio.run(main())
```

---

## 📋 核心参数说明

| 参数 | 说明 | 示例 |
|------|------|------|
| `title` | 标题（最多30字） | `"今天的下午茶☕️"` |
| `content` | 正文（最多1000字） | `"分享一下..."` |
| `tags` | 话题标签（建议≤3个） | `["下午茶", "咖啡"]` |
| `image_paths` | 图片列表（1-9张） | `["1.jpg", "2.jpg"]` |
| `publish_date` | 发布时间 | `0`（立即）或`datetime`（定时） |
| `account_file` | Cookie路径 | `"cookies/account.json"` |
| `location` | 地点（可选） | `"上海市·静安区"` |
| `headless` | 无头模式 | `False`（推荐有头） |

---

## 📝 完整示例

### 示例1：立即发布（单图）

```python
import asyncio
from uploader.xhs_note_uploader import XiaoHongShuImageNote

async def upload_single_image():
    note = XiaoHongShuImageNote(
        title="早安☀️",
        content="新的一天开始啦～",
        tags=["早安", "日常"],
        image_paths=["morning.jpg"],
        publish_date=0,
        account_file="cookies/xiaohongshu_note/account.json",
        headless=False
    )
    await note.main()

asyncio.run(upload_single_image())
```

### 示例2：立即发布（多图）

```python
import asyncio
from uploader.xhs_note_uploader import XiaoHongShuImageNote

async def upload_multiple_images():
    note = XiaoHongShuImageNote(
        title="今日穿搭分享👗",
        content="给大家分享一下今天的穿搭～\n简约又时尚！",
        tags=["穿搭", "时尚", "OOTD"],
        image_paths=["look1.jpg", "look2.jpg", "look3.jpg"],
        publish_date=0,
        account_file="cookies/xiaohongshu_note/account.json",
        location="北京市·朝阳区",
        headless=False
    )
    await note.main()

asyncio.run(upload_multiple_images())
```

### 示例3：定时发布

```python
import asyncio
from datetime import datetime, timedelta
from uploader.xhs_note_uploader import XiaoHongShuImageNote

async def upload_scheduled():
    # 明天上午10点发布
    tomorrow_10am = datetime.now() + timedelta(days=1)
    tomorrow_10am = tomorrow_10am.replace(hour=10, minute=0, second=0)
    
    note = XiaoHongShuImageNote(
        title="明日预告📢",
        content="明天10点见～",
        tags=["预告", "明天见"],
        image_paths=["preview.jpg"],
        publish_date=tomorrow_10am,  # 定时发布
        account_file="cookies/xiaohongshu_note/account.json",
        headless=False
    )
    await note.main()

asyncio.run(upload_scheduled())
```

### 示例4：批量上传（安全间隔）

```python
import asyncio
import random
from uploader.xhs_note_uploader import XiaoHongShuImageNote

async def batch_upload():
    notes_data = [
        {
            "title": "笔记1",
            "content": "内容1",
            "tags": ["标签1"],
            "images": ["1.jpg"],
        },
        {
            "title": "笔记2",
            "content": "内容2",
            "tags": ["标签2"],
            "images": ["2.jpg"],
        },
    ]
    
    for i, data in enumerate(notes_data):
        print(f"\n上传第 {i+1}/{len(notes_data)} 条笔记...")
        
        note = XiaoHongShuImageNote(
            title=data["title"],
            content=data["content"],
            tags=data["tags"],
            image_paths=data["images"],
            publish_date=0,
            account_file="cookies/xiaohongshu_note/account.json",
            headless=False
        )
        
        await note.main()
        
        # 间隔10-15分钟
        if i < len(notes_data) - 1:
            wait_min = random.randint(10, 15)
            print(f"⏰ 等待 {wait_min} 分钟...")
            await asyncio.sleep(wait_min * 60)

asyncio.run(batch_upload())
```

---

## ⚙️ 优化后的新特性

### 1. 批量图片上传
```python
# 一次性上传多张图片（更快！）
image_paths=["1.jpg", "2.jpg", "3.jpg", "4.jpg", "5.jpg"]
```

### 2. 精准元素定位
```python
# 使用优化后的选择器，定位成功率 95%+
# 自动适配小红书最新页面结构
```

### 3. 智能等待机制
```python
# 自动等待图片预览加载完成
# 显示实时进度：已加载 3/5 张图片
```

### 4. 人类化输入
```python
# 三种速度模式：
# - 标题：80-150ms/字符
# - 正文：100-200ms/字符  
# - 标签：500-800ms/字符（极慢，防检测）
```

---

## 🛡️ 安全建议

### ✅ 推荐配置
```python
{
    'headless': False,          # 有头模式
    'tags_limit': 3,            # 最多3个标签
    'upload_interval': 600,     # 间隔10分钟
    'max_notes_per_day': 5,     # 每天最多5条
}
```

### ❌ 不推荐配置
```python
{
    'headless': True,           # 无头模式不稳定
    'upload_interval': 60,      # 间隔太短
    'max_notes_per_day': 20,    # 数量太多，易触发风控
}
```

---

## 🐛 常见问题

### Q1: 找不到上传元素？
**A**: 使用有头模式检查页面是否正确加载
```python
headless=False  # 设置为False观察浏览器
```

### Q2: Cookie失效？
**A**: 重新获取Cookie
```python
from uploader.xhs_note_uploader.main import xiaohongshu_note_cookie_gen
await xiaohongshu_note_cookie_gen("cookies/account.json")
```

### Q3: 标签输入无效？
**A**: 
- 减少标签数量（≤3个）
- 使用简短标签文字
- 确保标签不包含特殊字符

### Q4: 图片上传慢？
**A**: 
- 优化图片大小（建议<5MB）
- 使用常见格式（.jpg, .png）
- 检查网络连接

---

## 📖 更多资源

- **详细文档**: `docs/xhs_note_uploader_optimization.md`
- **设计文档**: `docs/xhs_note_uploader_design.md`
- **完整示例**: `examples/upload_note_to_xiaohongshu_image.py`
- **测试脚本**: `examples/test_xhs_note_uploader.py`

---

## 🎯 下一步

1. **测试上传**: 运行测试脚本验证功能
```bash
python examples/test_xhs_note_uploader.py
```

2. **查看日志**: 检查上传详细日志
```bash
# 日志包含每个步骤的执行情况
```

3. **优化内容**: 根据需求调整标题、正文、标签
```python
# 真实、有价值的内容更容易获得推荐
```

4. **定期维护**: 定期手动登录维持账号活跃度
```python
# 建议每周至少手动登录一次
```

---

## 💡 专业提示

1. **图片质量**: 使用高质量、原创图片
2. **文案优化**: 标题要吸引人，正文要真诚
3. **标签选择**: 选择精准、热门的话题标签
4. **发布时间**: 选择用户活跃时段（早8点、午12点、晚8点）
5. **互动维护**: 及时回复评论，提高互动率

---

**祝你使用愉快！** 🎉