zhangzhangco/dsh-llm-antigravity

dsh-llm-antigravity

License: MIT

DeepSeek Harness 的 Antigravity 路由：它注册一个 LLM 提供方
（默认名为 antigravity-local），其请求会发送到本机上已安装并已登录的
Antigravity CLI（agy）。

此插件不属于已发布的 @deepseek-ai/ 发行版。它位于 web profile 中，
并通过该 profile 的 patch 层挂载，因此 DSH 安装本身不受影响。它是
dsh-llm-codex 的同类插件，
遵循相同的形态：一个 LlmAdapter、一条路由，并自带 bundle patch 一同发布。

快速开始——一条命令，无需编辑 patch 文件：

dsh plugin --profile web add git+ssh://git@github.com/zhangzhangco/dsh-llm-antigravity.git

该包声明了 dsh.bundle.patch，因此 dsh plugin 会将其追加到该 profile 的
dsh.profile.bundles 中，而它的 cordis.patch.yml 会自行挂载
llm-antigravity 行。重启该 profile 后，该路由就会出现在模型选择器中。其他安装形式
（tarball、链接文件夹）见与另一台机器共享。

此包有意不发布到 npm，并保留
private: true。npm 上的名称 dsh-llm-antigravity 属于另一位作者的不相关
实现；该字段是一种防护，防止覆盖发布到它上面。GitHub 是分发渠道——见
为什么用 GitHub 而不是 npm。

全新安装会使用 schema 默认值，这意味着仅文本
（textOnly: true）且审批开启（skipPermissions: false）。切换
其中任一项都是每台机器的决定，在你自己的 patch 文件中进行，而不是在此
包中——见配置。

它是什么（以及不是什么）

agy 是一个完整的 agent，拥有自己的工具、终端沙箱和审批
流程。因此，此适配器将其暴露为一条文本生成路由：

- 它转发对话（系统提示、历史记录、工具调用和工具
结果渲染为文本），并返回模型的回答。
- Antigravity 自身的工具使用不会被报告为 harness 工具调用，DSH
工具调用也不会由 Antigravity 执行。此路由上的 DSH 会话
保留自己的工具；Antigravity 根据提供给它的文本作答。
- 由于 Antigravity 拥有工具，它会在任务型
提示上尝试使用它们。见工具处理，
这是关于此路由最需要理解的一点。

如果你希望由 Antigravity 驱动 DSH 工具，或者希望将
Antigravity 的工具暴露为 DSH 工具，请改用 MCP 路径。

认证

该路由使用本机上 agy CLI 的现有登录状态。不需要 API
密钥，也不会从 ~/.gemini 中复制任何内容。如果该 CLI 尚未登录，请先以交互方式运行一次 agy；无头运行会复用该会话。

有两个主机事实很重要：
- 凭据存放在 macOS 钥匙串中。一个无法读取钥匙串的无头 agy 会报告 You are not logged into Antigravity，然后报告 authentication failed or timed out，这看起来像是插件缺陷，但并非如此。
- agy 通过 oauth2.googleapis.com 刷新其令牌。如果该请求无法离开本机，每次调用都会以相同方式失败。参见
网络与代理。

模型目录

agy models 会询问后端，并每行打印一对 \t（进度旋转指示器输出到 stderr）。适配器运行该命令，缓存解析后的列表，并将其公布：

gemini-3.8-flash-high	Gemini 3.8 Flash (High)
gemini-3.8-flash-medium	Gemini 3.8 Flash (Medium)
gemini-3.7-flash-high	Gemini 3.7 Flash (High)
gemini-3.1-pro-high	Gemini 3.1 Pro (High)
claude-sonnet-4-6	Claude Sonnet 4.6 (Thinking)
claude-opus-4-6-thinking	Claude Opus 4.6 (Thinking)
gpt-oss-120b-medium	GPT-OSS 120B (Medium)

说明：

- 发现过程需要一次网络往返（大约六到十秒）。结果会缓存在 ~/.cache/dsh-llm-antigravity/models.json 下，有效期为 6 小时
（modelsCacheTtlMs）。刷新失败会保留之前的列表，因此无法访问的后端不会清空选择器。
- agy models 不报告上下文窗口。容量来自显式的
contextWindows 条目，然后是系列提示（Gemini 1M、Claude 200k、
GPT-OSS 128k），最后是 defaultContextWindow。不会因为猜测错误而拒绝任何内容；只影响 token 估算。
- models 添加显式 id，而 discover: false 使插件完全离线。

