# dsh-quota 系统架构与实现原理

本文档介绍 **@francescoli/dsh-quota** 的系统设计、核心模块划分及数据流向。

---

## 1. 整体架构

```
┌─────────────────────────────────────────────────────────────┐
│                    DSH Web GUI (Browser)                    │
│  ┌─────────────────────────┐   ┌─────────────────────────┐  │
│  │   Sidebar View Panel    │   │      HUD Status Bar     │  │
│  │  (侧边栏全量用量看板)   │   │     (顶部常驻指标卡)    │  │
│  └────────────┬────────────┘   └────────────┬────────────┘  │
│               │                             │               │
│               └──────────────┬──────────────┘               │
│                              │ JSON RPC / REST API          │
└──────────────────────────────┼──────────────────────────────┘
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                   DSH Host Plugin Service                   │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                   Quota Manager Core                  │  │
│  │    • Local Config Store (~/.dsh/quota-config.json)    │  │
│  │    • In-memory Cache & Rate Limit Defense             │  │
│  └───────────────────────────┬───────────────────────────┘  │
│                              │                              │
│       ┌──────────────┬───────┴──────┬──────────────┐        │
│       ▼              ▼              ▼              ▼        │
│  ┌─────────┐   ┌──────────┐   ┌───────────┐  ┌───────────┐  │
│  │ Cursor  │   │  Codex   │   │Antigravity│  │OpenCode-Go│  │
│  │Provider │   │ Provider │   │ Provider  │  │ Provider  │  │
│  └─────────┘   └──────────┘   └───────────┘  └───────────┘  │
└─────────────────────────────────────────────────────────────┘
```

---

## 2. 核心模块与职责

1. **Host 核心层 (`src/core/`)**：
   - `manager.ts`：配额管理器总控，负责调度各 Provider、聚合响应、统一缓存与持久化配置；
   - `fetch.ts`：带代理与超时的统一网络请求封装；
   - `oauth.ts`：本地轻量 OAuth 回调 HTTP 服务；
   - `types.ts`：通用配额数据模型定义。

2. **服务适配层 (`src/providers/`)**：
   - `cursor.ts`：本地 VS Code / Cursor SQLite 数据库探测与配额解析；
   - `codex.ts`：OpenAI 官方与 OneAPI/NewAPI 用量统计；
   - `antigravity.ts`：Google Antigravity 配额获取与 Token 刷新；
   - `opencode-go.ts`：OpenCode 算力额度与重置计算。

3. **前端视图与 HUD 层 (`src/client/`)**：
   - `view.ts`：侧边栏卡片式面板渲染与宋代色彩主题；
   - `hud.ts`：Web 顶部 HUD 状态栏实时监控指标；
   - `controller.ts`：状态管理与前后端通信。