Bruce/CraftKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5b9fa51b6e68a0e10c0077ba7b19877641c6ac45
CraftKit/migration/MIGRATION_PLAN.md
T

11 KiB
Raw Blame History

Skill 迁移计划

1. 目标

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

迁移不追求来源 Skill 与目标 Skill 一一对应。重复能力应合并；公司专属实现不得迁移，但应优先将其解决的通用问题重建为中性平替，确无独立价值或无法安全替代时才排除。目标数量以职责清晰和实际复用价值为准。

2. 迁移路径

来源发现
  → 风险分类
  → 重复能力合并
  → 中性能力规格
  → 独立实现
  → 行为验证
  → 敏感内容扫描
  → 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

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

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

暂缓或排除

默认排除：

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

暂缓评估：

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

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. 当前执行顺序

  • 扩展 source-lock.json 的 Skill 级记录结构。
  • 实现来源只读扫描脚本。
  • 在 AGENTS.md 中固化分类、设计和确认流程。
  • 实现 Skill 与敏感内容检查脚本。
  • 实现迁移台账预览和更新脚本。
  • 迁移并验证首个样板 doc/format-md。
  • 迁移并验证脚本型特殊样本 doc/docx-to-md。
  • 迁移并验证只读 Git 特殊样本 git/commit-msg。
  • 迁移并验证有副作用 Git 特殊样本 git/branch。
  • 迁移并验证模板化交接特殊样本 knowledge/handoff。
  • 完成其余特殊样本并总结批量迁移规则。
  • 按插件和风险类型继续推进同质批量迁移。
  • 完成首个同质批量：md-to-docx、xlsx-to-md、archive。
  • 完成 Git 本地操作批次：identity、export。
  • 完成 Git 高风险隔离集成样本：integrate。
  • 完成知识管理批次：trace、distill、lessons、worklog。
  • 完成前端辅助批次：component、style、form，并以精确触发替代独立路由。
  • 完成项目规范维护能力：guidance-edit。
  • 完成开发分析与设计批次：plan-change、design-backend、design-frontend、prepare-api。
Reference in New Issue View Git Blame Copy Permalink