OpenLore

📜 OpenLore

Được tài trợ bởi

Phục vụ tài liệu của bạn cho các tác nhân AI qua SSH.

OpenLore là một cơ sở tri thức tối giản, có thể mở rộng, hướng đến tác nhân, giúp giữ bối cảnh dùng chung luôn cập nhật và có thể kiểm tra.

---

Giới thiệu

Các tác nhân lập trình AI đã biết cách khám phá tệp bằng ls, cat, grep, find, pipe và vòng lặp shell. OpenLore cung cấp cho chúng giao diện tương tự qua SSH, được hỗ trợ bởi tài liệu của bạn thay vì một máy thật.

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

Nó bắt đầu như một máy chủ tài liệu chỉ đọc, không cấu hình, một tệp nhị phân duy nhất. Khi bạn cần một cơ sở tri thức trực tiếp, bạn có thể thêm quyền truy cập theo danh tính, kiểm soát xuất bản, ghi nguyên tử, xác thực và phê duyệt thủ công mà không thay đổi cách tác nhân đọc hoặc điều hướng nội dung.

Lưu trữ và truy xuất Markdown

Đặt tài liệu, sổ tay vận hành, bối cảnh dự án hoặc ghi chú do tác nhân tạo trong các tệp Markdown thông thường. Không có quy trình nhập dữ liệu: trỏ OpenLore vào một thư mục và nó phục vụ trực tiếp cấu trúc thư mục hiện có. Tổ chức tài liệu bằng thư mục, kết nối chúng bằng liên kết Markdown chuẩn và nhóm chúng thành các bộ tài liệu khi những người hoặc tác nhân khác nhau cần quyền truy cập khác nhau. OpenLore chỉ đọc theo mặc định; bật ghi khi bạn muốn tác nhân tạo và cập nhật Markdown.

Bắt đầu nhanh

Cách nhanh nhất là để tác nhân của bạn thiết lập 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

Hoặc cài đặt và chạy trực tiếp:

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

openlore ./docs

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

Theo mặc định, điều này khởi động:

• SSH trên localhost:2222
• giao diện web dành cho con người trên http://localhost:8080
• MCP qua HTTP trên http://localhost:8080/mcp

Xem Cài đặt để biết thêm cách cài đặt và đóng gói OpenLore.

Tính năng

• Truy xuất hướng đến tác nhân — Tác nhân sử dụng các công cụ shell và mẫu kết hợp mà chúng đã hiểu thay vì học một API truy xuất tùy chỉnh.
• Một bề mặt tri thức, nhiều phương thức truyền tải — Phục vụ cùng một hệ thống tệp ảo qua SSH, SFTP/SSHFS, MCP và giao diện web thân thiện với con người.
• Tri thức trực tiếp, có quản trị — Giữ nội dung chỉ đọc, cho phép xuất bản có phạm vi, hoặc bật ghi đầy đủ cho từng bộ tài liệu. Ghi là nguyên tử, nhận biết xung đột và có thể yêu cầu phê duyệt thủ công.
• Chế độ xem theo danh tính — Cấp cho mỗi người hoặc tác nhân chỉ các bộ tài liệu cần thiết, với quyền ro, publish và rw dựa trên vai trò, bí danh đường dẫn và thư mục chính riêng tư.
• An toàn về mặt thiết kế — Shell là một trình thông dịch Go trong bộ nhớ, không phải shell hệ điều hành thực. Không có lỗ hổng shell, thực thi tiến trình tùy ý hoặc truy cập mạng xung quanh trong phiên bình thường.
• Gói tri thức di động — Nhúng tài liệu vào một tệp nhị phân tự chứa, xây dựng gói đa nền tảng với GitHub Action hoặc đóng gói chúng dưới dạng tiện ích mở rộng MCP máy tính để bàn.
• Tri thức có cấu trúc mà không cần ngôn ngữ truy vấn mới — Kiểm tra frontmatter dưới dạng NDJSON với lore meta, truy vấn bằng jq và xác thực các gói Định dạng Tri thức Mở (OKF) của Google và Kỹ năng tác nhân gần đường ghi.
• Chính sách và xử lý có thể mở rộng — Plugin có thể thêm xác thực, quyền, phần mềm trung gian đọc/ghi, siêu dữ liệu và xử lý sau cam kết trong khi vẫn giữ giao diện hệ thống tệp tương tự.

Trường hợp sử dụng

