Driver 1.x 云端转写模型列表合同

后端管理可扩展的模型列表，并把客户端稳定 ID 映射到实际网关 ASR 模型。Driver Host/Voice 由 ai-vibe-board 项目独立接入、合并和发行。本文是新接口合同；不代表现有 Driver 已完成接入。

产品版本

0.x：当前已发布版本（根目录 src-tauri/、web/）。从模型网关目录读取真实模型，由用户在客户端选择；仅请求 client-config 的 endpoints、vibeBoard，不读取本文列表或早期单模型映射。
1.x（SDK-driver 版）：driver-v2/ 正在开发的版本，使用本文列表合同。润色跟随 Agent。
archive/driver-v1/ 从未发布、无线上用户，已归档，不是兼容目标。schemaVersion:1 和网关路径 /v1 是数据/API 版本，不是产品版本。

2026-09-09 ask-project 核对：1.x 开发代码仍读取早期 transcriptionTiers，需由 ai-vibe-board 独立接入本文接口。删除早期映射不影响线上 0.x；不代表当前 1.x 开发版已完成接入。

管理端

GET /admin/app-settings/driver-transcription-config 和同路径 PUT 均要求 JWT 与 site:admin，API key 不可调用，响应 Cache-Control: no-store。

GET 返回 {success:true,data:{config:null,revision:null}} 表示尚未配置；有记录时返回完整 config 和原始微秒精度 revision。PUT 示例：

json

{
  "expectedRevision": null,
  "config": {
    "schemaVersion": 1,
    "defaultOptionId": "transcribe-fast",
    "options": [
      {"id":"transcribe-fast","labels":{"zh-CN":"快速模型","en-US":"Fast model"},"modelId":"actual-asr-model-a","enabled":true},
      {"id":"transcribe-accurate","labels":{"zh-CN":"精准模型","en-US":"Accurate model"},"modelId":"actual-asr-model-b","enabled":true}
    ]
  }
}

示例实际模型不是生产预设，也不代表速度或准确率测评。模型目录沿用 GET /admin/app-settings/client-config/transcription-models。

首次写入 expectedRevision:null；后续必须原样发送 GET/PUT 返回的 revision，不能转成毫秒日期再序列化。成功仍返回 {success:true,data:{config,revision}}。
缺 revision 为 428 driver_asr_revision_required，格式错为 400 driver_asr_revision_invalid，并发冲突为 409 driver_asr_revision_conflict。不自动重试或覆盖。
options 最多 50 项；id 唯一，匹配 ^transcribe-[a-z0-9]+(?:-[a-z0-9]+)*$，总长不超过 64，transcribe-default 保留。名称修改不改变 id。
labels 恰含 zh-CN 和 en-US，均为非空、无首尾空格、最多 80 字符；modelId 同规则最多 200 字符。enabled 必须布尔值。拒绝未知字段。
启用项不得映射同一实际模型。存在启用项时默认 ID 必须命中启用项，否则默认必须 null。保存只验证启用项引用的实际模型是否已发布、支持 ASR 且供应商已配置；禁用的下架项可保留。
校验错为 400 driver_asr_config_invalid，模型不可用为 400 driver_asr_model_unavailable；数据库失败为 503 driver_asr_config_unavailable。失败不写配置。
空列表 {schemaVersion:1,defaultOptionId:null,options:[]} 是明确清空，区别于从未配置。

后台点击“增加模型”，填写一个“模型显示名”，再选择已上架的实际模型，即为一条配置，可重复添加。页面输入的显示名同时用于中英文客户端；API 仍支持分别提供两种语言的 labels。该区域有独立的“保存模型列表”按钮，页面顶部按钮不保存此列表。保存失败保留编辑内容并持续提示，直到管理员关闭。0.x 区域提供真实模型管理入口；1.x 区域只维护此列表。下方本地模型有“保存 App 配置”按钮，调用通用配置保存；与列表保存独立。

公开配置

GET /public/driver-transcription-config 无需认证，从当前节点数据库读取，无跨环境回退。

json

{
  "schemaVersion": 1,
  "version": 1788858000000,
  "updatedAt": "2026-09-08T09:00:00.000Z",
  "configured": true,
  "defaultOptionId": "transcribe-fast",
  "options": [
    {"id":"transcribe-fast","labels":{"zh-CN":"快速模型","en-US":"Fast model"},"enabled":true},
    {"id":"transcribe-accurate","labels":{"zh-CN":"精准模型","en-US":"Accurate model"},"enabled":true}
  ]
}

