实现依据与边界

核对来源（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 按服务端实际结构处理。

Markdown 格式