SuperAPI AI 工具集

okf-refactor

编程与开发

查看项目

更新于 10-15 21:36

技能介绍

用途:将已存在于其他形态的知识——零散 Markdown 笔记、wiki、README/文档、数据目录导出、数据库 schema、JSON/CSV 元数据转储——转换为符合 OKF v0.1 规范的知识包:一个概念一个文件的 Markdown 文档目录,带 YAML frontmatter、可导航的 index.md 和交叉链接的知识图谱。

依赖:本技能依赖 okf 技能提供格式本身。重构前需阅读 ../okf/reference/SPEC.md(随附的 OKF v0.1 规范),它是唯一事实来源;用 ../okf/scripts/validate_okf.py 校验结果。

输入输出:输入 <src> 为要读取的目录、文件集或导出,视为不可变事实,绝不原地修改;输出 <out> 为写入的知识包目录,须与 <src> 分离。写入前确认两个路径;若省略 <out>,默认 ./bundles/<name> 并说明该选择。

重构流程(按序执行,先规划再写入):调查来源,盘点每条知识及其自然边界,识别每个“事物”的类型(表、端点、概念、运行手册)并记录关系;设计分类即目录布局,按类型或领域分组,先扁平、必要时再嵌套,目录承载粗分类,frontmatter 标签承载横切面;将每个来源项映射为一个概念文档,原子化、每文件一个概念,使用 <group>/<slug>.md 的 kebab-case 稳定 slug,多主题笔记需拆分;为每个概念写 frontmatter,type 非空,派生 title 与 description(一行),有规范 URI 时设 resource,映射来源元数据到 tags 与 timestamp,来源特有元数据保留为额外 frontmatter 键;写正文,结构化字段放 # Schema(优先表格),可运行用法放 # Examples,来源放 # Citations,保持简洁、不虚构来源中不存在的事实;连接图谱,把每个关系转为使用绝对包相对路径的内联 Markdown 链接,避免真正孤立的概念;为被多概念引用的外部权威来源创建 references/<slug>.md 独立参考文档;为每个可导航目录生成 index.md(无 frontmatter,按 # 分组,条目描述复制自被链接概念),根 index.md 带 okf_version: "0.1" frontmatter 并链接顶层分组;在根目录播种 log.md,记录 ## <YYYY-MM-DD> 条目及 Initialization: Refactored from <source>,使用真实当前日期;运行 validate_okf.py <out>,修复所有错误,断链为警告(规范容忍),尽量解决并报告其余。

保真规则:意义无损,重构可删冗余词但不可丢事实;不虚构描述、schema 或链接,真实缺口明确标注而非猜测;来源保持不可变,所有写入落在 <out>;近似幂等,对同一来源重跑应收敛到同一知识包而非累积重复。

完成后报告:按类型/分组统计产出的概念数、创建的索引与参考文档、连接的交叉链接,以及未解决的缺口或断链,并展示知识包目录树。

限制:资料未提供具体安装命令、收费、价格、平台或效果信息。