okf-loom — 仓库本地技能 是做什么的?
此仓库即为该技能。克隆该仓库,加载此 SKILL.md,然后使用下方引用的小型资源文件和检出本地脚本。无需学习包发布流程;持久化的工件就是这个 Git 仓库布局。
默认行为(无需请求即可执行)
以下是对使用该技能的任何 Agent 的固定期望:
-
文档是 OKF 包。 当用户要求提供文档、笔记、知识库或“写下来”时,请将其撰写为 OKF 概念——每个概念一个 Markdown 文件,包含完整的前置元数据(
type、title、description、tags、timestamp,以及aliases/entities/relations/provenance/citations,只要它们承载了真实信息)。使用scripts/okf-loom bootstrap <dir>启动新包,或添加到现有包中。docs-bundle/demo/showcase.md是一个完整概念的典范示例(打开渲染后的文件即可了解每个键为何必不可少)。 -
写入后验证。 在任何批处理写入后,运行
scripts/okf-loom validate <bundle>并修复发现的问题;定期运行scripts/okf-loom discover <bundle>以捕获缺失的链接/索引/描述。如果index.md文件已过时,scripts/okf-loom index <bundle>会重新生成生成的块(对标记安全——它只重写okf:generated标记之间的内容;没有标记的手写索引散文会被替换,因此请检查git diff)。 -
主动提供服务。 渲染后的 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。 -
运行协作循环。 当工作室运行时,用户的评论就是你的工作:
scripts/okf-loom wait <bundle>会阻塞直到有评论或更改,然后认领 → 编辑 → 解决(comment-claim/ 修改器 /comment-resolve)。在首次循环之前,请阅读resources/studio-agent-loop.md。 -
在工作室会话活动时,优先使用修改器进行内容更改(
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。