# Dev Flow

> Songloft 的分阶段开发流程助手。用于处理 GitHub Issue、Bug、功能需求和优化：收集信息、分析根因、设计方案、实施修改、验证、自审、生成提交信息，并在每个阶段等待用户确认；只有得到明确确认后才提交、推送或操作 Issue。

- Skill: `songloft-org/dev-flow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add songloft-org/dev-flow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/songloft-org/dev-flow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: songloft-org (https://skillmd.com/u/songloft-org)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/songloft-org/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 完成后，父仓库只在确认后更新子模块指针。