保存环境方案并在另一台 Mac 恢复

更新：2026-10-17。主线沿用 ADR 0011 与机器工作台方向。本轮优先交付一个用户可操作的恢复入口，以两套隔离环境验证；第二台实体 Mac 仍需单独验收。

现有能力与缺口

环节	现有能力	本轮处理及后续缺口
启动	Electron 携带运行时；本机检测可独立于 Workstation 工作	分阶段检查 Apple 工具、Homebrew、Node/npm 与 Workstation；提供官方说明和终端命令，完成后复检
软件目录	内置目录、线上 / 本地 Git 来源、静态解析与缓存	方案引用目录中的软件身份；在目标机重新核对官网及安装标识
软件安装	来源自己的不可变计划、确认、进度、取消、历史及重新检测	复用软件中心；检查后选择方案中可安装的缺失项，不由方案提供命令
配置恢复	Workstation 纳管清单、差异、逐项方向、预览、应用、备份及恢复	保存已同步配置的引用；进入原配置审阅页，继续由 Workstation 写入
配置源同步	原配置界面已有独立 Git 审阅和发布流程	本机修改须先审阅并同步到源；未发布到目标机可读取的版本仍不能用于换机
便携方案	已有 Setup Profile 领域定义；设置与 Workspace 已有各自的便携合同	新增一个版本化环境方案，使用显式文件导出 / 导入；未接入自动同步
新机器连接	本机插件、CLI 定位与能力协商已有实现	新桌面包携带预构建 Workstation；配置源在页面输入 HTTPS 地址、认证并验证，所选引用继续实际复检
完成验证	软件有实际探测状态；配置有同步状态与版本检查	汇总真实状态；版本约束、项目工具链、项目恢复及真实项目启动验收留待下一阶段

最小闭环

入口为 开发环境 → 我的环境方案（/environment/setup）。

1. 在源 Mac 选择软件和已与来源同步的全局配置，保存方案。配置页中的本机修改需先审阅并保存到配置源，按需提交和发布。
2. 导出 craft-hub-environment.json，通过用户选择的文件传递方式带到目标 Mac。
3. 在目标 Mac 打开 Craft Hub，选择文件或粘贴 JSON，确认保存导入方案。
4. 在“准备目标 Mac”完成 Apple 工具、Homebrew 及所选配置源的必要步骤。新桌面包自动验证随应用提供的 Workstation，无需先安装终端 Node/npm 或构建后端。配置源直接输入 HTTPS 地址并连接，按需完成 Git 登录或在页面提供用户名与访问令牌。连接后自动复检；系统安装器和高级 CLI 宿主保留原说明。
5. 点击“检查这台 Mac”。每项分别显示已就绪、未检测到、待审阅、来源变化、来源不可用或检测未知。
6. 前往软件中心，审阅选中的缺失软件及来源计划，再确认安装。配置项进入对应的配置审阅页，核对源与本机差异，选择方向、预览并应用。
7. 返回方案页重新检查。只有新的探测及配置观测才能使条目显示就绪；重启后仍可重新检查已保存方案。

第一版保存一份当前环境方案，最多包含 50 项软件及 100 项配置引用，完整 JSON 不超过 256 KiB。导入会替换本机当前方案，保留导入前的实际软件、文件与执行信任。修改前比较本机修订，拒绝覆盖其他窗口或进程刚保存的方案；无效或未知版本的持久文件保持原样。锁随写入进程退出释放，保存中断后可重新读取及重试。

数据与职责

setup-profile.v1.json 位于 OS Craft Hub 数据目录。文件包含名称、目标平台、软件来源 ID、软件 ID、展示名称、官网、安装来源标识，以及配置集成 ID、稳定条目 ID、类型、公开 / 私有来源类别和源内容展示摘要。

方案表达期望状态，不保存探测结果、软件版本快照、配置文件正文、绝对路径、登录状态、密钥、源文件修订、应用计划、安装任务 ID 或项目信任。软件安装标识只用于与目标机可信目录核对，导入的安装标识不能成为安装配方。配置摘要只用于比较来源展示内容，不代表仓库身份验证、完整内容签名或执行授权。

配置源和软件目录继续独立管理。目标机缺少对应来源时保持“待连接”，来源内容变化时要求重新审阅。原安装和配置入口在实际操作时生成自己的最新计划，继续执行能力协商、并发修改拒绝与恢复边界。安装器或原生插件管理的 Skills、项目配置和未纳管文件不进入配置捕获。

Craft Hub 负责方案、检查汇总和导航；Workstation 负责配置解释、计划、文件写入、备份与同步；软件 Provider 和包管理器负责安装。首版文件传递不新增账号或同步系统，后续便携同步应接入既有 Personal / Team 模型。

前置引导使用只读 /api/environment/setup。核心负责 macOS 工具前提，可信 Host Plugin 通过 environmentSetupProviders 提供自己的安装与连接说明；动作仅为 HTTPS 链接或可复制文本，没有执行接口。命令来自宿主适配器，导入方案不能携带命令、仓库地址、路径或凭据。Workstation 的 Node/npm 前提独立于 Craft Hub 自带运行时检查，CLI 就绪要求协议能力协商成功，配置源就绪要求所选引用已在实际清单中可读取。打开文档、复制命令、连接命令退出都不直接标记完成；读取失败保持未确认，其他阶段仍可检查。

配置源连接是独立的显式写入接口 /api/environment/sources，通过 environmentSourceProviders 委托可信本机适配器。浏览器仅提交来源类别、无凭据的 HTTPS 地址、会话 ID 及本次认证，不提交命令或目标路径。运行时只保留短时进度，令牌经受限的本机 askpass 通道交给 Git，认证重试关闭 credential helper 写入。工作目录由宿主决定，先在临时目录获取并由 Workstation 验证，再保存私有来源绑定；原配置内容仍不写入，失败保留原有来源。原安装、配置审阅、项目执行信任各自保持独立。

