first commit

2025-12-19 22:36:48 +08:00
commit 6802624e59
185 changed files with 43430 additions and 0 deletions
--- a/backend/QUICK_START.md
+++ b/backend/QUICK_START.md
@@ -0,0 +1,313 @@
+# 快速开始指南
+
+## 问题说明
+
+如果您在使用 `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 文件
+
+现在您可以尝试使用快速发布脚本了！🚀