WildDatum

WildDatum

WildDatum 是一个本地优先的生态数据工作台，以标准 Model Context Protocol 服务的形式提供。它让 Codex、Claude 和其他 MCP Agent 能够发现、物化、查询、可视化、选择和引用科学数据，而无需将凭据、私有路径或数百万行数据放入模型上下文。

NEON 以及来自 EMSO ERIC、ICOS Carbon Portal 和 Euro-Argo/Ifremer 的公共 ERDDAP 服务均为内置远程数据提供方。本地表格、栅格、矢量、点云、图像、高光谱和 N 维数组数据源使用相同的、与提供方无关的清单、查询、视图、选择和溯源模型。

“将这个 NEON LiDAR 瓦片与它的高光谱立方体进行比较。把它们放在一起显示，让我选择单个回波或图像像素，然后查询我所选内容背后的确切源点或光谱。”

一次真实的 WildDatum 浏览器会话，使用 Rerun Web Viewer：一个包含 660 万个点的 NEON LAS 瓦片、一个 500×500×107 的反射率立方体、不可变溯源，以及一个已验证且映射回 LAS 源行 2,543,044 的选择。

人与 Agent 的协作循环

scientific question
    → discover products, sites, and local assets
    → construct and approve a reproducible data plan
    → materialize immutable, checksum-verified sources
    → query and render a bounded multimodal Rerun view
    → human clicks, brushes, filters, or selects
    → WildDatum records that interaction as scientific state
    → agent queries the exact selected source data
    → export results, transformations, provenance, and citation

可视化不仅仅是一张供模型查看的图片。EcoViewSpec 是权威视图状态，SemanticSelection 是权威交互状态。Rerun 记录是可重新生成的渲染产物。对于经过验证的 WildDatum 点批次，实例拾取会映射回确切的 LAS/LAZ 源行；对于映射后的立方体，图像点击会映射回完整的源光谱。对于关联的轨迹和垂直剖面，地图或剖面上的点会映射回确切的物理 CSV/TSV、Parquet 或 Arrow 记录，包括提供方原生的 QC 值。

Alpha 版已实现的功能

• 一个标准的 MCP 2026-07-28 stdio 服务，可注册到 Codex 和 Claude Code。
• 公共 NEON 目录发现，以及可复现的计划、审批、后台物化、校验和、发布、许可证和引用处理。
• 公共 EMSO、ICOS ERDDAP 和 Euro-Argo 目录发现，以及经过验证的 tabledap/griddap 子集、支持重定向的审批、流式物化、许可证、引用和实时数据源溯源。
• 通过流式指纹识别进行的外部本地导入，以及面向 Agent 的不透明数据集 ID。
• Arrow/DataFusion 表格查询、空间栅格/矢量查询、索引 COPC 读取，以及有界 HDF5/NetCDF/Zarr N 维切片。
• 面向表格、图像、GeoTIFF、矢量、LiDAR、已映射科学立方体以及关联地理轨迹/垂直剖面的原生和浏览器 Rerun 视图。
• 持久化人工选择，可转换为带溯源链接的源查询，并在适用时导出为 CSV、Parquet、COG 或 RO-Crate。
• 语言中立的社区提供方子进程，采用与提供方无关的 v2 JSON-RPC 契约；RI 贡献者可以使用 Rust、Python、R、Go 或其他语言开发，无需添加提供方专用 MCP 工具。

Alpha.3：关联科学视图

主分支现在可以在不暴露私有路径的情况下，检查现有的本地或已物化数据集的科学结构：

wilddatum inventory ds_...
wilddatum suggest-views ds_lidar... ds_cube...
wilddatum create-suggested-view suggest_... ds_lidar... ds_cube...
wilddatum resolve-selection-links sel_...

对应的已注册 MCP 工具为 inspect_scientific_inventory 和 suggest_views；create_view_from_suggestion 接受其中一个不透明的 建议 ID，resolve_selection_links 则会在人工选择后评估适用规则。清单包含有界字段、 数组、坐标轴、单位、CF/QC 关系、证据和未解决的决策。在被接受之前，建议始终是确定性的， 且不产生副作用。接受建议后，WildDatum 会重新计算建议，拒绝客户端自行编造的 ID，并持久化 EcoViewSpec v2，其中包含明确的科学面板、编码和带版本号的关联规则。现有 v1 视图仍可读取。

