Communitygithub.com

okf-loom — 仓库本地技能

将 Markdown 文档包转换为经过验证的 OKF 知识图谱的工具包,附带本地工作室、静态站点输出和面向 Agent 的 CLI。

okf-loom — 仓库本地技能 是什么?

okf-loom 是一个专注于知识图谱构建的技能包,用于将 Markdown 文档包(OKF 概念)转化为经过验证的、可互操作的 OKF(Open Knowledge Fabric)知识图谱。它提供了一个本地协作工作室、静态站点生成能力,以及一组面向 AI Agent 的 CLI 命令。该技能的核心价值在于,它不依赖外部包发布流程,而是以 Git 仓库本身作为可读写的知识图谱载体。Agent 可以使用它进行文档写作、验证、索引、搜索和协作评论处理。支持 PyYAML,但内置了保守的 YAML 回退方案,确保在大多数环境下可直接运行。该技能为 Cursor、Codex 等基于 Agent 的编辑器设计,通过直接执行仓库内的脚本(`scripts/okf-loom`)来工作,无需安装。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add ojamin/okf-loom

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

okf-loom — 仓库本地技能 是做什么的?

此仓库即为该技能。克隆该仓库,加载此 SKILL.md,然后使用下方引用的小型资源文件和检出本地脚本。无需学习包发布流程;持久化的工件就是这个 Git 仓库布局。

默认行为(无需请求即可执行)

以下是对使用该技能的任何 Agent 的固定期望:

  1. 文档是 OKF 包。 当用户要求提供文档、笔记、知识库或“写下来”时,请将其撰写为 OKF 概念——每个概念一个 Markdown 文件,包含完整的前置元数据(type、title、description、tags、timestamp,以及 aliases/entities/relations/provenance/citations,只要它们承载了真实信息)。使用 scripts/okf-loom bootstrap <dir> 启动新包,或添加到现有包中。docs-bundle/demo/showcase.md 是一个完整概念的典范示例(打开渲染后的文件即可了解每个键为何必不可少)。

  2. 写入后验证。 在任何批处理写入后,运行 scripts/okf-loom validate <bundle> 并修复发现的问题;定期运行 scripts/okf-loom discover <bundle> 以捕获缺失的链接/索引/描述。如果 index.md 文件已过时,scripts/okf-loom index <bundle> 会重新生成生成的块(对标记安全——它只重写 okf:generated 标记之间的内容;没有标记的手写索引散文会被替换,因此请检查 git diff)。

  3. 主动提供服务。 渲染后的 Wiki 就是产品,而非调试视图。每当用户想要查看、阅读、审阅或评论文档时——或者当你刚刚构建/更改了一个用户可能会查看的包时——无需等待请求,直接启动工作室并将 URL 交给用户:

    scripts/okf-loom serve path/to/bundle --no-open          # local:  http://127.0.0.1:8787/
    scripts/okf-loom serve path/to/bundle --no-open --tunnel # + public https URL (needs cloudflared)
    

    --tunnel 会打印一个 https://…trycloudflare.com 链接,供不在此机器上的用户使用,并自动将隧道主机添加到工作室的跨域允许列表。告知用户可以通过选中任意文本进行评论;图谱位于 /__graph。

  4. 运行协作循环。 当工作室运行时,用户的评论就是你的工作:scripts/okf-loom wait <bundle> 会阻塞直到有评论或更改,然后认领 → 编辑 → 解决(comment-claim / 修改器 / comment-resolve)。在首次循环之前,请阅读 resources/studio-agent-loop.md。

  5. 在工作室会话活动时,优先使用修改器进行内容更改(write-concept、set-frontmatter、link-add、entity-add、update):它们会进行属性标记、可撤销,并实时广播到打开的标签页。否则直接编辑文件也是可以的——监听器会捕捉到这些更改。

快速开始

在 okf-loom/ 目录内执行:

scripts/okf-loom --help
scripts/okf-loom validate docs-bundle --strict

