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

spec 1.0 · chuẩn tắc

Context index của Leji

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.

Bản đồ được sinh ra của lớp ngữ cảnh. Không bao giờ bảo trì bằng tay; hãy sinh lại mỗi khi có thay đổi.

$id chuẩn: https://leji.org/schemas/v1.0/context-index.schema.json
Tệp gốc: context-index.schema.json

Các trường

#schemaVersionstringbắt buộc

Nhánh đặc tả Leji mà tệp này được viết theo, ví dụ "1.0".

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

#generatedAtstringbắt buộc

Dấu thời gian ISO 8601 lúc index được sinh ra.

Mẫu ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])[T ].+$

#generatorobject

Công cụ đã sinh ra index này.

namestring

Tên công cụ sinh ra, ví dụ "leji".

versionstring

Phiên bản của công cụ sinh ra.

#rootPathstringbắt buộc

Gốc ngữ cảnh mà index này được sinh cho; khớp với rootPath của manifest. Đường dẫn trong các mục là tương đối so với gốc kho mã nguồn, không tính lại theo gốc ngữ cảnh.

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

#entriesmảng các đối tượngbắt buộc

Mỗi tài liệu được đưa vào index của lớp ngữ cảnh có một mục. Mỗi id và mỗi path là duy nhất trên toàn bộ các mục; bộ kiểm tra tham chiếu thực thi điều này (JSON Schema không làm được, vì ràng buộc nằm ở một trường con chứ không phải cả đối tượng).

idstringbắt buộc

Định danh ổn định; việc đổi tên và di chuyển cập nhật path, không bao giờ đổi id.

pathstringbắt buộc

Đường dẫn tới tài liệu, tương đối so với gốc kho mã nguồn.

titlestringbắt buộc

Tiêu đề dạng người đọc được, lấy từ tiêu đề đầu tiên của tài liệu hoặc từ frontmatter.

category"domain" · "system" · "practice" · "governance" · "decisions"bắt buộc

Tài liệu này thuộc danh mục nội dung nào.

kind"intent" · "record"

Tài liệu là sự thật hiện tại được duy trì (intent) hay bằng chứng có ngày tháng (record). Bỏ trống nghĩa là intent.

datestring

Ngày của một record, chỉ lấy từ trường date hợp lệ trong frontmatter.

summarystring

Tóm tắt một dòng về tài liệu, dùng cho việc định tuyến và điều hướng.

tagsmảng chuỗi

Các nhãn tự do; không bắt buộc.

ownersmảng chuỗi

Chủ sở hữu của tài liệu này; không bắt buộc.

lastModifiedstring

Ngày ISO 8601 tài liệu thay đổi lần cuối, lấy từ hệ quản lý phiên bản nếu có.

contentHashstring

Hash nội dung của tài liệu, dùng để phát hiện trôi lệch và những lần di chuyển ổn định.

freshnessobject

Hạn xem xét lại của tài liệu này.

reviewAfterstring

Ngày theo ISO 8601, sau ngày đó tài liệu nên được xem xét lại xem đã lỗi thời chưa.

linksmảng chuỗi

Các tham chiếu đi ra từ tài liệu này; không bắt buộc.

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

Các bản ghi định tuyến cho những lớp ngữ cảnh ngang hàng được federation, suy ra từ federation.mounts của manifest (bản đặc tả: distribution.md, machine-readable-surface.md). Chỉ là siêu dữ liệu định tuyến: công cụ KHÔNG ĐƯỢC sao chép các mục index hay câu chữ của lớp ngang hàng vào đây. Một bản ghi mount không bao giờ tiết lộ những gì người đọc của lớp chủ không được phép thấy.

namestringbắt buộc

Tên của lớp ngang hàng; khớp với tên 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.

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ủ đọc.

trackingRefstring

Ref đối chiếu có tên đầy đủ, nếu được khai báo, dùng làm mốc để kiểm tra khả năng truy cập và độ lỗi thời.

ownerobjectbắt buộc

Chủ sở hữu của lớp ngang hàng.

namestringbắt buộc
contactstring
rolestring

Mô tả bằng lời về những gì lớp ngang hàng mang.

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.

topicsmảng chuỗi

Các nhãn chủ đề ngắn dùng cho việc định tuyến theo mức liên quan.

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, nếu không thì dừng an toàn.

