🆕 1.6号更新

• 📊 热点数据：内置微博/百度/头条/B站等热榜，支持一键带回首页生成内容
• 🪧 新增营销模板：在「🖼️ 封面中心」可选 营销海报🌟🌟🌟（本地生成 6 张图）/ 促销横幅 / 产品展示 等
• 🖼️ 预览/下载体验升级：首页支持一键打开「封面模板库」，并一键下载 封面 + 多页内容图
• 🎨 UI 体验优化：左侧编辑、右侧图片预览，生成流程更顺滑

📖 项目简介

小红书AI发布助手 是一个功能强大的自动化内容创作与发布工具，专为小红书平台的内容创作者设计。

🎯 核心价值

• 🧠 智能创作: 基于先进AI技术自动生成高质量内容
• ⚡ 效率提升: 一键操作节省90%发布时间
• 🎨 专业品质: 精美界面设计，用户体验极佳
• 🔧 功能完整: 从内容生成到发布全流程自动化

✨ 核心功能

📁 项目架构

📦 xhsaipublisher/
├── 📂 assets/                       # 🧩 内置系统模板预览（可选）
├── 📂 templates/                    # 🧩 文案/封面模板（可自行扩展）
├── 🧰 install.sh                    # 📦 一键安装（macOS/Linux）
├── 🧰 install.bat                   # 📦 一键安装（Windows）
├── 📂 src/                          # 🔧 源代码目录
│   ├── 📂 core/                     # ⚡ 核心功能模块
│   │   ├── 📂 models/               # 🗄️ 数据模型
│   │   ├── 📂 services/             # 🔧 业务服务层
│   │   ├── 📂 pages/                # 🎨 界面页面
│   │   ├── 📂 processor/            # 🧩 内容/图片处理
│   │   ├── 📂 scheduler/            # ⏰ 定时任务（到点自动发布）
│   │   └── 📂 ai_integration/       # 🤖 AI适配（实验）
│   ├── 📂 web/                      # 🌐 Web接口
│   │   ├── 📂 templates/            # 📄 HTML模板
│   │   └── 📂 static/               # 🎨 静态资源
│   └── 📂 logger/                   # 📝 日志系统
├── 📂 images/                       # 🖼️ 文档/界面截图资源
├── 📂 docs/                         # 📚 文档
├── 📂 tests/                        # 🧪 测试目录
├── 📂 venv/                         # 🐍 本地虚拟环境（已在 .gitignore，不会上传 GitHub）
├── 🐍 main.py                       # 🚀 主程序入口
├── 🚀 启动程序.sh                   # ▶️ 启动脚本（macOS/Linux）
├── 🚀 启动程序.bat                  # ▶️ 启动脚本（Windows）
├── ⚙️ .env.example                  # 🔑 环境变量示例（不要提交真实 .env）
├── 📋 requirements.txt              # 📦 依赖包列表
└── 📖 readme.md                     # 📚 项目说明

🛠️ 快速开始

📋 系统要求

Windows 建议使用 Python 3.11/3.12（64 位）；Python 3.13 或 32 位 Python 常见会导致 PyQt5 安装失败。

🚀 安装方式

🎯 一键安装（推荐）

| 操作系统 | 安装脚本 | 启动脚本 | |:---:|:---:|:---:| | macOS / Linux | ./install.sh | ./启动程序.sh | | Windows | install.bat | 启动程序.bat |

# macOS/Linux
chmod +x install.sh 启动程序.sh
./install.sh
./启动程序.sh

./启动程序.sh 会优先使用 venv/bin/python；若虚拟环境解释器缺失、软链失效或环境损坏，会自动回退到系统 python3 / python，不会写死机器路径。

:: Windows
install.bat
启动程序.bat

默认会检测 Playwright 浏览器并在缺失时自动安装；可用参数：

- 强制安装：./install.sh --with-browser / install.bat --with-browser

- 跳过浏览器：./install.sh --skip-browser / install.bat --skip-browser

- Windows 双击 启动程序.bat / install.bat 失败时，现在会保留报错窗口，方便定位问题

🧩 登录工具 + 服务模式（参考社区常见做法）

参考 xiaohongshu-mcp、xhs-toolkit 这类项目的思路，当前仓库也支持：

