tilebox-ingesting-datasets

将数据集摄取到 Tilebox

为离散场景、采集、产品及其他符合 Tilebox 时间或时空目录模型的记录，设计并实现可重复使用的转换器。STAC 是首选且文档最完善的输入格式；只要其依据足以确立相同的规范语义，也支持提供商 XML/JSON、API、存储桶和文件树。

操作约定

每个新摄取器都必须遵循以下规则：

1. 设计架构前先检查适用性。 Tilebox 目录数据集表示具有稳定身份、时间且通常具有几何信息的离散记录。不要从分析就绪的多维数据立方体中的块或切片构造场景记录。
2. 先发现，再创建。 提议字段或 Tilebox 集合前，检查有代表性的记录、源集合、文件布局和已知变体。
3. 生成干净、现代的 STAC 模型，而非源数据镜像。 设计 Tilebox 字段前，将较旧的 STAC 和非 STAC 输入规范化为规范的 STAC 1.1 和当前稳定的扩展语义。用现代等效属性替换已弃用属性；若其语义已在其他位置保留，则省略冗余的旧属性；原始源路径仅保留在转换配方中。
4. 仅将专用 STAC 结构保留为专用结构。 必需的空间字段使用 Geometry。STAC 专用的结构化数据集字段仅限 Assets、Links、Provider、ProcessingSoftware、Storage 和 Authentication。将 Item 级扩展属性组（如 SARProperties、SatelliteProperties 和 ProductProperties）展平为类型化字段；枚举可以保留枚举类型。不要展平 Asset 级或 Band 级元数据，以免丢失其关联关系。
5. 优先使用权威类型化值。 对于标准 STAC 扩展属性，应根据现代规范扩展 JSON Schema 推导目标类型，而不是依据其 README 表格或仅依据观测到的 JSON；仅使用旧版架构解析旧版输入。将语义上表示整数的源十进制字符串转换回最窄且正确的 Tilebox 整数类型。除非规范字段本身定义为任意 JSON，否则不要使用 JSON 字符串、google.protobuf.Value 或 Struct 来绕过不确定的源类型。
6. 遇到歧义时绝不猜测或静默丢弃元数据。 停下来，展示依据并提出备选方案，然后将用户的决定记录到转换配方中。
7. 在转换器中进行源数据规范化。 每个转换器都必须验证其源数据，并负责提供商特定的解析和 STAC 1.1 规范化，包括将提供商的处理级别字段映射为规范的 processing:level 值。
8. 通过 Tilebox CLI 创建并检查架构。 将架构发现和创建明确列为工作流步骤，不要将其放入摄取程序中。
9. 批量摄取前先验证。 从 Tilebox 查询有代表性的样本，并比较其规范语义，确认无误后再启用完整运行。

选择相关参考资料

只阅读与数据源和实现语言相关的参考资料。默认使用 Python。仅当用户明确要求使用 Go，或工作属于现有 Go 转换器项目时，才使用 Go。

参考资料	适用情况
reference/source-discovery-and-recipe.md	始终阅读。判断数据源是否适合 Tilebox，检查有代表性的差异，设计集合，并持久化决策。
reference/canonical-stac-1.1.md	始终阅读。规范化 STAC 核心字段、扩展、链接、媒体类型、角色和云位置。
reference/non-stac-and-file-tree-sources.md	数据源为 XML、非 STAC API、对象存储前缀、COG 目录或其他文件树时。
reference/stac-protobuf-mapping.md	设计 Tilebox 架构，并将规范值映射到已知消息或生成字段时。
reference/python-converter.md	默认实现路径。使用 tilebox-python 及其高级语义 Assets API。
reference/go-converter.md	用户明确要求使用 Go，或现有转换器项目以 Go 编写时。生成数据集类型，并使用 tilebox-go 导入数据。
reference/asset-profile-wire-format.md	仅用于 Go 的低级 Asset 配置优化和线缆编码。Python 无需阅读：AssetCollection 会自动处理这些内容。
reference/validation.md	测试数据源验证、规范语义、已编译消息、回查行为和完整导入时。
reference/examples/earth-search-sentinel-2.md	处理旧版 Band 数组、源优先级备用项和实用可查询字段时。
reference/examples/optical-and-hyperspectral.md	处理光学／高光谱边缘情况，例如有范围的修复、重叠集合或容器 Bands 时。
reference/examples/sar.md	处理 SAR／测高边缘情况，例如空 href、跨目录 Assets 和 Band 范围频率时。
reference/examples/authenticated-assets.md	对需要身份验证的位置、Storage 和 Authentication 建模时，包括 Copernicus Data Space 模式。

工作流

阶段 A — 探索并决策

