CraftKit/migration/MIGRATION_PLAN.md

# 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. `knowledge/init`：成熟项目与空项目双模式初始化、参考项目提炼和共享/本地信息边界样本，已完成。
8. `skill/migrate`：不迁移。来源能力用于把 Claude Code Skill 转换为 Codex Skill；CraftKit 自始按 Codex 规范开发，不存在平台转换需求。来源扫描、目标检查和状态追踪继续由 `migration/scripts/` 作为仓库维护设施承担。

完成门槛：适用样本均通过对应验证，不适用样本记录排除依据，并形成可复用的命名、目录、独立实现、测试、扫描和状态同步规则。出现未覆盖的新结构或权限类型时，应补充样本，不直接扩批。当前特殊样本阶段已完成，可以进入同质批量迁移。

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

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

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

### 文档转换批次

所属插件：`doc`

1. `docx-to-md`
2. `md-to-docx`（已完成）
3. `xlsx-to-md`（已完成）
4. `archive`（已完成，以可配置规则平替固定目录、业务文件名、专有章节拆分和内部系统校验）

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

### Git 工作流批次

所属插件：`git`

1. `branch`（已完成）
2. `identity`（已完成，只管理 Git 提交用户名和邮箱）
3. `export`（已完成，环境配置默认排除，规范明确要求并再次确认后才可导出）
4. `integrate`（已完成，按项目规范通过隔离 worktree 评估、准备和发布预集成分支）

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

### 知识管理批次

所属插件：`knowledge`

1. `trace`（已完成）
2. `distill`（已完成）
3. `lessons`（已完成，合并初始化、维护、审计和提升）
4. `worklog`（已完成）
5. `init`（已完成）

来源中与经验初始化、提升和回扫相关的多个能力统一合并为 `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/component`（已完成，基于项目证据完成组件选型与契约查证）
2. `dev/style`（已完成，基于项目视觉基线设计样式）
3. `dev/form`（已完成，设计表单结构、响应布局和可访问性）
4. `skill/guidance`（特殊样本已完成）
5. `skill/guidance-edit`（已完成，建立、检查和维护项目规范索引）

