个人软件与开发环境工作台

更新：2026-10-12。产品方向见 ADR 0011。当前路线由用户的软件安装、工具跳转与环境迁移需求驱动；下列待办不代表已经交付。

Craft Hub 帮助用户准备并使用一台能工作的电脑：看清软件和环境状态，选择缺失工具，审阅配置恢复步骤，完成后打开日常工具。“迁移”在这里指换机或重装后的配置与项目恢复，不是把 Workstation 的实现复制进 Craft Hub。

默认流程与首页

扫描这台电脑
  → 选择希望具备的软件与配置清单
  → 预览实际差异与准备步骤
  → 安装所选软件 / 审阅并恢复配置
  → 重新检查可用性
  → 打开日常工具与项目

首页拟以常用软件和环境就绪状态为主，展示缺失项、正在进行的准备步骤、需要手动处理的事项与最近检查时间。工作项、项目能力和外部交接保留为辅助入口，不再以跨来源任务闭环作为第一个交付目标。现有 /overview 尚未按这个方向重新实现。

“打开应用”“打开网站”“下载安装”是不同操作。安装记录成功后必须重新探测可用性，不能把下载完成、进程退出或配置文件存在等同于环境可用。Raycast 可承担快捷触发，Orca 等工具承担实际编码；Craft Hub 展示准备过程与持续状态。

一级侧栏顺序

一级入口收敛为：首页 → 项目 → 工具 → 开发环境 → 工作台。插件管理、诊断、账户、设置固定在桌面侧栏底部；移动端沿用相同顺序并清除底部留白。

• 首页只展示工作摘要、常用项目和前六个收藏工具，不再载入完整插件导航；查看全部工具进入 /tools。
• 项目保留原有项目侧栏与工作区树，配置源作为项目的二级入口。订阅、发现、详情和预览链接保持可用。
• 工具分为常用工具、软件中心、网站导航。完整收藏管理在 /tools，软件安装与进度继续由 /software 提供，插件网站链接由 /navigation 提供。
• 开发环境分为本机检测与环境配置。所有声明 configuration-manager block 的集成按能力归入环境配置，不依赖 Provider 名称。Workstation 的配置视图称为“环境配置”，既有检查、计划、确认、备份与恢复合同不变。
• 工作台入口 /workbenches 分类展示已安装工作台与独立集成。组合工作台保留自己的内部用途分组；被收纳的独立集成继续遵循原有隐藏规则，显式 showInSidebar 视图仍能从分类导航找到。

旧软件、导航、环境和插件链接不重定向；打开后由声明的能力高亮所属一级分类。诊断继续聚合 Craft Hub 配置、市场源、插件和集成问题，账户负责身份与登录，设置负责应用偏好与现有同步配置。

能力分工与现状

能力	已有事实	第一版缺口与归属
软件目录	Workstation 有分类、官网、下载页、cask / MAS 信息与 Brewfile	Workstation software-json v1 提供只读目录，Craft Hub /software 展示分类、搜索、官网、下载与源码入口，并可加入个人常用
安装状态	Workstation 仓库脚本检查应用目录、PATH、brew / MAS	软件目录按常见 macOS 应用目录或可执行路径报告已检测 / 未检测到；无检测声明或其他平台报告未知。进一步补版本、来源和检测失败原因
软件安装	software-json 提供按软件 ID 的不可变计划、独立 worker、逐项结果及本机历史	首版在 macOS 使用 Homebrew 安装声明的 cask / formula；其他来源保留官方下载入口
工具打开	software-json 通过软件 ID 重新检测并打开 macOS 应用；网站和下载入口独立	补充其他平台的可信宿主打开适配器
环境诊断	Craft Hub /environment 只读检查 Git、Node、pnpm、fnm、Homebrew 与 Workstation 的路径、版本和来源，单独展示后台 Node 与宿主架构；Workstation doctor 检查配置、chezmoi / APM	补充工具本身的架构与选定项目环境检查；环境检测不依赖 Workstation 已安装
配置恢复	Workstation configuration v1 与现有开发环境插件提供检查、预览、应用、历史、恢复及 Git 动作	复用既有计划和备份；补源连接与分阶段向导，不再实现另一套合并引擎
项目恢复	Workstation 有项目清单、克隆 / 状态 / 布局迁移能力	提供稳定的结构化合同，恢复后重新绑定 Craft Hub 的本机项目路径；项目仍需独立信任