配置

由包自身挂载。此行随
cordis.patch.yml 一起发布，包一经安装，dsh plugin 就会将其作为 bundle 层组合：

- insert:
- id: llm-antigravity
name: dsh-llm-antigravity

然后，以下每个字段都会从 config.js 中的 schema 获取其默认值。要在给定机器上更改某个字段，请向您自己的
~/.dsh/profiles//cordis.patch.yml 添加一个 id 定向补丁：

- id: llm-antigravity
config:
textOnly: false
skipPermissions: true

id 定向补丁会替换整个 config 值；schema 会为您省略的每个键填充默认值，因此部分覆盖就足够了。请不要为 llm-antigravity 编写第二个 insert 行——参见
从 0.2.x 升级。

| 字段 | 默认值 | 含义 |
|---|---|---|
| provider | antigravity-local | 向模型选择器显示的路由名称 |
| command | 自动发现 | 要运行的 agy；为空时自动发现（$AGY_COMMAND、PATH、已知安装位置） |
| args | [] | 在提示标志之前追加的额外 argv |
| model | 空 | 固定一个模型；为空时依次遵循目录、models，然后是 CLI 默认值 |
| effort | 空 | 默认推理级别，low/medium/high |
| agent | 空 | Antigravity agent；当 textOnly 开启时，为空会选择内置的无工具 agent |
| textOnly | true | 选择一个无工具的 agent，使回答是文本而非工具调用 |
| geminiConfigDir | 空 | Antigravity 配置根目录；为空时使用 $GEMINI_CONFIG_DIR 或 ~/.gemini/config |
| provisionAgent | true | 当内置的无工具 agent 文件缺失时创建它 |
| proxy | 空 | 子进程的代理，导出为 HTTP_PROXY/HTTPS_PROXY |
| noProxy | localhost,127.0.0.1,::1 | 绕过 proxy 的主机 |
| cwd | 空 | CLI 工作根目录；为空时使用会话工作区 |
| addDirs | [] | 额外的工作区根目录，每个对应一个 --add-dir |
| sandbox | false | 启用 Antigravity 自带的终端沙箱（--sandbox） |
| skipPermissions | false | 自动批准每个 Antigravity 工具请求（--dangerously-skip-permissions） |
| disableSlashCommands | true | 在打印模式下禁用斜杠命令和技能展开 |
| mode | 空 | accept-edits 或 plan；为空时使用 CLI 默认值 |
| timeoutMs | 600000 | 单次 agy 调用的挂钟时间预算 |
| printTimeout | 空 | --print-timeout（Go 时长，例如 8m）；为空时推导出一个略低于 timeoutMs 的值 |
| modelsCachePath | 空 | 目录缓存路径；为空时使用 ~/.cache/dsh-llm-antigravity/models.json |
| modelsCacheTtlMs | 21600000 | 目录新鲜度窗口（6 小时） |
| discover | true | 运行 agy models 以发现模型 |
| models | [] | 要额外公布的 id，列在最前面 |
| contextWindows | {} | 按精确模型 id 键控的每模型容量覆盖 |
| defaultContextWindow | 200000 | 当没有提示或覆盖适用时的容量回退值 |

工具处理：为什么 textOnly 很重要（默认开启）

正是这个失败塑造了这个插件，所以值得直白地说明。

agy 会自行决定一个提示是否需要工具。问它一些任务型的问题——“检查这个目录是否可写”*——它就会调用自己的 run_command。在打印模式下，没有人来回答批准提示，因此该调用会被自动拒绝，agent 停止，该轮以空响应结束。CLI 会如实报告这一点（denied_actions:
[{"action":"command","display_name":"RunCommand"}]），但测试框架只看到一个没有产生任何文本的模型。

使用 textOnly: true（默认值）时，适配器会配置一个小型自定义 agent，并通过 --agent 选择它：

~/.gemini/config/agents/dsh-text/agent.md

该 agent 被指示仅根据对话作答，绝不使用工具，这使该路由变成测试框架所期望的形式。该文件仅在缺失时创建，因此你自己编写的 agent 绝不会被覆盖；设置 geminiConfigDir 可将其重新定位，或设置 provisionAgent: false 自行管理该文件。

如果 Antigravity 仍然因工具调用被拒绝而结束一轮，适配器会抛出一个可操作的错误，指明该工具和两种修复方法，而不是一个简单的“无助手消息”：

