dsh-agy-ui

dsh-agy-ui

专为 DeepSeek Harness (DSH) 中 dsh-agy 打造的非侵入式 UI 伴生增强插件
模型列表智能净化 · 顶栏实时配额徽章 · 毛玻璃双周期额度浮层 · 移动端抽屉自适应

🌐 语言 / Language: 简体中文 · English

---

💡 为什么需要 dsh-agy-ui？

在 DeepSeek Harness (DSH) 生态中，dsh-agy 凭借直连 Google 内部核心 API（POST /v1internal:streamGenerateContent）以及 DSH 原生 Tool 执行能力，提供了轻量极速的底层调用通道。

但原生使用中存在几个直接影响日常体验的痛点：

dsh-agy-ui 定位为一个纯表层体验伴生增强插件：底层网络通信、流式解析与 Tool 调度 100% 交由 dsh-agy，本插件专注于提供优雅直观的前端交互。

---

🏛️ 插件定位与系统架构

dsh-agy-ui 遵循 Cordis 插件规范设计，在内存中以非侵入方式包裹 LLM 适配器，并在 Web 端通过 DSH 原生 Slots 插槽注入交互组件：

                    ┌────────────────────────────────────────────────────────┐
                    │               DeepSeek Harness (DSH Web)               │
                    └───────────┬────────────────────────────────┬───────────┘
                                │                                │
                        (Web Slots 注入)                 (Cordis 插件机制)
                                │                                │
                                ▼                                ▼
                    ┌────────────────────────┐      ┌─────────────────────────┐
                    │      dsh-agy-ui        │◄─────┤   适配器列表动态拦截包装  │
                    │   (顶栏徽章 + 浮层弹窗)  │      │ (净化/折叠/品牌化/排序)   │
                    └───────────┬────────────┘      └────────────┬────────────┘
                                │ RPC 管理面读取                  │ 原生模型委托
                                ▼                                ▼
                    ┌────────────────────────┐      ┌─────────────────────────┐
                    │  dsh-agy 管理面 RPC    │      │   dsh-agy 核心调用层    │
                    │ (/api/agy · account.*) │      │ (直连 Google 内部 API)  │
                    └───────────┬────────────┘      └─────────────────────────┘
                                │ account.limits 返回分组窗口
                                │ （5h / daily / weekly / monthly）
                                │
                    ┌───────────┴────────────┐
                    │      dsh-agy-link      │
                    │ (/plugins/agy-link/..) │
                    │   兼容回退通道（可选）  │
                    └────────────────────────┘

---

✨ 核心特性详解

1. 🧼 模型菜单智能净化与统一排版

▲ 净化后的 Antigravity (agy) 原生模型选择列表效果预览

• 内部幽灵模型过滤：自动过滤 ^chat_\d+$、^tab_ 等非对话专用的内部调试与代码补全模型。
• 思考档位规范折叠：将散落的 -low、-medium、-high 变体收敛至根模型，注入标准的 thinkingEfforts 声明，让 DSH 原生思考选择器生效。
• 品牌名称优雅规范：将 Tiered 系列模型（如 gemini-3.8-flash-tiered）自动格式化为标准展示名（如 Gemini 3.8 Flash）。
• 科学降序排列：Gemini Flash 系列（3.8 > 3.7 > 3.6 > 3.5 > 3）→ Gemini Pro（3.1 Pro）→ 2.5 系列 → Claude 4.6 → GPT-OSS。

2. ⚡ 顶栏实时配额徽章 (Header Badge)

▲ 挂载于会话顶栏的实时配额胶囊徽章（静态呼吸健康指示灯 + 动态百分比）

• 非侵入插槽注入：挂载于 conversation.session.header.actions 插槽，独立 ID agy-ui-quota-badge。
• 一目了然的配额显示：常驻显示当前活跃账号的 最紧的那一档额度（如 AGY · 55%），取自 dsh-agy 的分组窗口（account.limits），而非已被上游移除的逐模型额度。
• 按「离耗尽还有多远」取数，而不是取最小值：5 小时与周额度各自对齐自己的耗尽阈值（15% / 1%，与 dsh-agy 的轮换判定一致），所以一周快用尽时徽章会切到周额度并标注（如 AGY · 周额度 1%），而一周还剩一半时不会把 5 小时的数字拉低。浮层里的 daily / monthly 只展示、不参与判定，因为账号池不会因它们而停用。
• 动静相宜的呼吸微动效：静态健康圆点平时稳定常亮（绿=正常、黄=冷却中/限流、灰=无可用账号），仅在后台数据同步或手动刷新时展示 1.2 秒平滑呼吸光效。
• 120 秒全局频率锁：2 分钟定时轮询 + 120 秒标签页/窗口聚焦节流锁，彻底杜绝切换标签页时高频击穿后台触发 Google 429 限流。

3. 🪟 轻量化毛玻璃配额透视弹窗 (Popover)

▲ 点击或悬停徽章呼出的分组多窗口（5小时 / 日 / 周 / 月）配额监控面板

• 悬停即现，支持钉选 (Pin)：鼠标移入徽章毫秒级呼出，居中对齐徽章下方；点击徽章即可常驻固定。
• 按上游分组渲染的全窗口配额条：直接透传 dsh-agy 的配额分组（当前为 Gemini Models 与 Claude and GPT models），分组内每个窗口独立成行，行标签由上游的 window 字段决定：
  • 5 小时周期（5h） / 日额度（daily） / 周额度（weekly） / 月额度（monthly）；上游未来新增的窗口标识会原样展示，不会被丢弃。
  • 未返回的窗口显示为 — 与灰色空条，而不是 0% —— “未知”和“已用尽”是相反的事实。
