360 Secure SkillHub
360 安全技能中心

okf

将碎片化文章、笔记、数据库表结构以及 CSV/数据集/API 文档/schema 等输入，转换为符合 Open Knowledge Format v0.1 的 markdown 知识库 bundle：生成带 YAML frontmatter 的概念文档、交叉链接、index.md 导航与 log.md 记录；配套 schema 内省、合规校验和 bundle 查询（list/get/search…

360U3317909958
360U3317909958
热度 34.89
最近更新 2026-07-01 16:55:54
分类：知识依赖：代码执行 / 读写文件 / 内部调用大模型应用场景：笔记整理 / 数据处理 / 摘要总结 / 模板

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add okf
Metadata
name
okf
description
把碎片化知识转成 Open Knowledge Format (OKF v0.1) bundle —— 一个厂商中立、agent 友好的 markdown 知识库格式。三类输入统一处理：(1) 碎片化文章/笔记/wiki/文档，(2) 数据库表结构（SQLite/MySQL/PostgreSQL，读 schema 生成表概念并推断 join），(3) 其它内容（CSV/数据集/API 文档/指标定义/schema 文件）。生成带 YAML frontmatter、概念间交叉链接、index.md 导航的合规 bundle，可进版本控制、供 AI agent 直接消费。触发词：OKF、Open Knowledge Format、知识库、knowledge bundle、数据库文档化、schema 转文档、表结构生成文档、碎片化文章整理、agent 上下文、知识沉淀、data catalog、把这些整理成知识库。

/okf

把散落的知识（文章、数据库表、CSV/API/schema 等）转成符合 Open Knowledge Format v0.1 的 markdown bundle——一个可读、可 diff、可进版本控制、人和 AI agent 都能直接 消费的知识库格式。

OKF 的核心理念：格式而非平台。产物就是一堆带 YAML frontmatter 的 .md 文件， 不绑任何云、数据库或框架，无需 SDK 即可读写。

Usage

/okf <path>                          # 把本地文件/文件夹转成 OKF bundle
/okf <path> --out <dir>              # 指定输出目录（默认 ./okf-bundle）
/okf --db <conn> [--tables t1,t2]    # 连数据库，把表结构转成概念（含 join 推断）
/okf <path> --no-enrich              # 只做结构化转换，关闭 LLM 富化（零幻觉降级）
/okf <path> --update                 # 增量：只处理新增/变更文件，追加 log.md
/okf <bundle> --validate             # 校验现有 bundle 是否符合 OKF v0.1

# —— 查询已有 bundle（消费端）——
/okf <bundle> --query list [--type T] [--tag G]   # 列出概念，可按 type/tag 过滤
/okf <bundle> --query get <concept_id>            # 取概念全文 + 出链/入链
/okf <bundle> --query search "<关键词>"           # 全文搜索（frontmatter+body）
/okf <bundle> --query links <concept_id> [--in|--out]  # 看概念关系
/okf <bundle> --query neighbors <concept_id> --depth N  # 按边扩散 N 跳
/okf <bundle> --query types|tags|tree             # 统计各 type/tag / 打印概念树

<conn> 示例：

  • ./sales.db 或 sqlite:///path/sales.db（SQLite，零依赖）
  • mysql://user:pass@host:3306/dbname（需 pip install pymysql）
  • postgresql://user:pass@host:5432/dbname（需 pip install psycopg2-binary）

本 skill 的文件

  • scripts/db_introspect.py — 读数据库 schema，输出统一中间 JSON（不含 LLM，只读）
  • scripts/validate_bundle.py — 校验 bundle 是否符合 OKF v0.1 conformance
  • scripts/query_bundle.py — 查询 bundle（消费端）：list/get/search/links/neighbors/types/tags/tree（只读，零依赖）
  • references/okf-spec-v0.1.md — 规范精简版（离线可查，动手前先读）
  • references/frontmatter-fields.md — 字段详解 + 各 type 的推荐 body 骨架（写概念时对照）
  • references/examples/ — 三类输入的 before→after 完整样例（article / database / mixed）

工作流

第 0 步：读规范

动手前先读 references/okf-spec-v0.1.md 和 references/frontmatter-fields.md， 确保产物合规。写概念文档时对照 references/examples/ 里对应的样例。

第 1 步：识别输入 → 选择路径

  • 给了 --db 或连接串 → 数据库路径
  • 给了本地文件/文件夹 → 看内容：主要是文章/笔记 → 文章路径；含 CSV/API/schema 等异构内容 → 混合路径。一个 bundle 里可以并存多种。

第 2 步：抽取概念

