Cơ sở tri thức cục bộ

Cơ sở tri thức cục bộ là một thư mục tệp Markdown thông thường mà bạn viết và sắp xếp trong VelaTerm. Ghi chú và tệp đính kèm nằm ngay trong thư mục đó, nên bạn vẫn có thể tiếp tục chỉnh sửa chúng bằng các trình soạn thảo khác. Một số mục menu gọi cơ sở tri thức cục bộ là “sổ ghi chép” hoặc “sổ”; các tên gọi này đều chỉ cùng một thư mục.

“Kho kiến thức theo phiên” có sẵn nằm cạnh các cơ sở tri thức cục bộ của bạn. Kho này chứa kiến thức do tác nhân tổng hợp từ các phiên của bạn, với các bài viết, nguồn và lịch sử phiên bản riêng; xem Kho kiến thức theo phiên.

Mở kho kiến thức

Nhấp biểu tượng kiến thức ở bảng bên phải (chú thích “Kho kiến thức”). Một thẻ “Kho kiến thức” mở ở khung giữa và hiển thị trang chủ, gồm:

ô tìm kiếm (“Tìm trong kiến thức phiên và ghi chú cục bộ…”, xem phần Tìm kiếm bên dưới);
“Kho kiến thức theo phiên”;
“Cơ sở tri thức cục bộ” của bạn;
các nút “Mở cơ sở tri thức” và “Tạo cơ sở tri thức”.

Bảng bên phải hiển thị một cây có ba gốc: “Kho kiến thức theo phiên”, “Phiên đã lưu trữ” và “Cơ sở tri thức cục bộ”. Nhấp vào mũi tên để mở rộng một thư mục ngay tại chỗ; có thể mở rộng nhiều cơ sở tri thức cùng lúc. Nhấp vào tên thư mục để xem nội dung, và nhấp vào một ghi chú để mở ghi chú đó. Liên kết “Cơ sở tri thức” ở đầu cây đưa bạn về trang chủ, còn nút “Lên một cấp” ở phần đầu trang chuyển tới trang cấp trên mà không rời khỏi kho kiến thức.

Ghi chú mở trong thẻ tài liệu thông thường, với các chức năng chỉnh sửa, lưu, tìm kiếm và xuất PDF giống như mọi tệp Markdown khác (xem Thẻ tài liệu và thẻ trình duyệt). Thẻ “Kho kiến thức” vẫn nằm trên thanh thẻ để bạn quay lại đúng chỗ đang xem.

Mở hoặc tạo cơ sở tri thức cục bộ

Mở: nhấp “Mở cơ sở tri thức” và chọn một thư mục. Ứng dụng máy tính hiển thị hộp chọn thư mục của hệ thống; máy khách trình duyệt hiển thị trình duyệt thư mục của máy tính đang kết nối. Có thể mở trực tiếp một vault Obsidian có sẵn: các tệp vẫn ở nguyên vị trí, còn các thư mục ẩn như .obsidian không được lập chỉ mục và không bị thay đổi.
Tạo: nhấp “Tạo cơ sở tri thức”, nhập “Tên”, chọn “Thư mục” (hoặc “Duyệt”; thư mục đề xuất là ~/Notes) rồi xác nhận. VelaTerm tạo thư mục và mở thư mục đó. Thư mục cha phải tồn tại và chưa có thư mục nào trùng tên; nếu không, VelaTerm hiển thị “Đích đã tồn tại. Hãy chọn tên hoặc thư mục khác.” Để dùng một thư mục có sẵn, hãy chọn “Mở cơ sở tri thức”.
Đổi tên: nhấp chuột phải vào một cơ sở tri thức trong cây và chọn “Đổi tên”. Thao tác này đổi tên thư mục trên ổ đĩa.
Đóng: nhấp “Đóng sổ ghi chép” trên thanh công cụ của cơ sở tri thức, hoặc nhấp chuột phải vào cơ sở tri thức đó trong cây. Thao tác đóng chỉ xóa thư mục khỏi danh sách; các tệp vẫn còn trên ổ đĩa. Khi bạn mở lại cùng thư mục đó, thùng rác và lịch sử nhập vẫn còn nguyên.

“Cục bộ” ở đây là máy tính chạy máy chủ VelaTerm mà bạn đang kết nối. Trong máy khách trình duyệt, “Mở cơ sở tri thức” duyệt các thư mục trên máy tính đó, và thao tác nhập sẽ tải các tệp bạn chọn trong trình duyệt lên máy tính đó.

