xhs_factory/spec.md at 2ba87c8f6ec76166a71f0f1c913822285f71c920

zhoujie/xhs_factory

Fork 0

zhoujie 2ba87c8f6e

CI / Lint (ruff) (push) Has been cancelled

Details

CI / Import Check (push) Has been cancelled

Details

📝 docs(project): 添加开源社区标准文档与 CI 工作流

- 新增 GitHub Issue 模板（Bug 报告、功能请求）和 Pull Request 模板
- 新增 Code of Conduct（贡献者行为准则）和 Security Policy（安全政策）
- 新增 CI 工作流（GitHub Actions），包含 ruff 代码检查和导入验证
- 新增开发依赖文件 requirements-dev.txt

📦 build(ci): 配置 GitHub Actions 持续集成

- 在 push 到 main 分支和 pull request 时自动触发 CI
- 添加 lint 任务执行 ruff 代码风格检查
- 添加 import-check 任务验证核心服务模块导入

♻️ refactor(structure): 重构项目目录结构

- 将根目录的 6 个服务模块迁移至 services/ 包
- 更新所有相关文件的导入语句（main.py、ui/、services/）
- 根目录仅保留 main.py 作为唯一 Python 入口文件

🔧 chore(config): 调整配置和资源文件路径

- 将 config.json 移至 config/ 目录，更新相关引用
- 将个人头像图片移至 assets/faces/ 目录，更新 .gitignore
- 更新 Dockerfile 和 docker-compose.yml 中的配置路径

📝 docs(readme): 完善 README 文档

- 添加项目状态徽章（Python 版本、License、CI）
- 更新项目结构图反映实际目录布局
- 修正使用指南中的 Tab 名称和操作路径
- 替换 your-username 占位符为格式提示

🗑️ chore(cleanup): 清理冗余文件

- 删除旧版备份文件、测试脚本、临时记录和运行日志
- 删除散落的个人图片文件（已归档至 assets/faces/）

2026-02-27 22:12:39 +08:00

2.7 KiB

Raw Blame History

ADDED Requirements

Requirement: 根目录只包含正式项目文件

项目根目录 SHALL 不包含备份文件、一次性测试脚本、个人媒体资源或临时记录文件。具体地：

*_backup.py 命名的文件 SHALL 不存在于根目录
config copy.json（或同类配置副本）SHALL 不存在
_test_*.py 命名的一次性测试脚本 SHALL 不存在于根目录
*.log 运行日志文件 SHALL 不进入版本控制（由 .gitignore 保证）
个人图片（.png、.jpg 等媒体文件）SHALL 不散落在根目录，统一归入 assets/ 下对应子目录

Scenario: 克隆仓库后根目录无冗余文件

WHEN 开发者执行 git clone 并查看根目录
THEN 根目录 SHALL 仅包含：main.py、服务模块文件（*_service.py、*_client.py、*_manager.py、*_queue.py）、标准配置（config.example.json、requirements.txt、Dockerfile、docker-compose.yml、.gitignore、.dockerignore）、自动启动脚本（_autostart.*）、文档（README.md、CHANGELOG.md、CONTRIBUTING.md、mcp.md）

Scenario: 备份文件不出现在版本控制

WHEN 开发者执行 git status 或 git ls-files
THEN 输出中 SHALL 不包含 *_backup.py、config copy.json 等备份/副本文件

Requirement: 媒体资源归入 assets/ 目录

项目所需的图片等媒体资源 SHALL 存放于 assets/ 目录下的对应子目录，根据用途分类：

换脸/头像相关图片 SHALL 放入 assets/faces/
assets/faces/ SHALL 被 .gitignore 覆盖（不进入版本控制，属隐私数据）

Scenario: 换脸图片存放路径符合规范

WHEN 用户配置换脸头像功能
THEN 头像文件 SHALL 存放于 assets/faces/ 目录，而非项目根目录

Scenario: assets/faces/ 不进入版本控制

WHEN 开发者执行 git status
THEN assets/faces/ 目录下的文件 SHALL 显示为已忽略（不出现在 staged 或 unstaged 区域）

Requirement: .gitignore 覆盖所有非版本控制内容

项目 .gitignore SHALL 包含以下规则类别，且每类规则 SHALL 有注释说明用途：

Python 编译产物（__pycache__/、*.py[cod]）
虚拟环境目录（.venv/、venv/）
敏感配置（config.json、cookies.json、*.cookie）
运行日志（*.log、logs/）
备份与副本文件（*_backup.py、config copy.json）
个人媒体资产（assets/faces/）
IDE 配置（.vscode/、.idea/）
系统文件（.DS_Store、Thumbs.db）
工作空间输出目录（xhs_workspace/）

Scenario: 新增备份文件不被 git 追踪

WHEN 开发者在根目录创建 main_v2_backup.py
THEN git status SHALL 将其显示为已忽略文件

2.7 KiB Raw Blame History Unescape Escape