Workstation 的 software.config.ts 继续作为软件清单的唯一来源，新增独立 workstation software-json 命令，读取 stdin { "version": 1, "operation": "catalog" }，返回版本化目录。Host Plugin 通过 softwareCatalogProviders 提供只读目录及可选管理接口；软件安装计划、执行和进度由 Workstation 独立持久化，配置同步仍走 workstation configuration。读取不会触发安装或配置写入。目录只传展示、安装来源和链接元数据，不能透传或执行 installCommand；浏览器不能指定宿主命令或源文件路径。目录读取不要求项目信任，也不改变已有项目信任。

软件中心的「下载」打开官方安装/发布页，不代表已安装或安装成功。缺失且支持自动安装的项目可单项或批量审阅；确认后逐项显示进度与文本日志，安装完成重新检测。停止任务保留已完成项，失败、中断和停止项通过新的计划审阅重试。历史由 Workstation 保留，刷新或重启界面后可恢复。应用目录和可执行路径检测范围有限；not-detected 不证明软件不存在，unknown 不显示缺失。缺失或不可用的 Workstation 回退到内置目录，安装状态为未知，仍可搜索、筛选、下载和收藏；刷新后重新尝试本机检测。Craft Hub 直接静态解析唯一的 software.config.ts，默认携带经过验证的 TS 副本，运行时不依赖相邻仓库，也无需导出 JSON。安装和配置管理继续走插件；托管工作台只读取静态目录。维护步骤见软件目录。

插件安装的下载阶段显示当前文件的圆环百分比，数值来自 Workstation 读取的 Homebrew/curl 实际进度；提示中注明当前文件，多个依赖分别计数。总量未知时只显示正在下载；下载、校验完成并开始安装后切换为正在安装。卡片与安装记录使用同一状态组件，刷新后从持久化历史恢复。安装和打开采用轻量胶囊按钮；下载与安装阶段显示独立圆形控件，百分比位于圆环旁，支持键盘操作与减少动态效果。卡片上的停止按钮作用于整个安装任务，批量任务的提示包含剩余项目，不提供暂停语义。外部下载链接仍打开官方下载页。

可携带的 Setup Profile 保存想要的软件与配置来源；Environment Snapshot 描述当前机器观测状态，两者分开。软件清单、终端配置、MCP / skills、项目引用可以分别恢复；本机路径、登录状态、执行信任与密钥值不作为同一份便携配置迁移。安装和配置恢复是不同阶段，不承诺系统级事务或统一回滚。

P0：软件状态与每日入口

• 证明工作台在没有 Node、Homebrew 和 Workstation 时也能打开，并展示可行的下一步；这是新机器流程的前提。当前保留自带运行时的 Electron 默认入口，外部工具的缺失单独报告；基础启动检查不依赖 Workstation 插件或其目录 API。
• 在 Workstation 增加版本化、只读的软件目录与初步状态合同，复用现有目录；首版仅检测常见 macOS app 目录。
• 软件中心提供分类/搜索、检测状态、官网、下载、源码和加入个人常用；个人工具可编辑下载/源码链接，原有 Raycast / Orca 预设继续可用。
• 增加受控的 macOS 本机应用打开合同，打开前重新检测；自动安装完成后重新检测。
• 补充软件版本、检测路径和检测失败原因。
• 用户可勾选软件形成计划，预览安装来源、动作与 Homebrew 前提；宿主仅传软件 ID，不接受清单中的任意 shell 字符串。包管理器解析和安装必要依赖，首版不提供完整依赖差异预览。
• 支持安装计划逐项执行、取消或停止后续项、失败重试与重新探测；手动安装和平台不支持项目明确保留手动状态，命令成功但未检测到软件报告失败。
• 仅安装选中的缺失项，已检测软件跳过；禁用 Homebrew 自动更新、安装时对目标包的升级、清理及已安装 dependents（依赖该包的软件）检查。Homebrew 仍会处理必要依赖；不会执行整个 Brewfile 或调用 brew upgrade。独立的升级流程尚未实现。
• 软件中心支持关联线上与本地 Git 仓库，静态解析 TS 清单，提供预览、刷新与缓存；本机检测和安装仍由可信宿主适配器完成，仓库配置不作为程序执行。

