spec 1.0 · chuẩn tắc

Lớp ngữ cảnh

Một lớp ngữ cảnh Leji là tập hợp các tài liệu người đọc được, có đánh phiên bản và được quản trị, ghi lại cách một nhóm tư duy về công việc: ngôn ngữ của lĩnh vực, các bất biến của hệ thống, quy ước, ràng buộc bảo vệ và bản ghi quyết định. Người và agent đều đọc lớp này trong công việc thực tế, đồng thời đề xuất thay đổi qua cùng một cổng xem xét. Lớp ngữ cảnh được quản lý phiên bản để lịch sử, tính cập nhật và việc phê duyệt luôn kiểm chứng được; phần cơ chế nằm ở Yêu cầu bên dưới, còn đối tượng và cách thức tham gia nằm ở Tham gia.

Tham gia#

Việc tham gia một lớp ngữ cảnh dựa trên vai trò, không dựa trên công cụ. Đọc, đề xuất, xem xét và phê duyệt diễn ra qua bất kỳ giao diện nào giữ được ngữ nghĩa xem xét và phê duyệt của kho mã nguồn; hiểu biết trực tiếp về git hay dòng lệnh không phải là điều kiện để tham gia.

Ai có quyền truy cập thì đọc. Truy cập ở đây nghĩa là truy cập được trên thực tế qua công cụ thường ngày của nhóm, chứ không phải quyền shell vào kho mã nguồn.
Ai cũng đề xuất; người phê duyệt. Một đề xuất là một yêu cầu có chủ đích nhằm thay đổi lớp ngữ cảnh. Nó MAY do một người viết trực tiếp, do một agent sinh ra từ yêu cầu của một người, hoặc do một agent sinh ra từ công việc mà nó quan sát được. Trên thực tế, agent soạn phần lớn các thay đổi ngữ cảnh; phần đóng góp của con người không thể rút gọn được chính là quản trị: nêu ra chủ ý và phê duyệt điều gì trở thành chính thống. Người phê duyệt một thay đổi chịu trách nhiệm về ý nghĩa và hệ quả của nó, chứ không phải về việc đích thân thao tác hệ quản lý phiên bản.
Ý nghĩa cho người, bề mặt cho máy. Các tài liệu người đọc được mới là nguồn chuẩn tắc cho ngữ cảnh vận hành của một nhóm. Các tệp máy đọc được (manifest, index, changelog) tồn tại để công cụ định vị, lập index, kiểm tra và đồng bộ ý nghĩa đó; chúng không bao giờ thay thế nó.

Dạng chuẩn tắc của những luồng này, vòng tròn (ai cũng đọc, ai cũng đề xuất, người phê duyệt), được định nghĩa trong governance.md.

Đọc một bản ghi#

Nội dung được quản trị có hai loại, được định nghĩa trong content-categories.md: chủ ý, được duy trì như sự thật ở hiện tại, và bản ghi, là bằng chứng có ngày tháng mà trạng thái về sau thay thế chứ không sửa chữa. Cả hai đều được quản trị ngang nhau; khác biệt nằm ở chỗ người đọc được phép làm gì với thứ mình nạp. Người đọc MUST NOT coi một bản ghi là chủ ý hiện hành: một bản ghi cung cấp thông tin với tư cách bằng chứng đúng trong ranh giới mà nó tự nêu, và một người đọc trình bày các khẳng định của bản ghi như trạng thái hiện tại của sự việc, mà không nói rõ điều đó, là đang tự chế ra một tính cập nhật mà tài liệu vốn không có. Điều này phản chiếu quy tắc chế độ suy giảm bên dưới: trong cả hai trường hợp, nghĩa vụ của người đọc là biết, và nói ra, mình đang cầm trong tay thứ có tính cập nhật ở mức nào.

Yêu cầu#