Schema và ví dụ

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://leji.org/schemas/v1.0/context-index.schema.json",
  "title": "Leji context index",
  "description": "Generated map of the context layer. Never hand-maintained; regenerate on change.",
  "type": "object",
  "required": [
    "schemaVersion",
    "generatedAt",
    "rootPath",
    "entries"
  ],
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "description": "Optional pointer to this schema, for editor validation and tooling.",
      "type": "string"
    },
    "schemaVersion": {
      "description": "The Leji spec line this artifact was written against, e.g. \"1.0\".",
      "type": "string",
      "pattern": "^\\d+\\.\\d+$"
    },
    "generatedAt": {
      "description": "ISO 8601 timestamp when the index was generated.",
      "type": "string",
      "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])[T ].+$"
    },
    "generator": {
      "description": "The tool that generated this index.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "name": {
          "description": "Name of the generating tool, e.g. \"leji\".",
          "type": "string"
        },
        "version": {
          "description": "Version of the generating tool.",
          "type": "string"
        }
      }
    },
    "rootPath": {
      "description": "The context layer root this index was generated for; mirrors the manifest's rootPath. Entry paths are repository-root-relative, not re-based under it.",
      "type": "string",
      "pattern": "^(?!/)(?!\\./)(?!.*(^|/)\\.\\.(/|$))(?!.*\\\\).*$"
    },
    "entries": {
      "description": "One entry per indexed document in the context layer. Each `id` and each `path` is unique across entries; the reference validator enforces this (JSON Schema cannot, since the constraint is on a sub-field, not the whole object).",
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "path",
          "title",
          "category"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "description": "Stable identifier; renames and moves update the path, never the id.",
            "type": "string",
            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
          },
          "path": {
            "description": "Repository-root-relative path to the document.",
            "type": "string",
            "pattern": "^(?!/)(?!\\./)(?!.*(^|/)\\.\\.(/|$))(?!.*\\\\).+$"
          },
          "title": {
            "description": "Human-readable title, from the document's first heading or frontmatter.",
            "type": "string",
            "minLength": 1
          },
          "category": {
            "description": "Which content category this document belongs to.",
            "enum": [
              "domain",
              "system",
              "practice",
              "governance",
              "decisions"
            ]
          },
          "kind": {
            "description": "Whether the document is maintained present truth (intent) or dated evidence (record). Absent means intent.",
            "enum": [
              "intent",
              "record"
            ]
          },
          "date": {
            "description": "A record's date, sourced only from valid frontmatter date.",
            "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$",
            "type": "string"
          },
          "summary": {
            "description": "One-line summary of the document, for routing and navigation.",
            "type": "string"
          },
          "tags": {
            "description": "Optional free-form tags.",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "owners": {
            "description": "Optional owners of this document.",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "lastModified": {
            "description": "ISO 8601 date the document last changed, from version control where available.",
            "type": "string",
            "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])([T ].*)?$"
          },
          "contentHash": {
            "description": "Hash of the document's contents, used to detect drift and stable moves.",
            "type": "string"
          },
          "freshness": {
            "description": "Review horizon for this document.",
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "reviewAfter": {
                "description": "ISO 8601 date after which the document should be reviewed for staleness.",
                "type": "string",
                "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$"
              }
            }
          },
          "links": {
            "description": "Optional outbound references from this document.",
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "mounts": {
      "description": "Routing records for federated sibling context layers, derived from the manifest's federation.mounts (spec: distribution.md, machine-readable-surface.md). Routing metadata only: tooling MUST NOT copy a sibling's index entries or prose here. A mount record never discloses what the host's audience may not see.",
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "name",
          "source",
          "pin",
          "owner"
        ],
        "additionalProperties": false,
        "properties": {
          "name": {
            "description": "The sibling layer's name; matches the name in the sibling's own manifest.",
            "type": "string",
            "minLength": 1
          },
          "source": {
            "description": "Normalized repository locator of the sibling layer.",
            "type": "string",
            "minLength": 1
          },
          "pin": {
            "description": "Full immutable commit id (SHA-1 or SHA-256) of the sibling revision the host reads.",
            "type": "string",
            "pattern": "^([0-9a-f]{40}|[0-9a-f]{64})$"
          },
          "trackingRef": {
            "description": "Fully qualified witness ref reachability and staleness are compared against, when declared.",
            "type": "string",
            "pattern": "^refs/(heads|tags)/.+$"
          },
          "owner": {
            "description": "The owner of the sibling layer.",
            "type": "object",
            "required": [
              "name"
            ],
            "additionalProperties": false,
            "properties": {
              "name": {
                "type": "string",
                "minLength": 1
              },
              "contact": {
                "type": "string"
              }
            }
          },
          "role": {
            "description": "Prose description of what the sibling carries.",
            "type": "string"
          },
          "categories": {
            "description": "Content-category scopes this sibling can answer for.",
            "type": "array",
            "items": {
              "enum": [
                "domain",
                "system",
                "practice",
                "governance",
                "decisions"
              ]
            }
          },
          "topics": {
            "description": "Short topic labels for relevance routing.",
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          },
          "requiredWhen": {
            "description": "Task conditions under which a reader must resolve this mount or fail closed.",
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1
            }
          }
        }
      }
    }
  }
}

Một context index được sinh ra, CLI sinh lại mỗi khi có thay đổi.

{
  "$schema": "https://leji.org/schemas/v1.0/context-index.schema.json",
  "schemaVersion": "1.0",
  "generatedAt": "2026-07-31T12:23:37.412Z",
  "generator": {
    "name": "leji",
    "version": "1.3.1"
  },
  "rootPath": "docs/",
  "entries": [
    {
      "id": "adopt-leji",
      "path": "docs/decisions/0001-adopt-leji.md",
      "title": "Áp dụng lớp ngữ cảnh Leji",
      "category": "decisions",
      "kind": "record",
      "date": "2026-06-10",
      "lastModified": "2026-06-17",
      "contentHash": "sha256:9680ba24ad268894"
    },
    {
      "id": "glossary",
      "path": "docs/domain/glossary.md",
      "title": "Bảng thuật ngữ",
      "category": "domain",
      "kind": "intent",
      "summary": "Ở Acme, invoice, credit note và settlement nghĩa là gì.",
      "lastModified": "2026-06-17",
      "contentHash": "sha256:22d9bcc4fe0ce860"
    },
    {
      "id": "system-invariants",
      "path": "docs/system/invariants.md",
      "title": "Bất biến hệ thống",
      "category": "system",
      "kind": "intent",
      "summary": "Xử lý tiền, quy tắc chỉ nối thêm của sổ cái, ranh giới giữa các dịch vụ.",
      "lastModified": "2026-06-17",
      "contentHash": "sha256:6e179b4fa71bd5ad",
      "freshness": {
        "reviewAfter": "2026-12-10"
      }
    }
  ]
}

← Tất cả schema