okf-loom — 倉庫本地技能 是做什麼的?
此倉庫即為技能。將其複製下來,載入此 SKILL.md,然後使用下方提到的少量資源檔案和倉庫本地指令碼。無需學習套件發布流程;持久的產物就是這個 git 倉庫的佈局。
預設行為(無需提問即可執行)
以下是任何使用此技能的代理應遵守的常規期望:
-
文件即為 OKF 包。 當使用者要求文件、筆記、知識庫或「把這個寫下來」時,請以 OKF 概念的形式撰寫——每個概念一個 Markdown 檔案,包含完整的 frontmatter(
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 # 本地: http://127.0.0.1:8787/ scripts/okf-loom serve path/to/bundle --no-open --tunnel # + 公開 https URL (需要 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
範例直接使用倉庫內的 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。