# 实现依据与边界

## 核对来源（2026-09-13）

- 正在运行的公共 OpenAPI：`https://api.polyhaven.com/api-docs/swagger.json`
- 官方项目 API 定义：`https://github.com/Poly-Haven/Public-API/blob/master/swagger.yml`
- 官方入口与路线：`https://github.com/Poly-Haven/Public-API/blob/master/app.js`
- 官方服务条款：`https://github.com/Poly-Haven/Public-API/blob/master/ToS.md`
- 本机 aardio：`lib/web/rest/client.aardio`、`jsonLiteClient.aardio`、`github.aardio`、`inet/http.aardio`、`inet/url.aardio`。
- 本机范例：`examples/Web/REST/QuickStart.aardio`、`receiveFile.aardio`。

这是独立的 aardio 客户端实现，没有把 AGPL API 服务端代码复制到本库。

## 关键设计

- 延续 `web.rest.github` 的继承方式：`this=web.rest.jsonLiteClient(config)`，设置 `defaultUrlTemplate` 与 GET 动词，使用 `api().resource[id].get()`。
- 不复刻 HTTP/JSON/代理/错误框架。下载使用继承的 `receiveFile`；先检查其返回值，不直接链式调用可能失败的打开文件操作。
- 元数据与下载保持不同职责：plan 可以检查/序列化；下载可离线读取 plan，仅传输清单上的文件。
- 文件是主文件＋相对依赖的最小资产包，不预先下载所有变体，也不自动启动 Blender。
- TLS 证书错误不忽略；此客户端显式关闭底层默认的忽略证书错误选项。

## 实测发现的 web.rest 接入点

1. `inet.url.encodeMbcs` 只处理多字节字符，ASCII 空格不编码。作者名 `Andreas Mischok` 的请求自身可成功，但底层将旧 URL 用作下次请求 Referer，随后 `getInfo` 会出现 `beginSendData ERROR CODE:0xD(13)`。本库把 `encodeKey` 设置为 `inet.url.encode`，完整编码路径片段，已加入作者→元数据连续请求回归测试。未改动标准库。
2. `receiveFile` 回调中的 `recvSize` 为累计已接收量，而非仅当前块长度。下载取消时底层仍可能返回 true，因此库显式记录取消，并在改名之前校验。
3. `receiveFile` 在回调前已经写当前块。大小上限可在下一次读取前终止，不声称是精确到字节的网络流量限制；计划预算在下载前检查，完整性在写入后检查。
4. file-level rename 不代表整个目录原子提交。失败报告保留已完成项，供下次校验复用。

## 不包含

- 不包装私有/管理/未文档化端点。
- 不实现整站爬取、并行下载、自动重试、Range 续传、下载队列或 API 元数据永久缓存。
- 不在本库加入 bpy、MCP、贴图节点自动连线、场景替换或导入抽象层。
- 不创建自动刷新任务，不修改系统代理、安全配置、Blender 偏好、其他标准库或技能包。
- 不声称所有 Poly Haven 资产、所有格式和未来 API 版本均已验证；已验证 Blender 的三类样本，通用文件选择及 include 按服务端实际结构处理。