dsh-agy-link 0.4.5 → 0.4.10

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.
Files changed (6) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/README.md +176 -147
  3. package/dist/client.js +843 -444
  4. package/dist/index.js +392 -203
  5. package/docs/spec-account-pool.md +1 -1
  6. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,38 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.4.10 (2026-08-21)
4
+
5
+ - **Fixed `Error: unknown tool "run_code"` loop (Root Cause).**
6
+ - Standard DSH agents and WebUI run direct tool dispatch without Code Mode runner (`run_code`). Emitting span cuts addressed to `run_code` triggered `ToolNotFoundError: unknown tool "run_code"` and trapped agy in an infinite error loop.
7
+ - Span cuts now directly emit `agy_tool` tool-call blocks, which execute instantly and render native tool cards (Terminal, Diff, Read, Search).
8
+ - **Emphasized System Proxy & TUN Mode Requirements in README.**
9
+ - Added prominent warnings and configuration instructions for system proxy, TUN mode, and environment variables (`HTTPS_PROXY`) required for Google connectivity in restricted regions.
10
+
11
+ ## 0.4.9 (2026-08-20)
12
+
13
+ - **Theme-Adaptive System & High-Contrast Typography.**
14
+ - Dynamic adaptation to DSH light and dark themes (`body[data-ds-dark-theme]` / `[data-theme="dark"]` / system preferences) across all UI elements (Settings section, header status badge `AGY (n)`, and modal console dialog).
15
+ - High-contrast text & palette tuning: replaced hardcoded dark backgrounds and pale/white text with responsive semantic tokens, ensuring crystal clear legibility in light mode without washed-out or invisible text.
16
+ - Redesigned quota bars, status pills, submodel breakdown rows, buttons, segment toggles, OAuth dialogs, and alert banners with theme-adaptive contrast.
17
+
18
+ ## 0.4.8 (2026-08-20)
19
+
20
+ - **Pure SVG UI icon system (zero emojis).** Replaced tacky unicode emojis across the UI (trash can, star, plus, refresh, globe, mail, zap, alert, chevrons, close buttons) with clean, crisp, Lucide-style vector SVG icons for a professional developer experience.
21
+ - **Accurate quota window display & weekly lockout aggregation.**
22
+ - Quota bars and breakdown rows now display clear window badges (`5h 滚动` / `周限额`) and time countdowns (`↻ 15:46 (4h36m)`).
23
+ - Fixed family quota aggregation: bottleneck model selection now correctly binds the family `resetTime` to the bottleneck model with the lowest `remainingFraction` (and picks the furthest reset on tie), ensuring 7-day weekly rate limits are faithfully preserved and displayed.
24
+
25
+
26
+ - **Mid-turn steer preemption.** DSH claims a steered ("插话") message at the next step boundary and opens a NEW stream() call; the previous run's agy process used to stay alive and keep appending to the SAME conversation concurrently. The adapter now tracks the in-flight run per session and aborts it before starting the steered run (auxiliary calls neither preempt nor get tracked).
27
+ - **UI simplification.** Sidebar bottom-left shortcut removed (the console modal now lives on the header `AGY (n)` badge); quota rows are percent-first — brand logo + bar + `85%` + `↻ 14:44 · 3h12m` — with language-neutral `5h`/`7d` window badges and all Chinese status words (`充足/紧张/适中/未知`) dropped.
28
+
29
+ ## 0.4.6 (2026-08-20)
30
+
31
+ - **Fixed premature context compaction (root cause).** agy's `result` envelope reports CONVERSATION-CUMULATIVE usage (input 3.8M / cacheRead 72M in the wild), while `step_update` usage is per-call (true current context). DSH's token meter treats the last sample as context occupancy, so forwarding the cumulative envelope exploded pressure past the 80%-of-1M threshold within a few turns and fired constant compactions. The mapper now reports the last per-call step sample (tracked on the shared run recording, span-safe); falls back to the envelope only when no step carried usage.
32
+ - **Quota windows + model logos in the UI.** Per-family bars now carry official Gemini / Claude / OpenAI brand SVG marks, a 5小时额度/周额度 window badge (inferred from reset distance), and a live reset countdown; per-model breakdown rows stay available on expand. Removed the verbose mechanism-explainer block.
33
+ - **Unified browser login everywhere.** `/agy auth` now runs the same PKCE + loopback-callback flow as the pool's add-account (new `PoolAuthFlow.beginPrimary()` writing agy-format tokens into the real HOME); the QR/code-paste-first copy is gone from README and command help. Primary flows never touch staging cleanup.
34
+ - **README refresh.** Install/login instructions match the browser flow; new References section (CLIProxyAPI, opencode-antigravity-auth, OmniRoute, pi-mono).
35
+
3
36
  ## 0.4.5 (2026-08-20)
4
37
 
5
38
  - **Fixed Quota Display (Root Cause).**
package/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  <h1 align="center">🛰️ dsh-agy-link</h1>
2
2
 
3
3
  <p align="center">
4
- <b>DeepSeek Harness × Google Antigravity</b> — 用官方 agy CLI 把 Antigravity 模型接进 DSH / bring Google Antigravity models into DSH via the official agy CLI
4
+ <b>DeepSeek Harness × Google Antigravity</b> — 多账号智能池化与官方 agy CLI 驱动桥接 / Multi-Account Pool & Native agy CLI Bridge for DSH
5
5
  </p>
6
6
 
7
7
  <p align="center">
@@ -23,221 +23,250 @@
23
23
 
