216 lines
7.1 KiB
Markdown
216 lines
7.1 KiB
Markdown
# Skill 迁移计划
|
|
|
|
## 1. 目标
|
|
|
|
将两个本地来源中的通用能力整理为 CraftKit Skill。迁移结果必须适用于 Codex 插件市场，并与来源项目的品牌、内部框架、业务知识和运行环境解耦。
|
|
|
|
迁移不追求来源 Skill 与目标 Skill 一一对应。重复能力应合并，公司专属能力应排除，目标数量以职责清晰和实际复用价值为准。
|
|
|
|
## 2. 迁移路径
|
|
|
|
```text
|
|
来源发现
|
|
→ 风险分类
|
|
→ 重复能力合并
|
|
→ 中性能力规格
|
|
→ 独立实现
|
|
→ 行为验证
|
|
→ 敏感内容扫描
|
|
→ Codex 与插件校验
|
|
→ 更新迁移状态
|
|
```
|
|
|
|
禁止采用“完整复制来源目录后批量替换名称”的方式。中性能力规格形成后，目标实现应基于该规格、当前 Codex 能力和公开资料完成。
|
|
|
|
## 3. 状态模型
|
|
|
|
| 状态 | 含义 | 进入条件 |
|
|
| --- | --- | --- |
|
|
| `pending` | 待评估 | 已发现来源 Skill |
|
|
| `specified` | 已完成中性规格 | 已明确目标、边界、依赖和排除内容 |
|
|
| `rewriting` | 独立实现中 | 已创建目标 Skill |
|
|
| `review` | 待复核 | 功能完成，但版权、依赖或行为仍需确认 |
|
|
| `migrated` | 已迁移 | 全部门禁通过 |
|
|
| `excluded` | 不迁移 | 公司专属或没有独立价值 |
|
|
| `superseded` | 已合并 | 能力已由另一个目标 Skill 覆盖 |
|
|
|
|
## 4. 迁移批次
|
|
|
|
### 第 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-markdown`
|
|
2. `git/summarize-commit`
|
|
3. `knowledge/prepare-handoff`
|
|
4. `doc/write-report`
|
|
5. `doc/tech-to-requirements`
|
|
|
|
完成门槛：固化目录模板、验证命令、行为用例和迁移记录格式。
|
|
|
|
### 第 2 批：文档转换
|
|
|
|
所属插件：`doc`
|
|
|
|
1. `docx-to-markdown`
|
|
2. `markdown-to-docx`
|
|
3. `excel-to-markdown`
|
|
4. `archive-docs`
|
|
|
|
重点验证图片、表格、合并单元格、编码、覆盖策略和路径安全。脚本及测试数据必须独立创建。
|
|
|
|
### 第 3 批：Git 工作流
|
|
|
|
所属插件：`git`
|
|
|
|
1. `create-branch`
|
|
2. `configure-git`
|
|
3. `export-changes`
|
|
4. `integrate-branch`
|
|
|
|
`summarize-commit` 已在样板批次完成。涉及提交、合并和远端操作的 Skill 必须保留明确授权边界，并保护脏工作区。
|
|
|
|
### 第 4 批：知识管理
|
|
|
|
所属插件：`knowledge`
|
|
|
|
1. `analyze-agent-failure`
|
|
2. `distill-task`
|
|
3. `maintain-lessons`
|
|
4. `summarize-worklog`
|
|
5. `init-agents`
|
|
|
|
来源中与经验初始化、提升和回扫相关的多个能力统一合并为 `maintain-lessons`，通过模式区分具体工作。
|
|
|
|
### 第 5 批：开发主流程
|
|
|
|
所属插件：`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`，通过工作区、提交和分支三种模式覆盖。
|
|
|
|
### 第 6 批：项目规范与前端辅助
|
|
|
|
1. `dev/select-component`
|
|
2. `dev/design-style`
|
|
3. `dev/design-form`
|
|
4. `skill/retrieve-guidance`
|
|
5. `skill/maintain-guidance`
|
|
|
|
这里只实现读取和维护“当前项目自身规范”的机制，不随 CraftKit 提供任何来源项目规范。
|
|
|
|
### 第 7 批：基于公开资料重建
|
|
|
|
以下能力不从来源文本改写，而是根据官方资料重新设计：
|
|
|
|
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`
|
|
|
|
中性规格必须记录所采用的公开标准、官方文档和许可证信息。
|
|
|
|
### 第 8 批：暂缓或排除
|
|
|
|
默认排除：
|
|
|
|
- 公司框架知识查询与专属代码规范。
|
|
- 内部组件契约、审批流程和消息格式。
|
|
- 内部仓库发布流程和框架版本升级矩阵。
|
|
|
|
暂缓评估：
|
|
|
|
- 浏览器代理配置。
|
|
- 通用大版本升级工具。
|
|
- Skill 路由器。
|
|
- 工作量评估。
|
|
- 非 Codex 平台的迁移工具。
|
|
|
|
## 5. 合并原则
|
|
|
|
来源数量不等于目标数量。优先执行以下合并：
|
|
|
|
| 来源能力类型 | 目标 Skill |
|
|
| --- | --- |
|
|
| 代码检查、提交审查、分支审查 | `review-code` |
|
|
| 多套开发计划 | `plan-change` |
|
|
| 多套后端设计 | `design-backend` |
|
|
| 多套前端设计 | `design-frontend` |
|
|
| 多套后端实现 | `implement-backend` |
|
|
| 多套前端实现 | `implement-frontend` |
|
|
| 多套 Word 转 Markdown | `docx-to-markdown` |
|
|
| 经验初始化、提升、回扫 | `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] 实现迁移台账预览和更新脚本。
|
|
- [ ] 迁移并验证首个样板 `doc/format-markdown`。
|
|
- [ ] 样板通过后推进第 1 批其余 Skill。
|