ZEM17/dsh-subagent-agy

@dsh-external/dsh-subagent-antigravity

把任务直接委托给本机的 Google Antigravity CLI（agy）——一个独立的
Gemini 编程智能体——从 DeepSeek Harness 里直接使用。不需要任何 API key：
agy 使用你的 Antigravity 登录态（系统凭据 / Google 登录）完成认证。

English version: README.md · 源码: github.com/ZEM17/dsh-subagent-agy

安装

前置要求

1. 安装 agy：irm https://antigravity.google/cli/install.ps1 | iex
（Windows）。插件会自动定位它（PATH → AGY_BIN → %LOCALAPPDATA%\agy\bin
→ ~/.local/bin → ~/.gemini/bin → ~/go/bin）。
2. 登录一次 agy：在终端运行 agy 完成登录。之后如果遇到
"authentication required"，插件会自动弹出交互式登录窗口。
3. DeepSeek Harness：标准 web profile 即可（自带 dsh-subagent、
dsh-subprocess、dsh-tools、dsh-jobs）。

安装插件

从 GitHub 安装（推荐）：

dsh plugin --profile web add github:ZEM17/dsh-subagent-agy

从安装包安装：到
Releases 页面 下载
dsh-external-dsh-subagent-antigravity-0.2.0.tgz，然后：

dsh plugin --profile web add /path/to/dsh-external-dsh-subagent-antigravity-0.1.0.tgz

装完即用，无需重启。任何会话里的模型都能调用 antigravity 系列工具。

使用方法

你只需要提需求，模型会自动调用工具；也可以明确指定：

| 用途 | 工具 | 说明 |
|---|---|---|
| 新任务 | antigravity | 把独立任务委托给 agy（新对话）；返回 task 键 |
| 续聊 | antigravity_followup | 通过 task 键继续之前的 agy 对话——上下文完整延续 |
| 任务列表 | antigravity_tasks | 列出运行中 + 最近完成的任务；task 键在 DSH 重启后仍然有效 |
| 取消任务 | antigravity_cancel | 用 task 键停止一个运行中的任务（终止 agy 进程树） |
| 登录 | antigravity_login | 弹出 agy 交互式登录窗口（认证失败时也会自动弹出） |

示例：

"用 agy 把 D:\projects\my-project 的 README 重写一遍，列出改动。"

"用 antigravity 优化这个项目的页面"

识图

agy 的模型是多模态的——把图片路径写进 prompt，它就能描述/分析图片：

"用 antigravity 识别这张图片：C:\projects\screenshots\ui.png"

"Use agy to describe this image: C:\projects\design\mockup.png"

工作区内的图片直接可用；工作区之外的图片，需要把图片所在目录传给工具的
dirs 参数（或配置 addDirs）。

- 任务目标在会话工作区之外时，需要把目标目录传给工具的 dirs 参数
（你把路径告诉模型，它会自动带上）。
- 长任务：模型会自动用 background: true 后台运行——期间向你实时汇报
进度，完成后给出最终结果。
- 继续之前的任务：告诉模型用上次返回的 task 键续聊。
- 找回任务键：antigravity_tasks 列出运行中和最近完成的任务——任务键
记录在 ~/.dsh/agy-conversations.json，DSH 重启后依然存在，随时可以找回
用于续聊。
- 停止任务：用运行中任务的键调用 antigravity_cancel（后台任务也可用
job_kill）。

配置

所有字段都可选，默认值见下表。通过插件的设置区配置（如
$DSH_HOME/settings.yaml）：

dsh-subagent-antigravity:
model: gemini-3.1-pro-high   # agy models 里的模型；留空 = agy 默认
effort: high                 # low | medium | high
printTimeoutMs: 300000       # 前台任务上限（5 分钟）
backgroundTimeoutMs: 3600000 # 后台任务上限（1 小时）
skipPermissions: true        # 自动批准 agy 的工具调用（无头模式必需）
addDirs: []                  # 加入 agy 工作区的绝对路径（--add-dir）
proxy: ""                    # 代理 URL；回退到 AGY_PROXY 环境变量，再回退 ~/.dsh/agy-proxy.txt

