Communitygithub.com

okf-loom — 倉庫本地技能

將 Markdown 文件包轉換為驗證過的 OKF 知識圖譜的工具包,包含本地協作工作室、靜態網站輸出和 Agent 友好的 CLI。

okf-loom — 倉庫本地技能 是什麼?

okf-loom 是一個以倉庫為單位的技能,專為使用開放知識格式 (Open Knowledge Format, OKF) 的文件包而設計。它提供一套代理友好的 CLI 命令和引導流程,用於驗證、搜尋、發現、更新、渲染和提供 OKF 文件包的即時協作工作室。使用者可以將此技能載入到支援 SKILL.md 的代理環境中(例如 Claude Code、Cursor 或 Codex),然後直接使用倉庫中的 `scripts/okf-loom` 命令。 此技能的核心特色在於其“無需發布”的設計理念:OKF 文件包和相關指令碼都儲存在同一個 git 倉庫中,無需學習額外的套件發布流程。代理能夠執行引導、驗證、索引、伺服器啟動等操作,從而創建、維護和探索以圖譜為基礎的文件集。當工作室運行時,使用者可以直接在網頁上註釋文字,代理則可以透過 `wait`、`comment-claim` 和 `comment-resolve` 等命令參與協作循環,以非破壞性的方式處理回饋。此外,所有變異操作(`write-concept`、`link-add` 等)都會被記錄、可復原,並即時廣播給所有連線的客戶端。 支援的平台包括任何能讀取 SKILL.md 的代理工具(如 Claude Code、Cursor、Codex 等),以及標準的終端環境。該技能強調透過內建驗證和發現命令來維持文件品質,並使用標記安全 (marker-safe) 的索引機制以避免覆蓋人工編寫的內容。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

okf-loom — 倉庫本地技能 是做什麼的?

此倉庫即為技能。將其複製下來,載入此 SKILL.md,然後使用下方提到的少量資源檔案和倉庫本地指令碼。無需學習套件發布流程;持久的產物就是這個 git 倉庫的佈局。

預設行為(無需提問即可執行)

以下是任何使用此技能的代理應遵守的常規期望:

  1. 文件即為 OKF 包。 當使用者要求文件、筆記、知識庫或「把這個寫下來」時,請以 OKF 概念的形式撰寫——每個概念一個 Markdown 檔案,包含完整的 frontmatter(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          # 本地:  http://127.0.0.1:8787/
    scripts/okf-loom serve path/to/bundle --no-open --tunnel # + 公開 https URL (需要 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

範例直接使用倉庫內的 helper 腳本,而非本地 shell 包裝或已安裝的控制台指令。

何時讀取什麼

時機閱讀內容
始終優先閱讀(60 秒入門 + 預設路徑)resources/overview.md
首次寫入任何包之前resources/gotchas.md
執行任何 CLI 動詞 / 不確定某個旗標resources/command-reference.md
手動編寫或編輯概念檔案resources/format-basics.md 然後 resources/authoring.md
決定「良好」的 frontmatter 是什麼樣子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/               # 對代理友好的小型指導檔案
├── scripts/
│   ├── okf-loom              # 已納入倉庫的 helper 命令
│   ├── 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 的代理使用的簡短指標
└── CLAUDE.md                # 供會先讀取 CLAUDE 的代理使用的簡短指標

核心命令

# 驗證一個包。
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 "我將要做的事"
scripts/okf-loom comment-resolve path/to/bundle <comment-id> --summary "我已完成的事"

不可協商的事項

  • 使用 scripts/okf-loom;不要假設已安裝的套件或控制台腳本。
  • 如果有 PyYAML 則優先使用,但內建的回退方案足以應付一般的執行時期/文件驗證,並在不支援進階 YAML 時安全地關閉。
  • 不要將 PyPI/套件發布流程作為主要路徑加回來。
  • 保留未知的 frontmatter 鍵和人工編寫的包內容。
  • 在 OKF v0.1 下,type 是唯一強制要求的概念 frontmatter 鍵。
  • 對於消費者來說,失效連結預設為警告;除非明確使用 --allow-forward-reference,否則編寫變異器在目標缺失時會關閉失敗。
  • 所有 okf-loom 的寫入必須保持原子性且標記安全。

如需更深入的規則,請閱讀 resources/gotchas.md。

相關技能