instance-repo 1.3.2.dev2__py3-none-any.whl → 1.3.2.dev4__py3-none-any.whl

instance_repo/__init__.py

@@ -18,7 +18,7 @@ from .errors import (
     TransportError,
 )
 
-__version__ = "1.3.2.dev2"
+__version__ = "1.3.2.dev4"
 
 __all__ = [
     "Repo", "load_instances",

instance_repo/_routing.py

@@ -45,14 +45,14 @@ def _split_scheme(endpoint: str) -> tuple[str, str]:
     return "", endpoint
 
 
-def _probe_private_endpoint(endpoint: str, timeout: float = 3.0) -> bool:
+def _probe_private_endpoint(endpoint: str, timeout: float = 0.5) -> bool:
     """Quick TCP connect probe to decide whether a private endpoint is reachable.
 
     Performs a raw TCP connect (no TLS handshake) to the endpoint host/port.
     Returns True if the connect succeeds, False on any error.  The default
-    timeout is 3 seconds — short enough to save 60+ seconds of waiting when
-    the private endpoint is unreachable, yet long enough for a normal TCP
-    handshake on a reachable host.
+    timeout is 0.5 seconds — 内网 TCP 握手通常在几十毫秒内完成，0.5s 足够
+    判定可达性，同时把公网环境下私网不可达的探测开销从 3s 压到 0.5s
+    （结果按 store 缓存 5 分钟，仅端点变更或缓存过期才重探）。
     """
     _, host = _split_scheme(endpoint)
     # Determine port: default 443 for https, 80 for http.

instance_repo/clients/datasets.py

@@ -16,10 +16,13 @@ class DatasetsClient:
     _BASE = "/apis/v1/datasets/series"
 
     def __init__(self, transport, *, content_store=None,
-                 oss_prefix: str = "swe/datasets") -> None:
+                 oss_prefix: str = "swe/datasets",
+                 metadata_model: str | None = None) -> None:
         self._t = transport
         self._content = content_store
         self._oss_prefix = oss_prefix
+        # OSS 回退探测的布局语义（split_first 默认；version_first 显式切换）
+        self._metadata_model = metadata_model or "split_first"
 
     def list(self, l1: str | None = None) -> list[DatasetSeries]:
         """列出 dataset（便利语义：自动翻页取全量，见 :meth:`list_paged` 单页对照）。
@@ -158,7 +161,8 @@ class DatasetsClient:
         except TransportError as e:
             if (e.biz_code == 92001 and fallback_to_oss
                     and self._content is not None):
-                return self._discover_detail(name, storage_env=environment)
+                return self._discover_detail(name, storage_env=environment,
+                                             metadata_model=metadata_model)
             raise
 
     def update(self, name: str, *, display_name: str | None = None,
@@ -393,14 +397,16 @@ class DatasetsClient:
     # ── OSS fallback discovery (private) ─────────────────────────────────
 
     def _discover_detail(self, name: str, *,
-                         storage_env: str | None = None) -> DatasetDetail:
+                         storage_env: str | None = None,
+                         metadata_model: str | None = None) -> DatasetDetail:
         from ..store.oss_discovery import (
             parse_dataset_level, build_synthetic_dataset_detail,
             _warn_if_truncated)
         info = parse_dataset_level(
-            self._content, name, oss_prefix=self._oss_prefix)
+            self._content, name, oss_prefix=self._oss_prefix,
+            metadata_model=metadata_model or self._metadata_model)
         _warn_if_truncated(info, name, 500)
-        if not info.versions:
+        if not info.versions and not info.unversioned_splits:
             from ..errors import DatasetNotFound
             raise DatasetNotFound(f"dataset {name!r} not found in OSS")
         return build_synthetic_dataset_detail(

instance_repo/clients/splits.py

@@ -264,16 +264,23 @@ class SplitsClient:
         注意：回退场景（dataset 未注册）下 ``version_scope`` 是 MongoDB 语义，
         OSS 探测无从区分 versioned/unversioned——**忽略 scope 并返回全部探测结果**
         （G4：否则 ap CLI 无 --version 的 split list 恒空）。``version`` 非空时
-        仍精确匹配该 version。
+        仍精确匹配该 version；version 为空时额外包含 split_first 无版本 split
+        （version="" 归属）。
         """
         from ..store.oss_discovery import (
             parse_dataset_level, build_synthetic_split,
             _in_memory_paged, _warn_if_truncated,
         )
         info = parse_dataset_level(
-            self._content, dataset, oss_prefix=self._oss_prefix)
+            self._content, dataset, oss_prefix=self._oss_prefix,
+            metadata_model=self._discovery_mm())
         _warn_if_truncated(info, dataset, 500)
         splits: list[DatasetSplit] = []
