chaos-03x/dsh-agy

dsh-agy

CI
npm version

为 DeepSeek Harness 提供 Google Antigravity (agy) 访问：
OAuth 认证、支持 429 自动轮换的多账号池、设备
指纹，以及 CLI 和 Web 两种管理方式。

中文文档：docs/README_zh.md

功能特性

- OAuth 登录：通过浏览器 OAuth 回调一键登录，支持无头
粘贴 URL 模式以及远程粘贴凭据 blob 通道。
- 两种管理界面：Web 和 CLI，任选其一即可，核心功能
相同。
- 多账号池：加密账号存储、基于使用情况的账号
选择（按家族划分的配额、与 OMP 对齐的排序）、达到
速率限制时自动轮换、按账号冷却至真实重置时间、按账号设置设备
指纹。
- 配额仪表盘：仅在 DSH Web 运行时可用；在你的 dsh web 地址后追加 /agy：
登录、账号管理、按模型的配额条、模型
测试、凭据导出/导入、指纹管理。
- CLI：dsh-agy login|status|import|verify|logout 可独立运行，无论
是否使用 harness。

截图

DSH Web 中的 /agy 仪表盘——账号卡片、按模型的配额条，以及
一键模型测试：

dsh-agy dashboard

快速开始

路径 A：DSH Web GUI 用户（推荐——100% Web UI，零 CLI 命令）

适用于使用 DeepSeek Harness 浏览器工作区 / Web GUI 的用户：

1. Install plugin into DSH web profile (via dsh CLI, or pnpx/npx if dsh is not in PATH)
dsh plugin --profile web add dsh-agy
or: npx @deepseek-ai/dsh plugin --profile web add dsh-agy

2. Launch DSH Web
dsh web

3. Open dashboard at http://127.0.0.1:3080/agy
Click "Login with Google", complete OAuth authorization, and start using the agy provider

打开 Settings → Plugins → Antigravity → Open Antigravity dashboard；该按钮会在新标签页中打开 /agy。

路径 B：无头 / 仅终端（独立 CLI）

适用于 Linux VPS、SSH 远程服务器或无头 CI 环境：

Run directly without global install (npx / pnpx)
npx dsh-agy login
npx dsh-agy status

Or install globally
npm install -g dsh-agy
dsh-agy login          # interactive OAuth (browser, --headless paste, or --blob)
dsh-agy status         # list accounts + quota summary
dsh-agy verify         # refresh + health check
dsh-agy health         # batch health check (optionally on an interval)
dsh-agy import   # import agy auth.json or credential blob (--blob)
dsh-agy logout         # remove account

CLI 参考

| 命令 | 选项 | 描述 |
|---|---|---|
| dsh-agy login | --headless — 打印认证 URL 并等待粘贴重定向 URL--blob — 打印粘贴凭证 blob 而不是存储账户--port  — 回环回调端口（默认 51121）--project  — 将登录绑定到特定项目--timeout  — 回调超时（默认 300000） | 交互式 Google OAuth |
| dsh-agy status | — | 列出账户 + 每个模型的配额摘要 |
| dsh-agy import  | --blob — 粘贴的值是凭证 blob--email  — 设置账户邮箱（跳过 userinfo 验证）--overwrite — 替换具有相同邮箱的现有账户 | 导入 agy auth.json 文件或凭证 blob（多个文件 / 多行粘贴 = 批量导入） |
| dsh-agy export | --index  — 按索引导出一个账户（默认：全部）--out  — 为每个账户写入一个 dsh-agy-.blob（默认：打印到 stdout，每行一个 blob） | 将账户凭证导出为粘贴 blob |
| dsh-agy verify | --index  — 按索引验证一个账户（默认：全部） | 刷新 + 健康检查 |
| dsh-agy health | --index  — 仅检查这些账户（默认：全部已启用）--interval  — 按间隔重复而不是仅一次 | 批量健康检查（刷新 + userinfo），重新启用凭证再次可用的账户 |
| dsh-agy logout | --index  — 账户索引（默认：活动）--email  — 账户邮箱 | 移除账户 |

每账户代理

每个账户可以有自己的代理；凭证静态加密，并以 protocol//host:port 形式掩码显示。

dsh-agy login --proxy socks5://user:pass@host:1080
dsh-agy import --proxy  file.json
dsh-agy proxy set --index 0 --proxy    # 设置 / 更新
dsh-agy proxy clear --index 0               # 清除（回退到环境变量）
dsh-agy proxy test --index 0                # TCP 2s 快速失败探测
dsh-agy proxy list                          # 掩码列表
dsh-agy status                              # 显示代理列（掩码 host:port）

回退：没有每账户代理时，请求使用 EnvHttpProxyAgent（HTTP_PROXY/HTTPS_PROXY，并遵循 NO_PROXY）。每账户代理忽略 NO_PROXY，采用故障关闭（不可达代理会跳过该账户且不进入冷却并清除亲和性），回环目标（localhost/127.0.0.1/::1）始终强制直连。

Web 仪表盘（/agy）：每个账户卡片显示内联代理行 [input] [Save][Clear][Test]，带有掩码的 host:port；通过 POST /agy/api/proxy 写入，通过 POST /agy/api/proxy/test 探测。

路径 C：本地开发与链接