Antigravity tried to use its own tools (RunCommand), the print-mode approval was
自动拒绝，并且没有产生任何回答文本。保持 textOnly: true，这样模型会在没有工具的情况下回答；或者设置 skipPermissions: true，让它能在 harness 沙箱之外行动。

只有在确实希望 Antigravity 在机器上执行操作时，才设置 textOnly: false 加 skipPermissions: true——并且要接受它的工具随后会在 harness 沙箱之外运行，前面没有 DSH 审批。

工具模式实际会做什么

在一次使用 textOnly: false 和 skipPermissions: true 的真实运行中测得：

- agy 的 init 事件报告 57 个工具 和 permission_mode:
always-proceed，因此没有任何操作被拒绝，也不会返回 denied_actions；
- run_command 在配置的 cwd 中执行（当 cwd 为空时则在会话工作区中执行）——pwd 会返回该目录；
- 生成文件的工具可能会改为写入 Antigravity 自己的暂存区
~/.gemini/antigravity-cli/scratch/，因此模型报告为“已创建”的产物可能落在你预期的工作区之外。使用 addDirs
（agy --add-dir）将另一个根目录带入会话工作区，并检查报告的路径，而不是假定为 cwd；
- harness 仍然只接收文本：Antigravity 的工具流量永远不会变成 DSH 工具调用，因此 DSH 记录中不会出现任何工具调用，也不会有任何 DSH 工具执行。

因为最后一点出乎人们的意料，所以值得把这两个工具层区分开：textOnly 控制的是 Antigravity 的工具，而 harness 自己的工具（bash、read、write、web）在这条路径上无论 textOnly 开启还是关闭都不会参与。

网络与代理

agy 是一个 Go 二进制文件：它遵循 HTTP_PROXY/HTTPS_PROXY/NO_PROXY，并且忽略 macOS 系统代理设置。在只能通过本地代理（Clash、Surge 之类）访问 Google 的主机上，设置：

proxy: http://127.0.0.1:7890

不设置它时的症状是看起来像登录失败：

Error: authentication failed: token exchange failed:
Post "https://oauth2.googleapis.com/token": dial tcp 173.194.43.95:443: i/o timeout

适配器会将其归类为传输失败。将 proxy 留空会原样继承 harness 环境，当机器有直接访问能力时，这正是你想要的。

模型、id 与 effort

Antigravity 将推理级别编码在模型 id 中。因为
--model  --effort  会被直接拒绝——

invalid model selection: --model gemini-3.1-pro-low conflicts with --effort=high

——所以对于任何已经以 -low/-medium/-high 结尾的 id，适配器会省略 --effort，并且如果某个会话选择的级别与 id 所固定的级别不同，会记录一条警告。

流式传输

agy --output-format stream-json 会发出包含三种事件类型的 NDJSON，适配器会将其映射到 harness 的流式词汇表：

| agy 事件 | 适配器块 |
|---|---|
| 带 text_delta 的 step_update | block-start + text-delta（增量） |
| 带 usage 的 step_update/result | usage（缓存读取与输入分开报告） |
| result | finish（stop） |

提示词本身通过 stdin 作为一条 NDJSON user 消息发送
（--input-format stream-json），这样可以让长对话不占用命令行，
也避开 ARG_MAX。

安装 / 更新

dsh plugin --profile web add git+ssh://git@github.com/zhangzhangco/dsh-llm-antigravity.git
dsh plugin --profile web update dsh-llm-antigravity    # 之后更新

该包会自行挂载，所以这就是安装的全部步骤。之后重启 profile：
dsh.profile.bundles 只在启动时重新读取，而 patch 文件是实时重载的——
在两者之间，该行还没有目标，路由会从模型选择器中消失，直到重启。

本地开发改为将该目录安装为 link 依赖，这样此处的编辑会在下次加载时生效，
无需重新安装：

dsh plugin --profile web add link:~/.dsh/profiles/web/plugins/dsh-llm-antigravity

然后用 dsh --profile web --dump-config 验证。

为什么用 GitHub 而不是 npm

没有官方的 DSH 插件注册表：插件就是普通的包，通过 GitHub 的 dsh-plugin
主题来发现。本仓库就是以这种方式分发的，而 private: true 保留有一个具体
原因——npm 上的名称 dsh-llm-antigravity 已被一个无关的实现
（zsp1987/dsh-llm-antigravity）占用。以相同名称发布要么会失败，要么会与
用户已有的包冲突。请改为从 git 仓库安装；dsh-plugin 主题才是让它可被发现
的关键。

