# 贡献指南

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

## 开发环境搭建

```bash
# 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](https://www.conventionalcommits.org/) 规范：

```
<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 (8 Tabs) + 业务逻辑 + 自动化调度
├─ config_manager.py # 配置管理：单例模式，多 LLM 提供商
├─ llm_service.py    # LLM 封装：文案生成、热点分析、评论回复、SD Prompt 指南
├─ sd_service.py     # SD 封装：3 模型适配 + 9 人设视觉方案 + 换脸 + 反AI后处理
├─ mcp_client.py     # MCP 客户端：小红书搜索、发布、评论、点赞
├─ analytics_service.py  # 笔记数据分析 & 权重学习服务
└─ publish_queue.py      # 内容排期队列（SQLite + 后台 Publisher）
```

### 核心设计原则

- **模块解耦** — 各服务独立封装，通过配置管理器共享状态
- **MCP 协议** — 通过 JSON-RPC 与小红书 MCP 服务通信，不直接操作浏览器
- **LLM 无关** — 支持所有 OpenAI 兼容 API，不绑定特定提供商
- **UI 逻辑分离** — 业务函数与 Gradio UI 组件分开定义
- **人设驱动** — 从文案风格到图片视觉，人设参数贯穿全链路
- **防风控** — 每日操作限额、随机间隔、错误冷却、反 AI 检测多重保护

## 代码风格

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

## 感谢

感谢每一位贡献者！🙏