Bỏ qua, đến phần nội dung

Knowledge base từ repo GitHub, GitLab ​

Thay vì đẩy tài liệu bằng tay với ph kb push, bạn có thể gắn một repo GitHub hoặc GitLab vào knowledge base. Tara đọc README, docs và ADR, giữ cho chúng luôn mới, và cho bạn cùng agent tra cứu kèm trích dẫn nguồn. Repo riêng tư vẫn riêng tư: mỗi người chỉ thấy tài liệu của repo riêng tư nếu tài khoản GitHub hoặc GitLab của chính họ đọc được repo đó.

Tổ chức của bạn cần đã cài GitHub App PhillipCLI (xem Kết nối GitHub) hoặc đã kết nối một group GitLab (xem Kết nối GitLab). Với GitLab, chỉ gắn được repo nằm trong group đã kết nối, công khai hay riêng tư đều vậy. Gắn và gỡ repo là việc của Owner và Admin. Đọc và tra cứu thì mọi thành viên làm được.

Gắn một repo ​

Trên Portal, mở Knowledge, vào Repository sources rồi chọn repo trong danh sách: các repo mà GitHub App nhìn thấy và các project của group GitLab hiện chung một danh sách. Trên terminal, sau khi đăng nhập bằng ph login:

Mỗi nguồn hiện nhà cung cấp, chế độ riêng tư, số tài liệu và lần đồng bộ gần nhất; biểu mẫu bên dưới gắn thêm repo.
bash
ph kb source add acme/shop                         # README, docs và ADR (mẫu mặc định)
ph kb source add acme/shop --include 'docs/**' --include 'handbook/*.md'
ph kb source add https://gitlab.com/acme/platform/shop   # một project GitLab (dùng URL của nó; subgroup được)
ph kb sources                                      # các repo đã gắn và trạng thái đồng bộ

Với GitLab, ph kb source sync và ph kb source remove nhận cùng URL project đó, hoặc đường dẫn đầy đủ khi nó có từ ba đoạn trở lên (acme/platform/shop). Host phải là host của kết nối GitLab.

Lần đồng bộ đầu chạy ngay. Bạn theo dõi trạng thái bằng ph kb sources.

Những gì được đồng bộ ​

Tara đọc các tệp Markdown và văn bản thuần (.md, .markdown, .mdx, .txt và tệp README) khớp với mẫu --include. Nếu không đặt --include, mẫu mặc định là README*, docs/**, doc/**, adr/**, **/docs/**, **/adr/** và **/README*.

Trong một mẫu, * chỉ khớp trong một cấp thư mục, ** đi xuyên qua nhiều thư mục, còn mẫu không có dấu / thì chỉ khớp ở thư mục gốc của repo. Tara không bao giờ đọc node_modules, vendor, dist, build hay .git. Mỗi repo đóng góp tối đa 1000 tệp và 64 MiB, mỗi tệp tối đa 2 MiB.

Mỗi repo thành một space, tên là gh-<owner>-<repo> với GitHub (ví dụ gh-acme-shop) và gl-<group>-<subgroup>-<project> với GitLab. Mọi người chỉ đọc được space này. Muốn sửa tài liệu thì sửa ngay trong repo.

Cách giữ cho tài liệu luôn mới ​

  • Khi có push. Push vào nhánh mặc định sẽ kích hoạt đồng bộ qua webhook của GitHub App. Việc này cần app bật sự kiện Push và Repository (trang đăng ký GitHub App có danh sách). Trên GitLab, bạn tự cài webhook của kết nối và tick Push events. Tara đồng bộ đúng commit đó, và chỉ với push vào nhánh mặc định của project nằm trong group. Xóa project trên GitLab thì nguồn của nó bị đánh dấu lỗi.
  • Định kỳ. Mặc định mỗi giờ Tara đồng bộ thêm một lần, để bắt những gì webhook bỏ sót. Trên GitLab, đây là cách duy nhất cho tới khi bạn thêm webhook.
  • Sync now. Chạy ph kb source sync acme/shop (thêm --wait để chờ tới khi xong), hoặc bấm Sync now trên Portal.

