<p align="center">
  <h1 align="center">🍒 小红书 AI 爆文生产工坊</h1>
  <p align="center">
    <strong>全自动小红书内容创作 & 运营工具</strong><br>
    灵感 → 文案 → 绘图 → 发布 → 运营，一站式全闭环
  </p>
  <p align="center">
    <a href="#功能特性">功能特性</a> •
    <a href="#快速开始">快速开始</a> •
    <a href="#使用指南">使用指南</a> •
    <a href="#配置说明">配置说明</a> •
    <a href="#常见问题">FAQ</a> •
    <a href="#贡献指南">贡献</a>
  </p>
</p>

---

## ✨ 功能特性

### 📝 内容创作
- **AI 文案生成** — 输入主题即可生成小红书爆款标题、正文、话题标签
- **AI 绘图** — 集成 Stable Diffusion WebUI，自动生成配图（针对 JuggernautXL 优化）
- **一键导出** — 文案 + 图片打包导出到本地文件夹

### 🔥 热点探测
- **关键词搜索** — 搜索小红书热门笔记，支持多维度排序
- **AI 趋势分析** — 分析热门标题套路、内容结构，给出模仿建议
- **一键借鉴创作** — 参考热门笔记风格生成原创内容

### 💬 评论管家
- **主动评论引流** — 浏览笔记 → AI 智能生成评论 → 一键发送
- **自动回复粉丝** — 加载笔记评论 → AI 生成回复 → 发送

### 🤖 自动运营（无人值守）
- **一键评论** — 自动搜索高赞笔记 + AI 生成评论 + 发送
- **一键点赞** — 批量随机点赞，提升账号活跃度
- **一键回复** — 自动扫描我的笔记 + AI 回复粉丝评论
- **一键发布** — 自动生成文案 + SD 生图 + 发布到小红书
- **随机定时** — 评论/点赞/回复/发布全自动定时执行，随机间隔模拟真人

### 📊 数据看板
- **账号概览** — 粉丝数、获赞数等核心指标可视化
- **笔记排行** — 点赞排行图表分析

### 🔐 账号管理
- **扫码登录** — 小红书二维码登录，自动获取 Token
- **多 LLM 提供商** — 支持 DeepSeek、OpenAI、通义千问等所有兼容接口

---

## 📸 截图预览

> 启动后在浏览器中打开 `http://127.0.0.1:7860`

---

## 🚀 快速开始

### 环境要求

| 依赖 | 要求 | 说明 |
|------|------|------|
| **Python** | >= 3.10 | 推荐 3.11+ |
| **xiaohongshu-mcp** | 运行中 | 小红书 MCP 服务（默认端口 18060） |
| **Stable Diffusion WebUI** | 可选 | 本地 AI 绘图（默认端口 7860） |
| **LLM API** | 必须 | 任意 OpenAI 兼容接口 |

### 安装步骤

```bash
# 1. 克隆项目
git clone https://github.com/your-username/xhs-autobot.git
cd xhs-autobot

# 2. 创建虚拟环境（推荐）
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

# 3. 安装依赖
pip install -r requirements.txt

# 4. 复制配置文件并填写你的 API Key
cp config.example.json config.json
# 编辑 config.json，填写 api_key、base_url 等

# 5. 启动！
python main.py
```

启动后会自动打开浏览器，访问 `http://127.0.0.1:7860`。

### 🐳 Docker 部署（推荐）

使用 Docker Compose 一键启动所有服务，无需手动安装 Python 环境：

```bash
# 1. 克隆项目
git clone https://github.com/your-username/xhs-autobot.git
cd xhs-autobot

# 2. 准备配置文件
cp config.example.json config.json
# 编辑 config.json，填写 api_key、base_url 等
# ⚠️ mcp_url 改为容器网络地址：
#    "mcp_url": "http://xhs-mcp:18060/mcp"

# 3. 一键启动
docker compose up -d

# 4. 查看日志
docker compose logs -f xhs-autobot
```

启动后访问 `http://localhost:7860`。

#### Docker 服务说明

| 服务 | 容器名 | 端口 | 说明 |
|------|--------|------|------|
| `xhs-autobot` | xhs-autobot | 7860 | 主应用（Gradio UI） |
| `xhs-mcp` | xhs-mcp | 18060 | 小红书 MCP 服务 |
| `sd-webui` | sd-webui | 7861 | SD WebUI（可选，需 GPU） |

#### 常用命令

```bash
# 停止所有服务
docker compose down

# 重新构建（代码更新后）
docker compose up -d --build

# 查看运行状态
docker compose ps

# 进入主容器调试
docker compose exec xhs-autobot bash
```

#### 启用 Stable Diffusion（需要 NVIDIA GPU）

编辑 `docker-compose.yml`，取消 `sd-webui` 部分的注释，并将 `config.json` 中的 `sd_url` 改为：

```json
"sd_url": "http://sd-webui:7860"
```

---

### 前置服务

#### xiaohongshu-mcp（必须）

