SuperAPI AI 工具集

refac-module-to-subpackage

编程与开发

查看项目

更新于 10-15 20:31

技能介绍

用途:把大型单体 Python 模块(.py 文件)转换为由多个子模块组成的子包,属于纯机械式重组,不改变逻辑、不修复已有问题、不做任何改进。核心原则是行为保持:代码逐字复制,不重命名函数或改签名,不增删功能,目标是只移动代码的干净 diff,使审阅者可确认旧文件每一行都出现在恰好一个新文件中。

主要能力与流程分七个阶段:1)结构盘点,用 grep 扫描节标题与定义(如 grep -n "^# ==|^class |^def " <file>),记录节注释块、类与函数行范围、导入、顶层定义总数、模块级辅助与常量。2)目标发现,检查目标目录是否已存在子包、是否有 init.py、现有文件模式与重叠。3)分组设计,按作者节标题、功能内聚、导入内聚、大小平衡(避免小于约 20 行或超过约 500 行)启发式,产出映射表供用户确认;文件名应匹配所分组概念。4)共享代码放置:单一消费者放入其文件,两个消费者放入主要消费者文件,三个以上再考虑 _helpers.py 或 conftest.py。5)执行:创建新文件、写简短模块 docstring、只加所需导入、逐字复制、保留节注释;合并到已有文件时按行为而非名称判重并追加非重复代码;用 uv run ruff check --fix <new_files> 修复导入排序;最后 rm <original_monolith.py>。6)验证:用 grep 统计前后定义数(after 应≥before),检查悬空引用,运行测试、linter 与类型检查。7)PR 流程:审阅指出旧有问题时标记为 pre-existing,使用 erk exec get-pr-review-comments 和 erk exec resolve-review-thread --thread-id <PRRT_id> --comment "..." 回复并解决,禁止用裸 gh api 操作;提交信息格式为 Split <module> into <subpackage> subpackage (#<PR>),PR 描述应含映射表与前后定义数。

适用场景:拆分大型测试文件或工具模块等单体 Python 文件。限制:仅限行为保持的重组;具体项目命令、环境与执行细节以资料为准,未提供的收费、平台、效果等信息暂未提供。