| name | funasr-task-manager-reset-test-db |
| description | Reset the funasr-task-manager local database and storage to a clean state. Use when: preparing for tests (pytest, E2E, benchmark), user asks to clear tasks/data/uploads, wipe the database, rebuild after corruption, free disk space, or reset to initial state. Trigger on: "清空数据库", "重置数据", "清空任务", "只保留服务器", "其他都清空", "彻底清理", "释放空间", "reset db", "clean state", "wipe data".
|
适配项目版本：V0.4.28-Build0476-20260518
Reset ASR DB Before Test
在这个仓库里，需要在测试前把后端 SQLite 数据库恢复到干净状态时使用本技能。
本技能显式针对 runtime/storage/ 工作，而不是历史上放在 3-dev/src/backend/data/ 或仓库根目录 data/ 的旧目录。
这个技能封装的是一个可执行脚本，而不是已经注册好的聊天斜杠命令。实际脚本位于 scripts/ 目录。手动执行时，直接运行下面的命令：
python 6-skills/funasr-task-manager-reset-test-db/scripts/reset_db.py
在 macOS 或 Linux 上如果默认解释器是 Python 3，请优先使用：
python3 6-skills/funasr-task-manager-reset-test-db/scripts/reset_db.py
⚠️ 意图判断规则（必须先读）
核心原则：用户表达中出现"都"、"所有"、"全部"、"其他都清空"、"只保留 X"等全量清理语义时，必须加 --clear-uploads。uploads 里的文件属于"数据"的一部分——用户说"清空数据"时期望 uploads 也被清理。
| 用户说法（示例） | 命令 | 解释 |
|---|
| "重置测试数据库" / "清空任务" | 基础重置 | 仅清任务表和结果，保留 uploads |
| "只保留服务器信息，其他都清空" | --clear-uploads --force | "其他都清空"＝含 uploads |
| "清空所有数据" / "彻底清理" / "全部清空" | --clear-uploads --force | "所有/全部"＝含 uploads |
| "释放磁盘空间" / "清理占用" | --clear-uploads --force | 释放空间必须含 uploads |
| "回到初始状态" / "全部删掉重来" | --clear-uploads --reset-servers --force | 连服务器配置也不保留 |
判断口诀：用户只提"任务"或"数据库" → 不清 uploads；用户说"数据/都/所有/全部/其他" → 清 uploads。
适用场景
- 本地调试前，需要清空任务、结果和临时文件
- 跑 pytest、CLI 回归、浏览器 E2E 前，需要可重复的数据库初始状态
- 上一次测试中断，导致
runtime/storage/asr_tasks.db 缺失或状态不可信
- 上一次测试异常中断导致数据库损坏，需要重建
- 需要保留已有 ASR 服务器节点配置，但重新生成任务数据库
- 需要彻底重置服务器节点配置并重新插入默认测试节点
默认行为
默认执行：
- 检测数据库占用：通过
lsof（Unix）和 SQLite 排他锁检测数据库是否被其他进程（如运行中的后端）占用。如果检测到占用，脚本会拒绝执行并报告占用进程的 PID
- 如果旧数据库存在且未损坏，导出已有服务器配置以便重建后恢复
- 如果旧数据库存在，则先备份到
runtime/storage/backups/
- 清空
results/ 和 temp/
- 删除数据库及其附属文件（
-wal、-shm、-journal）并重建
- 运行 Alembic 迁移到最新版本
- 默认恢复已有服务器配置
- 默认不删除
uploads/——但如果用户意图是"全部清空/其他都清空/清空数据"，必须加 --clear-uploads（见上方意图判断规则）
- 默认不插入新的测试服务器，除非显式指定
--reset-servers
- 执行结束后自动做重置复核：检查
results/、temp/、以及启用 --clear-uploads 时的 uploads/ 是否真正清空，同时检查任务相关业务表是否归零、服务器数量是否符合预期；任一项失败都会直接返回 failed
如果数据库文件原本不存在，脚本会直接创建一份新的空库并完成迁移，不会因为"找不到旧库"而失败。
损坏数据库处理
如果旧数据库文件存在但已损坏（sqlite3.DatabaseError），脚本不会因为"无法导出服务器配置"而退出。它会跳过服务器配置保留，在输出中标注 servers_preservation_skipped，然后继续执行备份→删库→迁移的完整流程。用户无需额外传 --reset-servers 就能从坏库状态恢复。
Dry Run 评估
如果只想评估当前 runtime storage 的状态，而不真的执行清理，使用：
python 6-skills/funasr-task-manager-reset-test-db/scripts/reset_db.py --dry-run
这个模式会输出：
- 当前服务器配置摘要
- SQLite 数据库相关文件数量和大小
results/、temp/、uploads/ 目录的文件数量和大小- 当前任务总数、状态分布、最近任务摘要
- 按当前重置逻辑预计可释放的空间
如果数据库已损坏，dry-run 不会崩溃。它会在输出中设置 database_corrupt: true，将服务器和任务数据降级为零值，并在 summary 中提示用户执行不带 --dry-run 的重置来重建数据库。
如果希望把 uploads/ 也纳入估算，可以组合：
python 6-skills/funasr-task-manager-reset-test-db/scripts/reset_db.py --dry-run --clear-uploads
注意：--dry-run 只读取和评估，不会触发备份、删库、迁移或目录清理。
如果仓库里还残留旧的 3-dev/src/backend/data/ 或仓库根目录 data/，--dry-run 不会扫描它们；该脚本只处理推荐目录 runtime/storage/。
常用命令
基础重置：
python 6-skills/funasr-task-manager-reset-test-db/scripts/reset_db.py
重置服务器配置并插入 3 台默认测试节点：
python 6-skills/funasr-task-manager-reset-test-db/scripts/reset_db.py --reset-servers
删除上传文件并跳过确认：
python 6-skills/funasr-task-manager-reset-test-db/scripts/reset_db.py --clear-uploads --force
跳过备份以加快执行：
python 6-skills/funasr-task-manager-reset-test-db/scripts/reset_db.py --no-backup
只做容量和状态评估：
python 6-skills/funasr-task-manager-reset-test-db/scripts/reset_db.py --dry-run
参数规则
--no-backup: 仅跳过数据库备份，不影响重建和清理--dry-run: 只做评估，不执行任何清理或迁移--reset-servers: 不保留旧服务器配置，改为走默认测试服务器种子数据--skip-seed-servers: 只在 --reset-servers 时有效，表示重置后不插入默认测试节点--clear-uploads: 删除上传目录中的文件。未配合 --force 时会二次确认--force: 跳过危险操作确认，适合 CI 或非交互环境
执行结果
脚本输出 JSON，字段示例：
正常重置（保留服务器配置）：
{
"status": "success",
"message": "测试数据库重置完成，已准备好干净测试环境",
"data": {
"backup_path": "/abs/path/to/asr_tasks_test_backup_20260401_123045.db",
"servers_preserved": 2,
"database_recreated": true,
"seed_data_inserted": false,
"post_reset_verified": true
}
}
数据库损坏时的重置：
{
"status": "success",
"message": "测试数据库重置完成，已准备好干净测试环境",
"data": {
"servers_preservation_skipped": "数据库损坏，无法导出服务器配置，将创建空库",
"backup_path": "/abs/path/to/asr_tasks_test_backup_20260401_123045.db",
"database_recreated": true,
"seed_data_inserted": false,
"post_reset_verified": true
}
}
重置后复核失败：
{
"status": "failed",
"message": "重置后复核失败：仍有目录或数据未清空，请检查 details",
"data": {
"post_reset_verification": {
"ok": false,
"problems": [
"uploads 目录未清空: 3 个文件, 1 个子目录",
"数据表 tasks 仍有 2 条记录"
]
}
}
}
数据库被占用时的拒绝：
{
"status": "failed",
"message": "无法重置: 数据库文件正被其他进程占用 (PID: 12345)，请先停止后端服务再执行重置",
"data": {}
}
dry-run 输出会额外包含 servers、database_files、tasks、results、temp、uploads、estimated_savings 和 summary。如果数据库损坏，还会包含 database_corrupt: true。
安全约束
- 这是测试辅助技能，不要用于生产数据库
- 如果数据库正被后端进程占用，脚本会拒绝执行并报告占用进程的 PID，防止产生分叉状态
--clear-uploads 会删除上传文件，默认要求确认- 只有显式指定
--reset-servers 才会清空旧服务器配置
- 删除数据库时会一并清理
-wal、-shm、-journal 附属文件，防止残留锁文件干扰新数据库
相关文件
scripts/reset_db.py: 实际执行脚本
