为人类和智能体构建的 Spaces CLI

TL;DR

Mistral AI 发布了 Spaces，这是一个命令行界面，让开发者只需通过三个命令即可创建、运行和部署多服务项目，并且其设计初衷是让每个交互式提示都有对应的 flag 或配置等效项，从而使自主 AI 智能体能够在无需人工干预的情况下使用该工具。

什么是良好的开发者体验

Spaces 专注于消除重复的设置工作。它选择合理的目录布局，自动生成配置文件，并将服务连接在一起，使得新项目在运行以下命令后即可运行，并具备热重载、数据库和 Dockerfiles：

$ spaces init my-project
$ cd my-project
$ spaces dev

该 CLI 将命令分为三个功能桶：

  • Scaffolding – 创建项目结构，提出问题并显示选项。
  • Development – 通过单个 spaces dev 命令运行内部开发循环。
  • Operations – 执行需要明确确认的生产级操作。

为第二类用户设计：AI 智能体

当一个 AI 编程智能体尝试使用 init 的交互式 TUI 选择器时，它遇到了原始的 ANSI 转义码，并且无法导航 UI。简单的修复方法是暴露一个 --components flag，但更深层的见解是：每一个由 CLI 请求的信息都应该有一个非交互式的表示形式。

Flag 作为通用契约

每个交互式问题都代表一个契约：CLI 需要一个值才能继续。通过提供 flag、配置文件或默认值，无论输入如何到达，相同的业务逻辑都会运行。实现示例：

def init_command(
    components: str | None = Option(None),
    yes: bool = Option(False, "-y"),
):
    if components:
        selected = components.split(",")
    elif yes:
        selected = get_defaults()
    else:
        selected = show_picker()
    create_project(selected)

-y flag 标志着调用者通过程序化方式提供所有必需的数据，这会导致 CLI 在任何必需输入缺失时直接报错，而不是停留在 stdin 上等待。

端到端智能体工作流

智能体现在可以：

  1. 运行 spaces --help 来发现命令签名。
  2. 自动生成 config.yaml 和 context.json。
  3. 连接 Dockerfiles、注册表设置和 CI 流水线，无需人工干预。
  4. 在不到十分钟内将仓库部署为 Koyeb 上的一个 Space。

因为每个交互式提示都有对应的 flag 等效项，智能体可以从启动到部署实现自主运行。

使用结构化数据作为接口层

Spaces 使用插件系统，其中每个模块都由数据模型而非硬编码逻辑来描述：

class ModulePlugin(BaseModel):
    type_id: str
    category: str
    default_port: int
    def get_env_vars(self) -> list[EnvVarDef]: ...
    def get_dev_command(self, port: int) -> str: ...

插件是可内省的、可序列化为 JSON 的，并且可以进行差异对比。人类通过 TUI 选择器进行交互，而智能体查询注册表并接收 JSON。添加新模块现在只需要一个新的插件类，从而消除了在选择器、Dockerfile 生成器和 compose 模板中重复更新的需要。

为智能体提供上下文

Spaces 在每次 init 时生成两个文件：

  • context.json – 项目模块、端口、命令和环境变量的快照。
  • AGENTS.md – 为 LLM 提供的明确的程序化指令，例如：“在测试数据库更改之前，运行 mycli dev --migrate”。

这些产物为智能体提供了可靠的真理来源，减少了猜测并防止了诸如使用错误的端口或安装重复依赖项之类的错误。上下文文件还充当了缓存失效器；每当项目配置发生变化时，它会自动更新。

消除隐式状态

隐式假设（例如，依赖当前工作目录）会破坏智能体自动化。修复方法是让所有状态显式化，并提供合理的后备方案：

# Before
config = load_config(Path.cwd() / "config.yaml")
# After
config = load_config(
    path or find_config_in_parents(Path.cwd())
)

使 CWD、环境变量和 dot-file 位置显式化可以提高智能体可靠性和人类编写脚本的效率。

智能体友好型实践清单

  • 每个交互式输入都有一个对应的 flag。
  • Flags 为无头执行提供智能明的默认值。
  • 所有状态（路径、环境变量、配置）都是显式传递的。
  • 插件是纯数据模型，可自动进行内省。
  • context.json 和 AGENTS.md 给出智能体结构化的项目描述。

为什么这能为所有人提供更好的工具

新增的面向智能体的设计 does not 降低人类的体验：TUI 选择器、加载动画和确认对话框仍然保持不变。相反，为了智能体所需的约束（显式输入、基于 flag 的契约、结构化元数据）同样也使 CLI 变得更具组合性、可编写脚本化和可测试性，对于开发者而言也是如此。

Mistral AI 建议任何开发者工具的创建者审计每一个 input() 调用、CWD 假设和仅限人类的观察输出，并询问：非人类过程是否可以使用相同的接口？解决这些问题可以为人类和智能体提供更更强大的工具。

Spaces CLI was built by Lorenzo Signoretti, Riwa Hoteit, and Sam Fenwick at Mistral AI, with feedback from the Applied AI team.

Sources