用途:检测代码库中的循环导入依赖,并在机械上安全的情况下自动打破循环;无法安全自动处理的循环只做报告,交由人工架构决策。
主要能力:
- 语言识别:依据 package.json(TS/JS)、pyproject.toml(Python)、go.mod(Go)、Cargo.toml(Rust)判断。Go 与 Rust 在编译期就禁止循环,因此实际工作以 TS/Python 为主。
- 检测:TS/JS 用 madge(大仓库可用 skott),Python 用 pycycle 或 import-linter 兜底,Go 用 go build 确认,Rust 用 cargo build 与 cargo-modules 查看模块图。
- 评估:按置信度分级。HIGH(可自动修复,循环恰好 2 个模块,且一个方向只是常量、类型或不超过 20 行的纯工具函数);MEDIUM(3 个及以上模块,或双向依赖较重,仅报告);LOW(结构性循环,如 ORM 双向关系、父子组件引用,可能是有意为之)。
- 自动修复:仅对 HIGH 级别做叶节点抽取,即把常量/类型/工具函数移到新文件并更新双方导入,然后重新检测确认循环消失。
- 报告:写入 .claude/cleanup-reports/cleanup-cycles-{YYYY-MM-DD}.md,含循环数量、置信度统计、各循环路径与处理方案及架构评述。
使用方式:先做预检(Git 工作区脏则拒绝自动应用、确认报告目录、优先复用仓库已有的 cycle:check 脚本),再检测、评估、仅对 HIGH 应用,最后重新运行检测与类型检查/测试/lint 验证;若验证失败或出现新循环则 git revert HEAD 并升级为 MEDIUM。
限制:禁止对 3 个以上模块的循环自动应用;不得用 barrel 文件(index.ts 再导出)作为解决方案;不触碰框架约定造成的循环;不把类型集中到 types.ts 大文件;不得通过工具配置压制警告。具体安装与运行命令、工具版本及收费信息资料未完整提供。