dsh-agy-link 0.5.1 → 0.5.2

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/README.md CHANGED
@@ -1,416 +1,412 @@
1
- # dsh-agy-link
2
-
3
- 把 Google Antigravity 接入 DeepSeek Harness(DSH)。插件驱动官方未修改的 `agy` CLI,提供多账号池自动轮换、官方多 Bucket 配额监控、原生流式与工具卡片,以及 `/tsl` 大白话翻译。
4
-
5
- [![npm](https://img.shields.io/npm/v/dsh-agy-link?color=cb3837&label=npm)](https://www.npmjs.com/package/dsh-agy-link)
6
- [![CI](https://github.com/amlyczz/dsh-agy-link/actions/workflows/ci.yml/badge.svg)](https://github.com/amlyczz/dsh-agy-link/actions/workflows/ci.yml)
7
- [![license](https://img.shields.io/badge/license-MIT-lightgrey)](./LICENSE)
8
-
9
- [中文](#中文) · [English](#english) · [Português (Brasil)](./docs/README.pt-BR.md) · [Español](./docs/README.es.md) · [English (standalone)](./docs/README.en.md)
10
-
11
- ```bash
12
- dsh plugin --profile web add dsh-agy-link
13
- ```
1
+ <h1 align="center">🛰️ dsh-agy-link</h1>
14
2
 
15
3
  <p align="center">
16
- <img src="./docs/assets/console.png" alt="Antigravity 管理控制台:账号池、官方配额进度条与代理状态" width="760">
4
+ <b>DeepSeek Harness × Google Antigravity</b> — 多账号智能池化与官方 agy CLI 驱动桥接 / Multi-Account Pool & Native agy CLI Bridge for DSH
17
5
  </p>
18
6
 
19
7
  <p align="center">
20
- <img src="./docs/assets/model-picker.png" alt="DSH 模型选择器中的 Antigravity 分组,含 Gemini 3.8 Flash 等最新模型" width="300">
21
- &nbsp;&nbsp;
22
- <img src="./docs/assets/settings.png" alt="DSH 设置 → 插件中的 Antigravity 设置:运行方式、号池调度、周额度预热、自动翻译、思考强度与模型显示" width="520">
8
+ <a href="https://www.npmjs.com/package/dsh-agy-link"><img src="https://img.shields.io/npm/v/dsh-agy-link?color=cb3837&label=npm&logo=npm" alt="npm"/></a>
9
+ <a href="https://github.com/amlyczz/dsh-agy-link/actions/workflows/ci.yml"><img src="https://github.com/amlyczz/dsh-agy-link/actions/workflows/ci.yml/badge.svg" alt="CI"/></a>
10
+ <img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="MIT"/>
11
+ <img src="https://img.shields.io/badge/node-%3E%3D24-green" alt="node"/>
12
+ <img src="https://img.shields.io/badge/agy-v0.5.1-purple" alt="agy v0.5.1"/>
23
13
  </p>
24
14
 
25
15
  <p align="center">
26
- <img src="./docs/assets/token-usage.png" alt="原生 token 用量统计:缓存命中率、缓存读取与输出" width="300">
27
- &nbsp;&nbsp;
28
- <img src="./docs/assets/context-metering.png" alt="1M 上下文的实时占用计量" width="300">
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> ·
22
+ <a href="./docs/CONFIGURATION.md">完整配置文档</a>
29
23
  </p>
30
24
 
31
25
  ---
32
26
 
33
27
  # 中文
34
28
 
35
- ## 概述
36
-
37
- DSH 的模型列表里通常只有 DeepSeek。装上这个插件后,`agy` 背后的 Gemini、Claude、GPT-OSS 会以 `antigravity` 提供方的身份出现在 `/model` 里,用你已有的 Google 订阅额度工作。
38
-
39
- 它不是代理转发:插件按轮次启动官方 `agy` 进程,解析 NDJSON 事件流,再映射成 DSH 原生的文本、思考、工具卡片与 token 计量。因此换账号、看配额、断点重试都发生在插件内部,DSH 侧只看到一次正常的模型调用。
29
+ 把 **Google Antigravity 模型接入 DeepSeek Harness(DSH)** —— 支持**多账号智能池化轮换**、**官方多 Bucket 配额监控(5小时滚动 + 7天周额度 + Argon 独立周池)**、**浏览器免粘贴一键登录**与**浅色/深色主题高对比度自适应**,由官方未修改的 `agy` CLI 驱动,完整支持流式输出、思考折叠(thinking)、原生工具卡片与精确 token 用量。
40
30
 
41
- - 手上有多份 Google 账号时,额度用完自动接力,对话不中断。
42
- - 配额来自官方接口,5 小时窗口、每周窗口与付费账号的 Argon 池分开显示。
43
- - 思考过程、终端命令、文件改动按 DSH 原生样式呈现,不是一段灰色文本。
44
- - 模型说人话的能力参差,`/tsl` 可以随时把一条回复重写成大白话。
45
-
46
- ## 核心能力
47
-
48
- ### 多账号池
49
-
50
- - **池化管理**:主账号沿用系统凭据;备用账号各自拥有独立的 HOME 沙箱与 OAuth 凭证,互不覆写。
51
- - **顺序耗尽故障转移**:遇到 429 或额度耗尽,当前账号进入冷却,请求落到池内下一个可用账号,当前回复继续。
52
- - **额度到期优先**:多个账号都可用时,优先用掉最早重置的那一份,把“还能用很久”的额度留到后面,池子整体利用率更高。
53
- - **抖动安全鉴权**:代理抖动引起的 keyring 超时按可重试网络错误处理;判定“需要重新登录”要二次确认,不会因为一次网络抖动把健康账号标死。
54
- - **手动切换**:控制台一键“设为当前使用”,调度指针立即钉到指定账号,顶部徽标同步显示实际调度的账号。
55
- - **独立代理**:每个账号可绑定自己的 HTTP(S) / SOCKS 代理,隔离出口 IP;不配置时自动探测系统代理(macOS `scutil`、Windows 注册表、Linux gsettings)。
56
- - **并发租约**:同一账号的多个会话并行运行共享凭据租约;只有跨账号身份切换才串行交接,避免排队饥饿。
57
- - **按模型族冷却**:Gemini、Claude、GPT-OSS、Argon 的限流独立计算,一个模型族受限不影响其他模型族。
58
-
59
- ### 官方配额监控
60
-
61
- 直接调用 Antigravity 官方的 `v1internal:retrieveUserQuotaSummary`,按账号展示三类额度:
62
-
63
- | 额度 | 说明 |
64
- | --- | --- |
65
- | 5 小时滚动 | 短窗口削峰额度,带重置倒计时 |
66
- | 7 天周额度 | 账号级周上限 |
67
- | Argon 周池 | Pro / Ultra 账号专属的 Gemini 4 Argon 独立周额度,不占用普通 Gemini 池 |
68
-
69
- 每个模型族可展开查看明细,额度耗尽前就能看到,不必等 429 才发现。
31
+ <p align="center">
32
+ <img src="./docs/assets/console.png" alt="Antigravity 管理控制台 - 多账号池化与配额监控" width="760" />
33
+ </p>
34
+ <p align="center">
35
+ <img src="./docs/assets/model-picker.png" alt="DSH 模型选择器中的 Antigravity 模型列表" width="280" />
36
+ &nbsp;&nbsp;
37
+ <img src="./docs/assets/settings.png" alt="DSH 设置 → 插件中的 Antigravity 设置面板" width="540" />
38
+ </p>
39
+ <p align="center">
40
+ <img src="./docs/assets/token-usage.png" alt="原生上下文缓存与 Token 用量统计" width="340" />
41
+ &nbsp;&nbsp;
42
+ <img src="./docs/assets/context-metering.png" alt="1M 物理上下文负载精确计量" width="340" />
43
+ </p>
70
44
 
71
- ### 控制台与设置
45
+ ---
72
46
 
73
- 同一个控制台有两个入口:顶栏的 `AGY (n)` 徽标,以及 DSH「设置 → 插件 → Antigravity」。徽标上的数字是池内账号数,点开就是账号池、额度进度条与代理状态。
47
+ > 🚨 **【国内用户核心前置:必须开启系统代理 / TUN 模式!】**
48
+ >
49
+ > Google Antigravity 服务及 OAuth 登录需要直连 Google 海外官方服务器(`oauth2.googleapis.com`、`cloudcode-pa.googleapis.com` 等)。
50
+ >
51
+ > 1. **推荐方式(最稳妥)**:开启代理工具(Clash / Surge / v2rayA / Sing-box / Loon 等)的 **TUN 虚拟网卡模式(或系统代理全局接管)**,确保终端命令、后台 Node.js 进程及浏览器均能顺畅访问 Google 网络。
52
+ > 2. **终端代理环境变量**:若终端未被代理自动接管,启动 DSH 或运行命令前请在终端中执行:
53
+ > ```bash
54
+ > 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
55
+ > ```
56
+ > *(注:端口 `7890` 请替换为你本地代理软件的实际端口)*
57
+ > 3. **GUI 单账号独立代理**:进入 DSH「设置 → Antigravity」或点击顶部 `AGY` 徽标,点击卡片上的「🌐 代理」按钮,可为特定账号单独配置专属代理 URL(如 `http://127.0.0.1:7890`),实现多账号不同 IP 出口隔离。
74
58
 
75
- - **账号卡片**:别名与邮箱、当前使用标记、启用 / 停用、同步、预热、代理、删除;额度条下方可展开 Claude 与 GPT-OSS 的单模型明细。
76
- - **运行方式**:一行说明权限模式固定为 `skip`(静默执行,agy 内置保护仍然生效);需要换模式时用配置或 `DSH_AGY_MODE`。
77
- - **号池调度**:`顺序耗尽`(用完一个再换下一个)与 `轮询均衡`(把请求摊平)两种策略。
78
- - **7 天周额度自动预热**:开 / 关。开启后周窗口重置或冷启动时自动探活,提前激活 7 天计时器。
79
- - **自动翻译**:开 / 关,默认关闭;打开后每个回合结束自动生成一张 `/tsl` 翻译卡片。
80
- - **默认思考强度**:`auto` / `low` / `medium` / `high`,决定会话模型下拉框的初始档位,仍可按模型覆盖。
81
- - **模型显示**:点选隐藏或恢复模型;隐藏只影响选择器,不影响进行中的会话。
59
+ ---
82
60
 
83
- 模型选择器里 Antigravity 以 `Antigravity (agy CLI)` 分组出现,例如 Gemini 3.8 Flash、Claude Sonnet 4.6 (Thinking)、Claude Opus 4.6 (Thinking)、GPT-OSS 120B (Medium)。
61
+ ## 🌟 核心亮点:多账号池化与智能轮换
84
62
 
85
- ### 与 DSH 原生集成
63
+ 你拥有多个 Google Antigravity / Gemini 账号?**dsh-agy-link 让多账号管理变得极致简单与自动化**:
86
64
 
87
- - **模型路由**:注册 `antigravity` 提供方,Gemini、Claude、GPT-OSS、Argon 全族进入 `/model`(分组与模型名单见上节)。
88
- - **完整流式映射**:文本、思考(thinking turn 注记)与工具活动无损映射到 DSH 原生协议。
89
- - **原生工具卡片**:终端命令渲染为 Terminal 卡片(命令、cwd、退出码、超时),文件改动渲染为 inline diff;Antigravity 通过 MCP 元工具(`call_mcp_tool`)发起的调用也会被拆包成终端 / 搜索 / `<server>: <tool>` 卡片,不再是重复的原始 JSON。
90
- - **图表渲染**:回复中的 mermaid 代码块在流式结束后自动渲染为图,多个图表串行渲染互不踩踏。
91
- - **会话延续**:DSH 会话与 agy 原生会话(`--conversation`)绑定,历史由 agy 持有,每轮只发增量。
92
- - **目标与计划透传**:长任务携带 DSH goal / plan 上下文,工具续跑不丢任务状态。
93
- - **token 计量**:输入、输出、思考、缓存读取(`cache_read_tokens`)完整计入 DSH 用量,适配 1M 上下文。
94
- - **思考强度自适应**:模型拒绝 `--effort` 时,插件从报错里认出模型、原样重放一次(这一次不带 `--effort`),并把该模型记进 `~/.dsh/agy-link/effort-unsupported.json`。档位不兼容最多多花一个进程,不会让整轮对话失败。
95
- - **多模态图片**:图片落盘到本地媒体目录,再以 `--add-dir` 授权给 agy 查看。
96
- - **`agy_ask` 委托**:任意 DSH 模型可以把一次独立任务交给 Antigravity 模型处理。
65
+ - 👥 **多账号池化管理 (Account Pool)**:在 DSH 内添加任意数量的 Google 账号(主账号 + 备用账号群),每个账号拥有独立的 HOME 目录沙箱与凭证隔离。
66
+ - 🔄 **顺序耗尽故障转移 (Sequential Drain)**:当前账号额度用尽(触发 429 限流或 5h / 周额度耗尽)时,系统**自动平滑接力至下一个可用账号**,对话完全不中断!
67
+ - 🕰 **额度到期优先轮换 (Quota-Expiry-First)**:多个账号可用时,优先切换到**重置窗口最早到期**的账号,把"还剩很久才重置"的额度留给后面,整体池化利用率最大化。
68
+ - 🧠 **网络抖动智能甄别 (Jitter-Safe Auth)**:代理抖动导致的 keyring 鉴权超时会被自动识别为**可重试的网络错误**而非"登录失效"——基于 agy 本次运行日志的 `keyringAuth` 传输证据精准分类,且粘性"需重新登录"隔离需二次确认,健康账号绝不会被误标。
69
+ - 📊 **官方多 Bucket 配额监控 (Multi-Bucket Quota)**:直接调用 Antigravity 官方专用的 `v1internal:retrieveUserQuotaSummary` 接口,同时展示 **5小时滚动额度**、**7天周额度**,以及付费 Pro/Ultra 账号专属的 **Gemini 4 Argon 独立周额度池**(不占用普通 Gemini 池)。
70
+ - 🔀 **手动切换当前账号 (Manual Switch-Active)**:控制台卡片一键「设为当前使用」,即刻把调度指针钉到指定账号。
71
+ - 🔑 **GUI 内浏览器免粘贴登录 (In-GUI Zero-Paste OAuth)**:点击「➕ 添加账号」自动调起系统浏览器,本地回环监听自动捕获授权凭证,**全程无需手动复制粘贴授权码**。
72
+ - 🎨 **多主题高对比度自适应 (Light & Dark Themes)**:原生适配 DSH 浅色/深色主题,告别发暗发灰与看不清文字,UI 视觉清晰锐利。
73
+ - 📱 **手机 Web 端响应式自适应 (Mobile Web)**:控制台在屏幕宽度小于 680px 时自动变为全屏抽屉面板(`100dvh`),标签与开关控件折行重排,配额条独占单行,操作按钮等宽网格分布,并在多尺寸设备(360×800、390×844、768×1024)实测无横向溢出。
74
+ - 🗣 **DSH 原生大白话翻译卡片 (`/tsl`)**:卡片沿用 DSH 自己的观感(0.5px 细描边、markdown 代码块底色、12px 圆角、横幅表头),只用一枚单色 Gemini 星标 + 「Gemini 译文」标签标明出处,深浅主题全由 DSH 令牌决定,不再是一块品牌渐变横幅;每个 DSH 会话绑定独立翻译会话(`<sessionId>#tsl`),仅首轮注入人格,后续仅传指令行,共享主号池与故障转移。
75
+ - 🧠 **思考强度自适应学习 (Effort Learning)**:当模型拒绝 `--effort` 参数时,自动无 effort 原样重放确保轮次完成,持久化记录至本地文件并自动收回该机型的档位声明,避免后续重复报错。
76
+ - 🌐 **独立账号网络代理 (Per-Account Proxy)**:支持为每个账号独立绑定 HTTP(S) / SOCKS 代理,避免多账号同 IP 引起风控;未显式配置时自动探测系统代理(macOS `scutil` / Windows 注册表 / Linux gsettings)。
77
+ - ⚡ **分模型族独立冷却 (Family-Scoped Cooldown)**:Gemini、Claude、GPT-OSS 与 Argon 的速率限制独立计算,某个模型族受限不影响其他模型族正常调用。
97
78
 
98
- ### `/tsl` 大白话翻译
79
+ ---
99
80
 
100
- 不是每个模型都愿意说人话。`/tsl` 把当前会话的输出交给 Gemini(默认 `gemini-3.8-flash` · `high`),要一份“像跟同事随口解释”的改写。
81
+ ## ✨ 全功能特性一览
82
+
83
+ | 能力 | 说明 |
84
+ | ---- | ---- |
85
+ | 🎨 **官方专属矢量 Logo** | 36×36 高质感纯矢量微标(`assets/icon.svg`),透明底自适应深浅主题;设置左侧导航菜单(`[role="dialog"] nav`)动态替换系统齿轮,呈现专属品牌标识 |
86
+ | 🧩 **设置与插件面板统一** | 在 DSH「设置 → 插件」详情页直接内嵌 Antigravity 完整控制台,账号池、配额监控与代理配置一站式操作,列表保持轻量整洁 |
87
+ | 🚀 **副账号并发租约** | Windows 凭据槽支持同一副账号多会话共享租约并发运行,消除单账号多任务排队饥饿;仅在跨账号身份切换时串行交接 |
88
+ | ⚡ **原生上下文缓存与真实计量** | 完整映射 Google Gemini 原生上下文缓存协议(`cache_read_tokens`),精准追踪缓存读取与物理上下文占用,深度适配 1M 超长上下文 |
89
+ | 👥 **多账号池化轮换** | 支持主账号 + 多个备用账号;遇到 429 或配额耗尽自动平滑切换,模型族独立冷却,额度到期早的账号优先接班 |
90
+ | 🧠 **抖动安全鉴权 (Jitter-Safe Auth)** | 基于 agy 运行日志的 keyring 传输证据区分"网络抖动"与"真登出",抖动自动按可重试网络错误处理;粘性隔离需二次确认,杜绝误标"需重新登录" |
91
+ | 📊 **官方多 Bucket 配额监控** | 实时拉取官方端点,同时呈现 **5h 滚动额度**、**7d 周额度**与 **Argon 独立周池**(付费 Pro/Ultra)多进度条与倒计时,单模型明细可展开 |
92
+ | 🔑 **浏览器一键登录** | 点击添加账号自动唤起 Google 授权页,本地回环自动捕获,全程无需复制粘贴任何代码 |
93
+ | 🔀 **手动切换当前账号** | 控制台「设为当前使用」按钮即刻钉住调度指针;顶部徽标始终显示服务器实际调度的账号 |
94
+ | 🎨 **多主题高对比 UI** | 浅色、深色主题自适应变色,纯矢量 SVG 图标(无 Emoji),字迹清晰不发暗 |
95
+ | 📱 **手机 Web 端自适应** | 屏幕宽度 < 680px 时控制台自动转为全屏抽屉面板(`100dvh`),标签开关折行重排,操作按钮等宽网格分布,全面适配触屏滚动 |
96
+ | 🌐 **独立账号代理** | 每个账号支持独立配置 HTTP(S) 代理,隔离 IP 出口;亦可自动探测系统代理 |
97
+ | 🔌 **原生模型路由** | 在 DSH 模型配置中注册 `antigravity` 提供方,`/model` 选择器以 `Antigravity (agy CLI)` 分组随心切换 Gemini / Claude / GPT-OSS / Argon |
98
+ | 🌊 **完整流式映射** | 文本、思考过程(thinking turn)与工具活动均无损映射到 DSH 原生流协议 |
99
+ | 🃏 **原生工具卡片** | agy 执行的终端命令(`run_command`)、文件修改(inline diff)均以 DSH 原生卡片渲染;MCP 元工具(`call_mcp_tool`)自动拆包为 Terminal/Search 卡片 |
100
+ | 🔗 **会话上下文保真** | DSH 会话与 agy 原生会话绑定(`--conversation`),由 agy 管理完整历史,每轮仅发送增量 |
101
+ | 🎯 **DSH 目标与计划集成** | 长任务自动携带 DSH goal / plan 上下文,工具续跑不丢任务状态 |
102
+ | 📊 **精确 Token 统计** | 输入 / 输出 / 思考 / 缓存读取 token 完整计入 DSH 用量统计,全面适配 1M 上下文 |
103
+ | 🎛 **顶部控制台徽标** | 顶部栏 `AGY · 别名` / `AGY (n)` 徽标一键弹出控制台,直观查看账号池、配额进度条与代理状态 |
104
+ | 🖼 **图片多模态** | 支持多模态图片传入,自动落盘本地媒体目录并通过 `--add-dir` 安全授权给 agy 查看 |
105
+ | 🤝 **`agy_ask` 辅助工具** | 允许任意 DSH 模型把单次任务委托给 Antigravity 模型(AskAntigravity 协作模式) |
106
+ | 🧠 **思考强度自适应学习** | 模型若拒绝 `--effort`,自动无 effort 原样重放并记录至本地,后续自动收回档位声明,杜绝重复报错 |
107
+ | 🗣 **`/tsl` 大白话翻译** | DSH 原生卡片锚定在回复下方,会话 1:1 独立绑定复用;支持 `/tsl` 命令、自动翻译开关(设置页同一行可选**翻译模型**与**思考档**下拉框)及回复快捷按钮「译成人话」 |
108
+ | ⌨️ **`/agy` 快捷命令族** | `status` / `pool` / `auth` / `models` / `mode` / `effort` / `workspace` / `goal` / `session` / `enable-account` / `disable-account` / `clear` / `doctor` / `help` |
101
109
 
102
- - **三种入口**:`/tsl` 命令、设置面板里的自动翻译开关、以及每条回复下方的“译成人话”按钮。
103
- - **卡片落在回复下方**:结果以 `plugin:agy-link/translation` 记录持久化,渲染成一张带标记的翻译卡片,锚在被翻译的那条回复下面;刷新页面、切会话后仍在,原文可展开对照,且不会进入模型可见的历史。
104
- - **复用账号池**:翻译走插件自己的辅助通道,账号额度耗尽会冷却并自动在下一个账号重试。
105
- - **一个会话一条翻译会话**:人格设定(身份、DSH 会话 id、工作目录、原始日志路径)只发一次,后续只发请求行,省掉每轮重复的指令开销。
106
- - **默认关闭**:自动翻译每轮都要花额度,因此默认 `autoTranslate: false`,需要时在设置面板或 `/tsl auto on` 显式打开。
110
+ ---
107
111
 
108
- ## 快速开始
112
+ ## 📋 前置要求
109
113
 
110
- ### 前置要求
114
+ 在安装本插件前,请确保具备以下环境:
111
115
 
112
- | 前置项 | 说明 |
116
+ | 前置项 | 说明 / 验证方式 |
113
117
  | --- | --- |
114
- | 网络 | 能访问 Google(`oauth2.googleapis.com`、`cloudcode-pa.googleapis.com`)。受限网络请开 TUN / 系统代理 |
115
- | DeepSeek Harness | `dsh --version` |
116
- | Node.js | ≥ 24,`node --version` |
117
- | Google Antigravity CLI | 按[官方文档](https://antigravity.google/docs/cli/install)安装,`agy --version` 能输出版本号 |
118
+ | **1. 系统网络代理** | **【必须开启】**(推荐开启 Clash / Surge / v2rayA / Sing-box 的 TUN 模式或设置 `HTTPS_PROXY` 环境变量,确保可流畅连接 Google 服务) |
119
+ | **2. DeepSeek Harness (DSH)** | 你正在使用的 DSH 客户端;`dsh --version` 可验证 |
120
+ | **3. Node.js ≥ 24** | DSH 依赖环境;`node --version` 验证 |
121
+ | **4. Google Antigravity `agy` CLI** | 按 [Google 官方安装文档](https://antigravity.google/docs/cli/install) 安装(支持 macOS / Linux / Windows)。`agy --version` 能输出版本号即表示安装成功 |
118
122
 
119
- 受限网络下,若终端没有继承代理,启动 DSH 前自行导出:
120
-
121
- ```bash
122
- 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
123
- ```
123
+ > 💡 **提示**:即使你的 agy 尚未登录,也可以直接安装插件!在 DSH 界面顶部点击 `AGY` 徽标或进入「设置 → Antigravity」,点击「➕ 添加账号」即可直接在浏览器中完成登录。
124
124
 
125
- 端口换成你本地代理的实际端口。也可以在控制台给单个账号配专属代理。
125
+ ---
126
126
 
127
- ### 安装与登录
127
+ ## 🚀 快速上手
128
128
 
129
129
  ```bash
130
- # 安装(npm 官方包,无需本地编译)
130
+ # 0. 确保系统代理 / TUN 模式已开启(国内网络必需):
131
+ export HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890
132
+
133
+ # 1. 安装插件(npm 官方包,无需编译构建):
131
134
  dsh plugin --profile web add dsh-agy-link
132
135
 
133
- # 升级
134
- dsh plugin --profile web add dsh-agy-link@latest
136
+ # 升级到最新版:
137
+ # dsh plugin --profile web add dsh-agy-link@latest --registry https://registry.npmjs.org
135
138
 
136
- # 启动 DSH Web,检查状态
139
+ # 2. 启动 DSH Web GUI,在输入框中检查状态:
137
140
  # /agy status
138
- ```
139
141
 
140
- 登录有两种方式:点击顶栏的 `AGY (n)` 徽标 → “添加账号”,浏览器会打开 Google 授权页,本地回环自动收回凭证,不需要复制粘贴授权码;或在输入框执行 `/agy auth` 为主账号发起登录。登录完成后在 `/model` 里选一个 Antigravity 模型即可开始对话。
142
+ # 3. 登录与添加账号:
143
+ # 方式 A:点击顶部导航栏的 "AGY (n)" 徽标,点击 "➕ 添加账号",浏览器一键登录;
144
+ # 方式 B:输入框执行 /agy auth 为主账号发起登录。
141
145
 
142
- 即使 `agy` 尚未登录也可以先装插件,登录入口由插件提供。
146
+ # 4. 在 /model 选择器中挑选 Antigravity 模型,立即开启对话!
147
+ ```
143
148
 
144
- ## 使用与配置
149
+ ---
145
150
 
146
- ### `/agy` 命令
151
+ ## ⚙️ 配置说明
147
152
 
148
- | 命令 | 作用 |
149
- | --- | --- |
150
- | `status` | 二进制、版本、鉴权、权限模式、模型目录、会话绑定 |
151
- | `pool` / `accounts` | 账号池、实时额度百分比、冷却状态 |
152
- | `auth` / `auth-code` | 发起登录 / 用授权码或回调 URL 完成登录 |
153
- | `add-account` / `remove-account` | 新增账号槽位(随后在终端完成登录)/ 删除账号 |
154
- | `enable-account` / `disable-account` | 启用或停用指定账号 |
155
- | `refresh-quota` / `clear-cooldown` | 立即刷新额度 / 清除冷却 |
156
- | `models` | 模型目录 |
157
- | `mode` | 权限模式:`skip` / `plan` / `accept-edits` |
158
- | `effort` | 思考强度:`low` / `medium` / `high` / `default` |
159
- | `dispatch` / `dispatch-retries` / `parallel` / `max-concurrent` | 调度等待上限、重试次数、同账号并行、并发上限 |
160
- | `workspace` | 工作区根目录 |
161
- | `goal` | 查看或控制当前 DSH 目标(`status` / `complete` / `pause` / `resume` / `clear`) |
162
- | `session` | 会话绑定信息 |
163
- | `clear` | 清除当前会话绑定 |
164
- | `doctor` | 生成诊断报告并返回路径(敏感字段自动脱敏) |
165
-
166
- ### 配置
167
-
168
- 配置来源优先级:环境变量 `DSH_AGY_*` > 运行时覆盖 > 插件配置 > 默认值。以下是常用项,完整键名与默认值见[配置参考](./docs/CONFIGURATION.md)。
169
-
170
- | 键 | 环境变量 | 默认值 | 说明 |
153
+ 插件配置可在 `/plugin`、设置面板或环境变量中灵活调整:
154
+
155
+ | 键名 | 环境变量 | 默认值 | 作用说明 |
171
156
  | --- | --- | --- | --- |
172
- | `enabled` | `DSH_AGY_ENABLED` | `true` | 插件总开关 |
173
- | `agyBin` | `DSH_AGY_BIN` | 自动探测 | `agy` 可执行文件路径 |
174
- | `permissionMode` | `DSH_AGY_MODE` | `skip` | `skip`(无人值守执行)/ `plan` / `accept-edits`;设置面板不再提供切换,仍可由配置或环境变量覆盖 |
175
- | `defaultModel` | `DSH_AGY_DEFAULT_MODEL` | agy 默认 | 默认模型 slug |
176
- | `defaultEffort` | `DSH_AGY_DEFAULT_EFFORT` | `high` | 默认思考强度,只决定会话模型菜单的初始档位,模型菜单里仍可逐模型覆盖 |
177
- | `hiddenModels` | `DSH_AGY_HIDDEN_MODELS` | `[]` | 在模型选择器中隐藏的 slug 列表(黑名单,新模型默认可见) |
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 列表(黑名单语义,新模型默认可见;建议直接在设置面板"模型显示"中点选管理) |
178
163
  | `timeoutMs` | `DSH_AGY_TIMEOUT_MS` | `600000` | 单轮活跃看门狗超时(毫秒) |
179
- | `longToolIdleMinutes` | `DSH_AGY_LONG_TOOL_IDLE_MINUTES` | `240` | 存在未完成工具步骤时的空闲预算(分钟);`0` 表示维持 `timeoutMs`,卡死的工具快速失败 |
180
- | `workspaceRoot` | `DSH_AGY_WORKSPACE_ROOT` | 会话 cwd | agy 工作区根目录 |
181
- | `proxyUrl` | `DSH_AGY_PROXY_URL` | 空 | 全局代理;单账号代理在控制台里配置,优先于全局值 |
182
- | `suppressAgyAutoUpdate` | `DSH_AGY_SUPPRESS_AUTOUPDATE` | Windows `true`,其他平台 `false` | 每次 spawn 前刷新 agy 的更新检查时间戳,阻断 `--bg-updater` 子进程链(Windows 闪窗根因) |
183
- | `autoWarmup` | `DSH_AGY_AUTO_WARMUP` | `false` | 周额度自动预热(opt-in):周窗口重置或冷启动时发一次极小探活请求,提前激活 7 天计时器;每 5 分钟巡检一次。该路径直连 Google 内部端点,请自行评估风控 |
184
- | `warmupModels` | `DSH_AGY_WARMUP_MODELS` | `gemini-3.8-flash,claude-sonnet-4-6` | 预热使用的模型列表;空表示不预热 |
185
- | `autoTranslate` | `DSH_AGY_AUTO_TRANSLATE` | `false` | 每个新回合结束后自动翻译,也可用 `/tsl auto on` 按会话覆盖 |
186
- | `translateModel` | `DSH_AGY_TRANSLATE_MODEL` | `gemini-3.8-flash` | `/tsl` 与自动翻译使用的模型;目录缺失时按目录回退 |
187
- | `translateEffort` | `DSH_AGY_TRANSLATE_EFFORT` | `high` | 翻译模型的思考强度 |
188
- | `translateTargetLanguage` | `DSH_AGY_TRANSLATE_LANG` | `中文(简体)` | 翻译提示词里的目标语言 |
189
- | `translateBindConversation` | — | `true` | 每个 DSH 会话复用一条 agy 翻译会话:人格只发一次,后续只发请求行 |
190
- | `askTool` | — | `false` | 开放 `agy_ask` 委托工具 |
191
- | `mcpBridge` | `DSH_AGY_MCP_BRIDGE` | `false` | 把 DSH 侧的 MCP 配置桥接给 agy |
192
-
193
- ### `/tsl` 用法
164
+ | `longToolIdleMinutes` | `DSH_AGY_LONG_TOOL_IDLE_MINUTES` | `240` | 存在未完成工具步骤(ACTIVE)时的空闲预算(分钟);`0` = 不抬高预算,卡死的工具按 `timeoutMs` 快速失败 |
165
+ | `workspaceRoot` | `DSH_AGY_WORKSPACE_ROOT` | 会话 cwd | agy 工作区根目录(默认跟随当前会话工作区) |
166
+ | `proxyUrl` | `DSH_AGY_PROXY_URL` | 空字符串 | 全局代理 URL;若在控制台中单独配置了代理,优先使用账号独立代理 |
167
+ | `suppressAgyAutoUpdate` | `DSH_AGY_SUPPRESS_AUTOUPDATE` | Windows `true`,其他平台 `false` | 每次 spawn 前刷新 agy 的更新检查时间戳,阻断 `--bg-updater` 子进程链(Windows 闪窗根因)。关闭后 agy 恢复自动更新检查 |
168
+ | `autoWarmup` | `DSH_AGY_AUTO_WARMUP` | `false` | 7 天周配额自动预热(opt-in):周额度到达重置时间或冷启动时发送极小探活请求,提前激活 7 天计时器。开启后每 5 分钟巡检一次;该路径直连 Google 内部端点,请自行评估风控风险 |
169
+ | `warmupModels` | `DSH_AGY_WARMUP_MODELS` | `gemini-3.8-flash,claude-sonnet-4-6` | 自动预热使用的模型列表(逗号分隔);空数组表示不自动预热 |
170
+ | `autoTranslate` | `DSH_AGY_AUTO_TRANSLATE` | `false` | 每轮对话完成后自动调用 `/tsl` 生成大白话翻译卡片;亦可在会话中通过 `/tsl auto on` 动态开启 |
171
+ | `translateModel` | `DSH_AGY_TRANSLATE_MODEL` | `gemini-3.8-flash` | `/tsl` 默认使用的翻译模型,缺失时按目录回退 |
172
+ | `translateEffort` | `DSH_AGY_TRANSLATE_EFFORT` | `high` | 翻译模型思考强度档位 |
173
+ | `translateTargetLanguage` | `DSH_AGY_TRANSLATE_LANG` | `中文(简体)` | 翻译提示词中指定的目标语言 |
174
+ | `translateBindConversation` | — | `true` | 每个 DSH 会话绑定一条独立的 agy 翻译会话,人格仅发送一次,后续轮次仅传请求行与原文 |
175
+
176
+ > 💡 完整配置参数清单、高级选项与环境变量映射请参见 [docs/CONFIGURATION.md](./docs/CONFIGURATION.md)。
194
177
 
195
- ```
196
- /tsl # 翻译上一条已完成回复
197
- /tsl 3 # 翻译第 3 个回合
198
- /tsl --full # 连同该回合的中间叙述一起翻译
199
- /tsl --text 任意文本… # 翻译任意文本(不生成卡片)
200
- /tsl --model claude-sonnet-5-5 --effort medium
201
- /tsl --print # 同时在命令结果里回显正文
202
- /tsl auto on|off|status # 按会话开关自动翻译
203
- ```
178
+ ---
204
179
 
205
- ## 工作原理
180
+ ## 🗣 /tsl 大白话翻译
206
181
 
207
- 1. **按轮次驱动进程**:每轮对话启动一次 `agy -p --output-format stream-json`,逐条解析 NDJSON 事件。
208
- 2. **账号沙箱**:主账号沿用系统 Keychain / HOME;备用账号在插件私有目录下建立独立 HOME 并写入标准 OAuth 凭证。Windows 上 agy 的凭据实际位于机器级 Credential Manager(`gemini:antigravity`),插件以“身份级引用计数租约”接管该槽位:同一授权的多个会话可并行,只有身份切换串行,并由最后一个持有者还原主账号凭据。
209
- 3. **后台配额轮询**:定时静默调用官方配额接口,维护每个账号的三类额度水位与重置时间。
210
- 4. **失败分类**:错误按 AUTH / NETWORK / RATE_LIMIT / ELIGIBILITY / TIMEOUT 等分类;网络抖动借 agy 运行日志中的 `keyringAuth` 传输证据甄别为可重试故障。
211
- 5. **辅助通道**:`/tsl`、会话标题、目标推导等辅助调用走独立通道(`purpose:'translation'` 等),共享账号池与冷却逻辑,但不进入会话绑定、不暴露工具、不占用并发名额。
182
+ 模型输出往往偏专业、冗长或充满机器腔。`/tsl` 命令调用 Gemini 模型(默认 `gemini-3.8-flash` · `high`)将当前会话的回复重写为通俗、口语化的大白话。
212
183
 
213
- ## 常见问题
184
+ ```bash
185
+ /tsl # 翻译上一轮已完成的回复
186
+ /tsl 3 # 翻译指定第 3 轮回复
187
+ /tsl --full # 连同中间工具调用的叙述一并翻译
188
+ /tsl --text 任意文本… # 纯文本翻译模式(在终端直接输出,不生成卡片)
189
+ /tsl --model claude-sonnet-4-6 --effort medium # 临时指定翻译模型与思考强度
190
+ /tsl --print # 在命令执行输出中同步回显译文
191
+ /tsl auto on|off|status # 针对当前会话开启、关闭或查看自动翻译状态
192
+ ```
214
193
 
215
- **Windows 下开始对话时会闪一下黑色命令行窗口。**
216
- DSH 是 Electron 桌面应用,每轮对话前插件要同步 Windows 凭据管理器里的 OAuth Token,并启动 `agy.exe` 控制台子进程。Windows 11 若把默认终端设为“Windows 终端”,它会在分配后台控制台时短暂闪窗。把 Windows 终端的默认终端应用改为“Windows 控制台主机”,并完全退出重启 DSH 即可。
194
+ - **DSH 原生翻译卡片**:翻译结果持久化存储于 `plugin:agy-link/translation` 会话记录中,渲染为锚定在被翻译回复正下方的原生卡片(只靠一枚单色星标 + 「Gemini 译文」标签标明出处);刷新页面或切换会话后不丢失,原文支持一键展开折叠,且卡片内容不进入模型可见历史。
195
+ - **快捷动作**:每条回复下方均提供「译成人话」快捷操作按钮,历史任一轮次均可按需一键翻译。
196
+ - **会话 1:1 独立绑定 (`translateBindConversation`)**:每个 DSH 会话对应一条独立的 agy 翻译会话(`<sessionKey>#tsl`)。首次调用注入翻译员身份、工作区与日志路径;后续翻译复用该会话,每轮仅发送指令行与原文,显著降低 Token 开销。
197
+ - **共享号池与自愈容错**:翻译调用走插件辅助通道,共享主账号池与冷却机制,账号额度耗尽自动故障转移至下一个可用账号;遇到空返回(`EMPTY_RESPONSE`)自动退避重试。
198
+ - **严格遵循用户授权**:自动翻译默认关闭(`autoTranslate: false`),可在「设置 → Antigravity」中全局开启,或在会话中通过 `/tsl auto on` 动态开启。同一行右侧的两个下拉框可分别改**翻译模型**(默认自动挑 Gemini Flash)与**翻译思考档**(默认跟随「默认思考强度」),改完即写配置、下一轮翻译生效。
217
199
 
218
- **`agy` 自己的自动更新也会闪窗。**
219
- `agy` 在距上次更新检查超过 15 分钟后会派生 `--bg-updater → agy --version` 子进程链,这条链由 agy 内部创建并自行分配可见控制台。插件从 0.4.66 起在每次 spawn 前把 `last_check.timestamp` 刷到当前时间,agy 便直接跳过检查、不再派生子进程。代价是这个 agy home 不再自动检查更新,手动 `agy update` 不受影响;开关是 `suppressAgyAutoUpdate`。
200
+ ---
220
201
 
221
- **某个模型选了思考强度后每轮都报 `--effort is not supported`。**
222
- 插件会学习这种拒绝:识别模型 id、原样重放一次不带 `--effort` 的调用,并把该模型记入 `~/.dsh/agy-link/effort-unsupported.json`,同时收回它宣称可用的档位。`/agy status` 的 `effortUnsupported` 与 `/agy doctor` 报告里能看到记录。
202
+ ## 🧩 架构与工作原理
223
203
 
224
- **额度显示不刷新。**
225
- 控制台点“刷新额度”,或执行 `/agy refresh-quota`。后台轮询默认每小时一次,可用 `quotaPollIntervalMs` 调整。
204
+ 1. **短生命周期进程驱动**:每一轮 DSH 对话启动一个独立的官方 `agy -p --output-format stream-json` 进程,解析 NDJSON 事件流。
205
+ 2. **多账号沙箱机制**:除主账号沿用系统默认 Keychain / HOME 外,所有备用账号在插件私有目录下建立专属 HOME 隔离区,独立写入 agy 格式的标准 OAuth 凭证。Windows 上 agy 的凭据实际存放在机器级 Credential Manager(`gemini:antigravity`),插件因此以「身份级引用计数租约」接管该槽:**同一授权的多个会话并行运行**,只有账号**身份切换**才串行,且由最后一个持有者还原主账号凭据。
206
+ 3. **多 Bucket 官方配额汇总**:插件定时后台静默轮询官方 `v1internal:retrieveUserQuotaSummary`,精准掌控每个账号的 5h 滚动削峰水位、7d 账号阶梯周额度,以及付费账号的 Argon 独立周池。
207
+ 4. **会话级无缝故障转移**:当遭遇 HTTP 429、额度耗尽或凭证异常时,号池调度器自动标记当前账号家族进入冷却(或按额度到期时间择优轮换),并无缝将后续请求路由到池内下一个有效账号。
208
+ 5. **失败分类与自愈**:错误按 AUTH / NETWORK / RATE_LIMIT / ELIGIBILITY 等精确分类;网络抖动借由 agy 运行日志自动甄别为可重试故障,绝不误伤健康账号的登录状态。
209
+ 6. **辅助通道隔离**:`/tsl` 翻译、会话标题生成、任务目标推导等通过独立专用辅助通道执行,共享号池与冷却机制,不占主会话绑定与工具权限。
226
210
 
227
- ## 文档
211
+ ---
228
212
 
229
- | 文档 | 内容 |
230
- | --- | --- |
231
- | [CONFIGURATION.md](./docs/CONFIGURATION.md) | 全部配置键、环境变量与默认值 |
232
- | [HEADLESS-PERMISSIONS.md](./docs/HEADLESS-PERMISSIONS.md) | 无头运行下的权限模式、最小权限验证与验收方法 |
233
- | [SECURITY-NOTES.md](./docs/SECURITY-NOTES.md) | 凭据隔离、静态资源与诊断脱敏的边界 |
234
- | [KNOWN-GAPS.md](./docs/KNOWN-GAPS.md) | 已知缺口与不打算支持的场景 |
235
- | [spec-account-pool.md](./docs/spec-account-pool.md) · [adr-012-account-pool.md](./docs/adr-012-account-pool.md) | 账号池的规格与设计决策 |
236
- | [CHANGELOG.md](./CHANGELOG.md) | 逐版本变更 |
213
+ ## ❓ 常见问题排查 (FAQ)
237
214
 
238
- ## 致谢
215
+ ### Windows 平台开始对话时为什么会短暂闪一下黑色命令行窗口(黑框)?
216
+ **答:这是 Windows 系统的控制台分配机制,完全良性,不会影响对话和模型功能。**
217
+ - **原因分析**:DSH 是基于 Electron 的图形桌面应用(GUI 进程),每次发起对话时,插件需要调用底层命令校验并同步当前账号在 Windows 凭据管理器(Credential Manager)中的 OAuth Token,随后启动 `agy.exe` 控制台子进程建立流式通信。在 Windows 11 下,系统默认终端若被设为「Windows 终端 (Windows Terminal)」,Windows Terminal 会拦截后台控制台子进程的句柄分配并闪现弹窗(这是 Windows Terminal 已知的 OpenConsole 委托拦截机制)。
218
+ - **解决步骤**:
219
+ 1. 打开 **Windows 终端 (Windows Terminal)** 的「设置」→「启动」(或进入 Windows「设置」→「系统」→「开发者选项」)。
220
+ 2. 将 **默认终端应用程序 (Default terminal application)** 从「让 Windows 决定」或「Windows 终端」更改为 **「Windows 控制台主机 (Windows Console Host)」**。
221
+ 3. 点击右下角 **保存 (Save)**。
222
+ 4. **完全退出并重启 DSH**(使新启动的主进程应用更新后的控制台委托注册表),黑框闪烁即可彻底消除。
239
223
 
240
- - [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI):Antigravity 公开 OAuth 客户端与回环回调登录范式
241
- - [opencode-antigravity-auth](https://github.com/NoeFabris/opencode-antigravity-auth):opencode 平台的多账号实践
242
- - [OmniRoute](https://github.com/diegosouzapw/OmniRoute):Antigravity 端点分发与配额语义
243
- - [pi-mono](https://github.com/badlogic/pi-mono):轮换与桥接设计参考
224
+ ### agy 自己的自动更新子进程也会闪窗(0.4.66 修复)
225
+ 除了上面那种控制台委托导致的闪窗,`agy` **自己**还会在距上次更新检查满 15 分钟后派生一条 `--bg-updater` → `agy --version` 的子进程链,**这条链由 agy 内部创建,会自行分配可见控制台**,父进程的 `windowsHide` 和 `AGY_CLI_DISABLE_AUTO_UPDATE=1` 都来不及生效(这就是 Issue #49 实测确认的结论)。
244
226
 
245
- ## 免责声明与许可
227
+ 0.4.66 起的处理方式:每次 spawn agy 之前,插件把 agy 更新检查的 fast-path 时间戳(`<agy home>/last_check.timestamp`)刷新为当前时间。agy 的检查逻辑是「距上次检查 < 15 分钟就直接跳过且不派生子进程」,于是这条可见窗口链根本不会被创建——对话、冷启动探测、模型选择器刷新、登录探测全部覆盖。
246
228
 
247
- 插件只调用用户本地安装的官方、未修改的 `agy` CLI 进程,使用需遵守 Google Antigravity 服务条款。代码以 MIT License 发布。
229
+ - **代价**:插件所使用的那个 agy home 不再自动检查更新;手动 `agy update` 完全不受影响。
230
+ - **开关**:`suppressAgyAutoUpdate`(环境变量 `DSH_AGY_SUPPRESS_AUTOUPDATE`)。Windows 上默认开启,其他平台默认关闭;设为 `false` 即回到 agy 原本的自动更新行为。
231
+ - **旧版本用户的手动 workaround**:把 `%USERPROFILE%\.gemini\antigravity-cli\updater\update.lock` 设为只读(`attrib +R ...`),agy 拿不到更新锁就会跳过检查。代价是手动 `agy update` 会报 `update already in progress`,需要先 `attrib -R`。
248
232
 
249
- ---
233
+ ### 某个模型选定思考强度后提示 `--effort is not supported`?
234
+ 部分模型(例如 Gemini Flash 系列或特定版本)并不支持 `--effort` 参数。插件具备自适应学习机制:当检测到模型拒绝 `--effort` 时,插件自动从拒绝报错中提取模型标识,立即原样重放一次不带 `--effort` 的请求,确保当前轮次对话顺利完成;同时将该模型写入 `~/.dsh/agy-link/effort-unsupported.json` 本地记录,并在后续运行时收回该模型宣称的思考强度档位,前端选择器自动隐藏该选项。学习记录可通过 `/agy status` 中的 `effortUnsupported` 字段及 `/agy doctor` 报告查阅。
250
235
 
251
- # English
236
+ ### 配额进度条未及时更新?
237
+ 配额信息由后台定时轮询(默认每小时轮询一次,可通过 `quotaPollIntervalMs` 调整)。如需即时刷新,可在控制台卡片中点击「同步」,或在输入框执行 `/agy refresh-quota`。
252
238
 
253
- Bring Google Antigravity into DeepSeek Harness. The plugin drives the official, unmodified `agy` CLI and adds multi-account pooling, official multi-bucket quota tracking, native streaming and tool cards, and `/tsl` plain-language rewriting.
239
+ ---
254
240
 
255
- ## Overview
241
+ ## 🙏 参考与致谢
256
242
 
257
- A stock DSH install only lists DeepSeek models. With this plugin, the Gemini, Claude and GPT-OSS models behind `agy` appear in `/model` under the `antigravity` provider and run on your existing Google subscription quota.
243
+ - [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) — Antigravity 公开 OAuth 客户端与回环回调登录范式
244
+ - [opencode-antigravity-auth](https://github.com/NoeFabris/opencode-antigravity-auth) — opencode 平台的多账号实践
245
+ - [OmniRoute](https://github.com/diegosouzapw/OmniRoute) — Antigravity 端点分发与配额语义
246
+ - [pi-mono](https://github.com/badlogic/pi-mono) — Antigravity 轮换与桥接设计参考
258
247
 
259
- This is not a proxy. Each turn spawns the official `agy` process, parses its NDJSON event stream, and maps it to native DSH text, thinking, tool cards and token accounting. Account rotation, quota inspection and retries all happen inside the plugin; DSH only sees a normal model call.
248
+ ---
260
249
 
261
- - Multiple Google accounts drain in order, so a conversation survives a quota wall.
262
- - Quotas come from the official endpoint: the 5-hour window, the weekly window and the paid Argon pool are reported separately.
263
- - Thinking, terminal commands and file edits render as native DSH cards, not grey text.
264
- - Not every model writes plainly, so `/tsl` can rewrite any reply in plain language.
250
+ ## ⚠️ 免责声明
265
251
 
266
- ## Core capabilities
252
+ 本插件仅通过调用用户本地官方安装的未修改 `agy` CLI 进程进行交互。使用本插件需遵循 Google Antigravity 服务条款。
267
253
 
268
- ### Account pool
254
+ ## 许可证
269
255
 
270
- - **Pooling**: the primary account keeps system credentials; every extra account gets its own HOME sandbox and OAuth credentials, with no cross-writes.
271
- - **Sequential drain**: on HTTP 429 or exhaustion the account cools down and the request moves to the next available account while the turn continues.
272
- - **Quota-expiry first**: among usable accounts the scheduler spends the one that resets soonest, leaving longer-lived quota for later.
273
- - **Jitter-safe auth**: keyring timeouts caused by proxy jitter are treated as retryable network errors; a sticky "needs re-login" verdict requires a second confirmation, so a healthy account is never falsely flagged.
274
- - **Manual switch**: "Set active" pins the scheduler pointer to one account, and the header badge always names the account the server actually schedules.
275
- - **Per-account proxy**: each account can bind its own HTTP(S) / SOCKS proxy to isolate egress IPs; when unset the system proxy is auto-detected (macOS `scutil`, Windows registry, Linux gsettings).
276
- - **Parallel leases**: concurrent sessions on the same account share a credential lease; only cross-account identity switches serialize.
277
- - **Family-scoped cooldown**: Gemini, Claude, GPT-OSS and Argon rate limits are tracked independently.
256
+ MIT License.
278
257
 
279
- ### Official quota tracking
258
+ ---
280
259
 
281
- The plugin calls Antigravity's `v1internal:retrieveUserQuotaSummary` and reports three buckets per account:
260
+ # English
282
261
 
283
- | Bucket | Meaning |
284
- | --- | --- |
285
- | 5-hour rolling | Short-window burst quota with reset countdown |
286
- | 7-day weekly | Account-level weekly cap |
287
- | Argon weekly | Separate weekly pool for Gemini 4 Argon on paid Pro / Ultra plans, not shared with the plain Gemini pool |
262
+ 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.
288
263
 
289
- Per-model detail expands under each bucket, so exhaustion is visible before a 429 arrives.
264
+ <p align="center">
265
+ <img src="./docs/assets/console.png" alt="Antigravity Management Console - Multi-Account Pool & Quota Monitor" width="760" />
266
+ </p>
267
+ <p align="center">
268
+ <img src="./docs/assets/model-picker.png" alt="Antigravity Model Lineup in DSH Model Picker" width="280" />
269
+ &nbsp;&nbsp;
270
+ <img src="./docs/assets/settings.png" alt="Antigravity Settings Panel in DSH" width="540" />
271
+ </p>
272
+ <p align="center">
273
+ <img src="./docs/assets/token-usage.png" alt="Native Context Caching & Token Usage Breakdown" width="340" />
274
+ &nbsp;&nbsp;
275
+ <img src="./docs/assets/context-metering.png" alt="Accurate 1M Context Window Metering" width="340" />
276
+ </p>
290
277
 
291
- ### Console and settings
278
+ ---
292
279
 
293
- The same console opens from two places: the `AGY (n)` badge in the header, and DSH's Settings → Plugins → Antigravity. The badge counts the accounts in the pool; opening it shows the pool, the quota bars and the proxy state.
280
+ > 🚨 **【Important: System Proxy / VPN / TUN Mode Required in Restricted Regions】**
281
+ >
282
+ > Google Antigravity services and Google OAuth require access to Google servers (`oauth2.googleapis.com`, `cloudcode-pa.googleapis.com`, etc.).
283
+ >
284
+ > 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.
285
+ > 2. **Terminal Proxy Export**: If your terminal does not inherit proxy automatically, export the environment variables before starting DSH:
286
+ > ```bash
287
+ > 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
288
+ > ```
289
+ > 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`).
294
290
 
295
- - **Account card**: alias and mailbox, active marker, enable / disable, sync, warmup, proxy, delete; under the quota bars you can expand the per-model detail for Claude and GPT-OSS.
296
- - **Runtime**: one line stating the permission mode is fixed to `skip` (unattended; agy's own protections still apply). Change it through config or `DSH_AGY_MODE`.
297
- - **Pool scheduling**: `Sequential drain` (exhaust one account, then move on) or `Round robin` (spread the requests evenly).
298
- - **7-day auto-warmup**: on / off. When enabled, a probe fires on the weekly reset or a cold start to activate the 7-day timer early.
299
- - **Auto translate**: on / off, off by default; when on, every completed turn gets a `/tsl` card automatically.
300
- - **Default thinking effort**: `auto` / `low` / `medium` / `high`, seeding the session model menu's initial level and still overridable per model.
301
- - **Model visibility**: click to hide or restore a model. Hiding only affects the picker, never a running conversation.
291
+ ---
302
292
 
303
- In the model picker, Antigravity appears as the `Antigravity (agy CLI)` group: Gemini 3.8 Flash, Claude Sonnet 4.6 (Thinking), Claude Opus 4.6 (Thinking), GPT-OSS 120B (Medium), and so on.
293
+ ## 🌟 Core Feature: Multi-Account Pool & Smart Rotation
304
294
 
305
- ### Native DSH integration
295
+ Have multiple Google Antigravity / Gemini accounts? **dsh-agy-link makes multi-account orchestration seamless and automated**:
306
296
 
307
- - **Model routing**: registers the `antigravity` provider so the Gemini, Claude, GPT-OSS and Argon families all appear in `/model` (group and model names above).
308
- - **Full streaming**: text, thinking annotations and tool activity map losslessly onto the native DSH stream.
309
- - **Native tool cards**: commands render as Terminal cards (command, cwd, exit code, timeout) and edits as inline diffs. Calls made through Antigravity's MCP meta-tool (`call_mcp_tool`) are unwrapped into terminal, search or `<server>: <tool>` cards instead of repeated raw JSON.
310
- - **Diagram rendering**: mermaid blocks render to diagrams once streaming settles, and multiple diagrams render serially without clobbering each other.
311
- - **Session continuity**: DSH sessions bind to native agy conversations (`--conversation`); agy owns the history and each turn sends only the increment.
312
- - **Goal and plan forwarding**: long-running tasks carry DSH goal / plan context so tool continuations keep their state.
313
- - **Token metering**: input, output, thinking and cache-read (`cache_read_tokens`) tokens are all reported, with 1M context support.
314
- - **Effort learning**: when a model rejects `--effort`, the plugin parses the model id from the refusal, replays the call once without the flag, and records the model in `~/.dsh/agy-link/effort-unsupported.json`. A mismatch costs one extra process, never a failed turn.
315
- - **Multimodal images**: images are staged to a local media directory and authorized to agy through `--add-dir`.
316
- - **`agy_ask` delegation**: any DSH model can hand a self-contained task to an Antigravity model.
297
+ - 👥 **Multi-Account Pooling**: Manage unlimited Google accounts (Primary + Secondary pool) with fully isolated HOME sandbox environments and credentials.
298
+ - 🔄 **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!
299
+ - 🕰 **Quota-Expiry-First Rotation**: With several accounts available, the scheduler prefers the one whose **reset window expires soonest**, maximizing utilization across the whole pool.
300
+ - 🧠 **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.
301
+ - 📊 **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).
302
+ - 🔀 **Manual Switch-Active**: One click on "Set active" pins the scheduler pointer to the account you choose.
303
+ - 🔑 **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**.
304
+ - 🎨 **Theme-Adaptive High-Contrast UI**: Seamlessly adapts to Light and Dark DSH themes with crystal clear typography and crisp contrast.
305
+ - 📱 **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.
306
+ - 🗣 **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`).
307
+ - 🧠 **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.
308
+ - 🌐 **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).
309
+ - ⚡ **Family-Scoped Cooldowns**: Gemini, Claude, GPT-OSS, and Argon rate limits are calculated independently, preventing one exhausted model from blocking others.
317
310
 
318
- ### `/tsl` plain-language rewriting
311
+ ---
319
312
 
320
- `/tsl` sends the current session's output to Gemini (default `gemini-3.8-flash` · `high`) and asks for the explanation you would give a colleague out loud.
313
+ ## ✨ Features Overview
321
314
 
322
- - **Three entry points**: the `/tsl` command, an opt-in auto-translate switch in settings, and a per-reply "translate" action.
323
- - **Card anchored under the reply**: results persist as `plugin:agy-link/translation` records and render as a labelled translation card directly under the reply they translate. It survives reloads and session switches, keeps the original behind a toggle, and never enters model-visible history.
324
- - **Same account pool**: translation rides the plugin's auxiliary channel, so a quota-exhausted account cools down and the request retries on the next one.
325
- - **One translation conversation per DSH session**: the persona (identity, DSH session id, workspace, raw-log path) is sent once; later calls send only the request line.
326
- - **Off by default**: auto translation spends quota every turn, so `autoTranslate` stays `false` until you enable it in settings or with `/tsl auto on`.
315
+ | Feature | Description |
316
+ | --- | --- |
317
+ | 🎨 **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`) |
318
+ | 🧩 **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 |
319
+ | 🚀 **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 |
320
+ | ⚡ **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 |
321
+ | 👥 **Multi-Account Pool** | Primary + unlimited spare accounts with automatic Sequential Drain rotation upon rate limits; quota-expiry-first scheduling |
322
+ | 🧠 **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 |
323
+ | 📊 **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 |
324
+ | 🔑 **Zero-Paste Browser Login** | Automatic browser-based Google OAuth login with loopback callback handler |
325
+ | 🔀 **Manual Switch-Active** | Pin the scheduler to any account from the console; the header badge always names the server-scheduled account |
326
+ | 🎨 **Theme-Adaptive UI** | Dynamic light/dark theme switching, pure SVG vector marks (no emojis), high contrast |
327
+ | 📱 **Mobile Web Responsiveness** | Transitions to full-height sheet drawer (`100dvh`) below 680px, stacked labels, and equal-width button grid for touch devices |
328
+ | 🌐 **Per-Account Proxy** | Dedicated HTTP(S) proxy per account slot, or auto-detected system proxy |
329
+ | 🔌 **Native Model Routing** | Registers `antigravity` provider in DSH; choose Gemini / Claude / GPT-OSS / Argon in `/model` picker under `Antigravity (agy CLI)` |
330
+ | 🌊 **Full Streaming Protocol** | Native streaming for text, thinking turn annotations, and tool calls |
331
+ | 🃏 **Native Tool UI Cards** | Command runs and inline diffs render as clean, native DSH tool cards; MCP meta-tools unwrap to Terminal/Search cards |
332
+ | 🔗 **Session Continuity** | Binds DSH sessions to native agy conversations (`--conversation`) for zero-redundancy context |
333
+ | 🎯 **DSH Goal & Plan Integration** | Long-running tasks carry DSH goal / plan context across tool continuations |
334
+ | 📊 **Accurate Token Metering** | Input, output, thinking, and cacheRead tokens are fully reported to DSH with 1M context support |
335
+ | 🎛 **Top Header Console Badge** | Click the `AGY (n)` badge in the header to instantly open the management console |
336
+ | 🖼 **Multimodal Images** | Stages images to local storage and passes safe absolute paths via `--add-dir` |
337
+ | 🤝 **`agy_ask` Delegation** | Allows other DSH models to delegate subtasks to Antigravity models |
338
+ | 🧠 **Effort Learning Mechanism** | Automatically learns model effort refusals, replays without `--effort`, and hides unsupported options |
339
+ | 🗣 **`/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 |
340
+ | ⌨️ **`/agy` Commands** | Full command suite: `status`, `pool`, `auth`, `models`, `mode`, `effort`, `workspace`, `goal`, `session`, `enable-account`, `disable-account`, `clear`, `doctor`, `help` |
327
341
 
328
- ## Quick start
342
+ ---
329
343
 
330
- ### Requirements
344
+ ## 📋 Prerequisites
331
345
 
332
346
  | Requirement | Details |
333
347
  | --- | --- |
334
- | Network | Reachable Google endpoints (`oauth2.googleapis.com`, `cloudcode-pa.googleapis.com`). Use a TUN / system proxy where required |
335
- | DeepSeek Harness | `dsh --version` |
336
- | Node.js | ≥ 24, `node --version` |
337
- | Google Antigravity CLI | Installed per the [official guide](https://antigravity.google/docs/cli/install); `agy --version` prints a version |
338
-
339
- If your terminal does not inherit the proxy, export it before starting DSH:
348
+ | **1. System Proxy / VPN** | **【Required in restricted regions】** (TUN mode or `HTTPS_PROXY` environment variable to ensure Google endpoints are reachable) |
349
+ | **2. DeepSeek Harness (DSH)** | Your current DSH environment (`dsh --version`) |
350
+ | **3. Node.js ≥ 24** | Required runtime (`node --version`) |
351
+ | **4. Google Antigravity `agy` CLI** | Installed per [Google's official guide](https://antigravity.google/docs/cli/install). Verified with `agy --version` |
340
352
 
341
- ```bash
342
- 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
343
- ```
344
-
345
- Replace the port with your local proxy port. A dedicated proxy can also be set per account in the console.
353
+ ---
346
354
 
347
- ### Install and sign in
355
+ ## 🚀 Quick Start
348
356
 
349
357
  ```bash
350
- # Install (npm package, no local build)
358
+ # 0. Ensure System Proxy / TUN mode is active (required for Google connectivity):
359
+ export HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890
360
+
361
+ # 1. Install plugin:
351
362
  dsh plugin --profile web add dsh-agy-link
352
363
 
353
- # Upgrade
354
- dsh plugin --profile web add dsh-agy-link@latest
364
+ # Upgrade to latest:
365
+ # dsh plugin --profile web add dsh-agy-link@latest --registry https://registry.npmjs.org
355
366
 
356
- # Start DSH Web, then check status:
367
+ # 2. Start DSH Web GUI, test status:
357
368
  # /agy status
358
- ```
359
369
 
360
- To sign in, click the `AGY (n)` badge in the header and choose "Add account": the browser opens Google's consent page and the local loopback captures the credentials, so no authorization code needs copying. Alternatively run `/agy auth` for the primary account. Once signed in, pick an Antigravity model in `/model` and start chatting.
370
+ # 3. Add accounts:
371
+ # Click "AGY (n)" badge in the top header, click "➕ Add Account" and complete browser login.
361
372
 
362
- You can install the plugin before `agy` is signed in; the plugin provides the login entry point.
373
+ # 4. Select an Antigravity model in /model and start chatting!
374
+ ```
363
375
 
364
- ## Usage and configuration
376
+ ---
365
377
 
366
- ### `/agy` commands
378
+ ## ⚙️ Configuration
367
379
 
368
- | Command | Purpose |
369
- | --- | --- |
370
- | `status` | Binary, version, auth, permission mode, model catalog, session bindings |
371
- | `pool` / `accounts` | Account pool, live quota percentages, cooldowns |
372
- | `auth` / `auth-code` | Start login / finish login with a code or callback URL |
373
- | `add-account` / `remove-account` | Create an account slot (then finish terminal login) / delete an account |
374
- | `enable-account` / `disable-account` | Enable or disable an account |
375
- | `refresh-quota` / `clear-cooldown` | Refresh quotas now / clear cooldowns |
376
- | `models` | Model catalog |
377
- | `mode` | Permission mode: `skip` / `plan` / `accept-edits` |
378
- | `effort` | Thinking effort: `low` / `medium` / `high` / `default` |
379
- | `dispatch` / `dispatch-retries` / `parallel` / `max-concurrent` | Dispatch wait cap, retries, same-account parallelism, concurrency cap |
380
- | `workspace` | Workspace root |
381
- | `goal` | Inspect or control the DSH goal (`status` / `complete` / `pause` / `resume` / `clear`) |
382
- | `session` | Session binding details |
383
- | `clear` | Clear the current session binding |
384
- | `doctor` | Write a diagnostic report and return its path (secrets redacted) |
385
-
386
- ### Configuration
387
-
388
- Resolution order: `DSH_AGY_*` environment variables > runtime overrides > plugin entry config > defaults. The table below covers the common keys; the complete reference is in [docs/CONFIGURATION.md](./docs/CONFIGURATION.md).
389
-
390
- | Key | Environment variable | Default | Description |
380
+ | Key | Environment Variable | Default | Description |
391
381
  | --- | --- | --- | --- |
392
382
  | `enabled` | `DSH_AGY_ENABLED` | `true` | Master switch |
393
- | `agyBin` | `DSH_AGY_BIN` | auto-detected | Path to the `agy` binary |
394
- | `permissionMode` | `DSH_AGY_MODE` | `skip` | `skip` (unattended execution) / `plan` / `accept-edits`; not switchable in the settings panel, still overridable by config or env |
395
- | `defaultModel` | `DSH_AGY_DEFAULT_MODEL` | agy default | Default model slug |
396
- | `defaultEffort` | `DSH_AGY_DEFAULT_EFFORT` | `high` | Seeds the session model menu's initial level; the menu still overrides it per model |
397
- | `hiddenModels` | `DSH_AGY_HIDDEN_MODELS` | `[]` | Slugs hidden from the model picker (deny-list; new models stay visible) |
383
+ | `agyBin` | `DSH_AGY_BIN` | auto-detected | Path to `agy` binary |
384
+ | `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) |
385
+ | `defaultModel` | `DSH_AGY_DEFAULT_MODEL` | `(agy default)` | Default model slug |
386
+ | `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) |
387
+ | `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) |
398
388
  | `timeoutMs` | `DSH_AGY_TIMEOUT_MS` | `600000` | Activity watchdog timeout in milliseconds |
399
- | `longToolIdleMinutes` | `DSH_AGY_LONG_TOOL_IDLE_MINUTES` | `240` | Idle budget while a tool step is open; `0` keeps `timeoutMs` so wedged tools fail fast |
400
- | `workspaceRoot` | `DSH_AGY_WORKSPACE_ROOT` | session cwd | agy workspace root |
401
- | `proxyUrl` | `DSH_AGY_PROXY_URL` | empty | Global proxy; per-account proxies set in the console take precedence |
402
- | `suppressAgyAutoUpdate` | `DSH_AGY_SUPPRESS_AUTOUPDATE` | `true` on Windows, `false` elsewhere | Refreshes agy's update-check timestamp before each spawn so the `--bg-updater` chain (the Windows console flash) never starts |
403
- | `autoWarmup` | `DSH_AGY_AUTO_WARMUP` | `false` | Opt-in weekly-quota warmup: a minimal probe when the weekly window resets or is cold, re-checked every 5 minutes. This path talks to Google's internal endpoints, so assess the risk-control tradeoff yourself |
404
- | `warmupModels` | `DSH_AGY_WARMUP_MODELS` | `gemini-3.8-flash,claude-sonnet-4-6` | Models used for warmup; empty disables it |
405
- | `autoTranslate` | `DSH_AGY_AUTO_TRANSLATE` | `false` | Translate every completed turn; `/tsl auto on` overrides per session |
406
- | `translateModel` | `DSH_AGY_TRANSLATE_MODEL` | `gemini-3.8-flash` | Model used by `/tsl` and auto mode, with a catalog fallback |
407
- | `translateEffort` | `DSH_AGY_TRANSLATE_EFFORT` | `high` | Reasoning effort for the translate model |
408
- | `translateTargetLanguage` | `DSH_AGY_TRANSLATE_LANG` | `中文(简体)` | Target language in the translator prompt |
409
- | `translateBindConversation` | — | `true` | Reuse one agy translation conversation per DSH session so the persona is sent once |
410
- | `askTool` | — | `false` | Expose the `agy_ask` delegation tool |
411
- | `mcpBridge` | `DSH_AGY_MCP_BRIDGE` | `false` | Bridge DSH-side MCP configuration into agy |
412
-
413
- ### `/tsl` usage
389
+ | `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 |
390
+ | `workspaceRoot` | `DSH_AGY_WORKSPACE_ROOT` | session cwd | Working directory root |
391
+ | `proxyUrl` | `DSH_AGY_PROXY_URL` | empty string | Global proxy URL; per-account proxies configured in console take precedence |
392
+ | `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 |
393
+ | `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 |
394
+ | `warmupModels` | `DSH_AGY_WARMUP_MODELS` | `gemini-3.8-flash,claude-sonnet-4-6` | Model list used for warmup probes (comma-separated); an empty list disables automatic warmup |
395
+ | `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` |
396
+ | `translateModel` | `DSH_AGY_TRANSLATE_MODEL` | `gemini-3.8-flash` | Model used by `/tsl` and auto mode; falls back through the live catalog when absent |
397
+ | `translateEffort` | `DSH_AGY_TRANSLATE_EFFORT` | `high` | Reasoning effort for effort-capable translate models |
398
+ | `translateTargetLanguage` | `DSH_AGY_TRANSLATE_LANG` | `中文(简体)` | Target language wording in the translator prompt |
399
+ | `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 |
400
+
401
+ > 💡 For full configuration reference, see [docs/CONFIGURATION.md](./docs/CONFIGURATION.md).
402
+
403
+ ---
404
+
405
+ ## 🗣 Plain-language translation (`/tsl`)
406
+
407
+ Not every model writes plainly. `/tsl` sends the current session's output to a
408
+ Gemini model (default `gemini-3.8-flash` · `high`) and gets a "human language"
409
+ rewrite back.
414
410
 
415
411
  ```
416
412
  /tsl # translate the last completed turn
@@ -418,50 +414,90 @@ Resolution order: `DSH_AGY_*` environment variables > runtime overrides > plugin
418
414
  /tsl --full # include the turn's intermediate narration
419
415
  /tsl --text 任意文本… # translate arbitrary text (no card)
420
416
  /tsl --model claude-sonnet-5-5 --effort medium
421
- /tsl --print # echo the body in the command result
417
+ /tsl --print # also echo the body in the command result
422
418
  /tsl auto on|off|status # per-session auto mode
423
419
  ```
424
420
 
425
- ## How it works
421
+ - The result is stored as a durable `plugin:agy-link/translation` session
422
+ record and rendered as a **"Gemini translation" card pinned directly under the
423
+ reply it translates** — it survives reloads, reads like any other DSH card (one
424
+ tinted spark plus a "Gemini 译文" label are the only Gemini signals), and never
425
+ enters the model-visible history.
426
+ - Every reply also gets a hover action **"译成人话"** so historical turns can be
427
+ translated on demand.
428
+ - Binds 1:1 agy translation conversation (`<sessionId>#tsl`): persona sent once, per-turn calls transmit only the request line.
429
+ - The translation call rides this plugin's own auxiliary adapter route, so it
430
+ uses the same account pool: **when an account is out of quota it is cooled
431
+ down and the request retries on the next account automatically** (watch
432
+ `/agy pool` for the switch). Empty model responses (`EMPTY_RESPONSE`) retry automatically.
433
+ - Translation is strictly opt-in (`autoTranslate: false` by default) because it
434
+ spends quota per turn. Toggle it in **Settings → Antigravity**, or per session
435
+ with `/tsl auto on`.
426
436
 
427
- 1. **Per-turn process**: each turn spawns `agy -p --output-format stream-json` and parses the NDJSON events.
428
- 2. **Account sandboxes**: the primary account uses the system Keychain / HOME; extra accounts get an isolated HOME under the plugin's private directory with standard OAuth credentials. On Windows, agy's credential lives in the machine-level Credential Manager (`gemini:antigravity`), so the plugin takes that slot over with an identity-scoped reference-counted lease: concurrent sessions on one authorization run in parallel, only identity switches serialize, and the last holder restores the primary credential.
429
- 3. **Background quota polling**: a silent timer calls the official quota endpoint and maintains each account's bucket levels and reset times.
430
- 4. **Failure classification**: errors are classified as AUTH / NETWORK / RATE_LIMIT / ELIGIBILITY / TIMEOUT and so on; jitter is distinguished from a real sign-out by the `keyringAuth` transport evidence in agy's run log.
431
- 5. **Auxiliary channel**: `/tsl`, session titles and goal derivation use a separate channel (`purpose:'translation'` and friends) that shares the account pool and cooldowns but stays out of conversation bindings, tool exposure and concurrency slots.
437
+ ---
432
438
 
433
- ## FAQ
439
+ ## Headless operation
434
440
 
435
- **A black console window flashes when a turn starts on Windows.**
436
- DSH is an Electron app; before each turn the plugin syncs the OAuth token in the Windows Credential Manager and launches `agy.exe` as a console child. If Windows 11 uses "Windows Terminal" as the default terminal, it briefly flashes while allocating that background console. Set the default terminal application to "Windows Console Host" and restart DSH completely.
441
+ See [Headless permissions](docs/HEADLESS-PERMISSIONS.md) for a bounded reproduction,
442
+ least-privilege read-rule validation, and process-versus-tool acceptance checks.
437
443
 
438
- **agy's own auto-updater flashes a window too.**
439
- Once its last update check is more than 15 minutes old, agy spawns a `--bg-updater → agy --version` chain that allocates its own visible console. Since 0.4.66 the plugin refreshes `last_check.timestamp` before every spawn, so agy skips the check and never spawns the chain. The cost is that this agy home stops auto-checking for updates; a manual `agy update` still works. The switch is `suppressAgyAutoUpdate`.
444
+ The plugin passes the selected permission mode to `agy`; it does not approve,
445
+ deny, or bypass permissions itself. In headless/print operation, `agy` can
446
+ automatically deny a tool request in `plan` or `accept-edits`. The raw tool
447
+ error is retained in `/agy status`; it is not proof of a human denial.
440
448
 
441
- **A model keeps failing with `--effort is not supported`.**
442
- The plugin learns the refusal: it identifies the model, replays the call once without `--effort`, records the model in `~/.dsh/agy-link/effort-unsupported.json`, and stops advertising effort levels for it. See `effortUnsupported` in `/agy status` and the `/agy doctor` report.
449
+ Do not assume undocumented wildcard semantics for either mode. Test the exact
450
+ `agy` version and command set in a scoped workspace. Choose `skip` only when
451
+ you explicitly accept unattended tool execution.
443
452
 
444
- **Quotas look stale.**
445
- Press "Refresh quota" in the console or run `/agy refresh-quota`. Background polling defaults to once an hour and can be tuned with `quotaPollIntervalMs`.
453
+ ---
446
454
 
447
- ## Documentation
455
+ ## ❓ FAQ & Troubleshooting
456
+
457
+ ### Why does a black command prompt / terminal window briefly flash when starting a conversation on Windows?
458
+ **A: This is a cosmetic behavior of the Windows Console subsystem and is completely harmless.**
459
+ - **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).
460
+ - **Solution**:
461
+ 1. Open **Windows Terminal** → **Settings** → **Startup** (or Windows **Settings** → **System** → **For developers**).
462
+ 2. Change **Default terminal application** from "Let Windows decide" or "Windows Terminal" to **"Windows Console Host"**.
463
+ 3. Click **Save** in the bottom-right corner.
464
+ 4. **Completely exit and restart DSH** so the running host process picks up the updated console delegation setting.
465
+
466
+ ### agy's own auto-updater also flashes a window (fixed in 0.4.66)
467
+ On top of the console-delegation flash above, `agy` itself spawns a
468
+ `--bg-updater` → `agy --version` child chain once its last update check is more
469
+ than 15 minutes old. **That chain is created inside agy and allocates its own
470
+ visible console**, so the parent's `windowsHide` and `AGY_CLI_DISABLE_AUTO_UPDATE=1`
471
+ both apply too late — the exact conclusion of the measurements recorded in issue #49.
472
+
473
+ Since 0.4.66 the plugin refreshes agy's fast-path timestamp
474
+ (`<agy home>/last_check.timestamp`) right before every spawn. agy skips the
475
+ check entirely when it is under 15 minutes old and spawns nothing, so the
476
+ visible window chain never starts — for turns, boot probes, model-picker
477
+ refreshes and login probes alike.
478
+
479
+ - **Cost**: the agy home used by this plugin stops auto-checking for updates;
480
+ a manual `agy update` still works normally.
481
+ - **Switch**: `suppressAgyAutoUpdate` (env `DSH_AGY_SUPPRESS_AUTOUPDATE`).
482
+ On by default on Windows, off elsewhere; set `false` to restore agy's own behaviour.
483
+ - **Manual workaround on older versions**: make
484
+ `%USERPROFILE%\.gemini\antigravity-cli\updater\update.lock` read-only
485
+ (`attrib +R ...`). agy then fails to acquire the update lock and skips the
486
+ check — at the price of `agy update` reporting `update already in progress`
487
+ until you run `attrib -R`.
488
+
489
+ ### What happens when a model rejects `--effort` with `--effort is not supported`?
490
+ 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`.
491
+
492
+ ### Why are quota bars not updating?
493
+ 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.
448
494
 
449
- | Document | Contents |
450
- | --- | --- |
451
- | [CONFIGURATION.md](./docs/CONFIGURATION.md) | Every configuration key, environment variable and default |
452
- | [HEADLESS-PERMISSIONS.md](./docs/HEADLESS-PERMISSIONS.md) | Permission modes in headless runs, least-privilege validation and acceptance checks |
453
- | [SECURITY-NOTES.md](./docs/SECURITY-NOTES.md) | Credential isolation, static assets and diagnostic redaction boundaries |
454
- | [KNOWN-GAPS.md](./docs/KNOWN-GAPS.md) | Known gaps and scenarios that are out of scope |
455
- | [spec-account-pool.md](./docs/spec-account-pool.md) · [adr-012-account-pool.md](./docs/adr-012-account-pool.md) | Account-pool specification and design decision |
456
- | [CHANGELOG.md](./CHANGELOG.md) | Release-by-release changes |
495
+ ---
457
496
 
458
- ## Credits
497
+ ## ⚠️ Disclaimer
459
498
 
460
- - [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI): public Antigravity OAuth client and loopback callback pattern
461
- - [opencode-antigravity-auth](https://github.com/NoeFabris/opencode-antigravity-auth): multi-account practice on opencode
462
- - [OmniRoute](https://github.com/diegosouzapw/OmniRoute): Antigravity endpoint dispatch and quota semantics
463
- - [pi-mono](https://github.com/badlogic/pi-mono): rotation and bridge design reference
499
+ 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.
464
500
 
465
- ## Disclaimer and license
501
+ ## License
466
502
 
467
- The plugin only invokes the official, unmodified `agy` CLI installed on the local machine; use is subject to Google Antigravity's Terms of Service. Released under the MIT License.
503
+ MIT License.