dsh-plugin-ai-gateway (AI 聚合网关)

DeepSeek Harness 官方生态插件：本地多渠道 AI 聚合反代网关可视化控制台。

基于拥有 52k+ Stars 的开源内核 CLIProxyAPI，将 Google Antigravity（Gemini / Claude） 与 OpenAI Codex（GPT-5.6 / o1） 订阅账号统一反代为标准 OpenAI 兼容接口，深度集成至 DeepSeek Harness (DSH)。

提供集 环境部署、双通道 OAuth 授权、多账号智能轮换池、5h / Weekly 双时间窗额度大盘（0ms 极速 SWR）、自适应出海网络代理与上下文智能调优 于一体的完整图形化控制中枢。

---

核心特性

1. 🌐 双通道顶级模型一网打尽

• Google Antigravity 通道：
  • Gemini 3.8 Flash（262k 互切主力） & Gemini 3.8 Flash（1M 巨幕版）
  • Gemini 3.7 / 3.6 Flash、Gemini 3.1 Pro、Gemini 3.1 Flash Lite、Gemini Pro Agent
  • Claude Sonnet 4.6、Claude Opus 4.6 (Thinking)
• OpenAI Codex 通道：
  • GPT-5.6 Sol（旗舰深度推理）、GPT-5.6 Terra（全能平衡主力）、GPT-5.6 Luna（极速代码补全）
  • GPT-5.5、GPT-6 Astra、GPT-5.3 Codex Spark、Codex Auto Review
  • o1、o3-mini、GPT-4o

2. 👥 多账号智能轮换池与故障转移 (Failover)

• 负载均衡：多个 Google 或 OpenAI 账号自动按 round-robin 轮流调度，成倍扩充 5 小时内可用并发；
• 无缝接力：当某一账号触碰 5 小时限流或偶发 429 时，网关在底层毫秒级平滑故障转移至可用账号，前端智能体任务不中断；
• 生命周期管理：控制台提供一键新增 OAuth 账号、一键重置运行时熔断冷却、一键移除废弃账号。

3. 📊 5h 滚动 + 7 天周额度实时看板 (完全对齐官方体系)

• 高精指标：直连官方后端 API，精确计算 Claude、Gemini、Codex 的 5 小时窗口与 7 天周额度百分比；
• 倒计时预测：精准计算额度回满时间点（如 1h 54m (09/13 19:40)）；
• 高饱和状态胶囊条：翠绿（充足 >40%）/ 黄色预警（15%~40%）/ 红色危险（<15%），状态一目了然；
• Codex 额度重置券：自动同步 Banked Rate-Limit Resets 额度券余量，支持一键满血重置；
• 底栏气泡智能联动：底栏「上下文已用」圆环展开时，仅在当前会话使用反代模型时自动附带额度面板，切回原厂模型自动隐藏。

4. ⚡ SWR (Stale-While-Revalidate) 毫秒级极速响应

• 摆脱传统查询等待数秒的迟滞感；
• 内存级 SWR 机制，打开面板 0~1ms 瞬时直出；
• 后台 45s 定期异步预热对齐，保证数据既极速又新鲜。

5. 🔌 智能自适应出海代理 (Smart Egress Proxy)

• 三级自动探测：标准环境变量 → Windows 注册表系统代理 → 常见本地端口主动嗅探（7890/7891/7892/10808 等）；
• 自动让网关直连本地代理端口，彻底解决大请求体（如多轮带图长对话）在 TUN 虚拟网卡 Fake-IP 模式下的 TCP 握手超时断连问题。

6. 🧠 262k 敏捷互切与 1M 巨幕双轨策略

• 日常主力 262k 版：触发 DSH 自动上下文精炼压缩，在 Gemini ↔ GPT-5.6 ↔ Claude 间平级无缝秒切，不降智、不拖慢；
• 1M 巨幕版：保留百万 Token 原始吞吐能力，专攻巨型旧工程扫描。

---

架构与设计分工

DSH 遵循清晰的微内核与关注点分离规范：

┌─────────────────────────────────────────────────────────────┐
│                      DSH 浏览器前端                          │
│  ┌───────────────────────┐       ┌───────────────────────┐  │
│  │ DSH 原生模型选择器     │       │ 本插件控制台 & 气泡    │  │
│  │ (设置 → 模型 / 底栏)  │       │ (设置 → AI 聚合网关)  │  │
│  └───────────┬───────────┘       └───────────┬───────────┘  │
└──────────────┼───────────────────────────────┼──────────────┘
               │ (标准 LLM 请求)                 │ (管理面 RPC)
