dsh-agy-link 0.6.15 → 0.6.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,67 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.6.17 (2026-11-11)
4
+
5
+ ### English
6
+
7
+ - **Feat(auth): reauthenticate an existing pool account in place — `/agy auth <id|alias|email>`, final result via `/agy auth-status`.** (thanks @Ronnoc, #96)
8
+ - When a secondary account's stored credential is missing or invalid, you no longer have to remove and recreate it (losing its configuration and local state): the browser flow writes into a staging slot, verifies the Google identity, and only then **atomically** moves the new token into that account's isolated `.gemini/antigravity-cli` dir (mode 0600).
9
+ - Identity checks before the swap: the account must be isolated (not the system-HOME primary), the verified email must match the account's recorded email when one exists, and no **other** pool account may already own that email. Missing email, missing refresh token or a mismatched/duplicate identity aborts with `identity_unverified` / `identity_mismatch` and leaves the old credential untouched.
10
+ - The flow is stale-safe (a superseded flow never writes), clears `authRequired`, records the address, and refreshes that account's quota. No credential value is ever printed.
11
+
12
+ ### 中文
13
+
14
+ - **新增(auth):原地重登已有账号——`/agy auth <ID|别名|邮箱>`,最终结果用 `/agy auth-status` 查看。**(感谢 @Ronnoc,#96)
15
+ - 副账号凭据缺失/失效时,不必再「删除后重建」(会丢配置与本地状态):浏览器流程先写入 staging 槽位并校验 Google 身份,再把新 token **原子地** rename 到该账号独立的 `.gemini/antigravity-cli`(0600 权限)。
16
+ - 替换前的身份校验:必须是隔离账号(不是 system-HOME 主账号);已记录邮箱的账号要求邮箱一致;同一邮箱不得属于池中**其他**账号。缺邮箱/缺 refresh token/身份不符或重复 → `identity_unverified` / `identity_mismatch`,旧凭据保持不动。
17
+ - 流程具备「旧流程不写盘」的过期保护,成功后清除 `authRequired`、记录邮箱并刷新该账号配额;任何输出都不打印凭据值。
18
+
19
+ **Full Changelog**: https://github.com/amlyczz/dsh-agy-link/compare/v0.6.16...v0.6.17
20
+
21
+ ## 0.6.16 (2026-11-10)
22
+
23
+ ### English
24
+
25
+ - **Feat(image): headless image generation as a CLI (`dsh-agy-image`) that reuses the real `AgyAdapter` — no new HTTP API.**
26
+ - The CLI instantiates the plugin's own `AgyAdapter` with a new `purpose:'image'` route, so account selection, quota cooldown/rotation, proxy, failure classification and the `--effort`-refusal replay are the same code path a normal turn uses. A region/quota refusal rotates the pool and the retry lands on the next account (verified live: the primary was region-refused, a proxied account generated the image).
27
+ - The adapter sends the caller's bridge prompt verbatim (`agyImagePrompt`), is not forced into plan mode (the tool writes an artifact), and hands raw agy events back through `agyOnEvent` / `agyOnAccount` so the service can locate `brain/<conversation_id>/`.
28
+ - The bridge prompt pins `Prompt` / `ImageName` / `AspectRatio` / `ImagePaths` and asks for `IMAGE_PATH=` / `IMAGE_ERROR=`. Success is accepted only after magic-byte sniff (PNG/JPEG/WebP/GIF/BMP), dimension parsing, `imageMaxBytes` and a 3% aspect-ratio check.
29
+ - `--json` exposes `{ok, path, mime, width, height, aspectRatio, bytes, accountId?, conversationId?}` plus stable failure codes. Config: `imageModel` / `imageEffort` / `imageTimeoutMs` / `imageMaxBytes` / `imageOutputDir` / `imageRetries`.
30
+
31
+ - **Docs/UI: one README per language, a single configuration source, and a Settings row for image generation.**
32
+ - `README.md` is now Chinese-only; the duplicated English half moved to `docs/README.en.md` (fully rewritten, including image generation). Stale `docs/README.es.md` / `docs/README.pt-BR.md` were removed, and historical process docs moved under `docs/archive/`.
33
+ - The configuration table is no longer duplicated in the README — `docs/CONFIGURATION.md` is the only copy.
34
+ - Settings → Antigravity now shows an **Image generation** row: model/effort dropdowns (`imageModel` / `imageEffort`) plus a copyable `dsh-agy-image` command. It documents the CLI instead of pretending to run it in-page.
35
+
36
+ - **Fix(translate): the per-reply "translate" button now explains the message you actually clicked — and the translation is faster and much more colloquial.**
37
+ - `translateMessage` resolved the clicked message to its *turn* and then translated that turn's **last** answer. A turn often holds a preamble plus the real answer, so clicking message A could show a translation of message B. It now translates the clicked message by `messageId` (own text, own anchor seq).
38
+ - Dedupe is message-scoped: `findTranslationRecord` accepts a `messageId`, so siblings in one turn can each have their own card and clicking B never returns A's stored translation. Records written before `messageId` existed remain a fallback only while the turn has no message-scoped record at all.
39
+ - Default thinking effort drops from `high` to `medium`: on real agy the same 964-char reply takes **low ≈ 12s / medium ≈ 33s / high ≈ 45s** (≈9s is agy's own startup), and high-effort output also reads like a formal report. Switch to `low` in Settings for ~12s, or `high` when rigour matters.
40
+ - Prompt rewritten around "这一条回复": plain spoken Chinese, no report headings/bullets, no 书面 connectors, terms unpacked — and **keep the real content volume** (the old "挑重点" hint is gone; long sources are told to finish the walk-through instead of compressing).
41
+ - `sessionDigest` is now one pass instead of rescanning the whole log per turn (O(n²) → O(n)); chunked translations join with a blank line instead of a `---` divider.
42
+
43
+ ### 中文
44
+
45
+ - **新增(生图):headless 生图 CLI(`dsh-agy-image`),直接复用真实 `AgyAdapter`——不新增 HTTP API。**
46
+ - CLI 用插件自己的 `AgyAdapter` 新增 `purpose:'image'` 通道:选号、额度冷却/换号、代理、失败分类、`--effort` 被拒重放,全部与真实对话同一套代码。地区/额度拒绝会前移号池指针,重试落到下一个账号(实测:主号被地区拒绝 → 自动落到代理账号成功出图)。
47
+ - Adapter 原样发送调用方的桥接提示词(`agyImagePrompt`),不强制 plan 模式(工具要写 artifact),并通过 `agyOnEvent` / `agyOnAccount` 把 agy 原始事件与账号 HOME 交回服务层,用于定位 `brain/<conversation_id>/`。
48
+ - 提示词固定 `Prompt` / `ImageName` / `AspectRatio` / `ImagePaths`,要求回 `IMAGE_PATH=` / `IMAGE_ERROR=`;成功必须通过魔数识别(PNG/JPEG/WebP/GIF/BMP)、宽高解析、`imageMaxBytes` 与 3% 比例核对。
49
+ - `--json` 返回 `{ok, path, mime, width, height, aspectRatio, bytes, accountId?, conversationId?}`,失败带稳定 `code`。配置:`imageModel` / `imageEffort` / `imageTimeoutMs` / `imageMaxBytes` / `imageOutputDir` / `imageRetries`。
50
+
51
+ - **文档/UI:每种语言只留一份 README,配置只维护一份,设置页新增「生图」一行。**
52
+ - `README.md` 现在只保留中文;重复的英文半边移到 `docs/README.en.md`(完整重写,含生图)。删除过时的 `docs/README.es.md` / `docs/README.pt-BR.md`,历史过程文档移到 `docs/archive/`。
53
+ - README 不再重复配置表 —— `docs/CONFIGURATION.md` 是唯一副本。
54
+ - 设置 → Antigravity 新增「生图」行:模型/思考档下拉框(`imageModel` / `imageEffort`)+ 可复制的 `dsh-agy-image` 命令;只展示 CLI,不假装页面内能直接跑。
55
+
56
+ - **修复(翻译):每条回复的「译成人话」按钮现在翻的就是你点的那一条,并且更快、更口语。**
57
+ - `translateMessage` 原来先把消息映射到所属回合,再翻该回合的**最后一条**答复。一个回合里常常先有一段说明、后面才是真正的答复,所以点 A 可能拿到 B 的译文。现在按 `messageId` 精确翻译被点的那条(用它自己的正文和锚点 seq)。
58
+ - 去重改成消息级:`findTranslationRecord` 接受 `messageId`,同一回合的 A/B 各自可以有卡片,点 B 不会命中 A 的旧译文;没有 `messageId` 的历史记录只在该回合完全没有消息级记录时兜底。
59
+ - 默认思考档从 `high` 降到 `medium`:真实 agy 上同一段 964 字回复实测 **low ≈ 12s / medium ≈ 33s / high ≈ 45s**(其中约 9s 是 agy 启动开销),且 high 的译文更像正式报告。想更快可在设置里切 `low`(≈12s),需要更严谨再切 `high`。
60
+ - 提示词围绕「这一条回复」重写:大白话、短句、不要标题/分点/报告腔、不要「首先 / 其次 / 综上 / 因此」这类书面词、术语先用日常说法解释;同时**保留实际内容量**(删掉了旧的「挑重点」提示,长原文改为要求按顺序讲完,而不是压成结论)。
61
+ - `sessionDigest` 改为单次遍历(原来每个回合都重扫全量事件,O(n²));多块翻译之间改用空行连接,不再插入 `---` 分隔线。
62
+
63
+ **Full Changelog**: https://github.com/amlyczz/dsh-agy-link/compare/v0.6.15...v0.6.16
64
+
3
65
  ## 0.6.15 (2026-11-10)
4
66
 
5
67
  ### English
package/README.md CHANGED
@@ -13,12 +13,8 @@
13
13
  </p>
14
14
 
15
15
  <p align="center">
16
- <b>🌐 Language / 语言:</b>
17
- <a href="#中文">中文</a> ·
18
- <a href="#english">English</a> ·
19
- <a href="./docs/README.pt-BR.md">Português (Brasil)</a> ·
20
- <a href="./docs/README.es.md">Español</a> ·
21
- <a href="./docs/README.en.md">English (standalone)</a> ·
16
+ <b>🌐 语言:</b>
17
+ <a href="./docs/README.en.md">English</a> ·
22
18
  <a href="./docs/CONFIGURATION.md">完整配置文档</a>
23
19
  </p>
24
20
 
@@ -104,6 +100,7 @@
104
100
  | 🖼 **图片多模态** | 支持多模态图片传入,自动落盘本地媒体目录并通过 `--add-dir` 安全授权给 agy 查看 |
105
101
  | 🤝 **`agy_ask` 辅助工具** | 允许任意 DSH 模型把单次任务委托给 Antigravity 模型(AskAntigravity 协作模式) |
106
102
  | 🧠 **思考强度自适应学习** | 模型若拒绝 `--effort`,自动无 effort 原样重放并记录至本地,后续自动收回档位声明,杜绝重复报错 |
103
+ | 🎨 **生图(`generate_image` 桥接)** | `dsh-agy-image` CLI;直接复用真实 `AgyAdapter`(`purpose:'image'`)与账号池,额度/地区失败自动换号;固定 Prompt/ImageName/AspectRatio/ImagePaths 参数,产物按魔数+宽高+比例强校验 |
107
104
  | 🗣 **`/tsl` 大白话翻译** | DSH 原生卡片锚定在回复下方,会话 1:1 独立绑定复用;支持 `/tsl` 命令、自动翻译开关(设置页同一行可选**翻译模型**与**思考档**下拉框)及回复快捷按钮「译成人话」 |
108
105
  | ⌨️ **`/agy` 快捷命令族** | `status` / `pool` / `auth` / `models` / `mode` / `effort` / `workspace` / `goal` / `session` / `enable-account` / `disable-account` / `clear` / `doctor` / `help` |
109
106
 
@@ -141,48 +138,28 @@ dsh plugin --profile web add dsh-agy-link
141
138
 
142
139
  # 3. 登录与添加账号:
143
140
  # 方式 A:点击顶部导航栏的 "AGY (n)" 徽标,点击 "➕ 添加账号",浏览器一键登录;
144
- # 方式 B:输入框执行 /agy auth 为主账号发起登录。
141
+ # 方式 B:输入框执行 /agy auth 为主账号发起登录;执行 /agy pool 查看账号 ID,
142
+ # 再用 /agy auth <账号 ID> 重新登录已有的备用账号(也支持完整别名或邮箱)。
143
+ # 授权后 30 秒内执行 /agy auth-status 查看最终登录结果。
145
144
 
146
145
  # 4. 在 /model 选择器中挑选 Antigravity 模型,立即开启对话!
147
146
  ```
148
147
 
148
+ > 无头运行(`dsh headless`)的权限预设与目录白名单见 [docs/HEADLESS-PERMISSIONS.md](./docs/HEADLESS-PERMISSIONS.md)。
149
+
149
150
  ---
150
151
 
151
152
  ## ⚙️ 配置说明
152
153
 
153
- 插件配置可在 `/plugin`、设置面板或环境变量中灵活调整:
154
-
155
- | 键名 | 环境变量 | 默认值 | 作用说明 |
156
- | --- | --- | --- | --- |
157
- | `enabled` | `DSH_AGY_ENABLED` | `true` | 插件主开关 |
158
- | `agyBin` | `DSH_AGY_BIN` | 自动探测 | 显式指定 `agy` 二进制路径 |
159
- | `permissionMode` | `DSH_AGY_MODE` | `skip` | 权限模式:`skip`(无人值守执行)/ `plan` / `accept-edits`。设置面板已固定为 `skip`;`plan` / `accept-edits` 仍可用配置或 `DSH_AGY_MODE` 覆盖(例如无头运行) |
160
- | `defaultModel` | `DSH_AGY_DEFAULT_MODEL` | `(agy 默认)` | 默认模型 slug |
161
- | `defaultEffort` | `DSH_AGY_DEFAULT_EFFORT` | `high` | 思考预算:`low` / `medium` / `high`(`auto` = 各模型自身默认)。设置面板「默认思考强度」可直接切换;它只是会话**模型下拉框**的初始档位,仍可在该下拉框里按模型覆盖(与 agy 的等级一一对应) |
162
- | `hiddenModels` | `DSH_AGY_HIDDEN_MODELS` | `[]` | 在 `/model` 选择器中隐藏的模型 slug 列表(黑名单语义,新模型默认可见;建议直接在设置面板"模型显示"中点选管理) |
163
- | `timeoutMs` | `DSH_AGY_TIMEOUT_MS` | `600000` | 单轮活跃看门狗超时(毫秒) |
164
- | `longToolIdleMinutes` | `DSH_AGY_LONG_TOOL_IDLE_MINUTES` | `240` | 存在未完成工具步骤(ACTIVE)时的空闲预算(分钟);`0` = 不抬高预算,卡死的工具按 `timeoutMs` 快速失败 |
165
- | `maxTurnMinutes` | `DSH_AGY_MAX_TURN_MINUTES` | `0` | 单轮**墙钟**硬上限(分钟),`0` = 不限。空闲看门狗会被每一行输出重置,因此持续自驱动的会话只能靠它兜底;超限会终止 agy 进程树并返回可续跑错误(issue #92) |
166
- | `contextWindowDefault` | `DSH_AGY_CONTEXT_WINDOW` | `1048576` | 上报给 DSH 的模型上下文窗口(token)。agy 的模型列表不上报窗口,所以统一用该值;若你的模型实际是 256K(如部分 Claude/Gemini 配置),设为 `262144` 即可让「上下文已用 %」正确 |
167
- | `maxTokensDefault` | `DSH_AGY_MAX_TOKENS` | `65536` | 单次输出 token 上限(上报给 DSH) |
168
- | `workspaceRoot` | `DSH_AGY_WORKSPACE_ROOT` | 会话 cwd | agy 工作区根目录(默认跟随当前会话工作区) |
169
- | `proxyUrl` | `DSH_AGY_PROXY_URL` | 空字符串 | 全局代理 URL;若在控制台中单独配置了代理,优先使用账号独立代理 |
170
- | `suppressAgyAutoUpdate` | `DSH_AGY_SUPPRESS_AUTOUPDATE` | Windows `true`,其他平台 `false` | 每次 spawn 前刷新 agy 的更新检查时间戳,阻断 `--bg-updater` 子进程链(Windows 闪窗根因)。关闭后 agy 恢复自动更新检查 |
171
- | `autoWarmup` | `DSH_AGY_AUTO_WARMUP` | `false` | 7 天周配额自动预热(opt-in):周额度到达重置时间或冷启动时发送极小探活请求,提前激活 7 天计时器。开启后每 5 分钟巡检一次;该路径直连 Google 内部端点,请自行评估风控风险 |
172
- | `warmupModels` | `DSH_AGY_WARMUP_MODELS` | `gemini-3.8-flash,claude-sonnet-5-5` | 自动预热使用的模型列表(逗号分隔);空数组表示不自动预热 |
173
- | `autoTranslate` | `DSH_AGY_AUTO_TRANSLATE` | `false` | 每轮对话完成后自动调用 `/tsl` 生成大白话翻译卡片;亦可在会话中通过 `/tsl auto on` 动态开启 |
174
- | `translateModel` | `DSH_AGY_TRANSLATE_MODEL` | `gemini-3.8-flash` | `/tsl` 默认使用的翻译模型,缺失时按目录回退 |
175
- | `translateEffort` | `DSH_AGY_TRANSLATE_EFFORT` | `high` | 翻译模型思考强度档位 |
176
- | `translateTargetLanguage` | `DSH_AGY_TRANSLATE_LANG` | `中文(简体)` | 翻译提示词中指定的目标语言 |
177
- | `translateBindConversation` | — | `true` | 每个 DSH 会话绑定一条独立的 agy 翻译会话,人格仅发送一次,后续轮次仅传请求行与原文 |
178
-
179
- > 💡 完整配置参数清单、高级选项与环境变量映射请参见 [docs/CONFIGURATION.md](./docs/CONFIGURATION.md)。
154
+ 所有配置键、环境变量、默认值与高级选项**只维护一份**:[docs/CONFIGURATION.md](./docs/CONFIGURATION.md)。
155
+
156
+ 常用入口:`/plugin`、设置面板(Antigravity)、`DSH_AGY_*` 环境变量,以及 `~/.dsh/agy-link/runtime-overrides.json`(设置面板的写入位置)。
180
157
 
181
158
  ---
182
159
 
183
160
  ## 🗣 /tsl 大白话翻译
184
161
 
185
- 模型输出往往偏专业、冗长或充满机器腔。`/tsl` 命令调用 Gemini 模型(默认 `gemini-3.8-flash` · `high`)将当前会话的回复重写为通俗、口语化的大白话。
162
+ 模型输出往往偏专业、冗长或充满机器腔。`/tsl` 命令调用 Gemini 模型(默认 `gemini-3.8-flash` · `medium`)将当前会话的回复重写为通俗、口语化的大白话。
186
163
 
187
164
  ```bash
188
165
  /tsl # 翻译上一轮已完成的回复
@@ -200,6 +177,26 @@ dsh plugin --profile web add dsh-agy-link
200
177
  - **共享号池与自愈容错**:翻译调用走插件辅助通道,共享主账号池与冷却机制,账号额度耗尽自动故障转移至下一个可用账号;遇到空返回(`EMPTY_RESPONSE`)自动退避重试。
201
178
  - **严格遵循用户授权**:自动翻译默认关闭(`autoTranslate: false`),可在「设置 → Antigravity」中全局开启,或在会话中通过 `/tsl auto on` 动态开启。同一行右侧的两个下拉框可分别改**翻译模型**(默认自动挑 Gemini Flash)与**翻译思考档**(默认跟随「默认思考强度」),改完即写配置、下一轮翻译生效。
202
179
 
180
+
181
+ ---
182
+
183
+ ## 🎨 生图(`generate_image` 桥接 + `dsh-agy-image`)
184
+
185
+ agy 内置 `generate_image`(文生图 / 改图,产物写入会话 artifacts)。插件把它接成 headless 可用的 CLI,**不新增 HTTP API**:CLI 直接实例化插件真实的 `AgyAdapter`(`purpose:'image'`),所以选号、额度冷却、**额度/地区失败自动换号**、代理、失败分类全部复用主流程那一套,而不是另写一份 spawn / 选号逻辑。
186
+
187
+ ```bash
188
+ # 安装插件后即可用;无需交互式会话
189
+ dsh-agy-image -p "一只戴墨镜的柴犬,扁平插画风" -a 16:9 -o ./dog.jpg
190
+ dsh-agy-image -p "把背景换成夜晚" -i ./day.png -n night_scene --json
191
+ ```
192
+
193
+ - **与主流程共用同一套号池**:每次尝试都走 `AccountPoolManager.selectAccount()`;额度耗尽会冷却当前账号并换下一个;`User location is not supported`(地区/资格)也会前移指针换号重试。实测:主号被地区拒绝后,CLI 自动落到支持地区的备用号并成功出图(`accountId` 会写进 JSON)。
194
+ - **参数固定**:`Prompt`、`ImageName`、`AspectRatio`(`1:1` / `2:3` / `3:2` / `3:4` / `4:3` / `4:5` / `5:4` / `9:16` / `16:9` / `21:9` / `1:8` / `8:1` / `1:4` / `4:1`)、`ImagePaths`(参考图 / 改图源)。
195
+ - **强校验**:产物必须存在、按魔数确认为 PNG/JPEG/WebP/GIF/BMP、能解析出宽高、不超过 `imageMaxBytes`;指定了 `AspectRatio` 时按 3% 容差核对比例。
196
+ - **返回结构**(`--json`):`{ok, path, mime, width, height, aspectRatio, bytes, model, effort, durationMs, attempts, accountId?, conversationId?}`。失败带稳定 `code`:`BAD_PARAMS` / `EMPTY_PROMPT` / `IMAGE_NOT_FOUND` / `IMAGE_INVALID` / `IMAGE_ASPECT_MISMATCH` / `IMAGE_REGION_UNSUPPORTED` / `NO_ACCOUNT` / `TIMEOUT` …
197
+ - **退出码**:`0` 成功 · `2` 参数错误 · `3` 找不到 agy · `4` 生成失败 · `5` 产物校验失败 · `6` 账号/地区不可用。
198
+ - **已知限制**:agy 的图片模型只按比例出图,不接受任意像素尺寸(1:1 实测 1024×1024,16:9 实测 1376×768);部分网络出口地区会被 Google 拒绝(`User location is not supported for the API use.`),此时换号/换代理即可。真实生成通常 20–60 秒。
199
+
203
200
  ---
204
201
 
205
202
  ## 🧩 架构与工作原理
@@ -263,259 +260,3 @@ dsh plugin --profile web add dsh-agy-link
263
260
  ## 许可证
264
261
 
265
262
  MIT License.
266
-
267
- ---
268
-
269
- # English
270
-
271
- Bring **Google Antigravity models into DeepSeek Harness (DSH)** — featuring **Multi-Account Pooling & Automatic Rotation**, **Official Multi-Bucket Quota Tracking (5h Rolling + 7d Weekly + Argon Weekly Pool)**, **Zero-Paste In-GUI OAuth Login**, and **Theme-Adaptive High-Contrast UI**, powered by the official unmodified `agy` CLI.
272
-
273
- <p align="center">
274
- <img src="./docs/assets/console.png" alt="Antigravity Management Console - Multi-Account Pool & Quota Monitor" width="760" />
275
- </p>
276
- <p align="center">
277
- <img src="./docs/assets/model-picker.png" alt="Antigravity Model Lineup in DSH Model Picker" width="280" />
278
- &nbsp;&nbsp;
279
- <img src="./docs/assets/settings.png" alt="Antigravity Settings Panel in DSH" width="540" />
280
- </p>
281
- <p align="center">
282
- <img src="./docs/assets/token-usage.png" alt="Native Context Caching & Token Usage Breakdown" width="340" />
283
- &nbsp;&nbsp;
284
- <img src="./docs/assets/context-metering.png" alt="Accurate 1M Context Window Metering" width="340" />
285
- </p>
286
-
287
- ---
288
-
289
- > 🚨 **【Important: System Proxy / VPN / TUN Mode Required in Restricted Regions】**
290
- >
291
- > Google Antigravity services and Google OAuth require access to Google servers (`oauth2.googleapis.com`, `cloudcode-pa.googleapis.com`, etc.).
292
- >
293
- > 1. **Recommended**: Enable **TUN mode / System Proxy** in your VPN or proxy client (Clash, Surge, Sing-box, etc.) so that all terminal commands, Node.js background processes, and browser calls route through your proxy.
294
- > 2. **Terminal Proxy Export**: If your terminal does not inherit proxy automatically, export the environment variables before starting DSH:
295
- > ```bash
296
- > export HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890 ALL_PROXY=socks5://127.0.0.1:7890
297
- > ```
298
- > 3. **Per-Account Dedicated Proxy**: You can also configure a dedicated proxy URL per account directly in DSH Settings → Antigravity by clicking the "🌐 Proxy" button on the account card (e.g. `http://127.0.0.1:7890`).
299
-
300
- ---
301
-
302
- ## 🌟 Core Feature: Multi-Account Pool & Smart Rotation
303
-
304
- Have multiple Google Antigravity / Gemini accounts? **dsh-agy-link makes multi-account orchestration seamless and automated**:
305
-
306
- - 👥 **Multi-Account Pooling**: Manage unlimited Google accounts (Primary + Secondary pool) with fully isolated HOME sandbox environments and credentials.
307
- - 🔄 **Sequential Drain Failover**: When an account reaches its rate limits (429) or runs out of 5h/weekly quotas, requests **automatically and smoothly fail over to the next available account** without interrupting your conversation!
308
- - 🕰 **Quota-Expiry-First Rotation**: With several accounts available, the scheduler prefers the one whose **reset window expires soonest**, maximizing utilization across the whole pool.
309
- - 🧠 **Jitter-Safe Auth Classification**: A keyring-auth timeout caused by proxy jitter is recognized as a **retryable network error**, not a sign-out — classified from the `keyringAuth` transport evidence in agy's own run log, and sticky "needs re-login" quarantine requires a second confirmation, so healthy accounts are never falsely flagged.
310
- - 📊 **Official Multi-Bucket Quota Tracking**: Direct integration with Antigravity's official `v1internal:retrieveUserQuotaSummary` endpoint, providing real-time visibility for the **5-Hour Rolling Limit**, the **7-Day Weekly Limit**, and the **Gemini 4 Argon weekly pool** (paid Pro/Ultra accounts, billed separately from the plain Gemini pool).
311
- - 🔀 **Manual Switch-Active**: One click on "Set active" pins the scheduler pointer to the account you choose.
312
- - 🔑 **In-GUI Zero-Paste OAuth**: One-click "Add Account" opens your browser and automatically captures OAuth tokens via local loopback — **no copying and pasting of authorization codes required**.
313
- - 🎨 **Theme-Adaptive High-Contrast UI**: Seamlessly adapts to Light and Dark DSH themes with crystal clear typography and crisp contrast.
314
- - 📱 **Mobile Web Responsiveness**: Below 680px width, the console modal adapts to a full-height sheet drawer (`100dvh`) with stacked labels, full-width quota bars, and equal-width button grids, tested on 360×800, 390×844, and 768×1024 viewports.
315
- - 🗣 **DSH-Native Translation Card (`/tsl`)**: Plain-language explanations rendered as a native DSH card (0.5px hairline border, markdown code-block fill, 12px radius, banner header) differentiated only by a monochrome spark and a "Gemini 译文" label; light and dark themes come straight from DSH tokens instead of a brand gradient. Binds 1:1 agy translation conversation per session (`<sessionId>#tsl`).
316
- - 🧠 **Effort Learning Mechanism**: Automatically learns when a model rejects `--effort`, replays the turn without effort, records the slug in `~/.dsh/agy-link/effort-unsupported.json`, and withdraws the level declarations to prevent repeated errors.
317
- - 🌐 **Per-Account Proxy**: Configure dedicated HTTP(S) / SOCKS proxy for each individual account to isolate IP addresses; when unset, the system proxy is auto-detected (macOS `scutil` / Windows registry / Linux gsettings).
318
- - ⚡ **Family-Scoped Cooldowns**: Gemini, Claude, GPT-OSS, and Argon rate limits are calculated independently, preventing one exhausted model from blocking others.
319
-
320
- ---
321
-
322
- ## ✨ Features Overview
323
-
324
- | Feature | Description |
325
- | --- | --- |
326
- | 🎨 **Official Vector Logo** | Clean 36×36 retina vector mark (`assets/icon.svg`) with transparent background; dynamically replaces fallback gear in DSH Settings sidebar (`[role="dialog"] nav`) |
327
- | 🧩 **Unified Settings & Plugin Console** | Embedded Antigravity console directly in DSH Plugins settings; configure account pool, quotas, and proxies in one place while keeping list cards clean |
328
- | 🚀 **Secondary Account Parallel Leases** | Windows credential slot allows concurrent sessions on the same account to share leases without queue starvation; serializes only for cross-account switches |
329
- | ⚡ **Native Context Caching & Token Metering** | Native Google Gemini Prompt Caching (`cache_read_tokens`) forwarding; accurate cache read tracking and real prompt occupancy across 1M context windows |
330
- | 👥 **Multi-Account Pool** | Primary + unlimited spare accounts with automatic Sequential Drain rotation upon rate limits; quota-expiry-first scheduling |
331
- | 🧠 **Jitter-Safe Auth** | Distinguishes network jitter from a real sign-out via keyring transport evidence in agy's run log; sticky quarantine requires confirmation — no false "needs re-login" flags |
332
- | 📊 **Multi-Bucket Quota HUD** | Real-time progress bars for the **5h rolling**, **7d weekly**, and **Argon weekly** (paid Pro/Ultra) pools with exact reset countdowns |
333
- | 🔑 **Zero-Paste Browser Login** | Automatic browser-based Google OAuth login with loopback callback handler |
334
- | 🔀 **Manual Switch-Active** | Pin the scheduler to any account from the console; the header badge always names the server-scheduled account |
335
- | 🎨 **Theme-Adaptive UI** | Dynamic light/dark theme switching, pure SVG vector marks (no emojis), high contrast |
336
- | 📱 **Mobile Web Responsiveness** | Transitions to full-height sheet drawer (`100dvh`) below 680px, stacked labels, and equal-width button grid for touch devices |
337
- | 🌐 **Per-Account Proxy** | Dedicated HTTP(S) proxy per account slot, or auto-detected system proxy |
338
- | 🔌 **Native Model Routing** | Registers `antigravity` provider in DSH; choose Gemini / Claude / GPT-OSS / Argon in `/model` picker under `Antigravity (agy CLI)` |
339
- | 🌊 **Full Streaming Protocol** | Native streaming for text, thinking turn annotations, and tool calls |
340
- | 🃏 **Native Tool UI Cards** | Command runs and inline diffs render as clean, native DSH tool cards; MCP meta-tools unwrap to Terminal/Search cards |
341
- | 🔗 **Session Continuity** | Binds DSH sessions to native agy conversations (`--conversation`) for zero-redundancy context |
342
- | 🎯 **DSH Goal & Plan Integration** | Long-running tasks carry DSH goal / plan context across tool continuations |
343
- | 📊 **Accurate Token Metering** | Input, output, thinking, and cacheRead tokens are fully reported to DSH with 1M context support |
344
- | 🎛 **Top Header Console Badge** | Click the `AGY (n)` badge in the header to instantly open the management console |
345
- | 🖼 **Multimodal Images** | Stages images to local storage and passes safe absolute paths via `--add-dir` |
346
- | 🤝 **`agy_ask` Delegation** | Allows other DSH models to delegate subtasks to Antigravity models |
347
- | 🧠 **Effort Learning Mechanism** | Automatically learns model effort refusals, replays without `--effort`, and hides unsupported options |
348
- | 🗣 **`/tsl` Plain-Language Translation** | Gemini rewrites the agent's final answer in plain language and the card is pinned under that reply (persisted in session, labelled "Gemini translation", original text preserved); `/tsl auto on` translates every new turn; the settings row carries **translation model** and **thinking effort** dropdowns |
349
- | ⌨️ **`/agy` Commands** | Full command suite: `status`, `pool`, `auth`, `models`, `mode`, `effort`, `workspace`, `goal`, `session`, `enable-account`, `disable-account`, `clear`, `doctor`, `help` |
350
-
351
- ---
352
-
353
- ## 📋 Prerequisites
354
-
355
- | Requirement | Details |
356
- | --- | --- |
357
- | **1. System Proxy / VPN** | **【Required in restricted regions】** (TUN mode or `HTTPS_PROXY` environment variable to ensure Google endpoints are reachable) |
358
- | **2. DeepSeek Harness (DSH)** | Your current DSH environment (`dsh --version`) |
359
- | **3. Node.js ≥ 24** | Required runtime (`node --version`) |
360
- | **4. Google Antigravity `agy` CLI** | Installed per [Google's official guide](https://antigravity.google/docs/cli/install). Verified with `agy --version` |
361
-
362
- ---
363
-
364
- ## 🚀 Quick Start
365
-
366
- ```bash
367
- # 0. Ensure System Proxy / TUN mode is active (required for Google connectivity):
368
- export HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890
369
-
370
- # 1. Install plugin:
371
- dsh plugin --profile web add dsh-agy-link
372
-
373
- # Upgrade to latest:
374
- # dsh plugin --profile web add dsh-agy-link@latest --registry https://registry.npmjs.org
375
-
376
- # 2. Start DSH Web GUI, test status:
377
- # /agy status
378
-
379
- # 3. Add accounts:
380
- # Click "AGY (n)" badge in the top header, click "➕ Add Account" and complete browser login.
381
-
382
- # 4. Select an Antigravity model in /model and start chatting!
383
- ```
384
-
385
- ---
386
-
387
- ## ⚙️ Configuration
388
-
389
- | Key | Environment Variable | Default | Description |
390
- | --- | --- | --- | --- |
391
- | `enabled` | `DSH_AGY_ENABLED` | `true` | Master switch |
392
- | `agyBin` | `DSH_AGY_BIN` | auto-detected | Path to `agy` binary |
393
- | `permissionMode` | `DSH_AGY_MODE` | `skip` | `skip` (unattended execution) / `plan` / `accept-edits`. The settings panel no longer switches this; it stays `skip` by default, and `plan` / `accept-edits` remain available through config or `DSH_AGY_MODE` (e.g. headless runs) |
394
- | `defaultModel` | `DSH_AGY_DEFAULT_MODEL` | `(agy default)` | Default model slug |
395
- | `defaultEffort` | `DSH_AGY_DEFAULT_EFFORT` | `high` | Thinking budget: `low` / `medium` / `high` (`auto` = each model keeps its own default). Switchable from the settings panel row **Default thinking effort**; it only seeds the session **model menu** and can still be overridden per model there (levels map 1:1 to agy) |
396
- | `hiddenModels` | `DSH_AGY_HIDDEN_MODELS` | `[]` | Model slugs hidden from the `/model` picker (deny-list, newly discovered models stay visible; manage them via the "Model visibility" row in the settings panel) |
397
- | `timeoutMs` | `DSH_AGY_TIMEOUT_MS` | `600000` | Activity watchdog timeout in milliseconds |
398
- | `longToolIdleMinutes` | `DSH_AGY_LONG_TOOL_IDLE_MINUTES` | `240` | Idle budget while a tool step is ACTIVE (minutes); `0` keeps the normal `timeoutMs` budget so wedged tools fail fast |
399
- | `maxTurnMinutes` | `DSH_AGY_MAX_TURN_MINUTES` | `0` | Hard **wall-clock** cap per turn (minutes); `0` = unlimited. The idle watchdog is re-armed on every output line, so a self-driving session can only be bounded by this; exceeding it kills the agy process tree and returns a resumable error (issue #92) |
400
- | `contextWindowDefault` | `DSH_AGY_CONTEXT_WINDOW` | `1048576` | Model context window (tokens) reported to DSH. agy's model list carries no window, so this single value is used for every model; if yours is really 256K, set `262144` and the "context used %" becomes correct |
401
- | `maxTokensDefault` | `DSH_AGY_MAX_TOKENS` | `65536` | Output token cap reported to DSH |
402
- | `workspaceRoot` | `DSH_AGY_WORKSPACE_ROOT` | session cwd | Working directory root |
403
- | `proxyUrl` | `DSH_AGY_PROXY_URL` | empty string | Global proxy URL; per-account proxies configured in console take precedence |
404
- | `suppressAgyAutoUpdate` | `DSH_AGY_SUPPRESS_AUTOUPDATE` | `true` on Windows, `false` elsewhere | Refreshes agy's update-check timestamp before every spawn so its `--bg-updater` child chain (the Windows console-flash root cause) never starts. `false` restores agy's own auto-update checks |
405
- | `autoWarmup` | `DSH_AGY_AUTO_WARMUP` | `false` | Opt-in 7-day weekly quota warmup: sends a minimal probe when the weekly window has reset or is cold, activating the 7-day timer. Scans every 5 minutes; this path talks directly to Google's internal endpoints, so assess the risk-control tradeoff yourself |
406
- | `warmupModels` | `DSH_AGY_WARMUP_MODELS` | `gemini-3.8-flash,claude-sonnet-5-5` | Model list used for warmup probes (comma-separated); an empty list disables automatic warmup |
407
- | `autoTranslate` | `DSH_AGY_AUTO_TRANSLATE` | `false` | Auto plain-language translation after every completed turn (card under the reply). Per-session override: `/tsl auto on\|off` |
408
- | `translateModel` | `DSH_AGY_TRANSLATE_MODEL` | `gemini-3.8-flash` | Model used by `/tsl` and auto mode; falls back through the live catalog when absent |
409
- | `translateEffort` | `DSH_AGY_TRANSLATE_EFFORT` | `high` | Reasoning effort for effort-capable translate models |
410
- | `translateTargetLanguage` | `DSH_AGY_TRANSLATE_LANG` | `中文(简体)` | Target language wording in the translator prompt |
411
- | `translateBindConversation` | — | `true` | Keep ONE agy conversation per DSH session for translations: the persona is sent once; later translations reuse it and send only the short request line |
412
-
413
- > 💡 For full configuration reference, see [docs/CONFIGURATION.md](./docs/CONFIGURATION.md).
414
-
415
- ---
416
-
417
- ## 🗣 Plain-language translation (`/tsl`)
418
-
419
- Not every model writes plainly. `/tsl` sends the current session's output to a
420
- Gemini model (default `gemini-3.8-flash` · `high`) and gets a "human language"
421
- rewrite back.
422
-
423
- ```
424
- /tsl # translate the last completed turn
425
- /tsl 3 # translate turn 3
426
- /tsl --full # include the turn's intermediate narration
427
- /tsl --text 任意文本… # translate arbitrary text (no card)
428
- /tsl --model claude-sonnet-5-5 --effort medium
429
- /tsl --print # also echo the body in the command result
430
- /tsl auto on|off|status # per-session auto mode
431
- ```
432
-
433
- - The result is stored as a durable `plugin:agy-link/translation` session
434
- record and rendered as a **"Gemini translation" card pinned directly under the
435
- reply it translates** — it survives reloads, reads like any other DSH card (one
436
- tinted spark plus a "Gemini 译文" label are the only Gemini signals), and never
437
- enters the model-visible history.
438
- - Every reply also gets a hover action **"译成人话"** so historical turns can be
439
- translated on demand.
440
- - Binds 1:1 agy translation conversation (`<sessionId>#tsl`): persona sent once, per-turn calls transmit only the request line.
441
- - The translation call rides this plugin's own auxiliary adapter route, so it
442
- uses the same account pool: **when an account is out of quota it is cooled
443
- down and the request retries on the next account automatically** (watch
444
- `/agy pool` for the switch). Empty model responses (`EMPTY_RESPONSE`) retry automatically.
445
- - Translation is strictly opt-in (`autoTranslate: false` by default) because it
446
- spends quota per turn. Toggle it in **Settings → Antigravity**, or per session
447
- with `/tsl auto on`.
448
-
449
- ---
450
-
451
- ## Headless operation
452
-
453
- See [Headless permissions](docs/HEADLESS-PERMISSIONS.md) for a bounded reproduction,
454
- least-privilege read-rule validation, and process-versus-tool acceptance checks.
455
-
456
- The plugin passes the selected permission mode to `agy`; it does not approve,
457
- deny, or bypass permissions itself. In headless/print operation, `agy` can
458
- automatically deny a tool request in `plan` or `accept-edits`. The raw tool
459
- error is retained in `/agy status`; it is not proof of a human denial.
460
-
461
- Do not assume undocumented wildcard semantics for either mode. Test the exact
462
- `agy` version and command set in a scoped workspace. Choose `skip` only when
463
- you explicitly accept unattended tool execution.
464
-
465
- ---
466
-
467
- ## ❓ FAQ & Troubleshooting
468
-
469
- ### Desktop app fails to boot after upgrading to DSH 0.2.2 (`web boot: 1 entry did not activate` / `locale "es" is already registered`)?
470
- **A: That is a 0.4.99-and-earlier compatibility bug, fixed in 0.5.5 (#70 / `31c99c1`); current 0.6.x is unaffected.**
471
- - **Cause**: the 0.4.99 client called `locale.addLanguage({ id: 'es' | 'pt-BR' })` unconditionally. DSH 0.2.2's host locale plugin may have registered those languages first, so the call threw `locale "es" is already registered`; the plugin's client entry failed to activate and took the whole web boot down (the desktop app could not reach the chat UI).
472
- - **Fix**: upgrade `dsh-agy-link` to **≥ 0.5.5** (0.6.x recommended). Registration now inspects the host catalog, tolerates only "already registered / already has locale", and disposing removes only entries the plugin owns; host-registered `es`/`pt-BR` (including `ES`/`pt-br` case variants) coexist fine.
473
- - **Workaround**: if you cannot upgrade yet, disable the plugin to reach the chat UI.
474
-
475
- ### Why does a black command prompt / terminal window briefly flash when starting a conversation on Windows?
476
- **A: This is a cosmetic behavior of the Windows Console subsystem and is completely harmless.**
477
- - **Root Cause**: DSH is an Electron desktop app (GUI process). Before each conversation turn, the plugin verifies/syncs Google credentials via the Windows Credential Manager and launches the `agy.exe` console child process for streaming. On Windows 11, if the system default terminal is set to "Windows Terminal", Windows Terminal intercepts the background console allocation and momentarily flashes an empty window (a known Windows Terminal OpenConsole delegation behavior).
478
- - **Solution**:
479
- 1. Open **Windows Terminal** → **Settings** → **Startup** (or Windows **Settings** → **System** → **For developers**).
480
- 2. Change **Default terminal application** from "Let Windows decide" or "Windows Terminal" to **"Windows Console Host"**.
481
- 3. Click **Save** in the bottom-right corner.
482
- 4. **Completely exit and restart DSH** so the running host process picks up the updated console delegation setting.
483
-
484
- ### agy's own auto-updater also flashes a window (fixed in 0.4.66)
485
- On top of the console-delegation flash above, `agy` itself spawns a
486
- `--bg-updater` → `agy --version` child chain once its last update check is more
487
- than 15 minutes old. **That chain is created inside agy and allocates its own
488
- visible console**, so the parent's `windowsHide` and `AGY_CLI_DISABLE_AUTO_UPDATE=1`
489
- both apply too late — the exact conclusion of the measurements recorded in issue #49.
490
-
491
- Since 0.4.66 the plugin refreshes agy's fast-path timestamp
492
- (`<agy home>/last_check.timestamp`) right before every spawn. agy skips the
493
- check entirely when it is under 15 minutes old and spawns nothing, so the
494
- visible window chain never starts — for turns, boot probes, model-picker
495
- refreshes and login probes alike.
496
-
497
- - **Cost**: the agy home used by this plugin stops auto-checking for updates;
498
- a manual `agy update` still works normally.
499
- - **Switch**: `suppressAgyAutoUpdate` (env `DSH_AGY_SUPPRESS_AUTOUPDATE`).
500
- On by default on Windows, off elsewhere; set `false` to restore agy's own behaviour.
501
- - **Manual workaround on older versions**: make
502
- `%USERPROFILE%\.gemini\antigravity-cli\updater\update.lock` read-only
503
- (`attrib +R ...`). agy then fails to acquire the update lock and skips the
504
- check — at the price of `agy update` reporting `update already in progress`
505
- until you run `attrib -R`.
506
-
507
- ### What happens when a model rejects `--effort` with `--effort is not supported`?
508
- Certain models do not support the `--effort` parameter. The plugin automatically detects this refusal, parses the model slug from the error envelope, and replays the turn once without `--effort` so that execution succeeds seamlessly. It then writes the model slug to `~/.dsh/agy-link/effort-unsupported.json` and withdraws the model's effort level declarations, hiding the option in the UI for subsequent sessions. Learned records can be inspected via `/agy status` (`effortUnsupported`) or `/agy doctor`.
509
-
510
- ### Why are quota bars not updating?
511
- Quotas update via periodic background polling (defaulting to once per hour, tunable via `quotaPollIntervalMs`). For immediate updates, click "Sync" on the console card or run `/agy refresh-quota` in the chat input.
512
-
513
- ---
514
-
515
- ## ⚠️ Disclaimer
516
-
517
- This plugin operates strictly by invoking the official, unmodified `agy` CLI binary installed on your local system. Use of this plugin is subject to Google Antigravity's Terms of Service.
518
-
519
- ## License
520
-
521
- MIT License.