OpenLore

將 OpenLore 指向一個 Markdown 資料夾，無論是 Claude Code、Codex、Cursor 還是 CI 任務，你團隊中的每個代理都能讀取相同的檔案。代理使用他們已經熟悉的工具，例如 cat、grep 和 find。由你決定誰能查看和修改什麼。

_{一鍵託管伺服器。請參閱 將 OpenLore 部署到 Render。}

快速開始

安裝並提供資料夾服務：

brew install --cask aakarim/tap/lore
openlore ./docs

SSH 執行於連接埠 2222。網頁檢視和 MCP 共用連接埠 8080。./docs 的內容會顯示在 /。

連接代理：

# Claude Code
claude mcp add --transport http openlore http://localhost:8080/mcp

# Codex
codex mcp add openlore --url http://localhost:8080/mcp

# Anything with a shell
ssh -p 2222 localhost "grep -r 'retry' /"

告訴你的代理何時使用它：

ssh -p 2222 localhost agents >> AGENTS.md

或者讓你的代理完成整個設定：

ssh openlore.sh teach | claude

沒有 Homebrew？請參閱 快速開始 了解 Linux 和 Windows 的說明。

為什麼不直接把 Markdown 放在你的儲存庫中？

對於單一儲存庫中的單一代理，這樣做即可。

OpenLore 適用於多個代理、儲存庫或人員需要相同知識，且你需要指定誰可以讀取、寫入或發布什麼內容的情況。更新一次檔案，每個代理在下一次讀取時就會看到新版本。

沒有向量資料庫、攝取管道或 SDK。你的知識保持為普通的 Markdown。

指南

• 什麼是 OpenLore
• Claude Code
• Codex
• Cursor
• OpenCode
• 透過 SSH 使用任何代理
• 讓代理發布到收件匣
• 部署到 Render
• 所有文件

功能

• 代理原生檢索 — 代理使用他們已經理解的 shell 工具和組合模式，而不是學習專用的檢索 API。
• 單一知識表面，多種傳輸方式 — 透過 SSH、SFTP/SSHFS（包括直接 VS Code 瀏覽和編輯）、MCP 以及人性化的網頁檢視，提供相同的虛擬檔案系統。
• 即時、受治理的知識 — 保持內容唯讀、允許範圍限定的發布，或為每個文件集啟用完整寫入。寫入是原子的、具衝突感知的，並在提交前經過驗證。
• 身分範圍檢視 — 只給每個人或代理它需要的文件集，並提供基於角色的 ro、publish 和 rw 授權、路徑別名和私人主目錄。
• 本質安全 — shell 是記憶體中的 Go 直譯器，不是真實的作業系統 shell。在正常會話中沒有 shell 逃逸、任意程序執行或環境網路存取。
• 可攜式知識套件 — 將文件嵌入自包含的二進位檔，使用 GitHub Action 建立跨平台套件，或將其打包為桌面 MCP 擴充功能。
• 無需新查詢語言的結構化知識 — 使用 lore meta 將 frontmatter 檢查為 NDJSON，使用 jq 查詢它，並在接近寫入路徑處驗證 Google 的 Open Knowledge Format (OKF) 套件和 Agent Skills。
• 可擴充的政策和處理 — 外掛程式可以新增驗證、授權、讀寫中介軟體、元資料和提交後處理，同時保留相同的檔案系統介面。

使用案例