Nhập tệp và thư mục

Mở cơ sở tri thức đích và nhấp “Nhập” trên thanh công cụ.
Chọn “Thư mục” đích, sau đó chọn “Chọn tệp”, “Chọn thư mục” hoặc kéo tệp và thư mục vào vùng nhập.
Kiểm tra danh sách rồi xác nhận.

Quá trình nhập chạy ở nền, nên bạn có thể chuyển trang hoặc mở ghi chú trong lúc tệp đang được sao chép. Tiến độ hiển thị trên thanh công cụ của cơ sở tri thức và trên trang chủ, và có thể hủy quá trình nhập từ hộp thoại nhập hoặc từ “Lịch sử nhập”. Khi hoàn tất, một biểu ngữ cho biết số tệp đã nhập và đã bỏ qua; nếu cửa sổ không phải là cửa sổ đang hoạt động, một thông báo hệ thống (“Nhập hoàn tất” hoặc “Nhập thất bại”) sẽ xuất hiện. Mỗi cơ sở tri thức chỉ chạy được một lần nhập tại một thời điểm.

Thao tác nhập sao chép nguyên trạng các tệp, bao gồm tên tệp có ký tự ngoài ASCII, cấu trúc thư mục tương đối và tệp đính kèm, và không bao giờ sửa đổi tệp gốc. Khi nhập một thư mục, chính thư mục đó cũng được nhập. Nếu có bất kỳ tệp nào sẽ ghi đè lên một tệp hiện có, toàn bộ lô bị từ chối. Tệp ẩn và thư mục cấu hình ẩn được bỏ qua. Hộp chọn tệp của trình duyệt không cung cấp thư mục trống, nên thư mục trống không được nhập.

Mỗi lần nhập có thể chứa tối đa 5.000 tệp (các tệp ẩn bị bỏ qua cũng được tính vào giới hạn này) với tổng dung lượng tối đa 1 GiB, mỗi tệp không quá 100 MiB. Các tệp được đưa vào vùng tạm trước và chỉ xuất hiện ở thư mục đích sau khi cả lô đã được chuyển đến đầy đủ, nên một lần tải lên bị gián đoạn không bao giờ để lại ghi chú mới ghi được một nửa.

“Lịch sử nhập” liệt kê mọi lần nhập kèm thời gian, thư mục đích (“Thư mục gốc của cơ sở tri thức” với thư mục cấp cao nhất), trạng thái (“Đang nhập”, “Hoàn tất”, “Thất bại”, “Đã hủy” hoặc “Bị gián đoạn”), số tệp đã nhập và đã bỏ qua, dung lượng và thời lượng. Nhấp “Tệp (N)” để xem từng tệp và lý do tệp bị bỏ qua. “Xóa bản ghi” xóa mục đó khỏi lịch sử; các tệp đã nhập không bị xóa. Lần nhập có tiến độ dừng quá hai phút, chẳng hạn vì ứng dụng thoát bất ngờ, được đánh dấu “Bị gián đoạn”; khi xóa bản ghi của lần nhập đó, các tệp đã đưa vào vùng tạm cho nó cũng bị xóa.

Viết và sắp xếp ghi chú

Trang của một cơ sở tri thức có các chế độ xem “Ghi chú gần đây”, “Thùng rác” và “Lịch sử nhập”, nút “Ghi chú mới”, cùng các nút “Thư mục mới”, “Nhập” và “Đóng sổ ghi chép” trên thanh công cụ. Có thể lọc danh sách ghi chú theo nhãn (“Tất cả nhãn”) và sắp xếp theo “Cập nhật gần đây” hoặc “Theo tiêu đề”.

