Tiếng Việt
English简体中文日本語Português (Brasil)EspañolTiếng Việt

spec 1.0 · tra cứu

Manifest: leji.json

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.

Điểm vào cho máy của một lớp ngữ cảnh Leji. Nằm ở gốc kho mã nguồn với tên leji.json.

Manifest là tên tệp cố định duy nhất của Leji: công cụ luôn có thể tìm đúng tệp này ở gốc kho mã nguồn.

Các dòng mô tả trường được sinh ra từ schema, nên nội dung ở đây luôn khớp với hợp đồng. Trang này trình bày các trường cấp cao nhất cùng một số trường lồng nhau; với những cấu trúc sâu hơn, chẳng hạn các vai trò và câu lệnh của một actor, hãy đọc thẳng schema. Các trường bắt buộc đều được đánh dấu.

Các trường

#lejistringbắt buộc

Nhánh đặc tả Leji mà lớp ngữ cảnh này nhắm tới, ví dụ "1.0". Khoá tự đặt tên theo quy ước của OpenAPI và cho biết tệp này là một manifest Leji.

Mẫu ^\d+\.\d+$

#namestringbắt buộc

Một định danh ngắn, ổn định cho lớp ngữ cảnh này, ví dụ "acme-billing-context".

#descriptionstring

Tóm tắt một dòng về phạm vi lớp ngữ cảnh này bao phủ.

#rootPathstringbắt buộc

Gốc ngữ cảnh, đường dẫn POSIX tương đối so với gốc kho mã nguồn. Nó khai báo lớp ngữ cảnh nằm ở đâu; nó không tính lại 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 các tệp Leji đều phân giải từ gốc kho mã nguồn. 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.

Mẫu ^(?!/)(?!\./)(?!.*(^|/)\.\.(/|$))(?!.*\\).*$

#bootProfilePathstringbắt buộc

Đường dẫn tới boot profile, điểm vào không phụ thuộc agent mà mọi host và mọi người đều bắt đầu từ đó.

Mẫu ^(?!/)(?!\./)(?!.*(^|/)\.\.(/|$))(?!.*\\).+\.md$

#categoriesobjectbắt buộc

Ánh xạ từ danh mục logic sang tệp index. Khoá là năm định danh danh mục; mỗi khoá trỏ tới một hoặc nhiều tệp index được biên soạn, liệt kê nội dung của danh mục đó.

Mỗi khoá bên dưới đều có cùng một hình dạng:

indexesmảng chuỗibắt buộc

Một hoặc nhiều tệp index cho danh mục này, đường dẫn tương đối so với gốc kho mã nguồn. Mỗi tệp index là markdown được biên soạn, mang một khối leji-index có rào, trong đó các dòng - path: <thư-mục-hoặc-tệp> chọn nội dung thuộc về danh mục này. Nội dung vẫn nằm nguyên chỗ của nó; tệp index chỉ khai báo việc đưa vào.

domainobject

Nơi nội dung domain nằm: ngôn ngữ nghiệp vụ và ngữ nghĩa sản phẩm.

systemobject

Nơi nội dung system nằm: kiến trúc và những bất biến mà mọi thay đổi phải tôn trọng.

practiceobject

Nơi nội dung practice nằm: quy ước và những khuôn mẫu đã được kiểm chứng.

governanceobject

Nơi nội dung governance nằm: các ràng buộc bảo vệ cho agent và các quy tắc vận hành.

decisionsobject

Nơi các bản ghi quyết định nằm: những bản ghi có ngày tháng về lý do mọi thứ ở trạng thái hiện tại.

#machineobject

Vị trí của các tệp máy đọc được: index, changelog, các profile, và các bản ghi quyết định.

indexPathstring

Đường dẫn tới context index được sinh ra.

changelogPathstring

Đường dẫn tới context changelog máy đọc được.

agentProfilesPathstring

Thư mục chứa các tài liệu agent profile.

decisionRecordsPathstring

Thư mục chứa các bản ghi quyết định.

#agentsmap

Gắn vai trò với agent profile. Khoá là định danh vai trò (ví dụ "thought-partner", "reviewer"); giá trị là đường dẫn tới tài liệu agent profile. Các quy trình gọi vai trò; map này quyết định ai đảm nhận vai trò đó.

#actorsmap

