# 火山方舟用量看板操作教程

本教程说明如何在 dsh-devforge 的“服务工厂 → Coding Plan → 火山方舟”页面配置模型、推理档位和套餐用量看板。

## 一、先区分两类凭据

| 凭据 | 用途 | 在服务工厂中的位置 |
| --- | --- | --- |
| Agent Plan API Key（通常以 `ark-` 开头） | 调用 Agent Plan 模型 | “使用配置 → 模型调用凭据” |
| 火山 Access Key / Secret Key（AK/SK） | 调用控制面 OpenAPI，查询 Coding Plan 与 Agent Plan 套餐用量 | “用量统计 → 控制面 AK/SK” |

Plan API Key 不能读取套餐用量，这是火山方舟的数据面与控制面权限边界。用量看板必须另外配置 AK/SK。

## 二、配置模型与推理档位

1. 打开 DSH Web GUI。
2. 左侧进入“服务工厂”。
3. 打开“Coding Plan”，选择“火山方舟”。
4. 保持在“使用配置”页。
5. 在“模型调用凭据”输入框粘贴 Agent Plan API Key，点击“保存 Plan Key”。
6. 点击“同步模型与推理档位”。
7. 回到对话页面的模型选择器，选择 `volcengine-ark-plan` 下的模型；支持的模型会出现推理级别选项。

同步操作只补齐缺失模型、推理档位和必要兼容字段，不覆盖用户已经显式设置的字段。

## 三、获取火山控制面 AK/SK

1. 登录 [火山引擎控制台](https://console.volcengine.com/)。
2. 使用购买 Agent Plan 或 Coding Plan 的同一账号。
3. 点击右上角账号头像，进入“API 访问密钥”或直接打开 [访问密钥管理](https://console.volcengine.com/iam/keymanage/)。
4. 创建或启用一组 Access Key / Secret Key。
5. 确保当前身份拥有火山方舟用量查询权限。子用户若收到 `AccessDenied`，需要主账号在 IAM 中补充相应方舟只读/用量查询权限。

Secret Key 通常只在创建时完整展示。不要把 AK/SK 发到聊天、Issue、日志或源码中。

## 四、在用量看板中配置 AK/SK

1. 打开“服务工厂 → Coding Plan → 火山方舟”。
2. 切换到“用量统计”。
3. 在第一个输入框粘贴 Access Key。
4. 在第二个输入框粘贴 Secret Key。
5. 点击“保存并验证”。
6. Host 会先用这组 AK/SK 请求官方用量接口；验证成功后才成对写入受管凭据，并立即返回 Agent Plan 与 Coding Plan 的额度窗口。

验证失败不会写入任何新凭据；第二项写入失败时会自动恢复旧 Access Key，避免出现半配置状态。

凭据分别保存为 DSH 受管凭据：

- `VOLC_ACCESS_KEY`
- `VOLC_SECRET_KEY`

页面只显示“已配置/待配置”，不会把凭据明文回显给浏览器。

## 五、怎么看用量

看板按套餐显示以下窗口：

- 5 小时窗口：Agent Plan 通常标为 `5h`，Coding Plan 通常标为 `session`。
- 每周窗口：`weekly`。
- 每月窗口：`monthly`。

每行展示：

- 已用百分比；
- 剩余百分比；
- 已用/总量（仅上游返回绝对值时显示）；
- 距离下次重置的时间。

页面默认复用五分钟 Host 内存缓存。点击“实时刷新”会绕过缓存重新查询；若实时查询失败但已有成功快照，页面保留旧数据并标记“旧快照”。

## 六、常见问题

### 1. 提示尚未同时配置 AK/SK

Access Key 和 Secret Key 必须同时填写。两者属于同一组访问密钥，不能混用不同账号或不同密钥组。

### 2. 提示 AccessDenied

当前 AK/SK 对应的主账号或子用户缺少火山方舟用量查询权限。请在火山 IAM 中补充权限后再次点击“保存并验证”或“实时刷新”。

### 3. Plan Key 可以调用模型，但看板仍没数据

模型调用和套餐查询使用不同凭据。请确认“用量统计”页已经单独配置 `VOLC_ACCESS_KEY` 与 `VOLC_SECRET_KEY`。

### 4. 只显示一个套餐

当前账号可能只订阅了 Agent Plan 或 Coding Plan。另一个套餐会显示未订阅或接口提示，不影响已订阅套餐的数据。

### 5. 点击保存后状态没有变化

确认两个输入框都已填写；缺任意一项时按钮保持禁用。若浏览器仍显示旧页面，请强制刷新 DSH Web 页面后重新进入“服务工厂 → Coding Plan → 火山方舟 → 用量统计”。保存失败时页面会显示官方鉴权或写入错误，凭据不会静默落盘。

### 6. 更换或吊销 AK/SK

在火山控制台创建新密钥后，回到用量页同时填写新 AK 与新 SK，再点击“保存并验证”。验证成功后可在火山控制台吊销旧密钥。