📝 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
parent b5deafa2cc
commit 2ba87c8f6e
58 changed files with 1119 additions and 468 deletions
@@ -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,34 @@
+## ADDED Requirements
+
+### Requirement: 服务层文件统一归入 services/ 包
+所有业务服务模块 SHALL 位于 `services/` 目录下，根目录除 `main.py` 外 SHALL 不包含任何 `.py` 业务文件。
+
+迁移文件清单：
+- `config_manager.py` → `services/config_manager.py`
+- `llm_service.py` → `services/llm_service.py`
+- `sd_service.py` → `services/sd_service.py`
+- `mcp_client.py` → `services/mcp_client.py`
+- `analytics_service.py` → `services/analytics_service.py`
+- `publish_queue.py` → `services/publish_queue.py`
+
+#### Scenario: 根目录不存在游离服务文件
+- **WHEN** 开发者查看项目根目录
+- **THEN** 根目录 SHALL 仅含 `main.py` 作为唯一 Python 入口，其余 `.py` 文件均位于 `ui/` 或 `services/` 子目录
+
+### Requirement: 外部模块使用绝对导入访问 services/
+`main.py`、`ui/app.py`、`ui/tab_create.py` 等根目录/UI 层文件在导入服务模块时 SHALL 使用绝对导入格式 `from services.<module> import ...`。
+
+#### Scenario: main.py 正常启动无 ImportError
+- **WHEN** 在项目根目录执行 `python main.py`
+- **THEN** 应用 SHALL 正常启动，不抛出任何 `ImportError` 或 `ModuleNotFoundError`
+
+#### Scenario: UI 层导入路径正确
+- **WHEN** 执行 `python -c "import ui.app"`
+- **THEN** 不抛出导入错误，所有 `from services.*` 引用 SHALL 可正常解析
+
+### Requirement: services/ 内部使用相对导入
+`services/` 包内各模块之间的相互引用 SHALL 使用相对导入格式 `from .<module> import ...`，不依赖根目录在 `sys.path` 中的位置。
+
+#### Scenario: services 内部导入独立于运行上下文
+- **WHEN** 在任意工作目录执行 `python -m services.scheduler`（或类似模块测试）
+- **THEN** 内部相对导入 SHALL 正常解析，不因工作目录不同而失败