对于官方 NEON 教学数据对，WildDatum 会读取 107 个测量波长，选取最接近 650/550/450 nm 的波段， 并将 3D 点云 + RGB + 光谱工作区排在首位。立方体像素 → 光谱被标记为精确关联。WildDatum 还会提取 LAS WKT/GeoKey CRS 元数据，以及 HDF5 EPSG、Map_Info、空间范围、缩放因子和无数据值。 教学立方体的 Map_Info 原点与其声明的反射率范围相差 500 m，且其覆盖范围与教学 LAS 瓦片不重叠， 因此，对于该数据对，点 → 图像像素关联会正确地保持不可用，而不会将邻近误当成配准。

已接受的点云 + 光谱立方体视图通过与手动创建的视图相同的固定版本 Rerun 适配器和浏览器探索器渲染。 浏览器会报告视图规范版本以及面板和关联的数量。选取立方体像素后，系统会自动将其精确的、 感知波长的光谱物化为持久结果，并在其溯源信息中记录选择和关联规则。不可用的关联规则仍会以 结构化状态显示，并且不会创建结果，而不是变成猜测性的交互。视图修订版本变更后，关联评估会拒绝 过时的选择。

对于具有相同权威 CRS、一致的北向上仿射变换且覆盖范围重叠的数据集，现在可以通过精确的点选 推导出源立方体像素，并立即继续获取完整的、感知波长的光谱。推导出的像素、两项关联判定以及光谱 结果，仍可通过常规 MCP、CLI 和浏览器界面进行检查。

完成解析后，浏览器会将权威视图重新生成为完整的 Rerun 记录，其中包含洋红色的源像素/推导像素标记， 以及光谱面板内关联的波长/数值序列。结构化选择和结果溯源信息仍然是叠加层的依据；浏览器不会根据 画布坐标重新构建叠加层。

关联轨迹/剖面视图现在接受 CSV、TSV、Parquet、GeoParquet、Arrow IPC 和 Feather 源数据。一个地图 最多可驱动 8 个感知 QC 的数值剖面。闭区间深度/压力/高度范围和确定性的逐剖面点数预算可降低 视觉负载，同时透明的源数据槽会为所有显示格式保留精确的 Rerun 实例 → 物理记录对应关系。

详细支持情况和注意事项见格式矩阵。设计边界记录在架构文档 和实现决策中。规划中的研究基础设施、可视化和部署工作见公开的 路线图。

安装并查看运行效果

该 alpha 版本提供独立的 macOS 通用版和 Linux x86-64 软件包。你 无需安装 Rust、Node.js、CMake 或单独安装 Rerun：

curl -fsSL https://raw.githubusercontent.com/krnzt/wilddatum/v0.1.0-alpha.3/scripts/install.sh | sh

安装程序会验证发行版的 SHA-256，默认安装到 ~/.local 下，并运行 wilddatum setup。设置 WILDDATUM_INSTALL_DIR 可选择其他安装前缀。如果 ~/.local/bin 尚未加入 PATH，请先将其添加后再继续。

现有的 EcoScope alpha 安装仍可读取。若缺少对应的 WildDatum 设置，WildDatum 会回退使用旧版 ECOSCOPE_DATA_DIR、ECOSCOPE_CACHE_DIR、ECOSCOPE_WEB_DIST、默认应用数据目录和 NEON 钥匙串条目。如果不会覆盖用户自己的文件，安装程序也会保留 ecoscope 命令别名。

创建一个确定性的 LiDAR + 高光谱演示，并在捆绑的 Rerun 浏览器查看器中打开：

wilddatum demo synthetic

生成的 LAS 和 HDF5 文件会经过与用户数据相同的导入、清单、数据立方体映射、Rerun 记录和选择查询流程。无需网络或凭据。此外，还提供一个可选择启用的官方 NEON 教学数据演示（约 224 MiB）：

wilddatum demo neon --accept-download

注册标准 MCP 服务