文章路径（对照 examples/article-bundle/）

  1. 读入所有文本，按主题/标题切分成独立概念——一个概念一个 .md。
  2. 给每个概念选 type：Article / Reference / Runbook / Playbook / Glossary Term 等（宁具体勿含糊）。
  3. 概念放到有语义的目录下，如 concepts/、runbooks/。

数据库路径（对照 examples/database-bundle/）

  1. 跑内省脚本拿结构化 JSON（不含任何推断）： 
    python3 scripts/db_introspect.py --conn "<conn>" [--tables t1,t2] --out /tmp/schema.json
    缺驱动 → 退出码 3 并打印安装提示；连不上 → 退出码 4 并打印排查提示。
  2. 每张表/视图 → 一个概念 tables/<name>.md，type 用 Table/View 或具体方言 （PostgreSQL Table 等）。
  3. body 写「# Schema」字段表；有外键 → 「# Joins」段写确定关系并互链。

混合路径（对照 examples/mixed-bundle/）

  • CSV/数据集 → type: Dataset，字段表由表头 + 抽样值归纳。
  • API 文档 → type: API Endpoint，忠实提取参数/响应。
  • 指标定义 → type: Metric；schema 文件 → 按其描述的对象归类。

第 3 步：富化（默认开；--no-enrich 时跳过）

基于已读到的真实内容，为每个概念：

  • 补 description（单句）、title、tags、timestamp。
  • 写清晰的 body（按 frontmatter-fields.md 的骨架）。
  • 推断关系：数据库场景据外键+字段名推断 join；文章场景识别概念间引用关系。
  • 推断的关系必须标注「推断」，确定的（如外键）标「确定」。

⚠️ 零幻觉边界（见下方专节）——富化只做归纳/摘要/结构化/合理推断，绝不编造 不存在的表、字段、事实。

第 4 步：交叉链接

概念之间用标准 markdown 链接互连，推荐 bundle 相对绝对路径（以 / 开头， 文件移动时更稳）：[customers](/tables/customers.md)。断链是允许的（代表尚未撰写的知识）。

第 5 步：生成骨架

  • 每层目录写 index.md（无 frontmatter）做渐进式导航，列出该层概念 + 一句话。
  • bundle 根写 index.md（可带 bundle 级 frontmatter）。
  • bundle 根写 log.md 记录本次生成（来源、概念数、时间）。

第 6 步：自校验

python3 scripts/validate_bundle.py <out_dir>

必须通过 conformance（无 ERROR）。把校验结论报告给用户。

消费：查询已有 bundle

当用户已经有一个 bundle、想检索/问答/导航它时（而不是新建），用 scripts/query_bundle.py。核心原则：渐进式披露——不要把整个 bundle 读进 上下文，而是按需检索。加 --json 得到 agent 友好的结构化结果。

典型消费流程：

  1. 摸清全貌：query_bundle.py <bundle> tree（或 types / tags）看有哪些概念。
  2. 定位相关概念：search "<关键词>" 或 list --type Table / list --tag revenue。
  3. 取概念详情：get <concept_id> --json 拿到 frontmatter + body + 出链/入链。
  4. 顺着图走：links <id> --in 看谁引用了它；neighbors <id> --depth 2 做 多跳关联，回答「这张表牵动哪些下游」这类问题。

这样 agent 用几次小查询就能精确回答问题，而不必吞下整个知识库——这正是 OKF 相比「一坨文档」的价值：它是一张可导航的图。

OKF v0.1 规范速查

项 规则
概念 一个非保留 .md = 一个概念；路径去 .md = Concept ID
必填字段 仅 type（非空字符串）
推荐字段 title、description(单句)、resource(URI)、tags(列表)、timestamp(ISO8601)
保留文件名 index.md（无 frontmatter，根可例外）、log.md（变更历史）
链接 标准 markdown；推荐 / 开头绝对路径；断链合法
conformance ①每个概念有可解析 frontmatter ②有非空 type ③保留文件名结构正确
宽松原则 不因缺可选字段/未知 type/未知 key/断链/缺 index.md 而判失败

零幻觉边界（重要）

富化能做：

  • 基于真实内容写摘要、单句描述、tags
  • 把散文整理成结构化 body（场景/步骤/字段表）
  • 推断合理的关系，并明确标注为「推断」

富化绝不能做：

  • 编造不存在的表、列、字段类型、API 参数
  • 把仅凭字段名的猜测写成「确定」关系
  • 给文章添加原文没有的外部事实

--no-enrich 提供完全忠实的降级路径：只把已有信息按 OKF 格式重排，不补任何推断内容。 当数据准确性优先于丰富度时使用它。

不做的事

  • 不实现官方的静态 HTML 可视化器（超出本 skill 范畴）。
  • 不集成 Google Knowledge Catalog 云服务（保持 format-not-platform）。
  • 数据库只读 schema，绝不执行写操作。