# 使用文档

打开方式：**设置 → 插件 → Free Token**（重启 DSH 之后才会出现）。

页面分四块：**顶部状态条 → 全局配置 → Agent 标签页 → 流水与日志**。

---

## 1. 添加 OpenCode 账号

> **先说结论：想用免费模型，一个字段都不用填。**
>
> OpenCode 的免费模型**不要 API key、也不要登录** —— 但要**按客户端形状发请求**。
> 插件在「账号没填 key」时会自动补齐这份形状（会话头 + `read` 工具 + 强制流式），
> 所以你要做的只是：**标签填一个，凭证全留空，点添加**。

### 方式一：什么都不填（免费模型，推荐）

1. OpenCode 标签页 → 「新增账号」→ **只填标签**（例如「免费」）；
2. token / cookie / 额外请求头**全部留空** → 点「添加」；
3. 点这一行的「测活」，应当返回
   「上游接受匿名免费层请求（用 xxx 探的，session=ses_…）」；
4. 回对话框，模型选择器里选 `OpenCode · xxx (免费)` 就能聊。

这就是「匿名免费层」。原理与实测报文见
[`OPENCODE-API.md`](OPENCODE-API.md) §1.5–1.6（过门的三件事：
`stream:true` + 一个叫 `read` 的工具 + 规范的 `x-opencode-session`）。

> ⚠️ **只对免费模型有效。** 付费模型在匿名通道上会直接
> `401 Missing API key` —— 要用付费模型就得走下面两种方式。
>
> ⚠️ 上游可能再改门禁。被拒时错误信息会把那三件事列出来，不会让你瞎试；
> 真变了就换方式二/三。

### 方式二：登录 OpenCode 账号（要付费模型、或免费层被改了）

1. 账号卡片 → 点 **「登录 OpenCode 账号（设备码）」**；
2. 页面显示设备码（形如 `SNDF-LJTG`）与链接；
3. 点「打开授权页」，**在你自己的浏览器里**输码、授权；
   - 授权页显示「**opencode-cli** 申请访问你的 OpenCode 账号」——
     那是官方 CLI 用的同一个 OAuth 客户端；
4. 插件每 5 秒查一次，授权完成后**自动把账号加进来**（标签 = 你登录的邮箱）；
5. 完成。**全程没有创建过任何 API key。**

登录态会自动续期（access token 快过期时用 refresh token 换新的，并加密落盘）。

### 方式三：Console API key

