安装与环境¶

必需环境¶

工具	版本	锁定点
Node.js	22.22.2（锁定 major 22 并精确提高 floor：`>=22.22.2 <23`）	`.node-version`（取精确 floor）、根与各叶子包 `package.json` 的 `engines.node`；floor 由 `scripts/engine-floor-check.mjs` 从固定根 devDependencies 的 engines 实时重算，fact-check J 节绑定文档表面
pnpm	10.30.0	`package.json` 的 `packageManager`
projen	0.101.23	`package.json` 的 `devDependencies.projen`（精确版本，无范围符号）
Git	近年版本即可	仅开发者自行管理版本；本仓脚本不执行 Git 写操作

工具版本与锁定点登记在 .foundation/version-lock.json（projen 生成的机器真源，禁止手改）。升级流程见 scripts/README.md。

安装依赖¶

pnpm install

.npmrc 启用 save-exact=true，新增依赖也会以精确版本写入。

合成与检查¶

pnpm synth
pnpm check

pnpm synth 再生成 projen 受管文件。受管文件只能通过修改 .projenrc.js 间接变更；手写源码、文档和 fixture 不会被 synth 覆盖。
pnpm check 是当前统一根门禁：11 个稳定门禁 ID 按固定顺序串联执行，任一步骤非 0 即整体失败；本仓没有任何 CI/CD workflow，全部门禁都在私有工作区内运行。下方区块由根 package.json 的 scripts.check 机械投影（node scripts/docs/fact-check.mjs 逐字核对，禁止手写清单再次滞后）：

pnpm run check:structure
pnpm run check:packages
pnpm run check:profiles
pnpm run check:public-boundary
pnpm run check:scaffold
pnpm run check:docs
pnpm run check:public-snapshots
pnpm run check:release-artifacts
pnpm run check:projen
pnpm run check:integration
pnpm run check:artifacts

发布字节合同由两个固定入口承载：pnpm run release-artifacts:build（构建候选产物）与 pnpm run release-artifacts:verify（按合同校验），接口与拒绝矩阵详见当前产品状态。
耗时的 Python 文档矩阵不属于 pnpm check：它有独立入口 node scripts/docs/verify-matrix.mjs（矩阵版本覆盖由该脚本对照 scripts/docs/toolchain.json 机械核对；本仓无 CI，矩阵不声明在任何工作流里）。

其余命令：pnpm test（仅测试）、pnpm drift（只读 synth 漂移检查）、pnpm synth-idempotency(幂等性验证)、pnpm fixtures-projen（projen 反例 fixture）。

文档站点（Material for MkDocs）¶

文档站点锁定 mkdocs 1.6.1 与 Material for MkDocs 9.7.7。依赖锁是 pip-compile --generate-hashes 生成的完整内容锁（全部顶层与传递依赖都带 SHA-256 hash），见 scripts/docs/requirements.txt（人工输入只有同目录的 requirements.in）；工具链真源见 scripts/docs/toolchain.json。Python 3.10 或更高即可（node scripts/docs/verify-matrix.mjs 在最低版 3.10 与 tested 3.14 上都会用全新虚拟环境复现安装与严格构建）。

约定：不做系统级 pip install，虚拟环境必须建在仓库外部。原因是根 pnpm check 会对全仓做本地绝对路径字节扫描（见 node scripts/check-structure.mjs），而 macOS/Windows 上的虚拟环境内部嵌有本机绝对路径，放进仓库会造成误报。

安装命令统一使用 --require-hashes（内容锁要求逐条校验 hash）：

# 在仓库外部创建虚拟环境（路径可按需替换，示例用父目录）
python3 -m venv ../docs-site-venv

# 用哈希锁安装锁定版本（字节不符会直接失败）
../docs-site-venv/bin/pip install --require-hashes -r scripts/docs/requirements.txt

# 严格模式构建（任何警告都会失败），输出到 site/（已被 .gitignore 忽略）
../docs-site-venv/bin/mkdocs build --strict

# 本地预览（可选）
../docs-site-venv/bin/mkdocs serve

离线环境安装（固定流程）：在线机器只下载 wheelhouse，离线安装必须进入一个从未在线安装过的新 offline venv——复用在线 venv 无法证明离线链路可用：

# 1. 在线机器：下载 wheelhouse（下载同样逐条校验 hash；本步不安装到任何 venv）
python3 -m pip download --require-hashes -r scripts/docs/requirements.txt -d ../docs-wheels

# 2. 离线机器：新建一个从未在线安装过的 offline venv（路径可按需替换，不得复用 ../docs-site-venv）
python3 -m venv ../docs-site-offline-venv

# 3. 完全离线安装：不访问任何索引，只从 wheelhouse 解析，继续逐条校验 hash（字节不符直接失败）
../docs-site-offline-venv/bin/pip install --no-index --find-links ../docs-wheels --require-hashes -r scripts/docs/requirements.txt

# 4. 严格模式构建（任何警告都会失败）
../docs-site-offline-venv/bin/mkdocs build --strict

公开静态站（render-public-site.mjs）¶

公开静态站是本仓文档站的公开子集，唯一由 scripts/render-public-site.mjs 用上述冻结 MkDocs 环境渲染：

脚本只发现并校验冻结虚拟环境（SKILL_FAMILY_DOCS_VENV，或按本节步骤建的 ../docs-site-venv / ../docs-site-offline-venv），自身不做任何安装；
执行两次 strict 构建并要求树哈希一致（确定性），随后复用 scripts/leak-scan.mjs 核心与 scripts/leak-policy.json 做内容泄漏扫描；
--write 只写 docs/public/site/** 与 docs/public/site-baseline.json；--check 零写入重算并比对基线；--self-test 运行主动反例自测；
symlink、特殊文件、越界 realpath、单文件超限与不确定输出一律拒绝；基线禁止手改（渲染器是唯一写入面）。

node scripts/render-public-site.mjs --write
node scripts/render-public-site.mjs --check

站点文件与 engineering-kit public 发布镜像仓的 docs/** 逐文件对应（映射由发布配置执行，本仓不直接写镜像）；Pages 实例是否在线是发布后验证事实，口径唯一见当前产品状态。

文档事实与链接检查¶

文档中的版本、命令、包数与门禁事实由确定性脚本对照机器真源校验，链接由独立脚本解析：

node scripts/docs/fact-check.mjs
node scripts/docs/link-check.mjs

fact-check.mjs 是 Node 脚本，经仓内模块（scripts/engine-floor-check.mjs）消费根目录精确锁定的 semver@7.8.5，运行前必须先完成 pnpm install --frozen-lockfile；link-check.mjs 为纯 Node 实现（无第三方依赖）。两者退出码 0 表示通过。脚本职责见 scripts/docs/README.md。