> For the complete documentation index, see [llms.txt](https://submodel.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://submodel.gitbook.io/docs/jian-ti-zhong-wen/ban-ben-fa-bu/preview-20260803.md).

# preview-20260803

**发布日期：** 2026年8月3日

本次发布覆盖 `preview-20260803` API 标签的全平台更新，包含 Discovery 推荐引擎、SDK 层重写、完整文档以及自动化测试套件（148 个单元测试全绿）。

***

## 核心亮点

* **Discovery API** — 无状态、可解释的 GPU 方案推荐引擎（最多3个候选、确定性排序，决策链路中无 LLM）。
* **SDK 重写** — `ServerlessWorker` 取代旧版 `ServerlessHandler`；异常码 40100/40400 现在映射到类型化异常；`_requests` 端点 URL 路径已修正。
* **自动充值 UI** — 新增账单页面，支持配置触发阈值和充值金额，并管理已保存的支付方式。
* **日志查看器重构** — `v-html` 注入路径已做 XSS 防护（先转义再高亮），WebSocket 实时流式推送，支持批量处理和断线重连。
* **测试自动化** — 148 个 Python SDK 测试、3 套 Vue 单元测试、2 套后端纯函数测试。SDK 及单元级别的验收无需再启动完整前后端。

***

## 新增功能

### Discovery API（`backend-source`）

* `POST /api/v1/discovery/recommend` — 根据用户意图（mode、gpu\_count、gpu\_mem\_min、area、billing、sort\_priority、max\_price）返回已排名的 GPU 方案候选列表，严格过滤为当前认证用户可见的方案，最多3个候选。
* `POST /api/v1/discovery/event` — 隐私安全的只追加生命周期事件日志；仅允许白名单字段（EL-REQ-001/002）。
* `GET /api/v1/discovery/metrics` — 仅管理员可访问的聚合指标，含最小队列规则（EL-REQ-004/006）。
* 功能开关默认 **关闭**（`DISCOVERY_ENABLED`、`DISCOVERY_EVENT_WRITE`、`DISCOVERY_BASELINE`）——通过 trust-gate 前仅做影子探索（EL-REQ-005）。

### Python SDK（`submodel-sdk-python`）

* `ServerlessWorker` 为正式类名（原名 `ServerlessHandler`）。
* `exceptions.py` — 新增码 40100 → `AuthenticationError`；码 40400 → `ResourceNotFoundError`。
* `endpoint.py` — 修正 `get_requests()` 和 `get_request_details()` 使用 `/_requests` 路径。
* 完整测试套件：6 个模块共 148 个测试，全部通过。

### 前端（`webapp-source`）

* **AutoRecharge.vue** — 新增账户页面：开启/关闭自动充值、选择触发阈值（分）和充值金额（美元）、添加/移除已保存支付方式。
* **LogViewer.vue** — XSS 修复：`highlightSearchTerm()` 在正则替换和 v-html 注入前先对内容进行 HTML 转义。WebSocket 鉴权 token 通过消息体发送（不经过 URL）。高吞吐量日志流的批量处理优化。
* **DeploymentAssistant.vue** — 推荐面板已对接 Discovery API。

### 文档

* 新增 SDK 章节（中英文）：CLI 参考、Pod API、Serverless API、Storage API。
* Billing Information 页面新增自动充值章节（中英文）。
* 两个语言版本的 SUMMARY.md 导航已更新。

***

## Bug 修复

| 组件                  | 修复内容                                                |
| ------------------- | --------------------------------------------------- |
| `sdk/exceptions.py` | 码 40100 现在抛出 `AuthenticationError`（原为 `APIError`）   |
| `sdk/exceptions.py` | 码 40400 现在抛出 `ResourceNotFoundError`（原为 `APIError`） |
| `sdk/endpoint.py`   | `get_requests()` 路径已修正为 `sl/{inst_id}/_requests`    |
| `LogViewer.vue`     | 日志消息内容在 v-html 注入前已转义（XSS 防护）                       |
| `LogViewer.vue`     | WebSocket token 不再出现在 URL query string 中            |

***

## 安全说明

* **EL-REQ-001/002** — Discovery 事件仅存储白名单字段；`password`、`command`、`env`、`image` 已从事件 schema 中永久排除。
* **EL-REQ-003** — 结果事件在服务端通过实例归属验证；客户端无法伪造 `inst_id` 或 `outcome`。
* **XSS** — 日志查看器对所有用户输入和服务端返回的内容在 `v-html` 注入前均进行转义。
* **WebSocket 鉴权** — Token 在握手后通过消息体发送，不出现在 URL 中，避免暴露于服务器访问日志和代理缓存。
* `onCreateInst` 仍为**唯一**允许的实例创建路径，本次未新增任何创建路由。

***

## 破坏性变更

* `ServerlessHandler` 已从公开 API（`submodel.sdk`）移除，请使用 `ServerlessWorker`。
* `__init__.py` 的 `__all__` 已同步更新。

***

## 测试覆盖

| 测试套件                           | 测试数 | 结果     |
| ------------------------------ | --- | ------ |
| Python SDK（`pytest`）           | 148 | ✅ 全部通过 |
| Vue 单元测试 — DeploymentAssistant | 25  | ✅ 已有   |
| Vue 单元测试 — LogViewer           | 28  | ✅ 新增   |
| Vue 单元测试 — AutoRecharge        | 12  | ✅ 新增   |
| 后端单元测试 — mod\_discovery        | 22  | ✅ 新增   |
| 后端单元测试 — mod\_discovery\_event | 18  | ✅ 新增   |

***

## 贡献者

内部发布 — Submodel 平台团队。