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 正文、评论、标签和状态： ```bash 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：复现步骤、平台/版本、期望与实际行为、日志或截图、首次出现版本。 - 需求：使用场景、期望行为、涉及端、边界条件、兼容性或性能约束。 - 描述含糊时，先指出已知事实和未知项；不要在需求尚未清楚时开始改代码。 输出一份简短的结构化摘要： ```text 类型：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`，必要时搜索所有调用点。至少覆盖： | 检查项 | 关注点 | | --- | --- | | 逻辑正确性 | 空值、零值、负值、错误分支、边界条件 | | 调用链兼容 | 函数签名、API 响应、所有调用点和默认行为 | | 状态与并发 | 初始化、重置、销毁、事务、定时器和竞态 | | 数据库 | 迁移顺序、内置数据、事务边界、`ErrNotFound` 语义 | | UI 副作用 | 渲染、导航、事件绑定、生命周期、平台差异 | | 性能与资源 | 高频路径、I/O、子进程、连接和 goroutine 回收 | | 死代码与类型 | 未使用变量、不可达分支、字符串/数字比较、空值处理 | | 回归与测试 | 相关旧功能、错误路径和新增测试是否覆盖 | 发现问题时立即修复并重新执行受影响的格式化和验证。输出审查结果： ```text 代码审查结果 - 逻辑正确性：通过 / 已修复问题 / 未通过 - 调用链兼容：通过 / 已修复问题 / 未通过 - 状态、数据与并发：通过 / 已修复问题 / 未通过 - UI、性能与资源：通过 / 已修复问题 / 未通过 - 回归与测试：通过 / 有剩余风险 结论：无新增问题 / 已修复 <数量> 个问题 / 阻塞原因 ``` 审查未通过或仍有未解释的高风险时，不进入提交阶段。否则暂停，等待用户确认审查通过。 ## 阶段五：生成提交信息 根据最终 diff 生成一条 Conventional Commits 信息： ```text <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 本次确认的文件： ```bash git add <confirmed-files> git diff --cached --check git diff --cached --stat ``` 2. 展示 staged 文件和摘要；若出现无关文件，取消其 staging 并重新确认。 3. 仅在用户确认提交后执行： ```bash git commit -m '<confirmed-message>' ``` 4. 报告 commit SHA 和结果，单独询问是否推送。只有得到明确确认才执行： ```bash git push origin main ``` 5. 有 GitHub Issue 时，先草拟评论并等待确认；确认后再执行 `gh issue comment`。关闭 Issue 也必须单独确认。 提交信息模板： ```markdown 已修复/已实现。 提交：`<short-sha>` `<type>(<scope>): <description>` <根因、行为变化、用户侧操作或 API 变化> ``` ## 阶段控制 - 用户说“继续”“确认”“通过”时，只推进到下一个尚未确认的阶段。 - 用户提出新信息或要求修改时，更新当前阶段的摘要/方案，不要丢弃已完成的证据。 - 用户拒绝方案时，回到阶段二；用户拒绝提交时，保留代码和审查结果，不执行 commit。 - 任何阶段遇到阻塞，报告：已完成的调查、具体阻塞、尝试过的命令和需要用户提供的最小信息。 - 多仓库任务按仓库分别列出改动和验证；子模块 commit 完成后，父仓库只在确认后更新子模块指针。