Migrate To Codehub

---
name: migrate-to-codehub
description: 从其他项目中提取优秀架构设计或功能实现，剥离业务耦合后迁移到 PythonCodeHub。适用于“迁移到 CodeHub”“提取到 PythonCodeHub”“把这个设计迁移过来”“重构后加入 CodeHub”“migrate to codehub”等场景。
---

## 目的

本技能指导 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. **验证方式**：计划如何验证核心行为

参考格式：

```text
📋 迁移设计方案
━━━━━━━━━━━━━━━━
目标：迁移分布式锁的看门狗续期机制
路径：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` 只写对使用者真正有价值的内容

推荐结构：

```text
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 的不是原项目代码本身，而是其中值得复用的设计能力。**