阅读 reference/source-discovery-and-recipe.md 和适用的数据源参考资料。制定转换方案，涵盖有代表性的差异、规范语义、架构字段、标识、修订、集合路由和不支持的元数据。重要决策尚未解决前，不要创建数据集。

阶段 B — 设计并创建

阅读 reference/stac-protobuf-mapping.md，刷新 tilebox dataset create 元数据，然后通过 CLI 创建经过评审的架构和集合。生成类型或转换器代码前，先检查最终契约。非空数据集可以增加兼容字段，但绝不能重新指定现有字段的类型、重命名、删除、重新排序或重新编号。

阶段 C — 实现转换

根据 Python 或 Go 参考资料实现转换方案。转换器负责验证数据源结构、仅应用有文档记录的数据源／版本规范化、构建规范语义并路由数据点；它不负责探索或创建架构。将相对 href 解析为路径或 URI，不要逐个请求所有对象。

阶段 D — 验证并导入

阅读 reference/validation.md。在启用幂等且可观测的批量导入前，使用有界样本验证数据源、规范语义、SDK 和 Tilebox 回查行为。对于 COG，当用户需要窗口化读取时，验证有代表性的交付路径是否支持字节范围访问。Tilebox 没有 STAC 输出接口，因此应比较重建的语义，而不是要求正式的 STAC 导出。

为公开用户编写文档

将数据集描述视为面向希望发现和使用数据的用户的产品文档，而不是数据摄取报告。请在交接前编写，并使用 tilebox dataset update --description-file 发布。

内容应简洁实用：

• 说明任务或源计划、数据集包含的内容、覆盖范围或采集频率方面的注意事项，以及许可证，并引用权威来源链接；
• 列出可用的资源系列、各自包含的内容，以及用户在常见工作流中应选择的产品；
• 说明数据存储位置、是否需要凭据或请求方付费访问，以及提供哪些 HTTPS、S3 或其他位置；以及
• 如果数据集支持规范 Assets API，请提供一个简短示例，演示如何查询一个数据点、使用 AssetCollection.from_datapoint(...) 对其解码，以及通过 tilebox.storage.aio 读取或下载资源。

不要公开转换器机制、字段映射决策、去重规则、跳过的辅助记录、规范化细节、验证说明或其他仅供实现使用的信息。只有在有助于用户理解科学内容或覆盖范围时，才提及特定来源的子集或地点。请根据实时数据和权威文档核实链接、资源名称、访问要求及定量任务声明。

适用性与停止条件

如果源数据的自然记录是具有稳定标识、可靠时间、有意义边界和实用目录元数据的离散场景、采集、观测或产品，则适合接入。可直接使用分析就绪的 Zarr 或 Icechunk 数据立方体；只有在确有具体需求时，才对上游采集清单或真实产品记录编目。

有证据支持明确方案时，应直接推进，不要提出不必要的选项。仅在权威证据无法确定以下事项时才停止并询问：

• 标识、时间、几何形状、记录边界、去重或集合路由；
• 稳定的字段类型／名称，或旧版 Band 数组的对齐方式；
• 未知封闭值或含义模糊的源值；
• 嵌套元数据或源身份验证的有效表示方式；
• 相对或空 href 的确切基址／解析器；或
• 无损的云端替代项或文件树推断规则。

请展示代表性记录、源路径和规范路径、观测到的值／类型、拟议决策、备选方案及其后果。对于不受支持的身份验证，必须明确警告该身份验证无法以规范形式表示。将答案保存在配方中。

责任边界

源转换器负责：

• 发现断言和源数据验证；
• 提供商专用的解析和规范化；
• 规范 STAC 1.1 语义；
• 语义 Asset、Band、Link、Storage 和 Authentication 值；
• 生成的数据集属性值；
• 去重和集合路由；以及
• 可观测性和数据摄取控制。

Python 语义 Assets API 负责应用 STAC Asset／Band 继承规则、验证完整的语义 Assets 及其位置，并生成 Assets、Storage 和 Authentication 数据集字段。Python 转换器提供语义值，不要手动重新创建这些生成的消息。

Go 目前没有等效的高级 API；请将直接线格式构造隔离开，遵循高级参考，并为其编写黄金往返测试。

预期项目交付物

完成后的摄取项目包含：

• 一份记录了证据和策略决策的转换方案文档；
• Tilebox 模式源文件和数据集文档；
• 可重复执行的源数据转换器和摄取命令；
• 有代表性的源数据样例，包括格式错误和已规范化的案例；
• 规范的语义、幂等性、集合路由和查询回测；
• 关于凭据、修订、重试和完整摄取的操作指南。

不要构建通用模式生成脚本。Agent 会与用户一起完成探索和模式设计；提交的程序则根据已记录的约定转换并摄取记录。