migrate-to-codehub

从其他项目提取优秀架构设计或功能实现,剥离业务耦合后迁移到 PythonCodeHub。触发:"迁移到 CodeHub"、"提取到 PythonCodeHub"、"重构后加入 CodeHub"、"migrate to codehub"。

SKILL.md

GitHub

目的

本技能指导 AI 完成代码迁移过程:从现有项目中识别有价值的架构设计或功能实现,剥离业务耦合,将其转化为可复用的 PythonCodeHub 模块。迁移完成后,输出的代码应具备清晰的接口、良好的可复用性,并能通过核心行为验证。

功能

  • 价值评估:分析源代码的设计质量和复用潜力,判断是否值得迁移
  • 查重归类:在 PythonCodeHub 中搜索近似实现,决定扩展还是新增模块
  • 解耦分析:识别并处理业务耦合、外部依赖、环境假设等通用耦合
  • 方案设计:生成迁移方案,包括目标、路径、接口设计、文件规划等
  • 重构实现:保留核心设计骨架,删除业务分支,抽象外部依赖
  • 验证输出:确保迁移后的代码通过 lint、测试、接口验证

使用场景

  • 发现了值得沉淀的架构设计(如分布式锁、任务调度、缓存机制)
  • 发现了值得复用的功能实现(如装饰器、工具函数、协议处理)
  • 发现了不能直接照搬,但其设计思路值得重构保留的代码
  • 需要将其他项目的优秀设计迁移到 PythonCodeHub 以供复用
  • 用户提到“迁移到 CodeHub”“提取到 PythonCodeHub”“把这个设计迁移过来”“重构后加入 CodeHub”“migrate to codehub”

迁移目标

将其他项目中的优秀设计或实现,重构为可复用、低耦合、易参考的 PythonCodeHub 代码。

最终产物应满足:

  • 可被其他项目复制后小幅调整使用
  • 不携带业务耦合、敏感信息或私有实现痕迹
  • 保留原设计的关键价值,而不是仅保留表面代码

何时使用

仅在以下情况使用本 skill:

  • 发现了值得沉淀的架构设计
  • 发现了值得复用的功能实现
  • 发现了不能直接照搬,但其设计思路值得重构保留的代码

若只是普通业务逻辑搬运、一次性脚本、强依赖上下文的内部实现,则不使用。

执行原则

  1. 先判断值不值得迁移,再开始写代码
  2. 优先扩展现有模块,避免重复建设
  3. 优先保留设计思路,不强求保留原始写法
  4. 优先标准库和轻依赖,避免把业务环境搬进仓库
  5. 结构与复杂度匹配,避免过度拆分
  6. 至少验证核心行为,不只生成目录和 README

执行流程

阶段 1:识别与判定

先在 PythonCodeHub 中搜索近似实现,再决定是扩展还是新增。

必须同时满足以下条件,才值得迁移:

  • 通用性:去掉业务逻辑后,核心设计仍成立
  • 复用价值:至少存在一个明确的跨项目使用场景
  • 独立性:可以脱离原业务模块独立表达
  • 接口稳定性:能够抽象出清晰的公开类、函数或 Protocol
  • 代码质量:原实现确实有值得保留的设计优势

若不满足,直接向用户说明原因并停止。

迁移粒度判断

根据源代码复杂度决定迁移批次:

  • 单一职责能力(如一个装饰器、一个工具函数):一次性迁移
  • 中等复杂度(如一个完整的锁机制):一次迁移,但可分文件实现
  • 大型系统(如完整的任务调度框架):拆分为独立子能力,分批迁移,每批独立可用

拆分原则:每批迁移产物必须独立可运行、独立可测试,不依赖后续批次才能工作。

阶段 2:查重与归类

先判断目标能力是否已经在仓库中存在:

  • 若已有相近模块,优先补充现有模块
  • 若只是能力增强,优先新增文件或子能力,不要复制一套相似结构
  • 仅当现有目录确实无法容纳时,才新增模块目录

做出归类判断时,优先参考现有 ab_* 目录的能力边界,而不是按原项目目录生搬硬套。

阶段 3:解耦分析

逐项识别并处理常见的通用耦合:

耦合类型 处理方式
领域对象或持久化模型耦合 改为 Protocol、ABC、DTO 或通用数据结构
配置来源耦合 提取为构造参数、配置对象或函数参数
外部系统或基础设施耦合 改为接口抽象、适配器或标准库实现
运行环境耦合 删除隐式假设,改为显式注入运行参数
观测能力耦合 删除强绑定实现,替换为 logging 或可选扩展点
异常体系耦合 改为通用异常或通用自定义异常
命名约定与标识规则耦合 删除硬编码,改为参数化或示例值
私有实现细节耦合 只保留思路,重写为公共抽象
并发/线程模型耦合 抽象为可选的执行器接口,支持同步/异步两种模式
Python 版本特性耦合 标注最低版本要求,避免使用过新的语法糖

额外检查:

  • 不保留组织内部标识、私有地址、环境细节或敏感常量
  • 不迁移依赖特定部署方式、特定组织规则或封闭生态的实现细节
  • 若必须保留第三方依赖,优先复用仓库已有依赖,并说明必要性
  • 若第三方依赖只是为了省事,优先改为标准库或接口抽象

依赖冲突处理:

  • 优先适配仓库已有依赖版本
  • 若必须升级依赖,需评估对其他模块的影响
  • 若冲突不可调和,考虑将依赖改为可选(extras_require)

阶段 4:先出方案,等待确认

在开始写代码前,必须先给用户一个简要方案,并等待确认。

方案至少包含:

  1. 迁移目标:一句话说明本次沉淀什么能力
  2. 归属路径:落到哪个目录或文件
  3. 复用判断:扩展现有模块还是新增模块
  4. 解耦策略:要剥离哪些业务耦合
  5. 接口设计:核心公开类、函数、Protocol 的名称与关键参数
  6. 文件规划:预计新增或修改哪些文件
  7. 验证方式:计划如何验证核心行为

参考格式:

📋 迁移设计方案
━━━━━━━━━━━━━━━━
目标:迁移分布式锁的看门狗续期机制
路径: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 的不是原项目代码本身,而是其中值得复用的设计能力。