feat: 每平台可用模型范围 + 降级尝试 + 失败回报
配置页为每个 Agent 平台划定「邮件场景下可用的模型」，插件按顺序逐个尝试，
全部失败把原因封装成邮件回复。目录由插件上报、管理员只做勾选 —— 手打模型名
会打错，而打错的后果要到真发邮件时才暴露成一次失败。
## 目录上报走心跳，不另设端点
模型清单会在运行中变（换 provider 配置、上游上下线、换 API key）。
只在注册时报一次的话目录会静静变陈，管理员在配置页选中一个平台其实调不到的
模型。心跳本来就是 30 秒一次的现成通道；另设一个 POST 等于给「目录是谁写的」
留两个答案，排查时要同时看两处。
心跳响应回传 `allowed_models`，因此管理员改了范围后最多一个周期生效，
不必重启插件。
与 platform_sessions 同一约定：拉不到目录时**省略字段**（保留现有目录），
传空数组会把配置页清成空白。
## 目录与选择分两张表
模型会从平台目录里消失（上游临时下线、换了 provider 配置）。合成一张带
allowed 标记的表时，整行被删就连带把管理员的选择也删了，模型回来还得重配一遍。
分开存之后「选了什么」是持久的，目录只决定「这一项现在是否可用」；
已选但不在目录里的标为 stale 显示出来 —— 不显示会让人以为自己没选过它。
## 最难的一点：模型失败不是同步抛出的
两个平台都踩了。`promptAsync()` 立即返回、`ctx.agents.create()` 不校验模型，
只包 try/catch 的话第二个模型永远不会被试到 —— 第一个无效模型会被判成成功。
必须等异步结论：
- opencode → `session.error` 事件（event 钩子在 deliverMail 之外，
因此用 turnWatchers 表把两者接起来）
- DSH → `turn/end` 的 `reason.kind === 'error'`
DSH 还有个陷阱：**`assistant/chunk` 不能当成功信号**，它的 `finish` 子类型
也带错误 —— `{chunk:{type:'finish',reason:{kind:'error',failure:{code:'NO_ADAPTER'}}}}`。
实测「无效 provider 却判成功」正是因为把任意 chunk 当成了走通。判据要落在
chunk 的类型上：finish 看 reason，其余才意味着模型真的在产出。
超时按成功处理（60 秒窗口）：模型可能只是很慢，把慢当成失败会在换模型的同时
把已经在跑的那一轮丢掉。
DSH 换模型要换会话 id（`<原 id>-r1`）并 dispose 失败那个 agent：复用同一个 id
会让重试接在一条已经出错的会话后面，不 dispose 则 agent/status 还会为那个
死会话触发一次自动转发。
## 其他决策
- **范围优先于环境变量**：范围是运行时可改的策略，`AGENTMAIL_REPLY_*` 是部署时
的兜底。反过来的话管理员在配置页改了却不生效，得去改 service 文件重启
- **范围为空返回 `[undefined]` 而非 `[]`**：空数组会让调用方一次都不试，
而「管理员没配」的正确含义是不限定，不是「一个都不许用」
- **上限 10 个**：降级是串行的，选 50 个意味着最坏情况下一封邮件要等 50 次超时
- 前端 key 按**第一个** `/` 切分 provider/model：model id 可能含 `/`
（如 `org/model-name`），按最后一个切会把 provider 切错
- 保存后用服务端返回的结果刷新界面而非回显入参：repo 层会跳过重复与空字段
## 验证
- Go 10 个新测试（含「模型从目录消失后选择必须留存」的直接回归）
- 两插件各 18 个模型范围测试，共 180 个
- 端到端四轮：正常路由 → 全部无效（收到失败回报邮件，used_rounds 保持 0
确认走了免配额通道）→ DSH 降级（fake-a 失败 → llmsproxy/AUTO 成功）→
opencode 降级（nonexistent/bad 失败 → AUTO 成功，日志确认「前 1 个失败」）
- 生产已部署，前端「模型范围」页可用
This commit is contained in:
@ -31,6 +31,18 @@ type heartbeatRequest struct {
|
||||
// 空数组 = 平台侧确实一条会话都没有（清空镜像）。
|
||||
// 拿不到会话列表的插件应当省略该字段，而不是传空数组把镜像抹掉。
|
||||
PlatformSessions []repo.PlatformSession `json:"platform_sessions"`
|
||||
|
||||
// Models 是平台当前看得见的模型目录，供配置页勾选。
|
||||
//
|
||||
// 随心跳上报而不是只在注册时上报：模型清单会在运行中变
|
||||
// （换 provider 配置、上游上下线、换了 API key）。只在注册时报一次的话，
|
||||
// 目录会静静变陈，而管理员在配置页上看到的是上次重启时的快照 ——
|
||||
// 选中一个平台已经调不到的模型，失败要到真发邮件时才暴露。
|
||||
//
|
||||
// 与 PlatformSessions 同一约定：nil = 本次不上报（保留现有目录），
|
||||
// 空数组 = 平台确实一个模型都拿不到。拿不到目录时必须省略：
|
||||
// 清空目录会让配置页变成空白，管理员以为该平台没有任何可用模型。
|
||||
Models []repo.CatalogModel `json:"models"`
|
||||
}
|
||||
|
||||
// POST /api/v1/agent/register
|
||||
@ -143,6 +155,14 @@ func HeartbeatAgent(w http.ResponseWriter, r *http.Request) {
|
||||
}
|
||||
}
|
||||
|
||||
// 模型目录同理：写失败只让配置页看到的目录陈一轮，下一次心跳会补上。
|
||||
syncedModels := -1
|
||||
if req.Models != nil {
|
||||
if err := repo.ReplaceModelCatalog(r.Context(), agentName, req.Models); err == nil {
|
||||
syncedModels = len(req.Models)
|
||||
}
|
||||
}
|
||||
|
||||
// 心跳回传该 Agent 的累计统计与新任务默认预算。
|
||||
//
|
||||
// 不再回传「剩余额度」：额度属于具体任务（会话）而不属于 Agent，
|
||||
@ -161,6 +181,17 @@ func HeartbeatAgent(w http.ResponseWriter, r *http.Request) {
|
||||
if syncedSessions >= 0 {
|
||||
resp["platform_sessions_synced"] = syncedSessions
|
||||
}
|
||||
if syncedModels >= 0 {
|
||||
resp["models_synced"] = syncedModels
|
||||
}
|
||||
// 回传当前生效的模型范围，插件无需另起一个请求去读。
|
||||
//
|
||||
// 随心跳回传而不是让插件自己轮询：管理员在配置页改了范围后，
|
||||
// 插件最多一个心跳周期（30 秒）就能看到新值，不需要重启。
|
||||
if allowed, aErr := repo.ListAllowedModels(r.Context(), agentName); aErr == nil {
|
||||
resp["allowed_models"] = allowed
|
||||
resp["models_unrestricted"] = len(allowed) == 0
|
||||
}
|
||||
JSON(w, http.StatusOK, resp)
|
||||
}
|
||||
|
||||
|
||||
131
gateway/internal/handler/models_scope.go
Normal file
131
gateway/internal/handler/models_scope.go
Normal file
@ -0,0 +1,131 @@
|
||||
package handler
|
||||
|
||||
import (
|
||||
"net/http"
|
||||
"strings"
|
||||
|
||||
"github.com/agentmail/gateway/internal/middleware"
|
||||
"github.com/agentmail/gateway/internal/repo"
|
||||
"github.com/go-chi/chi/v5"
|
||||
)
|
||||
|
||||
// ---------- 邮件场景下的可用模型 ----------
|
||||
//
|
||||
// GET /agent/models/allowed 读取被允许的模型（Agent 凭证）
|
||||
// GET /admin/agents/{name}/models 管理员读目录 + 已选
|
||||
// PUT /admin/agents/{name}/models 管理员保存选择与优先级
|
||||
//
|
||||
// **目录上报走心跳**（见 agents.go 的 heartbeatRequest.Models），不另设端点：
|
||||
// 模型清单会在运行中变（换 provider 配置、上游上下线、换 API key），
|
||||
// 心跳本来就是 30 秒一次的现成通道。另设一个 POST 等于给「目录是谁写的」
|
||||
// 这个问题留两个答案，排查时要同时看两处。
|
||||
//
|
||||
// 生效的模型范围同样随心跳响应回传（allowed_models），因此插件通常不需要调
|
||||
// 下面这个 GET —— 它是给非插件的第三方客户端（没有心跳循环）与排查用的。
|
||||
|
||||
// GET /api/v1/agent/models/allowed —— 插件读取被允许的模型
|
||||
//
|
||||
// 返回按优先级排序的列表。空列表表示**不限定**，插件应回退到平台自己的默认模型
|
||||
// —— 与「一个都不许用」不同，后者等于让 Agent 彻底哑掉，不该是一次误配的后果。
|
||||
func GetAllowedModels(w http.ResponseWriter, r *http.Request) {
|
||||
agentName := middleware.GetAgentName(r)
|
||||
if agentName == "" {
|
||||
Error(w, http.StatusUnauthorized, "Unauthorized")
|
||||
return
|
||||
}
|
||||
models, err := repo.ListAllowedModels(r.Context(), agentName)
|
||||
if err != nil {
|
||||
Error(w, http.StatusInternalServerError, "Failed to list allowed models")
|
||||
return
|
||||
}
|
||||
JSON(w, http.StatusOK, map[string]any{
|
||||
"models": models,
|
||||
// unrestricted 明确表达「没配 = 不限」，省得插件自己去判断空数组的含义
|
||||
"unrestricted": len(models) == 0,
|
||||
})
|
||||
}
|
||||
|
||||
// GET /api/v1/admin/agents/{name}/models —— 管理员读目录（带已选标记）
|
||||
func AdminListAgentModels(w http.ResponseWriter, r *http.Request) {
|
||||
name := strings.TrimSpace(chi.URLParam(r, "name"))
|
||||
if name == "" {
|
||||
Error(w, http.StatusBadRequest, "Missing agent name")
|
||||
return
|
||||
}
|
||||
catalog, err := repo.ListModelCatalog(r.Context(), name)
|
||||
if err != nil {
|
||||
Error(w, http.StatusInternalServerError, "Failed to list model catalog")
|
||||
return
|
||||
}
|
||||
// 已选但已不在目录里的模型要单独给出来：平台可能临时下线了某个模型，
|
||||
// 界面上不显示的话管理员会以为自己没选过它，而它其实还在被插件尝试。
|
||||
stale, err := repo.ListStaleAllowedModels(r.Context(), name)
|
||||
if err != nil {
|
||||
stale = []repo.ModelRef{}
|
||||
}
|
||||
JSON(w, http.StatusOK, map[string]any{
|
||||
"agent_name": name,
|
||||
"catalog": catalog,
|
||||
"stale": stale,
|
||||
})
|
||||
}
|
||||
|
||||
// PUT /api/v1/admin/agents/{name}/models —— 管理员保存选择
|
||||
//
|
||||
// 入参顺序即优先级（rank）。插件按这个顺序逐个尝试，全部失败才回一封失败邮件。
|
||||
func AdminSetAgentModels(w http.ResponseWriter, r *http.Request) {
|
||||
name := strings.TrimSpace(chi.URLParam(r, "name"))
|
||||
if name == "" {
|
||||
Error(w, http.StatusBadRequest, "Missing agent name")
|
||||
return
|
||||
}
|
||||
|
||||
var req struct {
|
||||
Models []repo.ModelRef `json:"models"`
|
||||
}
|
||||
if err := Decode(r, &req); err != nil {
|
||||
Error(w, http.StatusBadRequest, "Invalid JSON")
|
||||
return
|
||||
}
|
||||
if len(req.Models) > maxAllowedModels {
|
||||
Error(w, http.StatusBadRequest,
|
||||
"选定的模型过多（上限 "+itoa(maxAllowedModels)+" 个）")
|
||||
return
|
||||
}
|
||||
|
||||
if err := repo.SetAllowedModels(r.Context(), name, req.Models); err != nil {
|
||||
Error(w, http.StatusInternalServerError, "Failed to save allowed models")
|
||||
return
|
||||
}
|
||||
// 回传保存后的实际结果而不是回显入参：repo 层会跳过重复项与空字段，
|
||||
// 回显入参会让前端以为那些也存下来了。
|
||||
saved, err := repo.ListAllowedModels(r.Context(), name)
|
||||
if err != nil {
|
||||
saved = []repo.ModelRef{}
|
||||
}
|
||||
JSON(w, http.StatusOK, map[string]any{
|
||||
"status": "saved",
|
||||
"models": saved,
|
||||
})
|
||||
}
|
||||
|
||||
// maxAllowedModels 限制管理员能选多少个模型。
|
||||
//
|
||||
// 降级尝试是串行的：选 50 个意味着最坏情况下一封邮件要等 50 次模型调用超时。
|
||||
// 十个已经足够表达「主力 + 几个备选」。
|
||||
const maxAllowedModels = 10
|
||||
|
||||
// itoa 避免为一个数字引入 strconv 导入（本文件只此一处用到）。
|
||||
func itoa(n int) string {
|
||||
if n == 0 {
|
||||
return "0"
|
||||
}
|
||||
var b [20]byte
|
||||
i := len(b)
|
||||
for n > 0 {
|
||||
i--
|
||||
b[i] = byte('0' + n%10)
|
||||
n /= 10
|
||||
}
|
||||
return string(b[i:])
|
||||
}
|
||||
Reference in New Issue
Block a user