📝 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/）
This commit is contained in:
@@ -0,0 +1,37 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: GitHub Actions CI 工作流在 Push 和 PR 时自动触发
|
||||
项目 SHALL 在 `.github/workflows/ci.yml` 提供持续集成工作流，在每次 Push 到 `main` 分支或创建 Pull Request 时自动执行代码质量检查。
|
||||
|
||||
#### Scenario: CI 在 PR 时自动运行
|
||||
- **WHEN** 贡献者向 `main` 分支提交 Pull Request
|
||||
- **THEN** GitHub Actions SHALL 自动触发 CI 工作流，在 PR 页面显示检查结果
|
||||
|
||||
#### Scenario: CI 通过后状态徽章更新
|
||||
- **WHEN** CI 工作流执行完毕
|
||||
- **THEN** 工作流状态 SHALL 可通过 Badge URL 获取，用于 README 展示
|
||||
|
||||
### Requirement: CI 执行 ruff 代码风格检查
|
||||
CI 工作流 SHALL 使用 `ruff` 对所有 Python 文件执行代码风格和常见错误检查，ruff 配置 SHALL 允许项目现有代码通过（宽松规则集）。
|
||||
|
||||
#### Scenario: 代码风格检查通过
|
||||
- **WHEN** CI 工作流中的 ruff 步骤执行
|
||||
- **THEN** 对 `*.py` 文件的 ruff 检查 SHALL 以 exit code 0 退出，工作流标记为 passed
|
||||
|
||||
#### Scenario: 引入明显错误时 CI 失败
|
||||
- **WHEN** PR 中包含未使用的 import 或明显语法问题
|
||||
- **THEN** ruff SHALL 检测到并返回非零 exit code，导致 CI 失败
|
||||
|
||||
### Requirement: CI 执行导入验证
|
||||
CI 工作流 SHALL 执行 Python 导入验证步骤，确认核心模块可被正常导入，及早发现迁移引入的导入错误。
|
||||
|
||||
#### Scenario: 导入验证通过
|
||||
- **WHEN** CI 执行导入验证步骤
|
||||
- **THEN** `python -c "from services.config_manager import ConfigManager"` 等关键导入 SHALL 成功执行
|
||||
|
||||
### Requirement: 提供 requirements-dev.txt 开发依赖声明
|
||||
项目根目录 SHALL 包含 `requirements-dev.txt`，声明开发和 CI 所需依赖（ruff、pre-commit 等），与生产依赖 `requirements.txt` 分离。
|
||||
|
||||
#### Scenario: 安装开发依赖命令可正常执行
|
||||
- **WHEN** 开发者执行 `pip install -r requirements-dev.txt`
|
||||
- **THEN** 所有开发工具 SHALL 成功安装，无版本冲突
|
||||
@@ -0,0 +1,33 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 提供标准化 GitHub Issue 模板
|
||||
项目 SHALL 在 `.github/ISSUE_TEMPLATE/` 下提供至少两个 Issue 模板：Bug 报告模板和功能请求模板，引导贡献者提供必要信息。
|
||||
|
||||
#### Scenario: Bug 报告模板包含必要字段
|
||||
- **WHEN** 用户在 GitHub 上新建 Issue 并选择「Bug 报告」
|
||||
- **THEN** 模板 SHALL 包含：问题描述、复现步骤、预期行为、实际行为、环境信息（Python 版本、操作系统）
|
||||
|
||||
#### Scenario: 功能请求模板包含场景描述
|
||||
- **WHEN** 用户选择「功能请求」模板
|
||||
- **THEN** 模板 SHALL 包含：问题/需求背景、期望的解决方案、替代方案考虑
|
||||
|
||||
### Requirement: 提供 Pull Request 模板
|
||||
项目 SHALL 在 `.github/pull_request_template.md` 提供 PR 模板，引导贡献者说明变更范围和测试情况。
|
||||
|
||||
#### Scenario: PR 模板包含变更说明和测试确认
|
||||
- **WHEN** 贡献者在 GitHub 上发起 Pull Request
|
||||
- **THEN** 模板 SHALL 包含：变更类型（Bug Fix / Feature / Docs / Refactor）、变更描述、测试说明、相关 Issue 引用
|
||||
|
||||
### Requirement: 包含行为准则文件
|
||||
项目根目录 SHALL 包含 `CODE_OF_CONDUCT.md`，采用 Contributor Covenant v2.1 中文版，明确社区行为规范和违规处理方式。
|
||||
|
||||
#### Scenario: 行为准则文件可访问
|
||||
- **WHEN** 贡献者查看项目根目录
|
||||
- **THEN** `CODE_OF_CONDUCT.md` SHALL 存在，包含社区行为规范、适用范围、执行说明、联系方式
|
||||
|
||||
### Requirement: 包含安全漏洞报告政策
|
||||
项目根目录 SHALL 包含 `SECURITY.md`，说明如何负责任地披露安全漏洞、支持的版本范围和响应时间承诺。
|
||||
|
||||
#### Scenario: 安全政策文件包含报告方式
|
||||
- **WHEN** 安全研究者发现漏洞
|
||||
- **THEN** `SECURITY.md` SHALL 提供私下联系方式（邮件或 GitHub Security Advisory），不要求通过公开 Issue 上报
|
||||
@@ -0,0 +1,29 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: README 顶部展示状态徽章
|
||||
`README.md` 顶部（标题下方）SHALL 包含至少三枚徽章：Python 版本要求、License 类型、CI 状态，采用 shields.io 或 GitHub Actions 徽章格式。
|
||||
|
||||
#### Scenario: 徽章在 GitHub 页面正常渲染
|
||||
- **WHEN** 访问项目 GitHub 主页
|
||||
- **THEN** README 顶部 SHALL 显示可点击的 Python、MIT License、CI 状态徽章，链接指向对应资源
|
||||
|
||||
### Requirement: README 项目结构图反映实际代码
|
||||
`README.md` 中的「项目结构」章节 SHALL 反映迁移后的实际目录结构，包含 `services/`（含所有迁移后文件）和 `ui/`（含 `app.py`、`tab_create.py`）的正确层级。
|
||||
|
||||
#### Scenario: 项目结构与 ls 输出一致
|
||||
- **WHEN** 开发者对照 README 查看实际文件目录
|
||||
- **THEN** README 的结构图 SHALL 与实际 `Get-ChildItem` / `ls` 输出一致，无过时文件或缺失目录
|
||||
|
||||
### Requirement: README 不包含 your-username 占位符
|
||||
`README.md` 中所有 `your-username` 占位符 SHALL 替换为实际仓库路径说明或格式示例，使克隆/安装命令可直接复制使用。
|
||||
|
||||
#### Scenario: 安装命令无需手动替换占位符
|
||||
- **WHEN** 用户复制 README 中的 `git clone` 命令
|
||||
- **THEN** 命令 SHALL 包含实际仓库 URL 或明确的 `<your-github-username>` 格式提示，不出现 `your-username` 字符串
|
||||
|
||||
### Requirement: README 使用指南与当前 UI 结构匹配
|
||||
`README.md` 中的「使用指南」和「首次使用流程」章节 SHALL 引用当前正确的 Tab 名称和操作路径，与 `ui/app.py` 实际 Tab 顺序保持一致（⚙️ 配置 Tab 已迁移，不再是「展开全局设置折叠块」）。
|
||||
|
||||
#### Scenario: 首次使用步骤描述与 UI 一致
|
||||
- **WHEN** 新用户按照 README「首次使用流程」操作
|
||||
- **THEN** README 中描述的 Tab 名称和操作入口 SHALL 与实际 Gradio UI 一致，用户无需猜测
|
||||
@@ -0,0 +1,49 @@
|
||||
## 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 将其显示为已忽略文件
|
||||
Reference in New Issue
Block a user