Dev Flow

Songloft Dev Flow

按阶段推进 Songloft 的开发任务。维护当前阶段和待确认事项；用户确认后才进入下一阶段。用户提出修正时，留在当前阶段重新整理，不要自行跳过确认点。

触发与范围

• 用户明确说“使用 dev-flow”、$dev-flow，或请求按项目开发流程处理 Issue、Bug、需求、提交或发布时使用本 skill。
• 输入包含 GitHub Issue URL 时，从 Issue 开始；否则按自由描述收集信息。
• 先确认实际工作的仓库和目录。父仓库是 songloft-org/songloft；前端、插件工具链和各插件可能是独立仓库或子模块。
• 遵守当前目录及其 AGENTS.md。若规则冲突，以更具体、更近的 AGENTS.md 为准。

不可跳过的安全规则

• 开始修改前运行 git status --short，识别并保留用户已有改动；禁止 reset、checkout 或覆盖无关改动。
• 只在已确认的 scope 内读写文件。发现需要扩大 scope 时，先说明原因并重新确认。
• 读操作可以自动执行；提交、推送、发布 Issue 评论、关闭 Issue 等不可逆操作必须分别获得明确确认。
• 不要把附件或代码上传到外部服务。Issue 附件仅下载到明确的 /tmp/issue-<number>-* 临时目录，分析后清理。
• 不能验证时如实报告原因和剩余风险，不要用“应该可以”代替验证。

阶段一：收集信息

有 Issue URL

1. 从 URL 提取 owner、repo 和 number。

2. 获取 Issue 正文、评论、标签和状态：

   gh issue view <number> --repo <owner>/<repo> \
     --json title,body,comments,labels,state,url
   

3. 按需分析正文中引用的附件。日志、压缩包、截图、崩溃报告和 JSON 都属于证据；下载后使用 unzip、rg、file 或图片查看工具检查。

4. 若 Issue 指向 CI 失败，使用 gh run view <run-id> --repo <owner>/<repo> 和 --log-failed 获取失败日志。

5. 判断类型：Bug、功能需求或优化。

自由描述

先用 rg 和相关文档建立上下文，再只询问缺失且会影响实现的关键信息。

• Bug：复现步骤、平台/版本、期望与实际行为、日志或截图、首次出现版本。
• 需求：使用场景、期望行为、涉及端、边界条件、兼容性或性能约束。
• 描述含糊时，先指出已知事实和未知项；不要在需求尚未清楚时开始改代码。

输出一份简短的结构化摘要：

类型：Bug / 功能 / 优化
问题或目标：
复现步骤或典型用例：
影响范围：
已知约束：
待确认事项：

然后暂停并询问：信息是否准确、完整，是否进入方案设计。

阶段二：分析与方案设计

Bug

• 根据描述、日志和代码调用链定位根因；区分已证实事实、推断和待验证假设。
• 检查 AGENTS.md 的业务踩坑、数据库、API、前端和平台规则。
• 说明为何现有行为会发生、修复点、回归风险和验证方法。

功能或优化

输出可执行方案，至少包含：

• 期望行为和不在 scope 内的内容
• 涉及的仓库、模块和文件
• 后端接口、响应格式、Swagger 注释和数据库迁移（如适用）
• 前端状态、交互和平台差异（如适用）
• 测试策略、兼容性、性能和回滚风险
• 需要用户决定的选项

