VERIFICATION_CHECKLIST.md

CloudMusic 项目改进 - 最终验证清单

使用方法: 孙子代理完成后，逐项检查并打勾

1. 孙子代理 1：TUI 框架（Textual）

文件检查

• cloudmusic/tui/app.py 存在且非空
• cloudmusic/tui/themes.py 包含至少 4 个主题
• cloudmusic/tui/widgets.py 包含自定义组件
• cloudmusic/tui/sidebar.py 左侧面板组件
• cloudmusic/tui/tracklist.py 右侧歌曲列表组件
• cloudmusic/tui/player_bar.py 底部播放控制栏
• cloudmusic/tui/lyrics_panel.py 歌词显示面板

功能检查

• TUI 可以启动（python -m cloudmusic.tui.app）
• 分屏布局正确显示
• 主题可以切换（按 T 键）
• 进度条动画流畅
• Unicode 图标正确显示
• 至少 4 个主题可用

测试检查

• tests/test_tui.py 测试通过
• 测试覆盖主题切换
• 测试覆盖布局渲染

2. 孙子代理 2：功能完善

文件检查

• cloudmusic/downloader.py 包含 download_songs_batch
• cloudmusic/player_controller.py 包含 PlayerController
• cloudmusic/api.py 包含 resolve_play_url（多音质）
• cloudmusic/api.py 包含 parse_lrc
• cloudmusic/config.py 包含 Config 类

功能检查

• 并发下载可用（测试下载 5 首歌）
• 播放控制可用：
  • 暂停/恢复
  • Seek（跳转）
  • 音量控制
  • 速度控制
• 多音质选择可用（至少 3 种音质）
• 配置文件加载/保存可用
• 歌词解析和显示可用

测试检查

• tests/test_downloader.py 测试通过
• tests/test_player.py 测试通过
• tests/test_api.py 测试通过
• tests/test_config.py 测试通过

3. 孙子代理 3：用户交互

文件检查

• cloudmusic/tui/keybindings.py 包含 KeyBindings
• cloudmusic/tui/search.py 包含 SearchInput
• cloudmusic/tui/notifications.py 包含 Notification
• cloudmusic/tui/dialogs.py 包含 ConfirmDialog

功能检查

• 快捷键系统可用（至少 20 个快捷键）
• 搜索自动补全可用（显示建议）
• 鼠标点击可用（选中/播放）
• 鼠标滚动可用
• 通知组件可用（4 种类型：success/error/warning/info）
• 确认对话框可用

测试检查

• tests/test_tui.py 包含快捷键测试
• tests/test_tui.py 包含通知测试
• tests/test_tui.py 包含搜索测试

4. 代码质量检查

格式化

• 代码已格式化（black .）
• 导入已排序（isort .）

类型检查

• mypy 检查通过（mypy cloudmusic）
• 所有函数有类型注解

Lint 检查

• flake8 检查通过（flake8 cloudmusic）

测试覆盖率

• pytest 测试通过（pytest）
• 覆盖率 > 80%（pytest --cov）

5. 集成测试

基本流程

• TUI 可以启动
• 登录流程可用（QR/Auto-Cookie/Manual）
• 搜索功能可用
• 播放功能可用
• 下载功能可用

兼容性

• 旧 cli/musicctl.py 仍然可用
• 新旧接口兼容

6. 文档检查

• README.md 已更新（替换为 README_NEW.md）
• CHANGELOG.md 已更新
• 所有公共函数有 docstring
• 类型注解完整

7. 最终验证

安装测试

• 可以安装（pip install -e .）
• 可以运行（cloudmusic 或 python -m cloudmusic.tui.app）
• 可以运行旧 CLI（musicctl 或 python cli/musicctl.py）

性能检查

• TUI 响应流畅（无卡顿）
• 并发下载不阻塞 UI
• 内存使用合理（< 200MB）

用户体验

• 快捷键直观易记
• 主题美观
• 错误提示清晰
• 操作流畅

---

全部完成 后，通知主代理（agent:main:main）