# Skill 迁移计划

## 1. 目标

将两个本地来源中的通用能力整理为 CraftKit Skill。迁移结果必须适用于 Codex 插件市场，并与来源项目的品牌、内部框架、业务知识和运行环境解耦。

迁移不追求来源 Skill 与目标 Skill 一一对应。重复能力应合并，公司专属能力应排除，目标数量以职责清晰和实际复用价值为准。

## 2. 迁移路径

```text
来源发现
  → 风险分类
  → 重复能力合并
  → 中性能力规格
  → 独立实现
  → 行为验证
  → 敏感内容扫描
  → Codex 与插件校验
  → 更新迁移状态
```

禁止采用“完整复制来源目录后批量替换名称”的方式。中性能力规格形成后，目标实现应基于该规格、当前 Codex 能力和公开资料完成。

## 3. 状态模型

| 状态 | 含义 | 进入条件 |
| --- | --- | --- |
| `pending` | 待评估 | 已发现来源 Skill |
| `specified` | 已完成中性规格 | 已明确目标、边界、依赖和排除内容 |
| `rewriting` | 独立实现中 | 已创建目标 Skill |
| `review` | 待复核 | 功能完成，但版权、依赖或行为仍需确认 |
| `migrated` | 已迁移 | 全部门禁通过 |
| `excluded` | 不迁移 | 公司专属或没有独立价值 |
| `superseded` | 已合并 | 能力已由另一个目标 Skill 覆盖 |

## 4. 迁移批次

迁移分为“特殊样本”和“同质批量”两个阶段。前者用于覆盖迁移机制的不同风险类型，后者在规则稳定后提高吞吐量。批次数量不固定：特殊样本原则上逐个迁移，批量阶段每批建议 6～12 个同质 Skill。

### 第 0 批：迁移基础设施

第 0 批属于仓库内部维护工具，不发布为市场 Skill：

1. `migration/scripts/scan_sources.py`：只读发现来源 Skill、辅助资源和文件哈希。
2. `AGENTS.md` 迁移工作流：完成分类、目标设计和用户确认。
3. `migration/scripts/check_skill.py`：检查结构、引用、占位符、敏感内容和凭据风险。
4. `migration/scripts/update_lock.py`：预览或更新来源指纹和迁移状态。

完成门槛：能够对全部来源 Skill 生成稳定清单，并在不复制来源内容的情况下更新状态。

### 第 1 阶段：特殊样本

特殊样本不追求模块连续性，而是覆盖不同迁移机制：

1. `doc/format-md`：纯指令型样本，已完成。
2. `doc/docx-to-md`：多来源合并、脚本、依赖和生成物样本，已完成。
3. `git/commit-msg`：只读 Git 状态分析样本，已完成。
4. `git/branch`：修改仓库状态和二次授权边界样本，已完成。
5. `knowledge/handoff`：模板化文档与项目上下文样本。
6. `skill/guidance`：大型参考资料、索引和渐进式加载样本。
7. `skill/migrate`：脚本、检查、同步和状态追踪组成的复合工作流样本。

完成门槛：每种样本均通过对应验证，并形成可复用的命名、目录、独立实现、测试、扫描和状态同步规则。出现未覆盖的新结构或权限类型时，应补充样本，不直接扩批。

### 第 2 阶段：同质批量迁移

特殊样本完成后，按同一插件、相近能力和相同风险类型组织批量迁移：

- 每批建议 6～12 个 Skill，高度同质时可以整组处理。
- 不把只读能力与有副作用能力、纯指令与复杂脚本、普通迁移与公开资料重建强行合为一批。
- 每批仍需迁移前确认和提交前确认，并统一更新 README、迁移计划和来源状态。
- 任一验收门禁失败时暂停该批，不继续扩大范围。

### 文档转换批次

所属插件：`doc`

1. `docx-to-md`
2. `markdown-to-docx`
3. `excel-to-markdown`
4. `archive-docs`

重点验证图片、表格、合并单元格、编码、覆盖策略和路径安全。脚本及测试数据必须独立创建。

### Git 工作流批次

所属插件：`git`

1. `create-branch`
2. `configure-git`
3. `export-changes`
4. `integrate-branch`

`commit-msg` 将作为只读 Git 特殊样本先行完成。涉及提交、合并和远端操作的 Skill 必须保留明确授权边界，并保护脏工作区。

### 知识管理批次

所属插件：`knowledge`

1. `analyze-agent-failure`
2. `distill-task`
3. `maintain-lessons`
4. `summarize-worklog`
5. `init-agents`

来源中与经验初始化、提升和回扫相关的多个能力统一合并为 `maintain-lessons`，通过模式区分具体工作。