• 持續學習儲存庫 - 在一個共享伺服器中儲存會話和學習內容。新增指標以便最佳化。允許代理在維持使用者隔離的同時互相分享學習內容。
• 團隊工件儲存庫 - 分享你建立的 Markdown、HTML、JSON、Excel 等文件，同時維持存取控制。比 git 更自然，比 Confluence/Notion 更貼近代理原生。
• 編碼代理的文件 — 將內部 API 文件、操作手冊、產品脈絡和架構筆記放在熟悉的、可 grep 的介面後面。
• 代理團隊的共享即時記憶 — 給代理分開或共享的文件集，以便他們發布發現、交接工作，並在會話之間累積持久脈絡。
• 公開文件網站 - 將任何檔案加入你的公開文件集，啟用公開存取，任何造訪你網站的代理都會看到它。無需編輯現有文件即可改善 AEO/GEO。
• 技能分享 — 將 Agent Skills 發布到共享集合中，讓每個授權代理都能發現並使用相同的受治理程序。
• 代理外掛程式儲存庫 — 從 GitHub 固定版本 Agent Plugins 儲存庫，並提供給你團隊的代理。以開放標準打包的技能會自動保持最新。
• 受治理的知識貢獻 — 讓貢獻者發布到收件匣，同時保留現有文件給維護者，並防止意外覆寫。
• 工件儲存庫 — 透過瀏覽器或 SSH 儲存和公開報告、日誌、螢幕截圖和產生的檔案，無需建立自訂工件檢視器或授予代理機器存取權。
• 身分特定工作區 — 為每個代理掛載私人主目錄，加上共享的團隊知識，全部透過一個伺服器和一個授權模型。
• 可攜式客戶或專案知識 — 發布內嵌相關文件的版本化可執行檔，或將相同的知識作為 MCPB 桌面擴充功能分發。
• 經驗證的知識目錄 — 強制執行 frontmatter 和套件慣例，廉價地檢查元資料，並在接收時阻止格式錯誤的知識。

運作方式

OpenLore 建構於 Wish 之上，用於 SSH 傳輸。連線完全針對虛擬檔案系統處理：

1. 驗證 — 無金鑰連線，或將 SSH 金鑰、憑證、通行金鑰或 OAuth 登入解析為身分。
2. 組合檢視 — 只掛載授予該身分的文件集和路徑。
3. 探索 — 在該檢視上執行以純 Go 函式實作的 shell 命令，或使用等效的 MCP shell 工具。
4. 安全貢獻 — 如果啟用寫入，在原子提交之前授權並驗證整個檔案的變更。

OAuth 用戶端使用委派身分，因此持久的寫入來源區分了 adil 的直接工作和以 adil/claude@claude.ai 執行的工作。委派者繼承的權限不會超過其委託人，並且可以透過文件集和功能拒絕清單來縮小範圍。CIMD 用戶端還可以透過供應商託管的元資料和 private_key_jwt 進行驗證；請參閱 已驗證的 OAuth 用戶端。

一般 shell 無法呼叫 bash、exec、curl 或任意主機程序。內嵌文件永遠是唯讀的。明確受信任的身分可以透過 spawn 功能獲得範圍狹窄的非同步處理授權。

受治理的寫入

OpenLore 預設為唯讀。可寫入的部署保持單一、受政策控制的寫入路徑，用於重新導向、附加、tee、patch、sed -i、檔案移動、發布和受信任的外部任務。

echo "# Research" | publish /backend/findings.md
cat change.diff | patch /backend/api.md
sed -i 's/old/new/g' /backend/runbook.md

寫入是整個物件的原子交換。比較並交換保護預設拒絕過時的編輯，文件集授權限制了目標，外掛程式可以在提交前驗證或延遲寫入。

請參閱 寫入和發布 了解使用者面向的設定，以及 寫入系統內部 了解實作模型。

安裝

請參閱 快速開始 了解 Homebrew、Linux 和 Windows 版本，以及哪些安裝包含儀表板。要自行建置 OpenLore，請參閱 從原始碼建置。

在二進位檔中嵌入文件

將文件放在 assets/lore/ 並建置。產生的二進位檔包含文件，並在沒有目錄參數執行時，以唯讀方式在 /docs 提供服務：

make dashboard-build   # optional: include the web UI
go build -o my-docs ./cmd/openlore

使用 GitHub Action 建置

產生內嵌文件的跨平台二進位檔：

- uses: aakarim/openlore@v1
  with:
    docs-dir: ./docs
    config: ./openlore.yml