• 先在可视化环境完成一次登录，保存登录态
• 再由 Web/API 服务或 Docker 无头复用该登录态执行发布

python scripts/xhslogincli.py --phone 13800138000 --country-code +86

说明：

• 该命令会打开浏览器并尽量复用/保存 storage_state + cookies
• 若命中验证码/扫码/滑块风控，可按提示在浏览器中手动完成
• 成功后，登录态默认保存在 ~/.xhssystem/（或 XHSDATA_DIR 指定目录）
• 当本地 storagestate/cookies 失效时，登录流程会自动尝试扫描系统 Chrome 的多个 Profile，识别可用的小红书登录态并导入；可用 XHSAUTOIMPORTSYSTEMCHROMESTATE=false 关闭
• 使用真实 Chrome 持久化 Profile 时，默认不再注入额外 stealth 指纹覆写；如确有需要可设置 XHSENABLESTEALTH_SCRIPT=true
• 自动发布默认禁用 JS 强制点击/强制 input/change 兜底；仅手动确认模式或显式设置 XHSENABLEFORCEDOMACTIONS=true 时才启用
• 若系统 Chrome 正在运行，自动识别登录态会默认跳过，避免额外弹出多窗口；需要手动导入时再显式操作

🐳 Docker 部署（推荐 Web/API 模式）

桌面版 PyQt 不适合直接做容器 GUI 部署；容器里推荐运行 FastAPI + Playwright 服务模式。

docker compose build
docker compose up -d

默认暴露：

• Web/API：http://localhost:8000
• 健康检查：http://localhost:8000/healthz
• 就绪检查：http://localhost:8000/readyz

• 现在 Web/Docker 模式默认采用 懒加载浏览器运行时
• 服务启动时只初始化基础管理器，不会立刻拉起 Playwright 浏览器
• 第一次调用登录/发布接口时，才按需初始化浏览器运行时
• 如需启动即预热浏览器，可设置 XHSWEBEAGER_BROWSER=true

• 先在本机可视化环境执行一次 python scripts/xhslogincli.py ... 获取登录态
• 将登录态目录挂载到容器的 /data（本仓库默认映射 ./docker-data:/data）
• 再以无头模式运行容器服务进行发布

• 默认 docker-compose.yml 中启用了 XHS_HEADLESS=true
• 如果当前登录态失效，无头模式不会弹验证码窗口，而会明确提示需要先在有界面环境重新登录
• docker compose ps 可直接看到健康状态；健康检查依赖 /healthz

📥 手动安装（高级用户）

# 1️⃣ 创建虚拟环境
python -m venv venv
2️⃣ 激活虚拟环境（macOS/Linux）
source venv/bin/activate
3️⃣ 安装依赖
pip install -r requirements.txt
4️⃣ （可选）安装 Playwright Chromium
PLAYWRIGHTBROWSERSPATH="$HOME/.xhs_system/ms-playwright" python -m playwright install chromium
5️⃣ 启动程序（首次启动会自动初始化数据库）
./启动程序.sh

./启动程序.sh 会自动检测可用 Python；如果本地 venv/bin/python 已损坏，也会回退到系统 Python 启动，并提示你后续可用 ./install.sh 修复环境。

提示：

• 运行数据默认存放于 ~/.xhs_system/（数据库、日志、浏览器缓存等）
• 也可通过 XHSDATADIR=/your/path 改为自定义目录（Docker/服务模式推荐）

• Windows 安装失败（多为 PyQt5）：请用 Python 3.11/3.12（64 位），避免 Python 3.13 或 32 位 Python
• Linux 浏览器启动失败：可能缺少系统依赖，执行 sudo python -m playwright install-deps chromium（或对应发行版命令）
• qt.qpa.fonts ... Microsoft YaHei：Qt 的字体告警，可忽略；当前版本已改为自动选择系统可用字体
• 内容页个别符号显示“方框/叉号”：通常是系统字体不支持该字符（emoji/圈数字/信息符号等）；建议减少特殊符号，或更换/安装字体（程序也会做一部分字符清理/替换）

📱 使用指南

🎯 基础使用流程

