取得精确源码与锁定依赖

在执行教程、配置参考或维护工作流中的仓库命令前，先使用本指南。你将取得处于 detached 状态的精确 Nexus 源码版本及经过审查的依赖闭包。首次克隆和取得依赖需要 Git、Python 3.11+ 及网络访问。本流程不构建、不刷写，也不建立软件或硬件资格。

选择当前文档描述的版本

打开页面版本横幅标识的不可变文档版本。从该版本根目录下载 documentation-manifest.json，或使用已验证离线包根目录中的同名文件。将其保存在即将创建的 checkout 外，例如工作父目录下的 nexus-documentation-manifest.json。如果从 stable/ 进入，先记录其选择的不可变版本，再下载；不得混用两个版本。

清单字段

用途

documentation_source.commit

包含这些页面及其工具的精确源码

code_source.commit

文档包描述的源码；应单独核对其身份

qualification_references[]

schema 2 包中显式验证的候选引用，各自保留原源码和范围；可以为空

历史 schema 1 包保留原始 qualified_code.commit 字段，用于只读恢复。不得将其解释为当前 schema 2 引用。

GitHub 默认分支可能落后于已审查的文档分支。分支名、成功克隆或文档发行都不能替代精确提交。此前已审查的文档快照是 5a7a75c321ea173df8692714f95a8df13715293d；选择它只能重建该快照，不能取得后续文档。它的不可变包清单是一个具体例子。执行当前教程时，使用你所读版本自己的清单。

克隆并初始化该精确版本

从保存已下载清单的父目录执行以下 POSIX shell 命令。选择新的 checkout 目录；命令不会替换已有目录。Python 命令先验证身份，再将其传给 Git：

nexus_source_revision=$(python -c 'import json, re; from pathlib import Path; manifest = json.loads(Path("nexus-documentation-manifest.json").read_text()); revision = manifest["documentation_source"]["commit"]; assert re.fullmatch(r"[0-9a-f]{40}", revision), "invalid documentation commit"; print(revision)')
git init nexus
cd nexus
git remote add origin https://github.com/X-Gen-Lab/nexus.git
git fetch --no-tags origin "$nexus_source_revision"
git checkout --detach "$nexus_source_revision"
python tools/dev/dev.py prepare --scope native --allow-network
git rev-parse HEAD
git submodule status --recursive
git status --short

检查每条命令的退出状态。git rev-parse HEAD 必须与清单中的完整提交一致。递归子模块状态输出不能以 -（缺失）、+（版本不同）或 U（冲突）开头；开始干净源码工作流前，git status --short 必须为空。提交不可取得或依赖取得失败时立即停止，绝不能替换为 main、HEAD 或最新依赖。准备命令在初始化显式选中的路径前，会审查源码维护的依赖清单和各父模块的 Gitlink。固件配置过程不会取得依赖。对于本命令引入之前的历史版本，请使用与其对应的不可变文档，不要把当前命令用于旧源码树。没有包清单的预览应从源码横幅或 documentation-build.json 记录完整提交，并显式使用该已验证提交。

获取精确源码提交可避免下载无关的产物分支。documentation-assets 分支存放大型历史证据归档，不是源码依赖。只有需要原始证据时，才按软件证据入口取得其标识的单个归档。经过验证的 Source SDK 是另一条维护的消费路径，不需要源码仓库的产物历史。

Windows 下可在 Git Bash 中执行这段 POSIX 命令，或读取同一清单字段，在自己的 shell 中执行对应 Git 命令。不要将这里的变量语法直接当作可移植的 PowerShell 命令。

只准备当前任务所需的工具

任务

后续准备

Native 消费工程或 I/O 夹具

所选教程要求的主机 Python、CMake、Ninja 和 C/C++ 编译器

检查配置

Python 与维护中的解析器；ARM 编译仍是独立步骤

平台维护

开发工具、TDD 与钩子

文档检查、构建或打包

锁定文档工具组合与统一 CLI

MCU 链接或硬件准备

精确工具链与 HIL 准备

每个教程都从上面确定的仓库根目录开始。按要求将独立消费工程和包输出保存在源码 checkout 外。删除目录前，保留清单、源码身份及必需报告，并且只删除自己创建的目录。干净 checkout 只提供输入身份；实际执行与资格证据仍需分别建立。