請參閱 使用 OpenLore 的方式 了解直接 VS Code 編輯、MCP stdio、MCPB 桌面打包、SSHFS 和 Go 函式庫用法。

建立自訂部署

使用隨附的 setup 技能建立 <team>-lore，這是一個小型客戶擁有的儲存庫，包含 openlore.yml、一個固定到官方 OpenLore 版本的輕量 Containerfile，以及部署工件。它會建置一個可運作的本地伺服器，並在部署前驗證 HTTP、MCP、已驗證的 SSH、寫入和持久性：

ssh openlore.sh setup | amp

產生的儲存庫將初始的 lore.json 政策和 SSH 可見檔案保留在 gitignored 的 .local/ 下。第一次部署會從該狀態初始化一個空的持久磁碟區。根 openlore.yml 仍然是 Git/IaC 的權威來源，並單獨部署到 /var/lib/openlore/config/openlore.yml；它不會被烘焙到映像檔中。之後在伺服器上的 lore.json 和檔案系統編輯是權威的，永遠不會被映像檔更新覆寫。

其他指令命令支援完整的生命週期：

• onboarding 在本地新增初始身分、角色、主目錄和資料夾；
• deploy 選擇 Fly.io、Railway、AWS、Google Cloud、Azure、DigitalOcean 或自訂部署，並驗證共享的持久性/網路契約；
• upgrade 只準備固定的基礎映像檔版本變更，以便現有的 CD 可以部署它。

供應商部署需要 HTTPS/MCP、已驗證的 OpenLore SSH、管理 shell 存取和持久的 /var/lib/openlore 磁碟區。在供應商支援的情況下，部署會設定公開連接埠 22 轉送到 OpenLore 連接埠 2222。否則，它會回報指定的連接埠，並建議外部 TCP 轉送系統。

發布的容器只包含 OpenLore。它刻意不包含入門政策或伺服器設定。在服務啟動之前，部署必須將 openlore.yml 和 lore.json 放入持久的設定目錄，並執行：

./out --config /var/lib/openlore/config/openlore.yml

這使得設定可以獨立部署：簡單的部署可以將 openlore.yml 複製到磁碟區，而 Kubernetes 可以從 ConfigMap 投射相同的檔案。使用 deploy 技能來處理 Fly.io、Railway、AWS、Google Cloud、Azure、DigitalOcean 或自訂基礎設施。儲存庫的 Railpack 和 Fly 檔案提供映像檔、持久磁碟區和連接埠接線；它們不會在程序啟動時植入或變更設定。

對於不需要自訂儲存庫的快速託管伺服器，請使用 部署到 Render 按鈕。與 Railpack 和 Fly 檔案不同，它的啟動指令碼會在首次啟動時將一個入門的 openlore.yml 和 lore.json 寫入空磁碟。Render 只提供 HTTPS、MCP 和網頁檢視；它沒有用於 OpenLore SSH 的公開 TCP 入口。

Railway 為其 SSH TCP 代理指派一個公開主機名稱和連接埠。標準 SSH 連接埠 22 需要外部原始 TCP 負載平衡器。Fly.io 可以將公開連接埠 22 對應到 OpenLore 的內部連接埠 2222，並使用專用位址。原始 SSH 沒有主機名稱或 SNI 路由，因此一個監聽器無法在連接埠 22 上路由多個網域。

容器工作流程從 main 發布 latest；版本也發布 VERSION、vVERSION、主要和次要映像檔標籤。

文件

相同的頁面，以相同的分組，發布在 openlore.sh/docs。

簡介

頁面	內容
什麼是 OpenLore	在一頁中提供服務、連接、範圍、治理和觀察
變更日誌	目前版本、版本說明、相容性說明和版本化文件

開始

