migrate-to-codehub
从其他项目提取优秀架构设计或功能实现,剥离业务耦合后迁移到 PythonCodeHub。触发:"迁移到 CodeHub"、"提取到 PythonCodeHub"、"重构后加入 CodeHub"、"migrate to codehub"。
SKILL.mdskills/migrate-to-codehub/SKILL.md
GitHub目的
本技能指导 AI 完成代码迁移过程:从现有项目中识别有价值的架构设计或功能实现,剥离业务耦合,将其转化为可复用的 PythonCodeHub 模块。迁移完成后,输出的代码应具备清晰的接口、良好的可复用性,并能通过核心行为验证。
功能
- 价值评估:分析源代码的设计质量和复用潜力,判断是否值得迁移
- 查重归类:在 PythonCodeHub 中搜索近似实现,决定扩展还是新增模块
- 解耦分析:识别并处理业务耦合、外部依赖、环境假设等通用耦合
- 方案设计:生成迁移方案,包括目标、路径、接口设计、文件规划等
- 重构实现:保留核心设计骨架,删除业务分支,抽象外部依赖
- 验证输出:确保迁移后的代码通过 lint、测试、接口验证
使用场景
- 发现了值得沉淀的架构设计(如分布式锁、任务调度、缓存机制)
- 发现了值得复用的功能实现(如装饰器、工具函数、协议处理)
- 发现了不能直接照搬,但其设计思路值得重构保留的代码
- 需要将其他项目的优秀设计迁移到 PythonCodeHub 以供复用
- 用户提到“迁移到 CodeHub”“提取到 PythonCodeHub”“把这个设计迁移过来”“重构后加入 CodeHub”“migrate to codehub”
迁移目标
将其他项目中的优秀设计或实现,重构为可复用、低耦合、易参考的 PythonCodeHub 代码。
最终产物应满足:
- 可被其他项目复制后小幅调整使用
- 不携带业务耦合、敏感信息或私有实现痕迹
- 保留原设计的关键价值,而不是仅保留表面代码
何时使用
仅在以下情况使用本 skill:
- 发现了值得沉淀的架构设计
- 发现了值得复用的功能实现
- 发现了不能直接照搬,但其设计思路值得重构保留的代码
若只是普通业务逻辑搬运、一次性脚本、强依赖上下文的内部实现,则不使用。
执行原则
- 先判断值不值得迁移,再开始写代码
- 优先扩展现有模块,避免重复建设
- 优先保留设计思路,不强求保留原始写法
- 优先标准库和轻依赖,避免把业务环境搬进仓库
- 结构与复杂度匹配,避免过度拆分
- 至少验证核心行为,不只生成目录和 README
执行流程
阶段 1:识别与判定
先在 PythonCodeHub 中搜索近似实现,再决定是扩展还是新增。
必须同时满足以下条件,才值得迁移:
- 通用性:去掉业务逻辑后,核心设计仍成立
- 复用价值:至少存在一个明确的跨项目使用场景
- 独立性:可以脱离原业务模块独立表达
- 接口稳定性:能够抽象出清晰的公开类、函数或 Protocol
- 代码质量:原实现确实有值得保留的设计优势
若不满足,直接向用户说明原因并停止。
迁移粒度判断
根据源代码复杂度决定迁移批次:
- 单一职责能力(如一个装饰器、一个工具函数):一次性迁移
- 中等复杂度(如一个完整的锁机制):一次迁移,但可分文件实现
- 大型系统(如完整的任务调度框架):拆分为独立子能力,分批迁移,每批独立可用
拆分原则:每批迁移产物必须独立可运行、独立可测试,不依赖后续批次才能工作。
阶段 2:查重与归类
先判断目标能力是否已经在仓库中存在:
- 若已有相近模块,优先补充现有模块
- 若只是能力增强,优先新增文件或子能力,不要复制一套相似结构
- 仅当现有目录确实无法容纳时,才新增模块目录
做出归类判断时,优先参考现有 ab_* 目录的能力边界,而不是按原项目目录生搬硬套。
阶段 3:解耦分析
逐项识别并处理常见的通用耦合:
| 耦合类型 | 处理方式 |
|---|---|
| 领域对象或持久化模型耦合 | 改为 Protocol、ABC、DTO 或通用数据结构 |
| 配置来源耦合 | 提取为构造参数、配置对象或函数参数 |
| 外部系统或基础设施耦合 | 改为接口抽象、适配器或标准库实现 |
| 运行环境耦合 | 删除隐式假设,改为显式注入运行参数 |
| 观测能力耦合 | 删除强绑定实现,替换为 logging 或可选扩展点 |
| 异常体系耦合 | 改为通用异常或通用自定义异常 |
| 命名约定与标识规则耦合 | 删除硬编码,改为参数化或示例值 |
| 私有实现细节耦合 | 只保留思路,重写为公共抽象 |
| 并发/线程模型耦合 | 抽象为可选的执行器接口,支持同步/异步两种模式 |
| Python 版本特性耦合 | 标注最低版本要求,避免使用过新的语法糖 |
额外检查:
- 不保留组织内部标识、私有地址、环境细节或敏感常量
- 不迁移依赖特定部署方式、特定组织规则或封闭生态的实现细节
- 若必须保留第三方依赖,优先复用仓库已有依赖,并说明必要性
- 若第三方依赖只是为了省事,优先改为标准库或接口抽象
依赖冲突处理:
- 优先适配仓库已有依赖版本
- 若必须升级依赖,需评估对其他模块的影响
- 若冲突不可调和,考虑将依赖改为可选(
extras_require)
阶段 4:先出方案,等待确认
在开始写代码前,必须先给用户一个简要方案,并等待确认。
方案至少包含:
- 迁移目标:一句话说明本次沉淀什么能力
- 归属路径:落到哪个目录或文件
- 复用判断:扩展现有模块还是新增模块
- 解耦策略:要剥离哪些业务耦合
- 接口设计:核心公开类、函数、Protocol 的名称与关键参数
- 文件规划:预计新增或修改哪些文件
- 验证方式:计划如何验证核心行为
参考格式:
📋 迁移设计方案
━━━━━━━━━━━━━━━━
目标:迁移分布式锁的看门狗续期机制
路径:ab_lock/distributed_lock/watchdog.py
复用:扩展现有 distributed_lock 目录,避免新增重复锁模块
解耦:
- BizRedisClient -> Protocol(RedisClient)
- biz:order: 前缀 -> 参数 key_prefix
- OrderLockError -> LockError
接口:
- Watchdog(interval: float, client: RedisClient)
- Watchdog.start(lock_key: str) -> None
- Watchdog.stop() -> None
文件:
- watchdog.py
- protocol.py
验证:
- pytest 覆盖续期启动、停止、异常路径
未得到用户确认前,不进入实现阶段。
阶段 5:重构实现
确认后,再开始重构代码。重构时遵循以下要求:
- 保留核心设计骨架,删除业务分支
- 通过
typing.Protocol或abc.ABC抽象外部依赖 - 将硬编码值提取为参数或配置对象
- 使用完整类型注解描述公开接口
- 注释使用中文,且保持精简
- 提供至少一个最小可运行示例
- 简单能力优先单文件,复杂能力再拆目录
重构底线:
- 不能因为“通用化”而把原本优秀的设计削平
- 不能只剩语法改写,而丢失原方案的关键优势
阶段 6:适配仓库结构
放入 PythonCodeHub 时,遵循以下规则:
- 优先归入已有
ab_*模块 - 简单功能优先单文件
- 仅在存在多个明确职责时再拆成子目录
__init__.py只导出公开接口,不暴露内部细节README.md只写对使用者真正有价值的内容
推荐结构:
ab_<category>/
├── __init__.py
├── <feature>.py
├── <feature>/
│ ├── __init__.py
│ ├── core.py
│ ├── protocol.py
│ └── README.md
└── README.md
阶段 7:验证
完成后,至少完成以下检查:
-
ruff check通过 - 有最小测试或关键行为测试,优先
pytest - 公开接口都有 type hints
- 无业务耦合残留
- 无敏感信息残留
- 最小示例可读、可复制、可落地
-
__init__.py导出正确 - 若新增第三方依赖,已说明必要性
- 异步/同步兼容性已验证(若涉及)
- 边界条件(空输入、超时、并发)已覆盖
- 与仓库已有模块无命名冲突
如无测试验证或核心行为未验证,不应视为迁移完成。
输出要求
执行本 skill 时,对用户的输出应保持简洁,优先提供:
- 是否值得迁移
- 建议扩展现有模块还是新增模块
- 解耦方案
- 设计方案确认内容
- 迁移完成后的关键文件与验证结果
不要输出冗长背景说明,不要把过程写成教程。
常见错误
以下情况应避免:
- 直接复制业务代码,只替换少量命名
- 未查重就新增一个近似模块
- 为了“看起来完整”而过度拆分目录
- 仅生成 README,没有验证核心行为
- 保留内部域名、业务前缀、租户信息、私有错误码
- 把内部 SDK 直接带入 PythonCodeHub
- 用第三方依赖掩盖本可抽象的接口边界
迁移完成标准
只有同时满足以下条件,才算完成一次合格迁移:
- 设计价值被保留
- 业务耦合被剥离
- 模块归类合理
- 仓库内无重复建设
- 最小示例可理解
- 核心行为已验证
- 无敏感信息残留
一句话判断准则
迁移到 PythonCodeHub 的不是原项目代码本身,而是其中值得复用的设计能力。