24
24
  > 全网统一昵称：**小斯syzs** · B站 [@小斯syzs](https://space.bilibili.com/390211071) · 抖音 · 小红书 · 快手（全网同名）
25
25
 
26
- 把 **Google Antigravity 模型接入 DeepSeek Harness（DSH）** —— 由官方
27
- `agy` CLI 驱动，完整支持对话输出、思考（thinking）、工具活动与 token
28
- 用量，全部走你的 Antigravity 订阅。
26
+ 把 **Google Antigravity 模型接入 DeepSeek Harness（DSH）** —— 支持**多账号智能池化轮换**、**官方双 Bucket 配额监控（5小时滚动 + 7天周额度）**、**浏览器免粘贴一键登录**与**浅色/深色主题高对比度自适应**，由官方未修改的 `agy` CLI 驱动，完整支持流式输出、思考折叠（thinking）、原生工具卡片与精确 token 用量。
29
27
 
30
- **它是怎么工作的**：在 `/model` 选择器里挑一个 Antigravity 模型，之后每一轮对话，插件都会在你的工作区启动一个短生命周期的官方 `agy` 进程（`agy -p --output-format stream-json`），解析它输出的 NDJSON 事件流，把文本、思考、工具活动逐块映射回 DSH。多轮对话通过把 DSH 会话绑定到 agy 原生会话（`--conversation`）实现——agy 自己保存历史，每轮只发最新消息。**插件只启动官方未修改的 agy 二进制**：不逆向它的数据库、不解码 protobuf、不碰你的 OAuth token。
28
+ ---
29
+
30
+ > 🚨 **【国内用户核心前置：必须开启系统代理 / TUN 模式！】**
31
+ >
32
+ > Google Antigravity 服务及 OAuth 登录需要直连 Google 海外官方服务器（`oauth2.googleapis.com`、`cloudcode-pa.googleapis.com` 等）。
33
+ >
34
+ > 1. **推荐方式（最稳妥）**：开启代理工具（Clash / Surge / v2rayA / Sing-box / Loon 等）的 **TUN 虚拟网卡模式（或系统代理全局接管）**，确保终端命令、后台 Node.js 进程及浏览器均能顺畅访问 Google 网络。
35
+ > 2. **终端代理环境变量**：若终端未被代理自动接管，启动 DSH 或运行命令前请在终端中执行：
36
+ > ```bash
37
+ > 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
38
+ > ```
39
+ > *(注：端口 `7890` 请替换为你本地代理软件的实际端口)*
40
+ > 3. **GUI 单账号独立代理**：进入 DSH「设置 → Antigravity」或点击顶部 `AGY` 徽标，点击卡片上的「🌐 代理」按钮，可为特定账号单独配置专属代理 URL（如 `http://127.0.0.1:7890`），实现多账号不同 IP 出口隔离。
41
+
42
+ ---
43
+
44
+ ## 🌟 核心亮点：多账号池化与智能轮换
31
45
 
32
- ## ✨ 你能得到什么
46
+ 你拥有多个 Google Antigravity / Gemini 账号？**dsh-agy-link 让多账号管理变得极致简单与自动化**：
47
+
48
+ - 👥 **多账号池化管理 (Account Pool)**：在 DSH 内添加任意数量的 Google 账号（主账号 + 备用账号群），每个账号拥有独立的 HOME 目录沙箱与凭证隔离。
49
+ - 🔄 **顺序耗尽故障转移 (Sequential Drain)**：当前账号额度用尽（触发 429 限流或 5h / 周额度耗尽）时，系统**自动平滑接力至下一个可用账号**，对话完全不中断！
50
+ - 📊 **官方双 Bucket 配额监控 (Dual-Bucket Quota)**：直接调用 Antigravity 官方专用的 `v1internal:retrieveUserQuotaSummary` 接口，同时展示 **5小时滚动额度** 与 **7天周额度** 真实数据及精准重置倒计时。
51
+ - 🔑 **GUI 内浏览器免粘贴登录 (In-GUI Zero-Paste OAuth)**：点击「➕ 添加账号」自动调起系统浏览器，本地回环监听自动捕获授权凭证，**全程无需手动复制粘贴授权码**。
52
+ - 🎨 **多主题高对比度自适应 (Light & Dark Themes)**：原生适配 DSH 浅色/深色主题，告别发暗发灰与看不清文字，UI 视觉清晰锐利。
53
+ - 🌐 **独立账号网络代理 (Per-Account Proxy)**：支持为每个账号独立绑定 HTTP(S) / SOCKS 代理，避免多账号同 IP 引起风控。
54
+ - ⚡ **分模型族独立冷却 (Family-Scoped Cooldown)**：Gemini 与 Claude / GPT-OSS 速率限制独立计算，某个模型族受限不影响其他模型族正常调用。
55
+
56
+ ---
57
+
58
+ ## ✨ 全功能特性一览
33
59
 
34
60
  | 能力 | 说明 |
35
61
  | ---- | ---- |
36
- | 🔌 **模型路由** | 在 DSH 模型配置里注册 `antigravity` 提供方，`/model` 选择器直接挑任意 Antigravity 模型（Gemini / Claude / GPT-OSS） |
37
- | 🌊 **完整流式** | 文本、思考、agy 工具活动（注记为 reasoning 块）全部映射到 DSH 原生流协议 |
38
- | 🔗 **会话连续** | 每个 DSH 会话绑定原生 agy 会话（`--conversation`），多轮上下文由 agy 历史承载，不重发全量 |
39
- | 📊 **token 用量** | 输入/输出/思考/缓存 token 全部进入 DSH 用量统计 |
40
- | ⚙️ **设置页状态** | DSH 设置 → Antigravity 页面显示 agy 连接/登录/工作区/绑定数/最近运行状态 |
41
- | 🔐 **GUI 内 Google 登录** | `/agy auth` 打印授权 URL；设置 → Antigravity 页面提供二维码 + 授权码粘贴框 |
42
- | 🤝 **`agy_ask` 工具** | 任何 DSH 模型都可以把一次性任务委托给 Antigravity 模型（AskAntigravity 模式） |
43
- | ⌨️ **`/agy` 命令族** | `status` / `auth` / `auth-code` / `models` / `mode` / `effort` / `workspace` / `clear` / `doctor` / `help` |
44
- | 🖼 **图片多模态（v0.2）** | 图片落盘到本地媒体目录（TTL 清理），prompt 以绝对路径引用 + `--add-dir` 授权，agy 用自己的工具看图 |
45
- | 📎 **文件内联 + 结构化输出（v0.2）** | `agy_ask` 新增 `readPaths`（文本文件内联）与 `schema`（`--json-schema` 强约束答案） |
46
- | 🌉 **MCP 反向桥（v0.2 实验）** | `mcpBridge: true` 开启后 agy 可直接调 DSH 侧工具（回环 + token 守卫端点 + 零依赖 stdio MCP 服务器，`.mcp.json` 合并写入/禁用还原） |
47
- | 😴 **休眠安全** | 没装 agy？没登录？插件照常加载并告诉你怎么修 |
62
+ | 👥 **多账号池化轮换** | 支持主账号 + 多个备用账号；遇到 429 或配额耗尽自动平滑切换，模型族独立冷却 |
63
+ | 📊 **官方双 Bucket 配额监控** | 实时拉取官方端点，同时呈现 **5h 滚动额度** 与 **7d 周额度** 双进度条与倒计时，单模型明细可展开 |
64
+ | 🔑 **浏览器一键登录** | 点击添加账号自动唤起 Google 授权页，本地回环自动捕获，全程无需复制粘贴任何代码 |
65
+ | 🎨 **多主题高对比 UI** | 浅色、深色主题自适应变色，纯矢量 SVG 图标（无 Emoji），字迹清晰不发暗 |
66
+ | 🌐 **独立账号代理** | 每个账号支持独立配置 HTTP(S) 代理，隔离 IP 出口 |
67
+ | 🔌 **原生模型路由** | 在 DSH 模型配置中注册 `antigravity` 提供方，`/model` 选择器随心切换 Gemini / Claude / GPT-OSS |
68
+ | 🌊 **完整流式映射** | 文本、思考过程（thinking turn）与工具活动均无损映射到 DSH 原生流协议 |
69
+ | 🃏 **原生工具卡片** | agy 执行的终端命令（`run_command`）、文件修改（inline diff）均以 DSH 原生卡片渲染 |
70
+ | 🔗 **会话上下文保真** | DSH 会话与 agy 原生会话绑定（`--conversation`），由 agy 管理完整历史，每轮仅发送增量 |
71
+ | 📊 **精确 Token 统计** | 输入 / 输出 / 思考 / 缓存读取 token 完整计入 DSH 用量统计，全面适配 1M 上下文 |
72
+ | 🎛 **顶部控制台徽标** | 顶部栏 `AGY (n)` 徽标一键弹出控制台，直观查看账号池、配额进度条与代理状态 |
73
+ | 🖼 **图片多模态** | 支持多模态图片传入，自动落盘本地媒体目录并通过 `--add-dir` 安全授权给 agy 查看 |
74
+ | 🤝 **`agy_ask` 辅助工具** | 允许任意 DSH 模型把单次任务委托给 Antigravity 模型（AskAntigravity 协作模式） |
75
+ | ⌨️ **`/agy` 快捷命令族** | `status` / `auth` / `models` / `mode` / `effort` / `workspace` / `clear` / `doctor` / `help` |
76
+
77
+ ---
48
78
 
49
79
  ## 📋 前置要求
50
80
 
51
- 装插件**之前**，先把这三样备齐（缺一样插件也能装，但会休眠并提示你补什么）：
81
+ 在安装本插件前，请确保具备以下环境：
52
82
 
53
- | 前置 | 怎么装 / 怎么验证 |
83
+ | 前置项 | 说明 / 验证方式 |
54
84
  | --- | --- |
55
- | **1. DeepSeek Harness（DSH）** | 你正在用的就是；`dsh --version` 可验证 |
56
- | **2. Node.js ≥ 24** | DSH 本身就要求 Node 24+，通常已满足；`node --version` 验证 |
57
- | **3. Google Antigravity 的 `agy` CLI** | 按 [Google 官方安装指南](https://antigravity.google/docs/cli/install)装（Linux / macOS / Windows 都有），然后**在终端跑一次 `agy`**，按提示完成 Google 登录。`agy --version` 能出版本号、`agy models` 能列模型就算就绪 |
85
+ | **1. 系统网络代理** | **【必须开启】**（推荐开启 Clash / Surge / v2rayA 的 TUN 模式或设置 `HTTPS_PROXY` 环境变量，确保可流畅连接 Google 服务） |
86
+ | **2. DeepSeek Harness (DSH)** | 你正在使用的 DSH 客户端；`dsh --version` 可验证 |
87
+ | **3. Node.js ≥ 24** | DSH 依赖环境；`node --version` 验证 |
88
+ | **4. Google Antigravity `agy` CLI** | 按 [Google 官方安装文档](https://antigravity.google/docs/cli/install) 安装（支持 macOS / Linux / Windows）。`agy --version` 能输出版本号即表示安装成功 |
58
89
 
59
- > **什么是 agy？** Google Antigravity 的官方命令行智能体（类似 Claude Code / Gemini CLI）。本插件不替代它，而是驱动它——所以你需要一份有效的 **Antigravity 订阅**（免费额度也行）。
60
- >
61
- > 没登录也能先装：插件自带的 `/agy auth` 会给你授权 URL + 二维码，在 GUI 里完成登录。
90
+ > 💡 **提示**：即使你的 agy 尚未登录，也可以直接安装插件！在 DSH 界面顶部点击 `AGY` 徽标或进入「设置 → Antigravity」，点击「➕ 添加账号」即可直接在浏览器中完成登录。
62
91
 
63
- ## 🚀 快速开始
92
+ ---
93
+
94
+ ## 🚀 快速上手
64
95
 
65
96
  ```bash
66
- # 0. 确认前置要求满足（见上一节）：agy --version 有输出
97
+ # 0. 确保系统代理 / TUN 模式已开启（国内网络必需）：
98
+ export HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890
67
99
 
68
- # 1. 安装插件（npm 官方包，预构建产物，无需构建许可）：
100
+ # 1. 安装插件（npm 官方包，无需编译构建）：
69
101
  dsh plugin --profile web add dsh-agy-link
70
- # 升级（每次新版本发布后执行；镜像标签可能滞后，指定官方源最稳）：
71
- # dsh plugin --profile web add dsh-agy-link@latest --registry https://registry.npmjs.org
72
102
 
73
- # 2. 重启 DSH Web GUI，输入框执行：
74
- # /agy status ← 应显示 agy 版本号；没装好会告诉你缺什么
103
+ # 升级到最新版：
104
+ # dsh plugin --profile web add dsh-agy-link@latest --registry https://registry.npmjs.org
75
105
 
76
- # 3. 登录（一次性；终端里已经跑过 agy 登录过的可跳过）：
77
- # /agy auth ← 打开授权 URL，批准并复制授权码
78
- # /agy auth-code <授权码> ← 或直接用设置 → Antigravity 页面的二维码 + 粘贴框
106
+ # 2. 启动 DSH Web GUI，在输入框中检查状态：
107
+ # /agy status
79
108
 
80
- # 4. /model 选择器里选 antigravity 模型，开聊
81
- ```
109
+ # 3. 登录与添加账号：
110
+ # 方式 A：点击顶部导航栏的 "AGY (n)" 徽标，点击 "➕ 添加账号"，浏览器一键登录；
111
+ # 方式 B：输入框执行 /agy auth 为主账号发起登录。
82
112
 
83
- > 插件绝不读取/复制/移动 `~/.gemini/antigravity-cli/antigravity-oauth-token`；登录完全通过官方 CLI 自己的流程完成。
113
+ # 4. 在 /model 选择器中挑选 Antigravity 模型，立即开启对话！
114
+ ```
84
115
 
85
- > 🖥 **跨平台**：Linux / macOS / Windows 均受支持——bin 探测按平台查找 `agy`/`agy.exe`（PATH、`~/.local/bin`、`/usr/local/bin`、`/opt/homebrew/bin`、`%LOCALAPPDATA%\Programs`，npm `.cmd` shim 自动经 cmd.exe 安全引号包裹启动）；中断/超时杀树在 Windows 走 `taskkill /T /F`；CRLF 输出统一剥离；媒体目录与 MCP 桥路径全部 `fileURLToPath`/`join` 构造。
116
+ ---
86
117
 
87
- ## ⚙️ 配置
118
+ ## ⚙️ 配置说明
88
119
 
89
- 配置在 `agy-link` 插件条目里（`/plugin` 或 profile patch 层编辑），环境变量优先：
120
+ 插件配置可在 `/plugin`、设置面板或环境变量中灵活调整：
90
121
 
91
- | 键 | 环境变量 | 默认值 | 含义 |
122
+ | 键名 | 环境变量 | 默认值 | 作用说明 |
92
123
  | --- | --- | --- | --- |
93
- | enabled | `DSH_AGY_ENABLED` | `true` | 总开关 |
94
- | agyBin | `DSH_AGY_BIN` | 自动 | 显式 agy 路径 |
95
- | permissionMode | `DSH_AGY_MODE` | `skip` | `skip` / `plan` / `accept-edits`（见下） |
96
- | defaultModel | `DSH_AGY_DEFAULT_MODEL` | `(agy 默认)` | 模型 slug |
97
- | defaultEffort | `DSH_AGY_DEFAULT_EFFORT` | `(模型默认)` | `low` / `medium` / `high` |
98
- | timeoutMs | `DSH_AGY_TIMEOUT_MS` | `600000` | 单轮看门狗 |
99
- | extraArgs | `DSH_AGY_EXTRA_ARGS` | — | 附加 agy 参数（空格分隔） |
100
- | workspaceRoot | `DSH_AGY_WORKSPACE_ROOT` | 会话 cwd | agy 工作区；显式配置优先，未设置时自动使用 DSH 会话的 cwd |
101
-
102
- ### ⚠️ 权限模式——必读
103
-
104
- agy 有**自己的**工具循环，会自己做文件编辑和 shell 执行。桥接层映射为三种模式：
124
+ | `enabled` | `DSH_AGY_ENABLED` | `true` | 插件主开关 |
125
+ | `agyBin` | `DSH_AGY_BIN` | 自动探测 | 显式指定 `agy` 二进制路径 |
126
+ | `permissionMode` | `DSH_AGY_MODE` | `skip` | 权限模式：`skip`（免审批推荐）/ `plan`（只读）/ `accept-edits` |
127
+ | `defaultModel` | `DSH_AGY_DEFAULT_MODEL` | `(agy 默认)` | 默认模型 slug |
128
+ | `defaultEffort` | `DSH_AGY_DEFAULT_EFFORT` | `(模型默认)` | 思考预算：`low` / `medium` / `high` |
129
+ | `timeoutMs` | `DSH_AGY_TIMEOUT_MS` | `600000` | 单轮活跃看门狗超时（毫秒） |
130
+ | `workspaceRoot` | `DSH_AGY_WORKSPACE_ROOT` | 会话 cwd | agy 工作区根目录（默认跟随当前会话工作区） |
105
131
 
106
- - **plan** —— 只读，体验桥接的安全默认。
107
- - **accept-edits** —— agy 可以不经询问改文件。
108
- - **skip** —— `--dangerously-skip-permissions`：agy **所有**工具免审批。非交互 DSH 轮次需要它（或 plan），因为 agy 的权限提示会卡死 print 模式；但这意味着真实的无人值守 写/执行 权限。设置面板里这个按钮是红色的。
132
+ ---
109
133
 
110
- DSH 侧的工具与权限不受影响——这里只约束 agy 子进程在自己工作区能做什么。
134
+ ## 🧩 架构与工作原理
111
135
 
112
- ## 🧩 工作原理
136
+ 1. **短生命周期进程驱动**：每一轮 DSH 对话启动一个独立的官方 `agy -p --output-format stream-json` 进程，解析 NDJSON 事件流。
137
+ 2. **多账号沙箱机制**：除主账号沿用系统默认 Keychain / HOME 外，所有备用账号在插件私有目录下建立专属 HOME 隔离区，独立写入 agy 格式的标准 OAuth 凭证。
138
+ 3. **双 Bucket 官方配额汇总**：插件定时后台静默轮询官方 `v1internal:retrieveUserQuotaSummary`，精准掌控每个账号的 5h 滚动削峰水位与 7d 账号阶梯周额度。
139
+ 4. **会话级无缝故障转移**：当遭遇 HTTP 429、额度耗尽或凭证异常时，号池调度器自动标记当前账号家族进入冷却，并无缝将后续请求路由到池内下一个有效账号。
113
140
 
114
- 一次 DSH 模型调用 = 一个短生命周期 `agy -p --output-format stream-json` 进程。NDJSON 事件流被解析、归一化并映射为 DSH StreamChunk：文本 → text 块，工具活动 → 注记 reasoning 块（含失败注记），结果信封 → usage + finish。agy 的 print 模式**不输出思考文本**（只有 `thinking_tokens` 计数），因此每个思考轮次以 `[agy thinking turn · N thinking tokens]` 注记呈现，思考 token 也进入用量统计。会话 id 优先取自流本身，conversations 目录快照对比兜底。**不逆向数据库、不解码 protobuf、不碰 token 文件**——只启动官方未修改的 agy 二进制。
141
+ ---
115
142
 
116
- ## 📋 它做不到什么（诚实清单）
143
+ ## 🙏 参考与致谢
117
144
 
118
- - **图片不是真多模态**——agy 的 print 模式没有图片入参，插件走的是“落盘 + 路径引用”方案（v0.2 起）：图片写进本地媒体目录，prompt 里给绝对路径，agy 用它自己的看图工具查看。能用，但和原生多模态不同。
119
- - **agy 的文件编辑不经过 DSH 审批**——它直接落盘，DSH 的 inline diff 审查不介入（想要只读就 `/agy mode plan`）。
120
- - **DSH 工具默认不暴露给 agy**——agy 跑自己的封闭工具循环；v0.2 的 MCP 反向桥（实验性，`mcpBridge: true`）可以打通，但有递归/扇出成本。
121
- - **结构化输出只在 `agy_ask` 里**——`schema` 参数走 `--json-schema`；DSH 原生工具调用生成还没接（上游没有对应字段）。
145
+ - [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) — Antigravity 公开 OAuth 客户端与回环回调登录范式
146
+ - [opencode-antigravity-auth](https://github.com/NoeFabris/opencode-antigravity-auth) — opencode 平台的多账号实践
147
+ - [OmniRoute](https://github.com/diegosouzapw/OmniRoute) — Antigravity 端点分发与配额语义
148
+ - [pi-mono](https://github.com/badlogic/pi-mono) — Antigravity 轮换与桥接设计参考
122
149
 
123
- 完整清单见 [docs/KNOWN-GAPS.md](docs/KNOWN-GAPS.md)。
150
+ ---
124
151
 
125
- ## ⚠️ 免责与风险提示
152
+ ## ⚠️ 免责声明
126
153
 
127
- 本插件只启动**官方未修改**的 `agy` 二进制并消费其公开 print 输出，不解码内部数据库、不触碰 OAuth token。自动化订阅 CLI 仍可能与提供方服务条款冲突（Google Antigravity ToS §6 语境）；风险自负，被要求停止时请停止。
154
+ 本插件仅通过调用用户本地官方安装的未修改 `agy` CLI 进程进行交互。使用本插件需遵循 Google Antigravity 服务条款。
128
155
 
129
156
  ## 许可证
130
157
 
131
- MIT
158
+ MIT License.
132
159
 
133
160
  ---
134
161
 
135
162
  # English
136
163
 
137
- > Known online as **小斯syzs** — Bilibili [@小斯syzs](https://space.bilibili.com/390211071) · Douyin · Xiaohongshu · Kuaishou (same handle on every platform).
164
+ > Known online as **小斯syzs** — Bilibili [@小斯syzs](https://space.bilibili.com/390211071) · Douyin · Xiaohongshu · Kuaishou (same handle across all platforms).
138
165
 
139
- Bring **Google Antigravity models into DeepSeek Harness (DSH)** — chat, thinking, tool activity, and token usage from your Antigravity subscription, driven by the official `agy` CLI.
166
+ Bring **Google Antigravity models into DeepSeek Harness (DSH)** — featuring **Multi-Account Pooling & Automatic Rotation**, **Official Dual-Bucket Quota Tracking (5h Rolling + 7d Weekly)**, **Zero-Paste In-GUI OAuth Login**, and **Theme-Adaptive High-Contrast UI**, powered by the official unmodified `agy` CLI.
140
167
 
141
- **How it works**: pick an Antigravity model in the `/model` picker; for every turn the plugin spawns a short-lived, official `agy` process in your workspace (`agy -p --output-format stream-json`), parses its NDJSON event stream, and maps text, thinking, and tool activity back into DSH chunk by chunk. Multi-turn rides a binding between the DSH session and a native agy conversation (`--conversation`) — agy keeps its own history, so only the latest message is sent each turn. **The plugin only ever spawns the official, unmodified agy binary**: no database reverse-engineering, no protobuf decoding, no touching your OAuth token.
142
-
143
- ## ✨ What you get
144
-
145
- | Capability | Description |
146
- | ---- | ---- |
147
- | 🔌 **A model route, not a proxy** | Registers the `antigravity` provider in DSH's model config; pick any Antigravity model (Gemini / Claude / GPT-OSS) from the `/model` picker |
148
- | 🌊 **Full streaming** | Text, thinking (reasoning), and token usage mapped onto DSH's native chunk protocol |
149
- | 🃏 **Native tool cards (v0.3)** | agy's tool activity renders with DSH's own tool-card UI — terminal cards for `run_command`, inline diffs for file writes — via the internal `agy_tool` mirror riding the real agent loop |
150
- | 🔗 **Session continuity** | Each DSH session binds to a native agy conversation (`--conversation`); multi-turn context rides agy history instead of re-sending everything |
151
- | 📊 **Token usage** | Input/output/thinking/cache tokens surface in DSH usage accounting |
152
- | ⚙️ **Settings status** | DSH Settings → Antigravity page shows agy connection/login/workspace/bindings/last-run state |
153
- | 🔐 **In-GUI Google login** | `/agy auth` prints the consent URL; Settings → Antigravity adds a QR code and a paste box for the authorization code |
154
- | 🤝 **`agy_ask` tool** | Let any DSH model delegate a one-shot task to an Antigravity model (the AskAntigravity pattern) |
155
- | ⌨️ **`/agy` commands** | `status`, `auth`, `auth-code`, `models`, `mode`, `effort`, `workspace`, `clear`, `doctor`, `help` |
156
- | 😴 **Dormant-safe** | No agy binary? Not signed in? The plugin loads anyway and tells you what to fix |
157
- | 🖼 **Image multimodal (v0.2)** | image attachments staged to a TTL-swept local dir, referenced by absolute path with `--add-dir`; agy views them with its own tools |
158
- | 📎 **File inlining + structured output (v0.2)** | `agy_ask` gains `readPaths` (inline text files) and `schema` (enforced via `--json-schema`) |
159
- | 🌉 **MCP reverse bridge (v0.2, experimental)** | with `mcpBridge: true`, agy calls DSH-side tools directly (loopback token-guarded endpoint + zero-dep stdio MCP server merged into `.mcp.json`, restored on disable) |
168
+ ---
160
169
 
161
- ## 📋 Prerequisites
170
+ > 🚨 **【Important: System Proxy / VPN / TUN Mode Required in Restricted Regions】**
171
+ >
172
+ > Google Antigravity services and Google OAuth require access to Google servers (`oauth2.googleapis.com`, `cloudcode-pa.googleapis.com`, etc.).
173
+ >
174
+ > 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.
175
+ > 2. **Terminal Proxy Export**: If your terminal does not inherit proxy automatically, export the environment variables before starting DSH:
176
+ > ```bash
177
+ > 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
178
+ > ```
179
+ > 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`).
162
180
 
163
- Before installing, have these three ready (the plugin installs fine without them, but stays dormant and tells you what to fix):
181
+ ---
164
182
 
165
- | Requirement | How to install / verify |
166
- | --- | --- |
167
- | **1. DeepSeek Harness (DSH)** | You are using it; `dsh --version` verifies |
168
- | **2. Node.js ≥ 24** | DSH already requires Node 24+; `node --version` verifies |
169
- | **3. Google Antigravity's `agy` CLI** | Follow [Google's official install guide](https://antigravity.google/docs/cli/install) (Linux / macOS / Windows), then **run `agy` once in a terminal** and complete the Google login. `agy --version` printing a version and `agy models` listing models means you are ready |
183
+ ## 🌟 Core Feature: Multi-Account Pool & Smart Rotation
170
184
 
171
- > **What is agy?** Google Antigravity's official command-line agent (think Claude Code / Gemini CLI). This plugin does not replace it — it drives it, so you need an active **Antigravity subscription** (the free tier works).
172
- >
173
- > Not logged in yet? Install anyway: the built-in `/agy auth` gives you a consent URL + QR code to finish login inside the GUI.
185
+ Have multiple Google Antigravity / Gemini accounts? **dsh-agy-link makes multi-account orchestration seamless and automated**:
174
186
 
175
- ## 🚀 Quick start
187
+ - 👥 **Multi-Account Pooling**: Manage unlimited Google accounts (Primary + Secondary pool) with fully isolated HOME sandbox environments and credentials.
188
+ - 🔄 **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!
189
+ - 📊 **Official Dual-Bucket Quota Tracking**: Direct integration with Antigravity's official `v1internal:retrieveUserQuotaSummary` endpoint, providing real-time visibility for both **5-Hour Rolling Limit** and **7-Day Weekly Limit** with live countdowns.
190
+ - 🔑 **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**.
191
+ - 🎨 **Theme-Adaptive High-Contrast UI**: Seamlessly adapts to Light and Dark DSH themes with crystal clear typography and crisp contrast.
192
+ - 🌐 **Per-Account Proxy**: Configure dedicated HTTP(S) / SOCKS proxy for each individual account to isolate IP addresses.
193
+ - ⚡ **Family-Scoped Cooldowns**: Gemini, Claude, and GPT-OSS rate limits are calculated independently, preventing one exhausted model from blocking others.
176
194
 
177
- ```bash
178
- # 0. Confirm the prerequisites (previous section): agy --version prints something
179
-
180
- # 1. Install (npm, prebuilt — no build approval needed):
181
- dsh plugin --profile web add dsh-agy-link
182
- # Upgrade (run after every release; mirror tags can lag, so pin the official registry):
183
- # dsh plugin --profile web add dsh-agy-link@latest --registry https://registry.npmjs.org
195
+ ---
184
196
 
185
- # 2. Restart the DSH Web GUI, then in the composer:
186
- # /agy status <- should show the agy version; tells you what is missing otherwise
197
+ ## ✨ Features Overview
187
198
 
188
- # 3. Login (one time; skip if you already ran agy in a terminal):
189
- # /agy auth <- open the consent URL, approve, copy the code
190
- # /agy auth-code <code> <- or use Settings -> Antigravity (QR + paste box)
199
+ | Feature | Description |
200
+ | --- | --- |
201
+ | 👥 **Multi-Account Pool** | Primary + unlimited spare accounts with automatic Sequential Drain rotation upon rate limits |
202
+ | 📊 **Dual-Bucket Quota HUD** | Real-time dual progress bars for both **5h rolling** and **7d weekly** quota limits with exact reset countdowns |
203
+ | 🔑 **Zero-Paste Browser Login** | Automatic browser-based Google OAuth login with loopback callback handler |
204
+ | 🎨 **Theme-Adaptive UI** | Dynamic light/dark theme switching, pure SVG vector marks (no emojis), high contrast |
205
+ | 🌐 **Per-Account Proxy** | Dedicated HTTP(S) proxy per account slot |
206
+ | 🔌 **Native Model Routing** | Registers `antigravity` provider in DSH; choose Gemini / Claude / GPT-OSS in `/model` picker |
207
+ | 🌊 **Full Streaming Protocol** | Native streaming for text, thinking turn annotations, and tool calls |
208
+ | 🃏 **Native Tool UI Cards** | Command runs and inline diffs render as clean, native DSH tool cards |
209
+ | 🔗 **Session Continuity** | Binds DSH sessions to native agy conversations (`--conversation`) for zero-redundancy context |
210
+ | 📊 **Accurate Token Metering** | Input, output, thinking, and cacheRead tokens are fully reported to DSH with 1M context support |
211
+ | 🎛 **Top Header Console Badge** | Click the `AGY (n)` badge in the header to instantly open the management console |
212
+ | 🖼 **Multimodal Images** | Stages images to local storage and passes safe absolute paths via `--add-dir` |
213
+ | 🤝 **`agy_ask` Delegation** | Allows other DSH models to delegate subtasks to Antigravity models |
214
+ | ⌨️ **`/agy` Commands** | Full command suite: `status`, `auth`, `models`, `mode`, `effort`, `workspace`, `clear`, `doctor`, `help` |
191
215
 
192
- # 4. Pick an antigravity model in /model and chat
193
- ```
216
+ ---
194
217
 
195
- > The plugin never reads, copies, or moves `~/.gemini/antigravity-cli/antigravity-oauth-token`; login is driven entirely through the official CLI's own flow.
218
+ ## 📋 Prerequisites
196
219
 
197
- > 🖥 **Cross-platform**: Linux / macOS / Windows — platform-aware binary discovery (`agy` / `agy.exe` across PATH, `~/.local/bin`, `/usr/local/bin`, `/opt/homebrew/bin`, `%LOCALAPPDATA%\Programs`; npm `.cmd` shims spawn through cmd.exe with safe quoting), tree-kill via `taskkill /T /F` on Windows, CRLF output normalized, media and bridge paths built with `fileURLToPath`/`join`.
220
+ | Requirement | Details |
221
+ | --- | --- |
222
+ | **1. System Proxy / VPN** | **【Required in restricted regions】** (TUN mode or `HTTPS_PROXY` environment variable to ensure Google endpoints are reachable) |
223
+ | **2. DeepSeek Harness (DSH)** | Your current DSH environment (`dsh --version`) |
224
+ | **3. Node.js ≥ 24** | Required runtime (`node --version`) |
225
+ | **4. Google Antigravity `agy` CLI** | Installed per [Google's official guide](https://antigravity.google/docs/cli/install). Verified with `agy --version` |
198
226
 
199
- ## ⚙️ Configuration
227
+ ---
200
228
 
201
- Config lives in the `agy-link` plugin entry (edit via `/plugin` or the profile patch layer). Environment variables override the file:
229
+ ## 🚀 Quick Start
202
230
 
203
- | Key | Env | Default | Meaning |
204
- | --- | --- | --- | --- |
205
- | enabled | `DSH_AGY_ENABLED` | `true` | master switch |
206
- | agyBin | `DSH_AGY_BIN` | auto | explicit agy binary path |
207
- | permissionMode | `DSH_AGY_MODE` | `skip` | `skip` / `plan` / `accept-edits` (below) |
208
- | defaultModel | `DSH_AGY_DEFAULT_MODEL` | `(agy default)` | model slug |
209
- | defaultEffort | `DSH_AGY_DEFAULT_EFFORT` | `(model default)` | `low` / `medium` / `high` |
210
- | timeoutMs | `DSH_AGY_TIMEOUT_MS` | `600000` | sliding activity watchdog (inactivity timeout; active long tasks run indefinitely) |
211
- | extraArgs | `DSH_AGY_EXTRA_ARGS` | — | extra agy flags, space-separated |
212
- | workspaceRoot | `DSH_AGY_WORKSPACE_ROOT` | session cwd | agy workspace; explicit config wins, otherwise the DSH session's cwd is used |
231
+ ```bash
232
+ # 0. Ensure System Proxy / TUN mode is active (required for Google connectivity):
233
+ export HTTPS_PROXY=http://127.0.0.1:7890 HTTP_PROXY=http://127.0.0.1:7890
213
234
 
214
- ### ⚠️ Permission modes — read this
235
+ # 1. Install plugin:
236
+ dsh plugin --profile web add dsh-agy-link
215
237
 
216
- agy runs its **own** tool loop with its own file edits and shell commands. The bridge maps that to one of three modes:
238
+ # Upgrade to latest:
239
+ # dsh plugin --profile web add dsh-agy-link@latest --registry https://registry.npmjs.org
217
240
 
218
- - **plan** — read-only; the safe default for trying the bridge.
219
- - **accept-edits** — agy may edit files without asking.
220
- - **skip** — `--dangerously-skip-permissions`: agy runs **every** tool without approval. Non-interactive DSH turns need this (or plan) because agy permission prompts hang print mode, but it means real unattended write/exec access. The settings panel shows this button in red.
241
+ # 2. Start DSH Web GUI, test status:
242
+ # /agy status
221
243
 
222
- DSH-side tools and permissions are unaffected — this only governs what the spawned agy process may do in its workspace.
244
+ # 3. Add accounts:
245
+ # Click "AGY (n)" badge in the top header, click "➕ Add Account" and complete browser login.
223
246
 
224
- ## 🧩 How it works
247
+ # 4. Select an Antigravity model in /model and start chatting!
248
+ ```
225
249
 
226
- One DSH turn = one short-lived `agy -p --output-format stream-json` process. The NDJSON event stream is parsed, normalized, and recorded. Spans of that recording are mapped to DSH StreamChunks — thinking → reasoning blocks, text → text blocks, result envelope → usage + finish — and each **completed agy tool step cuts the span** with a `tool-calls` finish. The tool-call block addresses `run_code` — the only tool DSH's dispatch policy lets a model call directly — wrapping a generated one-line program that invokes the internal `agy_tool` mirror; the inner dispatch instantly replays the recorded output, writes real `tool/call` + `tool/result` session events, and re-calls the provider to continue the run. Tool activity therefore renders with DSH's **native tool-card UI** (terminal cards, diffs, read/search icons) instead of text annotations, and cards read agy's PascalCase arg keys (`CommandLine`, `AbsolutePath`, …). Conversation ids come from the stream itself, with a conversations-directory snapshot diff as fallback. **No reverse-engineered database scraping, no protobuf decoding, no token-file access** — only the official unmodified agy binary is spawned.
250
+ ---
227
251
 
228
- ## 📋 What it cannot do (honest list)
252
+ ## ⚙️ Configuration
229
253
 
230
- - **Images are not true multimodal** — agy print mode has no image input flag; since v0.2 the bridge stages images to a local media directory and references them by absolute path, with agy viewing them via its own tools. Workable, but not native multimodality.
231
- - **agy's file edits bypass DSH review** — they land directly on disk; DSH's inline diff review does not engage (`/agy mode plan` for read-only).
232
- - **DSH tools are not exposed to agy by default** — agy runs its own closed tool loop; the v0.2 MCP reverse bridge (experimental, `mcpBridge: true`) can bridge that, at a recursion/fan-out cost.
233
- - **Structured output only inside `agy_ask`** — the `schema` parameter rides `--json-schema`; DSH-native tool-call generation is not wired (no upstream field to map onto).
254
+ | Key | Environment Variable | Default | Description |
255
+ | --- | --- | --- | --- |
256
+ | `enabled` | `DSH_AGY_ENABLED` | `true` | Master switch |
257
+ | `agyBin` | `DSH_AGY_BIN` | auto-detected | Path to `agy` binary |
258
+ | `permissionMode` | `DSH_AGY_MODE` | `skip` | `skip` (recommended) / `plan` (read-only) / `accept-edits` |
259
+ | `defaultModel` | `DSH_AGY_DEFAULT_MODEL` | `(agy default)` | Default model slug |
260
+ | `defaultEffort` | `DSH_AGY_DEFAULT_EFFORT` | `(model default)` | Thinking budget: `low` / `medium` / `high` |
261
+ | `timeoutMs` | `DSH_AGY_TIMEOUT_MS` | `600000` | Activity watchdog timeout in milliseconds |
262
+ | `workspaceRoot` | `DSH_AGY_WORKSPACE_ROOT` | session cwd | Working directory root |
234
263
 
235
- Full list in [docs/KNOWN-GAPS.md](docs/KNOWN-GAPS.md).
264
+ ---
236
265
 
237
- ## ⚠️ Disclaimer & risk note
266
+ ## ⚠️ Disclaimer
238
267
 
239
- This plugin spawns the **official, unmodified** `agy` binary and consumes its public print-mode output. It does not decode internal databases or touch OAuth tokens. Automating a subscription CLI may still conflict with the provider's terms of service (Google Antigravity ToS §6 context); use it at your own risk, and stop if asked to.
268
+ 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.
240
269
 
241
270
  ## License
242
271
 
243
- MIT
272
+ MIT License.