安装与环境¶
本页用于准备 Foundation 私有工作区的研发环境。项目只想判断某项已发布能力是否适用时,无需先初始化或升级。把已发布版本、同版本能力目录查询结果和只读 adopt-plan 结果交给唯一的 foundation-adoption-review Skill。该 Skill 没有要初始化的项目对象,也不代为安装依赖、运行 check 或执行资格探测。
先判断是否需要调整环境¶
- 先对照下方版本约束,确认现有 Node.js、pnpm 与项目依赖是否已经满足要求。满足时保持现状,不重复安装。
- 需要分析存量仓时,先运行只读
adopt-plan,查看写集、冲突和迁移条件。参考骨架差异只用于规划,不要求项目复制本仓目录。 - 版本不满足但现有已发布能力仍够用时,可选择继续锁定原发布版本。只有目标能力或安全修复明确要求新版本时,才安排升级。
- 安装、升级、
scaffold、projection和存量文件修改都属于工程动作。调用方必须先明确授权、写集和验证入口,再执行对应命令;Foundation 不提供存量仓通用apply。
普通 check 静态读取声明、配置和文件,不运行目标 Skill、业务脚本或 hooks。下文的包测试、宿主驱动和根门禁属于 Foundation 研发自测,只验证本工作区产品。它们不能替代消费者的领域门禁、真实宿主资格或独立审计。已发布能力、候选能力与本地未发布源码分别判断,当前状态以当前产品状态为准。
必需环境¶
| 工具 | 版本 | 锁定点 |
|---|---|---|
| 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。
安装与原生环境¶
本候选环境基于 Windows 11 x64 平台,使用本地 NTFS 文件系统,以普通用户身份运行,使用原生 Node.js;WSL 结果不能充作 Windows 资格。原生 Node.js 版本需满足 >=22.22.2 <23,包管理器为 pnpm 10.30.0,且三个叶子包必须保持完全一致的精确版本。预构建装载不触发编译或二进制下载;npm 依赖安装仍由调用方管理。官方宿主进程可能联网,调用者负责认证与外部动作授权。
安装过程通过精确的 npm/pnpm 启动机制执行,依赖包内预构建的 win32-x64 N-API 二进制文件,不依赖消费者本地编译环境。启动时使用 npm 的 bin/npm-cli.js 或 pnpm 的 bin/pnpm.cjs 作为可执行入口,不解析 .cmd 或 .bat 文件,也不通过后缀名推断执行逻辑。官方宿主 .exe 入口仍需绑定真实可执行身份,其点时身份仅用于上下文识别,不构成签名信任或内核映像的证明。