Lớp ngữ cảnh MUST nằm trong một kho git và MUST được đánh phiên bản cùng với phần công việc mà nó mô tả (cùng kho mã nguồn, hoặc một kho ngữ cảnh riêng được tiêu thụ theo distribution.md). Chính kho git là thứ khiến lịch sử của lớp ngữ cảnh, tính cập nhật của bản checkout, và tính toàn vẹn chỉ thêm mới của changelog trở nên kiểm chứng được; công cụ tuân thủ suy ra cả ba từ đó. Đọc lớp ngữ cảnh mà không có kho mã nguồn đó là một chế độ được hỗ trợ nhưng bị suy giảm, định nghĩa ở Chế độ đọc.
Một kho mã nguồn áp dụng Leji MUST mang một tệp manifest, leji.json, ở gốc kho mã nguồn, hợp lệ theo context-manifest.schema.json. Manifest là điểm vào cho máy: nó khai báo phiên bản đặc tả (khoá tự đặt tên leji), tên lớp ngữ cảnh, gốc ngữ cảnh, đường dẫn boot profile, các ánh xạ danh mục, một tuyên bố mức tuân thủ tuỳ chọn, và quyền sở hữu. Nó MAY mang thêm một map agents gắn các định danh vai trò (ví dụ thought-partner, reviewer) với các tài liệu agent profile: giao thức triệu tập vai trò; map quyết định ai lấp vai trò đó. Map là một danh bạ các vai trò, không phải một thứ tự nạp: một liên kết, kể cả liên kết ở khoá default, không bao giờ khiến một profile được đọc; chỉ mục Nạp của boot profile mới làm việc đó.
Manifest MAY khai báo actor: những bên tham gia có tên, có thể lấp vào các vai trò. Mỗi actor khai báo những vai trò mà nó đủ điều kiện đảm nhận, cùng một khuôn lệnh cho từng vai trò. Việc lấy vai trò làm khoá cho câu lệnh chính là điểm mấu chốt: cùng một actor có thể cần một cách gọi khác nhau tuỳ theo nó đang lấp vai trò nào, nên một câu lệnh duy nhất cho mỗi actor không diễn đạt được điều đó. Tập vai trò khai báo của một actor và tập khoá câu lệnh của nó MUST trùng nhau. Ở nơi một vai trò đã có actor, agent profile gắn với vai trò đó MUST NOT khai báo thêm invocation: hai câu lệnh cùng có thẩm quyền mà không nói rõ cái nào thắng là một mâu thuẫn, và lớp ngữ cảnh giải quyết bằng cách chỉ khai báo câu lệnh ở một chỗ. Actor là tuỳ chọn và phần lớn lớp ngữ cảnh không cần tới. Chúng chỉ xứng đáng có mặt khi một vai trò có nhiều hơn một actor đủ điều kiện, hoặc khi một actor cần cách gọi khác nhau tuỳ vai trò nó đang lấp; chỉ một trong hai điều đó cũng đã đủ lý do, còn một vai trò chỉ có một actor và chỉ cần một câu lệnh thì đã được phục vụ bằng chính host và invocation của profile. Khai báo một actor không trao thẩm quyền nào: nó nói ai có thể được nhờ lấp một vai trò, không bao giờ nói ai được phê duyệt.

Khuôn lệnh, ở bất cứ đâu chúng xuất hiện (các giá trị commands của một actor và invocation.command của một agent profile), đều theo một quy tắc. Một khuôn là một dòng lệnh dành cho shell mà bên gọi chọn; những cách triệu tập không có hình dạng shell (một lời gọi argv có cấu trúc, một lần spawn trong cùng tiến trình) không biểu diễn được bằng các trường này ở nhánh 1.0. Mọi khuôn MUST mang chỗ giữ <prompt>, và mỗi lần xuất hiện MUST đứng thành một từ shell không trích dẫn của riêng nó ở vị trí đối số, không bao giờ nằm trong dấu trích dẫn hay dính liền với văn bản khác. Việc thay thế diễn ra một lượt: những lần xuất hiện có trong khuôn được viết ra sẽ được thay đồng thời, đúng một lần, nên chuỗi ký tự <prompt> nằm bên trong nội dung prompt vẫn là dữ liệu và không bao giờ bị bung ra lần nữa. Bên gọi sở hữu khâu chuyển giao, và hợp đồng ở đây là kết quả bắt buộc chứ không phải thuật toán trích dẫn: mỗi lần xuất hiện sinh ra đúng một đối số có giá trị bằng đúng nội dung prompt, và không phần nào của nó bị diễn giải như cú pháp shell. Cái mà schema kiểm được chỉ là sự hiện diện của một chỗ để thay thế; còn vị trí và cách chuyển giao là điều quy tắc này bắt buộc và bên gọi phải tôn trọng.
Manifest MUST khai báo một gốc ngữ cảnh (rootPath). Mặc định RECOMMENDED là docs/. Mọi đường dẫn của lớp ngữ cảnh đều theo kiểu POSIX, tính tương đối từ gốc kho mã nguồn. rootPath khai báo nơi lớp ngữ cảnh nằm; nó không đặt lại gốc cho các đường dẫn mà nó quản trị: các mục index, các trang được ghim, các đường dẫn tới profile và mọi đường dẫn khác trong mọi artifact của Leji đều được giải từ gốc kho mã nguồn, kể cả những đường dẫn có lặp lại tiền tố rootPath. homepage, logo và favicon của viewer là ngoại lệ: chúng được viết tương đối so với gốc ngữ cảnh, và một đường dẫn tương đối so với gốc kho mã nguồn nhưng nằm dưới gốc ngữ cảnh cũng được chấp nhận. Đường dẫn của danh mục và của machine SHOULD nằm dưới rootPath; bộ kiểm tra sẽ cảnh báo khi không phải vậy.
Lớp ngữ cảnh MUST có một boot profile theo boot-profile.md. Vị trí mặc định RECOMMENDED là docs/boot-profile.md; bootProfilePath trong manifest khai báo vị trí thực tế.
Nội dung của lớp ngữ cảnh MUST ưu tiên người đọc được. Markdown là định dạng RECOMMENDED cho văn xuôi; siêu dữ liệu có cấu trúc dùng frontmatter YAML hoặc các artifact JSON được định nghĩa trong machine-readable-surface.md. Một tài liệu chỉ máy mới đọc được thì không thuộc về lớp ngữ cảnh.
Lớp ngữ cảnh MUST có một người sở hữu được nêu tên (owners.primary trong manifest): một người chịu trách nhiệm về tính cập nhật của nó. Lớp ngữ cảnh vô chủ thì sẽ mục ruỗng.