git clone https://github.com/chaos-03x/dsh-agy.git
cd dsh-agy && pnpm install && pnpm run build
dsh plugin --profile web link .

需要 Node >= 22。

卸载

1. 从配置文件中移除 DSH 插件
dsh plugin --profile web remove dsh-agy

2. 卸载 CLI
npm uninstall -g dsh-agy
3. 可选：删除本地账户数据（账户 + 主密钥 + 指纹覆盖）
dsh-agy logout              # 先移除账户（或跳过）
rm -f ~/.dsh/agy-accounts.json
仅从 ~/.dsh/.credentials.yaml 中移除 AGY_MASTER_KEY 行——保留其他密钥！
rm -f ~/.dsh/agy-fingerprint-data.json   # 仅当你创建了覆盖时

4. 可选：撤销 Google 侧的授权
Google 账户安全 → 第三方访问 → 撤销 “Antigravity”

删除本地文件不会撤销 Google 侧的令牌；刷新令牌会一直有效，
直到过期，或者你在 Google 账户安全设置中将其撤销。

其他你可能关心的事项

轮换机制

用量感知选择：当有多个账户可用时，请求会根据所请求模型的后端计数器族
（gemini- → Google，claude- → Anthropic，gpt-* → OpenAI）对它们进行排名：
配额即将重置且仍有剩余额度的账户会被优先使用（“不用就浪费”），
接近耗尽的族会被避开，而已耗尽的族会阻止该账户，直到真正的重置时间。

429（请求过多）响应：

| 类别 | 行为 |
|---|---|
| soft_rate_limit（Retry-After  | 在 harness 内进行后台批量健康探测（按配置的间隔执行 refresh + userinfo）；默认关闭。 |
| AGY_CLIENT_ID / AGY_CLIENT_SECRET | 自带 OAuth 应用的逃生通道：覆盖内嵌的公共 Antigravity 客户端凭据。 |

关于缓存命中：为什么不像 DeepSeek V4 那样达到 99%？

归根结底：缓存命中策略由模型提供方的缓存机制决定（对我们来说，就是 Antigravity 的）；agy 的机制与 DeepSeek 有两点不同，因此其命中率自然会比 DeepSeek 低一档。

第一，进入门槛。 DeepSeek 的缓存默认开启且没有门槛——它的第一个请求就已经命中之前缓存的系统提示词。agy 的 Gemini 分层模型只有在请求前缀
大约达到 16k tokens，而 DSH 默认的裸系统提示词只有
大约 13k —— 低于这条线。所以每个新对话的前 1-2 个请求
都是 0%，直到累积的消息超过 16k。

第二，缓存更新有多快。 DeepSeek 在每个请求结束时
刷新其缓存 —— 每轮只有最新的消息未命中，从而给出
接近 100% 的命中率。agy 的缓存更新滞后：本轮的
新增内容在下一轮不会被命中 —— 它们大约在两轮之后才进入
缓存，而在此期间对相同内容的请求
都算作未命中。每一轮大约浪费其新增内容的 1.5-2 倍；
随着上下文增长，长对话的命中率持续上升，受限于
模型的上下文窗口。

实用建议

- 不要指望 agy 达到 99%：这一差距来自上游机制，没有
优化空间。
- 如果你有某种奇怪的数字执念，就往
System Prompt 里塞一些自定义内容（MCP / 工具定义 / 角色扮演……）。

存储与密钥

- 账户：~/.dsh/agy-accounts.json —— AES-256-GCM 加密；主密钥位于
~/.dsh/.credentials.yaml（AGY_MASTER_KEY，0600）。$DSH_HOME 可重定位这两者。
- 指纹池（版本字符串、SDK 客户端）可通过
~/.dsh/agy-fingerprint-data.json 由用户覆盖 —— 无需发布代码即可保持其最新。

⚠️ 免责声明

本插件使用随 Antigravity 桌面产品一同发布的 Google 消费者 OAuth 客户端进行身份验证，
并在该产品之外使用 Antigravity Cloud Code API。这可能
违反 Antigravity 的服务条款。使用风险自负 ——
账户可能被限流、节流或封禁。多账户轮换、设备
指纹识别和签名绕过哨兵默认启用，其设计
目的是绕过上游限制；你需对自己的使用方式
以及任何账户后果负责。

致谢

本项目参考了以下 MIT 许可来源的逻辑和数据：

| 来源 | 内容 |
|---|---|
| opencode-antigravity-auth（已归档） | OAuth 流程形态、账户存储 schema 与版本化迁移、429/退避概念、指纹设计 |
| antigravity-claude-proxy PR #170 | 设备指纹生成（经由 opencode-antigravity-auth） |
| OmniRoute | 传输格式（信封、标头、SSE）、端点顺序、agy 令牌文件解析、粘贴凭据 blob 编解码器、thoughtSignature 重放、429 分类引擎 |
| DeepSeek Harness | 插件外壳、LlmAdapter 接缝、DSH 约定 |

开发
sh
pnpm install
pnpm test                      # vitest, fixture-driven, no network
pnpm run record:fixtures       # re-record real-API fixtures (needs a real account)
pnpm run e2e                   # real-account end-to-end (needs AGY_REFRESH_TOKEN)
pnpm run debug:request         # 端点/请求头二分探测
pnpm run verify:tools          # 实时两轮工具签名检查
npm pack --dry-run             # 验证可发布产物