1. 到 [opencode.ai/console](https://opencode.ai/console) → **Keys** → 新建 API Key。
   - 想查**额度**（预算/已用）就建 **Service Account** 并选 **All** 权限；
   - 只用来对话 / 拉模型，**Inference only** 就够。
2. 回到插件页 → 「新增账号」→ 填标签 + 粘贴 `oc_sk_…` → 点「添加」。

### 方式四：走中转 / 反代

1. 把 **「对话 base url」** 改成你中转的地址（还有 **「业务 API base url」**）；
2. 凭证按中转要求填（不要求就留空）；
3. 点「测活」确认。

> **免 key 的模型目录**：`/inference/v1/models` 不带凭证就能读，
> 所以模型选择器里的分组与倍率**一个账号都不加也能显示**，只是发不出请求。

> 同一个 Agent 下可以加 **N 个账号**，凭证各自独立保存。免费层账号（空凭证）
> 与付费 key 账号可以并存，会作为独立账号参与路由。

账号列表每行的开关：

| 开关 | 含义 |
|---|---|
| **对话** | 参与对话请求的路由（关掉 = 保留但不用它发请求） |
| **签到** | 参与每日自动签到（账号级覆盖 Agent 级） |
| **任务** | 参与活动任务（账号级覆盖 Agent 级） |

每行的按钮：

| 按钮 | 作用 |
|---|---|
| **测活** | 真实打一次上游，验证凭证还有效 |
| **重置健康** | 把降权 / 失败计数清零，让它立刻重新参与路由 |
| **恢复** | 解除该账号的**活动任务暂停** |
| **删除** | 删掉账号（连带清掉它的额度与健康缓存） |

**凭证永远不会回到浏览器**：接口返回的账号对象里，token/cookie 都已被脱敏成
`oc_s***cd**.

---

## 2. 看积分 / 额度

三种入口：

1. **定时拉取**：Agent 标签页里打开「定时拉取额度」，默认每 30 分钟一次；
   结果落在「额度」列，并写进 `state.json`。
2. **手动刷新**：点「刷新额度」，立刻拉一次。
3. **问模型**：对话里说「看看我各个号的额度」——模型会调 `multiagent_quota` 工具。

额度的三种状态：

| 显示 | 含义 |
|---|---|
| `12.34 美元` / `500 积分` | 拉到真实数值 |
| `不限` | 上游说这个账号没有限额 |
| `未知` + 一句原因 | **没拉到**。原因是人话，例如「这个 key 没有 All 权限」 |

**不会用 0 冒充未知额度**：`未知` 就写 `未知`，并在下面写清原因。

---

## 3. 配置自动签到

签到与活动任务是**两套完全独立的模块**。

1. Agent 标签页 → 勾选 **「自动签到（基础每日任务）」**；
2. 「签到时间」填 `every:86400`（每天一次）或 `0 30 8 * * *`（每天 08:30）；
3. 点「保存配置」；
4. 想立刻试一次：「立即签到」按钮（会忽略「今天已签过」）。

行为细节：

- **幂等**：同一天内同一个账号只会签一次（键是 `agent:account:yyyy-mm-dd`），
  DSH 重启也不会漏也不会重复；
- **上游没有签到接口时**：返回「上游没有这个接口（这不是故障）」，
  **不计失败、不触发暂停**，只在日志里记一条；
- 每个账号错峰执行（启动后 60 秒起，账号间再错开 5 秒），避免同一秒打上游。

---

## 4. 配置活动任务

1. Agent 标签页 → 勾选 **「自动活动任务」**（默认**关**）；
2. 填三个参数：
   - **轮询间隔（分钟）**：建议 ≥ 30；
   - **并发上限**：默认 1（串行）。多账号时**不要**贪高，容易触发上游风控；
   - **连续失败暂停阈值**：默认 3。达到后**只暂停这一个账号**并写告警日志。
3. 填上游接口路径（只有上游真的有这些接口时才填）：
   - `签到接口路径`、`额度接口路径`、`任务列表路径`、
   - `领取奖励路径`（用 `{taskId}` 占位）、`任务状态路径`（可空）。
4. 点「保存配置」。

手动动作：

| 按钮 | 作用 |
|---|---|
| **列任务** | 只为看一眼当前可做的任务（不执行） |
| **跑一轮任务** | 立刻按配置跑一轮（并发受 `并发上限` 限制） |
| **刷新** | 重新拉页面数据 |

任务流水（页面下方「任务执行流水」）逐条记录：

```
2026/10/16 09:12:33 [opencode/主号] 每日签到 → 成功 (+5)
2026/10/16 10:00:01 [opencode/主号] 完成每日任务 → 成功 (+10)
2026/10/16 10:00:02 [opencode/副号] 观看视频 → 失败 kind=rate_limit HTTP 429
```

---

## 5. 账号路由策略

顶部的 **「账号路由策略」** 下拉：

| 策略 | 什么时候用 |
|---|---|
| **quota-first（优先额度高）** | 默认。同 Agent 下有的号快没额度了 —— 先把请求压在还有额度的号上 |
| **round-robin（轮询）** | 几个号完全对等、只想把压力摊开 |

三件事**自动**发生（不用你管）：

1. **换号**：请求遇到 401 / 429 / 额度耗尽 → 自动切到同 Agent 下另一个可用账号重试；
2. **降权**：连续失败到阈值 → 该账号被临时降权（默认鉴权失败 10 分钟、
   额度耗尽 30 分钟、限流取 `Retry-After` 与 300 秒的较大者）；
3. **自动恢复**：降权到期后，调度器会周期性做一次轻量探测（默认 10 分钟一轮），
   探活成功就立刻解除降权。

「多账号路由」这一切换过程会写日志：

```
[router] 账号 opencode:主号 失败（auth）expired —— 尝试切换下一个账号
[router] 「opencode」第 2 次尝试成功 account=opencode:副号 用时=412ms
```

**不该换号的情况**（换了也一样错，所以直接返回）：

- `bad_request`（模型名写错、参数不合法）→ 直接报给用户，不浪费其它账号的额度。

---

## 6. 模型与倍率

Agent 标签页 →「模型与倍率」→ 点 **「列出模型」**：

| 模型 | 倍率 | 上下文 | 选择器里显示成 |
|---|---|---|---|
| DeepSeek V4.1 Flash Free | 免费 | 200000 | `OpenCode · DeepSeek V4.1 Flash Free (免费)` |
| MiniMax M3 | ×1 | 200000 | `OpenCode · MiniMax M3 (×1)` |
| Claude Opus 5 | ×20.83 | 200000 | `OpenCode · Claude Opus 5 (×20.83)` |

倍率口径与自定义见 [`MODELS.md`](MODELS.md)。

- 想让模型名不带 `OpenCode · ` 前缀 → 关掉「模型名带 Agent 前缀」；
- 不想让这个 Agent 的模型出现在对话框下拉里 → 关掉「上报模型到 DSH 选择器」；
- 倍率显示 `未知倍率` = 价格源没拉到（不影响使用，只是看不出贵度）。

### 只把我要的模型放进下拉（默认就不是「全部」）

上游有 **85 个模型**，全进下拉的话免费那几个会被淹没。所以这里是**勾选式**的：

1. 「模型与倍率」→ 点 **「列出模型」**（会把全量拉下来，带搜索框）；
2. 上面三个按钮选一种：

   | 按钮 | 效果 |
   |---|---|
   | **只报免费模型**（默认） | 只把免费的那几个放进下拉 —— 免费层就是这么用的 |
   | **只报我勾选的** | 只放你打了勾的；**勾选会自动切到这个模式** |
   | **全部上报** | 85 个全进去（找起来费劲，一般不用） |

3. 勾完点 **「保存」**。「进下拉」那一栏显示的是**当前实际上报的**，保存后才会变。

> 勾选列表里的倍率就是它在选择器里的标记：`(免费)` / `(×2)` / `(未知倍率)`。
> 判据是**价格**，不是名字 —— 名字带 `free` 但取不到价格的模型会显示成「未知倍率」，
> 不会被「只报免费」选中。

**选了免费层不覆盖的模型会怎样**：上游回 401，插件现在会明确告诉你
「这个模型不在匿名免费层里，换一个免费模型或填真 key」——
而不是像以前那样显示成「API 密钥无效」（那会让人以为账号坏了）。

---

## 7. 用模型（对话）

在对话框底部的模型选择器里：

```
OpenCode          ← 分组标题（= Agent 名）
  OpenCode · DeepSeek V4.1 Flash Free (免费)
  OpenCode · MiniMax M3 (×1)
  ...
Qoder
  （待实现）
```

选一个就能聊。思维链（`reasoning_content`）会原样透传到 DSH 的「思考过程」里。

用反代平台时，记得在 Agent 的「上游地址 → 对话 base url」填成反代地址。

---

## 8. 用工具（让模型替你操作）

五个工具，模型可以直接调用：

| 工具 | 做什么 |
|---|---|
| `multiagent_accounts` | 列出 / 新增 / 修改 / 删除 / 测活账号 |
| `multiagent_quota` | 查看 / 刷新额度 |
| `multiagent_checkin` | 立即签到 |
| `multiagent_tasks` | 列任务 / 跑一轮 / 看流水 / 解除暂停 |
| `multiagent_routing` | 看路由状态 / 重置健康 / 立刻跑恢复检测 |

例子：「帮我给 OpenCode 加一个账号，标签叫备用，token 是 …」
「把 opencode 里那个连续失败的号重置一下」。

---

## 9. 存储位置

页面最下方「存储位置」会列出四份文件的实际路径。默认在
`<DSH_HOME>/multi-agent-gateway/`，含义见 [README](../README.md#数据落在哪)。

---

## 10. 常见现象速查

| 现象 | 含义 / 处理 |
|---|---|
| 账号行显示「降权中（2 次失败）」 | 该号最近连续失败，正在降权。点「重置健康」可立刻恢复 |
| 额度列一直「未知」 | 看括号里的原因。最常见是 key 没有 `All` 权限 |
| 「立即签到」返回「上游没有这个接口（这不是故障）」 | opencode.ai 官方 Console 确实没有签到。用反代平台时填 `签到接口路径` |
| 任务流水里同一个任务反复失败 | 达到阈值后该账号的自动任务会自动暂停，并写一条告警日志 |
| 模型下拉里分组在，但模型列表空 | 上游模型目录不可达 → 点「列出模型」看真实报错 |
| 保存配置总失败 | 界面会列出「改过哪些路径」。只有声明了 `volatile` 的字段可写 |