spec 1.0 · 规范性

上下文层

Leji 上下文层由一组纳入版本管理、受治理的人类可读文档构成，记录团队如何理解自己的工作：领域语言、系统不变量、约定、护栏和决策记录。人和智能体都会在实际工作中读取它，也会通过同一道评审关卡提议变更。上下文层存放在版本控制系统中，因此历史、时效与批准状态都可以验证；具体机制见下文的要求，参与者及其参与方式见参与方式。

参与方式#

参与一个上下文层是基于角色的，而不是基于工具的。读取、提议、评审与批准，通过任何能保留仓库评审与批准语义的界面进行；参与不要求懂得直接使用 git 或命令行。

凡有访问权的人都读取。这里的访问权指的是通过团队日常工具获得的实际访问能力，而不是对仓库的 shell 访问权限。
任何参与者都可以提议；由人来批准。提议是一次有意的上下文层变更请求。它可以由人直接撰写，可以由智能体依据某人的请求生成，也可以由智能体依据观察到的工作生成。实践中，多数上下文变更由智能体起草；不可替代的人类贡献是治理：提出意图，并批准什么可以成为权威内容。批准变更的人对其含义与后果负责，而不是对亲手操作版本控制系统负责。
人类的含义，机器可读接口。人类可读的文档才是团队运作上下文的规范性来源。机器可读的文件（清单、索引、变更日志）的存在，是为了让工具能够定位、索引、校验并同步那份含义；它们绝不取代含义本身。

这些流动的规范形式，即圆环（所有人都读取，任何参与者都可以提议，由人来批准），定义在 governance.md 中。

读取一份记录#

受治理的内容分为两类，定义见 content-categories.md：意图按当前真实状态持续维护；记录是带日期的证据，后续状态会取代它，而不是修正它。两者受到同等治理，区别在于读取者可以如何使用。读取者不得把记录当作当前意图：记录以证据的形式提供信息，其有效范围以自身声明的边界为限；如果读取者不加说明，便将记录中的主张表述为当前状态，就等于赋予这份文档本不具备的时效性。这与下文的降级模式规则原理相同：无论哪种情况，读取者都有义务了解并说明手中内容的时效性。

要求#

上下文层必须存放在一个 git 仓库中，并且必须与它所描述的工作一起纳入版本管理（同一个仓库，或者一个专用的上下文仓库，按 distribution.md 消费）。正是这个 git 仓库，使上下文层的历史、工作副本时效与仅可追加的变更日志完整性可被验证；符合规范的工具从中推导出这三者。在没有该仓库的情况下读取上下文层是受支持但降级的模式，定义见读取模式：权威与降级。
接入 Leji 的仓库必须在仓库根目录携带清单文件 leji.json，且对 context-manifest.schema.json 有效。清单是机器入口：它声明规范版本（自命名的 leji 键）、上下文层名称、上下文根目录、引导配置路径、类别映射、可选的一致性声明，以及归属。它也可以携带一个 agents 映射，把角色标识符（例如 thought-partner、reviewer）绑定到智能体配置文档：协议启用角色，而这个映射决定由谁来担任。该映射是角色目录，不是加载顺序：任何绑定，包括 default 键上的绑定，都绝不会导致某份配置被读取；只有引导配置的“加载”一节才会。
清单可以声明 actors（可担任者）：能够填充角色的具名参与者。每个 actor 声明它有资格担任的角色，以及按角色划分的命令模板。以角色为键正是关键所在：同一个 actor 可能因为担任的角色不同而需要不同的调用方式，因此“每个 actor 一条命令”无法表达这一点。一个 actor 声明的角色集合与它的命令键集合必须相同。当某个角色配有 actor 时，绑定到该角色的智能体配置不得同时声明 invocation：两条都自称权威、又没有说明优先级的命令，本身就是矛盾，而本层通过把命令声明在唯一一处来消解它。actors 是可选的，多数层不需要。它们的价值出现在某个角色有多于一个合格 actor 时，或者某个 actor 因担任角色不同而需要不同调用方式时；任一条件单独成立即足够，而一个只有单一 actor、只需一条命令的角色，由配置自身的 host 与 invocation 即可满足。声明一个 actor 不授予任何批准权：它说的是谁可以被请来担任某个角色，绝不是谁可以批准。

