边车服务 (Sidecars)

边车服务（Sidecars）是与 Antigravity 并行运行的后台进程。Antigravity 负责管理边车服务的生命周期，自动启动它们，并在它们崩溃或报错时重新启动。它们对于持久后台脚本、定时循环任务以及响应事件非常有用。

配置方式 (Configuration)

Antigravity 通过搜索 sidecar.json 配置文件来发现边车服务。它们可以定义在两个位置：

• 全局边车服务：位于 ~/.gemini/config/sidecars/
• 插件边车服务：位于 ~/.gemini/config/plugins/<pluginName>/sidecars/

每个边车服务都有自己的专属目录，且该目录名称将被用作边车服务的 ID。从插件加载的边车服务，其 ID 格式为 <pluginName>/<sidecarName>。

边车服务的目录必须包含一个 sidecar.json 文件，也可以包含其他辅助文件（如待运行的脚本）。该目录同时也会作为执行边车服务命令的当前工作目录。

示例目录结构

~/.gemini/config/sidecars/
├── sidecar1/
│   ├── sidecar.json
│   └── script.py
└── sidecar2/
    └── sidecar.json

~/.gemini/config/plugins/
└── my-plugin/
      └── sidecars/
            └── plugin-sidecar/
                  └── sidecar.json

配置模式 (Config Schema - sidecar.json)

• command (string)：要执行的命令/可执行文件（例如 python3 或 /bin/bash）。与 builtin 互斥。
• builtin (string)：要执行的内置命令。目前支持 schedule。与 command 互斥。
• args (string[])：可选。传递给命令或内置函数的参数。
• restart_policy (string)：可选。重启行为。可选值为 always、on-failure 或 never。默认为 always。
• description (string)：可选。关于边车服务作用的易读描述。
• env (object)：可选。为边车服务进程设置的环境变量映射。
• display_name (string)：可选。在用户界面（UI）中显示的名称。

command 或 builtin 必须设置其中之一。

示例

{
  "description": "Background worker",
  "command": "python3",
  "args": [
    "worker.py"
  ],
  "restart_policy": "on-failure"
}

{
  "description": "Hourly agent to triage review requests.",
  "builtin": "schedule",
  "args": [
    "0 * * * *",
    "agentapi",
    "new-conversation",
    "Give me a summary of incoming review requests."
  ]
}

用户启用配置 (User Configuration - config.json)

除非用户在全局配置文件（位于 ~/.gemini/config/config.json）中显式启用，否则边车服务默认是禁用的。

• enabled (boolean)：是否启用该边车服务。
• projectId (string)：可选。在使用 agentapi 创建对话时关联的项目 ID。

示例

{
  "sidecars": {
    "sidecar1": {
      "enabled": true
    },
    "my-plugin/plugin-sidecar": {
      "enabled": true,
      "projectId": "<projectId>"
    }
  }
}

运行时数据 (Runtime Data)

边车服务产生的运行时数据存储在 ~/.gemini/antigravity/sidecar_data/<sidecarId>/ 中。

包括以下内容：

• data/：存放任何持久化数据的子目录。该路径可以通过环境变量 ANTIGRAVITY_EXECUTABLE_DATA_DIR 获取。
• logs/：自动生成的带时间戳的 stdout 和 stderr 日志。
• events/：为 agentapi 调用记录的 JSON 文件。

schedule 内置命令 (Builtin)

schedule 是用于运行周期性循环命令的内置调度程序。

{
  "builtin": "schedule",
  "args": [
    "* * * * *",
    "<command>",
    "<arg1>",
    "<arg2>"
  ]
}

第一个参数是标准的 5 字段 Cron 表达式。其余参数是要在指定计划中运行的命令及其参数。

agentapi 工具

边车服务可以使用 agentapi CLI 来以编程方式与 Antigravity 交互。该可执行文件会被自动添加到边车服务的环境变量 PATH 中，直接调用 agentapi 即可。

创建新对话

agentapi new-conversation <prompt>

[!IMPORTANT] 边车服务在创建新对话时必须已设置 projectId。

发送消息

agentapi send-message <conversation_id> <prompt>