WildDatum 在官方 MCP Registry 中以 io.github.krnzt/wilddatum 发布。它也是标准的本地 stdio 服务：Codex、Claude Code 和任何兼容的宿主都会启动同一个 wilddatum mcp 进程并发现其工具。

wilddatum register codex
wilddatum register claude

这两条注册命令都可安全地重复执行，并会保留现有的 WildDatum 条目。每个发行版都附带特定于平台的 MCPB 软件包，供安装 MCPB 软件包的宿主和注册表使用。

等效的宿主命令如下：

codex mcp add wilddatum -- /absolute/path/to/wilddatum mcp
claude mcp add --scope user wilddatum -- /absolute/path/to/wilddatum mcp

通用 MCP 配置：

{
  "mcpServers": {
    "wilddatum": {
      "command": "/home/you/.local/bin/wilddatum",
      "args": ["mcp"]
    }
  }
}

注册后，宿主会像启动其他本地 MCP 服务一样启动 WildDatum、协商协议、发现其工具，并接收有界结构化结果，而非大量科学数据文件。

使用本地科学文件

wilddatum import examples/observations.csv
wilddatum datasets
wilddatum preview ds_... --limit 20
wilddatum create-view --name "Site comparison" ds_...
wilddatum open view_...

本地路径在终端中选择，绝不会作为 MCP 参数传递。私有 SQLite 注册表会保留源路径；Agent 会收到不透明 ID、校验和、显示名称、科学元数据和来源信息。同一条路径支持格式矩阵中的栅格、矢量、点云、图像和数据立方体格式。

关联轨迹与垂直剖面

剖面/轨迹渲染是一种基于常规 CSV、TSV、Parquet、GeoParquet、Arrow IPC 或 Feather 数据的经过验证的配方，而非特定于数据提供方的渲染器。可从确定性演示开始本地体验：

wilddatum demo profile-trajectory

无论是本地导入还是已物化的 ERDDAP 表，Agent 工作流都相同：

user imports a compatible local table, or agent materializes a provider subset
  → create_view
  → configure_profile_trajectory_view
  → open_view
  → human selects a map or profile observation
  → inspect_view
  → query_selection
  → exact source record with native identifiers, values, units, and QC

配方会明确指定轨迹/剖面标识符、时间、经度、纬度、垂直坐标及其方向、一个主要显示值和可选的其他显示值、单位、填充值，以及接受的原生 QC 代码。它还可以应用包含边界值的源坐标垂直范围，以及每个剖面的显示预算。WildDatum 会根据源数据验证这些字段，然后编写精确行映射；浏览器不能将源索引声明为可信，采样也不会更改源实例槽位。

Rerun Web Viewer 中随附的合成剖面演示。所选剖面观测会持久化为 rows 选择，其中仅包含其 Rerun 实体、实例、映射类型和固定版本；服务会独立将该实例解析为原始分隔符文件中的对应行。

NEON

发现元数据无需凭据。精确的文件规划和下载需要使用存储在模型上下文之外的 NEON API 令牌：

./target/release/wilddatum connect-neon

提示词不会回显令牌。WildDatum 会将令牌存储在操作系统钥匙串中，并且仅通过 X-API-Token 标头将其发送到上游。无头系统可以通过其密钥管理器注入 NEON_API_TOKEN。

wilddatum doctor 会为非交互式钥匙串探测设置时间限制。neon_connected: null 且 neon_credential_probe: "timed_out" 表示操作系统未响应就绪探测；这不会暴露或删除已存储的凭据。

公共 ERDDAP 基础设施

常规注册的 MCP 通过与 NEON 和社区提供方相同的工具，提供三个无需凭据的公共预设：

提供方 ID	公共服务	边界
emso	EMSO ERIC ERDDAP	联邦式公共数据集；经批准的重定向链会标识返回数据字节的区域服务器
icos-erddap	ICOS Carbon Portal ERDDAP	仅限公共 ERDDAP；经过身份验证的 Carbon Portal 对象属于单独的未来集成
euro-argo	Ifremer ERDDAP	目录搜索范围限定为共享服务上的 Argo/Euro-Argo 数据

Agent 无需凭据即可调用 search_catalog 和 inspect_resource，然后构建类型化表格子集：