Danh bạ các actor có thể đảm nhận vai trò; không bắt buộc. Khoá là định danh actor ổn định. Một actor khai báo những vai trò nó đủ điều kiện đảm nhận và một mẫu câu lệnh cho mỗi vai trò. Hãy dùng 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 đảm nhận; chỉ một trong hai điều đó đã là đủ lý do. 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ởi host và invocation của chính agent profile.

#ownersobjectbắt buộc

Ai chịu trách nhiệm về sức khoẻ của lớp ngữ cảnh. Chủ sở hữu chịu trách nhiệm giữ cho lớp ngữ cảnh luôn hiện thời và được tỉa gọn; không phải chỉ mình họ viết hay biên soạn nội dung đó (governance.md).

Mỗi khoá bên dưới đều có cùng một hình dạng:

namestringbắt buộc

Tên của người đó.

contactstring

Cách liên hệ với họ, ví dụ một địa chỉ email.

primaryobjectbắt buộc

Người chịu trách nhiệm về tính hiện thời của lớp ngữ cảnh. Lớp ngữ cảnh không có chủ thì sẽ mục ruỗng.

continuityobject

Không bắt buộc. Một người khác mang đúng trách nhiệm đó khi người chính vắng mặt hoặc rời đi; những lần áp dụng có hỗ trợ nên chỉ định một người trước khi bên hỗ trợ rút đi. Nêu lại chính người chính thì không tạo ra tính liên tục nào, và một agent không thể đảm nhận: chủ sở hữu là những con người chịu trách nhiệm.

#conformanceobject

Mức tuân thủ mà lớp ngữ cảnh này tuyên bố, công cụ kiểm được.

claimedLevel"core" · "indexed" · "governed" · "federated"

Mức tuân thủ được tuyên bố: core, indexed, governed, hoặc federated.

claimedAtstring

Ngày ISO 8601 tuyên bố được khẳng định lần gần nhất.

#federationobject

Những lớp ngang hàng được mount vào kho mã nguồn này (bản đặc tả: distribution.md, khuôn mẫu 3). Vòng tròn ghép các quyền sở hữu lại với nhau; nó không tập trung hoá chúng.

mountsmảng các đối tượng

Mỗi mount là một lớp ngữ cảnh ngang hàng được đọc tại một phiên bản đã ghim, thông qua phép chiếu lớp do resolver nạp về, đồng thời giữ nguyên kho mã nguồn, quyền sở hữu và cổng xem xét của riêng nó. Nội dung được tạo thành tệp cục bộ nằm trong bộ nhớ đệm của resolver, được Git bỏ qua và không bao giờ được commit vào đây.

namestringbắt buộc

Tên của lớp ngang hàng; phải khớp với name trong manifest của chính lớp đó.

sourcestringbắt buộc

Địa chỉ kho mã nguồn đã chuẩn hoá của lớp ngang hàng: một URL từ xa dạng https://, ssh://, hoặc kiểu SCP. Đây là gốc phân giải và là không gian tên của pin. Đường dẫn tệp cục bộ chỉ hợp lệ trong những gợi ý cục bộ của máy, không bao giờ ở đây.

pinstringbắt buộc

Id commit đầy đủ và bất biến (SHA-1 hoặc SHA-256) của bản sửa đổi lớp ngang hàng mà lớp chủ này đọc. Đây là trạng thái mong muốn do manifest giữ: việc cập nhật pin là hành động biên soạn có chủ ý và đã qua xem xét.

trackingRefstring

