hướng dẫn

Federation

Bản dịch có sự hỗ trợ của AI agent. Nếu có khác biệt, trang tiếng Anh là bản có hiệu lực. Nếu bạn thấy vấn đề nào trong văn bản, rất mong bạn mở một issue hoặc gửi một pull request.

Federation cho phép các nhóm cùng đọc những lớp ngữ cảnh thuộc quyền sở hữu riêng biệt mà không phải gộp chúng lại hay chuyển giao trách nhiệm giữ cho chúng cập nhật.

Vì sao ghép lại thay vì tập trung hoá

Một lớp ngữ cảnh luôn cập nhật vì chính chủ sở hữu đọc và sửa nó trong quá trình làm việc. Nếu tập trung hoá nội dung của nhóm khác, ta sẽ tách nội dung khỏi những người chịu trách nhiệm về nó. Federation giữ nguyên vẹn từng kho mã nguồn, từng chủ sở hữu và từng quy trình xem xét. Trang lý do thiết kế lập luận đầy đủ về điều này.

Một mount ngang hàng là gì

Một lớp ngang hàng là lớp ngữ cảnh của một nhóm khác, do lớp chủ khai báo trong federation.mounts. Khai báo này ghim commit bất biến đầy đủ mà lớp chủ đọc, đồng thời ghi lại quyền sở hữu và cách định tuyến theo tác vụ. Công cụ đọc phép chiếu lớp do manifest của lớp ngang hàng định nghĩa, tại đúng pin đó, vào một bộ nhớ đệm bị bỏ qua. Nó không bao giờ chép nội dung của lớp ngang hàng vào lớp chủ.

Phép chiếu là hợp của những gì mà chính manifest của lớp ngang hàng làm cho đọc được tại pin: tệp leji.json của nó, gốc ngữ cảnh của nó, boot profile của nó, các tệp index danh mục của nó, những profile mà các liên kết agents của nó nêu tên, các cây agent-profile và decision-record của nó, index và changelog máy đọc được của nó, cùng mọi đường dẫn được quản trị mà index sinh ra của nó liệt kê, bất kể chúng nằm ở đâu.

Một lớp ngang hàng thường nằm bên trong một kho mã nguồn sản phẩm lớn hơn, nên chính ranh giới đó là thứ ngăn một mount phải nhập cả sản phẩm về chỉ để đọc ngữ cảnh của nó.

Một mount là một tham chiếu, không phải một bản fork hay một sự cấp quyền. Lớp ngang hàng vẫn giữ thẩm quyền của nó và hệ quản lý phiên bản của nó vẫn quyết định ai được đọc. Việc mount làm cho quan hệ ấy và phiên bản đã chọn trở nên rõ ràng với những người vốn đã có quyền truy cập.

"federation": {
   "mounts": [
      {
         "name": "product-context",
         "source": "https://github.com/acme/product-context",
         "pin": "7d3f2a19c4e8b6a0d5f1c2e9b8a7f6d5c4b3a2e1", // mã commit đầy đủ: phiên bản làm chuẩn
         "trackingRef": "refs/heads/main",                    // độ lỗi thời được xét theo ref này
         "owner": { "name": "Product team", "contact": "product@acme.example" },
         "role": "product-side context, owned by the product team",
         // định tuyến: khi nào mount này liên quan đến một tác vụ
         "categories": ["domain", "decisions"],
         "requiredWhen": ["a task changes how a plan or entitlement is represented"]
      }
   ]
}

Các lần cập nhật pin là những thay đổi đã qua xem xét đối với leji.json. Lớp chủ khai báo quan hệ; lớp ngang hàng giữ kho mã nguồn, chủ sở hữu, cổng xem xét, changelog và tuyên bố mức tuân thủ của riêng nó.

Làm việc với các mount

leji mounts hydrate --fetch      # hiện thực hoá phép chiếu của từng lớp ngang hàng tại pin
leji mounts status               # tính sẵn có, tính toàn vẹn và độ tụt lại của từng pin
leji mounts update-pin <name>    # đưa một pin tiến tới commit đã ghi nhận
leji mounts locate <name>        # nơi người đọc tìm lớp ngang hàng

Dùng hydrate --fetch để nạp về mọi phép chiếu tại pin tương ứng, đồng thời chủ động tải dữ liệu qua mạng. Dùng status để xem tính sẵn có, tính toàn vẹn và độ lỗi thời của pin. Dùng locate để lấy đường dẫn do resolver quản lý, nơi người đọc nên mở một lớp ngang hàng.

Để cập nhật một mount, hãy chạy trọn vòng lặp này: hydrate --fetch để đọc trạng thái các nguồn, status để xem mỗi pin đã tụt lại bao xa, update-pin để đẩy một pin tiến tới commit mà resolver đã ghi nhận, rồi hydrate lần nữa để nạp về phép chiếu tại pin mới. Việc đổi pin và nạp phép chiếu là hai hành động tách biệt, nên phần viết lại trở thành một diff có thể xem xét trước khi có bất kỳ nội dung nào đổi bên dưới chân bạn.