• Kho lưu trữ Học tập liên tục — lưu trữ phiên và bài học trong một máy chủ dùng chung. Thêm số liệu để bạn có thể tối ưu hóa. Cho phép tác nhân chia sẻ bài học với nhau trong khi duy trì sự cô lập người dùng.
• Kho lưu trữ tạo phẩm của nhóm — chia sẻ tài liệu markdown, HTML, JSON, Excel, v.v. mà bạn đã tạo trong khi duy trì kiểm soát truy cập. Tự nhiên hơn nhiều so với git, hướng đến tác nhân hơn Confluence/Notion.
• Tài liệu cho tác nhân lập trình — Đặt tài liệu API nội bộ, sổ tay vận hành, bối cảnh sản phẩm và ghi chú kiến trúc sau một giao diện quen thuộc, có thể tìm kiếm.
• Bộ nhớ trực tiếp dùng chung cho nhóm tác nhân — Cấp cho tác nhân các bộ tài liệu riêng hoặc dùng chung để chúng có thể xuất bản phát hiện, bàn giao công việc và tích lũy bối cảnh bền vững qua các phiên.
• Trang web tài liệu công khai — thêm bất kỳ tệp nào vào bộ tài liệu công khai của bạn, bật truy cập công khai và nó sẽ được hiển thị cho bất kỳ tác nhân nào tình cờ ghé thăm trang web của bạn. Cải thiện AEO/GEO mà không cần chỉnh sửa tài liệu hiện có.
• Chia sẻ kỹ năng — Xuất bản Kỹ năng tác nhân vào các bộ sưu tập dùng chung để mọi tác nhân được ủy quyền có thể khám phá và sử dụng cùng các quy trình có quản trị.
• Kho lưu trữ Plugin tác nhân — Ghim phiên bản kho Plugin tác nhân từ GitHub và phục vụ chúng cho tác nhân của nhóm bạn. Kỹ năng được đóng gói theo tiêu chuẩn mở tự động cập nhật.
• Đóng góp tri thức có quản trị — Cho phép người đóng góp xuất bản vào hộp thư đến trong khi dành các đường dẫn nhạy cảm cho người phê duyệt và ngăn ghi đè vô tình.
• Xem xét từ xa tạo phẩm của tác nhân — Hiển thị báo cáo, nhật ký, ảnh chụp màn hình và tệp đã tạo qua trình duyệt hoặc SSH mà không cần xây dựng trình xem tạo phẩm tùy chỉnh hoặc cấp quyền truy cập vào máy của tác nhân.
• Không gian làm việc theo danh tính — Gắn một thư mục chính riêng cho mỗi tác nhân cộng với tri thức nhóm dùng chung, tất cả qua một máy chủ và một mô hình ủy quyền.
• Tri thức khách hàng hoặc dự án di động — Phân phối một tệp thực thi có phiên bản với tài liệu liên quan được nhúng hoặc phân phối cùng tri thức dưới dạng tiện ích mở rộng MCPB máy tính để bàn.
• Danh mục tri thức đã xác thực — Thực thi frontmatter và quy ước gói, kiểm tra siêu dữ liệu một cách rẻ và chặn tri thức sai định dạng tại thời điểm tiếp nhận.

Cách hoạt động

OpenLore được xây dựng trên Wish cho truyền tải SSH. Một kết nối được xử lý hoàn toàn dựa trên một hệ thống tệp ảo:

1. Xác thực — kết nối không cần khóa hoặc phân giải khóa SSH, chứng chỉ, khóa truy cập hoặc đăng nhập OAuth thành một danh tính.
2. Tạo chế độ xem — chỉ gắn các bộ tài liệu và đường dẫn được cấp cho danh tính đó.
3. Khám phá — chạy các lệnh shell được triển khai dưới dạng hàm Go thuần túy trên chế độ xem đó hoặc sử dụng công cụ MCP shell tương đương.
4. Đóng góp an toàn — nếu ghi được bật, ủy quyền và xác thực một thay đổi toàn bộ tệp trước khi cam kết nguyên tử hoặc chuyển nó để phê duyệt.

Khách hàng OAuth sử dụng danh tính được ủy quyền, vì vậy nguồn gốc ghi bền vững phân biệt công việc trực tiếp bởi adil với công việc thực hiện dưới dạng adil/claude@claude.ai. Người được ủy quyền không thể kế thừa quyền hạn nhiều hơn hiệu trưởng của họ và có thể bị thu hẹp theo danh sách từ chối bộ tài liệu và khả năng. Khách hàng CIMD cũng có thể xác thực với siêu dữ liệu do nhà cung cấp lưu trữ và private_key_jwt; xem Khách hàng OAuth đã xác thực.