只返回上述白名单字段，不包含实际 modelId、provider 或凭据，也不返回 legacyOption。enabled 代表管理员开关，不承诺供应商实时健康或账户准入。

尚未配置：{schemaVersion:1,version:0,updatedAt:null,configured:false,defaultOptionId:null,options:[]}。明确清空时 configured 为 true。私有配置非法或 DB 失败返回 503，错误体 {error:{code,message}}，code 分别为 driver_asr_config_invalid / driver_asr_config_unavailable，Cache-Control:no-store。

正常响应使用强 ETag，Cache-Control: public, max-age=60, s-maxage=60, must-revalidate。If-None-Match 支持弱标签、标签列表和 *，命中返回 304 和相同缓存头。仅私有模型列表的原始 revision 参与摘要；只更换后台真实模型也会失效 ETag。公共 client-config 的变更不影响此接口版本，客户端不得无限延用过期配置。

语音调用

沿用 POST /api/model-gateway/v1/audio/transcriptions、OAuth scopes（vibe-board:cloud / mobile:full / model-gateway:invoke）或原 API key 权限。用 multipart/form-data：

text

model: driver-asr:transcribe-fast
file: <audio binary>
language: auto
response_format: json

环境 URL 从 Driver 当前受信任 API origin 派生，不能硬编码 ReAI 域名。language、prompt、temperature 等遵循原网关合同。成功 {text:"..."}，请求追踪头 X-Wainao-Request-Id。原调用方身份、OAuth App 归属、余额/订阅准入、实际模型计费保留。

情况	状态	error.code
别名格式错误	400	driver_asr_alias_invalid
没有配置	503	driver_asr_not_configured
配置损坏	503	driver_asr_config_invalid
读取配置失败	503	driver_asr_config_unavailable
选项不存在	404	driver_asr_option_not_found
选项禁用	403	driver_asr_option_disabled
真实模型已下架或不支持 ASR	503	driver_asr_model_unavailable

错误格式沿用 OpenAI {error:{message,type,code,param?}}。别名调用隐藏真实模型/供应商错误文案；其他鉴权、余额、供应商错误状态/代码沿用现有网关。请求时重新查当前配置和目录，不用过期别名缓存。driver-asr: 前缀永远只走别名，解析失败不会当真实模型、第一项或旧默认继续请求。

1.x 客户端选择规则

场景	Driver 行为
无持久化选择 + 配置成功	可用有效、启用的 defaultOptionId 初始化
已保存新 ID	保持该 ID；名称随当前语言 labels 更新
已保存 ID 被删/禁用	保留选择并提示不可用；不换成新默认或第一项
开发阶段保存了 transcribe-default 或真实模型 ID	不能猜测对应关系，提示重新选择
configured=false、空列表、配置非法或加载失败	分别提示未配置、无可用模型或错误；不回退早期映射

transcribe-default 是禁止使用的保留 ID，网关在查询配置前即返回 400 driver_asr_alias_invalid。不提供早期开发接口回退。0.x 的真实模型调用路径保留。

真实映射存 public.driver_transcription_config 私有单例表，启用 RLS/显式 deny-all，撤销 PUBLIC/anon/authenticated 读写权限，仅 service_role 可访问。site_settings 历史存储中的 cloud.transcriptionTiers 在公开与管理 client-config 输出时均被移除，新提交含此字段返回 400、issues code retired_driver_config；不执行生产数据清理。通用 App 的 cloud.asrModel/refineModel 字段仍保留，可在后台“高级 JSON → 通用 App 云端模型”编辑并点击“保存 App 配置”保存（例如省略 model 的通用转写请求使用 asrModel），这些不是 0.x Driver 默认设置，也不承诺隐藏历史公开模型数据。

迁移 20260908190000_driver_transcription_config.sql 只建私有表、ACL 和单调 revision 触发器，不初始化模型；不修改订阅/成本或旧配置。后端先上线，再上线管理页面，再由管理员选择真实模型列表，最后由 Driver 项目接入发行并真机验收。应用回滚保留私有表和 ACL；删除表前必须备份后续写入的配置并另行授权。

Driver 1.x 云端转写模型列表合同 ​

产品版本 ​

管理端 ​

公开配置 ​

语音调用 ​

1.x 客户端选择规则 ​

Driver 1.x 云端转写模型列表合同

产品版本

管理端

公开配置

语音调用

1.x 客户端选择规则