update-pin mặc định chạy offline: lệnh chỉ nâng pin tới mốc commit đã ghi nhận gần nhất mà một lần chạy thực sự quan sát được và ghi rõ điều đó trong đầu ra, thay vì ngầm coi mốc ấy là mới. Thêm --fetch để quan sát nguồn đã khai báo ngay trong lần chạy, việc này chỉ liên hệ đúng nguồn đó và không gì khác; nếu bất kỳ phần nào trong đó hỏng, lần chạy sẽ từ chối và để nguyên leji.json. Pin chỉ tiến về phía trước. Một đích không phải hậu duệ của pin hiện tại sẽ bị từ chối, trừ khi bạn nêu tên nó tường minh bằng --to <oid> và thêm --allow-non-fast-forward. Một nhánh thượng nguồn đã bị viết lại là lý do thường gặp để phải dùng tới cặp cờ đó; một lần chủ động lùi về một commit cũ hơn cũng cần tới chúng, vì phép kiểm xét quan hệ tổ tiên chứ không xét chuyện lịch sử có bị viết lại hay không. Tổ hợp đó được cảnh báo mỗi lần và được ghi vào đầu ra JSON, vì nó đẩy một pin tới một commit mà pin hiện tại không với tới. Dùng --dry-run để xem phần so sánh và phần viết lại mà không thực sự viết lại manifest; kết hợp với --fetch thì nó vẫn thực hiện các thao tác lên kho lưu trữ và lên mạng của cờ đó, nên các đối tượng và ref đã tải về vẫn nằm lại trong kho lưu trữ do resolver quản lý.

Chỉ các byte của pin được viết lại, nên thứ tự trường, cách định dạng và mọi khoá mà schema không mô hình hoá đều được giữ nguyên. Mục bộ nhớ đệm của pin cũ vẫn ở chỗ cũ: vì được định địa chỉ theo nội dung, nó đơn giản không còn được tham chiếu. Không có lệnh dọn dẹp nào; hãy tự tay xoá các mục cũ dưới .leji/mounts/ khi bạn muốn lấy lại dung lượng.

Việc nạp về không bao giờ công bố một phép chiếu dở dang. Vùng đệm nằm dưới .leji/mounts/, và init thêm đường dẫn đó vào .gitignore ở gốc. Hãy xem đường dẫn ấy là chi tiết triển khai: locate mới cho biết nên đọc lớp ngang hàng ở đâu, còn ghi cứng đường dẫn bộ nhớ đệm sẽ hỏng khi cách công bố thay đổi.

Viewer hiển thị trạng thái đó mà không cần terminal. leji viewer sinh một trang Manifest với đồ thị của lớp chủ và các lớp ngang hàng, kèm một dòng cho mỗi mount: tính sẵn có, độ trôi lệch, chủ sở hữu, pin và nguồn. Hãy sinh lại nó sau khi nạp về.

Tuyên bố mức federated

Một mount chưa nạp về chỉ tạo cảnh báo, không bao giờ làm hỏng bản build. CI có thể buộc kiểm tra tính sẵn có bằng leji validate --federation=available|required. Việc kiểm tra thông thường không tải về và cũng không đòi hỏi phải có đủ mọi mount.

Tính sẵn có tại chỗ không phải là mức tuân thủ. Pin phải với tới được từ một ref được quảng bá của source, và việc đó cần tới mạng. Hãy chạy leji conformance --federation=verify cho phép kiểm ấy. Nếu phép kiểm không với tới được nguồn, nó báo unknown; và unknown thì không bao giờ trao mức.

Việc xác minh là điều kiện cần, chưa đủ. Mức federated còn đòi hỏi rằng chính lớp ngữ cảnh này được một kho mã nguồn khác tiêu thụ dưới dạng một mount có ghim, rằng việc báo cáo pin lỗi thời đã có sẵn, và rằng boot profile cùng index được sinh ra đều làm nổi lên mọi lớp ngang hàng.

Hai điều đầu là khai theo quy trình, nên verifiedLevel không bao giờ khẳng định thay bạn. Việc một mount đã được nạp về trên máy cụ thể không phải đầu vào để xét mức tuân thủ.

Hãy chọn khuôn mẫu phân phối trước

Một git submodule chỉ gồm tài liệu cho phép nhiều kho mã nguồn cùng tiêu thụ một lớp ngữ cảnh. Federation thì nối nhiều nhóm mà mỗi nhóm đã sở hữu một lớp. Hai khuôn mẫu này trả lời những câu hỏi khác nhau, nên federation không thay thế submodule. Hướng dẫn áp dụng giữ trọn quy trình submodule.

Hãy đọc phân phối để có phần chuẩn tắc về bao đóng của phép chiếu, ranh giới lỗi, và toàn bộ quy tắc federation.