• 账号健康与快捷入口：展示当前激活账号脱敏标识及健康状态（含 verification-required 待验证态及其申诉链接），内置手动刷新按钮；dsh-agy ≥ 0.3.0 下顶栏提示改为「设置 → Antigravity」。

4. 📱 移动端抽屉式卡片自适应 (Mobile Drawer)

• 采用响应式设计，当屏幕宽度 $\le$ 640px 时，弹窗自动转为 iOS/Android 风格的底部抽屉（Bottom Sheet），并配有半透明遮罩与触控关闭优化。

5. 🛡️ 命名空间隔离与多插件共存

• 所有 CSS 均置于 agy-ui-* 独立前缀命名空间，杜绝全局样式污染。
• 完整兼容并可与 dsh-agy-link 无缝共存：额度数据遵循 dsh-agy 分组窗口 → dsh-agy-link 家族额度 → 旧版逐模型额度 的回退顺序。

6. 🔌 数据拉取通道（dsh-agy ≥ 0.3.0 适配）

dsh-agy 0.3.0 起把管理面从独立的 /agy 仪表盘迁到了 DSH 自有 RPC 通道：宿主注册 /api/agy，浏览器侧通过 connection.rpc.call('/api', 'agy', { method, payload }) 调用，仅 /agy/oauth-callback 仍是普通 HTTP 路由（Google 会用 GET 跳转过去）。旧的 /agy/api/accounts 已被删除。同时 5 小时 / 周额度的数据源由 fetchAvailableModels 的逐模型 quotaInfo（不含窗口字段，因此永远无法区分 5h 与 weekly）换成 v1internal:retrieveUserQuotaSummary，按账号缓存在 cachedLimits。

本插件因此按以下顺序取数（实现见 src/quota-source.ts）：

• 自动轮询绝不 force：TTL 内不产生上游调用；若某次探测整体失败（measured: 0 且 failed > 0），客户端会退避一整个 TTL，避免持续击穿 Google 接口。
• RPC 不可用时自动降级：connection 服务缺失或 RPC 报错时回落到旧 HTTP 通道；两者都不可用时保留上一次成功数据，而不是清空面板。

---

🚀 一键快速安装 (Quick Start)

💡 前置要求：请确保已经安装并配置好底层 Provider dsh-agy。

本项目已正式发布至 npm 官方仓库 (dsh-agy-ui)。打开终端，一行命令即可全自动安装并完成 Profile 激活注册：

# 官方 CLI 一键安装注册（全自动拉取并注入 Profile）
dsh plugin --profile web add dsh-agy-ui

# 💡 若未全局安装 dsh 命令，可使用 npx 免安装执行：
npx @deepseek-ai/dsh plugin --profile web add dsh-agy-ui

安装完成后，启动或重启 DSH Web：

dsh web
# 或：dsh restart

刷新浏览器页面（http://127.0.0.1:3080），顶栏实时额度徽章与净化后的模型列表即刻呈现！

🛠️ 开发者 / 源码安装方式

• 从 GitHub 仓库一键直装：

  dsh plugin --profile web add github:Erick0412-dev/dsh-agy-ui
  

• 本地克隆二次开发：

  dsh plugin --profile web add /path/to/dsh-agy-ui
  

---

❓ 常见问题 (FAQ)

Q1: 为什么我的徽章一直显示灰色点？

灰色点表示当前未检测到活跃的 Antigravity 账号。`dsh-agy` 0.3.0 起请在 DSH 的 设置 → Antigravity 中添加账号并完成 Google 登录（上游已移除旧的 /agy 仪表盘）。

Q2: 为什么切换标签页时不会立即刷新额度？

为了保护您的 Google 账号不被 Google 接口报 429 速率限制（Rate Limit），插件内置了 120 秒全局频率锁。在 120 秒内频繁切回标签页不会发起重复网络请求。如需立即获取最新额度，可点击浮层中的刷新图标手动刷新。

Q3: 我同时安装了 dsh-agy-link 会发生冲突吗？

不会。dsh-agy-ui 具有独立插槽 ID 与独立的 CSS 命名空间，不仅完全兼容，还会自动读取 dsh-agy-link 的配额接口作为回退：优先展示 dsh-agy 的分组窗口（5h / 日 / 周 / 月），无分组数据时再使用 link 的家族额度。

---

🙏 致谢 (Special Thanks)

本项目站在巨人的肩膀上，在此由衷感谢以下优秀的开源项目与贡献者：

• 🌟 DeepSeek Harness (deepseek-ai/deepseek-harness)
  一切的核心基石。DSH 优雅强大的 Cordis 微内核架构、模块化 Web UI Slots 插槽与 LLM 适配器抽象，让插件的非侵入式开发成为可能。
• ⚡ dsh-agy by @chaos-03x
  核心上游 Provider。以极其纯粹高效的底层设计直连 Google 内部 API，支持原生 Tool 运行与账号轮换，是本插件依托的坚实后盾。
• 🎨 dsh-agy-link by @amlyczz
  卓越的灵感源泉与排版榜样。其精巧绝伦的排版设计、双桶配额（5h / 7d）监控思路以及细腻的交互美感，为本插件的 UI/UX 设计提供了莫大的启发与参考！

---

⚖️ 开源协议与声明 (License & Compliance)

• 本项目基于 MIT License 开源。
• 关联项目（deepseek-harness、dsh-agy、dsh-agy-link）均采用宽松平易的 MIT 许可证。本项目完全遵循相关许可协议，通过动态挂载、公开 HTTP 端点和插槽机制协同工作，不包含任何专有或侵权闭源衍生代码。
• 免责声明：本项目为社区个人独立开源的伴生增强插件，与 Google LLC、DeepSeek 等官方实体无直接商业或从属关联。请在符合各服务商使用条款的范围内合理使用。