📝 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,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-02-26
|
||||
@@ -0,0 +1,36 @@
|
||||
## Context
|
||||
|
||||
项目工作区根目录（`f:\3_Personal\AI\xhs_bot\autobot\`）随开发过程积累了多个无用文件：旧版备份（`main_v1_backup.py`）、配置副本（`config copy.json`）、一次性测试脚本（`_test_config_save.py`）、临时记录（`Todo.md`）、运行日志（`autobot.log``）以及散落的个人图片（4 张 `.png`/`.jpg`）。
|
||||
|
||||
这些文件虽已被 `.gitignore` 排除出版本控制，但依然存在于工作区，干扰了目录可读性。无需改动任何运行时逻辑。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 删除 5 个明确无用的文件
|
||||
- 将 4 张个人图片归入 `assets/faces/` 目录并更新 `.gitignore`
|
||||
- 完善 `.gitignore` 注释与规则覆盖
|
||||
- 建立 `project-structure` 规范 spec，为后续维护提供参考
|
||||
|
||||
**Non-Goals:**
|
||||
- 不将根目录服务文件（`analytics_service.py`、`llm_service.py` 等）迁移至 `services/`（涉及 import 改动，留作独立变更）
|
||||
- 不修改任何 Python 业务代码
|
||||
- 不调整 Docker / CI 配置
|
||||
|
||||
## Decisions
|
||||
|
||||
**决策 1：图片归档至 `assets/faces/`**
|
||||
- 选择 `assets/faces/` 而非直接删除，因为换脸功能可能在 UI 中需要默认头像路径，保留文件可避免破坏演示/教学场景
|
||||
- 替代方案：直接删除 → 风险是用户文档引用了这些文件路径
|
||||
|
||||
**决策 2：`assets/faces/` 整体纳入 `.gitignore`**
|
||||
- 个人图片属于隐私敏感数据，不应进入版本控制
|
||||
- 在 `.gitignore` 中新增 `assets/faces/` 规则，并补充注释
|
||||
|
||||
**决策 3：`Todo.md` 直接删除而非迁移**
|
||||
- 内容已过时且已有 openspec 任务管理体系替代，迁移意义不大
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **[风险] `my_face.png` 等文件路径可能被 `config.json` 引用** → 缓解：删除前检查 `config.json` 中是否存在相关路径字段；若存在则仅移动不删除，并在 `config.example.json` 中更新说明
|
||||
- **[风险] `_autostart.bat` / `_autostart.vbs` 与 `assets/faces/` 路径无关，但同属根目录非标准文件** → 此次保留，自动启动脚本属于有效使用场景
|
||||
@@ -0,0 +1,33 @@
|
||||
## Why
|
||||
|
||||
项目根目录混入备份文件、临时测试脚本、个人图片等无关文件，导致目录结构混乱、难以辨别哪些是正式代码。部分内容（人脸图片、日志文件）已被 `.gitignore` 排除但仍残留在工作区，须手动清理。
|
||||
|
||||
## What Changes
|
||||
|
||||
- **删除冗余/备份文件**：
|
||||
- `main_v1_backup.py`（旧版备份，已被 `.gitignore` 的 `*_backup.py` 规则覆盖）
|
||||
- `config copy.json`（配置副本，已被 `.gitignore` 覆盖）
|
||||
- `_test_config_save.py`（一次性测试脚本，无保留价值）
|
||||
- `Todo.md`（个人临时记录，已有 openspec 任务管理替代）
|
||||
- `autobot.log`（运行日志，已被 `*.log` 规则覆盖）
|
||||
|
||||
- **整理个人图片**：将散落在根目录的人脸/头像图片（`beauty.png`、`myself.jpg`、`my_face.png`、`zjz.png`）移入 `assets/faces/` 目录，更新 `.gitignore` 将该目录纳入忽略范围
|
||||
|
||||
- **评估根目录服务文件**：检查 `analytics_service.py`、`llm_service.py`、`sd_service.py`、`mcp_client.py`、`publish_queue.py`、`config_manager.py` 是否应迁移至 `services/`；若涉及大量 import 改动则列为独立后续变更，本次仅做评估记录
|
||||
|
||||
- **补全 `.gitignore`**：确保 `assets/faces/`、`*.log`、`__pycache__/` 等规则完整且注释清晰
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `project-structure`: 定义项目标准目录结构、根目录文件清单规范及 `.gitignore` 策略
|
||||
|
||||
### Modified Capabilities
|
||||
（无需修改现有 spec）
|
||||
|
||||
## Impact
|
||||
|
||||
- 删除 5 个文件，不影响任何运行时逻辑
|
||||
- `assets/faces/` 目录新增后，换脸功能的默认头像路径可能需要在 `config.example.json` 中更新说明
|
||||
- 对 Docker 构建无影响（`.dockerignore` 已存在）
|
||||
- 无 API 变更，无依赖变更
|
||||
+49
@@ -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 将其显示为已忽略文件
|
||||
@@ -0,0 +1,25 @@
|
||||
## 1. 删除冗余文件
|
||||
|
||||
- [x] 1.1 删除 `main_v1_backup.py`（旧版备份，无保留价值）
|
||||
- [x] 1.2 删除 `config copy.json`（配置副本，无保留价值）
|
||||
- [x] 1.3 删除 `_test_config_save.py`（一次性测试脚本）
|
||||
- [x] 1.4 删除 `Todo.md`（临时记录，已由 openspec 替代）
|
||||
- [x] 1.5 删除 `autobot.log`（运行日志，已被 `.gitignore` 覆盖）
|
||||
|
||||
## 2. 整理图片资源
|
||||
|
||||
- [x] 2.1 创建 `assets/faces/` 目录
|
||||
- [x] 2.2 将 `my_face.png` 移入 `assets/faces/my_face.png`
|
||||
- [x] 2.3 将 `beauty.png`、`myself.jpg`、`zjz.png` 移入 `assets/faces/`
|
||||
- [x] 2.4 更新 `sd_service.py` 第 22 行的 `FACE_IMAGE_PATH`，将路径从 `"my_face.png"` 改为 `os.path.join(os.path.dirname(__file__), "assets", "faces", "my_face.png")`
|
||||
|
||||
## 3. 完善 .gitignore
|
||||
|
||||
- [x] 3.1 在 `.gitignore` 中新增 `assets/faces/` 规则，并加注释（个人头像不入版本控制）
|
||||
- [x] 3.2 确认 `.gitignore` 中 `*.log` 规则已存在（已有，检查确认即可）
|
||||
|
||||
## 4. 回归验证
|
||||
|
||||
- [ ] 4.1 启动应用 `python main.py`，确认换脸功能（⚙️ 配置 Tab AI 换脸头像）加载正常
|
||||
- [ ] 4.2 确认 `SDService.load_face_image()` 能正确读取新路径下的 `my_face.png`
|
||||
- [x] 4.3 执行 `git status` 确认 `assets/faces/` 已被忽略，根目录无残留冗余文件
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-02-27
|
||||
@@ -0,0 +1,55 @@
|
||||
## Context
|
||||
|
||||
当前项目根目录同时存在 6 个业务服务文件（`config_manager.py`、`llm_service.py`、`sd_service.py`、`mcp_client.py`、`analytics_service.py`、`publish_queue.py`）与 `services/` 包目录并列，架构层次混乱。`services/` 下游代码（`scheduler.py` 等）通过裸名导入（flat import）引用这些文件，依赖 Python 将根目录隐式加入 `sys.path` 这一运行时特性。
|
||||
|
||||
迁移约束：
|
||||
- `services/__init__.py` 已存在，`services/` 是合法 Python 包
|
||||
- 所有受影响文件共约 20 处 import，分布在 `main.py`、`ui/app.py`、`ui/tab_create.py`、`services/*.py`
|
||||
- 必须保证 Python 不产生循环导入（circular import）
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 将 6 个服务文件移入 `services/`，根目录只保留 `main.py` 一个 Python 文件
|
||||
- 所有 import 使用绝对路径（`from services.xxx import ...`），保持一致性、可读性
|
||||
- `services/` 内部文件之间使用相对导入（`from .xxx import ...`），减少路径依赖
|
||||
- 不引入任何新的运行时依赖或行为变更
|
||||
|
||||
**Non-Goals:**
|
||||
- 不拆分或合并任何模块的内部逻辑
|
||||
- 不更改 `services/__init__.py` 的公开导出（除非需要兼容性垫片）
|
||||
- 不迁移 `ui/` 下的文件（已有独立模块结构）
|
||||
|
||||
## Decisions
|
||||
|
||||
**决策 1：外部文件用绝对导入 `from services.xxx import ...`**
|
||||
- `main.py`、`ui/app.py`、`ui/tab_create.py` 均从根目录运行，绝对导入路径清晰、错误信息可读
|
||||
- 替代：在 `services/__init__.py` 重新导出所有符号（向后兼容）→ 增加维护负担，拒绝
|
||||
|
||||
**决策 2：`services/` 内文件之间用相对导入 `from .xxx import ...`**
|
||||
- 避免 `services/` 内部对根目录的隐式依赖，打包或测试时不受 `sys.path` 影响
|
||||
- 替代：也用绝对导入 → 可行但不如相对导入内聚
|
||||
|
||||
**决策 3：分两阶段迁移（先移文件，再改 import）**
|
||||
- 防止中间状态同时修改多文件导致错误难以定位
|
||||
- 迁移顺序：`config_manager` → `mcp_client` → `llm_service` → `sd_service` → `analytics_service` → `publish_queue`（按依赖深度从浅到深）
|
||||
|
||||
**决策 4：不添加兼容性垫片（shim）**
|
||||
- 项目无外部 PyPI 消费者，无向后兼容压力，直接修改所有 import 更干净
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- **[风险] `services/` 内循环导入** → 缓解：迁移前用 `grep` 确认依赖关系，`config_manager` 通常是叶节点（最少依赖），优先迁移
|
||||
- **[风险] `ui/app.py` 在迁移中途启动失败** → 缓解：一次性修改所有文件 import，不留半迁移状态；迁移后立即用 `ast.parse()` 验证语法
|
||||
- **[风险] Dockerfile `COPY . .` 已是整目录复制** → 无影响，`services/` 子目录正常复制
|
||||
- **[风险] CI 首次运行可能因 GitHub Secrets 缺失（如无 `GITHUB_TOKEN`）报错** → 缓解：CI 仅做静态检查，不需要 Secrets
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. 将 6 个文件 `Move-Item` 到 `services/`
|
||||
2. 批量替换所有外部文件（`main.py`、`ui/*.py`）中的 import：`from xxx` → `from services.xxx`
|
||||
3. 批量替换 `services/*.py` 中的内部 import：`from xxx` → `from .xxx`
|
||||
4. 语法验证：对所有修改文件执行 `ast.parse()`
|
||||
5. 启动验证：`python -c "from ui.app import build_app"` 确认无导入错误
|
||||
|
||||
**回滚方案：** 删除 `services/` 下新迁移的文件，将 git 恢复（或手动移回根目录），改回 import）
|
||||
@@ -0,0 +1,57 @@
|
||||
## Why
|
||||
|
||||
项目代码已具备完整功能，但存在两个问题：①缺少优秀开源项目的标准配置（Issue/PR 模板、CI、Code of Conduct、Security Policy），降低社区协作门槛和可信度；②根目录混杂 6 个服务文件（`llm_service.py`、`sd_service.py`、`mcp_client.py`、`analytics_service.py`、`publish_queue.py`、`config_manager.py`），与 `services/` 模块目录并列，架构层次不清晰。两个问题结合目录清理后的稳定状态一并解决。
|
||||
|
||||
## What Changes
|
||||
|
||||
### 目录结构整理
|
||||
- **将 6 个根目录服务文件迁移至 `services/`**：
|
||||
- `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`
|
||||
- **更新所有受影响文件的 import 语句**（`main.py`、`ui/app.py`、`ui/tab_create.py`、`services/*.py` 共约 20 处）
|
||||
- **更新 `services/__init__.py`** 导出新增模块（可选，保持向后兼容）
|
||||
|
||||
目标根目录结构：
|
||||
```
|
||||
autobot/
|
||||
├── main.py # 程序入口（唯一根目录 .py）
|
||||
├── ui/ # UI 层 (Gradio)
|
||||
├── services/ # 全部业务逻辑层（迁移后）
|
||||
├── assets/ # 静态资源
|
||||
├── config.example.json # 配置模板
|
||||
├── requirements.txt # 生产依赖
|
||||
├── requirements-dev.txt # 开发依赖（新增）
|
||||
├── Dockerfile / docker-compose.yml
|
||||
└── *.md / LICENSE # 文档
|
||||
```
|
||||
|
||||
### 开源社区标准文件
|
||||
- **新增 GitHub Issue 模板** — `.github/ISSUE_TEMPLATE/bug_report.md` 和 `feature_request.md`
|
||||
- **新增 PR 模板** — `.github/pull_request_template.md`
|
||||
- **新增 CI 工作流** — `.github/workflows/ci.yml`（Push/PR 触发 ruff + 导入验证）
|
||||
- **新增 Code of Conduct** — `CODE_OF_CONDUCT.md`（Contributor Covenant v2.1 中文版）
|
||||
- **新增 Security Policy** — `SECURITY.md`
|
||||
- **新增 `requirements-dev.txt`** — ruff、pre-commit
|
||||
- **完善 README**：顶部徽章（Python、License、CI）、修正项目结构图、替换 `your-username` 占位符
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `project-restructure`: 根目录服务文件迁移至 `services/`，全量 import 更新，分层架构清晰
|
||||
- `oss-community-health`: Issue 模板、PR 模板、Code of Conduct、Security Policy
|
||||
- `oss-ci-workflow`: GitHub Actions CI（ruff 代码检查 + 导入验证）
|
||||
- `oss-readme-polish`: README 徽章、结构说明修正、占位符修复
|
||||
|
||||
### Modified Capabilities
|
||||
（无需修改现有 spec）
|
||||
|
||||
## Impact
|
||||
|
||||
- `project-restructure`：影响 `main.py`、`ui/app.py`、`ui/tab_create.py`、`services/` 下全部文件（仅修改 import 路径，不改业务逻辑）
|
||||
- 社区文件和 CI 仅新增，不修改现有代码
|
||||
- Dockerfile 的 `COPY` 指令兼容（整目录复制，无需修改）
|
||||
- 对运行时行为、Docker 部署、依赖均无影响
|
||||
@@ -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 成功安装，无版本冲突
|
||||
+33
@@ -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 一致，用户无需猜测
|
||||
+34
@@ -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 正常解析，不因工作目录不同而失败
|
||||
@@ -0,0 +1,186 @@
|
||||
## Tasks
|
||||
|
||||
### 1. 迁移服务文件至 services/ 包（project-restructure）
|
||||
|
||||
- [x] **1.1** 将 `config_manager.py` 移入 `services/`
|
||||
```powershell
|
||||
Move-Item config_manager.py services\config_manager.py
|
||||
```
|
||||
|
||||
- [x] **1.2** 将 `mcp_client.py` 移入 `services/`
|
||||
```powershell
|
||||
Move-Item mcp_client.py services\mcp_client.py
|
||||
```
|
||||
|
||||
- [x] **1.3** 将 `llm_service.py` 移入 `services/`
|
||||
```powershell
|
||||
Move-Item llm_service.py services\llm_service.py
|
||||
```
|
||||
|
||||
- [x] **1.4** 将 `sd_service.py` 移入 `services/`
|
||||
```powershell
|
||||
Move-Item sd_service.py services\sd_service.py
|
||||
```
|
||||
|
||||
- [x] **1.5** 将 `analytics_service.py` 移入 `services/`
|
||||
```powershell
|
||||
Move-Item analytics_service.py services\analytics_service.py
|
||||
```
|
||||
|
||||
- [x] **1.6** 将 `publish_queue.py` 移入 `services/`
|
||||
```powershell
|
||||
Move-Item publish_queue.py services\publish_queue.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. 更新外部文件的绝对导入（main.py、ui/）
|
||||
|
||||
- [x] **2.1** 更新 `main.py` 中的导入
|
||||
- `from config_manager import ConfigManager, OUTPUT_DIR` → `from services.config_manager import ConfigManager, OUTPUT_DIR`
|
||||
- `from llm_service import LLMService` → `from services.llm_service import LLMService`
|
||||
|
||||
- [x] **2.2** 更新 `ui/app.py` 中的导入
|
||||
- `from config_manager import ConfigManager` → `from services.config_manager import ConfigManager`
|
||||
- `from sd_service import SDService, DEFAULT_NEGATIVE, FACE_IMAGE_PATH, ...` → `from services.sd_service import SDService, DEFAULT_NEGATIVE, FACE_IMAGE_PATH, ...`
|
||||
- `from analytics_service import AnalyticsService` → `from services.analytics_service import AnalyticsService`
|
||||
- `from publish_queue import STATUS_LABELS` → `from services.publish_queue import STATUS_LABELS`
|
||||
|
||||
- [x] **2.3** 更新 `ui/tab_create.py` 中的导入（检查并替换所有根目录服务模块引用）
|
||||
|
||||
---
|
||||
|
||||
### 3. 更新 services/ 内部使用相对导入
|
||||
|
||||
- [x] **3.1** 更新 `services/scheduler.py`
|
||||
- `from config_manager import ConfigManager, OUTPUT_DIR` → `from .config_manager import ConfigManager, OUTPUT_DIR`
|
||||
- `from llm_service import LLMService` → `from .llm_service import LLMService`
|
||||
- `from sd_service import SDService` → `from .sd_service import SDService`
|
||||
- `from mcp_client import get_mcp_client` → `from .mcp_client import get_mcp_client`
|
||||
- `from analytics_service import AnalyticsService` → `from .analytics_service import AnalyticsService`
|
||||
|
||||
- [x] **3.2** 更新 `services/content.py`
|
||||
- `from config_manager import ConfigManager, OUTPUT_DIR` → `from .config_manager import ConfigManager, OUTPUT_DIR`
|
||||
- `from llm_service import LLMService` → `from .llm_service import LLMService`
|
||||
- `from sd_service import SDService, get_sd_preset` → `from .sd_service import SDService, get_sd_preset`
|
||||
- `from mcp_client import get_mcp_client` → `from .mcp_client import get_mcp_client`
|
||||
|
||||
- [x] **3.3** 更新 `services/hotspot.py`
|
||||
- `from llm_service import LLMService` → `from .llm_service import LLMService`
|
||||
- `from mcp_client import get_mcp_client` → `from .mcp_client import get_mcp_client`
|
||||
|
||||
- [x] **3.4** 更新 `services/engagement.py`
|
||||
- `from mcp_client import get_mcp_client` → `from .mcp_client import get_mcp_client`
|
||||
- `from llm_service import LLMService` → `from .llm_service import LLMService`
|
||||
|
||||
- [x] **3.5** 更新 `services/profile.py`
|
||||
- `from mcp_client import get_mcp_client` → `from .mcp_client import get_mcp_client`
|
||||
|
||||
- [x] **3.6** 更新 `services/persona.py`
|
||||
- `from config_manager import ConfigManager` → `from .config_manager import ConfigManager`
|
||||
|
||||
- [x] **3.7** 检查 `services/queue_ops.py`、`services/rate_limiter.py`、`services/autostart.py`、`services/connection.py` 有无根目录模块引用，按需更新
|
||||
|
||||
---
|
||||
|
||||
### 4. 回归验证——导入与语法检查
|
||||
|
||||
- [x] **4.1** 对所有修改文件执行 Python 语法验证
|
||||
```powershell
|
||||
python -c "
|
||||
import ast, pathlib
|
||||
files = ['main.py','ui/app.py','ui/tab_create.py',
|
||||
'services/scheduler.py','services/content.py',
|
||||
'services/hotspot.py','services/engagement.py',
|
||||
'services/profile.py','services/persona.py']
|
||||
for f in files:
|
||||
ast.parse(pathlib.Path(f).read_text(encoding='utf-8'))
|
||||
print(f'OK: {f}')
|
||||
"
|
||||
```
|
||||
|
||||
- [x] **4.2** 执行核心服务导入验证
|
||||
```powershell
|
||||
python -c "from services.config_manager import ConfigManager; print('config_manager OK')"
|
||||
python -c "from services.llm_service import LLMService; print('llm_service OK')"
|
||||
python -c "from services.sd_service import SDService; print('sd_service OK')"
|
||||
python -c "from services.mcp_client import get_mcp_client; print('mcp_client OK')"
|
||||
python -c "from services.analytics_service import AnalyticsService; print('analytics_service OK')"
|
||||
python -c "from services.publish_queue import STATUS_LABELS; print('publish_queue OK')"
|
||||
```
|
||||
|
||||
- [x] **4.3** 执行 UI 层导入验证
|
||||
```powershell
|
||||
python -c "import ui.app; print('ui.app OK')"
|
||||
```
|
||||
|
||||
- [x] **4.4** 确认根目录无游离 `.py` 业务文件
|
||||
```powershell
|
||||
Get-ChildItem -Path . -MaxDepth 1 -Filter "*.py" | Select-Object Name
|
||||
# 预期仅显示 main.py（以及测试脚本如 _test_config_save.py）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. 添加社区健康文件（oss-community-health）
|
||||
|
||||
- [x] **5.1** 创建 `.github/ISSUE_TEMPLATE/bug_report.md`（Bug 报告模板）
|
||||
包含：问题描述、复现步骤、预期行为、实际行为、环境信息（Python 版本、OS）
|
||||
|
||||
- [x] **5.2** 创建 `.github/ISSUE_TEMPLATE/feature_request.md`（功能请求模板）
|
||||
包含：背景/需求、期望解决方案、替代方案
|
||||
|
||||
- [x] **5.3** 创建 `.github/pull_request_template.md`（PR 模板）
|
||||
包含：变更类型（Bug Fix / Feature / Docs / Refactor）、变更描述、测试说明、相关 Issue
|
||||
|
||||
- [x] **5.4** 创建 `CODE_OF_CONDUCT.md`（Contributor Covenant v2.1 中文版）
|
||||
|
||||
- [x] **5.5** 创建 `SECURITY.md`（安全漏洞报告政策）
|
||||
包含：支持版本、私下报告方式（GitHub Security Advisory）、响应时间承诺
|
||||
|
||||
---
|
||||
|
||||
### 6. 添加 CI 工作流（oss-ci-workflow）
|
||||
|
||||
- [x] **6.1** 创建 `requirements-dev.txt`，包含 `ruff>=0.4.0`
|
||||
|
||||
- [x] **6.2** 创建 `.github/workflows/ci.yml`
|
||||
- trigger: `push` to `main`、`pull_request` to `main`
|
||||
- job `lint`:
|
||||
- `pip install ruff`
|
||||
- `ruff check . --select E,F,W --ignore E501`（宽松规则，忽略行长）
|
||||
- job `import-check`:
|
||||
- `pip install -r requirements.txt`
|
||||
- `python -c "from services.config_manager import ConfigManager"`
|
||||
- `python -c "from services.llm_service import LLMService"`
|
||||
- `python -c "from services.sd_service import SDService"`
|
||||
|
||||
---
|
||||
|
||||
### 7. 完善 README（oss-readme-polish）
|
||||
|
||||
- [x] **7.1** 在 README 标题下方添加徽章（Python、MIT License、CI Status）
|
||||
```markdown
|
||||
|
||||
[](LICENSE)
|
||||
[](https://github.com/<your-github-username>/autobot/actions/workflows/ci.yml)
|
||||
```
|
||||
> 将 `<your-github-username>` 替换为实际 GitHub 用户名
|
||||
|
||||
- [x] **7.2** 修正 README 中的「项目结构」章节，反映迁移后 `services/` 的完整内容
|
||||
|
||||
- [x] **7.3** 全局搜索替换 `your-username` 占位符
|
||||
```powershell
|
||||
Select-String -Path README.md -Pattern "your-username"
|
||||
# 确认所有出现位置后，手动或批量替换
|
||||
```
|
||||
|
||||
- [x] **7.4** 检查「首次使用流程」中的 Tab 名称与实际 Gradio UI 一致
|
||||
|
||||
---
|
||||
|
||||
### 8. 最终验证
|
||||
|
||||
- [x] **8.1** 执行 `git status` 确认所有变更文件符合预期
|
||||
- [x] **8.2** 执行 `git diff --stat` 确认无意外文件被修改
|
||||
- [x] **8.3** 启动应用：`python main.py` 确认 Gradio UI 正常加载，无启动错误
|
||||
Reference in New Issue
Block a user