指南
接入指南
AI 智能体辅助翻译。如有出入，以英文页面为准。如果你发现文本有任何问题，欢迎提交议题或发起拉取请求。
接入 Leji，就是把仓库从初始脚手架逐步建成真正可用的上下文层。你需要映射现有文档、接通入口、加入检查，并确定上下文层的存放位置。完成后，每个人都会有一个可靠的起点。
01脚手架
leji adopt 会复用 docs/、doc/ 或 documentation/，不搬动你的工作成果。它会写出：
- 一份
leji.json，其中name取自目录名，rootPath已设置，owners取自可用的 git 身份。 - 一份引导配置、各类别索引、一份入门简报，以及一份完整的、
status: accepted的首个决策。 - 在没有
AGENTS.md时，写一份指针式的AGENTS.md。
leji adopt --dry-run # 预览每一处写入；不会写入任何内容
leji adopt # 既有仓库：围绕现有内容生成脚手架
leji init # 新仓库：生成 leji.json、引导配置、类别起始内容与第一份决策
leji adopt --wire-adapters # 在厂商入口（CLAUDE.md、AGENTS.md）上完成接入也可以一步到位，无需预先安装任何东西：npm create leji 会检查当前目录，并在这里运行 leji adopt，或者在没有什么可接入的仓库里运行 leji init。这条命令会替代本步骤，而不是作为它的前置步骤；运行后，直接从下一节继续即可。
应当映射实际存在的路径，而不是重命名它们。docs/engineering/START-HERE.md 完全可以直接作为引导配置；新建的层则建议采用默认的小写连字符命名。
02把它变成你自己的
首先，为已有内容分类。每一份生成的索引文件选中的都是它所属的整个类别目录，因此已经放在其中的内容，在脚手架落地的那一刻就受治理；写在其他位置的内容，则要等有人把它列入索引，才会进入上下文层。你可以把入门简报交给智能体，批准它提出的映射方案，也可以自行编辑索引文件。
什么都不需要搬动。一个类别映射到若干整理好的索引文件，而其中一条条目选中的既可以是单个文件，也可以是整个目录，因此既有的docs/ 树可以原地不动（见内容类别）。
把你的决策历史一并带过来。既有的 ADR 目录，只要其中的记录带上决策记录 schema所要求的 frontmatter 就能适配；脚手架已经把 <rootPath>/decisions/0001-adopt-leji.md 写成了第一份。
接下来，接好发现路径。在既有的 CLAUDE.md、GEMINI.md、.cursor/rules 或AGENTS.md 之上接入时，那个文件被刻意保持原样，这意味着这次接入还只是草稿：旧入口还没有重定向，leji validate 会报 vendor-adapter-redirect，而 leji conformance 对照你所声明的 core 只验证出 none。
leji adopt --wire-adapters 会把那些内容迁入上下文层，并把入口替换成：Read ./<bootProfilePath> first. It is the canonical context entrypoint for this repository. 此后校验就能在 core 通过。
AGENTS.md 是那个可通用的适配器，许多宿主都原生读取它。init 与 adopt 在它不存在时创建一个只含指针的文件；--no-agents 会跳过它。单一厂商专属的入口文件，绝不会被创建。
若要手动接入，复制 templates/leji.json 与 templates/boot-profile.md，创建索引，并使用 templates/decision-record.md。在声明 core 之前，清掉 leji validate 点名的每一处占位内容；不需要的 agents 条目或类别就删掉。
03让它真正派上用场
上下文层的价值，在于让智能体动手前就读取它，而不是事后补读。leji start会从仓库根目录启动编码智能体，让它以引导配置为起点，而不是先自行猜测仓库情况。
leji start # 检测宿主，并在上下文层中打开它
leji start --agent codex # 指定宿主，不再检测
leji start --agent claude-code -- --chrome # 将标志传给该宿主leji detect 列出可用宿主；leji start --help 解释参数透传。脚本使用 bootProfilePath。agents 中的绑定，哪怕是 default，也只是记录有哪些配置，绝不会加载它们；只有引导配置里的指示才会。
04让它保持诚实
可靠的上下文层应当如实描述仓库当前的状态。引用断裂，或索引与源内容不再一致时，下面这些检查都会失败。未被索引的 markdown 和残留的占位内容则会被报告，但不会导致检查失败，这样你就能在智能体依照过期指引行动前发现漂移。
leji validate --content 找出占位内容与内容单薄之处。leji status 找出未被索引的、悬空的或过期的材料。leji conformance 报告进展。
在 indexed 级别，leji index 生成 context-index.json；leji index --check 会在它过期时失败。leji changelog check 校验那份机器可读的变更日志。
还没有 CI 约定的话，leji ci 会生成一个工作流；leji ci --hooks 会把这些关卡装成 pre-commit 钩子。leji ci --help 解释 CLI 的解析方式。
在已经稳定运行的流水线中，将 leji validate 和 leji index --check 加入必需任务与钩子。把 CLI 声明为 dev dependency，这样一次干净安装就会带上它：leji init/leji adopt 会识别本仓库实际使用的包管理器，并在你明确同意时运行它自己的添加命令（pip 与 1.24 之前的 Go 则只得到需要添加的那一行）。
在 governed 级别，再加上经过评审的变更、有效的智能体配置、时效性检查，以及必需的 CI。
展示你的一致性
leji badge 会在仓库根目录写出 leji-badge.svg，并打印可粘贴进 README 的那一行：
leji badge # 写入 leji-badge.svg，并打印代码片段
leji badge --out docs/badge.svg # 写到其他位置；代码片段会使用该路径[](https://leji.org/agent-ready/)这枚徽章是自我声明的，并且对这一次运行保持诚实：它陈述的是 leji conformance 验证到的级别，绝不会高于leji.json 所声明的级别，有时还会低于它。离线运行无法确认的声明，会被写在 stdout 上，而不是做进徽章里。
请在已提交的代码树上运行它。没有已提交基线的变更日志，无法据以检查仅可追加的规则，因此无论 leji.json声明什么，这次运行都止步于 core；而在已提交的变更日志之上追加的条目，会与 HEAD比对，不必自己先提交也能通过。一次运行如果没有验证到任何级别，就根本不会写出徽章。
这段代码里的图片路径是相对仓库根目录的。位于子目录中的 README，需要把路径调整成从那里能够到达该文件。
05它存放在哪里
一个仓库，把一个上下文层留在它的工作旁边。
如果多个仓库共用同一个层，可采用只含文档的子模块。先创建它自己的仓库，再将它挂载到每个消费方的 context/，并由各仓库固定版本。固定版本更新应通过可评审、可脚本化的方式提出。构建和运行时都不得依赖它。
把智能体指向 context/docs/boot-profile.md；保留下来的厂商文件重定向到那里。见多仓库示例与分发规范。
联邦面向的是各自拥有一个层的团队。它的指南覆盖了声明、填充、状态、路由，以及federated 相关的检查。
06可选情形
一个角色可以由多个 actor 担任
一个角色通常绑定到一份配置；host 与 invocation 描述如何启用它。若有多个参与者，或者需要按角色区分的调用方式，可选的actors 会列出各自有资格担任的角色与命令模板。见清单 schema。
actor 不授予任何批准权。具体由编排方选择；Leji 1.0 不定义选择规则。
意图与记录共处一个目录
把状态与读数作为记录来治理。一个文件选择器就能让意图留在同一个目录里：
```leji-index record
- path: docs/operations/
```
```leji-index intent
- path: docs/operations/escalation-policy.md
```文件选择器优先。智能体会将该策略作为必需意图加载；记录则单独返回，作为带日期的候选，只有在任务选中某条记录或有人明确要求时才加载。见内容类别。
在查看器中呈现上下文层
context-index.json 可以被各类文档工具使用。CLI 命令：
leji viewer serve # 在 http://127.0.0.1:5354/ 本地预览
leji viewer build # 导出自包含的静态文件夹，供内部部署serve 不是正式部署。只向这个上下文层的受众发布。构建产物写在仓库内部（默认是 .leji/dist/，或者其中的某个 --out路径），而那个输出目录归你：把它复制到你的部署环境读取的任何位置。受治理文档的 H1 提供导航；清单的 viewer 字段提供品牌与固定项。MkDocs 也可以使用这份索引。见机器可读接口规范。
各家渲染器对 markdown 的处理并不一致，因此一个上下文层可以依赖哪些语法，由渲染配置固定下来。leji export会对照那份配置检查它所携带的每一份文档，因此导出干净的层，始终处在已写明的语法子集之内，也不含那份配置点名的那些差异。这比“在每一个托管平台和编辑器预览里都渲染得一模一样”要窄。
从同步或沙箱化的来源读取
Leji 可以读取由克隆、沙箱挂载，或保留 git 的 Google Drive、Dropbox 目录所呈现出来的 git 树。
上传的文件、粘贴的文本，以及没有 .git 的文档，缺少版本元数据。它们的时效是未知的；git 工作副本仍然是权威的。见治理。