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

spec 1.0 · 参考

清单：leji.json

AI 智能体辅助翻译。如有出入，以英文页面为准。如果你发现文本有任何问题，欢迎提交议题或发起拉取请求。

Leji 上下文层的机器入口。以 leji.json 的形式位于仓库根目录。

清单是 Leji 唯一规定了固定名称的文件，工具始终可以在仓库根目录找到它。

字段表由该 schema生成，因此本页内容始终与契约保持一致。本页涵盖顶层字段和部分嵌套字段；更深层的结构，例如某个 actor 的角色与命令，请直接阅读 schema。必填字段已作标记。

字段

#lejistring必填

本上下文层面向的 Leji 规范版本系列，例如 "1.0"。这个自命名的键沿用 OpenAPI 的惯例，用来表明该文件是一份 Leji 清单。

匹配模式 ^\d+\.\d+$

#namestring必填

本上下文层的一个简短、稳定的标识符，例如 "acme-billing-context"。

#descriptionstring

一行摘要，说明本上下文层涵盖什么。

#rootPathstring必填

上下文根目录，相对仓库根目录的 POSIX 路径。它声明上下文层位于何处，但不会为它所治理的路径重设基准：索引条目、侧边栏固定页面、配置路径，以及 Leji 产物中的其他所有路径，都从仓库根目录解析。查看器的 homepage、logo 与 favicon 是例外：它们相对上下文根目录书写，落在该根目录之下的、相对仓库根目录的路径也会被接受。

匹配模式 ^(?!/)(?!\./)(?!.*(^|/)\.\.(/|$))(?!.*\\).*$

#bootProfilePathstring必填

引导配置的路径，即每个智能体宿主和每个人都从这里开始的、不依赖具体智能体的入口。

匹配模式 ^(?!/)(?!\./)(?!.*(^|/)\.\.(/|$))(?!.*\\).+\.md$

#categoriesobject必填

逻辑类别到索引文件的映射。键是五个类别标识符；每个键映射到一份或多份撰写好的索引文件，由它们列出该类别的内容。

下面每个键都具有相同的形态：

indexes字符串数组必填

本类别的一份或多份索引文件，路径相对仓库根目录。每份索引文件都是撰写好的 markdown，其中带有一个 leji-index 围栏代码块，块内的 - path: <dir-or-file> 行选出属于本类别的内容。内容仍留在原处；由索引文件声明纳入。

domainobject

domain 类内容所在之处：业务语言与产品语义。

systemobject

system 类内容所在之处：架构，以及每一次变更都要遵守的不变量。

practiceobject

practice 类内容所在之处：约定与已被验证有效的模式。

governanceobject

governance 类内容所在之处：智能体护栏与运作规则。

decisionsobject

决策记录所在之处：带日期的记录，说明事情为何如此。

#machineobject

机器可读产物的位置：索引、变更日志、智能体配置和决策记录。

indexPathstring

生成的上下文索引的路径。

changelogPathstring

机器可读的上下文变更日志的路径。

agentProfilesPathstring

存放智能体配置文档的目录。

decisionRecordsPathstring

存放决策记录的目录。

#agents映射

角色到智能体配置的绑定。键是角色标识符（例如 "thought-partner"、"reviewer"）；值是智能体配置文档的路径。协议启用角色，而这个映射决定由谁来担任。

#actors映射

可选的 actor 注册表，登记能够担任角色的参与者。键是稳定的 actor 标识符。每个 actor 声明它有资格担任的角色，以及按角色划分的命令模板。当某个角色有多于一个合格 actor，或者同一个 actor 因担任角色不同而需要不同调用方式时使用它；任一条件单独成立即足够。一个只有单一 actor、只需一条命令的角色，由智能体配置自身的 host 与 invocation 即可满足。

#ownersobject必填

谁对上下文层的健康负责。负责人要为上下文层保持当前有效、及时精简负责；但并不由他们独自撰写或编排（governance.md）。

下面每个键都具有相同的形态：

namestring必填

这个人的姓名。

contactstring

如何联系到他们，例如一个电子邮件地址。

primaryobject必填

对上下文层是否当前有效负责的那个人。没有负责人的上下文层会腐坏。

continuityobject

可选。当主负责人无法履职或离开时，由另一个人承担同样的责任；有外部协助的接入应当在协助方撤出之前指定一位。重复填写主负责人不构成任何延续性，智能体也无法担任：负责人是承担责任的人。

#conformanceobject

本上下文层所声明的一致性级别，可由工具检查。

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

所声明的一致性级别：core、indexed、governed 或 federated。

claimedAtstring

最近一次作出该声明的 ISO 8601 日期。

#federationobject

挂载进本仓库的同级层（规范：distribution.md 模式 3）。圆环组合各方的归属，而不是把归属集中起来。

mounts对象数组

每个挂载都是一个同级上下文层，通过解析器填充的层投影在固定版本处读取，并保有自己的仓库、归属和评审关卡。物化后的内容存放在被 git 忽略的解析器缓存中，绝不提交到这里。

namestring必填

同级层的名称；必须与该同级层自身清单中的 name 一致。

sourcestring必填

