# Local API and extension guide

## Endpoint

```http
GET /api/dsh-volcengine-usage/v1/usage
```

接口仅供 DSH 本机 Web UI 和本机二次开发使用，返回头包含 `Cache-Control: no-store`。

## Success response

```json
{
  "ok": true,
  "usage": {
    "status": "Normal",
    "updatedAt": 0,
    "session": 0,
    "weekly": 0,
    "monthly": 0,
    "sessionReset": 0,
    "weeklyReset": 0,
    "monthlyReset": 0
  },
  "fetchedAt": 0
}
```

百分比字段直接来自火山接口。时间字段是上游时间戳；调用方应兼容 `0`，不要假设一定存在。

## Error response

```json
{
  "ok": false,
  "error": "可安全展示的错误信息"
}
```

典型 HTTP 状态：

- `403`：请求不是来自本机环回地址
- `405`：请求方法不是 GET
- `502`：凭据缺失、过期，或火山接口请求失败

## Extension points

### 修改刷新间隔

编辑 `lib/client.js` 中的：

```js
setInterval(refresh, 5 * 60 * 1000)
```

### 修改默认位置

编辑 `loadPosition()` 返回值。用户拖动后的坐标存于浏览器 localStorage：

```text
dsh-volcengine-usage:position
```

### 修改显示字段

服务端 `normalizeUsage()` 负责将上游响应整理为稳定结构；浏览器端 `Card()` 和 `Row()` 只消费整理后的字段。新增字段时优先保持现有 v1 字段兼容。

### 添加新接口版本

如需破坏性变更，请新增 `/v2/` 路径，不要改变 v1 字段含义。

## Privacy boundary

不得把 `VOLCENGINE_COOKIE`、`VOLCENGINE_WEB_ID` 或 CSRF token 放进 JSON 响应、浏览器日志、错误信息或遥测。