+        # split_first 无版本布局：dataset 根下直接是 split 目录
+        if not version:
+            for us in info.unversioned_splits:
+                splits.append(build_synthetic_split(
+                    dataset, "", us.name, instance_count=us.instance_count))
         for v in info.versions:
             if version and v.version != version:
                 continue
@@ -295,8 +302,14 @@ class SplitsClient:
             parse_dataset_level, build_synthetic_split, _warn_if_truncated,
         )
         info = parse_dataset_level(
-            self._content, dataset, oss_prefix=self._oss_prefix)
+            self._content, dataset, oss_prefix=self._oss_prefix,
+            metadata_model=self._discovery_mm())
         _warn_if_truncated(info, dataset, 500)
+        if not version:
+            for us in info.unversioned_splits:
+                if us.name == split_name:
+                    return build_synthetic_split(
+                        dataset, "", us.name, instance_count=us.instance_count)
         for v in info.versions:
             if version and v.version != version:
                 continue
@@ -309,6 +322,13 @@ class SplitsClient:
                     dataset, v.version, split_name)
         return None
 
+    def _discovery_mm(self) -> str:
+        """OSS 回退探测的布局语义（split_first 默认；version_first 显式切换）。"""
+        from ..layout import normalize_metadata_model
+        return normalize_metadata_model(
+            getattr(self._p, "metadata_model", None)
+            if self._p is not None else None)
+
     # ── 写 ──
 
     def _post_create(self, dataset: str, split: str, version: str,

instance_repo/clients/versions.py

@@ -229,7 +229,7 @@ class VersionsClient:
         except TransportError as e:
             if (e.biz_code == 92001 and fallback_to_oss
                     and self._content is not None):
-                return self._discover_versions(dataset)
+                return self._discover_versions(dataset, metadata_model=metadata_model)
             raise
 
     def list_paged(self, dataset: str, *, status: str | None = None,
@@ -264,7 +264,8 @@ class VersionsClient:
             if (e.biz_code == 92001 and fallback_to_oss
                     and self._content is not None):
                 return self._discover_versions_paged(
-                    dataset, status, int(page), int(page_size))
+                    dataset, status, int(page), int(page_size),
+                    metadata_model=metadata_model)
             raise
         rows = data.get("versions", data) if isinstance(data, dict) else data
         rows = rows if isinstance(rows, list) else []
@@ -295,7 +296,8 @@ class VersionsClient:
         except TransportError as e:
             if (e.biz_code == 92001 and fallback_to_oss
                     and self._content is not None):
-                return self._discover_version(dataset, version)
+                return self._discover_version(dataset, version,
+                                              metadata_model=metadata_model)
             raise
 
     def status(self, dataset: str, version: str, *,
@@ -891,31 +893,37 @@ class VersionsClient:
 
     # ── OSS fallback discovery (private) ─────────────────────────────────
 
-    def _discover_versions(self, dataset: str) -> list:
+    def _discover_versions(self, dataset: str,
+                           metadata_model: str | None = None) -> list:
         from ..store.oss_discovery import (
             parse_dataset_level, build_synthetic_version, _warn_if_truncated)
         info = parse_dataset_level(
-            self._content, dataset, oss_prefix=self._oss_prefix)
+            self._content, dataset, oss_prefix=self._oss_prefix,
+            metadata_model=metadata_model or self._discovery_mm())
         _warn_if_truncated(info, dataset, 500)
-        if not info.versions:
+        # split_first 无版本布局（只有 split）也是发现成功，只是没有版本可列
+        if not info.versions and not info.unversioned_splits:
             from ..errors import DatasetNotFound
             raise DatasetNotFound(f"dataset {dataset!r} not found in OSS")
         return [build_synthetic_version(dataset, v) for v in info.versions]
 
     def _discover_versions_paged(self, dataset: str, status: str | None,
-                                 page: int, page_size: int):
+                                 page: int, page_size: int,
+                                 metadata_model: str | None = None):
         """OSS 回退的 list_paged：全量探测后按 status 过滤 + 内存分页。"""
         from ..store.oss_discovery import _in_memory_paged
-        items = self._discover_versions(dataset)
+        items = self._discover_versions(dataset, metadata_model=metadata_model)
         if (status or "").strip():
             items = [v for v in items if v.status == status.strip()]
         return _in_memory_paged(items, int(page), int(page_size))
 