验收：缺少 Workstation 时仍能看到启动检查和引导入口；已装应用直接打开；缺失应用在审阅后安装并重新检查；一个应用失败不会把其他应用显示为失败或完成；重试不重复成功项，未知状态不显示“环境就绪”。

本轮软件中心验证：Craft Hub 完整 lint、类型检查、构建与串行全套 1006 项测试通过（2 项平台相关跳过）；Workstation 284 项测试通过。安装、进度、取消、重试和打开行为用隔离 fixture 验证，Chromium / WebKit 在 1440、768、390、320px 检查通过。已重新安装 macOS 应用并验证真实目录和 iTerm2 安装计划预览，保留原有 8 项常用工具；未在用户机器上执行第三方软件安装。默认外部 Codex 包为 335.15 MiB。并发全套运行时，已有 Git 集成测试曾超过 5 秒限制，独立与串行全套均通过。

P1：环境检查与换机恢复

• 环境页只读检查固定工具的可执行路径、版本和来源，区分工作台后端 Node 与本机搜索路径中的 Node，显示宿主架构、检查时间和逐项错误；Finder / 终端的搜索路径差异通过来源与检索路径展示。
• 补充工具本身的架构、所选项目的环境要求及其 Node 版本；本机 Node 观测结果不证明某个项目已经可运行。
• 连接用户选择的配置源，分别选择软件、终端配置、MCP / skills 与项目恢复；展示平台不适用、无权限、未连接和本机冲突。
• 配置步骤复用 Workstation 的检查、逐项决定、不可变预览、并发修改拒绝、备份与恢复，不改变既有同步权威。
• 源更新 / 远端同步与本机应用分别审阅；恢复项目后重新绑定本机目录，配置恢复不授予命令执行信任。
• 记录每阶段的实际结果与后续步骤，支持重启后继续；登录、权限提示与手动安装可保持“等待用户处理”。

验收：用隔离 HOME 与配置源在新机器场景恢复一套选定环境；已有本机修改会被识别并保留选择；中断后只重做未完成阶段，诊断不能将账号登录和文件恢复混作成功。

P2：便携方案与分发

• 保留共享 Node 后端与 Electron；macOS 默认使用本机 Codex CLI，缺失时可通过软件中心按需安装。工作台启动无需 Codex CLI 或本机 Node，已有 SDK 调用与项目信任保持原合同；显式 CRAFT_HUB_DESKTOP_CODEX_MODE=bundled 保留内置 CLI 兼容构建。Workstation CLI 本身仍需要本机 Node。
• 将其余内部 Agent 执行调用者迁移到外部工作台，再评估是否移除 SDK。包体积测量见 桌面包分析。
• 若继续 Tauri + 本机 Node，先提供独立的启动检查 / 设置页与可验证的引导合同，再谈默认分发；不能先调用依赖 Node 的 Workstation CLI 来查找缺失 Node。
• 将便携方案接入已有 Personal / Team 配置源模型；软件偏好与本机观测、路径绑定保持分离，不创建第二套账号与同步系统。
• 在同功能范围测量完整安装包、首次使用步骤、启动和内存，再决定轻量宿主；自动配置所有软件账号、通用终端和内嵌 Agent IDE 不作为本轮目标。

参考：Homebrew Bundle 的安装 / 检查 / 升级语义、已有 Workstation 配置接入、此前交接与宿主实验记录。

UI 统一

环境页复用现有页面框架、语义 token、按钮、状态标记与错误提示。UI 统一路线 已接入 YunLeFun 的 CSS 基础和 Workspace / Admin 密度，保留工作台布局、Reka UI 交互与专用组件。软件和环境品牌图标通过本地 Iconify collection 编译，未核实品牌保留语义图标。

环境检测只在打开环境页或手动刷新时执行固定版本探测，不执行 shell 初始化、项目脚本或软件安装。missing 表示当前搜索位置未找到，不代表软件未安装；失败输出经过归纳，不返回环境变量或原始工具输出。Hosted 模式拒绝本机检测，普通浏览器连接本地 API 时观察的是该 API 宿主。