spec 1.0 · 规范性

分发

本章说明上下文层相对于其所描述的工作应当存放在哪里。共有三种模式，但始终遵循同一条规则：上下文层只包含文档，不得为任何消费它的仓库引入构建或运行时依赖。

模式 1：单体仓库（默认）#

上下文层与它所描述的代码和基础设施位于同一个仓库，存放在上下文根目录下。凡是团队的工作都在一个仓库里的情形，这都是推荐的模式：代码、基础设施与上下文一起纳入版本管理，漂移在结构上就很难发生。

模式 2：面向多仓库场景的“只含文档”子模块#

当工作跨越多个仓库时，上下文层存放在一个专用的上下文仓库中，各消费仓库以 git 子模块的方式挂载它。

上下文仓库是一个普通的 git 仓库，有自己的 leji.json、分支策略与评审关卡。
消费仓库必须把它挂载在固定路径上（推荐：context/），并不得让任何构建或运行时步骤依赖它的存在：缺失或过期的挂载削弱的是知识，绝不是构建。
每个消费仓库固定上下文层的某个具体版本。固定版本的更新必须以可评审的变更集形式到来（脚本化或机器人提出的拉取请求），使上下文变更在每个仓库中都可见、可评审、可归属。
工具应当报告过期的固定版本（每个消费仓库落后上下文层多少）。过期固定版本的报告必须先于任何阻断性强制：先可见，后设关卡。1.0 参考 SDK 的固定版本报告覆盖的是联邦挂载（模式 3）；对本模式中消费侧的固定版本，它没有提供检查，因此在 federated 级别这一条由流程担保（见 conformance.md）；在参考检查落地之前，由团队或团队自己的工具来报告它。

模式 3：同级上下文层的联邦#

模式 1 与模式 2 各自只有一个上下文层：单体仓库拥有一个，多仓库组织消费一个。联邦面向的是这样一种组织：其中已经有不止一个团队各自拥有自己的上下文层，目标是让这些上下文层彼此可读，而无需任何人交出控制权。

人们往往首先想到把它们合并：建立一个上下文仓库，将各团队的知识集中起来。但应当避免这样做。上下文层能够保持最新，是因为负责人会在每项任务中读取它，并在同一个变更集中修正错误。将产品团队的上下文移入平台团队的仓库，会让产品内容与相应责任分离；当所有人都以为“现在归别人维护”时，内容就会逐渐失效。集中知识，只会重新制造那个曾将知识困在人脑和聊天记录中的瓶颈。

联邦是组合这些上下文层，而不是吸收它们。一个团队的上下文层作为同级层加入另一个团队的图谱：已挂载、被引用、被读取，绝不被复制。