-    def _discover_version(self, dataset: str, version: str):
+    def _discover_version(self, dataset: str, version: str,
+                          metadata_model: str | None = None):
         from ..store.oss_discovery import (
             parse_dataset_level, build_synthetic_version, _warn_if_truncated)
         info = parse_dataset_level(
-            self._content, dataset, oss_prefix=self._oss_prefix)
+            self._content, dataset, oss_prefix=self._oss_prefix,
+            metadata_model=metadata_model or self._discovery_mm())
         _warn_if_truncated(info, dataset, 500)
         for v in info.versions:
             if v.version == version:
@@ -924,6 +932,13 @@ class VersionsClient:
         raise DatasetNotFound(
             f"version {version!r} not found in OSS for dataset {dataset!r}")
 
+    def _discovery_mm(self) -> str:
+        """OSS 回退探测的布局语义（split_first 默认；version_first 显式切换）。"""
+        from ..layout import normalize_metadata_model
+        return normalize_metadata_model(
+            getattr(self._p, "metadata_model", None)
+            if self._p is not None else None)
+
 
 # 与 apiserver `DatasetVersionListItem`（pkg/server/dataset_service.go:315）对齐:
 # 列表项带 instance_count/split_count/updated_at/last_ingested_at,详情接口才带

instance_repo/repo.py