Khi trang của một cơ sở tri thức đang hiển thị, ⌘N / Ctrl+N tạo “Ghi chú mới”, ⌘O / Ctrl+O mở “Mở nhanh” (tìm ghi chú theo đường dẫn), và ⌘⇧F / Ctrl+Shift+F chuyển tới ô “Tìm ghi chú…”.
Để đổi tên một ghi chú, nhấp chuột phải vào ghi chú đó trong cây và chọn “Đổi tên”. Để di chuyển, kéo ghi chú vào một thư mục khác trong cùng cơ sở tri thức. “Xóa” chuyển ghi chú vào thùng rác của cơ sở tri thức.
Khi một thư mục đang mở, “Đổi tên hoặc di chuyển” chuyển thư mục đó tới một đường dẫn tương đối tính từ thư mục gốc của cơ sở tri thức; thư mục cha phải tồn tại sẵn. Khi một ghi chú hoặc thư mục được di chuyển, các liên kết trong những ghi chú khác của cùng cơ sở tri thức sẽ được cập nhật; văn bản hiển thị của liên kết được giữ nguyên và phần mã không bị thay đổi.
Các mục đã xóa được chuyển vào thư mục .vkb-trash bên trong cơ sở tri thức. Mở “Thùng rác” và nhấp “Khôi phục” để lấy lại một mục; tệp hiện có trùng tên không bao giờ bị ghi đè.
Nhãn được lấy từ #tag trong văn bản và từ danh sách hoặc mảng tags trong YAML.
Ảnh dán vào ghi chú được lưu trong thư mục assets nằm cạnh ghi chú.

Cây và các danh sách được làm mới khoảng năm giây một lần khi trang đang hiển thị, và mỗi khi cửa sổ được chọn lại. Thẻ tài liệu đang mở phát hiện các thay đổi do chương trình khác tạo ra và đề nghị tải lại.

Các trang cơ sở tri thức, hộp thoại, lịch sử nhập, tìm kiếm, phạm vi tìm kiếm, nhãn, cách sắp xếp và mở nhanh đều có URL riêng, nên bạn có thể làm mới trang hoặc dùng nút lùi và tiến của trình duyệt. Văn bản chưa lưu và dữ liệu đang nhập trong biểu mẫu không nằm trong URL.

Tìm kiếm

Trang chủ: tìm đồng thời trong kho kiến thức theo phiên và mọi cơ sở tri thức cục bộ, rồi nhóm kết quả theo nguồn. Phiên đã lưu trữ không nằm trong phạm vi tìm kiếm này.
Bảng bên phải: ô “Tìm ghi chú…” phía trên cây tìm trong mọi cơ sở tri thức cục bộ.
Trang cơ sở tri thức: ô “Tìm ghi chú…” tìm trong tên, đường dẫn và nội dung ghi chú. “Phạm vi tìm kiếm” chuyển giữa “Cơ sở tri thức này” và “Tất cả cơ sở tri thức”.

Khi nhập nhiều từ, kết quả phải khớp với tất cả các từ. Mỗi kết quả hiển thị cơ sở tri thức hoặc nhóm phiên chứa nó, một đoạn trích, số dòng, số lần khớp và các “Ghi chú liên quan” mà ghi chú đó liên kết tới; nhấp vào bất kỳ mục nào để mở. Dùng phím Lên và Xuống để chọn kết quả, Enter để mở và Esc để xóa nội dung tìm kiếm. Kết quả được sắp xếp theo mức khớp ở tên hoặc đường dẫn, sau đó theo số lần khớp, rồi theo thời gian cập nhật gần nhất. Danh sách hiển thị tối đa 100 kết quả; khi có nhiều hơn, cuối danh sách sẽ có dòng “Chỉ hiển thị những kết quả đầu tiên. Thu hẹp tìm kiếm để xem phần còn lại.”

VelaTerm tìm kết quả khớp chính xác trước và chỉ chuyển sang kết quả gần đúng khi không có kết quả chính xác nào, kèm thông báo “Không có kết quả khớp chính xác. Đang hiển thị kết quả gần đúng.” Khớp gần đúng áp dụng cho các từ gồm chữ cái Latinh và chữ số: các chữ cái theo đúng thứ tự (knwl tìm được knowledge), chữ cái đầu (kb tìm được knowledge base) và lỗi gõ nhỏ (một lỗi với từ từ bốn ký tự trở lên, hai lỗi với từ từ tám ký tự trở lên; knoledge tìm được knowledge). Tiếng Trung và các văn bản không dùng chữ Latinh được so khớp chính xác.

Liên kết và khả năng tương thích với tệp có sẵn

