取得精确源码与锁定依赖

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

选择当前文档描述的版本

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

清单字段

用途

documentation_source.commit

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

code_source.commit

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

qualified_code.commit

被引用的软件资格基线，保留其原始范围与结果

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 clone --no-checkout https://github.com/X-Gen-Lab/nexus.git nexus
cd nexus
git checkout --detach "$nexus_source_revision"
git submodule sync --recursive
git submodule update --init --recursive
git rev-parse HEAD
git submodule status --recursive
git status --short

检查每条命令的退出状态。git rev-parse HEAD 必须与清单中的完整提交一致。递归子模块输出不能以 -（缺失）、+（版本不同）或 U（冲突）开头；开始干净源码工作流前，git status --short 必须为空。提交不可取得或依赖取得失败时立即停止，绝不能替换为 main、HEAD 或最新依赖。没有包清单的预览应从源码横幅或 documentation-build.json 记录完整提交，并显式使用该已验证提交。

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

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

任务

后续准备

Native 消费工程或 I/O 夹具

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

检查配置

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

平台维护

开发工具、TDD 与钩子

文档检查、构建或打包

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

MCU 链接或硬件准备

精确工具链与 HIL 准备

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