OKFy 是做什麼的？
概述
使用 OKFy 將文件網站或本地 Markdown 資料夾轉換為本機的 Open Knowledge Format 知識包，然後透過唯讀的 MCP 伺服器將其提供給代理使用。建議在產生的命令中使用 npx -y okfy-ai，這樣用戶端無需全域安裝即可啟動已發布的套件。
快速參考
| 目標 | 指令或動作 |
|---|---|
| 註冊一個文件網站並列印設定 | npx -y okfy-ai init <名稱> <網址> --client codex --max-pages 100 --max-depth 4 |
| 匯入本地 Markdown | npx -y okfy-ai import ./docs --out ./docs-okf --source-name "專案文件" |
| 為某項任務證明來源 | npx -y okfy-ai activate <名稱或知識包> --client codex --task "<任務>" --out okfy-activation |
| 預覽準備狀態與圖表 | npx -y okfy-ai map <名稱或知識包> --out okfy-inspector.html |
| 診斷設定 | npx -y okfy-ai doctor <名稱> --client codex |
| 提供 MCP 服務 | npx -y okfy-ai serve <名稱或知識包> --mcp --auto-refresh |
設定工作流程
- 選擇一個簡短的來源名稱，例如
stripe、clerk或project-docs。 - 對於文件網站，執行
npx -y okfy-ai init <名稱> <網址> --client codex --max-pages 100 --max-depth 4。 - 對於本地 Markdown，執行
import，然後執行validate，最後提供生成的知識包路徑。僅在使用者明確同意覆蓋輸出目錄時才添加--force。 - 當使用者在設定變更前需要證明時，執行
activate並使用--task參數匹配其真實問題。生成的套件包含okfy-inspector.html、okfy-setup.md和okfy-proof.json。 - 如果設定失敗或 MCP 用戶端無法看到工具，請在手動編輯用戶端設定之前執行
doctor。
MCP 使用
當 OKFy MCP 伺服器可用時，請依序使用以下工具：
bundle_summary檢查驗證狀態、時效性、可用的來源以及工具使用預期。search_concepts使用使用者的任務術語進行搜尋。在已知相關文件來源的多來源工作區中使用source過濾器。read_concept讀取最相關的概念，先保持少量讀取再進行擴展。get_neighbors當答案依賴於關聯概念、反向連結、前置要求或附近的 API/參考頁面時使用。- 引用概念結果中呈現的來源 URL 或資源欄位。
從狹隘的搜尋開始，僅在結果不足時才擴大範圍。在工作區中，當概念 ID 不明確時，請同時傳遞 source 和 id 給 read_concept。
工作區
當任務跨越整個技術棧時，透過一個 MCP 伺服器提供多個已註冊來源的服務：
npx -y okfy-ai serve stripe clerk --mcp --auto-refresh
然後過濾搜尋：
{ "query": "checkout sessions", "source": "stripe", "limit": 5 }
每當使用者提及產品、API、框架或文件來源名稱時，請使用 source 過濾器。如果使用者要求跨整個技術棧查詢，請先在不使用過濾器的情況下搜尋工作區，然後再針對特定來源進行精準讀取。
安全規則
- MCP 工具是唯讀的。自動重新整理是針對已註冊來源的伺服器端維護，而不是代理可呼叫的寫入工具。
- 不要使用
npx okfy；請使用npx -y okfy-ai來執行無需安裝的命令。 - 不要在一般的交談式終端機階段中執行
serve --mcp。MCP 用戶端會將其作為 stdio 子程序啟動。 - 除非使用者明確接受風險，否則不要繞過爬蟲安全預設值、私有網路保護或不安全的
--force防護。 - 當
init、activate或doctor能夠產生或驗證確切的命令/設定時，不要先手動編輯用戶端設定。
常見錯誤
| 錯誤 | 修正方式 |
|---|---|
| 將 OKFy 視為託管索引 | 將工作流程保持在本機：知識包檔案、MCP stdio 和來源 URL 均保持可審查。 |
| 搜尋後閱讀所有概念 | 先閱讀最符合的結果，然後僅在必要時使用鄰近節點進行擴展。 |
| 忽略工作區的來源名稱 | 對多來源知識包使用 source 過濾器和限定來源的讀取。 |
| 跳過證明 | 當使用者需要在連接 MCP 之前獲得信心時，使用 activate --task。 |
| 盲目除錯設定 | 執行 doctor <名稱> --client codex 並遵循其下一步修復命令。 |