边车

Sidecar 是与 Antigravity 一起运行的后台进程。反重力管理边车的生命周期，自动启动它们，并在它们崩溃或出错时重新启动它们。它们对于持久后台脚本、计划的重复任务以及对事件做出反应非常有用。

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

• 全局 sidecar：低于 ~/.gemini/config/sidecars/
• 插件 sidecar：在 ~/.gemini/config/plugins/<pluginName>/sidecars/ 下每个 sidecar 都有自己的目录，目录名称用作 sidecar 的 ID。从插件加载的 Sidecar 的 ID 为 <pluginName>/<sidecarName> 。

sidecar 的目录必须包含 sidecar.json 文件，并且还可能包含其他帮助程序文件，例如要运行的脚本。 sidecar 的目录也充当 sidecar 命令的当前工作目录。目录结构示例

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

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

配置架构 (sidecar.json)

• ** command ** （字符串）：命令/可执行文件（例如 python3 或 /bin/bash ）。与 builtin 互斥。
• ** builtin **（字符串）：要执行的内置命令。目前支持 schedule 。与 command 互斥。
• ** args ** (string[])：可选。传递给命令或内置函数的参数。
• ** restart_policy **（字符串）：可选。重新启动行为。 always 、 on-failure 或 never 之一。默认为 always 。
• ** description **（字符串）：可选。人类可读的 sidecar 功能描述。
• ** env **（对象）：可选。为 sidecar 进程设置的环境变量映射。
• ** display_name **（字符串）：可选。 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."
  ]
}

用户配置（config.json）除非用户在位于 ~/.gemini/config/config.json 的全局配置文件中明确启用，否则 Sidecar 将被禁用。

• ** enabled ** (boolean): 是否启用 sidecar。
• ** projectId **（字符串）：可选。将在其中创建对话的项目 ID agentapi 。例子：

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

运行时数据

sidecar 生成的运行时数据存储在 ~/.gemini/antigravity/sidecar_data/<sidecarId>/ 中。这包括：
** data/ ：任何持久数据的子目录。此路径可通过 ANTIGRAVITY_EXECUTABLE_DATA_DIR 环境变量获得。
** logs/ ：从 stdout 和 stderr 自动生成带时间戳的日志。
* ** events/ ：为 agentapi 调用记录的 JSON 文件。

schedule 内置

schedule 是一个简单的内置调度程序，用于运行重复命令。

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

第一个参数是标准的 5 字段 cron 表达式。其余参数是按指定计划运行的命令和参数。

agentapi

Sidecars 可以使用 agentapi CLI 以编程方式与 Antigravity 进行交互。可执行文件会自动添加到 sidecar 的路径中，并以 agentapi 形式提供。

• agentapi new-conversation <prompt>
  创建对话的 Sidecar 必须设置 projectId 。
• agentapi send-message <conversation_id> <prompt>