Shell bình thường không thể gọi bash, exec, curl hoặc các tiến trình máy chủ tùy ý. Tài liệu nhúng luôn chỉ đọc. Các danh tính được tin cậy rõ ràng có thể được cấp xử lý không đồng bộ có phạm vi hẹp thông qua khả năng spawn.

Ghi có quản trị

OpenLore chỉ đọc theo mặc định. Các triển khai có thể ghi giữ một đường ghi duy nhất, có kiểm soát chính sách cho chuyển hướng, nối thêm, tee, patch, sed -i, di chuyển tệp, xuất bản và các công việc bên ngoài được phê duyệt.

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

Ghi là các hoán đổi nguyên tử toàn bộ đối tượng. Bảo vệ so sánh và hoán đổi từ chối các chỉnh sửa lỗi thời theo mặc định, quyền bộ tài liệu giới hạn mục tiêu và các đường dẫn đã chọn có thể tạo các bộ thay đổi có thể xem xét dưới /requests thay vì cam kết trực tiếp.

Xem Ghi và xuất bản để biết thiết lập hướng đến người dùng và Nội bộ hệ thống ghi để biết mô hình triển khai.

Cài đặt

Cài đặt bằng Go

Yêu cầu Go 1.26 trở lên:

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

Xây dựng từ mã nguồn

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

Nhúng tài liệu vào tệp nhị phân

Đặt tài liệu trong assets/lore/ và xây dựng. Tệp nhị phân kết quả chứa tài liệu và phục vụ chúng ở chế độ chỉ đọc tại /docs khi chạy không có đối số thư mục:

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

Xây dựng với GitHub Action

Tạo tệp nhị phân đa nền tảng với tài liệu của bạn được nhúng:

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

Xem Cách sử dụng OpenLore để biết cách sử dụng MCP stdio, đóng gói MCPB máy tính để bàn, SSHFS và thư viện Go.

Tạo triển khai tùy chỉnh

Sử dụng kỹ năng setup đi kèm để tạo <team>-lore, một kho lưu trữ nhỏ do khách hàng sở hữu chứa openlore.yml, một Containerfile mỏng được ghim vào bản phát hành OpenLore chính thức và các tạo phẩm triển khai. Nó xây dựng một máy chủ cục bộ hoạt động và xác minh HTTP, MCP, SSH đã xác thực, ghi và lưu trữ trước khi triển khai:

ssh openlore.sh setup | amp

Kho lưu trữ được tạo giữ chính sách lore.json ban đầu và các tệp hiển thị qua SSH dưới .local/ bị bỏ qua bởi git. Lần triển khai đầu tiên khởi tạo một ổ đĩa bền vững trống từ trạng thái đó. openlore.yml gốc vẫn là cơ quan Git/IaC và được triển khai riêng đến /var/lib/openlore/config/openlore.yml; nó không được nướng vào hình ảnh. Các chỉnh sửa lore.json và hệ thống tệp sau đó trên máy chủ là có thẩm quyền và không bao giờ bị ghi đè bởi các bản cập nhật hình ảnh.

Các lệnh hướng dẫn bổ sung hỗ trợ toàn bộ vòng đời:

• onboarding thêm danh tính, vai trò, thư mục chính và thư mục ban đầu cục bộ;
• deploy chọn Fly.io, Railway, AWS, Google Cloud, Azure, DigitalOcean hoặc triển khai tùy chỉnh và xác minh hợp đồng lưu trữ/mạng dùng chung;
• upgrade chỉ chuẩn bị thay đổi phiên bản hình ảnh cơ sở được ghim để CD hiện có có thể triển khai nó.

Triển khai nhà cung cấp yêu cầu HTTPS/MCP, SSH OpenLore đã xác thực, quyền truy cập shell quản trị và ổ đĩa /var/lib/openlore bền vững. Ở nơi nhà cung cấp hỗ trợ, triển khai cấu hình cổng công khai 22 để chuyển tiếp đến cổng OpenLore 2222. Nếu không, nó báo cáo cổng được chỉ định và đề xuất một hệ thống chuyển tiếp TCP bên ngoài.

Container được xuất bản chỉ chứa OpenLore. Nó cố tình không chứa chính sách gia nhập hoặc cấu hình máy chủ. Trước khi dịch vụ khởi động, quá trình triển khai phải đặt openlore.yml và lore.json trong thư mục cấu hình bền vững và chạy:

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