Ref đối chiếu có tên đầy đủ trên nguồn (refs/heads/* hoặc refs/tags/*), dùng làm mốc cho báo cáo pin lỗi thời và kiểm tra khả năng truy cập trong federation; không bắt buộc. Nếu vắng, nhánh mặc định mà nguồn quảng bá sẽ được dùng và được ghi lại trong kết quả câu lệnh.

ownerobjectbắt buộc

Chủ sở hữu của lớp ngang hàng. Quyền sở hữu vẫn thuộc về nhóm của lớp đó; lớp chủ không bao giờ hấp thụ nội dung của nó.

rolestring

Lớp ngang hàng này mang những gì, viết bằng lời, ví dụ "ngữ cảnh phía sản phẩm". Dành cho con người; việc định tuyến dùng các trường có cấu trúc bên dưới.

categoriesmảng gồm "domain" · "system" · "practice" · "governance" · "decisions"

Những phạm vi danh mục nội dung mà lớp ngang hàng này có thể trả lời. Chỉ là siêu dữ liệu định tuyến; nội dung của lớp ngang hàng vẫn nằm ở lớp đó. Bắt buộc với mức tuân thủ federated.

topicsmảng chuỗi

Các nhãn chủ đề ngắn mà lớp chủ nhìn thấy, dùng để định tuyến một tác vụ tới lớp ngang hàng này, ví dụ "billing", "checkout". Chỉ là siêu dữ liệu định tuyến.

requiredWhenmảng chuỗi

Những điều kiện tác vụ mà ở đó người đọc phải phân giải mount này, hoặc dừng lại và báo rằng ngữ cảnh chưa đầy đủ nếu không phân giải được (dừng an toàn). Lớp chủ nhìn thấy được; không được tiết lộ bất cứ điều gì người đọc của lớp chủ không được phép thấy.

#vendorAdaptersmảng chuỗi

Các tệp điểm vào của nhà cung cấp có mặt trong kho mã nguồn này; mỗi tệp phải chuyển hướng về boot profile.

#viewerobject

Tuỳ chọn trình bày mà leji viewer đọc. Đây là cấu hình tiện lợi, không mang tính chuẩn tắc; bản thân việc trình bày nằm ngoài phạm vi chuẩn tắc.

portinteger

Cổng ưa dùng cho bản xem trước cục bộ của leji viewer serve. Cờ --port sẽ ghi đè; mặc định là 5354 (LEJI trên bàn phím điện thoại).

logostring

Ảnh logo cho viewer, dạng đường dẫn nằm dưới gốc ngữ cảnh (ví dụ "assets/logo.svg"). Mặc định là dấu hiệu của Leji.

titlestring

Tiêu đề hiển thị của viewer (đầu thanh bên và tiêu đề trang). Mặc định là tên lớp ngữ cảnh.

agentsLabelstring

Nhãn thanh bên cho nhóm agent profile (dùng emoji cũng được). Mặc định là "🤖 Agents". Nhóm này liệt kê các agent profile của lớp và được sắp xếp theo viewer.groupOrder như mọi nhóm khác.

faviconstring

Favicon cho viewer, dạng đường dẫn nằm dưới gốc ngữ cảnh (ví dụ "assets/icon.svg"). Mặc định là dấu hiệu của Leji.

homepagestring

Trang đích của viewer, dạng đường dẫn tương đối so với gốc ngữ cảnh (ví dụ "README.md"). Mặc định là tệp overview.md được tạo sẵn.

pinsmảng các phần tử

Các trang được ghim lên đầu thanh bên: đường dẫn markdown tương đối so với gốc kho mã nguồn, hoặc {path, label} nếu muốn nhãn tự biên soạn. Ghim boot profile sẽ thay cho dòng mặc định của nó.

groupOrdermảng chuỗi

Trình tự nhóm trên thanh bên do người dùng biên soạn, theo đúng nhãn nhóm (chính là H1 của tệp index). Những nhóm được liệt kê xếp trước theo thứ tự này; các nhóm còn lại theo sau theo thứ tự suy ra.

themeobject

Ghi đè chủ đề của viewer.

primarystring

Màu chính/màu nhấn dạng màu CSS hex (ví dụ "#009F71"). Nó chi phối khung viewer, các trạng thái đang hoạt động và màu nhấn của sơ đồ; còn liên kết trong phần thân và mã nội dòng dùng tông màu dễ tiếp cận đã cố định, trừ khi viewer.theme.link cung cấp một màu vượt qua được ngưỡng tương phản.

linkstring

Màu liên kết dạng màu CSS hex (ví dụ "#5A50F9"). Chỉ áp dụng cho liên kết trong phần thân và mã nội dòng khi nó đạt tỉ lệ 4,5:1 so với nền mã nội dòng, là nền hẹp hơn trong hai nền mà chúng nằm lên; nếu không, tông màu dễ tiếp cận đã cố định vẫn được giữ và leji view / leji export sẽ cảnh báo.

mermaidboolean

Kết xuất các khối mã ```mermaid có rào thành sơ đồ trong viewer. Mặc định là true.

poweredByboolean

Hiển thị dấu hiệu nhỏ "Powered by Leji" ở góc viewer. Mặc định là true; đặt false để bỏ đi.

categoryEmojisobject

Ghi đè emoji mặc định hiển thị bên cạnh mỗi danh mục trong bản đồ lớp được sinh ra. (Các nhóm trên thanh bên được đặt nhãn theo chính H1 của mỗi tệp index.)

Một ví dụ đầy đủ

Ví dụ về một lớp ngữ cảnh federation ở quy mô tổ chức, có mount một lớp ngang hàng, sử dụng nhiều trường hơn hẳn manifest ngoài thực tế. Phần lớn lớp ngữ cảnh chỉ khai báo những trường thực sự dùng: leji init tạo sẵn một số trường trong đó, còn manifest ở mức core thì ngắn hơn nhiều.

Cấu trúc này có hai điểm dễ gây nhầm lẫn: mỗi danh mục trỏ tới các tệp index do người viết ra chứ không trỏ tới thư mục nội dung; còn agents gắn định danh vai trò với tài liệu profile. Đây là danh bạ vai trò, không phải thứ tự nạp, vì vậy việc gắn một profile không bao giờ tự động khiến profile đó được đọc.

Có một trường mang tính điều kiện chứ không mang tính khai báo: viewer.theme.link chỉ tô màu cho liên kết trong phần thân và cho mã nội dòng khi nó đạt tỉ lệ tương phản 4,5:1 so với nền mã nội dòng của viewer, còn một giá trị không đạt ngưỡng thì được báo là cảnh báo trong khi tông màu dễ tiếp cận đã cố định vẫn được giữ nguyên.

{
  "$schema": "https://leji.org/schemas/v1.0/context-manifest.schema.json",
  "leji": "1.0",
  "name": "acme-context",
  "description": "Organization-wide context layer for Acme: consumed by product repos and composing one sibling layer.",
  "rootPath": "docs/",
  "bootProfilePath": "docs/boot-profile.md",
  "categories": {
    "domain": {
      "indexes": [
        "docs/context/domain.md"
      ]
    },
    "system": {
      "indexes": [
        "docs/context/system.md"
      ]
    },
    "practice": {
      "indexes": [
        "docs/context/practice.md"
      ]
    },
    "governance": {
      "indexes": [
        "docs/context/governance.md"
      ]
    },
    "decisions": {
      "indexes": [
        "docs/context/decisions.md"
      ]
    }
  },
  "machine": {
    "indexPath": "docs/context-index.json",
    "changelogPath": "docs/context-changelog.json",
    "agentProfilesPath": "docs/agents/",
    "decisionRecordsPath": "docs/decisions/"
  },
  "agents": {
    "core": "docs/agents/core.md",
    "reviewer": "docs/agents/reviewer.md"
  },
  "owners": {
    "primary": {
      "name": "Sam Park",
      "contact": "sam@acme.example"
    },
    "continuity": {
      "name": "Ada Okafor",
      "contact": "ada@acme.example"
    }
  },
  "conformance": {
    "claimedLevel": "federated",
    "claimedAt": "2026-06-12"
  },
  "federation": {
    "mounts": [
      {
        "name": "acme-product-context",
        "source": "https://github.com/acme/product-context",
        "pin": "7d3f2a19c4e8b6a0d5f1c2e9b8a7f6d5c4b3a2e1",
        "trackingRef": "refs/heads/main",
        "owner": {
          "name": "Product team",
          "contact": "product@acme.example"
        },
        "role": "product-side context, owned and curated by the product team",
        "categories": [
          "domain",
          "decisions"
        ],
        "topics": [
          "pricing",
          "entitlements",
          "billing plans"
        ],
        "requiredWhen": [
          "a task changes how a plan, price, or entitlement is represented"
        ]
      }
    ]
  },
  "vendorAdapters": [
    "CLAUDE.md",
    "AGENTS.md"
  ],
  "viewer": {
    "port": 5354,
    "title": "Acme Billing",
    "logo": "assets/brand.svg",
    "favicon": "assets/icon.svg",
    "pins": [
      "docs/dashboard.md",
      "docs/TODO.md"
    ],
    "theme": {
      "primary": "#009F71",
      "link": "#007D59"
    }
  }
}

Hãy xem bề mặt máy đọc được để biết manifest liên hệ thế nào với index, changelog và các profile, cùng đánh phiên bản cho khoá nhánh đặc tả leji.