优先复用现有架构和接口。数据库改动遵守 goose/sqlc/squirrel/Repository/UnitOfWork 规范；业务配置遵守 /settings/* 与模块配置端点规范；新增或修改路由 handler 必须同步 Swagger 产物。

展示方案后暂停，等待用户确认 scope 和实现方案。未确认时只进行只读调查和方案讨论。

阶段三：实施与验证

收到方案确认后：

1. 再次检查 git status --short，记录本次改动前的工作树状态。
2. 按确认的文件和模块实施，保持改动最小；不要顺手重构无关代码。
3. 按仓库规则执行必要的生成和格式化：
   • Go：执行 gofmt -w .；必要时运行 go vet。
   • Dart：在 clients/player/ 执行 dart format lib/ test/。
   • 修改 database/queries/*.sql：执行 make sqlc，检查生成文件。
   • 修改 handler 的 swag 注释或新增 handler：执行 make swagger，检查 docs/swagger.json、docs/swagger.yaml、docs/docs.go。
   • 修改文档：同步对应的中英文版本；自动生成页改源文件，不直接改生成物。
4. 根据变更范围验证：
   • 后端改动：至少运行相关测试；涉及公共后端行为时运行 make check。
   • Flutter 改动：运行 flutter analyze 和相关 flutter test；涉及共享行为时扩大测试范围。
   • UI 改动且用户要求界面验证：按 AGENTS.md 的 Docker 无头浏览器流程实际操作并截图。
   • API、配置或后台动作：除截图外，使用 HTTP、数据库或进程状态等后端可观测结果验证。
5. 检查 git diff --check，并检查本次改动文件是否出现 UTF-8 替换字符 �。

如果命令失败，先判断是代码失败、环境缺失还是权限/网络问题；能修复就修复并重跑，不能修复就保留失败输出和影响范围。

输出：改动文件清单、生成物、验证命令及结果、未验证项目和剩余风险。然后暂停，等待用户确认改动结果。

阶段四：提交前自审

用户确认实施结果后，逐文件检查 git diff，必要时搜索所有调用点。至少覆盖：

发现问题时立即修复并重新执行受影响的格式化和验证。输出审查结果：

代码审查结果
- 逻辑正确性：通过 / 已修复问题 / 未通过
- 调用链兼容：通过 / 已修复问题 / 未通过
- 状态、数据与并发：通过 / 已修复问题 / 未通过
- UI、性能与资源：通过 / 已修复问题 / 未通过
- 回归与测试：通过 / 有剩余风险
结论：无新增问题 / 已修复 <数量> 个问题 / 阻塞原因

审查未通过或仍有未解释的高风险时，不进入提交阶段。否则暂停，等待用户确认审查通过。

阶段五：生成提交信息

根据最终 diff 生成一条 Conventional Commits 信息：

<type>(<scope>): <中文描述>

<用中文说明为什么改，必要时说明重要取舍>

Fixes <issue-ref>   # Bug 完整修复
Closes <issue-ref>  # 功能完成
Ref <issue-ref>     # 部分完成或仅相关

规则：

• type 使用 feat、fix、refactor、docs、chore、perf 或 test。
• scope 使用实际业务模块，如 player、scan、hls、jsplugin、cache、tag。
• 提交说明和正文尽量使用中文；禁止 Co-Authored-By。
• 当前仓库 issue 可写 #123；跨仓库 issue 必须写完整的 owner/repo#123。
• 子模块仓库提交引用父仓库 issue 时，必须写 songloft-org/songloft#123。

展示提交信息后暂停，等待用户确认或修改。

阶段六：提交、推送和 Issue 收尾

收到提交信息确认后：

1. 只 stage 本次确认的文件：

   git add <confirmed-files>
   git diff --cached --check
   git diff --cached --stat
   

2. 展示 staged 文件和摘要；若出现无关文件，取消其 staging 并重新确认。

3. 仅在用户确认提交后执行：

   git commit -m '<confirmed-message>'
   

4. 报告 commit SHA 和结果，单独询问是否推送。只有得到明确确认才执行：

   git push origin main
   

5. 有 GitHub Issue 时，先草拟评论并等待确认；确认后再执行 gh issue comment。关闭 Issue 也必须单独确认。

提交信息模板：

已修复/已实现。

提交：`<short-sha>` `<type>(<scope>): <description>`

<根因、行为变化、用户侧操作或 API 变化>

阶段控制

• 用户说“继续”“确认”“通过”时，只推进到下一个尚未确认的阶段。
• 用户提出新信息或要求修改时，更新当前阶段的摘要/方案，不要丢弃已完成的证据。
• 用户拒绝方案时，回到阶段二；用户拒绝提交时，保留代码和审查结果，不执行 commit。
• 任何阶段遇到阻塞，报告：已完成的调查、具体阻塞、尝试过的命令和需要用户提供的最小信息。
• 多仓库任务按仓库分别列出改动和验证；子模块 commit 完成后，父仓库只在确认后更新子模块指针。