xhs_factory/CONTRIBUTING.md

贡献指南

感谢你对本项目的关注！我们欢迎任何形式的贡献，包括但不限于 Bug 报告、功能建议、代码提交和文档改进。

开发环境搭建

# 1. Fork 并克隆项目
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. 复制配置文件
cp config.example.json config.json
# 编辑 config.json 填写你的 API Key

# 5. 启动开发
python main.py

提交规范

本项目使用 Conventional Commits 规范：

<type>(<scope>): <description>

[可选正文]

[可选脚注]

Type 类型

类型	说明
feat	新功能
fix	Bug 修复
docs	文档更新
style	代码格式调整（不影响逻辑）
refactor	重构（非新功能、非修复）
perf	性能优化
test	测试相关
chore	构建/工具变更

示例

feat(auto): 增加自动收藏功能
fix(llm): 修复 JSON 模式下 400 错误
docs: 更新 README 安装步骤
refactor(mcp): 重构评论解析逻辑

Pull Request 流程

1. Fork 本仓库
2. 从 main 创建特性分支：git checkout -b feature/your-feature
3. 编写代码并测试
4. 确保代码风格一致（建议使用 IDE 自动格式化）
5. 提交更改，遵循上述提交规范
6. 推送分支：git push origin feature/your-feature
7. 在 GitHub 上发起 Pull Request，描述你的更改内容

Bug 报告

提交 Issue 时请包含：

• 环境信息：Python 版本、操作系统、相关服务版本
• 复现步骤：尽可能详细的操作步骤
• 期望行为：你认为应该发生什么
• 实际行为：实际发生了什么
• 日志/截图：如有错误日志或截图请附上

功能建议

欢迎通过 Issue 提交功能建议，请描述：

• 使用场景：你在什么情况下需要这个功能
• 期望功能：你希望它如何工作
• 参考实现：是否有类似的项目/功能可参考

项目架构

main.py              # 主程序：Gradio UI + 业务逻辑 + 自动化调度
├─ config_manager.py # 配置管理：单例模式，多 LLM 提供商
├─ llm_service.py    # LLM 封装：文案生成、热点分析、评论回复
├─ sd_service.py     # SD 封装：txt2img、img2img（JuggernautXL 优化）
└─ mcp_client.py     # MCP 客户端：小红书搜索、发布、评论、点赞

核心设计原则

• 模块解耦 — 各服务独立封装，通过配置管理器共享状态
• MCP 协议 — 通过 JSON-RPC 与小红书 MCP 服务通信，不直接操作浏览器
• LLM 无关 — 支持所有 OpenAI 兼容 API，不绑定特定提供商
• UI 逻辑分离 — 业务函数与 Gradio UI 组件分开定义

代码风格

• Python 3.10+ 语法
• 函数和类使用中文 docstring
• 日志使用 logging 模块，不使用 print
• 配置通过 ConfigManager 单例管理，不硬编码

感谢

感谢每一位贡献者！🙏