SpaceApp 安装体验升级：从一条命令到第一个页面

SpaceApp 是一个自托管的 AI 编程工作空间，它把 AI 编码 CLI 装进隔离的“房间”里运行。每个房间组织一项工作，房间内的每个面板都是一个独立的 CLI 或应用会话。支持的运行时包括 OpenCode、Codex、Gemini、Qwen Code、Kimi Code、Grok Build 和一个实验性的 DeepSeek CLI；Claude Code 则有独立的、由所有者发起的安装流程。

最近的几个安装版本聚焦于同一段体验：从运行安装器到拿到第一个有用回答之间的那段时间。本文按步骤拆解这条路径，并说明每一步发生了什么变化。

安装：一条命令与明确的门槛

SpaceApp 要求 Linux、macOS 或 Windows 11，Node.js 20.11 或更新版本，以及至少 4 个 CPU、8 GB 内存和 15 GiB 可用磁盘。标准配置（会额外加入一个受管理的浏览器）建议 8 个 CPU、16 GB 内存和 25 GiB。

npx --yes run-spaceapp@latest install

启动器负责管理核心 API 与 Web 应用、各 CLI 运行时、PostgreSQL 和 Temporal。默认的轻量配置不包含受管理的 Chromium；标准配置会同时启动一个浏览器容器。这种“一条命令装全套”的思路，把原本分散的依赖编排收拢到一个入口，对自托管场景相当友好。

Temporal 是一个开源的持久化执行（durable execution）工作流引擎。在 AI 编程工作空间中，一次智能体任务往往包含多个步骤：读取文件、调用工具、等待人工确认、重试失败操作。如果进程崩溃或重启，普通代码会丢失执行状态。Temporal 把每个步骤的状态记录在事件历史中，服务恢复后可以从断点继续，而不必从头重跑。SpaceApp 把 Temporal 纳入默认安装，意味着面板会话和任务编排具备崩溃恢复能力，这对长时间运行的编码智能体尤其实用。对于自托管用户，这也意味着需要额外维护一个 Temporal 服务实例。

PostgreSQL 在此扮演的是持久化存储角色，通常保存工作区元数据、会话记录和任务状态，与 Temporal 的事件历史配合构成状态层。安装器把两者一并编排，省去了用户分别部署和配置连接的步骤。

创建所有者账号：注册工作区是前置条件

安装通过就绪检查后，你需要用一次性设置令牌创建第一个账号、注册希望智能体工作的文件夹，并通过各提供方的官方登录流程或掩码凭据输入来连接它们。

主机文件夹只有在被注册为工作区之后才可见，同时也支持只读挂载。这一点值得留意：它不是简单的“授权访问某个目录”，而是显式地把目录纳入工作区模型，权限边界更清晰。

本次更新在设置向导的“就绪”步骤中提供了三个可复制的首个提示词，降低了“装完之后不知道下一步做什么”的空白感。

第一个模型：用真实工具调用做验收

第一个 OpenCode 面板会从一个免费模型 Big Pickle 起步。一个模型只有在完成一次真实的工具调用后才算“可用”：它必须用自己的读取工具读取一个小文件，并回答文件中的随机令牌。如果 Big Pickle 未通过这项检查，系统会改用最新的、具备工具调用能力的免费模型。

这个验收方式比“能返回文字”严格得多。免费模型的上游随时可能变化，如果你正在使用的模型停止响应，可以在 OpenCode 中另选一个。

工具调用（tool calling） 指模型在生成文本之外，能够输出结构化的调用请求，让运行时去执行读取文件、运行命令等操作，再把结果返回给模型继续推理。它是编码智能体的基础能力：没有工具调用，模型只能“说”而不能“做”。正因如此，仅验证模型能返回文字并不足以说明它可用——模型可能支持对话却不支持函数调用，或在调用格式上不符合运行时要求。SpaceApp 用“读取小文件并回答其中随机令牌”作为验收，实际上同时检验了三件事：模型是否发起工具调用、运行时是否正确执行、结果是否被模型正确消费。这比单纯的连通性测试更贴近真实使用场景。

第一个提示词：两个曾经卡住新用户的问题

据原文说明，这里过去有两个障碍。

没有项目的房间无处可写。 现在，这类房间中的 CLI 面板会从 /workspaces/<room> 启动，因此像“给我建一个页面”这样的首个提示词会把 index.html 写在那里。

首个任务可能停在权限提示上。 在 macOS 上，第一个 OpenCode 任务曾会停在“访问外部目录 /tmp”上等待人工应答。现在 OpenCode 的首次运行只授权它自己的私有暂存目录，引导指令也会把临时文件发送到那里；工作区之外的其他路径仍然会询问。这相当于把“默认放行范围”收紧到最小必要集合，既减少打断，又不扩大权限面。

工作区（workspace）模型 是理解权限边界的关键。在 SpaceApp 中，主机上的目录并不会自动对智能体可见，只有被显式注册为工作区后才纳入可访问范围；未注册的路径默认位于边界之外，需要人工确认。这与容器挂载的思路类似：挂载什么、以读写还是只读方式挂载，都是显式决策。/workspaces/<room> 则是房间内的默认工作目录，CLI 面板从这里启动，使首个提示词产生的文件有确定的落点，而不是散落在进程当前目录或临时目录中。理解这两层——工作区注册决定“能看见什么”，面板启动目录决定“默认写到哪里”——有助于排查智能体找不到文件或写入失败的问题。

保持更新：应用内提示与一键复制

当存在更新版本时，应用现在会显示“Update available”，并打开带复制按钮的更新命令：

npx --yes run-spaceapp@latest update

对于自托管工具来说，更新路径的顺滑程度往往决定了用户是否会长期跟进版本。把命令直接呈现在界面里，比让用户去翻文档更实际。

尝试之前需要知道的几件事

SpaceApp 是为单个自托管实例上的单个可信所有者设计的，这决定了它的安全模型假设：不去防御多租户场景下的横向攻击。

备份是可移植且带校验和的，覆盖应用数据、PostgreSQL 和所有者记忆；但提供方凭据、登录状态、工作区内容和浏览器配置文件不在备份范围内。这意味着迁移或恢复时，凭据需要重新连接，工作区数据要自行管理。

遥测是选择性加入的。回答“否”则什么都不发送；回答“是”则会在智能体首次完成回答时发送一个匿名事件，包含事件类型、随机 ID、版本、CPU 架构和日期。

作者也在征集反馈：首个五分钟仍在哪里断裂、你的操作系统、安装器选择的配置，以及卡住的那一步。完整的发布说明可以在其 GitHub 仓库的 releases 页面找到。

对于想在自己机器上跑 AI 编码智能体、又不想把代码交给第三方托管的人来说，这类把安装、模型验收和权限边界都做进产品流程的尝试，值得关注。

单所有者自托管 是一种明确的安全模型取舍。SpaceApp 假设一台实例只服务一个可信用户，因此不构建多租户隔离、租户间权限校验等机制。在这样的假设下，省略这些防护是合理的设计简化；但一旦把实例暴露给多人使用，或让不可信输入驱动智能体，原有假设就不再成立。同样，备份范围排除了提供方凭据、登录状态和浏览器配置文件，是因为这些内容往往与具体机器和会话绑定，迁移后重新连接比复制更安全。评估这类工具时，先确认其威胁模型与自己的使用方式是否一致，比逐项对比功能更重要。