# 🛰️ sub-antigravity

让任何 Harness 都能把本机 Antigravity CLI 当作可委派的子代理

继续使用 Codex、DeepSeek Harness、Claude Code、Cursor、Hermes 等熟悉的工作流，把写代码、改文章、翻译和分析任务直接交给当前机器上已经登录的官方 AGY。

[项目简介](#-项目简介) · [核心能力](#-核心能力) · [工作方式](#-工作方式) · [系统架构](#️-系统架构) · [快速开始](#-快速开始) · [MCP 接入](#-mcp-接入)

---

## 📖 项目简介

sub-antigravity 是一个面向 AI Agent 与开发 Harness 的 Antigravity 委派桥接器。它调用用户本机安装并登录的官方 `agy`，通过通用 stdio MCP 和 Direct CLI 提供统一入口，让不同宿主共享同一套 Antigravity 子代理能力。

在 MCP 模式下，宿主负责理解当前对话和决定何时委派，AGY 负责执行具体任务；在 Direct 模式下，任务可以直接进入 AGY，不经过宿主模型。两种入口使用同一个执行器、模型选择策略和会话续接方式。

> 💡 一句话概括：保留你习惯的 Harness，把真正耗时的工作交给 Antigravity。

## ✨ 核心能力

- 🔌 **通用 MCP 委派** —— 为支持 stdio MCP 的 Harness 提供统一的 Antigravity 子代理工具。
- ⚡ **Direct 直通** —— 从终端直接把任务交给 AGY，适合希望尽量减少宿主模型 Token 消耗的场景。
- 🧭 **自动模型选择** —— 每次任务前读取账号当前可用模型，优先选择最新 Gemini Flash 的最高推理档，并自动适应后续版本更新。
- 🧵 **长任务与后台 Job** —— 提交任务后立即获得 Job ID，可继续查询、等待、读取结果或取消；状态和结果会落盘。
- ✂️ **按需交付** —— 文件任务返回简短预览，文章和代码可以返回完整正文；完整结果也保存在本地。
- 📝 **长文本输入** —— UTF-8 标准输入传递任务，支持多行正文、中文和引号；CLI 可读取任务文件。
- 💬 **连续对话** —— 使用 `conversation_id` 继续既有 AGY 会话，不必从头描述上下文。
- 🧩 **委派 Skill** —— 为支持 Skills 的宿主提供任务分流规则，帮助宿主判断哪些工作更适合交给 AGY。

## 🔄 工作方式

| 入口 | 适合场景 | 宿主模型参与 |
| --- | --- | --- |
| MCP | 在原有 Harness 对话中自动决定并委派任务 | 参与任务判断与结果接收 |
| Direct CLI | 从终端直接调用 AGY，或由支持本地命令直通的宿主触发 | 命令直通不参与；模型调用终端仍有调度消耗 |

MCP 使用异步 Job 流程处理长任务：

```text
提交任务 → 返回 job_id → 等待或查询 → 获取紧凑结果
```

Direct CLI 直接等待 AGY 完成并输出结果：

```text
输入任务 → AGY 执行 → 返回结果与 conversation_id
```

## 🏗️ 系统架构

```mermaid
flowchart LR
    U[用户任务] --> H[Codex / DSH / Claude Code / Cursor / Hermes]
    H -->|stdio MCP| M[sub-antigravity MCP]
    U -->|Direct CLI| D[sub-antigravity Direct]
    M --> J[后台 Job]
    D --> R[统一执行器]
    J --> R
    R --> S[动态模型选择]
    S --> A[官方 agy CLI]
    A --> W[目标工作区]
    A --> C[紧凑结果 / 会话续接]
    C --> H
    C --> U
```

## 🧠 模型选择

sub-antigravity 在每次任务开始前读取 `agy models`，按照以下顺序自动选择：

1. 最新版本的 Gemini Flash；
2. 同一版本中可用的最高推理档；
3. 没有可用 Flash 时，选择最新 Gemini Pro 的最高推理档。

任务始终使用 AGY 提供的最高推理强度，并通过 `--effort high` 执行。模型名称不绑定具体版本，因此 AGY 账号出现更新的 Gemini Flash 后无需修改配置。

## 🛠️ 技术栈

| 领域 | 选型 |
| --- | --- |
| 运行时 | Python 3.10+ |
| Agent 执行 | 官方 Antigravity CLI（`agy`） |
| 宿主接入 | Model Context Protocol（stdio） |
| CLI | `sub-antigravity` |
| 任务状态 | 本地 Job 与结果文件 |
| 委派策略 | Agent Skill |

## 🚀 快速开始

### 1. 准备 AGY

确认官方 `agy` 已安装并完成登录：

```powershell
agy
```

### 2. 安装 sub-antigravity

```powershell
uv tool install "git+https://github.com/ZorIgn/sub-antigravity"
sub-antigravity check
```

如果安装器提示命令目录不在 PATH，运行 `uv tool update-shell`，重新打开终端。更新已有安装使用 `uv tool upgrade sub-antigravity`，然后重启宿主的 MCP 进程。

本地开发：

```powershell
git clone https://github.com/ZorIgn/sub-antigravity
cd sub-antigravity
uv sync --extra dev
uv run sub-antigravity check
```

项目会从当前 `PATH` 和 Windows 常见安装位置查找 `agy`。也可以显式指定路径：

```powershell
$env:SUB_ANTIGRAVITY_AGY_PATH = "C:\Users\you\AppData\Local\agy\bin\agy.exe"
```

### 3. 直接委派任务

分析当前项目：

```powershell
sub-antigravity direct --cwd E:\project "分析登录失败的原因并给出结论"
```

让 AGY 直接改稿：

```powershell
sub-antigravity direct --cwd E:\project --edit "把 README.md 改得通俗自然，保留代码和链接，只改这个文件。完成后简短说明。"
```

允许 AGY 修改工作区时，需要显式加入 `--edit`：

```powershell
sub-antigravity direct --cwd E:\project --edit "修复登录失败并运行相关测试"
```

默认自动批准已委派任务的 AGY 工具调用；`--edit` 选择允许修改文件的执行模式。任务应写清允许操作的文件，`cwd` 指定工作目录，不是文件系统沙箱。需要使用 AGY 自身权限配置时，加 `--configured-permissions`。

长任务说明放入 UTF-8 文件，完整回答直接保存为 Markdown：

```powershell
sub-antigravity direct --cwd E:\project --prompt-file task.txt --output answer.md
```

也可以用 `--stdin` 读取 UTF-8 输入。输出保存到文件后，终端只返回路径、模型与会话 ID，避免让宿主重复读入整篇正文。

以 JSON 结果委派任务：

```powershell
sub-antigravity delegate --cwd E:\project "检查当前项目的构建失败原因"
```

继续上一次对话：

```powershell
sub-antigravity continue <conversation-id> --cwd E:\project --edit "继续处理剩余问题"
```

## 🔌 MCP 接入

完成安装后，每个 Harness 直接注册同一个 stdio MCP。通用配置：

```json
{
  "mcpServers": {
    "sub-antigravity": {
      "command": "sub-antigravity-mcp",
      "args": []
    }
  }
}
```

### Codex

```powershell
codex mcp add sub-antigravity -- sub-antigravity-mcp
```

### Claude Code

```powershell
claude mcp add --transport stdio sub-antigravity -- sub-antigravity-mcp
```

### Cursor 与其他 MCP Harness

使用上面的通用 `mcpServers` 配置，并将 transport 设为 `stdio`。

### Hermes

```yaml
mcp_servers:
  sub-antigravity:
    command: sub-antigravity-mcp
    args: []
    enabled: true
    connect_timeout: 120
mcp_discovery_timeout: 45
```

Windows 上如果宿主找不到命令，把 `command` 换成安装器返回的 `sub-antigravity-mcp.exe` 绝对路径。使用代理联网的机器，应在 MCP 的 `env` 中显式传入自己的 `HTTP_PROXY` 和 `HTTPS_PROXY`。

### DeepSeek Harness

```yaml
- id: mcp-sub-antigravity
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: sub-antigravity
    transport: stdio
    command: sub-antigravity-mcp
    args: []
    toolCallTimeoutMs: 60000
```

## 🧰 MCP 工具

| 工具 | 用途 |
| --- | --- |
| `antigravity_delegate` | 提交新任务，或通过 `conversation_id` 继续已有会话；支持 `allow_edits` 与 `dangerously_skip_permissions` |
| `antigravity_job` | 查询、等待、读取结果或取消后台任务 |
| `antigravity_check` | 查看 AGY、可用模型与自动选择结果 |

典型调用流程：

```text
antigravity_delegate
→ job_id
→ antigravity_job(action="wait", wait_seconds=45, detail="compact")
→ 完成后读取 compact 结果
```

`dangerously_skip_permissions` 默认是 `true`，用于执行用户已授权的委派任务。需要修改文件时设置 `allow_edits=true`；要遵守 AGY 自身权限规则时设置 `dangerously_skip_permissions=false`。

`compact` 只裁剪返回宿主的预览，超过 1600 字符会标记 `truncated=true`。要拿回整篇文章，使用 `detail="response"`；或直接使用 `response_path` 对应的完整 Markdown 文件。AGY 的回答不受固定 JSON 内容格式限制。

## 🧩 委派 Skill

[`skills/delegate-to-antigravity`](skills/delegate-to-antigravity/SKILL.md) 描述了适合委派给 AGY 的任务范围、结果接收方式和工作区修改规则。

将该目录安装到 Harness 的 Skills 目录后，宿主可以结合 MCP 自动判断何时调用 Antigravity。MCP 也可以独立使用，不依赖 Skill。

例如：

> 用 Antigravity 把当前目录的 README.md 改得更通俗，保留代码，只改这个文件。你负责委派并把完成结果告诉我。

Skill 会优先使用当前 Harness 的 MCP；工具尚未加载时，使用当前 Harness 的终端直接调用 CLI。接入一个宿主不会自动给其他宿主安装 MCP，需要分别配置。

## 📂 项目结构

```text
src/sub_antigravity/                 CLI、MCP Server、任务与 AGY 执行器
skills/delegate-to-antigravity/      通用委派 Skill
docs/IMPLEMENTATION.md               实现说明
tests/                               核心流程测试
```

## 📚 延伸阅读

- [实现说明](docs/IMPLEMENTATION.md)
- [Antigravity Headless 文档](https://antigravity.google/docs/cli/headless/)

## 🙏 Acknowledgements

项目参考了以下开源实现：

- [F1rstDan/call-agy](https://github.com/F1rstDan/call-agy)
- [rhishi99/agy-headless-bridge](https://github.com/rhishi99/agy-headless-bridge)
- [ZEM17/dsh-subagent-agy](https://github.com/ZEM17/dsh-subagent-agy)

本项目使用 [MIT License](LICENSE)。