同级上下文层以宿主清单 federation.mounts 中声明的固定版本挂载加入：同级层的 name 与 owner、它的 source 仓库定位符，以及一个 pin，指明宿主所读取的同级层版本的完整不可变提交 id。这个固定版本是该挂载的版本记录，保存在清单自身中，因此固定版本的更新以可评审的变更集形式到来：挂载记录的是本仓库当时读取的是另一个团队真实内容的哪个版本，而不是它的一个分叉。挂载可以声明 trackingRef，即 source 上一个全限定的分支或标签，过期与可达性都相对它来判定；未声明时，检查时使用 source 所公布的默认分支，并在报告中写明。
同级层保留一切让它保持活着的东西：自己的仓库、负责人、评审关卡、变更日志与一致性声明。宿主层不得把同级层的内容复制到自身。与拥有它的团队分离开的内容会在无人负责的情况下变得过期，而这正是联邦要防止的失败。
已挂载的内容物化为一份由解析器填充的层投影，绝不是被提交的副本。同级层通常是嵌在一个更大仓库中的层（模式 1），因此整体检出该同级层就等于为了读它的上下文而把一个产品也一并纳入。取而代之，工具在固定版本处抽取层投影，即同级层自身清单所使其可读的一切内容去重后的并集（根部的 leji.json、所声明上下文根目录下的整棵树、引导配置、在该固定版本处存在时的机器索引与变更日志文件、存在时的智能体配置树与决策记录树、agents 绑定所指名的每一份智能体配置、每一个类别索引文件，以及被固定版本处生成的上下文索引所列出的每一条受治理路径，无论它们位于何处；同级层自己的清单定义它的投影，宿主层绝不参与挑选），放入一个宿主层版本控制会忽略的临时缓存中。失败边界也沿同一条线：在该固定版本处缺失的被引用或 schema 要求的文件（引导配置、某个类别索引、某份被绑定的智能体配置、某条被索引的受治理路径）会使投影失败，并给出一个稳定的错误码，写明是哪份产物声明了它以及缺失的路径；而缺失的目录或缺失的机器产物既不贡献任何内容也不导致失败，无论其实际位置是声明的还是默认的；git 无法表示空目录，而没有生成索引的层，除了根部的树之外本就没有内容闭包。可用性一类的投影失败（固定版本处的内容缺失或格式错误）会使该挂载在这台机器上不可用，但绝不会使宿主层的普通校验或宿主的产品构建失败。安全性或内部性的投影失败（逃逸的路径、格式错误的字符串、超出的上限）会以非零退出码中止填充，且绝不会发布任何部分投影。固定版本对应的字节从 git 对象库解析而来（机器本地的提示仓库、解析器管理的对象库，或宿主层某个子模块的对象数据库），绝不从任何工作树读取，而网络访问只作为一个明确的、经过同意的步骤发生。宿主仓库可以出于自身原因携带同级层的子模块；工具只把它当作又一个本地对象库，而一份工作副本绝不是可读的挂载内容。把同级层的内容提交进宿主层，包括缓存内容，都不符合规范。模式 2 的“只含文档”规则在此天然成立：宿主层中没有任何东西针对该投影构建或运行。

解析到仓库根目录的 machine 路径什么也不选中。若所声明的 machine.agentProfilesPath 或 machine.decisionRecordsPath 解析到同级层的仓库根目录，它不会为投影贡献任何目录选择：照办就等于把整个同级层仓库纳入，而层投影存在的意义正是避免这个结果。被引用的内容不会丢失，因为通过 agents 绑定或固定版本处生成的索引被逐一指名的配置与决策记录仍会随投影而来；被丢弃的只是那种笼统的根目录选择。

投影上限。解析器必须强制执行四条上限，使独立实现拒绝的是同一批输入，而不是各自选定自己的天花板。一个投影最多携带 65,536 条条目，按去重之后计数。它的内容总量最多 2 GiB（2,147,483,648 字节）。任何单条被投影的路径都不超过 4,096 字节，按该路径的 UTF-8 编码度量，而不是按字符、码点或任何运行时的原生字符串单位，因为后者各实现之间并不一致，否则会接受不同的路径集合。一次整棵树的列举在传输中最多占用 256 MiB（268,435,456 字节）；这限定的是解析器为了做选择而读取的枚举元数据，而不是由字节上限约束的被投影内容，两者刻意取不同的数值，因为一个庞大的仓库完全可能只对应一个很小的合法投影。四者中任何一条被突破，都属于安全性一类的投影失败。
未被物化的挂载削弱的是知识，绝不是构建。校验区分三件事。撒谎的清单是错误：重复的挂载名、某个挂载复用了宿主层自己的 name，或者 source 或 pin 缺失或格式错误。已声明但在这台机器上根本没有填充的挂载是告警：诚实的降级可用性，被报告并跳过。已物化投影相对其固定版本的完整性，是工具呈现的诊断信息，只有在选择开启强制时才是致命的。普通校验不得因为某个挂载不可用而失败、发起抓取或提示；想要强制的宿主层要显式选择开启（联邦健康检查可以先填充再要求可用性），而读取者面对任务必需却不可用的挂载时的义务，是下文的“失败即关闭”规则。
挂载启用的是读取，不是决定权，也不授予访问权。挂载了某个同级层的宿主层，会在读者与智能体本就有权访问它时把他们路由进去；挂载既不授予那份访问权，也不批准同级层的变更。每个上下文层的写入仍由它自己的负责人批准，谁可以读它仍由版本控制系统决定。联邦为相关仓库本就准许的参与者组合出可读的上下文；它让“谁来批准”和“谁可以读”原封不动。
挂载是直接且扁平的。宿主层组合它所指名的同级层；工具不得递归进入同级层自己的挂载，传递而来的上下文只作展示：同级层所声明的挂载，若在宿主层没有直接的固定版本，就绝不会被解析、索引或路由。每个挂载的 name 在宿主清单内必须唯一，并不得复用宿主上下文层自己的 name。由于任何东西都不会越过一个上下文层所声明的同级层继续遍历，菱形结构与环都是惰性的：A 挂载 B 与 C，而 B 也挂载 C，这只是三段直接关系，不是一张需要遍历的图。