同级层的归一化仓库定位符：一个 https://、ssh:// 或 SCP 风格的远程 URL。它既是解析的根，也是固定版本的命名空间。本地文件系统路径只在机器本地的提示中有效，绝不出现在这里。

pinstring必填

本宿主层所读取的同级层修订版的完整不可变提交 id（SHA-1 或 SHA-256）。它是保存在清单中的目标状态：固定版本的更新是有意为之、经过评审的编排。

trackingRefstring

可选的、位于 source 上的全限定见证 ref（refs/heads/* 或 refs/tags/*），过期固定版本的报告与联邦可达性都相对它来比较。未声明时，使用 source 所公布的默认分支，并写入命令输出。

ownerobject必填

同级层的负责人。归属留在同级层所属的团队；宿主层绝不吸收它的内容。

rolestring

用散文说明这个同级层承载什么，例如 "product-side context"。它是给人读的；路由使用下面那些结构化字段。

categories由 "domain" · "system" · "practice" · "governance" · "decisions" 构成的数组

这个同级层可以应答的内容类别范围。仅为路由元数据；同级层的内容仍留在同级层。federated 级一致性要求声明它。

topics字符串数组

简短的、宿主层可见的主题标签，用于把一项任务路由到这个同级层，例如 "billing"、"checkout"。仅为路由元数据。

requiredWhen字符串数组

在这些任务条件下，读取者必须解析这个挂载，无法解析时则停下并报告上下文不完整（失败即关闭）。它对宿主层可见；不得披露任何宿主层受众不该看到的内容。

#vendorAdapters字符串数组

本仓库中存在的厂商入口文件；每一个都必须重定向到引导配置。

#viewerobject

由 leji viewer 读取的呈现偏好。这是非规范性的便利配置；呈现本身不属于规范范围。

portinteger

leji viewer serve 首选的本地预览端口。--port 参数会覆盖它；默认值是 5354（手机键盘上的 LEJI）。

logostring

查看器使用的标志图片，以上下文根目录下的路径给出（例如 "assets/logo.svg"）。默认使用 Leji 标志。

titlestring

查看器的显示标题（侧边栏标题与页面标题）。默认使用上下文层的名称。

agentsLabelstring

智能体配置分组在侧边栏中的标签（欢迎使用 emoji）。默认为 "🤖 Agents"。该分组列出本层的智能体配置，并像其他分组一样由 viewer.groupOrder 排序。

faviconstring

查看器使用的站点图标，以上下文根目录下的路径给出（例如 "assets/icon.svg"）。默认使用 Leji 标志。

homepagestring

查看器的首页，以相对上下文根目录的路径给出（例如 "README.md"）。默认使用脚手架生成的 overview.md。

pins元素数组

固定在侧边栏顶部的页面：相对仓库根目录的 markdown 路径，或者用 {path, label} 指定一个自行编排的标签。固定引导配置会替换它默认的那一行。

groupOrder字符串数组

自行编排的侧边栏分组顺序，按分组标签精确匹配（即索引文件的 H1）。列出的分组按此顺序排在前面；未列出的分组按推导顺序排在后面。

themeobject

查看器主题的覆盖设置。

primarystring

主色/强调色，用十六进制 CSS 颜色表示（例如 "#009F71"）。它决定查看器外框、激活状态和图表强调色；正文链接与行内代码使用那个固定的无障碍色调，除非 viewer.theme.link 提供了一个能通过对比度检查的颜色。

linkstring

链接颜色，用十六进制 CSS 颜色表示（例如 "#5A50F9"）。只有当它相对行内代码背景（正文链接与行内代码所落在的两种背景中较窄的那一个）达到 4.5:1 时，才会应用到正文链接与行内代码；否则仍保留那个固定的无障碍色调，并由 leji view / leji export 发出告警。

mermaidboolean

在查看器中把 ```mermaid 围栏代码块渲染为图表。默认为 true。

poweredByboolean

在查看器角落显示那个小小的 "Powered by Leji" 标记。默认为 true；设为 false 即可移除。

categoryEmojisobject

覆盖生成的层地图中每个类别旁默认显示的 emoji。（侧边栏分组的标签取自各索引文件自己的 H1。）

一个完整示例

下面是一个组织级联邦上下文层的完整示例，其中挂载了一个同级层，使用的字段远多于实际场景通常所需。多数上下文层只需声明自己用到的字段子集：leji init 脚手架生成的只是其中少数几个字段，而一个 core 级别的清单要短得多。

这个形态里有两点容易读错：每个类别指向的是撰写好的索引文件，不是内容目录；而 agents 把角色标识符绑定到配置文档，它是角色目录而不是加载顺序，因此绑定某一份配置绝不会导致它被读取。

有一个字段是条件式的，而不是声明式的：viewer.theme.link只有在相对查看器的行内代码背景达到 4.5:1 的对比度时，才会为正文链接与行内代码着色；未达到该下限的取值会以告警形式报告，同时保留那个固定的无障碍色调。

{
  "$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"
    }
  }
}

清单与索引、变更日志和各类配置之间的关系，见机器可读接口；leji 这个规范版本系列键，见版本管理。