zhoujie
a75d6ea422
- 更新 CHANGELOG.md，新增 v2.5.0 版本日志，记录人设专属 SD 视觉优化、新增人设及内容排期系统等重大功能 - 更新 CONTRIBUTING.md 项目架构图，补充新增的服务模块（analytics_service.py, publish_queue.py）和核心设计原则 - 全面更新 README.md，将项目标题升级至 V2.5，重构功能特性章节以对应 8 个 Tab，新增人设系统、内容排期、智能学习、反 AI 检测等核心功能的详细说明，并更新配置说明和常见问题解答
123 lines
3.5 KiB
Markdown
123 lines
3.5 KiB
Markdown
# 贡献指南
|
||
|
||
感谢你对本项目的关注！我们欢迎任何形式的贡献，包括但不限于 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` 单例管理，不硬编码
|
||
|
||
## 感谢
|
||
|
||
感谢每一位贡献者！🙏
|