{
  "provider": "emso",
  "resource_id": "OBSEA_seabed_station_TS_L1c",
  "variables": ["time", "TEMP", "TEMP_QC"],
  "temporal_start": "2025-01-01T00:00:00Z",
  "temporal_end": "2025-01-02T00:00:00Z",
  "provider_options": {
    "protocol": "tabledap",
    "output_format": "csv",
    "constraints": [
      {"variable": "TEMP_QC", "op": "eq", "value": 1}
    ]
  }
}

这是 plan_materialization 的输入；规划不会下载数据集。WildDatum 会根据 ERDDAP info 元数据验证每个变量，将通用时间边界转换为 tabledap 的 time 约束，探测精确的重定向链，并返回一个待审批 URL。使用返回的哈希调用 approve_plan，然后调用 materialize_dataset。存储对象以其 BLAKE3 摘要命名，而清单会保留解码后的查询、重定向链、ETag、Last-Modified 值、访问时间、服务器版本、全局属性、变量级 CF 属性、许可证和引用信息。下载会通过可配置的硬性字节上限进行流式传输（默认 512 MiB），失败或超限的部分下载会被删除。

网格子集使用 protocol: "griddap" 和显式数组。每个坐标轴都可以使用整数索引或 ERDDAP 值坐标：

{
  "protocol": "griddap",
  "output_format": "netcdf",
  "arrays": [{
    "variable": "temperature",
    "slices": [
      {"start": "0", "stop": "23", "stride": 1},
      {"start": "10", "stop": "30", "stride": 2}
    ]
  }]
}

ERDDAP 子集是实时生成的结果，而非固定版本。审批时通常无法得知文件大小，因此请谨慎约束变量、行数、时间和网格坐标轴。物化会在本地固定返回的确切数据字节；之后重复相同的上游查询，可能会得到不同的校验和。

一个通过 WildDatum 注册的 stdio MCP 执行的真实 EMSO 工作流： plan_materialization → approve_plan → materialize_dataset → create_view → render_view。浏览器展示了公共 OBSEA 温度和原生 QC 通道、可重新生成的 EcoViewSpec，以及以结构化 Agent 上下文形式返回的选择事件。

多维数据

WildDatum 会清点数据立方体数组，而不臆测含糊的科学含义。当 X、Y 和光谱轴明确无歧义时，会推断常见的 NEON 反射率惯例。否则，映射会显式定义并进行版本修订：

./target/release/wilddatum configure-cube view_... \
  --layer-id layer_1 \
  --cube-array /SITE/Reflectance/Reflectance_Data \
  --y-axis 0 --x-axis 1 --spectral-axis 2 \
  --wavelength-dataset /SITE/Reflectance/Metadata/Spectral_Data/Wavelength \
  --red-band 14 --green-band 9 --blue-band 5

与提供方无关的 MCP 对应工具是 configure_cube_view。

社区提供方

内置了受维护的远程提供方，但其架构并非针对特定机构设计。安装受信任的、 与语言无关的提供方可执行文件：

./target/release/wilddatum provider install ./my-provider.json
./target/release/wilddatum provider list

安装过程会执行协议握手，并验证提供方身份、功能、响应边界和声明的 HTTPS 源。提供方可执行文件是受信任的本地代码，而非沙盒化插件，也永远不会收到凭据 值。完整的线路协议契约、一致性测试样例和安全模型，请参阅提供方 SDK。规范的 DatasetRequest v2 和 提供方清单 v2 架构会将 RI 原生名称保留在适配器内，而 plan_materialization 会在各提供方之间公开一个类型化的 MCP 输入。

已知限制