@@ -84,7 +84,8 @@ class Repo:
         self.datasets = DatasetsClient(
             self.transport,
             content_store=self._content,
-            oss_prefix=self.profile.oss_prefix)
+            oss_prefix=self.profile.oss_prefix,
+            metadata_model=self.profile.metadata_model)
         self.versions = VersionsClient(
             self.transport, self.profile,
             content_store=self._content,

instance_repo/store/oss_discovery.py

@@ -23,6 +23,7 @@ from ..models import (
     DatasetInstance,
     DatasetSplit,
     DatasetVersion,
+    ManifestEntry,
     PagedResult,
     SplitManifest,
 )
@@ -63,6 +64,14 @@ class OssVersionInfo:
     default_instance_count: int = 0
 
 
+@dataclass
+class OssUnversionedSplit:
+    """split_first 无版本布局：dataset 根下直接是 split 目录（无 version 层）。"""
+    name: str
+    has_assets: bool          # 同层 {name}-assets/ 存在（split 级 content）
+    instance_count: int       # {name}/ 下直接 .json 数
+
+
 @dataclass
 class OssDatasetLevelInfo:
     """Overall dataset structure discovered from OSS directory layout."""
@@ -70,6 +79,12 @@ class OssDatasetLevelInfo:
     versions: list[OssVersionInfo]
     total_instance_count: int
     truncated: bool = False
+    # split_first 无版本布局下的 split（version="" 语义）
+    unversioned_splits: list[OssUnversionedSplit] = None  # type: ignore[assignment]
+
+    def __post_init__(self):
+        if self.unversioned_splits is None:
+            self.unversioned_splits = []
 
 
 # ---------------------------------------------------------------------------
@@ -185,11 +200,18 @@ def parse_dataset_level(
     *,
     oss_prefix: str = "swe/datasets",
     max_versions: int = 500,
+    metadata_model: str = "split_first",
 ) -> OssDatasetLevelInfo:
     """Discover version/split structure from OSS directory layout.
 
-    Performs at most ``1 + min(N, max_versions)`` LIST calls where *N* is the
-    number of Level 1 entries.
+    Performs ``1 + min(N, max_versions)`` LIST calls where *N* is the number
+    of Level 1 entries; the per-group probes run concurrently (8-way).
+
+    语义消歧（``metadata_model``）：
+    - ``split_first``（SDK 默认）：level-1 目录 `X/` 下**只有 .json、无子目录**
+      时，`X` 是无版本 split（`{split}/{id}.json` 契约形态）；含子目录时是
+      version（子目录为其 split）。
+    - ``version_first``（显式切换）：level-1 目录一律视为 version（旧行为）。
 
     Args:
         content_store: :class:`~instance_repo.store.oss.OssContentStore` instance.
@@ -197,6 +219,8 @@ def parse_dataset_level(
         oss_prefix: Root prefix inside the bucket (default ``"swe/datasets"``).
         max_versions: Upper bound on the number of versions to probe.  When
             exceeded the result is truncated and ``truncated=True`` is set.
+        metadata_model: ``split_first``（默认）or ``version_first``；决定
+            level-1 目录的语义归属（见上）。
 
     Returns:
         :class:`OssDatasetLevelInfo` with the discovered version/split tree.
@@ -231,90 +255,104 @@ def parse_dataset_level(
             f"dataset {dataset!r} not found in OSS under {root!r}"
         )
 
-    # -- Group level 1 names into version candidates -----------------------
+    # -- Group level 1 names into candidates -------------------------------
     l1_groups = _group_level_names(level1_names)
 
-    if not l1_groups and not level1_json_keys:
+    if not l1_groups:
+        if level1_json_keys:
+            # 实例 .json 直接位于 dataset 根下（无 version/split 层）是**非法布局**：
+            # paths.py 契约要求 metadata 至少带 version 层（version_first）或
+            # split 层（split_first）。不兼容识别，明确报错引导上传方修正。
+            raise DatasetNotFound(
+                f"dataset {dataset!r} exists in OSS but has no recognizable "
+                f"version/split structure: {len(level1_json_keys)} .json file(s) "
+                f"directly under {root!r} (expected {root!r}{{version}}/[{{split}}/] "
+                f"layout per paths.py contract)")
         raise DatasetNotFound(
             f"dataset {dataset!r} exists in OSS but has no recognizable "
             f"version/split structure under {root!r}"
         )
 
     # Sort for deterministic output.
-    version_names = sorted(l1_groups.keys())
+    names = sorted(l1_groups.keys())
 
     # -- Truncation protection ---------------------------------------------
     truncated = False
-    if len(version_names) > max_versions:
-        version_names = version_names[:max_versions]
+    if len(names) > max_versions:
+        names = names[:max_versions]
         truncated = True
 
-    # -- Level 2: probe each version ---------------------------------------
-    versions: list[OssVersionInfo] = []
-    total_instance_count = 0
-
-    for v_name in version_names:
-        grp = l1_groups[v_name]
-        version_dir = f"{root}{v_name}/"
-
-        # 3-layer content/report siblings at level 1.
-        has_three_layer_content = grp.has_assets  # {version}-assets/ exists
+    split_first = (metadata_model or "split_first") != "version_first"
 
-        # Level 2 listing (subdirectories of {version}/).
+    # -- Level 2: probe each candidate (concurrent) ------------------------
+    # 每个 group 的完整分析（level-2 列举 + 逐 split 计数）都在 probe 内完成，
+    # 使大 version 数数据集的探测全程并行，避免串行逐 split 计数拖慢整链。
+    def probe(name: str):
+        """分析单个 level-1 group，返回 OssVersionInfo / OssUnversionedSplit。"""
+        grp = l1_groups[name]
+        group_dir = f"{root}{name}/"
         try:
-            level2_names = content_store.list_prefixes(version_dir, list_only=True)
+            level2_names, level2_keys = content_store.list_level(
+                group_dir, list_only=True)
         except Exception:  # noqa: BLE001
-            level2_names = []
-
+            level2_names, level2_keys = [], []
         l2_groups = _group_level_names(level2_names)
-
-        # Splits are level 2 groups that have a real directory (has_dir) or
-        # an assets directory (4-layer content pattern).
-        splits: list[str] = sorted(
-            name for name, g in l2_groups.items()
-            if g.has_dir or g.has_assets
-        )
-
-        # Detect default-split instances: .json files directly under {version}/.
-        try:
-            _level2_dirs, v_all_keys = content_store.list_level(
-                version_dir, list_only=True)
-            v_json_keys = _direct_json_keys(v_all_keys, version_dir)
-            has_default_instances = len(v_json_keys) > 0
-            default_instance_count = len(v_json_keys)
-            instance_count = len(v_json_keys)
-        except Exception:  # noqa: BLE001
-            has_default_instances = False
-            default_instance_count = 0
-            instance_count = 0
-
-        # Count instances in each named split directory.
+        direct_json = _direct_json_keys(level2_keys, group_dir)
+        subdirs = [g for g in l2_groups.values() if g.has_dir or g.has_assets]
+
+        # split_first 无版本布局：`{name}/` 下只有 .json、无子目录 →
+        # 无版本 split（contract: {split}/{id}.json + {split}-assets/）。
+        if split_first and grp.has_dir and not subdirs and direct_json:
+            return OssUnversionedSplit(
+                name=name,
+                has_assets=grp.has_assets,
+                instance_count=len(direct_json),
+            )
+
+        # version 路径（version_first 或含子目录的 split_first 形态）。
+        splits: list[str] = sorted(g.name for g in subdirs)
+        instance_count = len(direct_json)
         for s_name in splits:
-            split_dir = f"{version_dir}{s_name}/"
+            split_dir = f"{group_dir}{s_name}/"
             try:
                 _s_dirs, s_keys = content_store.list_level(
                     split_dir, list_only=True)
-                s_json = _direct_json_keys(s_keys, split_dir)
-                instance_count += len(s_json)
+                instance_count += len(_direct_json_keys(s_keys, split_dir))
             except Exception:  # noqa: BLE001
                 pass  # best-effort
-
-        total_instance_count += instance_count
-
-        versions.append(OssVersionInfo(
-            version=v_name,
-            has_three_layer_content=has_three_layer_content,
+        return OssVersionInfo(
+            version=name,
+            has_three_layer_content=grp.has_assets,
             splits=splits,
-            has_default_instances=has_default_instances,
+            has_default_instances=len(direct_json) > 0,
             instance_count=instance_count,
-            default_instance_count=default_instance_count,
-        ))
+            default_instance_count=len(direct_json),
+        )
+
+    try:
+        from ..concurrency import map_concurrent
+        results = map_concurrent(probe, names, concurrency=16)
+    except Exception:  # noqa: BLE001 - 并发不可用时退化为串行
+        results = [probe(n) for n in names]
+
+    versions: list[OssVersionInfo] = []
+    unversioned_splits: list[OssUnversionedSplit] = []
+    total_instance_count = 0
+
+    for entry in results:
+        if isinstance(entry, OssUnversionedSplit):
+            unversioned_splits.append(entry)
+            total_instance_count += entry.instance_count
+        else:
+            versions.append(entry)
+            total_instance_count += entry.instance_count
 
     return OssDatasetLevelInfo(
         dataset=dataset,
         versions=versions,
         total_instance_count=total_instance_count,
         truncated=truncated,
+        unversioned_splits=unversioned_splits,
     )
 
 
@@ -323,9 +361,10 @@ def _warn_if_truncated(info: OssDatasetLevelInfo, dataset: str, max_versions: in
     if info.truncated:
         import logging
         logging.getLogger(__name__).warning(
-            "dataset %r has more than %d versions; OSS discovery results "
+            "dataset %r has more than %d level-1 entries; OSS discovery results "
             "are truncated (showing %d of >%d)",
-            dataset, max_versions, len(info.versions), max_versions)
+            dataset, max_versions,
+            len(info.versions) + len(info.unversioned_splits), max_versions)
 
 
 # ---------------------------------------------------------------------------
@@ -389,6 +428,10 @@ def build_synthetic_dataset_detail(
         if v.has_default_instances:
             all_splits.add("default")
         total_instances += v.instance_count
+    # split_first 无版本布局：level-1 目录即 split
+    for us in info.unversioned_splits:
+        all_splits.add(us.name)
+        total_instances += us.instance_count
 
     available_envs: list[str] = [storage_env] if storage_env else []
 
@@ -450,10 +493,11 @@ def build_synthetic_split(
     instance_count: int = 0,
 ) -> DatasetSplit:
     """Build a :class:`DatasetSplit` from OSS discovery (``registered=False``)."""
+    base = f"swe/datasets/{dataset}" + (f"/{version}" if version else "")
     if split_name == "default":
-        storage_path = f"swe/datasets/{dataset}/{version}/"
+        storage_path = f"{base}/"
     else:
-        storage_path = f"swe/datasets/{dataset}/{version}/{split_name}/"
+        storage_path = f"{base}/{split_name}/"
 
     return DatasetSplit(
         dataset=dataset,
@@ -468,6 +512,16 @@ def build_synthetic_split(
     )
 
 
+def _metadata_prefix(dataset: str, version: str, split: str | None,
+                     oss_prefix: str) -> str:
+    """拼接 metadata 列举前缀；version 为空时表示 split_first 无版本布局。"""
+    l1, l2 = P.split_dataset(dataset)
+    base = f"{oss_prefix}/{l1}/{l2}" + (f"/{version}" if version else "")
+    if split and split != "default":
+        return f"{base}/{split}/"
+    return f"{base}/"
+
+
 def build_synthetic_instances(
     content_store,
     dataset: str,
@@ -475,20 +529,16 @@ def build_synthetic_instances(
     split: str | None = None,
     *,
     oss_prefix: str = "swe/datasets",
+    read_content: bool = False,
 ) -> list[DatasetInstance]:
     """List and build :class:`DatasetInstance` objects from OSS metadata JSONs.
 
     For each ``{instance_id}.json`` found directly under the target prefix, a
-    ``DatasetInstance`` is constructed.  An attempt is made to read the JSON
-    body to populate ``tags``, ``difficulty``, ``docker_image``, and
-    ``extend_meta``; on failure the instance is returned with those fields
-    left at their defaults (best-effort).
+    ``DatasetInstance`` is constructed.  ``read_content=True`` 时尝试读 JSON
+    回填 tags/difficulty/docker_image；默认 False——发现模式（list-only STS）
+    无 GetObject，逐实例 GET 必然失败，跳过可省 N 次无谓的 STS 签发与下载。
     """
-    l1, l2 = P.split_dataset(dataset)
-    if split and split != "default":
-        metadata_prefix = f"{oss_prefix}/{l1}/{l2}/{version}/{split}/"
-    else:
-        metadata_prefix = f"{oss_prefix}/{l1}/{l2}/{version}/"
+    metadata_prefix = _metadata_prefix(dataset, version, split, oss_prefix)
 
     all_keys = content_store.list_objects(metadata_prefix, list_only=True)
     json_keys = _direct_json_keys(all_keys, metadata_prefix)
@@ -503,20 +553,74 @@ def build_synthetic_instances(
             split=split or "default",
             registered=False,
         )
-        # Best-effort: read JSON to populate optional fields.  With list_only=True
-        # STS, GetObject is not granted, so these reads will fail silently (returning
-        # empty dicts) — the instance will still be listed but with empty optional fields.
-        data = _read_json_object(content_store, key)
-        if data:
-            inst.tags = data.get("tags", {})
-            inst.difficulty = data.get("difficulty")
-            inst.docker_image = data.get("docker_image")
-            inst.extend_meta = data.get("extend_meta", {})
+        if read_content:
+            data = _read_json_object(content_store, key)
+            if data:
+                inst.tags = data.get("tags", {})
+                inst.difficulty = data.get("difficulty")
+                inst.docker_image = data.get("docker_image")
+                inst.extend_meta = data.get("extend_meta", {})
         instances.append(inst)
 
     return instances
 
 
+def _instance_dir(dataset: str, version: str, split: str | None,
+                  instance_id: str, suffix: str, oss_prefix: str) -> str:
+    """拼接实例的 -assets/-report 目录；version 为空表示无版本 split 布局。"""
+    l1, l2 = P.split_dataset(dataset)
+    base = f"{oss_prefix}/{l1}/{l2}" + (f"/{version}" if version else "")
+    if split and split != "default":
+        return f"{base}/{split}-{suffix}/{instance_id}/"
+    return f"{base}-{suffix}/{instance_id}/"
+
+
+def _format_from_key(key: str) -> str:
+    if key.endswith(".jsonl"):
+        return "jsonl"
+    if key.endswith(".json"):
+        return "json"
+    if key.endswith(".tgz") or key.endswith(".tar.gz"):
+        return "tgz"
+    return ""
+
+
+def _instance_manifest(
+    content_store,
+    dataset: str,
+    version: str,
+    instance_id: str,
+    split: str | None,
+    metadata_key: str,
+    *,
+    oss_prefix: str,
+) -> list[ManifestEntry]:
+    """用 LIST 枚举实例的文件结构（metadata + {split}-assets + {split}-report）。
+
+    发现模式（list-only STS）无 GetObject，读不到 metadata JSON 内容，但目录
+    结构可通过 LIST 完整呈现——恰好满足「查看实例的目录文件结构」需求。
+    """
+    keys = [metadata_key]
+    for suffix in ("assets", "report"):
+        try:
+            keys.extend(k for k in content_store.list_objects(
+                _instance_dir(dataset, version, split, instance_id,
+                              suffix, oss_prefix),
+                list_only=True) if not k.endswith("/"))
+        except Exception:  # noqa: BLE001
+            pass  # best-effort：无 assets/report 目录时忽略
+    bucket = getattr(content_store, "bucket_name", "") or ""
+    return [
+        ManifestEntry(
+            file_path=f"oss://{bucket}/{k}" if bucket else k,
+            content_type="file",
+            content_format=_format_from_key(k),
+            object_path=k,
+        )
+        for k in keys
+    ]
+
+
 def build_synthetic_instance(
     content_store,
     dataset: str,
@@ -525,13 +629,30 @@ def build_synthetic_instance(
     split: str | None = None,
     *,
     oss_prefix: str = "swe/datasets",
+    read_content: bool = False,
+    include_files: bool = True,
 ) -> DatasetInstance | None:
     """Build a single :class:`DatasetInstance` by exact key lookup in OSS.
 
-    Returns ``None`` if the metadata JSON does not exist.
+    Returns ``None`` if the metadata JSON does not exist.  ``read_content``
+    语义同 :func:`build_synthetic_instances`（发现模式默认跳过 JSON 回填）。
+
+    ``include_files``（默认 True）用 LIST 枚举实例文件结构（metadata + assets
+    + report 目录）回填 ``manifest``——文件名为真实值，digest/大小留空
+    （list-only STS 无 GetObject）。仅 instance get 单条路径开启，避免列表
+    路径 N 倍 LIST 开销。
     """
-    key = P.metadata_key(
-        dataset, version, instance_id, split, prefix=oss_prefix)
+    if version:
+        key = P.metadata_key(
+            dataset, version, instance_id, split, prefix=oss_prefix)
+    else:
+        # split_first 无版本布局：{split}/{id}.json（split=None/default 不合
+        # 此形态，调用方须传真实 split 名）
+        l1, l2 = P.split_dataset(dataset)
+        base = f"{oss_prefix}/{l1}/{l2}"
+        key = (f"{base}/{split}/{instance_id}.json"
+               if split and split != "default"
+               else f"{base}/{instance_id}.json")
 
     # 存在性判定用 LIST（list_only=True 仅需 ListObjects）而非 HEAD——
     # list-only STS 无 oss:GetObject，object_exists 的 HEAD 会在 STS 签发或
@@ -551,11 +672,19 @@ def build_synthetic_instance(
         split=split or "default",
         registered=False,
     )
-    data = _read_json_object(content_store, key)
-    if data:
-        inst.tags = data.get("tags", {})
-        inst.difficulty = data.get("difficulty")
-        inst.docker_image = data.get("docker_image")
-        inst.extend_meta = data.get("extend_meta", {})
+    if include_files:
+        try:
+            inst.manifest = _instance_manifest(
+                content_store, dataset, version, instance_id, split, key,
+                oss_prefix=oss_prefix)
+        except Exception:  # noqa: BLE001
+            pass  # best-effort：manifest 枚举失败不阻断实例返回
+    if read_content:
+        data = _read_json_object(content_store, key)
+        if data:
+            inst.tags = data.get("tags", {})
+            inst.difficulty = data.get("difficulty")
+            inst.docker_image = data.get("docker_image")
+            inst.extend_meta = data.get("extend_meta", {})
 
     return inst

{instance_repo-1.3.2.dev2.dist-info → instance_repo-1.3.2.dev4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instance-repo
-Version: 1.3.2.dev2
+Version: 1.3.2.dev4
 Summary: InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{instance_repo-1.3.2.dev2.dist-info → instance_repo-1.3.2.dev4.dist-info}/RECORD

@@ -1,5 +1,5 @@
-instance_repo/__init__.py,sha256=ae2kTZekBd48C9oAOBgdUsN2JST5lkCSA6M348urFGI,1422
-instance_repo/_routing.py,sha256=XbdKPF-Zh2sEkr4UyLC9HuiRcTLP-ssvhp6SCDC98YM,8326
+instance_repo/__init__.py,sha256=lAyyofR-xkJ6HHVt7KUbO5Ar3_hFdKTJxyAK13u7hnE,1422
+instance_repo/_routing.py,sha256=fX3oKJNca1XTD1pKK304eq0clf7I8iEdFkd2WFO3oV4,8414
 instance_repo/_site_defaults.py,sha256=ck7aHHTup8ibBo0l5MSR03XpTtxJ11hYo7oM2DzWs4A,2383
 instance_repo/artifacts.py,sha256=OOcSI1ehB_dw1ZNScjyhzghPqOdL534kQp_iI2Hz7IU,10659
 instance_repo/bootstrap.py,sha256=qtBZoq77zHUcri3EgUleTrXTDUQq3GU9cI2wzw_wly4,9658
@@ -15,7 +15,7 @@ instance_repo/loader.py,sha256=lWjhw0MjEIIxbZ5w6cjyaDIWkNVFDhjjNdu1lc5zRuo,474
 instance_repo/models.py,sha256=-DyP2DBu2vNecmASbyExfNu5nJkutNsqWInhlq8_ZMU,35987
 instance_repo/paths.py,sha256=EL0d613T0mnabiYCtZQBC50rZT3mWKUq-3TepPbTRec,8438
 instance_repo/release.py,sha256=Up96Qeh2GRH26BSAHVEjDFQnFCaEA-vIvSme3a8FQFo,13882
-instance_repo/repo.py,sha256=5D7jYLeaDSZLKnf548YlfXT9tUPNgdcXT2j31wzShpA,40305
+instance_repo/repo.py,sha256=XDa-61in_7P-2SGIMDbNM1okbJYuJh6ODlQCdY1DajI,40361
 instance_repo/retry.py,sha256=8y-AX9qmnLqGwqRzVJ5PKqZt2fWyqUL2t2P0suSBAA4,3438
 instance_repo/tasktoml.py,sha256=b-tWfNiOHN9D-ixCbPpCLnZaaU9Q6LRGG0Wl4YN8r10,5152
 instance_repo/transport.py,sha256=2Vh2atYxmq5Hrh0mc-10yA3p8QUOQruAE_2f1i1uwWk,21995
@@ -23,22 +23,22 @@ instance_repo/validate.py,sha256=NMR-vFBIU_FQ0WKdBZuQ-ua4jtkAzvWwEjnAHyAFwDs,118
 instance_repo/clients/__init__.py,sha256=5V7Pe0b6nnMiwIhACA4ctQowovrL4iHTiHKKcjmsBQo,488
 instance_repo/clients/benchmarks.py,sha256=RzHY8VzDP1o2jT4M8gxxbcr3amuNr4mlSblZhhJqG_w,2778
 instance_repo/clients/config.py,sha256=UdfNDqeQnFaOBBAl-Aj-W2JvuouvJ11q-_gB4da9yBg,21209
-instance_repo/clients/datasets.py,sha256=0b94qr-UNXKuEg1zIi3dl1FKd0Rz0TokvlflNdeUL88,24052
+instance_repo/clients/datasets.py,sha256=snSqr4tHVzOCj4HnQlGHoKmqtz1HrxEoMNoja4yrSuI,24497
 instance_repo/clients/images.py,sha256=8i0FXxAAL2mOUUTrVgDdWSYM2imJ5nOEXzpVRBa-G-k,4911
 instance_repo/clients/instances.py,sha256=IOAKl3MAlW3UcftX8b5cGIEdC5_1qfouaVSE_0-OAxE,58125
 instance_repo/clients/reports.py,sha256=4Z8bpcSi-mmfkQLKpMklelLI4mgHcnjfb0725bE2nkI,3001
 instance_repo/clients/scaffold.py,sha256=VLicNFnqKi2iYB-gjOkQ9wa1unNOJXO7UxBZlz7El5A,4998
-instance_repo/clients/splits.py,sha256=9hUZAiLCv0gZpxbEPvxtsJZ0qeGxSxaYl21ARF3sl58,27211
-instance_repo/clients/versions.py,sha256=jeLwV0K5h4lpeeEMPQMnv-BpzfRcm0jiqcGIa0Nl2RI,52658
+instance_repo/clients/splits.py,sha256=o8ygCVAMrxECNojzfUdaHQtuwL4Imzm7ghNKWPxG-VE,28255
+instance_repo/clients/versions.py,sha256=IOzGckKjQGTWC4w1Zqg12hN6bdzX2gClOZdgNCHdeyA,53639
 instance_repo/clients/workflows.py,sha256=6ftl1tuyEGx8BtMLSjfExP9_VcQhK4veo7ex1jDOdlc,3686
 instance_repo/store/__init__.py,sha256=fGwePNjKuojqx1yagSaY-svONE5pjaEz2BZmG0ISUZ0,674
 instance_repo/store/acr.py,sha256=OD7LH3GZY4HrrbEht86Mf3NfW_lh-8MhCTOGyX6gLT4,19468
 instance_repo/store/base.py,sha256=7feHdDXDvSkq60wXYvF6p8TK9KRj7YTLlESdgZ5MQHo,2622
 instance_repo/store/oss.py,sha256=-1dBPlUBLD0z-aI4GOuO6kwGyIgZX1zRvYCD-IPp-Zs,30672
-instance_repo/store/oss_discovery.py,sha256=4s8n2i8AhiNCKP2LoDaRgELEOLW3quodRgREhMM0I3g,20008
+instance_repo/store/oss_discovery.py,sha256=gFZmHkpl1136hsXGL2CEBcHEbnpbTz3kAt2OZA71U-E,25894
 instance_repo/store/registry.py,sha256=1R2GqXsuDZ8wc3IGpncF9yL6IHk-FeiwUlZN7v2ndSc,10837
-instance_repo-1.3.2.dev2.dist-info/METADATA,sha256=H2v_y6ot4xb5UX5sY5YwDfOgEIt96jdDLxPO8NQXVvg,14227
-instance_repo-1.3.2.dev2.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
-instance_repo-1.3.2.dev2.dist-info/entry_points.txt,sha256=tn6jgwYChSx7eAqw9YNed_JFYYgoRtE7WkFn8xqa8Rw,53
-instance_repo-1.3.2.dev2.dist-info/top_level.txt,sha256=mblK0Bkwwp6jCZioS6q3sSuFFs8NR9DKTJ0DJpIRDmY,14
-instance_repo-1.3.2.dev2.dist-info/RECORD,,
+instance_repo-1.3.2.dev4.dist-info/METADATA,sha256=CY7IFFYrk54y2DSipSc5lSGMsFgGQfZiHfdh2ykx518,14227
+instance_repo-1.3.2.dev4.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
+instance_repo-1.3.2.dev4.dist-info/entry_points.txt,sha256=tn6jgwYChSx7eAqw9YNed_JFYYgoRtE7WkFn8xqa8Rw,53
+instance_repo-1.3.2.dev4.dist-info/top_level.txt,sha256=mblK0Bkwwp6jCZioS6q3sSuFFs8NR9DKTJ0DJpIRDmY,14
+instance_repo-1.3.2.dev4.dist-info/RECORD,,