对于正常的文档验证,不需要安装主运行时。如果系统中存在 PyYAML,则会使用它;否则 okf-loom 会使用其保守的内置 YAML 回退。

从父工作区(检出目录名为 okf-loom/)执行:

okf-loom/scripts/okf-loom validate okf-loom/docs-bundle --strict

示例直接使用检入的辅助程序,而不是本地 shell 包装器或已安装的控制台脚本。

何时阅读什么

时机阅读内容
始终,首先(60 秒定位 + 默认路径)resources/overview.md
首次向任何包写入之前resources/gotchas.md
运行任何 CLI 动词/不确定某个标志时resources/command-reference.md
手动编写或编辑概念文件时resources/format-basics.md 然后 resources/authoring.md
确定“好的”前置元数据样式时docs-bundle/demo/showcase.md — 实操示例
验证运行失败或需要 CI 门控时resources/validation.md
搜索模式、发现、计划、静态构建时resources/advanced-operations.md
工作室已启动且用户正在评论时resources/studio-agent-loop.md
更改 scripts/okf_loom/ 下的运行时resources/architecture-map.md
任何模棱两可的情况——约束合同docs-bundle/reference/spec.md
指向人类用户的最终用户文档docs-bundle/

仓库布局

okf-loom/
├── SKILL.md                 # 此可加载技能入口点
├── resources/               # Agent 可读的小型指导文件
├── scripts/
│   ├── okf-loom              # 检入的辅助命令
│   ├── okf_loom/             # 检出本地运行时包
│   ├── build_skill_archive.py
│   ├── capture_readme_media.py
│   ├── capture_viewer_proof.py
│   ├── capture_signal_controls.py
│   └── lint-js.sh
├── docs-bundle/             # OKF 文档包
├── samples/                 # 示例 OKF 包
├── tests/                   # 检出脚本的 pytest 验证
├── docs/                    # README 媒体(docs/media/)、截图、设计计划
├── README.md                # 人类概览
├── AGENTS.md                # 面向先读取 AGENTS 的 Agent 的轻量指针
└── CLAUDE.md                # 面向先读取 CLAUDE 的 Agent 的轻量指针

核心命令

# 验证一个包。
scripts/okf-loom validate path/to/bundle --strict

# 检查/搜索。
scripts/okf-loom info path/to/bundle
scripts/okf-loom search path/to/bundle "customer order" --mode hybrid

# 提供实时协作工作室(添加 --tunnel 以获取公开链接)。
scripts/okf-loom serve path/to/bundle --no-open

# 发现差距并应用安全的修改。
scripts/okf-loom discover path/to/bundle --out /tmp/okf-suggestions.json
scripts/okf-loom link-add --bundle path/to/bundle --source tables/orders --target tables/customers

# 工作室启动时的协作循环(当前规范第 12 节)。
scripts/okf-loom wait path/to/bundle        # 阻塞直到有评论/更改到达
scripts/okf-loom comment-claim path/to/bundle <comment-id> --summary "what I will do"
scripts/okf-loom comment-resolve path/to/bundle <comment-id> --summary "what I did"

不可协商事项

  • 使用 scripts/okf-loom;不要假设已安装的包或控制台脚本。
  • 如果系统中存在 PyYAML,则首选使用;但捆绑的回退足以满足正常的运行时/文档验证,并在遇到不支持的高级 YAML 时安全地失败关闭。
  • 不要将 PyPI/包发布流程添加为主要路径。
  • 保留未知的前置元数据键和手写的包内容。
  • 在 OKF v0.1 下,type 是唯一硬性要求的概念前置元数据键。
  • 断开的链接默认对消费者来说是警告;除非明确指定 --allow-forward-reference,否则编写修改器在目标缺失时会失败关闭。
  • 所有 okf-loom 的写入操作必须保持原子性和对标记安全。

有关更详细的规则,请阅读 resources/gotchas.md。

相关技能