命令模板无论出现在哪里（actor 的 commands 值，以及智能体配置的 invocation.command），都遵循同一条规则。模板是一行命令，交给调用方所选的 shell；不是 shell 形态的启用方式（结构化的 argv 调用、进程内派生）在 1.0 版本系列中无法由这些字段表达。每个模板必须携带 <prompt> 占位符，且每一次出现必须作为独立的、未加引号的 shell 词出现在参数位置上，绝不能置于引号内或与其他文本拼接。替换是一次性的：所撰写模板中已出现的各处会被同时、且恰好各替换一次，因此提示文本内部字面的 <prompt> 字符串仍是数据，绝不会被二次展开。交付方式由调用方负责，而契约是所要求的结果而非引用转义算法：每一次出现都产生恰好一个参数，其值等于提示文本，且其中任何部分都不作为 shell 语法求值。Schema 所验证的是替换位点的存在；位置与交付则由本规则要求、由调用方履行。
清单必须声明一个上下文根目录（rootPath）。推荐的默认值是 docs/。上下文层的所有路径都是 POSIX 风格，相对于仓库根目录。rootPath 声明上下文层存放在哪里；它不会为它所治理的路径重设基准：索引条目、侧边栏固定页面、配置路径，以及任何 Leji 产物中的其他每一个路径，都从仓库根目录解析，包括那些重复了 rootPath 前缀的路径。查看器的 homepage、logo 与 favicon 是例外：它们相对上下文根目录书写，落在该根目录之下的、相对仓库根目录的路径也会被接受。类别路径与 machine 路径应当落在 rootPath 之下；否则校验器会告警。
上下文层必须拥有一份引导配置，见 boot-profile.md。推荐的默认位置是 docs/boot-profile.md；实际位置由清单的 bootProfilePath 声明。
上下文层的内容必须首先是人类可读的。散文格式推荐使用 markdown；结构化元数据使用 YAML frontmatter，或 machine-readable-surface.md 中定义的 JSON 产物。只有机器能读的文档不属于上下文层。
上下文层必须有一位具名负责人（清单中的 owners.primary）：一个对其时效性负责的人。无人负责的上下文层必然腐烂。

读取模式：权威与降级#

上下文层有两种读取模式；读取者必须知道自己处于哪一种，因为二者的保证不同。读取者依据自己能解析到什么来判定模式：能在仓库根目录访问到 leji.json，并且具备 git 工作树或宿主平台提供的仓库版本标识，即为权威模式；两者皆无、只能作为普通文件读到内容，即为降级模式。

权威模式。读取者通过 git 仓库解析上下文层：一份工作副本，或宿主平台的仓库视图。历史、工作副本时效与变更日志完整性都可被验证，已批准的内容可确知对应到所读取的版本。
降级模式。读取者以普通文件内容的形式接触上下文层，没有可用的 git 工作树或版本元数据：文件被上传、同步或复制到另一个界面，而仓库并未随行。普通文件读取就阅读而言是一等的（文档按要求本就人类可读，机器可读的变更日志仍传达声明的新近程度），但降级模式的读取者必须把工作副本时效与批准状态视为未知，绝不能视为当前有效（见 governance.md 的“时效性”）。在此模式下，变更日志是可随副本携带、用于声明新近程度的信息载体；它本身并不能证明这份副本与权威仓库一致。

降级读取扩大了谁能消费上下文层、以及能消费到什么；它绝不是通往权威性的路径。变更只有经由基于 git 的评审关卡才成为权威，而降级副本无法满足联邦所依赖的权威模式检查（固定版本的时效、过期固定版本状态、归属完整性，以及受限挂载的访问检查，见 distribution.md）。

厂商适配器规则#

智能体宿主的配置文件（例如 CLAUDE.md、AGENTS.md、GEMINI.md、.cursorrules、.cursor/rules、.windsurfrules、.github/copilot-instructions.md）：

不得承载权威的上下文层内容。
若存在，必须重定向到引导配置（通常是一行指针）。
可以携带在该智能体宿主之外没有意义的宿主专有机制（模型选择、运行器设置），前提是其中不存放任何团队知识。
工具从两个来源发现需要检查哪些入口文件：清单中可选的 vendorAdapters 列表，以及一份公开的知名集合（上面列出的那些文件）。上面的示例列表就是本版本系列的知名集合；入口文件不在其中的宿主，只有在清单于 vendorAdapters 中点名时才会被检查。

现有的入口约定告诉智能体宿主去哪里看；Leji 定义的是智能体在那里会看到什么。一个事实来源，所有参与者读的都是它。

上下文层不是什么（非规范性）#

不是 wiki。 Wiki 本身没有机制确保内容始终最新。上下文层能够持续有效，是因为智能体执行每项任务时都会读取它（错误的上下文会立即导致可感知的错误结果），变更像代码一样经过评审，工具也会让陈旧内容显现出来。
不是传统意义上的文档。传统文档往往在事后描述系统做了什么；上下文层则用现在时描述团队如何思考，并持续供人和智能体读取。
不是可直接导入的模板。借来的上下文很快就会过时。上下文层的价值在于它表达的是团队自身的认识；Leji 标准化的是形态与治理，而不是内容。