Điều này giữ cấu hình có thể triển khai độc lập: một triển khai đơn giản có thể sao chép openlore.yml vào ổ đĩa, trong khi Kubernetes có thể chiếu cùng một tệp từ ConfigMap. Sử dụng kỹ năng deploy cho Fly.io, Railway, AWS, Google Cloud, Azure, DigitalOcean hoặc cơ sở hạ tầng tùy chỉnh. Các tệp Railpack và Fly của kho lưu trữ cung cấp hình ảnh, ổ đĩa bền vững và kết nối cổng; chúng không khởi tạo hoặc thay đổi cấu hình khi khởi động tiến trình.

Railway chỉ định cho proxy TCP SSH của nó một tên máy chủ và cổng công khai. Cổng SSH chuẩn 22 yêu cầu bộ cân bằng tải TCP thô bên ngoài. Fly.io có thể ánh xạ cổng công khai 22 đến cổng nội bộ 2222 của OpenLore với một địa chỉ chuyên dụng. SSH thô không có tên máy chủ hoặc định tuyến SNI, vì vậy một trình nghe không thể định tuyến nhiều miền trên cổng 22.

Quy trình container xuất bản latest từ main; các bản phát hành cũng xuất bản VERSION, vVERSION, các thẻ hình ảnh chính và phụ.

Tải lên hộp thư đến HTTP

Cấu hình một bộ tài liệu inbox và một vai trò có quyền publish của nó, sau đó tạo thông tin xác thực cho một danh tính hiện có (cấu hình máy chủ phải đặt tên auth_file để CLI có thể xác thực nó):

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} chấp nhận thông tin xác thực bearer hoặc HMAC thân chính xác bằng X-OpenLore-Token-Id và X-OpenLore-Signature. Mã thông báo truy cập OAuth chỉ được sử dụng cho POST/GET /inbox/tokens và DELETE /inbox/tokens/{id}; thông tin xác thực hộp thư đến là riêng biệt và có thể thu hồi. Xem Cấu hình và danh tính.

Tài liệu

Hướng dẫn	Nội dung
Các cách sử dụng OpenLore	SSH, MCP, web, SSHFS, nhị phân nhúng, GitHub Action, MCPB và cách sử dụng thư viện
Tham chiếu lệnh	Tham chiếu đầy đủ về shell, nội quan, xuất bản, cú pháp, lệnh CLI và cờ
Cấu hình và danh tính	openlore.yml, xác thực, vai trò, docset, bí danh, thư mục chính và xác minh máy chủ
Liên kết danh tính khối lượng công việc	Xác thực CI và tác nhân bằng mã thông báo danh tính bên ngoài ngắn hạn
Viết và xuất bản	Chế độ viết, hộp thư đến, xử lý xung đột, phê duyệt và công việc
Plugin và định dạng kiến thức	Cài đặt plugin, giao diện, xác thực OKF, lore validate và lore meta
Nội bộ hệ thống ghi	Phân lớp hệ thống tệp, đường nối ghi, tập thay đổi, hook và công việc không đồng bộ
Đánh giá bảo mật	Mô hình mối đe dọa và thuộc tính bảo mật

Bảo mật

• Các lệnh chạy trong trình thông dịch Go thuần túy, không thông qua os/exec.
• Hệ thống tệp ảo làm sạch đường dẫn và thực thi ranh giới docset.
• Các mẫu tệp được phép và thư mục bị bỏ qua giữ bí mật khỏi chế độ xem.
• RBAC kiểm soát đọc, xuất bản, ghi, phê duyệt và các khả năng đáng tin cậy.
• Điểm cuối web có thể xuất bản khóa máy chủ SSH qua TLS để tránh tin tưởng mù khi sử dụng lần đầu; chứng chỉ người dùng và máy chủ SSH cũng được hỗ trợ.

Xem SECURITY.md để có đánh giá bảo mật đầy đủ.

Giấy phép

MIT — Adil Karim

OpenLore đi kèm các thành phần mã nguồn mở của bên thứ ba. Giấy phép và thông báo bắt buộc của chúng được liệt kê trong assets/legal/THIRD_PARTY_NOTICES.md, với văn bản giấy phép đầy đủ trong assets/legal/licenses/. Các tệp này được nhúng trong nhị phân và được phục vụ bởi dịch vụ đang chạy tại /legal.