| 字段 | 默认值 | 含义 |
|---|---|---|
| providerName | antigravity | ctx.subagents 注册名 |
| toolName | antigravity | 新任务工具名 |
| followupToolName | antigravity_followup | 续聊工具名 |
| loginToolName | antigravity_login | 登录窗口工具名 |
| tasksToolName | antigravity_tasks | 任务列表工具名 |
| cancelToolName | antigravity_cancel | 取消任务工具名 |
| command | agy | 可执行文件（PATH 名或绝对路径） |
| model | '' | --model （见 agy models）；留空 = agy 默认 |
| effort | '' | --effort low\|medium\|high；留空 = 不传 |
| agent | '' | --agent ；留空 = 不传 |
| printTimeoutMs | 300000 | 前台任务上限（--print-timeout） |
| backgroundTimeoutMs | 3600000 | 后台任务上限（1 小时） |
| watchdogMarginMs | 60000 | agy 卡死时、超时上限之外强制终止的余量 |
| skipPermissions | true | --dangerously-skip-permissions（自动批准 agy 工具调用） |
| sandbox | false | --sandbox（agy 终端沙箱限制） |
| avoidBrowser | true | 在 prompt 中追加"不要用浏览器工具"说明（部分机器上无头浏览器会卡死） |
| avoidLargeReads | true | 在 prompt 中追加"超过 1 MB 的文件用 grep/sed 读取"说明（agy 读取工具有 4 MB 上限） |
| outputFormat | json | 输出格式（json 或 text）；后台模式自动优先 stream-json |
| extraArgs | [] | 追加在生成参数之后的原始 argv |
| cwd | '' | 工作目录覆盖；留空 = 会话工作区 |
| addDirs | [] | 加入 agy 工作区的绝对路径（--add-dir）——目标在会话工作区之外时必需 |
| env | {} | 环境变量覆盖（在 Harness 凭据清理之后合并） |
| proxy | '' | 代理 URL；回退 AGY_PROXY，再回退 ~/.dsh/agy-proxy.txt（每次调用重读） |
| registryPath | '' | 续聊注册表文件；留空 = ~/.dsh/agy-conversations.json |
| disposeGraceMs | 5000 | 进程树终止宽限（SIGTERM → SIGKILL） |
| autoLoginWindow | true | 认证失败时自动弹出交互式登录窗口 |
| loginWindowMinimized | true | 登录窗口最小化启动（只在任务栏显示图标） |

工作原理（简述）

每次任务都会在会话工作区里拉起一个全新的 agy -p  进程，返回最终
回答。运行使用 --output-format json，其回复携带 agy 的
conversation_id；插件把它记入持久化注册表（~/.dsh/agy-conversations.json），
antigravity_followup 通过 --conversation  恢复同一对话。后台运行
使用 stream-json 提供实时进度，并接入 DSH 的任务系统（job_output /
job_kill）。本地看门狗会终止卡死的运行——任何情况下都不会无限等待。

antigravity_tasks 展示持久注册表（重启安全）和实时运行中的任务，
antigravity_cancel 可以停止某个运行中的任务。注册表自带自愈：损坏的
文件会先备份一次（.corrupt）再重置，绝不会被静默覆盖；所有注册表
写入都是串行化的，并发运行不会互相丢失记录。

故障排查

| 现象 | 解决办法 |
|---|---|
| authentication required | 在自动弹出的登录窗口里完成登录（或调用 antigravity_login），然后重试 |
| User location is not supported | 配置代理（proxy 或 ~/.dsh/agy-proxy.txt） |
| timeout waiting for response | 调大 printTimeoutMs / backgroundTimeoutMs，或改用 background: true |
| agy exited 0 but produced no stdout | 已知的 agy 非 TTY 输出丢失 bug；默认的 --output-format json 可规避——仍出现就升级 agy |
| cannot resolve "agy" | 设置 AGY_BIN 指向 agy 可执行文件 |
| 任务卡在浏览器工具上 | avoidBrowser（默认开启）已阻止；确实需要浏览器预览时才设 false |
| file size (…) exceeds limit | agy 读取工具上限 4 MB；avoidLargeReads（默认开启）已让 agy 改用 grep/sed——或瘦身该文件 |
| 注册表损坏 | 插件会把损坏的文件备份一次到 .corrupt 再重置注册表——历史记录绝不会被静默覆盖 |

开发

bash scripts/build.sh            # 从 DSH 运行时 junction 链接 @deepseek-ai 依赖，然后 tsc 编译 src/ → lib/
npm run selftest                 # 离线自检：agy 存在性、参数探测、注册表往返
npm run selftest:e2e             # + 真实 PONG 双轮对话（需要已登录 agy）

本地 DSH 开发流程（超级模组注入器）：dev_build_plugin（构建+打包）→
dev_inject_plugin（免重启运行时注入）；日常迭代用 dev_build_plugin →
dev_reload_package。