• WildDatum 目前是本地 stdio MCP；尚未实现远程 Streamable HTTP 和 OAuth。
• macOS alpha 可执行文件尚未经过 Apple 公证。macOS 可能要求首次运行时明确批准；发布校验和仍可保护构件完整性。
• 浏览器资源管理器使用 Rerun 的 WebGL 渲染器，以可靠地支持软件运行和 CI。对于超大型场景，原生 Rerun 仍是上限更高的选择。
• Rerun 会公开实体／实例选择事件，但没有适用于所有视图的通用画笔协议。显式的区间、地图、栅格、光谱和行选择都使用相同的 record_selection/query_selection 路径。
• GeoParquet 支持精确的 GeoDataFusion 查询，但尚不支持直接将几何数据记录到 Rerun；GeoPackage 目前支持检查，但没有查询适配器。
• 派生自 WildDatum 的 COPC 索引提供全分辨率空间访问，但尚未包含达到提供方质量的多分辨率层级结构。
• 通用 ERDDAP 规划不会推断特定机构的站点／位置维度，也不会转换任意多边形。请使用类型化的 tabledap 约束或 griddap 切片。CF 剖面角色会保留，但科学值／QC 策略仍需通过显式配方选择，而非自动猜测。
• 链接剖面渲染支持从 CSV/TSV、Parquet/GeoParquet、Arrow IPC 或 Feather 中显示最多八个值，但行数超过 100,000 的数据源会被拒绝，而不是采用流式处理或平铺处理。Rerun 原始值二维视图的纵横比可能会导致较窄的数值范围相对于较深的垂直范围看起来被水平压缩。
• 纯 Rust NetCDF-3 适配器会限制对整个变量的解码，因为其读取器目前不支持子集 I/O。

开发

从源代码构建需要 Rust 1.95、Node.js 22、CMake 和 C/C++ 编译器。Linux 使用随附的静态 D-Bus 客户端访问密钥链。

git clone https://github.com/krnzt/wilddatum.git
cd wilddatum
npm --prefix viewer/web-bootstrap ci
npm --prefix viewer/web-bootstrap run build
cargo build --release
./target/release/wilddatum setup

使用以下命令运行完整的验证套件：

cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
npm --prefix viewer/web-bootstrap run check
npm --prefix viewer/web-bootstrap run build
npm --prefix viewer/web-bootstrap exec -- playwright install chromium
npm --prefix viewer/web-bootstrap run test:e2e
npm --prefix viewer/web-bootstrap audit --omit=dev

一个可选启用的集成测试会测试已发布的 NEON 教学数据子集：一个包含 6,609,829 个点的 LAS 瓦片，以及一个 500×500×107 的 HDF5 反射率数据立方体。

curl -fL -o /tmp/neon-point-cloud.las https://ndownloader.figshare.com/files/7024955
curl -fL -o /tmp/neon-hyperspectral.h5 https://ndownloader.figshare.com/files/21754221
NEON_POINT_CLOUD_FIXTURE=/tmp/neon-point-cloud.las \
NEON_HYPERSPECTRAL_FIXTURE=/tmp/neon-hyperspectral.h5 \
cargo test -p wilddatum-rerun --test official_neon_fixtures -- --ignored

受维护的 ERDDAP 预设还支持可选启用的实时漂移检查。它们会搜索并检查全部三项服务，物化一个经过重定向的微型 EMSO 子集，并通过 CF 发现、物化、配方验证和 Rerun 渲染，处理一个范围受限的当前 Euro-Argo 剖面：

cargo test -p wilddatum-provider-erddap --test live -- --ignored
cargo test -p wilddatum-provider-erddap --test argo_profile_smoke -- --ignored

在 Rust 和浏览器构建完成后，使用 scripts/package-release.sh target/release/wilddatum dist macos-arm64 darwin 构建本地 MCPB 和归档构件（在 Linux 上替换为 linux-x86_64 linux）。标签工作流会构建并合并两种 macOS 架构，验证 Linux 链接，发布带校验和的发行构件，并使用 GitHub OIDC 提交生成的 server.json。

项目状态

WildDatum 目前处于早期公开 Alpha 阶段。科学数据模型、提供方契约和 Rerun 边界均经过设计以便扩展，但 API 和打包方式在首个稳定版本发布前仍可能发生变化。

欢迎生态学研究人员、数据管理员、研究基础设施团队、可视化开发者和科学格式专家参与贡献。适合开展首次协作的方向包括代表性元数据样例、格式适配器、选择语义、无障碍支持，以及可复现的生态学演示。请阅读 CONTRIBUTING.md，并在开始大规模的提供方或查看器改动前提交 issue。

WildDatum 采用 MIT 许可证。Rerun 根据其 MIT/Apache-2.0 许可证使用；构建的程序包会在 THIRD_PARTY_NOTICES.md 中保留所需声明。