Bruce/CraftKit

Fork 0

Files

T

zhiye.sun 72398c9f89 docs(migration): 建立剩余 Skill 连续迁移波次

2026-08-26 10:15:09 +08:00

16 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：

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

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

第 1 阶段：特殊样本

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

doc/format-md：纯指令型样本，已完成。
doc/docx-to-md：多来源合并、脚本、依赖和生成物样本，已完成。
git/commit-msg：只读 Git 状态分析样本，已完成。
git/branch：修改仓库状态和二次授权边界样本，已完成。
knowledge/handoff：模板化文档与项目上下文样本，已完成。
skill/guidance：大型参考资料、索引和渐进式加载样本，已完成；只检索项目资料和基于公开一级资料独立重建的中性公共基线。
knowledge/init：成熟项目与空项目双模式初始化、参考项目提炼和共享/本地信息边界样本，已完成。
skill/migrate：不迁移。来源能力用于把 Claude Code Skill 转换为 Codex Skill；CraftKit 自始按 Codex 规范开发，不存在平台转换需求。来源扫描、目标检查和状态追踪继续由 migration/scripts/ 作为仓库维护设施承担。

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

第 2 阶段：同质批量迁移

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

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

文档转换批次

所属插件：doc

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

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

Git 工作流批次

所属插件：git

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

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

知识管理批次

所属插件：knowledge

trace（已完成）
distill（已完成）
lessons（已完成，合并初始化、维护、审计和提升）
worklog（已完成）
init（已完成）

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

开发主流程批次

所属插件：dev

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

建议顺序：

plan-change（已完成）
design-backend（已完成）
design-frontend（已完成）
prepare-api（已完成）
implement-backend（已完成）
implement-frontend（已完成）
review-code（已完成）
test-backend（已完成）
test-ui（已完成）
analyze-bugs（已完成）

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

项目规范与前端辅助批次

dev/component（已完成，基于项目证据完成组件选型与契约查证）
dev/style（已完成，基于项目视觉基线设计样式）
dev/form（已完成，设计表单结构、响应布局和可访问性）
skill/guidance（特殊样本已完成）
skill/guidance-edit（已完成，建立、检查和维护项目规范索引）

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

基于公开资料重建批次

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

dev/design-api（已完成）
dev/design-db（已完成）
dev/review-java（已完成）
dev/review-frontend（已完成）
dev/design-frontend-data（已完成）
dev/review-mybatis（已完成）
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

波次总门禁

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

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 的迁移步骤

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

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。

16 KiB Raw Blame History Unescape Escape