OKF Bundle 插件

@docmd/plugin-okf 插件在静态编译期间生成一个 Open Knowledge Format (OKF) 知识包。OKF 是一种开放、供应商中立的规范，用于为 AI 智能体与 LLM 工具链结构化文档元数据、概念图谱与领域上下文。

该插件 默认启用。在每次站点编译过程中，OKF 知识包都会被输出至 site/okf/ 目录。

架构概览

OKF 将知识架构规范化为一个包含 YAML 清单、Markdown 概念文件和可视化力导向图谱资源的便携式目录结构。

设计原则

1. 最小化结构约束: 每个概念条目仅要求包含一个 type 字段。
2. 生产者/消费者独立性: 人类编写的 Markdown 文件编译为标准 Schema，可由任意 LLM 框架进行查询。
3. 供应商中立: 独立于具体的云服务商、模型托管商或向量数据库引擎。

生成的产物目录

编译将生成以下目录树：

site/okf/
├── okf.yaml  # 清单摘要文件
├── index.md  # 按类型分组的概念目录
├── graph/  # 交互式图谱资源（仅当 graph: true 时生成）
│   ├── index.html  # 力导向图谱可视化器
│   ├── graph.json  # 图形节点与边数据
│   ├── graph.js  # 独立图形运行时
│   └── graph.css  # 主题感知的样式文件
├── concepts/
│   └── <slug>.md  # 独立概念 Markdown 文件
└── _meta/
    ├── bundle.json  # okf.yaml 的 JSON 镜像
    └── lint-report.txt  # 构建 Linting 报告

默认构建行为

OKF 插件会在编译期间自动加载：

• 默认语言作用域: 在包根目录下输出主语言的概念文件。
• 自动类型推断: 自动将 /api/、/guides/、/reference/、/concepts/、/runbooks/、/datasets/、/metrics/ 和 /tables/ 路径下的文件归类为对应的类型化概念。
• 逐字 Markdown 复制: 将页面内容与 Frontmatter 复制到概念文件中。

选择退出

在 docmd.config.json 中禁用 OKF 知识包生成：

{
  "plugins": {
    "okf": false
  }
}

或者设置 enabled: false：

{
  "plugins": {
    "okf": {
      "enabled": false
    }
  }
}

配置选项

在 docmd.config.json 中配置 OKF 知识包参数：

全局配置示例

{
  "plugins": {
    "okf": {
      "outputDir": "knowledge",
      "defaultType": "concept",
      "graph": true
    }
  }
}

多语言文件夹策略

{
  "plugins": {
    "okf": {
      "localeStrategy": "folders"
    }
  }
}

输出目录结构：

site/okf/  # 默认语言（根目录）
├── okf.yaml
├── index.md
└── concepts/

site/okf/de/  # 德语（嵌套）
├── okf.yaml
└── concepts/

从 OKF 中排除页面

使用 Frontmatter 标记排除特定页面：

---
title: "内部运维说明"
okf: false # 仅从 OKF 知识包中排除该页面
---

若要在 Sitemap、搜索、LLM 文件和 OKF 中全局排除页面，请设置 noindex: true。

概念类型解析

插件使用自顶向下的优先级确定概念类型：

1. frontmatter.okf.type, 嵌套显式声明。
2. frontmatter.type, 顶层显式声明。
3. frontmatter.okfType, 旧版别名。
4. 路径前缀推断: 针对 /guides/、/api/、/reference/、/concepts/ 等路径自动映射。
5. defaultType 回退 ('concept')。

概念元数据与标签解析

OKF 插件直接从每个页面的 Frontmatter 提取丰富的元数据并写入 site/okf/okf.yaml 与 site/okf/_meta/bundle.json：

• 概念描述: 页面的 description 属性会直接包含在 okf.yaml 和 bundle.json 的每个概念条目中，方便 AI 智能体直接基于摘要定位内容，无需逐一解析各个 Markdown 文件。
• 从 tags 与 keywords 提取标签: 插件会自动整合 Frontmatter 中的 tags 与 keywords 属性。同时支持字符串数组（如 ["api", "auth"]）与逗号分隔的字符串（如 "api, auth"），并自动完成不区分大小写的去重处理。