环境 Doctor 与安装器为什么必须分开

自动化环境配置如果把“检测缺失”和“立即安装”写在同一个流程里，很容易覆盖用户配置、下载不可信制品或在已经可用的机器上制造差异。更稳妥的 Harness 会把 Doctor 与 Installer 做成两个权限完全不同的组件。

Doctor 只读

Doctor 根据任务 Profile 检查真正需要的运行时、命令行工具、外部连接和系统能力，并输出 passed、fallback 或 blocked。它可以检查版本和可调用性，但不下载、不改 PATH、不注册服务，也不把“存在配置文件”误判为“当前会话可用”。

Installer 是显式写操作

只有 Doctor 给出缺口且用户允许安装时，Installer 才执行。每个来源需要固定版本、校验摘要、候选下载地址和平台映射；全部来源不可达就中止，不能在未知网站上临时搜索并执行。凭据不进入命令行和安装日志。

重装也要可恢复

安装目录保存版本标记。版本与摘要一致时跳过解压；需要升级时先在临时目录完成下载、校验和解压，再合并允许保留的用户配置，最后原子替换。失败时旧版本仍可使用。强制覆盖必须是单独、明确的选择。

安装后重新诊断

“写入配置成功”不是验收。安装后重新运行同一 Doctor，检查二进制版本、帮助命令和只读连接；需要重启会话才能发现的新能力，要明确告诉用户，不能提前宣布就绪。

这套分离让安全边界非常清晰：诊断可以默认运行，安装需要依据与授权，凭据由运行环境提供，最终状态由第二次只读检查证明。

第二轮实践复核

可复用交付物： 只读诊断报告、安装来源清单和复检结果。这些内容是从工程实践抽象出的通用方法，不包含内部仓库、真实工作项、业务数据、凭据、地址或实现源码。

最低验收： 诊断不写系统；安装失败保留旧版本；安装后用同一 Profile 重新检查。验收记录必须分开事实、推断、缺口和授权范围；只读检查不能自动扩展为提交、推送、评论或发布。

Doctor 报告的机器契约

{
  "profile": "node-blog-build",
  "status": "blocked",
  "checks": [
    { "id": "node", "status": "passed", "observed": "v24.x", "required": ">=24 <25" },
    { "id": "package-manager", "status": "passed", "observed": "npm" },
    { "id": "registry", "status": "fallback", "reason": "primary timed out" },
    { "id": "renderer", "status": "blocked", "reason": "binary not found" }
  ],
  "writes_performed": 0
}

状态需要稳定定义：passed 表示主路径满足，fallback 表示有被允许且已验证的替代路径，blocked 表示任务无法安全继续。进程退出码与顶层状态对应，CI 不必解析自然语言。

检查“命令存在”还不够。Doctor 依次验证解析到的绝对路径、版本、最小只读子命令和当前会话可见性。网络检查使用 HEAD/健康端点和短超时，不下载完整制品；凭据检查只判断存在性与作用域，绝不回显值。

Installer 的事务式步骤

阶段	写入	失败处理
plan	无	输出来源、版本、摘要和目标路径
acquire	临时目录	删除本次临时制品
verify	无额外写入	摘要/签名不符立即停止
stage	版本目录	不改当前版本指针
activate	原子切换指针	恢复旧指针
diagnose	无	复检失败则回滚激活

安装计划绑定平台、架构和版本，下载后的实际摘要必须与计划一致。解压要防止路径穿越和符号链接逃逸；安装脚本不能自动提升权限。并发安装使用锁和唯一临时目录，陈旧锁有明确恢复规则。

测试覆盖 PATH 中同名假命令、版本过旧、主源超时后可信镜像成功、摘要错误、磁盘不足、激活中断和新会话才生效。验收不仅看成功安装，还要证明 Doctor 前后差异准确、失败后旧版本可运行、日志无凭据，重复执行不会继续产生变化。

公开规范

SLSA 供应链要求

规范复核日期：2026-08-22。

小规模演练

先运行只读 Profile，再依据 blocked 项生成安装计划；安装后重跑同一 Profile 并比较结果。

失败注入： 故意提供一个缺字段、过期版本或无权限目标，确认流程停在预定门禁。
观测指标： 误报缺失数、安装失败数、复检仍不可用数。
回滚方法： 安装失败不得删除旧版本；使用原子目录恢复，凭据和用户配置保持原位。