新 macOS 打包流程在发布机从固定公开提交构建 Workstation，仅携带生产文件及依赖，当前约 2.6 MB，复用 Electron 运行时。包内不包含配置仓库或私有数据，配置写入始终指向用户目录。插件管理的“宿主扩展”展示随应用提供的引擎及版本；市场声明式插件与配置订阅源继续各自管理展示能力和期望环境，不能隐式安装可执行后端。已有本机 CLI 和显式宿主覆盖仍优先。市场按需下载可执行组件需要独立的安装、完整性与更新合同，不通过现有声明式 Catalog 绕过。

外部 CLI 宿主仍保留公开源码构建及 ~/.local/bin/workstation 入口登记说明。2026-10-16 验证时公开 npm registry 尚无 @yunyoujun/workstation 包，因此引导不显示未经发布的全局 npm 安装命令。连接说明与限制见开发环境配置指南。

验收与下一阶段

自动化覆盖独立数据目录的保存 / 导入 / 重新读取、未知与缺失状态、来源变化、重复条目、无效格式、未同步配置拒绝、并发保存、损坏文件保留、Hosted 拒绝和同源 JSON 边界。保存与导入不调用安装或配置写入，项目保持 untrusted。

隔离恢复验收使用源与目标两个临时 HOME、独立数据目录和本地克隆的配置仓库。配置预览 / 应用应调用真实 Workstation 引擎；软件安装使用仅写入临时目录的 Provider fixture。浏览器检查包括保存、文件导出、文件导入、软件计划确认、配置差异预览、应用、返回复检和重载恢复。

2026-10-16 的隔离验收已完成上述浏览器流程，目标状态依次为 0/2、1/2、2/2 就绪，重载后复检仍为 2/2。真实 Workstation 配置引擎验证了预览前不写入、重复预览无修改、陈旧计划拒绝覆盖较新编辑、备份恢复和重新应用。两个环境的项目始终为 untrusted。Chromium 在 1440×1000 与 390×844 检查页面、交互、横向溢出、框架错误覆盖层及控制台，未发现相关错误。Browser plugin not available，使用工作区内置 Playwright；未在真实机器安装第三方软件。

前置引导的追加验收从 Git、Homebrew、Node/npm 和 CLI 全部缺失开始，逐阶段模拟本机探测结果。在含空格与单引号的隔离 HOME 中实际执行页面提供的源码获取、固定版本 pnpm 安装、构建与入口登记命令；通过真实 Workstation CLI 从本地 Git fixture 连接私有配置源，再完成软件审阅 fixture 与真实配置预览 / 应用，复检及重载后均为 2/2。复制安装和连接命令不会推进阶段；过期结果、Provider 失败、Hosted 与跨源访问另有自动化覆盖。Apple / Homebrew / Node 安装器和真实私有仓库认证仍需实体 Mac 验收。

预构建后端的追加验收已在移除终端 Node/npm 的 PATH 和独立 HOME 中，通过真实 Electron 可执行文件读取 host-json、configuration 与 software-json。本地生成的 arm64 macOS 应用包也已启动验证，实际桌面 IPC 返回随附组件版本，点击市场宿主扩展页的恢复入口后能验证包内后端能力。隔离浏览器恢复无需 Workstation 源码目录，私有源连接与真实配置预览 / 应用后达到 2/2，重载保持结果；软件安装仍使用 fixture。Chromium 在 1440×1000 和 390×844 验证页面、交互、控制台与横向溢出。全量检查为 224 个文件、1763 项通过、2 项跳过，lint、根及 Vue 类型检查、构建通过。当前仅生成本地测试包，未发布新版本；x64 包及实体新 Mac 的安装器、认证与真实软件安装仍待验证。

2026-10-17 的配置源界面验收使用带 Basic 认证的隔离 HTTPS Git 服务器、临时 CA、独立源 / 目标 HOME 和真实 Git / Workstation。浏览器完成地址输入、取消认证、错误令牌拒绝、正确令牌重试、克隆及验证绑定；连接前后本机配置保持不变，随后审阅软件 fixture 和真实配置预览 / 应用，达到 2/2，重载保持结果。无效仓库拒绝后原来源绑定和本机配置保持原样；目标数据目录与状态响应未发现测试令牌。页面切换 / 缩放触发的滚动空引用已补防护，桌面与 390px 窄屏重放通过，控制台无相关错误。重新打包的 arm64 客户端也实际完成地址输入、HTTPS 认证、绑定及真实配置预览 / 应用，保留已有配置，使用包内运行时。全量为 230 个文件、1785 项通过、2 项跳过；lint、根及 Vue 类型检查、构建通过。尚未发布新版本，真实托管账号的认证、SSH 与实体新 Mac 安装仍需后续验收。

后续按优先级推进：

1. 真实第二台 Mac：从个人实际方案中选择少量软件及一项终端配置，验证前置安装、源连接、真实安装和一个项目启动；记录耗时与手动步骤。
2. 独立组件分发：新桌面包已免去终端 Node/npm 和后端源码构建；后续需要按需下载或独立更新时，为可信本机组件补充专用安装、完整性与更新合同，保留声明式市场插件及配置订阅的边界。
3. 项目与版本要求：在现有项目引用模型上补充克隆、路径重绑定、工具链要求及实际运行检查，继续单独确认项目执行信任。
4. 方案分发与同步：复用 Personal / Team 同步目标，携带方案和配置源身份；本机观测及绑定仍留在目标机。

全新机器全自动配置、跨平台恢复及真实项目可运行性不属于这次隔离验证的通过结论。