SuperAPI AI 工具集

blocking-io-guard

编程与开发

查看项目

更新于 10-15 17:30

技能介绍

用途:在 DeerFlow 后端异步代码变更中,识别可能阻塞 asyncio 事件循环的调用,并通过运行时锚点测试让阻塞 IO CI 门禁能看到这些代码。动态检测器只能捕获测试实际执行到的路径,该技能用于弥补这一缺口。

适用场景:一是自有 diff(Mode A,PR 前),改动涉及 backend/app/、backend/packages/harness/deerflow/ 或 backend/scripts/ 下可能运行于异步事件循环的 Python 代码;二是在现有代码库做维护分诊(Mode B)。

主要步骤:Step 0 确定范围,Mode A 执行 uv run --project backend python scripts/scan_changed_blocking_io.py --base origin/main(需先提交,未提交行不会被选中),Mode B 执行 make detect-blocking-io,结果写入 .deer-flow/blocking-io-findings.json;Step 1 判定候选属于 GUARD、FIX+ANCHOR 还是 NO-ACTION,跨文件可达性需另查;Step 2 仅 FIX+ANCHOR 需先修改生产代码并重新扫描确认候选消失,按 (path, function, symbol) 匹配而非行号;Step 3 检查 backend/tests/blocking_io/ 中已有锚点;Step 4 依据 templates/anchor.template.py 生成或扩展锚点,驱动具体分支,不得用测试专用 asyncio.to_thread 绕过;Step 5 强制验证有效性,临时恢复阻塞后 cd backend && make test-blocking-io 必须变红,恢复修复后必须变绿,持续为绿说明缺少 Blockbuster 规则;Step 6 提交锚点与改动,PR 中说明候选、处置、重扫结果与红到绿证据。书写锚点前需阅读 references/good-anchor-rules.md。

限制:扫描器的异步可达性仅限同文件,新增的跨文件 async 调用可能不可见,需手动检查;优先级是确定性审查排序,不代表已确认缺陷;资料未提供具体价格、平台支持范围与运行环境要求。