OpenLore

📜 OpenLore

由 贊助

透過 SSH 將你的文件提供給 AI 代理程式。

OpenLore 是一個極簡、可擴充、以代理程式為中心的知识库，讓共享的上下文保持最新且可檢視。

---

關於

AI 編碼代理程式已經知道如何使用 ls、cat、grep、 find、管道和 shell 迴圈來探索檔案。OpenLore 透過 SSH 為它們提供相同的介面， 背後由你的文件而非真實機器支援。

Agent ──SSH or MCP──▶ OpenLore ──▶ docs, knowledge, and artifacts

它一開始是單一二進位檔、零設定、唯讀的文件伺服器。當你需要即時知识库時， 可以加入以身份為範圍的存取控制、受控發布、原子寫入、驗證和人工核准， 而不需要改變代理程式讀取或瀏覽內容的方式。

儲存與擷取 Markdown

將文件、操作手冊、專案上下文或代理程式撰寫的筆記放在一般 Markdown 檔案中。 沒有擷取管線：將 OpenLore 指向一個目錄，它就會直接提供現有的階層結構。 使用資料夾組織文件，用標準 Markdown 連結連接它們，並在需要不同人員或代理程式 擁有不同存取權限時，將它們分組為文件集。OpenLore 預設為唯讀；當你希望代理程式 也能建立和更新 Markdown 時，再啟用寫入功能。

快速開始

最快的方式是讓你的代理程式設定 OpenLore：

# Teach your agent how to install, configure, and bundle OpenLore
ssh openlore.sh teach | your-agent-cli

# Add documentation access instructions to AGENTS.md
ssh openlore.sh agents >> AGENTS.md

或直接安裝並執行：

go install github.com/aakarim/go-openlore/cmd/openlore@latest

openlore ./docs

ssh -p 2222 localhost
ssh -p 2222 localhost "grep -r 'authentication' /docs"

預設情況下，這會啟動：

• 在 localhost:2222 上的 SSH
• 在 http://localhost:8080 上的人員導向網頁檢視
• 在 http://localhost:8080/mcp 上的 MCP over HTTP

請參閱 安裝 以了解安裝和封裝 OpenLore 的更多方式。

功能

• 代理程式原生擷取 — 代理程式使用它們已經熟悉的 shell 工具和組合模式， 而不是學習專屬的擷取 API。
• 單一知識表面，多種傳輸方式 — 透過 SSH、SFTP/SSHFS、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 文件、操作手冊、產品上下文和架構筆記 放在熟悉的、可搜尋的介面後面。
• 代理程式團隊的共享即時記憶 — 給代理程式獨立或共享的文件集，讓它們可以 發布發現、交接工作，並在跨工作階段累積持久上下文。
• 公開文件網站 — 將任何檔案加入你的公開文件集、啟用公開存取，任何碰到你 網站的代理程式都會看到它。無需編輯現有文件即可改善 AEO/GEO。
• 技能分享 — 將 Agent Skills 發布到共享集合中，讓每個授權的代理程式都能 發現並使用相同的受治理程序。
• 代理程式外掛程式儲存庫 — 從 GitHub 固定版本 Agent Plugins 儲存庫，並將它們提供給你團隊的代理程式。以開放標準封裝的技能會自動保持最新。
• 受治理的知識貢獻 — 讓貢獻者發布到收件匣，同時為核准者保留敏感路徑， 並防止意外覆寫。
• 代理程式工件的遠端檢閱 — 透過瀏覽器或 SSH 公開報告、日誌、螢幕截圖和 產生的檔案，而不需要建立自訂工件檢視器或授予代理程式機器的存取權。
• 身份專屬工作區 — 為每個代理程式掛載私有家目錄，加上共享的團隊知識， 全部透過一個伺服器和一個授權模型。
• 可攜式客戶或專案知識 — 出貨帶有相關文件嵌入的版本化可執行檔，或將相同 知識作為 MCPB 桌面擴充功能發布。
• 經驗證的知識目錄 — 強制執行 frontmatter 和套件慣例、廉價地檢查中繼資料， 並在接收時阻止格式錯誤的知識。

運作方式

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

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

OAuth 用戶端使用委派身份，因此持久的寫入來源區分 adil 的直接工作和 以 adil/claude@claude.ai 執行的工作。委派者繼承的權限不會超過其主體，且可以透過 docset 和功能拒絕清單縮小範圍。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

寫入是整個物件的原子交換。比較並交換保護預設拒絕過時的編輯，docset 授權限制目標， 選定的路徑可以在 /requests 下產生可檢閱的變更集，而不是直接提交。

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

安裝

使用 Go 安裝

需要 Go 1.26 或更新版本：

go install github.com/aakarim/go-openlore/cmd/openlore@latest

從原始碼建置

git clone https://github.com/aakarim/go-openlore.git
cd go-openlore
go build -o openlore ./cmd/openlore

在二進位檔中嵌入文件

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

go build -o my-docs ./cmd/openlore

使用 GitHub Action 建置

產生帶有嵌入文件的跨平台二進位檔：

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

請參閱 使用 OpenLore 的方式 以了解 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 檔案提供映像檔、持久磁碟區和連接埠接線；它們不會在 程序啟動時植入或變更設定。

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

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

HTTP 收件匣上傳

設定一個 docset inbox 和一個具有其 publish 授權的角色，然後為 現有身份建立憑證（伺服器設定必須指定 auth_file，以便 CLI 可以驗證它）：

openlore inbox token create --identity alice --label webhook --config openlore.yml
curl -H 'Authorization: Bearer olin_ID_SECRET' -H 'Content-Type: text/markdown' \
  --data-binary @note.md 'https://docs.example.com/inbox/docs?name=note.md'

POST /inbox/{docset} 接受 bearer 憑證或使用 X-OpenLore-Token-Id 和 X-OpenLore-Signature 的 精確主體 HMAC。OAuth 存取權杖只用於 POST/GET /inbox/tokens 和 DELETE /inbox/tokens/{id}； 收件匣憑證是分開且可撤銷的。請參閱 設定和身份。

文件

指南	內容
使用 OpenLore 的方式	SSH、MCP、網頁、SSHFS、嵌入式二進位檔、GitHub Action、MCPB 與函式庫使用方式
指令參考	完整的 shell、內省、發布、語法、CLI 指令與旗標參考
設定與身分	openlore.yml、驗證、角色、文件集、別名、家目錄與主機驗證
工作負載身分聯合	使用短期外部身分權杖驗證 CI 與代理程式
撰寫與發布	撰寫模式、收件匣、衝突處理、核准與工作
外掛程式與知識格式	外掛程式安裝、介面、OKF 驗證、lore validate 與 lore meta
撰寫系統內部機制	檔案系統分層、撰寫接縫、變更集、鉤子與非同步工作
安全性評估	威脅模型與安全屬性

安全性

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

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

授權

MIT — Adil Karim

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