### 开发主流程批次

所属插件：`dev`

```text
plan-change
  ├─ design-backend → implement-backend → test-backend
  └─ design-frontend → implement-frontend → test-ui
                              ↓
                         review-code
```

建议顺序：

1. `plan-change`
2. `design-backend`
3. `design-frontend`
4. `prepare-api`
5. `implement-backend`
6. `implement-frontend`
7. `review-code`
8. `test-backend`
9. `test-ui`
10. `analyze-bugs`

多个来源中的代码检查、代码审查能力合并为 `review-code`，通过工作区、提交和分支三种模式覆盖。

### 项目规范与前端辅助批次

1. `dev/select-component`
2. `dev/design-style`
3. `dev/design-form`
4. `skill/retrieve-guidance`
5. `skill/maintain-guidance`

这里只实现读取和维护“当前项目自身规范”的机制，不随 CraftKit 提供任何来源项目规范。

### 基于公开资料重建批次

以下能力不从来源文本改写，而是根据官方资料重新设计：

1. `dev/design-api`
2. `dev/design-db`
3. `dev/review-java`
4. `dev/review-frontend`
5. `dev/design-frontend-data`
6. `dev/review-mybatis`

中性规格必须记录所采用的公开标准、官方文档和许可证信息。

### 暂缓或排除

默认排除：

- 公司框架知识查询与专属代码规范。
- 内部组件契约、审批流程和消息格式。
- 内部仓库发布流程和框架版本升级矩阵。

暂缓评估：

- 浏览器代理配置。
- 通用大版本升级工具。
- Skill 路由器。
- 工作量评估。
- 非 Codex 平台的迁移工具。

## 5. 合并原则

来源数量不等于目标数量。优先执行以下合并：

| 来源能力类型 | 目标 Skill |
| --- | --- |
| 代码检查、提交审查、分支审查 | `review-code` |
| 多套开发计划 | `plan-change` |
| 多套后端设计 | `design-backend` |
| 多套前端设计 | `design-frontend` |
| 多套后端实现 | `implement-backend` |
| 多套前端实现 | `implement-frontend` |
| 多套 Word 转 Markdown | `docx-to-md` |
| 经验初始化、提升、回扫 | `maintain-lessons` |
| 规范检索和索引维护 | `retrieve-guidance`、`maintain-guidance` |

目标 Skill 总量不设硬指标，预期控制在约 30 个，避免细碎能力和重复触发。

## 6. 单个 Skill 的迁移步骤

1. 记录来源相对路径、提交和 SHA-256。
2. 判断该能力是迁移、合并、重建还是排除。
3. 只提炼目标、输入、输出、关键边界和真实用例，形成中性规格。
4. 确定目标插件和简短 Skill 名称。
5. 基于中性规格和公开资料独立实现。
6. 对脚本执行单元或行为测试，对文档型 Skill 执行真实请求测试。
7. 扫描敏感内容、来源残留、无效工具名和宿主绑定表达。
8. 运行 Skill 与插件校验。
9. 将状态更新为 `migrated`，记录目标路径、目标版本和复核日期。
10. 展示迁移结果、验证证据、待提交文件和建议提交信息，等待用户再次确认。
11. 用户确认后精确暂存本批文件并创建本地提交；推送和发布仍需独立授权。

## 7. 每批验收门禁

- Skill 名称简洁，目录名与 frontmatter 一致。
- `description` 能准确触发，不是大而全的能力描述。
- 不存在来源正文、脚本、模板、示例或独特结构的直接复制。
- 公司标识、内部域名、包名、路径和人员信息扫描为零。
- 所有引用文件存在，脚本和生成物经过实际验证。
- Skill 校验和所属插件校验通过。
- 至少一个真实请求用例通过。
- `source-lock.json` 已更新。

任一门禁未通过时，不进入下一批的大规模迁移。

## 8. 当前执行顺序

- [x] 扩展 `source-lock.json` 的 Skill 级记录结构。
- [x] 实现来源只读扫描脚本。
- [x] 在 `AGENTS.md` 中固化分类、设计和确认流程。
- [x] 实现 Skill 与敏感内容检查脚本。
- [x] 实现迁移台账预览和更新脚本。
- [x] 迁移并验证首个样板 `doc/format-md`。
- [x] 迁移并验证脚本型特殊样本 `doc/docx-to-md`。
- [x] 迁移并验证只读 Git 特殊样本 `git/commit-msg`。
- [x] 迁移并验证有副作用 Git 特殊样本 `git/branch`。
- [ ] 完成其余特殊样本并总结批量迁移规则。
- [ ] 按插件和风险类型推进同质批量迁移。