flowchart LR
    A[🚀 启动程序] --> B[📱 登录账户]
    B --> C[✍️ 输入主题]
    C --> D[🤖 AI生成内容]
    D --> E[👀 预览效果]
    E --> F[📤 一键发布]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#e8f5e8
    style D fill:#fff3e0
    style E fill:#fce4ec
    style F fill:#e0f2f1

📝 详细步骤

• 🚀 启动程序

• 👥 用户管理（可选）

• 🌐 浏览器环境（可选）

• 📊 数据中心（可选）

• 🖼️ 封面模板（可选）

• 📱 账户登录

• 🔗 网页链接导入（可选）

• ✍️ 内容创作

• 🖼️ 图片处理

• 👀 预览发布

🤖 自定义模型与模板

• 入口：侧边栏「⚙️ 后台配置」→「AI模型配置」
• API Key：保存时默认加密写入 ~/.xhs_system/keys.enc（settings.json 不再明文保存）
• 文案模板：在「文案模板」下拉框选择；模板文件位于 templates/prompts/
• 系统图片模板：侧边栏「⚙️ 后台配置」→「模板库」可选择/导入（将外部模板导入到 ~/.xhssystem/systemtemplates，便于跨平台使用）
• 封面模板：侧边栏「🖼️ 封面中心」选择并应用到首页；生成图片默认缓存于 ~/.xhssystem/generatedimgs/，可在首页「📥 下载图片」导出

⚙️ 通过 .env 配置模型（可选，推荐 OpenAI-compatible）

.env 已在 .gitignore，不会推送到 GitHub；请勿把真实 key 写进 .env.example。

cp .env.example .env

说明：

• 默认优先使用 UI「AI模型配置」里的设置；仅当 UI 未配置时才会使用 .env 作为兜底
• 如需强制使用 .env，将 XHSLLMOVERRIDE=true
• XHSLLMBASEURL 可填 baseurl（如 .../v1、.../api/paas/v4）或完整的 .../chat/completions（程序会自动补全）

XHSLLMBASE_URL=https://open.bigmodel.cn/api/paas/v4
XHSLLMMODEL=glm-5
XHSLLMAPI_KEY=你的key
可选：强制使用环境变量（即使 UI 已配置）
XHSLLMOVERRIDE=true
可选：GLM-5 建议给大一点
XHSLLMTIMEOUT=120
XHSLLMMAX_TOKENS=3200

图片排版风格（可选）：

XHSIMGSHOW_TAGS=false
XHSIMGSHOWCONTENTCARD=false
XHSIMGBOXEDLISTCARDS=false

🔧 高级配置

📁 数据与配置位置

• ~/.xhs_system/settings.json：应用配置（手机号/标题/模型/模板等）
• ~/.xhs_system/keys.enc：模型 API Key 加密存储
• ~/.xhssystem/xhsdata.db：本地数据库（用户/浏览器环境等）
• ~/.xhssystem/generatedimgs/：生成图片缓存
• ~/.xhs_system/ms-playwright/：Playwright 浏览器缓存目录
• ~/.xhs_system/logs/：运行日志
• ~/.xhssystem/hotspotscache.json：热点缓存
• ~/.xhssystem/scheduletasks.json：定时发布任务

📊 开发路线图

• [x] ✅ 基础功能: 内容生成和发布
• [x] ✅ 用户管理: 多账户/当前用户切换/数据隔离
• [x] ✅ 模板库: 文案模板 + 系统图片模板导入 + 封面模板库
• [x] ✅ 数据中心: 多平台热榜采集 + 一键带回首页生成
• [x] ✅ 定时发布: 支持任务管理与到点自动发布（需保持程序运行）
• [ ] 🔄 发布效果分析: 数据统计/分析面板持续完善
• [ ] 🔄 API接口: 开放API接口

🤝 参与贡献

🛠️ 贡献指南

• 🍴 Fork 项目
• 🌿 创建功能分支 (git checkout -b feature/AmazingFeature)
• 💾 提交更改 (git commit -m 'Add some AmazingFeature')
• 📤 推送到分支 (git push origin feature/AmazingFeature)
• 🔄 创建 Pull Request

📞 联系我们

💬 加入我们的社区

🐱 微信群 扫码加入讨论

📱 公众号 获取最新动态

⭐ Star 历史

📄 许可证