与另一台机器共享

该插件是 可移植的：它在加载时发现 agy CLI，从该机器的后端读取模型
目录，并从接收方的 DSH 安装中解析 harness 包。这里没有任何内容硬编码本机
的路径。同一个包在任何装有 DSH 且已登录 agy 的机器上都能工作，挂载行也
会随之迁移。

如果你在 0.3.0 之前安装过，请参阅从 0.2.x 升级。

方案 A —— git 仓库

dsh plugin --profile web add git+ssh://git@github.com/zhangzhangco/dsh-llm-antigravity.git

这一条命令即可完成安装和挂载。之后用
dsh plugin --profile web update dsh-llm-antigravity 更新。

方案 B —— tarball

构建该包，将 .tgz 复制过去，然后：

dsh plugin --profile web add /path/to/dsh-llm-antigravity-0.3.0.tgz

pnpm 会将 tarball 复制到其虚拟存储中，所以 .tgz 只在安装时需要。用更新的
tarball 重新运行同一命令即可更新。接收方的 profile 无需任何编辑：挂载行来自
该包。

在此目录中运行 npm pack 会生成该 tarball，即使设置了 private: true 也能
正常工作——该字段只阻止发布到注册表。

方案 C —— 用于开发的文件夹

dsh plugin --profile web add link:~/src/dsh-llm-antigravity
dsh plugin 会将相对的 file:/link: 规格锚定到你的当前目录，而不是配置文件目录，因此请从配置文件目录之外运行它。

从 0.2.x 升级

在 0.3.0 之前，该包未声明 dsh.bundle，因此每次安装都需要手动完成：在 ~/.dsh/profiles//cordis.patch.yml 中添加一行配置文件补丁，内容为 id: llm-antigravity。从 0.3.0 起，bundle 会提供该行，而两个具有相同 id 的条目在启动时是致命的——加载器会抛出 duplicate loader entry id: llm-antigravity，配置文件无法启动。

因此，从 0.2.x 迁移时，请从你自己的补丁文件中删除 llm-antigravity 的 insert 行，并仅保留针对每台机器的覆盖项，作为以 id 为目标的补丁：

- id: llm-antigravity
config:
textOnly: false
skipPermissions: true

以 id 为目标的补丁会替换整个 config 值；config.js 中的 Schemastery schema 会用默认值填充每个省略的键，因此部分覆盖就足够了。无需启动任何东西即可检查组合后的树：

dsh --profile web --dump-config

不会迁移的内容

- 凭据。 Antigravity 的登录是按机器进行的——如果尚未登录，请在该机器上运行 agy。
- ~/.gemini/config/agents/dsh-text/agent.md。 只要 provisionAgent 保持开启，插件会在首次加载时重新创建它。
- 目录缓存。 它会在首次调用 agy models 时重新填充。

验证

- dsh --profile web --dump-config —— 组合后恰好有一个 llm-antigravity 条目，标记为 patched by …/dsh-llm-antigravity/cordis.patch.yml，并且你自己补丁文件中任何以 id 为目标的覆盖项都会应用在其之上。
- 启动该配置文件；启动日志会输出
dsh-llm-antigravity: route antigravity-local ready (transport=cli, command=…, agent=dsh-text, discover=true)。
- 模型选择器会在 Antigravity (local) 下列出 Antigravity 模型。
- 绕过 harness 进行一次调用：

printf '{"event":"user","message":{"content":"Reply with exactly: pong"}}\n' \
| agy --input-format stream-json --output-format stream-json \
--agent dsh-text --model gemini-3.1-pro-low --print=

已知限制

- 没有推理增量。 stream-json 仅发出 step_update.text_delta；思考内容以 thinking_tokens 计数的形式呈现。
- 仅文本。 图像块会被渲染为 [image attachment …] 占位符。
- textOnly 是一条指令，而不是沙箱。 Antigravity 仍会向模型公布其工具列表；内置 agent 被指示不要使用它，而拒绝会作为错误报告，而不是静默的空回合。
- 每次调用都是一次全新的对话。 历史记录会作为提示文本重放；不使用 --continue/--conversation，因此 Antigravity 在回合之间不保留记忆（与使用 --ephemeral 的 dsh-llm-codex 是同样的取舍）。
- 目录需要网络。 离线主机应设置 models 和 discover: false。
- Antigravity 的工具会在 harness 沙箱之外运行，只要
使用了 skipPermissions: true。