Chế độ đọc: chính thống và suy giảm#

Một lớp ngữ cảnh được đọc theo hai chế độ; người đọc MUST biết mình đang ở chế độ nào, vì các bảo đảm là khác nhau. Người đọc xác định chế độ của mình từ những gì nó giải được: một leji.json tới được ở gốc kho mã nguồn cùng với hoặc một cây làm việc git hoặc danh tính phiên bản kho mã nguồn do nền tảng chủ quản cung cấp, là chính thống; nội dung tới được dưới dạng tệp thuần mà không có cả hai thứ đó là suy giảm.

Chính thống. Người đọc giải được lớp ngữ cảnh qua chính kho git của nó: một bản checkout, hoặc khung nhìn kho mã nguồn của nền tảng chủ quản. Lịch sử, tính cập nhật của bản checkout và tính toàn vẹn của changelog đều kiểm chứng được, và nội dung đã phê duyệt được biết là còn hiệu lực tính tới phiên bản đang đọc.
Suy giảm. Người đọc tiếp cận lớp ngữ cảnh như nội dung tệp thuần, không có cây làm việc git hay siêu dữ liệu phiên bản nào truy cập được: tệp được tải lên, được đồng bộ, hoặc được sao chép sang một giao diện khác mà không kèm kho mã nguồn. Việc đọc tệp thuần là hạng nhất về mặt đọc (tài liệu vốn đã bắt buộc phải người đọc được, và changelog máy đọc được vẫn truyền tải được mức độ mới đã khai báo), nhưng một người đọc ở chế độ suy giảm MUST coi tính cập nhật của bản checkout và trạng thái phê duyệt là không rõ, không bao giờ coi là còn hiệu lực (xem governance.md, phần Độ tươi). Changelog là bề mặt mang tính di động cho mức độ mới đã khai báo trong chế độ này; tự nó không chứng minh được rằng bản sao khớp với kho mã nguồn chính thống.

Đọc ở chế độ suy giảm mở rộng phạm vi ai và cái gì có thể tiêu thụ một lớp ngữ cảnh; nó không bao giờ là một con đường dẫn tới thẩm quyền chính thống. Một thay đổi chỉ trở thành chính thống qua cổng xem xét dựa trên git, và một bản sao suy giảm không thể thoả mãn các phép kiểm ở chế độ chính thống mà federation phụ thuộc vào (tính cập nhật của pin, trạng thái pin lỗi thời, sự nguyên vẹn của quyền sở hữu, và quyền truy cập mount bị giới hạn theo distribution.md).

Quy tắc vendor adapter#

Các tệp cấu hình của agent host (ví dụ CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules, .cursor/rules, .windsurfrules, .github/copilot-instructions.md):

MUST NOT giữ nội dung chính thống của lớp ngữ cảnh.
Nếu có mặt, MUST chuyển hướng tới boot profile (thường là một con trỏ một dòng).
MAY mang những cơ chế riêng của host mà ngoài agent host đó ra thì không có nghĩa gì (chọn mô hình, thiết lập trình chạy), miễn là không có tri thức nào của nhóm nằm ở đó.
Công cụ tìm ra cần kiểm tra những điểm vào nào từ hai nguồn: danh sách vendorAdapters tuỳ chọn trong manifest, và một tập well-known đã công bố (chính các tệp nêu trên). Danh sách ví dụ ở trên chính là tập well-known của nhánh này; một host có điểm vào không nằm trong đó chỉ được kiểm tra khi manifest nêu tên nó trong vendorAdapters.

Các quy ước điểm vào hiện có chỉ cho agent host biết phải tìm ở đâu; Leji định nghĩa agent sẽ thấy gì ở đó. Mọi bên tham gia cùng đọc một nguồn sự thật duy nhất.

Lớp ngữ cảnh không phải là gì (tham khảo)#

Không phải một wiki. Không có gì buộc wiki phải luôn cập nhật. Lớp ngữ cảnh duy trì được sức sống vì agent đọc nó trong mọi tác vụ (ngữ cảnh sai tạo ra đầu ra sai và bị nhận ra ngay), vì các thay đổi đi qua vòng xem xét như code và vì công cụ giúp nhận biết nội dung lỗi thời.
Không phải tài liệu theo nghĩa truyền thống. Tài liệu truyền thống mô tả hệ thống làm gì sau khi công việc đã hoàn tất. Lớp ngữ cảnh mô tả cách nhóm suy nghĩ ở hiện tại và được cả người lẫn agent đọc liên tục.
Không phải một mẫu để nhập về. Ngữ cảnh vay mượn sẽ lỗi thời ngay lập tức. Giá trị của lớp ngữ cảnh nằm ở chỗ nó phản ánh chính nhóm đó; Leji chuẩn hoá hình thái và cách quản trị, chứ không chuẩn hoá nội dung.