頁面	內容
快速入門	安裝 OpenLore、提供資料夾服務，並連接代理程式
Claude Code	透過 MCP 連接 Claude Code，並設定其可檢視的範圍
Codex	透過 MCP 連接 Codex
Cursor	透過 MCP 連接 Cursor
OpenCode	透過 MCP 連接 OpenCode
透過 SSH 連接任何代理程式	透過 SSH 連接編碼代理程式或 CI 任務，並賦予其身分

概念

OpenLore 的運作方式：文件集、傳輸、身分、寫入、規則與觀測。

頁面	內容
文件集	什麼是文件集、為何存取圍繞其組織，以及巢狀、授權、別名與失敗關閉驗證的運作方式
傳輸	SSH、SFTP、MCP、JSON API 與網頁如何共享單一檔案系統、MCP 工具、命令結果、工作階段與指令命令
驗證	驗證姿態、SSH 金鑰、憑證、通行金鑰、OAuth 權杖與收件匣憑證如何解析為身分、角色、文件集、別名、家目錄與工作負載身分聯盟
寫入與發布	寫入模式、收件匣、衝突處理、成功寫入檢查與不檢查的內容，以及任務
資料夾規則	.lore/config.yaml 與 lore.json 規則、分層、權限、拒絕訊息與成長限制
外掛程式與格式	提供者介面、開放知識格式驗證、lore validate、lore meta 與 Agent Skills 外掛程式
儀表板與指標	儀表板驗證、事實與活動的區別，以及檔案檢視器

操作指南

任務逐步解說。

頁面	內容
使用 OpenLore 的方式	設定 SSH、透過 HTTP 與 stdio 的 MCP、網頁檢視、SSHFS、嵌入式二進位檔、GitHub Action、MCPB 與程式庫使用
設定伺服器	建立 openlore.yml、相對於嵌入式設定與旗標的優先順序、分析與除錯記錄
讓代理程式發布至收件匣	接受代理程式的貢獻，而不讓其編輯其他內容
從編輯器瀏覽與編輯	直接設定 VS Code 與 SFTP 編輯器，無需本機專案鏡像
執行 headlong / shellm	從 headlong 的 shellm 引擎透過 SSH 使用 OpenLore，包括其維護技能
從原始碼建置	自行建置網頁 UI 與二進位檔，或在不含網頁 UI 的情況下建置
將 OpenLore 部署至 Render	一鍵 Render 部署、首次通行金鑰登入、升級與自訂網域

參考資料

查詢資料：命令、金鑰、端點、介面與內部機制。

頁面	內容
命令參考	完整的 shell、內省、發布、語法、CLI 命令與旗標參考
openlore.yml 參考	針對 openlore.yml 接受的每個金鑰所產生的參考
規則標準程式庫	針對編譯內建規則成員及其參數所產生的參考
HTTP 收件匣 API	使用 bearer 或 HMAC 憑證的 POST /inbox/{docset}，以及權杖端點
OAuth 用戶端	CIMD 用戶端身分、private_key_jwt、mTLS 佐證與簽章金鑰輪換
寫入系統內部機制	檔案系統分層、寫入接縫、准入中介軟體與非同步任務
建置儀表板	前端建置與僅後端的 Go 建置
安全性評估	威脅模型與安全屬性

安全性

• 命令在純 Go 直譯器中執行，而非透過 os/exec。
• 虛擬檔案系統會清理路徑並強制執行文件集邊界。
• 允許的檔案模式與忽略的目錄可防止機密進入檢視範圍。
• RBAC 控制讀取、發布、寫入、核准與受信任的能力。
• 網頁端點可透過 TLS 發布 SSH 主機金鑰，以避免首次使用時的盲目信任；同時也支援 SSH 使用者與主機憑證。

完整的安全性評估請參閱 SECURITY.md。

授權

Apache License 2.0 — 版權所有 © 2026 Adil Karim

OpenLore 整合了第三方開放原始碼元件。其授權與必要聲明列於 assets/legal/THIRD_PARTY_NOTICES.md，完整授權文字位於 assets/legal/licenses/。這些內容已嵌入二進位檔中，並由執行中的服務在 /legal 提供。