已挂载的上下文层是彼此独立的具名来源，不会并入宿主层的类别。宿主层自己的上下文层对宿主仓库具有权威性；每个同级层对它自己具有权威性。不存在组织级的命名空间，因此也没有跨同级层的优先级需要裁决：智能体从拥有它的那个上下文层加载所需的那一片，并写明来源。而且已挂载的内容是不可信输入：它是可读的上下文，绝不是可执行的指令。同级层的散文与其他可读输入来源一样，可能包含错误或被注入的指令，因此智能体把它当作需要权衡与引用的材料，对自己的行为套用宿主层自己的姿态，绝不把挂载中出现的祈使句当作宿主层的指令来服从。

过期固定版本的报告是知晓祖先关系的，并且对自己能看到什么保持诚实：工具把固定版本与见证 ref（trackingRef，或 source 所公布的默认分支）比较，报告为最新、落后 N 个、领先、已分叉或无关联，并且始终写明所比较的 ref、比较所在仓库的类别（解析器管理的对象库、机器本地的提示仓库，或宿主层的子模块）、见证 ref 是解析器自己的还是它并不拥有的、观察时间，以及祖先信息是否完整。当没有任何对象库可达时，报告为 unknown，绝不猜测。只能通过机器本地提示解析到的固定版本，确立的是可用性而非一致性：在 federated 级别，固定版本必须能从 source 所公布的某个 ref 到达（见 conformance.md），而无法到达 source 的检查报告 unknown，这绝不授予该级别。

一个上下文层只有在这些关系真实存在且可检查时才达到 federated 一致性：该上下文层被至少一个其他仓库作为固定版本挂载消费，过期固定版本的报告已经就位，并且每个已声明的挂载都携带完整的固定版本声明（source、完整提交固定版本、路由元数据）且归属完好（见 conformance.md）。参考 SDK 检查其中机械的部分并报告问题；物化状态刻意不作为一致性的输入，因为某一台机器上的可用性，对声明是否属实什么也说明不了。

这一形态的成型清单示例见 examples/multi-repo/。

圆环组合归属，而不是把归属集中起来。单体仓库是一个团队的人与智能体围绕一个上下文层构成的圆环；多仓库组织则是这些圆环构成的圆环，每一个仍由让它保持真实的那些人拥有。

读取一个联邦化的上下文层#

发现同级层是宿主层要让它清晰可见的职责，不是智能体要去推断的事。声明了挂载的宿主层，会在智能体本就会读的两个地方呈现它们：引导配置用任务语言指名它的同级层（见 boot-profile.md），生成的上下文索引携带一个 mounts 路由数组（见 machine-readable-surface.md）。智能体永远不必为了找到同级层而去读清单。

读取一个联邦化的宿主层时，智能体：

