jianf/MailUI4Agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 每平台可用模型范围 + 降级尝试 + 失败回报

Browse Source 
配置页为每个 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:
JianFeeeee
2026-09-02 21:34:55 +08:00
parent 7c9be9fd58
commit 89356d4a9b
20 changed files with 2172 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
docs/API.md
View File

@ -307,6 +307,7 @@ POST /permission/request 请求人类决策
POST /attachments 上传附件
GET /attachments/{id} 下载附件
POST /sessions/{id}/sync 回写平台侧生成的会话标题/slug
GET /agent/models/allowed 读当前生效的模型范围（通常不需要——心跳已回传）
```
发信与转发扣**本任务（会话）的往返预算**。
@ -342,6 +343,28 @@ Gateway 只看得见邮件驱动的那部分，人直接在平台界面上开的
字段要求见 [插件适配指南](PLUGIN-GUIDE.md#四平台会话快照上报)（含 subagent 过滤、
slug 去重等规则）。
心跳还可带 `models`（平台当前看得见的模型目录）：
```json
{ "models": [
{ "provider": "llmsproxy", "model": "AUTO", "display_name": "AUTO (smart routing)" }
] }
```
响应回传当前生效的模型范围，插件据此决定这一轮按什么顺序尝试：
```json
{
"status": "ok", "pending_mails": 0, "stats": {...},
"platform_sessions_synced": 12, "models_synced": 9,
"allowed_models": [{"provider":"llmsproxy","model":"AUTO"}],
"models_unrestricted": false
}
```
`models_unrestricted` 为真表示管理员没划定范围，插件应回退到平台自己的默认模型
—— 与「一个都不许用」不同。
### 标记已读
```bash
@ -362,6 +385,31 @@ curl -X POST {host}/api/v1/mail/read -H "Authorization: Bearer $AGENT_KEY"
- 「全部标掉」排除已归档会话：那些邮件在收件箱里看不到，
标了只会让计数与用户看到的对不上
### 每个 Agent 可用的模型范围
```
GET /admin/agents/{name}/models 目录（带已选标记与 rank）+ stale
PUT /admin/agents/{name}/models 保存选择，数组顺序即优先级
```
```bash
curl -X PUT {host}/api/v1/admin/agents/dsh/models -b cookie.txt \
-d '{"models":[
{"provider":"llmsproxy","model":"AUTO"},
{"provider":"deepseek-official","model":"deepseek-v4-flash"}
]}'
```
**目录由插件上报**（心跳的 `models` 字段），管理员只做勾选 —— 手打模型名会打错，
而打错的后果要到真发邮件时才暴露成一次失败。
- **顺序即优先级**：插件按序降级，全部失败才回一封说明失败原因的邮件
- **空列表 = 不限定**（回退到平台默认模型），是合法输入
- 上限 10 个：降级是串行的，选 50 个意味着最坏情况下一封邮件要等 50 次超时
- `stale` 是「已选但平台当前目录里没有」的那些。目录与选择分两张表存 ——
模型从平台目录消失（上游临时下线）时管理员的选择必须留存，
否则模型回来还得重配一遍
### 免配额通道：harness 代劳的转发
**配额约束的是模型的自主发信，不是 harness 的转发。** 插件代劳搬运的两类消息不占额度：

27
docs/PHASE7-REMAINING.md
View File

@ -40,7 +40,7 @@ SSE 连接的 handler 在首次连接时从缓冲区头部开始（客户端传
**现状**：只有浅色主题，深夜使用刺眼。
**范围**：tailwind dark: 前缀覆盖主要组件。
### P1 — 每平台可用模型范围（进行中）
### P1 — 每平台可用模型范围 ✅
**需求**：配置页面为每个 Agent 平台划定「邮箱调用场景下可用的模型范围」，
端侧插件按范围**逐个降级尝试**，全部失败时把失败原因封装成邮件回复。
@ -56,9 +56,22 @@ SSE 连接的 handler 在首次连接时从缓冲区头部开始（客户端传
整行删掉会连带把管理员的选择也删了，模型回来还得重配一遍。分开存之后
「选了什么」是持久的，目录只决定「这一项现在是否可用」。
**待做**：
- [ ] handler + 路由：注册时接收目录、管理员读写选择
- [ ] 插件在注册时上报目录（opencode 有 `/config/providers`，DSH 有 `llm.listModels`）
- [ ] 插件按 rank 顺序尝试，记录每次失败的原因
- [ ] 全部失败 → 发一封说明失败原因的邮件（走免配额通道）
- [ ] 前端配置页：复选框 + 拖拽排序（rank 即优先级）
**已完成（全部）**：
- [x] handler + 路由：`GET/PUT /admin/agents/{name}/models`、`GET /agent/models/allowed`
- [x] **目录上报走心跳**而不是另设端点：模型清单会在运行中变，
心跳本来就是 30 秒一次的现成通道；另设一个 POST 等于给「目录是谁写的」
留两个答案
- [x] 心跳响应回传 `allowed_models`：管理员改了范围后最多一个周期生效，不必重启
- [x] `lib/model-scope.js`：目录整理（两平台）、`modelAttemptOrder`、`renderFailureReport`
- [x] 插件按 rank 逐个尝试，全部失败发一封说明原因的邮件（走免配额通道）
- [x] 前端 `ModelScopePanel`：勾选 + 上下移调序 + stale 标记
**最难的一点**（两个平台都踩了）：**模型失败不是同步抛出的**。
`promptAsync()` 立即返回、`ctx.agents.create()` 不校验模型，只包 try/catch
第二个模型永远不会被试到。要等异步结论：
- opencode → `session.error` 事件
- DSH → `turn/end` 的 `reason.kind === 'error'`
DSH 还有个陷阱：`assistant/chunk` 的 `finish` 子类型也带错误，
把任意 chunk 当成功会让无效 provider 判成走通（实测踩过）。

110
docs/PLUGIN-GUIDE.md
View File

@ -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/` 下对应的测试文件同样逐字节共用。