┌──────────────▼───────────────────────────────▼──────────────┐
│                    DSH Node.js 宿主端                       │
│  ┌───────────────────────┐       ┌───────────────────────┐  │
│  │ @deepseek-ai/         │       │ dsh-plugin-ai-gateway │  │
│  │ dsh-llm-pi-ai         │       │ (守护管理/看门狗/SWR) │  │
│  └───────────┬───────────┘       └───────────┬───────────┘  │
└──────────────┼───────────────────────────────┼──────────────┘
               │ (127.0.0.1:8317/v1)           │ (管理端口/本地鉴权)
┌──────────────▼───────────────────────────────▼──────────────┐
│            本地加固网关进程 (CLIProxyAPI Daemon)            │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ 负载均衡池 (Round-Robin) · 凭据管理器 · 代理隧道出口   │  │
│  └───────────┬───────────────────────────────┬───────────┘  │
└──────────────┼───────────────────────────────┼──────────────┘
               │                               │
┌──────────────▼────────────┐     ┌────────────▼──────────────┐
│  Google Cloud Code 后端   │     │      OpenAI Codex 后端    │
│  (Antigravity / Gemini)   │     │    (ChatGPT Plus / Team)  │
└───────────────────────────┘     └───────────────────────────┘

• 模型路由与协议转换：完全归属 DSH 原生 llm-pi-ai 适配器（声明于 $DSH_HOME/settings.yaml）；
• 网关与环境治理：归属本插件（进程保活、双向鉴权、多账号、配额采集、界面注入）。

---

快速上手

1. 安装插件

在插件工程根目录下，执行内置安装工具将其装入指定的 DSH profile：

node tools/install-into-profile.mjs --profile web

或在发布到 npm 后使用官方 CLI 安装：

dsh plugin --profile web add dsh-plugin-ai-gateway

2. 启动与重启

使用自带的幂等安全重启工具（自动验证端口、进程名与环境参数）：

node tools/restart-web.mjs --yes

3. 连接账号

1. 浏览器打开 DSH Web（http://127.0.0.1:3080）；
2. 导航至左侧 「设置 → AI 聚合网关」；
3. 点击 ➕ 登录 Google 账号 或 ➕ 登录 Codex 账号，在弹出链接中完成一次性 OAuth 授权；
4. 授权成功后，点击下方 「一键接入」，插件将自动把 agy-gateway 与 codex-gateway 配置及安全密钥写入 DSH。

---

安全设计

1. 绝对本地回环：网关默认严格绑定 127.0.0.1，拒绝一切局域网暴露；
2. 密钥分离与凭据库隔离：
   • 数据面 apiKey 与管理面 managementKey 完全独立生成；
   • API Key 持久化存储于 DSH 专属的 ~/.dsh/.credentials.yaml 凭据隔离区，主配置文件仅保留引用；
3. 同源防护与远程控制阻断：
   • 前端管理接口强制校验 Origin，拦截任何跨站 CSRF 请求；
   • 当 DSH 宿主绑定在非本机 IP 时，启停、删除、登录等破坏性写操作默认强制 403 拒绝；
4. 孤儿进程防护与自愈看门狗：
   • DSH 退出或重载时，插件内置 Disposer 会精准清退底层子进程；
   • 运行时内置 60 秒轻量看门狗，意外断线自动拉起，手动停止则尊重意图保持静默。

---

排障手册 (Troubleshooting)

1. 上游返回 403 VALIDATION_REQUIRED

• 现象：刚登录 Google 账号后推理报 Verify your account to continue；
• 原因：Google 触发了针对新设备/新节点的安全质询；
• 解决：点击面板账号卡片右侧的 → 去验证账号 链接，在无痕浏览器中登录该账号并确认授权，完成后瞬间自动解禁。

2. 模型请求报错 Invalid value ... thinking_level: "xhigh" (400)

• 原因：Google Gemini 官方枚举仅支持 low 与 high，不接受 xhigh；
• 解决：在 DSH 设置中，插件已预置平滑映射：UI 上的 xhigh 会自动向下转换为 Google 顶格的 high，避免 400 报错。

3. 上游返回 503 dial tcp ... i/o timeout

• 原因：本地代理软件开启 TUN 模式时，虚拟网卡的 Fake-IP 在转发几兆级的多轮长对话请求体时发生握手超时；
• 解决：插件已内置 proxy-url: "auto" 机制，会自动直连本地代理 HTTP 端口（如 7892/7890），绕过虚拟网卡直通出海。

---

自动化测试集

运行全套质量门禁（132 项全部通过）：

npm test

• 红线规范检查 (redline-check)：21/21 项（编码格式、无 BOM、导出契约、产物完整性）
• 极端边界测试 (edge-case-test)：17/17 项（冷启、破坏性配置、陈旧 PID、哈希不符、降级回退）
• 全功能冒烟测试 (smoke-test)：84/84 项（真实网关全链路、写操作幂等、跨域拦截、凭据注入）
• 界面渲染测试 (client-render-test)：10/10 项（全状态分支、双通道卡片、高亮胶囊轨、槽位隔离）

---

开源许可

MIT License