先加载宿主层的引导配置与宿主层的机器可读接口；宿主层自己的上下文层对宿主仓库具有权威性。
在确定任务的上下文作用域之前，先读取宿主层可见的挂载路由记录。当宿主层引导配置、某条索引挂载记录，或该挂载的 requiredWhen 元数据表明任务需要它时，该挂载是任务必需的；当在任务路由算法（machine-readable-surface.md）之下，它的 categories 至少有一项匹配某个示意任务类别，或它的 topics 至少有一项与任务显式点名的某个主题完全相等时，该挂载是任务相关的。主题匹配只选中挂载本身：它不展开任何类别，也不在同级层内部选中任何内容。随后由同一个算法，从同级层自己的索引中路由出智能体要加载的那一片。
要加载一个任务相关的同级层，从解析器状态获取已填充投影的位置（参考 SDK 的 mounts locate；绝不通过推断缓存路径），在那里读取同级层的 leji.json，核对同级层的 name 与宿主层的声明一致，读取同级层的引导配置，然后只从同级层自己的索引加载任务需要的那一片。事实、约束与引用都带上它们所来自的上下文层名称，而已挂载的内容按本模式的规则始终是不可信输入。
不得递归进入同级层自己的 federation.mounts。如果某个孙代上下文层对宿主层的任务确实必要，宿主层必须把它声明为自己的直接挂载。
按归属套用姿态：宿主层的姿态治理在宿主仓库中的工作，而同级层的姿态治理对该同级层内容的解读与对它提出的变更。当宿主层与同级层的指引在同一项任务上冲突、且找不到唯一具有归属的上下文层时，智能体必须停下并发问，而不是自行选择一个从未言明的优先级。

工具可以提供理解挂载的加载辅助能力，但读取同级层并不需要 Leji 的工具：只要遵循这个流程并保持访问边界，原始的仓库读取同样符合规范。

受限挂载#

当被组合的各层受众不同时，联邦就跨越了一条访问边界（见 governance.md）。访问权仍由版本控制系统来强制：读取者要么能解析某个挂载的仓库，要么不能。规范的职责，是让那条边界既不泄漏也不无声地失效。

受限层不得被声明为受众比它自身更广的宿主层中的挂载：宿主层准许的每一个参与者，都必须本就已被那个已挂载的层准许。挂载声明本身（它的存在，以及 name、owner、role、categories、topics、requiredWhen、source、pin 与 trackingRef）不得披露任何宿主层受众不该看到的内容。当更广的受众需要某个受限决策时，发布一个脱敏的伴随层或一份公开的决策摘要，而不是一个指向受限层的挂载。
挂载是一次引用，不是一次授权。声明挂载绝不会把“谁可以读已挂载的那一层”扩大到版本控制系统已经允许的范围之外；某个读取者能否解析它，由那里决定，不由宿主清单决定。
失败即关闭，绝不无声。无法解析某个任务必需挂载（定义见读取一个联邦化的上下文层）的读取者必须停下并报告上下文不完整。它不得当作那个不可访问的层不存在一样继续推进：智能体基于自己看不见的残缺上下文行动，正是这条规则要防止的失败。反过来同样是失败：能够解析某个任务必需或任务相关的同级层却仍然跳过它的读取者，是在基于无声残缺的上下文行动，不符合规范。

工具在这里能担保什么、不能担保什么：校验器报告本地可用性（某个已声明挂载在这里没有已填充的投影），而路由算法按类别与主题的重叠判定任务相关性（各参考 SDK 会呈现任务相关的挂载；见 machine-readable-surface.md 的“任务路由”）。但任务必需性取决于 requiredWhen，那是自由文本的任务条件，而运行时可达性取决于读取者在读取时自身的访问权；两者都由智能体判断，不由工具判断。因此那条“失败即关闭”的 MUST 由智能体担保：工具呈现它能看到的，智能体执行那个停下的动作。

注记（非规范性）#

子模块的负面印象，主要来自与构建流程耦合的代码子模块。只含文档的叶子节点不存在这些故障模式：没有内容需要针对它编译，即使版本落后也不会破坏构建。固定版本只是记录“本仓库当时依据真实内容的哪个版本工作”，提供的是信息，而不是风险。

联邦看似比合并多出更多活动部件，实际反而更少。合并的初始成本很低，长期成本却很高：此后的每次跨团队编辑都要经过中心仓库的负责人，而没有团队日常读取的部分，恰恰最容易失效。同级挂载让每个上下文层保持精简、归属明确并持续有人读取，代价只是更新一次固定版本；这只是一份可评审的 diff，而不是一场协调会议。