这里只实现读取和维护“当前项目自身规范”的机制，不随 CraftKit 提供任何来源项目规范。
原前端导航能力由上述 Skill 的精确触发描述和 Codex 自动发现替代，不再维护独立路由 Skill。混合任务按 `style` → `component` → `form` → 前端设计或实现的依赖顺序处理。

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

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

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`（已完成）
7. `dev/design-workflow`（已完成）

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

### 平替或排除结果

- 公司框架知识与专属规范由 `skill/guidance`、项目源码和 `.craftkit/standards/` 平替。
- 内部组件契约、审批规则和消息格式不迁移，目标 Skill 只读取项目证据和用户输入。
- 升级、估算与发布已重建为通用能力，不携带内部版本矩阵和仓库流程。
- 浏览器代理配置由 Codex 浏览器或计算机操作能力平替。
- Skill 路由依靠精确触发描述和 Codex 自动发现，不增加独立路由器。
- 非 Codex 平台转换能力保持排除。

### 剩余迁移波次

截至 2026-08-26，原有 29 个 `pending` 来源已在一个连续波次内全部处理完成。所有来源均已闭合为 `migrated`、`superseded` 或 `excluded`；本波次完成验证后统一等待本地提交确认。

#### 阶段 1：公开基线与专项设计

| 来源能力 | 目标 Skill | 处理方式 |
| --- | --- | --- |
| API 约定 | `dev/design-api` | 基于 HTTP、OpenAPI 等官方资料独立重建 |
| 数据库约定 | `dev/design-db` | 基于目标数据库官方资料和项目证据独立重建 |
| Java 约定 | `dev/review-java` | 基于 Java 与所用框架对应版本官方资料独立重建 |
| 前端约定 | `dev/review-frontend` | 基于当前框架版本官方资料独立重建 |
| 前端数据约定 | `dev/design-frontend-data` | 建立请求、状态与视图模型的通用设计边界 |
| MyBatis 约定 | `dev/review-mybatis` | 基于 MyBatis 官方资料独立重建 |
| 工作流约定 | `dev/design-workflow` | 以项目工作流契约和用户输入平替内部审批规则 |

公开资料只采用一级官方来源，记录适用版本、重建日期和许可证或引用边界；不得改写来源规范正文。

#### 阶段 2：代码实现

| 来源 Skill | 目标 Skill | 状态关系 |
| --- | --- | --- |
| `back-code`、同类后端编码来源 | `dev/implement-backend` | 两个来源合并，一个迁移、一个 `superseded` |
| `front-code`、同类前端编码来源 | `dev/implement-frontend` | 两个来源合并，一个迁移、一个 `superseded` |

实现 Skill 直接修改业务源码，必须保护脏工作区、使用项目真实版本与规范、执行风险相称的验证，且不自动提交或推送。

#### 阶段 3：审查、测试与问题分析

| 来源能力 | 目标 Skill | 处理方式 |
| --- | --- | --- |
| 两套代码检查与一套代码审查 | `dev/review-code` | 合并为工作区、提交和分支审查模式 |
| 后端单元测试 | `dev/test-backend` | 按当前测试框架和项目模式生成或修改测试 |
| UI 测试 | `dev/test-ui` | 按用户可观察行为设计并执行浏览器测试 |
| Bug 列表分析 | `dev/analyze-bugs` | 解析通用结构化问题清单并形成证据化报告 |

本阶段不得把静态检查、单元测试、浏览器测试和真实环境验收混为同一结论。

#### 阶段 4：交付、升级与估算

| 来源能力 | 目标 Skill 或处理结果 | 处理方式 |
| --- | --- | --- |
| 后端升级、前端升级 | `dev/upgrade` | 合并为基于源版本、目标版本和官方迁移资料的通用升级流程 |
| 版本发布 | `git/release` | 只准备版本、变更摘要、标签和发布检查；远端动作单独授权 |
| 工作量评估 | `dev/estimate` | 基于范围、依赖、风险和假设输出区间估算 |
| 框架约定 | `skill/guidance` | `superseded`，内部规则由项目 `.craftkit/standards/` 提供 |
| 框架知识查询 | `skill/guidance` | `superseded`，改为检索项目证据和公开官方资料 |

#### 阶段 5：写作与平台工具收尾

| 来源能力 | 目标 Skill 或处理结果 | 处理方式 |
| --- | --- | --- |
| 领导汇报 | `doc/report` | 中性化为面向不同受众的事实型工作汇报 |
| 消息模板 | `doc/message` | 中性化为项目消息与通知草稿 |
| 技术内容转需求 | `doc/requirements` | 将技术输入转换为可确认的需求说明 |
| 能力创建器 | 官方 `skill-creator` | `superseded`，不重复发布同类 CraftKit Skill |
| 浏览器代理配置 | Codex 浏览器或计算机操作能力 | `superseded`，不迁移宿主专属代理配置 |
| Skill 转 Cursor | 无 | `excluded`，CraftKit 只面向 Codex |

#### 波次总门禁

1. 29 个来源全部更新为 `migrated`、`superseded` 或 `excluded`，不得遗留 `pending`。
2. 所有目标 Skill 通过结构、引用、敏感内容和真实请求边界测试。
3. 公开基线记录官方来源、适用版本和重建边界。
4. 有脚本的 Skill 完成隔离行为测试；有外部工具的 Skill 明确权限和未验证边界。
5. README、插件版本、迁移计划和来源锁同步一致。
6. 全量测试、JSON 校验和 `git diff --check` 通过。
7. 波次完成后只展示提交方案，不创建提交；用户统一确认后按逻辑范围创建本地提交。

## 5. 合并原则

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

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

目标 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`。
- [x] 迁移并验证模板化交接特殊样本 `knowledge/handoff`。
- [x] 完成其余特殊样本并总结批量迁移规则。
- [ ] 按插件和风险类型继续推进同质批量迁移。
- [x] 完成首个同质批量：`md-to-docx`、`xlsx-to-md`、`archive`。
- [x] 完成 Git 本地操作批次：`identity`、`export`。
- [x] 完成 Git 高风险隔离集成样本：`integrate`。
- [x] 完成知识管理批次：`trace`、`distill`、`lessons`、`worklog`。
- [x] 完成前端辅助批次：`component`、`style`、`form`，并以精确触发替代独立路由。
- [x] 完成项目规范维护能力：`guidance-edit`。
- [x] 完成开发分析与设计批次：`plan-change`、`design-backend`、`design-frontend`、`prepare-api`。