first commit

backend/XHS_PUBLISH_README.md

@@ -0,0 +1,313 @@
+# 小红书笔记发布脚本使用说明
+
+## 功能介绍
+
+`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. 图片文件是否存在