VelaTerm nhận biết các dạng thông dụng [[note]], [[folder/note|label]] và [[note#heading]], liên kết Markdown tương đối chuẩn, và ![[image.png]]. VelaTerm dùng các liên kết này để cập nhật liên kết khi ghi chú được di chuyển, để liệt kê “Ghi chú liên quan” trong kết quả tìm kiếm, và cho các lệnh vkb được mô tả bên dưới. Trong trình soạn thảo, liên kết [[…]] hiển thị dưới dạng văn bản thuần. Khi nhiều tệp trùng tên, liên kết ngắn chỉ được phân giải nếu đích là duy nhất; nếu không, hãy ghi cả đường dẫn thư mục.

Các tệp vẫn là Markdown thuần, và YAML front matter vẫn nằm trong tệp; chế độ Mã nguồn của trình soạn thảo hiển thị phần này đúng như trong tệp. Các tệp Markdown không mã hóa UTF-8 hoặc lớn hơn 5 MiB không được liệt kê là ghi chú mà được tính vào mục “Đã bỏ qua”. Một cơ sở tri thức có thể chứa tối đa 50.000 tệp và thư mục; thư mục lớn hơn không mở được và hiển thị “Tệp hoặc nội dung đã chọn vượt quá giới hạn của sổ.” Liên kết tượng trưng (symbolic link) không được theo.

Các tính năng này đáp ứng công việc hằng ngày với tệp cục bộ, thư mục, Markdown, liên kết và tìm kiếm. Plugin, chủ đề, Canvas, tham chiếu khối, ghi chú nhúng và bí danh YAML của Obsidian không được hỗ trợ; các tệp tương ứng được giữ nguyên. Về mô hình tệp và cú pháp liên kết, hãy xem tài liệu của Obsidian về vault, liên kết nội bộ và tệp đính kèm.

Sao chép từ kho kiến thức theo phiên và truy vấn của tác nhân

Mở một bài viết trong kho kiến thức theo phiên, chọn “Sao chép vào sổ cục bộ”, rồi chọn cơ sở tri thức đích và tên tệp. Bản sao là một ghi chú Markdown độc lập; bài viết gốc, các bản chụp nguồn và lịch sử phiên bản của bài viết vẫn được giữ nguyên.

Trong một phiên VelaTerm, bạn hoặc tác nhân có thể đọc các cơ sở tri thức cục bộ đã đăng ký bằng vkb:

vkb notes "reading notes"
vkb note <knowledge-base-ID> "reading/how-to-take-notes.md"
vkb search "architecture decision"

notes tìm trong mọi cơ sở tri thức cục bộ đã đăng ký trên máy chủ hiện tại. Mỗi kết quả gồm vaultId, vaultName, path, absolutePath, line, matches, score, matched (đoạn văn bản thực sự khớp), related (các ghi chú mà ghi chú này liên kết tới) và summary (đoạn văn bản quanh chỗ khớp). Phản hồi còn cho biết total, hasMore, unavailable (các cơ sở tri thức không đọc được) và fuzzy (kết quả có phải là kết quả gần đúng hay không). Lệnh trả về tối đa 100 kết quả.
note trả về nội dung, dàn ý, liên kết, liên kết ngược và nhãn của một ghi chú.
search trả về kết quả khớp từ kho kiến thức theo phiên, các ghi chú cục bộ và, khi đã có chỉ mục mã, từ đồ thị mã nguồn (xem Đồ thị mã nguồn và kho kiến thức).

Các lệnh này chỉ đọc dữ liệu. Chúng không bao giờ thay đổi ghi chú, và VelaTerm không tự động đưa nội dung của cơ sở tri thức vào các phiên.

Nơi lưu dữ liệu và nhật ký

Các tệp trên ổ đĩa là bản chính thức của ghi chú và tệp đính kèm. Cơ sở dữ liệu của ứng dụng (các bảng kb_*) chỉ lưu danh sách các cơ sở tri thức đã đăng ký, bản ghi thùng rác, lịch sử nhập và bộ nhớ đệm tìm kiếm có thể dựng lại. Kho kiến thức theo phiên dùng các bảng memory_* riêng.

Các thao tác mở, ghi, di chuyển, xóa, khôi phục và nhập được ghi vào nhật ký thời gian chạy kèm ID thao tác, số lượng và thời gian thực hiện, không bao giờ kèm nội dung ghi chú. Các dòng này dùng sự kiện knowledge; khi chưa đặt VLX_LOG_DIR, VLX_KNOWLEDGE_LOG_DIR quy định thư mục chứa chúng. Lịch sử nhập được lưu trong cơ sở dữ liệu và hiển thị ở trang “Lịch sử nhập”. Để sao lưu đầy đủ một cơ sở tri thức, hãy giữ cả thư mục của nó lẫn dữ liệu ứng dụng, nơi chứa bản ghi thùng rác và bản ghi nhập của cơ sở tri thức đó.