Chỉ những tệp có nội dung thay đổi mới được xử lý lại, và tệp đã bị xóa khỏi repo thì cũng bị gỡ khỏi space. Nếu một lần đồng bộ lỗi, tài liệu cũ vẫn tra cứu được và lỗi hiện ngay cạnh repo.

Ai xem được gì ​

  • Người ngoài tổ chức đã gắn repo thì không thấy gì.
  • Với repo công khai, mọi thành viên của tổ chức đều thấy.
  • Với repo riêng tư, chỉ những thành viên có tài khoản GitHub đã liên kết và có ít nhất quyền đọc repo đó. Tara hỏi GitHub qua app và nhớ câu trả lời 10 phút. Nếu bạn mất quyền trên GitHub thì chậm nhất sau 10 phút bạn cũng mất quyền ở đây.
  • Trên GitLab, luật giống vậy. Thành viên phải từng đăng nhập Tara bằng GitLab trên host của kết nối, và GitLab phải báo họ là thành viên của project (trực tiếp hoặc qua group) với role Reporter trở lên. Guest không đọc được code trong project riêng tư nên không tính. Chế độ internal của GitLab được coi là riêng tư, nên người không phải thành viên vẫn bị từ chối dù GitLab cho họ đọc. Tara hỏi GitLab bằng credential của kết nối, nhớ câu trả lời 10 phút, và nhận thay đổi chế độ hiển thị ở lần đồng bộ hằng giờ kế tiếp.

Khi Tara không chắc, câu trả lời là không. Thành viên chưa liên kết tài khoản GitHub hay GitLab, repo nằm ngoài installation hoặc group, bản cài đặt đang bị tạm ngưng, kết nối GitLab cần kết nối lại, hoặc nơi lưu repo trả lỗi, tất cả đều có nghĩa là không xem được tài liệu của repo riêng tư. Tara không lưu token GitHub hay GitLab của ai.

Để liên kết tài khoản, hãy đăng nhập bằng GitHub hoặc GitLab, hay liên kết trong phần cài đặt tài khoản.

Tra cứu từ Claude Code ​

Tài liệu nằm trong cùng một knowledge base, nên kit kit-knowledge tra được chúng với đúng quyền như trên Portal. Chỉ cần cài một lần:

bash
ph tara add kit-knowledge

Sau đó agent gọi được search, get_document và list_spaces ngay trong phiên làm việc. Trên terminal, thêm --space gh-acme-shop vào ph kb search để chỉ tìm trong một repo. Trích dẫn trỏ về tệp trên GitHub hoặc GitLab tại đúng commit đã đồng bộ.

Các lệnh ​

LệnhViệc làm
ph kb sourcesLiệt kê các repo đã gắn kèm trạng thái đồng bộ
ph kb source add <owner/repo hoặc URL GitLab> [--include <glob>]…Gắn một repo
ph kb source sync <owner/repo> [--wait]Đồng bộ ngay
ph kb source remove <owner/repo>Gỡ repo và xóa tài liệu của nó

Lệnh nào cũng nhận --json. Danh sách đầy đủ nằm ở tham chiếu ph kb.

Giới hạn ​

  • Tara tải mỗi repo dưới dạng một tệp nén tối đa 256 MiB. Repo lớn hơn sẽ không đồng bộ được. Hãy thu hẹp bằng --include, hoặc tách phần cần dùng sang một repo nhỏ hơn.
  • Chỉ nhận văn bản, chưa đọc PDF, giống phần còn lại của knowledge base.
  • Liên kết trích dẫn của GitHub luôn trỏ về github.com. Nếu máy chủ của bạn nói chuyện với GitHub Enterprise Server thì tìm kiếm và đồng bộ vẫn chạy, nhưng các liên kết đó sẽ không mở đúng trang. Liên kết GitLab dùng https và host của kết nối.
  • Nguồn GitLab được đọc bằng credential của kết nối, nên khi kết nối cần kết nối lại (reauth_required) thì việc đồng bộ tạm dừng.
  • Push đến đúng lúc một lần đồng bộ đang chạy sẽ được lần đồng bộ định kỳ kế tiếp nhận.

Đọc thêm ​