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:
@ -254,7 +254,95 @@ POST /api/v1/sessions/{id}/sync { alias?, title? }
|
||||
|
||||
---
|
||||
|
||||
## 五、平台差异对照
|
||||
## 五、模型范围与降级尝试
|
||||
|
||||
管理员在配置页为每个平台划定「邮件场景下可用的模型」。插件按顺序逐个尝试，
|
||||
全部失败才回一封说明失败原因的邮件。
|
||||
|
||||
### 上报目录
|
||||
|
||||
随心跳带 `models`（与会话快照同一个请求）：
|
||||
|
||||
```json
|
||||
{ "models": [
|
||||
{ "provider": "llmsproxy", "model": "AUTO", "display_name": "AUTO (smart routing)" }
|
||||
] }
|
||||
```
|
||||
|
||||
**为什么随心跳而不是只在注册时报一次**：模型清单会在运行中变（换 provider
|
||||
配置、上游上下线、换 API key）。只在注册时报的话目录会静静变陈，管理员在配置页
|
||||
选中一个平台其实调不到的模型，失败要到真发邮件时才暴露。
|
||||
|
||||
与 `platform_sessions` 同一约定：拉不到目录时**省略该字段**（保留服务端现有目录），
|
||||
传空数组会把配置页清成空白。
|
||||
|
||||
| 平台 | 目录来源 |
|
||||
|---|---|
|
||||
| opencode | `client.config.providers()` → `providers[].models` 是**对象**，键是 model id |
|
||||
| DSH | `ctx.llm.listProviders()` 再逐个 `listModels(provider)` |
|
||||
|
||||
### 读取生效范围
|
||||
|
||||
心跳响应回传 `allowed_models`（按优先级）与 `models_unrestricted`。
|
||||
插件存在模块级变量里，下次投递时用 —— 管理员改了范围后最多一个心跳周期
|
||||
（30 秒）生效，不需要重启。
|
||||
|
||||
也有 `GET /agent/models/allowed`，但那是给没有心跳循环的第三方客户端与排查用的。
|
||||
|
||||
### 尝试顺序
|
||||
|
||||
共用实现 `lib/model-scope.js` 的 `modelAttemptOrder(allowed, envDefault)`：
|
||||
|
||||
| 情形 | 返回 |
|
||||
|---|---|
|
||||
| 管理员划定了范围 | 按 rank 顺序的路由列表 |
|
||||
| 没划定，但配了 `AGENTMAIL_REPLY_*` | 环境变量那一个 |
|
||||
| 都没有 | `[undefined]` —— 交给平台自己选 |
|
||||
|
||||
**范围优先于环境变量**：范围是运行时可改的策略，环境变量是部署时的兜底。
|
||||
反过来的话管理员在配置页改了却不生效,得去改 service 文件重启。
|
||||
|
||||
**范围为空时返回 `[undefined]` 而不是 `[]`**：返回空数组会让调用方一次都不试,
|
||||
而「管理员没配」的正确含义是不限定，不是「一个都不许用」。
|
||||
|
||||
### 判定一次尝试是否成功 —— 这里最容易错
|
||||
|
||||
**两个平台的模型失败都不是同步抛出的。** 只包一个 try/catch 的话第二个模型
|
||||
永远不会被试到：
|
||||
|
||||
| 平台 | 提交调用 | 失败从哪来 |
|
||||
|---|---|---|
|
||||
| opencode | `promptAsync()` 立即返回 | `session.error` 事件 |
|
||||
| DSH | `ctx.agents.create()` 不校验模型 | `turn/end` 的 `reason.kind === 'error'` |
|
||||
|
||||
DSH 侧还有一个陷阱：**`assistant/chunk` 本身不能当成功信号**，它的 `finish`
|
||||
子类型也带错误 ——
|
||||
|
||||
```json
|
||||
{"chunk": {"type": "finish", "reason": {"kind": "error", "failure": {"code": "NO_ADAPTER"}}}}
|
||||
```
|
||||
|
||||
实测踩过一次「无效 provider 却判成功」正是因为把任意 chunk 当成了走通。
|
||||
判据要落在 chunk 的类型上：`finish` 看 reason，其余（`block-start`、
|
||||
`text-delta`、`tool-call-delta`…）才意味着模型真的在产出。
|
||||
|
||||
**超时按成功处理**：模型可能只是很慢（首 token 前要装载上下文），
|
||||
把慢当成失败会在换模型的同时把已经在跑的那一轮丢掉。窗口取 60 秒。
|
||||
|
||||
DSH 侧换模型要**换会话 id**（`<原 id>-r1`）并 `dispose()` 失败那个 agent：
|
||||
复用同一个 id 会让重试接在一条已经出错的会话后面，而不 dispose 的话
|
||||
`agent/status` 还会为那个死会话触发一次自动转发。
|
||||
|
||||
### 全部失败时必须发信
|
||||
|
||||
模型一次都没跑起来时会话里没有任何 assistant 消息，自动转发因此什么也不会发
|
||||
—— 发件人只会看到邮件发出去后再无音讯。
|
||||
|
||||
`renderFailureReport(failures, subject)` 生成正文（逐条列出路由与原因，
|
||||
并指出去哪里调整）。这封信带 `relay: 'summary'` 走免配额通道：
|
||||
它是插件的故障报告，不是模型的自主发信。
|
||||
|
||||
## 六、平台差异对照
|
||||
|
||||
| 关注点 | opencode | DeepSeek Harness |
|
||||
|---|---|---|
|
||||
@ -265,12 +353,14 @@ POST /api/v1/sessions/{id}/sync { alias?, title? }
|
||||
| 一轮结束 | `session.idle` 事件 | `agent/status` → `idle` |
|
||||
| 权限钩子 | `permission.ask`（同步，不能等） | `approval/request`（异步 waterfall，能等） |
|
||||
| 会话列表 | `client.session.list()` | `ctx.sessionQuery.listSessions()` |
|
||||
| 模型目录 | `client.config.providers()` | `ctx.llm.listProviders()` + `listModels()` |
|
||||
| 模型失败信号 | `session.error` 事件 | `turn/end` 的 `reason.kind==='error'` |
|
||||
| 别名来源 | `session.slug` | 模型标题派生 |
|
||||
| 日志可见性 | `console.error` | `console.error`（`ctx.logger` 不进 journalctl） |
|
||||
|
||||
---
|
||||
|
||||
## 六、踩过的坑
|
||||
## 七、踩过的坑
|
||||
|
||||
按「排查成本」降序。新接平台时先扫一遍这一节。
|
||||
|
||||
@ -342,7 +432,7 @@ opencode 还有个额外问题：**插件是懒加载的**，进程起来了插
|
||||
|
||||
---
|
||||
|
||||
## 七、新平台适配清单
|
||||
## 八、新平台适配清单
|
||||
|
||||
```
|
||||
[ ] 1. 认证与连接
|
||||
@ -373,13 +463,20 @@ opencode 还有个额外问题：**插件是懒加载的**，进程起来了插
|
||||
[ ] 转不出去就让位给本地 UI
|
||||
[ ] 拆插件时未决询问 fail closed
|
||||
|
||||
[ ] 6. 命名与快照
|
||||
[ ] 6. 模型范围（复用 lib/model-scope.js）
|
||||
[ ] 心跳带 models（拉不到就省略，别传空数组）
|
||||
[ ] 心跳响应读回 allowed_models
|
||||
[ ] 按 modelAttemptOrder 逐个尝试
|
||||
[ ] **等异步结论**再判成功／失败（失败不是同步抛的！）
|
||||
[ ] 全部失败 → renderFailureReport + relay:'summary' 发信
|
||||
|
||||
[ ] 7. 命名与快照
|
||||
[ ] alias/title 回写 POST /sessions/{id}/sync
|
||||
[ ] slug 去掉 . @ / 等寻址分隔符
|
||||
[ ] 心跳带 platform_sessions（复用 lib/session-snapshot.js）
|
||||
[ ] 过滤 subagent、slug 去重
|
||||
|
||||
[ ] 7. 工程
|
||||
[ ] 8. 工程
|
||||
[ ] 可测逻辑放 lib/，入口保持最小
|
||||
[ ] 纯函数测试纳入 deploy/install.sh 的门禁
|
||||
[ ] 端到端：发一封 → 会话建在正确 cwd → 自动回信 → 别名可续谈
|
||||
@ -387,7 +484,7 @@ opencode 还有个额外问题：**插件是懒加载的**，进程起来了插
|
||||
|
||||
---
|
||||
|
||||
## 八、共用模块
|
||||
## 九、共用模块
|
||||
|
||||
`lib/` 下的文件在两个插件里**逐字节相同**，接新平台时直接拷。
|
||||
它们只依赖 node 内置模块，不碰任何平台 SDK。
|
||||
@ -398,6 +495,7 @@ opencode 还有个额外问题：**插件是懒加载的**，进程起来了插
|
||||
| `inbox-format.js` | 收件箱渲染 + 已读策略 |
|
||||
| `session-snapshot.js` | 平台会话快照整理（含 subagent 过滤、slug 派生） |
|
||||
| `workspace.js` | 寻址 path 位 → 可用的 cwd |
|
||||
| `model-scope.js` | 模型目录整理 + 降级顺序 + 失败报告 |
|
||||
| `message.js` | DSH 的消息构造与会话日志读取（DSH 专用） |
|
||||
|
||||
`test/` 下对应的测试文件同样逐字节共用。
|
||||
|
||||
Reference in New Issue
Block a user