Bruce/CraftKit

Fork 0

Files

T

zhiye.sun f35b6a99d2 feat(doc): 新增 Markdown 排版 Skill

2026-08-25 11:02:09 +08:00

7.2 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. 迁移批次

第 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/report、doc/requirements
git/commit-msg
knowledge/handoff

完成门槛：doc/format-md 固化目录模板、验证命令、行为用例和迁移记录格式后，才能继续本批其余 Skill。

第 2 批：文档转换

所属插件：doc

docx-to-markdown
markdown-to-docx
excel-to-markdown
archive-docs

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

第 3 批：Git 工作流

所属插件：git

create-branch
configure-git
export-changes
integrate-branch

summarize-commit 已在样板批次完成。涉及提交、合并和远端操作的 Skill 必须保留明确授权边界，并保护脏工作区。

第 4 批：知识管理

所属插件：knowledge

analyze-agent-failure
distill-task
maintain-lessons
summarize-worklog
init-agents

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

第 5 批：开发主流程

所属插件：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，通过工作区、提交和分支三种模式覆盖。

第 6 批：项目规范与前端辅助

dev/select-component
dev/design-style
dev/design-form
skill/retrieve-guidance
skill/maintain-guidance

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

第 7 批：基于公开资料重建

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

dev/design-api
dev/design-db
dev/review-java
dev/review-frontend
dev/design-frontend-data
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 的迁移步骤

记录来源相对路径、提交和 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。
样板通过后推进第 1 批其余 Skill。

7.2 KiB Raw Blame History