@xia-sc/dsh-decision

2. 安装与配置

### 3.4 设置页如何读写配置

**读**（三个来源，先快后慢，永远不会因为慢请求白屏）：

1. 浏览器 `localStorage` 里上次的快照（`dsh-decision.status.v1` / `dsh-decision.usage.v1`）—— 进页面**立即**渲染，不转圈；
2. `GET /status` —— Key 掩码前缀、默认模型、模型表、诊断信息（Host 端 20 秒复用，热时 3–80 ms）；
3. `GET /usage` —— 今日请求/tokens 与每个模型的配额条（上游较慢，单独请求，到达后补进页面；Host 端同样 20 秒复用）。

后台请求返回后会替换屏幕上的缓存并回写 `localStorage`；请求失败时**保留已有数据**，只在下面补一行错误提示（不会把页面清空）。前端两个请求都带 15 秒超时。

**写**：

- 填写 Key → `POST /config`：Host 先用 `/api/keys/self` **验证该 Key**，成功才 `credentials.set`；失败返回 400 与原因。
- 选择模型 → 同一个 `POST /config`：校验它在 `/api/info` 的模型列表里，然后原子写入 `$DSH_HOME/.dsh-decision.json`。
- 保存成功后 Host 使缓存失效并返回最新 status + usage，页面直接应用，不再多打一轮请求。

**为什么拆成 `/status` 与 `/usage`**：`/api/info` 冷启动要 4–5 秒、配额接口约 0.8–2.5 秒，而模型表/Key 状态是页面的主体。拆开后主体先出来，配额随后补齐；再叠加两级缓存（Host 20 秒 + 浏览器上次快照），重复进入设置页基本是瞬时的。

### 3.5 密钥与配置的解析顺序

```text
DECISION_API_KEY 环境变量
  → DSH 凭据 DECISION_API_KEY（ctx.credentials.resolve，返回 { value, source }）
  → $DSH_HOME/.dsh-decision.json 的 apiKey（无 credentials 服务时的兜底写入位置）

默认模型每次调用时读取（readSettings 有进程内缓存，写入后失效），所以改完设置立刻生效，不需要重启。