读取平台按名提供的只读资料集：列出资料键并读取某个键的文字，如云工作台环境命令读取的豫言标准库源码；宿主缓存大型资料，应用不必也不可在程序里解析整包资料。
源码浏览已生成；不能解析的文件以纯文本展示，不表示通过类型检查。
# 平台资料接口规范 0.1.0
本包让应用读取**平台按名提供的只读资料集**，而不必在程序里下载、解压、解析整包资料。云工作台的 AI Shell 命令「环境.列出」「环境.读取」要向模型展示豫言标准库的源码：这份资料是一个约 2.7 MB 的压缩包（解压后约 57 MB 的 JSON，键是文件路径、值是文字或 `{内容}`），豫言程序的 JSON 解析器不能也不该吞下它；宿主一次取回、解压、只保留应用有权看的那一部分键，并在同一宿主实例内缓存，应用只按键取用文字。任何“查阅平台随附的只读文字资料”的应用都可以用它。
## 函数
| 函数 | 类型 | 语义 |
| --- | --- | --- |
| `列出平台资料键 集名 前缀` | `字符串 → 字符串 → 字符串` | 返回资料集里键以「前缀」起首的全部键，形式是 JSON 字符串数组文字，按 UTF-8 字节序升序；前缀为空串则全部列出。 |
| `读取平台资料文字 集名 键` | `字符串 → 字符串 → （爻 合 字符串）` | 键存在返回（阳，文字），不存在返回（阴，空串）。 |
- **集名**：平台定义的资料集名，1 至 64 字节、不含控制字符（0 至 31 与 127）。云工宿主目前只有一个资料集：`标准库`，内容是豫言标准库的源码，键形如 `/库/标准库/数据结构/字符串术。豫`（以 `/库/标准库/` 起首，只收这一部分键，压缩包里的其他条目对应用不可见），值是该文件的文字。
- **前缀**至多 512 字节；**键**1 至 512 字节。
- **限额**：一个资料集至多列出 4096 个键，列表 JSON 文字至多 1 MiB；单个条目文字至多 2 MiB（更大的条目视为不存在，也不会被列出）。
- **失败**：集名不合规、未知、宿主没有授权它所依赖的服务绑定、资料取不到或格式不对，一律抛出**可捕获**的豫言异常，消息为 `未知的平台资料集：<集名>`、`未授权的平台资料集：<集名>` 或 `<集名>资料不可用`（对云工的 `标准库`，就是 `标准库资料不可用`，与旧云工作台一致）。资料不可用后，下一次调用会重新取。参数越限（集名、前缀、键的长度或字符）抛出 `平台资料参数无效`。
## 云工的实现约定（供适配与宿主）
云工把资料集 `标准库` 映射到许可里授权的服务绑定 `BROWSER_COMPILER` 上的 `https://playground.yuyan-lang.org/编译/资源/标准库.json.gz`：宿主用 `DecompressionStream('gzip')` 解压并解析成对象，只保留键以 `/库/标准库/` 起首且值是字符串（或带字符串 `内容` 字段的对象）的条目，其余立即丢弃；结果按宿主实例缓存（同一持久对象的所有事件共享一份），取用失败时不缓存。应用的 `许可.json` 因此要在 `SERVICE` 里列出 `BROWSER_COMPILER`。
## 一致性样例
设资料集 `标准库` 里有三个键：`/库/标准库/总集。豫`（文字 `首行\n次行\n末行`）、`/库/标准库/数据结构/整数操作。豫`（文字 `整数正文`）和压缩包里的另一个条目 `/库/其他/旁支。豫`：
- `列出平台资料键 『标准库』 『』` 返回 `["/库/标准库/总集。豫","/库/标准库/数据结构/整数操作。豫"]`（不含旁支）；`列出平台资料键 『标准库』 『/库/标准库/数据结构/』` 只返回后一个。
- `读取平台资料文字 『标准库』 『/库/标准库/总集。豫』` 得（阳，`首行\n次行\n末行`）；键 `/库/标准库/无此文。豫` 得（阴，空串）；`/库/其他/旁支。豫` 也得（阴，空串）。
- 未知集名 `不存在` 抛「未知的平台资料集：不存在」；服务绑定未授权抛「未授权的平台资料集：标准库」；服务返回非 2xx 抛「标准库资料不可用」，随后服务恢复时再调用成功；压缩包不是有效 gzip 或 JSON 同样抛「标准库资料不可用」。
- 集名为空、65 字节、含换行，键为空或 513 字节，前缀 513 字节，都抛「平台资料参数无效」。
- 同一宿主实例内连续调用一百次，只向服务取一次资料。
## 边界
本包只读；不提供写入、按内容搜索、目录树或二进制资料；不授予访问服务绑定的一般能力（资料集到服务的映射由宿主固定）。资料的更新由平台负责（宿主实例重建后重新取）。
# 平台资料公约 0.1.0
此包使客读**平台按名所供之只读资料集**，不必于程序中自下载、解压、解析全包。云工作台之 AI Shell 命令「环境.列出」「环境.读取」，欲示模型以豫言标准库之源：其资料乃约二兆七之压缩包（解之约五十七兆之 JSON，键为文件之径，值为文或 `{内容}`），豫言程序之 JSON 解析器不能亦不当吞之；宿主一取而解之，惟留客所当见之键，并于同宿主实例内缓之，客但依键取文。凡“查平台随附之只读文字资料”者，皆可用之。
## 术
- `列出平台资料键 集名 前缀`，返字符串：返资料集中键以「前缀」起首者之全，形为 JSON 字符串数组之文，依 UTF-8 字节序升；前缀空则全列。
- `读取平台资料文字 集名 键`，返（爻 合 字符串）：键在则（阳，文），不在则（阴，空串）。
- **集名**：平台所定之名，一至六十四字节，不含控制之字（零至三十一与一百二十七）。云工宿主今惟一集：`标准库`，其内容乃豫言标准库之源，键如 `/库/标准库/数据结构/字符串术。豫`（以 `/库/标准库/` 起首，惟收此部之键，压缩包中他条于客不可见），值为其文。
- **前缀**至多五百一十二字节；**键**一至五百一十二字节。
- **限**：一集至多列四千零九十六键，列表 JSON 文至多一 MiB；单条之文至多二 MiB（更大者视为无，亦不列）。
- **败**：集名不合、未知、宿主未授其所依之服务绑定、资料取之不得或式不合，皆抛**可捕**之豫言异，辞曰 `未知的平台资料集：<集名>`、`未授权的平台资料集：<集名>` 或 `<集名>资料不可用`（于云工之 `标准库`，即 `标准库资料不可用`，同旧云工作台）。资料不可用之后，再调则重取。参数越限（集名、前缀、键之长或字）抛 `平台资料参数无效`。
## 云工之实现约
云工以资料集 `标准库` 映于许可所授服务绑定 `BROWSER_COMPILER` 上之 `https://playground.yuyan-lang.org/编译/资源/标准库.json.gz`：宿主以 `DecompressionStream('gzip')` 解而析为对象，惟留键以 `/库/标准库/` 起首且值为字符串（或带字符串 `内容` 字段之对象）者，余悉弃之；果依宿主实例而缓（同一持久对象诸事件共一份），取败则不缓。应用之 `许可.json` 因须于 `SERVICE` 列 `BROWSER_COMPILER`。
## 一致性样例
设资料集 `标准库` 有三键：`/库/标准库/总集。豫`（文 `首行\n次行\n末行`）、`/库/标准库/数据结构/整数操作。豫`（文 `整数正文`）与压缩包中另一条 `/库/其他/旁支。豫`：
- `列出平台资料键 『标准库』 『』` 返 `["/库/标准库/总集。豫","/库/标准库/数据结构/整数操作。豫"]`（不含旁支）；前缀 `/库/标准库/数据结构/` 则只返后者。
- `读取平台资料文字 『标准库』 『/库/标准库/总集。豫』` 得（阳，`首行\n次行\n末行`）；键 `/库/标准库/无此文。豫` 得（阴，空串）；`/库/其他/旁支。豫` 亦得（阴，空串）。
- 未知集名 `不存在` 抛「未知的平台资料集：不存在」；服务绑定未授抛「未授权的平台资料集：标准库」；服务返非二百抛「标准库资料不可用」，其后服务复原再调则成；压缩包非有效 gzip 或 JSON 亦抛「标准库资料不可用」。
- 集名空、六十五字节、含换行，键空或五百一十三字节，前缀五百一十三字节，皆抛「平台资料参数无效」。
- 同宿主实例内连调一百次，惟向服务取资料一次。
## 界
此包只读；不供写入、依内容搜索、目录树与二进制资料；不授一般访服务绑定之能（资料集至服务之映，宿主固定之）。资料之更新，平台任之（宿主实例重建则重取）。