本项目通过 [xiaohongshu-mcp](https://github.com/punkpeye/xiaohongshu-mcp) 与小红书交互（搜索、发布、评论等），请先启动 MCP 服务：

```bash
# 按照 xiaohongshu-mcp 文档启动，默认端口 18060
npx xiaohongshu-mcp
```

#### Stable Diffusion WebUI（可选，用于 AI 绘图）

推荐使用 [AUTOMATIC1111/stable-diffusion-webui](https://github.com/AUTOMATIC1111/stable-diffusion-webui)，启动时开启 API：

```bash
python launch.py --api
```

推荐模型：[JuggernautXL](https://civitai.com/models/133005)（参数已优化适配）。

---

## 📖 使用指南

### 首次使用流程

1. **配置 LLM** — 展开「⚙️ 全局设置」，添加 LLM 提供商（API Key + Base URL），点击「连接 LLM」
2. **连接 SD**（可选）— 填写 SD WebUI URL，点击「连接 SD」
3. **检查 MCP** — 点击「检查 MCP」确认小红书服务正常
4. **登录小红书** — 切换到「🔐 账号登录」Tab，扫码登录
5. **开始创作** — 切换到「✨ 内容创作」Tab，输入主题，一键生成

### 自动化运营

切换到「🤖 自动运营」Tab：

- **一键操作** — 手动触发单次评论/点赞/回复/发布
- **定时调度** — 勾选需要的功能，设置间隔时间，点击「▶️ 启动定时」
- **查看日志** — 点击「🔄 刷新日志」查看实时执行记录

---

## ⚙️ 配置说明

配置文件 `config.json` 会在运行时自动创建和保存。首次使用请从 `config.example.json` 复制：

```json
{
    "api_key": "你的LLM API Key",
    "base_url": "https://api.deepseek.com/v1",
    "sd_url": "http://127.0.0.1:7860",
    "mcp_url": "http://localhost:18060/mcp",
    "model": "deepseek-chat",
    "persona": "温柔知性的时尚博主",
    "my_user_id": "你的小红书userId(24位)"
}
```

| 字段 | 说明 | 必填 |
|------|------|------|
| `api_key` | LLM API 密钥 | ✅ |
| `base_url` | LLM API 地址（OpenAI 兼容） | ✅ |
| `sd_url` | Stable Diffusion WebUI 地址 | 绘图需要 |
| `mcp_url` | xiaohongshu-mcp 服务地址 | ✅ |
| `model` | 默认使用的 LLM 模型名 | ✅ |
| `persona` | AI 评论回复的人设 | 可选 |
| `my_user_id` | 你的小红书 userId（24 位十六进制） | 数据看板/自动回复需要 |
| `llm_providers` | 多 LLM 提供商配置数组 | 通过 UI 管理 |

### 获取 userId

1. 浏览器打开你的小红书主页
2. 网址格式为 `xiaohongshu.com/user/profile/xxxxxxxx`
3. `profile/` 后面的就是 userId

---

## 📁 项目结构

```
xhs-autobot/
├── main.py              # 主程序入口 (Gradio UI + 业务逻辑)
├── config_manager.py    # 配置管理模块 (单例、自动保存)
├── llm_service.py       # LLM 服务封装 (文案生成、热点分析、评论回复)
├── sd_service.py        # Stable Diffusion 服务封装 (txt2img、img2img)
├── mcp_client.py        # 小红书 MCP 客户端 (搜索、发布、评论、点赞)
├── config.json          # 运行时配置 (gitignore)
├── config.example.json  # 配置模板
├── requirements.txt     # Python 依赖
├── Dockerfile           # Docker 镜像构建
├── docker-compose.yml   # Docker Compose 编排
├── .dockerignore        # Docker 构建排除规则
├── xhs_workspace/       # 导出的文案和图片 (gitignore)
└── autobot.log          # 运行日志 (gitignore)
```

---

## ❓ 常见问题

<details>
<summary><b>Q: LLM API 报错 400 json_object</b></summary>

某些 API 在使用 `response_format: json_object` 时要求消息中包含 "json" 一词。本项目已自动处理，如仍遇到请升级到最新版本。
</details>

<details>
<summary><b>Q: 评论发送成功但 App 上看不到</b></summary>

小红书有内容审核机制，评论可能需要 1-5 分钟显示。部分评论可能被风控（仅自己可见）。查看自动化日志中的 MCP 响应可排查。
</details>

<details>
<summary><b>Q: SD WebUI 连接失败</b></summary>

确保启动 SD WebUI 时加了 `--api` 参数，且端口匹配。本项目默认连接 `http://127.0.0.1:7860`。
</details>

<details>
<summary><b>Q: xiaohongshu-mcp 是什么？怎么启动？</b></summary>

这是一个开源的小红书 MCP 服务端，提供搜索、发布、评论等 API。详见 [xiaohongshu-mcp 项目](https://github.com/punkpeye/xiaohongshu-mcp)。
</details>

<details>
<summary><b>Q: 支持哪些 LLM？</b></summary>

支持所有 OpenAI 兼容接口，包括但不限于：DeepSeek、GPT-4o、通义千问、Gemini（通过中转）、Claude（通过中转）等。
</details>

---

## 🤝 贡献指南

欢迎贡献代码！请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详情。

简要流程：
1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'feat: add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 发起 Pull Request

---

## 📋 更新日志

详见 [CHANGELOG.md](CHANGELOG.md)。

---

## ⚠️ 免责声明

- 本项目仅供学习和研究目的，请遵守小红书平台的使用规范和服务条款
- 过度使用自动化功能可能导致账号被限制，请合理设置操作间隔
- 用户需为自己发布的内容和使用行为承担全部责任
- 本项目不保存、不传输任何用户的账号密码信息

---

## 📄 许可证

本项目使用 [MIT License](LICENSE) 开源。

---

## 🌟 Star History

如果这个项目对你有帮助，请点亮 ⭐ Star！

