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

spec 1.0 · chuẩn tắc

Context changelog 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 ghi máy đọc được, chỉ nối thêm, về các thay đổi của lớp ngữ cảnh.

$id chuẩn: https://leji.org/schemas/v1.0/context-changelog.schema.json
Tệp gốc: context-changelog.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+$

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

Các thay đổi của lớp ngữ cảnh. Thứ tự chuẩn được suy ra bằng cách sắp xếp tăng dần theo (date, id); vị trí trong mảng không mang ý nghĩa. Mục mới có thể nằm ở bất cứ đâu; những mục cũ nhất có thể được gộp lại bằng một mục compaction. Phải có ít nhất một mục: một changelog sinh ra đã rỗng là không hợp lệ, và việc gộp bao giờ cũng để lại mục compaction của chính nó.

idstringbắt buộc

Định danh ổn định cho mục thay đổi này, duy nhất trong phạm vi changelog.

datestringbắt buộc

ISO 8601 theo UTC: một ngày lịch YYYY-MM-DD (xếp thứ tự như đầu ngày) hoặc một dấu thời gian đầy đủ kết thúc bằng Z, ví dụ 2026-06-13T15:04:05Z. Không cho phép độ lệch múi giờ và thời gian không có múi giờ, nhờ vậy thứ tự chữ cũng là thứ tự thời gian.

type"added" · "changed" · "deprecated" · "removed" · "fixed" · "decision" · "governance" · "compaction"bắt buộc

Loại thay đổi.

summarystringbắt buộc

Mô tả một dòng về những gì đã thay đổi.

pathsmảng chuỗibắt buộc

Các đường dẫn tương đối so với gốc kho mã nguồn mà thay đổi này chạm tới. Ít nhất một đường dẫn; một mục compaction ghi hợp của những đường dẫn nó đã gộp, hoặc chính đường dẫn của changelog khi hợp đó rỗng.

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

Các danh mục nội dung mà thay đổi này chạm tới.

decisionRefsmảng chuỗi

Id của các bản ghi quyết định liên quan tới thay đổi này.

proposedBystring

Con người hoặc agent đã đề xuất thay đổi.

approvedBystring

Con người đã phê duyệt thay đổi.

breakingboolean

Thay đổi này có phá vỡ những nơi tiêu thụ lớp ngữ cảnh hay không.

compactedobject

Bắt buộc với mục compaction: việc gộp đã lấy đi những gì ở đầu cũ nhất.

entriesintegerbắt buộc

Việc gộp này đã lấy đi bao nhiêu mục ở đầu cũ nhất.

firstIdstringbắt buộc

Id của mục cũ nhất bị việc gộp này lấy đi.

lastIdstringbắt buộc

Id của mục mới nhất bị việc gộp này lấy đi.

Schema và ví dụ

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://leji.org/schemas/v1.0/context-changelog.schema.json",
  "title": "Leji context changelog",
  "description": "Append-only machine-readable record of context layer changes.",
  "type": "object",
  "required": [
    "schemaVersion",
    "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+$"
    },
    "entries": {
      "description": "Context layer changes. Canonical order is derived by sorting on (date, id) ascending; array position is not significant. New entries may appear anywhere; the oldest may be compacted with a compaction entry. At least one entry: a born-empty changelog is invalid, and compaction always leaves its compaction entry behind.",
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": [
          "id",
          "date",
          "type",
          "summary",
          "paths"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "description": "Stable identifier for this change entry, unique within the changelog.",
            "type": "string",
            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
          },
          "date": {
            "description": "ISO 8601 in UTC: a calendar date YYYY-MM-DD (ordered as start of day) or a full timestamp ending in Z, e.g. 2026-06-13T15:04:05Z. Offsets and zoneless times are not allowed, so lexical order is chronological.",
            "type": "string",
            "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])(T([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\dZ)?$"
          },
          "type": {
            "description": "The kind of change.",
            "enum": [
              "added",
              "changed",
              "deprecated",
              "removed",
              "fixed",
              "decision",
              "governance",
              "compaction"
            ]
          },
          "summary": {
            "description": "One-line description of what changed.",
            "type": "string",
            "minLength": 1
          },
          "paths": {
            "description": "Repository-root-relative paths the change affected. At least one; a compaction entry records the union of the paths it folded, or the changelog's own path when that union is empty.",
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "pattern": "^(?!/)(?!\\./)(?!.*(^|/)\\.\\.(/|$))(?!.*\\\\).+$"
            }
          },
          "categories": {
            "description": "Content categories the change touched.",
            "type": "array",
            "items": {
              "enum": [
                "domain",
                "system",
                "practice",
                "governance",
                "decisions"
              ]
            }
          },
          "decisionRefs": {
            "description": "Ids of decision records related to this change.",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "proposedBy": {
            "type": "string",
            "description": "Human or agent that proposed the change."
          },
          "approvedBy": {
            "type": "string",
            "description": "Human who approved the change."
          },
          "breaking": {
            "description": "Whether the change breaks consumers of the context layer.",
            "type": "boolean"
          },
          "compacted": {
            "type": "object",
            "description": "Required on compaction entries: what the compaction removed from the oldest end.",
            "required": [
              "entries",
              "firstId",
              "lastId"
            ],
            "additionalProperties": false,
            "properties": {
              "entries": {
                "description": "How many entries this compaction removed from the oldest end.",
                "type": "integer",
                "minimum": 1
              },
              "firstId": {
                "description": "Id of the oldest entry removed by this compaction.",
                "type": "string",
                "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
              },
              "lastId": {
                "description": "Id of the newest entry removed by this compaction.",
                "type": "string",
                "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
              }
            }
          }
        },
        "if": {
          "properties": {
            "type": {
              "const": "compaction"
            }
          },
          "required": [
            "type"
          ]
        },
        "then": {
          "required": [
            "compacted"
          ]
        }
      }
    }
  }
}

Một changelog máy đọc được về các thay đổi của lớp ngữ cảnh.

{
  "$schema": "https://leji.org/schemas/v1.0/context-changelog.schema.json",
  "schemaVersion": "1.0",
  "entries": [
    {
      "id": "seed-layer",
      "date": "2026-06-10",
      "type": "added",
      "summary": "Gieo lớp ngữ cảnh: boot profile, bảng thuật ngữ, bất biến hệ thống, bản ghi quyết định đầu tiên.",
      "paths": [
        "docs/boot-profile.md",
        "docs/domain/glossary.md",
        "docs/system/invariants.md",
        "docs/decisions/0001-adopt-leji.md"
      ],
      "categories": [
        "domain",
        "system",
        "decisions"
      ],
      "proposedBy": "agent:claude",
      "approvedBy": "Jo Lee"
    },
    {
      "id": "thought-partner-profile",
      "date": "2026-06-12",
      "type": "added",
      "summary": "Thêm agent profile thought-partner và gắn nó vào vai trò trong map agents của manifest.",
      "paths": [
        "docs/agents/thought-partner.md",
        "leji.json"
      ],
      "proposedBy": "agent:claude",
      "approvedBy": "Jo Lee"
    },
    {
      "id": "ownership-to-platform-team",
      "date": "2026-09-11",
      "type": "governance",
      "summary": "Chuyển quyền sở hữu lớp ngữ cảnh từ Jo Lee sang Acme Platform Team.",
      "paths": [
        "leji.json"
      ],
      "approvedBy": "Acme Platform Team"
    }
  ]
}

← Tất cả schema