inkeep/open-knowledge

OpenKnowledge — 代理指南

OpenKnowledge (OK) 是一個通過 MCP 公開的 Markdown-CRDT 協作平台。此技能是 OK 代理指南的單一來源。除非另有標記，否則每一條規則都是「必須」遵守的。深度內容位於 references/*.md 中，深度為一層；當相關任務出現時，請載入對應的參考文件。

技能版本追蹤 @inkeep/open-knowledge-server。執行 cat ~/.ok/skill-state.yml 可以查看已安裝的內容。ok seed 需要 @inkeep/open-knowledge >= 0.4.0；如果它報錯 unknown command，請執行 npm install -g @inkeep/open-knowledge。

設定（尚未連接？）。 如果你在客戶端中沒有看到 mcp__open-knowledge__* 工具，則表示此專案尚未在該機器上配置好 — 請參閱 references/setup.md 了解階梯式設置（批准 .mcp.json → ok start CLI → 可選的桌面應用程式）以及標準的快速入門指南。

TL;DR — 90% 的使用場景

1. 讀取： 對於單一文件使用 exec("cat …")，對於目錄使用 exec("ls -A …")（資料夾預設值 + 模板選單），對於文字內容使用 exec("grep …")，對於排序檢索則使用 search。僅對原始碼（.ts / .py / …）使用原生的 Read / Grep，絕不對範圍內的 .md / .mdx 文件使用。
2. 寫入： 使用 write({ document: { path, content } }) 來新增或完全取代文件；使用 edit({ document: { path, find, replace } }) 來進行內文查找/取代；使用 edit({ document: { path, frontmatter } }) 來進行 frontmatter 的合併修補（null 會刪除一個鍵）。delete({ document }) 用於刪除，move({ from, to }) 用於移動/重新命名。內文查找/取代僅作用於內文。每次寫入內容時，都必須傳遞一行 summary（≤80 個字元，面向用戶的結果）。
3. 預覽： 每次讀取/寫入的回應都會攜帶一個僅包含路徑的 previewUrl（格式為 /#/<doc>，不含 host:port）。在會話開始時打開瀏覽器一次。不要使用 preview_screenshot 來確認編輯 — 工具的回應本身就是確認。完整的多主機合約請參閱：references/preview.md。
4. 工作流程指南： workflow({ kind: 'ingest' | 'research' | 'consolidate' | 'discover' }) 會返回一個程序性的指南，而不是資料。當工作符合該層的性質時使用它。
5. 直接提問： 一個純粹的業務問題（「哪些客戶…」、「我們對…做了什麼決定？」）應使用 search / exec 並加上有引用的聊天回答 — 不需要關鍵詞 "research"。僅在資訊具有持久性、跨多個文件且尚未被涵蓋時才進行持久化，並且先提出。請參閱 references/corpus-qa.md。
6. 撰寫或改進技能（「編寫/製作一個技能」、「改進這個技能」、「將其轉換為一個技能」）：停止並調用 open-knowledge-write-skill 技能 — 它負責範圍選擇（專案級 vs 全域級）、SKILL.md 合約、評估和安裝；不要根據這個技能即興發揮。通過 skill 目標進行撰寫（write({ skill })），絕不直接操作原始的 .ok/skills/… 文件。絕不讀取、比較或編輯安裝在 .claude/skills/ · .cursor/skills/ · .codex/skills/ · .opencode/skills/ · .agents/skills/ 下的投影檔案 — install 會生成它們並在下次同步時覆蓋它們；它們不是事實來源。

工具索引 — 19 個工具（路由器；MCP 工具描述中包含了每個工具的完整合約）

• 讀取 — exec（主要工具；唯讀的 cat/ls/grep/find/head/tail/wc/sort/uniq/cut 加上 frontmatter/反向連結/歷史記錄的豐富資訊；單一命令或單一管道，不是 shell）、search（排序的 BM25 + 時效性）、history（文件的版本記錄）、links（kind: backlinks|forward|dead|orphans|hubs|suggest，或使用陣列進行一次性審計）、skills（查找並讀取技能：省略 name 來列出專案級和全域級的所有技能，傳遞 name 來讀取一個技能 — 通過 name+scope 來定位，絕不通過路徑）、config（已解析的配置）、palette（Markdown 原生的撰寫表單 + html preview 啟動器 + 主題標記；palette({ components }) 用於 JSX 架構）、preview_url（按需取得瀏覽器預覽 URL）、share_link（基於 GitHub 的分享 URL；唯讀，若無 GitHub 遠端則報錯）。
• 寫入 — 四個原生的 CRUD 動詞，對 document / folder / template / skill / asset 具有多型性（請傳遞恰好一個目標，並嵌套在其位址鍵下）：write（建立/覆寫；write({ skill: { name, description, body, scope? } }) 用於撰寫一個技能 → 放到 .ok/skills/<name>/SKILL.md，在 install 之前處於草稿狀態）、edit（內文查找/取代 或 frontmatter 合併修補；不適用於資產）、delete（刪除）、move（移動/重新命名，並重寫引用者；對於技能，還可以使用 scope/toScope 在專案級與全域級之間移動 — 歷史記錄會重置，需要重新 install）。輸出反映了輸入的目標鍵；預覽信封（previewUrl、warning）保持在頂層。另外還有 install（技能的「草稿 → 已安裝」步驟 — 將其投影到你的編輯器中；在執行 write({ skill }) 後運行）、checkpoint（命名版本）和 restore_version（回滾）。資料夾的 frontmatter 是開放形狀的，且僅作用於自身（不會級聯）；模板是新文件的起始內容。撰寫/改進一個技能？調用 open-knowledge-write-skill（TL;DR #6），不要即興發揮。
• 衝突 — conflicts（kind: list|content）、resolve_conflict（寫入一個解決方案並提交；具破壞性）。請參閱 references/conflict-resolution.md。
• 工作流程 — workflow（kind: ingest|research|consolidate|discover；程序性指南，非資料）。請參閱 references/workflow-guides.md。

錯誤使用時的自動修正： 對於 JSON Schema 無法表達的約束（「恰好一個目標」、「find 需要 replace」、內文 XOR frontmatter），工具會返回 isError: true 並提供一行修正提示。請閱讀該提示並按照該形狀重試，不要猜測。

不屬於 OK MCP 的工具（你的主機工具）： preview_start、preview_screenshot、WebFetch、WebSearch、原生 Read / Grep / Glob / Edit。STOP 規則規定了你可以在範圍內的 Markdown 上使用哪些工具。

STOP — 對範圍內的 .md / .mdx 使用原生工具

將所有範圍內的 Markdown 讀取和寫入操作都路由到 OK 的 MCP 工具 — 絕不使用主機的原生文件工具。 在範圍內的 Markdown 上使用原生的 Edit / sed / 直接的 Write 會繞過 CRDT，並在影子儲存庫中失去代理歸屬；原生的讀取操作會跳過 OK 為每個匹配文件提供的 frontmatter、反向連結、影子儲存庫活動和專案 git 歷史記錄。當此工作區配置了 OpenKnowledge MCP 時，不要對內容目錄內的 Markdown 路徑使用原生文件工具。此禁令涵蓋了所有常見的合理化行為：

• 對範圍內的 .md / .mdx 使用原生 Read / Grep / Glob — 原始情況。
• 對包含範圍內 Markdown 的目錄使用 Bash ls / Bash find / Bash cat — 改用 exec("ls -A …") / exec("find … -name '*.md'") / exec("cat …")。原生工具返回裸名；exec 返回 frontmatter、反向連結計數和近期活動。-A 會顯示隱藏條目（.ok/、.okignore），而沒有 ./.. 的干擾。
• 針對 Markdown 的 Glob 模式（**/*.md、specs/**、reports/**、docs/**）— 使用 exec 配合 find 或 exec("ls -A <dir>")。
• 調度探索/通用子代理來進行大量 Markdown 的探索 — 子代理在內部使用原生工具並繞過 OK。請自行通過 exec / search 進行 Markdown 探索。子代理仍然適用於原始碼的探索。
• 對 .ok/ 內範圍內的 Markdown 使用原生 Read / Grep — .ok/ 在範圍內；將其 .md / .mdx 視為任何其他 KB 文件。
• 使用 ls / cat / find 操作 .ok/skills/ 來發現或讀取一個技能 — .ok/skills/ 是不透明的內部狀態；技能是通過 name+scope 來定位的，而不是通過路徑。請使用 skills 工具（省略 name 來列出專案級和全域級的所有技能，傳遞 name 來讀取一個）；絕不瀏覽 .ok/skills/... 路徑。

MCP 工具的可見性 — 看不到 exec 不是逃脫通道。 MCP 的連接方式因客戶端而異（Claude Code、Cursor、Codex、Windsurf、VS Code）。伺服器標籤是由用戶定義的；工具可能不會以名為 exec 的頂層符號出現。如果 OpenKnowledge 在此處註冊為 MCP 伺服器，請通過你客戶端記錄在案的 MCP 調用方式（包括任何通用的「調用 MCP 工具」流程）將 Markdown 讀取路由到其 exec / search。註冊與否是測試標準，而不是頂層符號的可見性。

你初始的工具列表並非詳盡無遺 — 在得出 MCP 缺失的結論之前，請先運行工具發現。 某些客戶端（尤其是 Codex）會將 MCP 工具延遲到惰性的 tool_search / 工具發現步驟之後，因此 mcp__open-knowledge__* 在初始工具集中是缺席的，只有在你搜尋後才會出現。在可見列表中缺席意味著「我還沒有發現它」，而不是「它沒有被註冊」。如果你沒有看到這些工具，你的第一步是運行你客戶端的工具發現 / 為 open-knowledge（或 exec / search / write）執行 tool_search — 不要從初始列表推斷其不可用。

逃脫通道。 僅在以下情況下才允許對 .md / .mdx 使用原生 Read / Grep / Glob：在運行上述工具發現之後，確認此專案沒有註冊任何 OpenKnowledge MCP 伺服器；或者，在你實際調用了一個 MCP 呼叫且該呼叫失敗之後 — 然後以一句用戶可見的 OpenKnowledge MCP unavailable: 開頭。「未註冊」是一個你只能在工具發現返回空結果後才能得出的結論 — 絕不能僅從初始工具列表就得出此結論。切勿因為跳過了客戶端的 MCP 路徑、沒有看到 exec 作為頂層工具、沒有運行工具發現，或者認為這個技能不是必要的，就使用此逃脫通道。

原始碼和非 Markdown 文件（.ts、.py、package.json，……）：始終使用原生 Read / Grep / Glob。

讀取 — 範例

• 讀取一個文件：exec("cat <path>.md") — 內容 + 完整的豐富資訊。
• 列出一個目錄：exec("ls -A <dir>") — 每個子項的 frontmatter、遞迴的 Markdown 計數、每個子目錄中最近更新的文件、該資料夾自身的 title/description/tags 以及 templates_available。優先使用 -A 而不是普通的 ls。
• 文字搜尋：exec("grep -rn <term> <dir> | head -5") — 匹配結果 + 匹配文件的豐富資訊。
• 排序搜尋：search({ query }) — 標題提升 + 內文 BM25 + 時效性；在選擇最佳文件時使用，而不是在列出每個出現位置時使用。

寫入

在你準備好內容後立即調用 write / edit（根據 STOP 規則，通過 MCP 路由）。

逐步持久化 — 知識庫本身就是你的檢查點（必須遵守）。 在任何多步驟或長時間運行的任務中 — 一次研究掃描、一次多源綜合、一批文件 — 在完成每個單元時（每個章節、每個來源、每個文件）立即將完成的工作寫入知識庫。切勿將已完成的發現僅保存在你的上下文中，等待最後一次統一寫入。速率限制、崩潰或上下文壓縮可能會丟棄所有尚未寫入的內容；已經持久化的工作會保留下來，你可以通過重新讀取文件來繼續。提前建立目標文件（骨架 + frontmatter），然後在每個章節確定後使用 edit 將其寫入。

在每次寫入內容時都傳遞一個 summary（應該遵守） — 一行（≤80 個字元）面向用戶的更改說明，它將成為時間軸條目。追求視覺結構（Callout、mermaid、表格、html preview），在其比文字更能表達觀點的地方使用；在草稿撰寫時調用 palette。關於寫入警告、MDX 撰寫、刪除/移動機制和視覺撰寫的建議：references/writing.md + references/components-and-visuals.md + references/media-and-assets.md。

引用依據 — 每個事實性主張都需要一個來源（必須遵守）

知識庫文件是事實性的人工製品。每個主張都必須是可追溯的，並且來源必須存在於知識庫內部，而不是漂浮在公共網路上。

• 知識庫是事實來源 — 封閉循環。 外部來源不會被引用到公開的網路上；它們會通過 ingest 被拉取進來，然後在本地被引用。一個裸的 [source](https://...) URL 放在 KB 文件內部不是一個完成的引用 — 它是一個待辦事項，表明「這個來源仍然需要被匯入」。只有當每一個葉子都是一個本地文件時，這個引用鏈才算完整。
• 每個事實性主張都必須在主張點引用其來源。 不要進行無來源的推測。
• KB 文件的網路來源 → 獲取頁面內容（主機的 WebFetch / WebSearch），然後將其 ingest 為一個本地文件，然後引用本地路徑：[source name](./path/to/source.md)（本地文件在其 source_url: 中承載了 URL）。行內 [source](URL) 是一種聊天便利措施，而非 KB 的標準做法。
• 自行獲取的也算。 當你為了支持一個將要寫入 KB 的主張而獲取了一個 URL 時，這次獲取會像用戶分享一樣觸發 ingest — 不要因為這次獲取是由代理發起的就將其降級為行內 URL 引用。
• 內部交叉引用 → 使用標準的 Markdown 連結指向包含權威主張的 OK 文件；該文件必須引用其自身的來源（引用鏈終止於被保存的本地文件）。
• 如果你沒有證據： 執行網路搜尋並 ingest 它，或者標記行內 (TODO: needs source)，或者不寫這個主張。不要捏造。 未經來源的推測會腐化為無法追溯的部落知識。

連結 — 標準的 Markdown 連結（必須遵守）

對每個命名了另一個文件的名詞短語都加上連結 — [text](./relative/path.md) — 並且要慷慨地連結。每個連結都必須解析到一個在你完成時存在的文件（在同一輪工作中，你稍後建立的向前引用是可以的；對於一個確實不會存在的文件，將其提及保留為純文字並加上一個追蹤任務）。永遠不要用反引號包圍連結（`[text](./foo.md)` 是一個錯誤）也永遠不要使用 HTML <a>。在每次 write/edit 的回應中讀取 brokenLinks： [] 表示所有連結都可解析；一個非空的列表會指出每個損壞的 href + reason（no-such-doc / no-such-file / unresolvable）— 在後續的 edit 中修復它們。links({ kind: "dead" }) 是權威的最終狀態審計（編輯器的紅色底線對 slug 是寬容的，並且會說謊，所以要信任這個工具）。外部網路來源不是行內主體連結（請參閱「引用依據」）。完整的規則集加上 [[Page]] 遺留註記：references/linking.md。

資料夾、Frontmatter、模板

每個 .md / .mdx 都需要 YAML frontmatter — title + description 是必需的，tags 是建議的。有兩個可選的、巢狀的資料夾機制：資料夾 frontmatter（<folder>/.ok/frontmatter.yml — 資料夾自身的開放形狀屬性；僅作用於自身，不會級聯）和模板（<folder>/.ok/templates/ — 新增文件時的起始範本）。系統資料夾（.ok/）是隱藏的，且管理著索引、影子儲存庫和技能。請勿自行修改。

錯誤處理

所有工具在收到無效請求時都應該返回清晰的錯誤訊息。如果錯誤訊息不明確，請嘗試不同的參數組合。對於預期的約束違反，工具會返回 isError: true 並提供修正形狀。