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        │◄─────┤   适配器列表动态拦截包装  │
                    │   (顶栏徽章 + 浮层弹窗)  │      │ (净化/折叠/品牌化/排序)   │
                    └───────────┬────────────┘      └────────────┬────────────┘
                                │ HTTP 状态读取                   │ 原生模型委托
                                ▼                                ▼
                    ┌────────────────────────┐      ┌─────────────────────────┐
                    │   dsh-agy 后台 API     │      │   dsh-agy 核心调用层    │
                    │  (/agy/api/accounts)   │      │ (直连 Google 内部 API)  │
                    └────────────────────────┘      └─────────────────────────┘
                                ▲
                                │ 兼容读取（可选共存）
                    ┌───────────┴────────────┐
                    │      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。
• 一目了然的配额显示：常驻显示当前活跃账号的 Gemini 5 小时配额（如 AGY · 55%）。
• 动静相宜的呼吸微动效：静态健康圆点平时稳定常亮（绿=正常、黄=冷却中/限流、灰=无可用账号），仅在后台数据同步或手动刷新时展示 1.2 秒平滑呼吸光效。
• 120 秒全局频率锁：2 分钟定时轮询 + 120 秒标签页/窗口聚焦节流锁，彻底杜绝切换标签页时高频击穿后台触发 Google 429 限流。

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

▲ 点击或悬停徽章呼出的多模型双周期（5小时/7天）配额监控面板

• 悬停即现，支持钉选 (Pin)：鼠标移入徽章毫秒级呼出，居中对齐徽章下方；点击徽章即可常驻固定。
• 双周期（Dual-Bucket）配额条：
  • 5 小时周期（Sprint）：展示当前 5 小时内的剩余额度进度与百分比。
  • 7 天周额度（Weekly Cap）：存在周额度数据时自适应展示。
• 账号健康与快捷入口：展示当前激活账号脱敏标识及健康状态，内置手动刷新按钮与一键直达 /agy 管理后台快捷入口。

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

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

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

• 所有 CSS 均置于 agy-ui-* 独立前缀命名空间，杜绝全局样式污染。
• 完整兼容并可与 dsh-agy-link 无缝共存，自动优先读取 link 提供的官方周配额与 5 小时配额。

🚀 一键快速安装 (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），顶栏实时额度徽章与净化后的模型列表即刻呈现！

❓ 常见问题 (FAQ)

🙏 致谢 (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 等官方实体无直接商业或从属关联。请在符合各服务商使用条款的范围内合理使用。