instance-repo 1.3.2.dev5__tar.gz → 1.3.5.dev0__tar.gz

{instance_repo-1.3.2.dev5 → instance_repo-1.3.5.dev0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: instance-repo
-Version: 1.3.2.dev5
+Version: 1.3.5.dev0
 Summary: InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-Requires-Dist: irepo-artifact<0.2.0,>=0.1.1
+Requires-Dist: irepo-artifact<0.3.0,>=0.1.1
 Requires-Dist: tomli>=1.1.0; python_version < "3.11"
 Provides-Extra: oss
 Requires-Dist: oss2>=2.19; extra == "oss"

{instance_repo-1.3.2.dev5 → instance_repo-1.3.5.dev0}/instance_repo/__init__.py

@@ -9,6 +9,7 @@ from .models import (
     DatasetSeries, DatasetVersion, DatasetInstance, ManifestEntry,
     OwnerReference, Feedback, Identity, PushResult,
     RolloutReport, RolloutJob, ScaffoldConfig,
+    DatasetObjectDirectory, DatasetObjectFile, DatasetObjectListResult,
     canonical_json, parse_feedbacks, append_feedback,
 )
 from .errors import (
@@ -18,13 +19,14 @@ from .errors import (
     TransportError,
 )
 
-__version__ = "1.3.2.dev5"
+__version__ = "1.3.5.dev0"
 
 __all__ = [
     "Repo", "load_instances",
     "DatasetSeries", "DatasetVersion", "DatasetInstance", "ManifestEntry",
     "OwnerReference", "Feedback", "Identity", "PushResult",
     "RolloutReport", "RolloutJob", "ScaffoldConfig",
+    "DatasetObjectDirectory", "DatasetObjectFile", "DatasetObjectListResult",
     "canonical_json", "parse_feedbacks", "append_feedback",
     "InstanceRepoError", "LayoutError", "SchemaError", "OwnerRefMissing",
     "ImageMissing", "Immutable", "DigestMismatch", "Forbidden", "NotVisible",

{instance_repo-1.3.2.dev5 → instance_repo-1.3.5.dev0}/instance_repo/clients/datasets.py

@@ -160,7 +160,8 @@ class DatasetsClient:
             return DatasetDetail.from_dict(data) if isinstance(data, dict) else DatasetDetail()
         except TransportError as e:
             if (e.biz_code == 92001 and fallback_to_oss
-                    and self._content is not None):
+                    and self._content is not None
+                    and self._discovery_env_match(environment)):
                 return self._discover_detail(name, storage_env=environment,
                                              metadata_model=metadata_model)
             raise
@@ -396,6 +397,20 @@ class DatasetsClient:
 
     # ── OSS fallback discovery (private) ─────────────────────────────────
 
+    def _discovery_env_match(self, environment: str | None) -> bool:
+        """OSS 回退环境兼容性检查：请求的 environment 须与 profile storage_env 派生环境一致。"""
+        req = (environment or "").strip()
+        if not req:
+            return True
+        if self._p is None:
+            return True
+        from .config import dataset_environment_for
+        derived = dataset_environment_for(
+            getattr(self._p, "storage_env", ""))
+        if not derived:
+            return True
+        return req == derived
+
     def _discover_detail(self, name: str, *,
                          storage_env: str | None = None,
                          metadata_model: str | None = None) -> DatasetDetail:

{instance_repo-1.3.2.dev5 → instance_repo-1.3.5.dev0}/instance_repo/clients/instances.py

@@ -177,12 +177,14 @@ class InstancesClient:
         except TransportError as e:
             # 路径 1: dataset 不存在(92001) → OSS 回退
             if (e.biz_code == 92001
-                    and fallback_to_oss and self._content is not None):
+                    and fallback_to_oss and self._content is not None
+                    and self._discovery_env_match(environment)):
                 return self._discover_instance(
                     dataset, version, instance_id, split)
             raise
         # 路径 2: instance 不存在(None, registry 吞了 92003) → OSS 回退
-        if result is None and fallback_to_oss and self._content is not None:
+        if result is None and fallback_to_oss and self._content is not None \
+                and self._discovery_env_match(environment):
             return self._discover_instance(
                 dataset, version, instance_id, split)
         return result
@@ -203,7 +205,8 @@ class InstancesClient:
             return self._reg.query(dataset, version, split, **overrides)
         except TransportError as e:
             if (e.biz_code == 92001
-                    and fallback_to_oss and self._content is not None):
+                    and fallback_to_oss and self._content is not None
+                    and self._discovery_env_match(environment)):
                 return self._discover_instances(dataset, version, split)
             raise
 
@@ -281,7 +284,8 @@ class InstancesClient:
                 "GET", f"{self._BASE}?{query}")
         except TransportError as e:
             if (e.biz_code == 92001
-                    and fallback_to_oss and self._content is not None):
+                    and fallback_to_oss and self._content is not None
+                    and self._discovery_env_match(environment)):
                 return self._discover_instances_paged(
                     dataset, version, split,
                     q=q, instance_id=instance_id,
@@ -295,6 +299,20 @@ class InstancesClient:
 
     # ── OSS 回退发现（未注册 dataset 的 instance 合成） ──
 
+    def _discovery_env_match(self, environment: str | None) -> bool:
+        """OSS 回退环境兼容性检查：请求的 environment 须与 profile storage_env 派生环境一致。"""
+        req = (environment or "").strip()
+        if not req:
+            return True
+        if self._p is None:
+            return True
+        from .config import dataset_environment_for
+        derived = dataset_environment_for(
+            getattr(self._p, "storage_env", ""))
+        if not derived:
+            return True
+        return req == derived
+
     def _discover_instances(self, dataset: str, version: str,
                             split: str | None = None) -> list[DatasetInstance]:
         """OSS 回退的 instances.list — 从 OSS 列举指定 version/split 下的实例。"""
@@ -366,6 +384,145 @@ class InstancesClient:
                 result[parts[0]] = ""
         return result
 
+    # ── 实例目录/文件列举（GET /datasets/objects）──────────────────
+
+    def list_objects(self, dataset: str, instance_id: str,
+                     split: str | None = None, *,
+                     version: str = "",
+                     prefix: str | None = None,
+                     page_size: int = 100,
+                     token: str | None = None,
+                     environment: str | None = None,
+                     metadata_model: str | None = None,
+                     dataset_split_id: str | None = None
+                     ) -> "DatasetObjectListResult":
+        """列举实例资产目录下的文件/子目录（单页）。
+
+        调用控制面 ``GET /apis/v1/datasets/objects``，返回指定实例的
+        ``{split}-assets/{instance_id}/`` 路径下的目录和文件列表。
+
+        Parameters
+        ----------
+        dataset : str
+            Dataset 名称（``L1/L2`` 格式）。
+        instance_id : str
+            实例 ID。
+        split : str, optional
+            Split 名称；为 None 时使用 ``"default"``。
+        version : str
+            版本号，默认空串（split_first 布局下可为空）。
+        prefix : str, optional
+            子目录前缀过滤（相对于实例资产根目录）；为 None 时列举实例根目录。
+        page_size : int
+            每页大小，默认 100。
+        token : str, optional
+            分页游标（首次传 None，后续传上次返回的 ``next_token``）。
+        environment : str, optional
+            ``online`` / ``pre``，None 时用 profile 派生值。
+        metadata_model : str, optional
+            ``split_first`` / ``version_first``，None 时用 profile 派生值。
+        dataset_split_id : str, optional
+            Split ID，可直接指定以避免 split 名称解析。
+
+        Returns
+        -------
+        DatasetObjectListResult
+            包含 ``directories``、``files``、``next_token``、``truncated``。
+        """
+        from urllib.parse import quote
+        from ..models import DatasetObjectListResult
+        if not (dataset or "").strip():
+            raise SchemaError("dataset is required for instances.list_objects")
+        if not (instance_id or "").strip():
+            raise SchemaError(
+                "instance_id is required for instances.list_objects")
+        split = (split or "default").strip()
+        # 计算实例资产根前缀：{split}-assets/{instance_id}/
+        instance_asset_prefix = f"{split}-assets/{instance_id.strip()}"
+        if prefix:
+            full_prefix = f"{instance_asset_prefix}/{prefix.strip().strip('/')}"
+        else:
+            full_prefix = instance_asset_prefix
+        # 构建查询参数
+        params: list[tuple[str, str]] = [
+            ("dataset_name", dataset.strip()),
+            ("split", split),
+            ("prefix", full_prefix),
+            ("page_size", str(int(page_size)))]
+        if (version or "").strip():
+            params.append(("version", version.strip()))
+        if (dataset_split_id or "").strip():
+            params.append(("dataset_split_id", dataset_split_id.strip()))
+        if (token or "").strip():
+            params.append(("token", token.strip()))
+        # environment / metadata_model：优先显式值，其次 profile 派生
+        env = (environment or "").strip()
+        if not env:
+            env = (getattr(self._p, "dataset_environment", "") or "").strip()
+        if env:
+            params.append(("environment", env))
+        mm = (metadata_model or "").strip()
+        if not mm:
+            mm = (getattr(self._p, "metadata_model", "") or "").strip()
+        if mm:
+            params.append(("metadata_model", mm))
+        qs = "&".join(f"{k}={quote(v, safe='')}" for k, v in params)
+        data = self._t.get(f"/apis/v1/datasets/objects?{qs}")
+        if isinstance(data, dict):
+            return DatasetObjectListResult.from_dict(data)
+        return DatasetObjectListResult()
+
+    def list_all_objects(self, dataset: str, instance_id: str,
+                         split: str | None = None, *,
+                         version: str = "",
+                         prefix: str | None = None,
+                         environment: str | None = None,
+                         metadata_model: str | None = None,
+                         dataset_split_id: str | None = None,
+                         page_size: int = 100,
+                         max_pages: int = 50
+                         ) -> "DatasetObjectListResult":
+        """自动翻页列举实例资产目录下的全部文件/子目录。
+
+        反复调用 :meth:`list_objects` 直到 ``truncated=False`` 或达到
+        ``max_pages`` 上限，合并所有页的 ``directories`` 和 ``files``。
+
+        Parameters
+        ----------
+        max_pages : int
+            最大翻页数（安全阀，防无限循环），默认 50。
+
+        其余参数同 :meth:`list_objects`。
+
+        Returns
+        -------
+        DatasetObjectListResult
+            合并后的完整结果，``truncated`` 反映是否因 ``max_pages`` 截断。
+        """
+        from ..models import DatasetObjectListResult
+        all_dirs: list = []
+        all_files: list = []
+        tk: str | None = None
+        result = DatasetObjectListResult()
+        for _ in range(max_pages):
+            page = self.list_objects(
+                dataset, instance_id, split,
+                version=version, prefix=prefix,
+                page_size=page_size, token=tk,
+                environment=environment,
+                metadata_model=metadata_model,
+                dataset_split_id=dataset_split_id)
+            all_dirs.extend(page.directories)
+            all_files.extend(page.files)
+            result = page  # 保留最后一页的 dataset/version/prefix 元信息
+            if not page.truncated or not page.next_token:
+                break
+            tk = page.next_token
+        result.directories = all_dirs
+        result.files = all_files
+        # 若因 max_pages 截断，truncated 保持 True + 保留 next_token
+        return result
+
     def update(self, dataset: str, version: str, instance_id: str, *,
                split: str | None = None, dataset_split_id: str | None = None,
                manifest: list[dict] | None = None,
@@ -850,7 +1007,8 @@ class InstancesClient:
         return results
 
     def pull(self, dataset: str, version: str, instance_id: str, dest_dir,
-             split: str = "default", *, verify: bool = True) -> Path:
+             split: str = "default", *, verify: bool = True,
+             fallback_to_oss: bool = True) -> Path:
         """下载实例内容。自动检测格式：harbor 下载 content.tgz，swe 下载 {id}.json，
         custom 下载 {id}.json + assets 目录。
 
@@ -860,6 +1018,8 @@ class InstancesClient:
         2. 无元数据或 manifest 无法区分 swe/custom → 下载 metadata JSON 检查
            metadata_model 字段（custom → 下载 assets 目录；否则 swe）
         3. metadata JSON 不存在 → fallback 到 harbor（下载 content.tgz）
+        4. dataset 未注册（92001）→ OSS 回退：list-only 枚举文件树 + 逐文件下载
+           （仍走 DOWNLOAD 意图：仅私网，公网下载照旧禁止）
         """
         validate_instance_id(instance_id, source="pull()")
         expected = None
@@ -869,7 +1029,15 @@ class InstancesClient:
         meta_bytes: bytes | None = None
 
         if verify:
-            meta = self._reg.get(dataset, version, instance_id, split)
+            try:
+                meta = self._reg.get(dataset, version, instance_id, split)
+            except TransportError as e:
+                if (e.biz_code == 92001 and fallback_to_oss
+                        and self._content is not None):
+                    # dataset 未注册 → OSS 回退下载（私网 + 系统调用方语义）
+                    return self._pull_unregistered(
+                        dataset, version, instance_id, dest_dir, split)
+                raise
             if meta is not None and meta.manifest:
                 has_tgz = False
                 for m in meta.manifest:
@@ -1044,6 +1212,47 @@ class InstancesClient:
             downloaded.append(local_path)
         return downloaded
 
+    def _pull_unregistered(self, dataset: str, version: str,
+                           instance_id: str, dest_dir, split: str) -> Path:
+        """未注册 dataset 的 pull 回退：list-only 枚举文件树 + 逐文件下载。
+
+        下载仍走 :meth:`~instance_repo.store.oss.OssContentStore.get_object`
+        的 DOWNLOAD 意图——**仅私网可用，公网下载照旧被拒**（与注册路径一致）。
+
+        STS 语义：未注册 dataset 无 RBAC 记录，GetObject STS 仅 system 白名单
+        调用方可签发（非 system 调用方在签发阶段收到明确错误），与历史行为一致。
+
+        产物结构（harbor 同层，便于 CLI 整体搬移）::
+
+            {dest_dir}/{instance_id}/{instance_id}.json     # metadata
+            {dest_dir}/{instance_id}/<assets 相对路径>      # assets 文件
+            {dest_dir}/{instance_id}/report/<report 相对路径>  # report 文件
+
+        Returns the metadata JSON 本地路径。
+        """
+        from ..store.oss_discovery import discover_instance_file_tree
+
+        tree = discover_instance_file_tree(
+            self._content, dataset, version, instance_id, split,
+            oss_prefix=self._oss_prefix)
+        if tree is None:
+            from ..errors import DatasetNotFound
+            raise DatasetNotFound(
+                f"instance {instance_id!r} not found in OSS for "
+                f"dataset {dataset!r}")
+
+        metadata_key, files = tree
+        dest_root = Path(dest_dir) / instance_id
+        dest_root.mkdir(parents=True, exist_ok=True)
+        metadata_dest = dest_root / f"{instance_id}.json"
+
+        self._content.get_object(metadata_key, metadata_dest, dataset=dataset)
+        for key, rel in files:
+            local_path = dest_root / rel
+            local_path.parent.mkdir(parents=True, exist_ok=True)
+            self._content.get_object(key, local_path, dataset=dataset)
+        return metadata_dest
+
     def pull_many(self, instance_ids: list[str], dataset: str, version: str,
                   dest_dir, *, split: str = "default",
                   concurrency: int = 8, continue_on_error: bool = False,

{instance_repo-1.3.2.dev5 → instance_repo-1.3.5.dev0}/instance_repo/clients/splits.py

@@ -103,7 +103,8 @@ class SplitsClient:
         except TransportError as e:
             # ── 2. 92001 异常 → 直接进入 OSS 回退 ──
             if (e.biz_code == 92001
-                    and fallback_to_oss and self._content is not None):
+                    and fallback_to_oss and self._content is not None
+                    and self._discovery_env_match(environment)):
                 return self._discover_splits(
                     dataset, version, scope, status, page, page_size)
             raise
@@ -114,7 +115,8 @@ class SplitsClient:
         if not items and not (status or "").strip():
             items = self._legacy_list(dataset, version, self._env(environment))
         # ── 3b. 仍为空 → OSS 回退 ──
-        if not items and fallback_to_oss and self._content is not None:
+        if not items and fallback_to_oss and self._content is not None \
+                and self._discovery_env_match(environment):
             return self._discover_splits(
                 dataset, version, scope, status, page, page_size)
         return PagedResult.from_response(items, pagination, int(page), int(page_size))
@@ -156,7 +158,8 @@ class SplitsClient:
                 if result is not None:
                     return result
                 # Legacy 回退无果 → OSS 回退
-                if fallback_to_oss and self._content is not None:
+                if fallback_to_oss and self._content is not None \
+                        and self._discovery_env_match(environment):
                     return self._discover_split(dataset, split, version)
                 return None
             raise
@@ -261,11 +264,14 @@ class SplitsClient:
                          page: int, page_size: int) -> PagedResult:
         """OSS 回退的 splits.list — 处理 version_scope 和 status 过滤。
 
-        注意：回退场景（dataset 未注册）下 ``version_scope`` 是 MongoDB 语义，
-        OSS 探测无从区分 versioned/unversioned——**忽略 scope 并返回全部探测结果**
-        （G4：否则 ap CLI 无 --version 的 split list 恒空）。``version`` 非空时
-        仍精确匹配该 version；version 为空时额外包含 split_first 无版本 split
-        （version="" 归属）。
+        split_first 模式下 OSS 探测可区分无版本 split（level-1 目录只有 .json）
+        和有版本 split（level-1 目录含子目录），因此 ``version_scope`` 生效：
+
+        - ``"unversioned"``: 只返回无版本 split
+        - ``"versioned"``: 只返回有版本 split
+        - ``"all"`` / None: 返回全部（SDK 默认行为）
+
+        ``version`` 非空时仍精确匹配该 version。
         """
         from ..store.oss_discovery import (
             parse_dataset_level, build_synthetic_split,
@@ -276,21 +282,23 @@ class SplitsClient:
             metadata_model=self._discovery_mm())
         _warn_if_truncated(info, dataset, 500)
         splits: list[DatasetSplit] = []
+        scope = (version_scope or "all").strip().lower()
         # split_first 无版本布局：dataset 根下直接是 split 目录
-        if not version:
+        if not version and scope in ("all", "unversioned"):
             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
-            if v.has_default_instances:
-                splits.append(build_synthetic_split(
-                    dataset, v.version, "default",
-                    instance_count=v.default_instance_count))
-            for s in v.splits:
-                splits.append(build_synthetic_split(
-                    dataset, v.version, s))
+        if scope in ("all", "exact"):
+            for v in info.versions:
+                if version and v.version != version:
+                    continue
+                if v.has_default_instances:
+                    splits.append(build_synthetic_split(
+                        dataset, v.version, "default",
+                        instance_count=v.default_instance_count))
+                for s in v.splits:
+                    splits.append(build_synthetic_split(
+                        dataset, v.version, s))
         if (status or "").strip():
             splits = [s for s in splits if s.status == status.strip()]
         return _in_memory_paged(splits, int(page), int(page_size))
@@ -329,6 +337,27 @@ class SplitsClient:
             getattr(self._p, "metadata_model", None)
             if self._p is not None else None)
 
+    def _discovery_env_match(self, environment: str | None) -> bool:
+        """OSS 回退环境兼容性检查。
+
+        请求的 ``environment`` 必须与 profile 的 storage_env 派生环境一致，
+        否则 OSS 回退返回空——因为 bucket 是按 storage_env 绑定的，dev 桶里
+        的数据不应作为 online 结果返回（反之亦然）。
+
+        ``environment`` 为空时视为兼容（跟随 profile 默认环境）。
+        """
+        req = (environment or "").strip()
+        if not req:
+            return True
+        if self._p is None:
+            return True
+        from .config import dataset_environment_for
+        derived = dataset_environment_for(
+            getattr(self._p, "storage_env", ""))
+        if not derived:
+            return True  # 无法派生时不做限制
+        return req == derived
+
     # ── 写 ──
 
     def _post_create(self, dataset: str, split: str, version: str,

{instance_repo-1.3.2.dev5 → instance_repo-1.3.5.dev0}/instance_repo/clients/versions.py

@@ -228,7 +228,8 @@ class VersionsClient:
             return [DatasetVersion(**_pick(r)) for r in (rows or [])]
         except TransportError as e:
             if (e.biz_code == 92001 and fallback_to_oss
-                    and self._content is not None):
+                    and self._content is not None
+                    and self._discovery_env_match(environment)):
                 return self._discover_versions(dataset, metadata_model=metadata_model)
             raise
 
@@ -262,7 +263,8 @@ class VersionsClient:
             data, pagination = self._t.request_with_meta("GET", f"{self._BASE}?{q}")
         except TransportError as e:
             if (e.biz_code == 92001 and fallback_to_oss
-                    and self._content is not None):
+                    and self._content is not None
+                    and self._discovery_env_match(environment)):
                 return self._discover_versions_paged(
                     dataset, status, int(page), int(page_size),
                     metadata_model=metadata_model)
@@ -295,7 +297,8 @@ class VersionsClient:
             return DatasetVersion.from_dict_full(data) if isinstance(data, dict) else DatasetVersion(version=version, dataset=dataset)
         except TransportError as e:
             if (e.biz_code == 92001 and fallback_to_oss
-                    and self._content is not None):
+                    and self._content is not None
+                    and self._discovery_env_match(environment)):
                 return self._discover_version(dataset, version,
                                               metadata_model=metadata_model)
             raise
@@ -939,6 +942,20 @@ class VersionsClient:
             getattr(self._p, "metadata_model", None)
             if self._p is not None else None)
 
+    def _discovery_env_match(self, environment: str | None) -> bool:
+        """OSS 回退环境兼容性检查：请求的 environment 须与 profile storage_env 派生环境一致。"""
+        req = (environment or "").strip()
+        if not req:
+            return True
+        if self._p is None:
+            return True
+        from .config import dataset_environment_for
+        derived = dataset_environment_for(
+            getattr(self._p, "storage_env", ""))
+        if not derived:
+            return True
+        return req == derived
+
 
 # 与 apiserver `DatasetVersionListItem`（pkg/server/dataset_service.go:315）对齐:
 # 列表项带 instance_count/split_count/updated_at/last_ingested_at,详情接口才带

{instance_repo-1.3.2.dev5 → instance_repo-1.3.5.dev0}/instance_repo/models.py

@@ -871,3 +871,82 @@ class RoleBinding:
             role_id=d.get("role_id", ""),
             added_by=d.get("added_by", ""),
             added_at=d.get("added_at", ""))
+
+
+# ── Dataset Objects（目录/文件列举）──────────────────────────────────
+
+@dataclass
+class DatasetObjectDirectory:
+    """``GET /datasets/objects`` 返回的目录项。"""
+    name: str
+    path: str
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "DatasetObjectDirectory":
+        return cls(name=d.get("name", ""), path=d.get("path", ""))
+
+    def to_dict(self) -> dict:
+        return {"name": self.name, "path": self.path}
+
+
+@dataclass
+class DatasetObjectFile:
+    """``GET /datasets/objects`` 返回的文件项。"""
+    name: str
+    path: str
+    size_bytes: int = 0
+    content_type: str = ""
+    previewable: bool = False
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "DatasetObjectFile":
+        return cls(
+            name=d.get("name", ""),
+            path=d.get("path", ""),
+            size_bytes=int(d.get("size_bytes", 0)),
+            content_type=d.get("content_type", ""),
+            previewable=bool(d.get("previewable", False)))
+
+    def to_dict(self) -> dict:
+        return {"name": self.name, "path": self.path,
+                "size_bytes": self.size_bytes,
+                "content_type": self.content_type,
+                "previewable": self.previewable}
+
+
+@dataclass
+class DatasetObjectListResult:
+    """``GET /datasets/objects`` 分页响应。
+
+    ``directories`` 和 ``files`` 为当前页条目；``truncated`` 为 True 时
+    可用 ``next_token`` 继续翻页。
+    """
+    dataset: str = ""
+    version: str = ""
+    prefix: str = ""
+    directories: list[DatasetObjectDirectory] = field(default_factory=list)
+    files: list[DatasetObjectFile] = field(default_factory=list)
+    next_token: str = ""
+    truncated: bool = False
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "DatasetObjectListResult":
+        return cls(
+            dataset=d.get("dataset", ""),
+            version=d.get("version", ""),
+            prefix=d.get("prefix", ""),
+            directories=[DatasetObjectDirectory.from_dict(x)
+                         for x in d.get("directories", [])],
+            files=[DatasetObjectFile.from_dict(x)
+                   for x in d.get("files", [])],
+            next_token=d.get("next_token", ""),
+            truncated=bool(d.get("truncated", False)))
+
+    def to_dict(self) -> dict:
+        return {
+            "dataset": self.dataset, "version": self.version,
+            "prefix": self.prefix,
+            "directories": [d.to_dict() for d in self.directories],
+            "files": [f.to_dict() for f in self.files],
+            "next_token": self.next_token,
+            "truncated": self.truncated}

{instance_repo-1.3.2.dev5 → instance_repo-1.3.5.dev0}/instance_repo/store/oss.py

@@ -467,7 +467,8 @@ class OssContentStore(BaseContentStore):
             lambda bucket: bucket.object_exists(key),
         )
 
-    def list_objects(self, prefix: str, *, list_only: bool = False) -> list[str]:
+    def list_objects(self, prefix: str, *, list_only: bool = False,
+                     dataset: str | None = None) -> list[str]:
         def list_all(bucket):
             keys: list[str] = []
             marker = ""
@@ -481,10 +482,11 @@ class OssContentStore(BaseContentStore):
             return keys
 
         return self._execute_oss(
-            _OperationIntent.NON_DOWNLOAD, prefix, None, list_all,
+            _OperationIntent.NON_DOWNLOAD, prefix, dataset, list_all,
             list_only=list_only)
 
-    def list_prefixes(self, prefix: str, *, list_only: bool = False) -> list[str]:
+    def list_prefixes(self, prefix: str, *, list_only: bool = False,
+                       dataset: str | None = None) -> list[str]:
         """List immediate child *directories* under *prefix* using ``delimiter='/'``.
 
         Returns stripped directory names (without the parent prefix or trailing
@@ -515,11 +517,12 @@ class OssContentStore(BaseContentStore):
             return names
 
         return self._execute_oss(
-            _OperationIntent.NON_DOWNLOAD, prefix, None, list_dirs,
+            _OperationIntent.NON_DOWNLOAD, prefix, dataset, list_dirs,
             list_only=list_only)
 
     def list_level(self, prefix: str, *,
-                   list_only: bool = False) -> tuple[list[str], list[str]]:
+                   list_only: bool = False,
+                   dataset: str | None = None) -> tuple[list[str], list[str]]:
         """Single-level listing with ``delimiter='/'``.
 
         Returns ``(dir_names, file_keys)`` where *dir_names* are stripped
@@ -549,7 +552,7 @@ class OssContentStore(BaseContentStore):
             return names, keys
 
         return self._execute_oss(
-            _OperationIntent.NON_DOWNLOAD, prefix, None, list_one_level,
+            _OperationIntent.NON_DOWNLOAD, prefix, dataset, list_one_level,
             list_only=list_only)
 
     # ── directory-level helpers（自定义格式实例 = 目录级上传/下载）──

{instance_repo-1.3.2.dev5 → instance_repo-1.3.5.dev0}/instance_repo/store/oss_discovery.py

@@ -235,7 +235,7 @@ def parse_dataset_level(
     # -- Level 1: list immediate children under the dataset root -----------
     try:
         level1_names, level1_all_keys = content_store.list_level(
-            root, list_only=True)
+            root, list_only=True, dataset=dataset)
     except TransportError as e:
         if e.status == 403:
             # OSS fallback requires ListObjects permission, which is only granted
@@ -293,7 +293,7 @@ def parse_dataset_level(
         group_dir = f"{root}{name}/"
         try:
             level2_names, level2_keys = content_store.list_level(
-                group_dir, list_only=True)
+                group_dir, list_only=True, dataset=dataset)
         except Exception:  # noqa: BLE001
             level2_names, level2_keys = [], []
         l2_groups = _group_level_names(level2_names)
@@ -316,7 +316,7 @@ def parse_dataset_level(
             split_dir = f"{group_dir}{s_name}/"
             try:
                 _s_dirs, s_keys = content_store.list_level(
-                    split_dir, list_only=True)
+                    split_dir, list_only=True, dataset=dataset)
                 instance_count += len(_direct_json_keys(s_keys, split_dir))
             except Exception:  # noqa: BLE001
                 pass  # best-effort
@@ -540,7 +540,8 @@ def build_synthetic_instances(
     """
     metadata_prefix = _metadata_prefix(dataset, version, split, oss_prefix)
 
-    all_keys = content_store.list_objects(metadata_prefix, list_only=True)
+    all_keys = content_store.list_objects(
+        metadata_prefix, list_only=True, dataset=dataset)
     json_keys = _direct_json_keys(all_keys, metadata_prefix)
 
     instances: list[DatasetInstance] = []
@@ -585,6 +586,62 @@ def _format_from_key(key: str) -> str:
     return ""
 
 
+def discover_instance_file_tree(
+    content_store,
+    dataset: str,
+    version: str,
+    instance_id: str,
+    split: str | None,
+    *,
+    oss_prefix: str,
+) -> tuple[str, list[tuple[str, str]]] | None:
+    """用 LIST 枚举实例的完整文件树（发现模式，list-only STS）。
+
+    Returns ``(metadata_key, files)`` where *files* is a list of
+    ``(oss_key, rel_path)`` tuples covering ``{split}-assets/{id}/`` 与
+    ``{split}-report/{id}/`` 下的所有对象。*rel_path* 相对实例根（assets
+    文件为原相对路径，report 文件加 ``report/`` 前缀避免与 assets 同名冲突）。
+
+    实例不存在（metadata .json 的精确 key LIST 未命中）时返回 ``None``。
+    """
+    if version:
+        metadata_key = P.metadata_key(
+            dataset, version, instance_id, split, prefix=oss_prefix)
+    else:
+        l1, l2 = P.split_dataset(dataset)
+        base = f"{oss_prefix}/{l1}/{l2}"
+        metadata_key = (f"{base}/{split}/{instance_id}.json"
+                        if split and split != "default"
+                        else f"{base}/{instance_id}.json")
+
+    # 存在性判定用 LIST（list-only STS 无 GetObject，不能 HEAD）。
+    # 不能用「prefix=精确 key」的 LIST：OSS 的 prefix 过滤是字符串前缀语义，
+    # 且 RAM 条件只放行 {parent}/*（精确 key 会带出同前缀兄弟对象，见 apiserver
+    # sts/client.go），改为父目录 LIST + 客户端成员判断。
+    parent = metadata_key.rsplit("/", 1)[0] + "/"
+    try:
+        if metadata_key not in content_store.list_objects(
+                parent, list_only=True, dataset=dataset):
+            return None
+    except Exception:  # noqa: BLE001
+        return None
+
+    files: list[tuple[str, str]] = []
+    for suffix, rel_prefix in (("assets", ""), ("report", "report/")):
+        dir_prefix = _instance_dir(dataset, version, split, instance_id,
+                                   suffix, oss_prefix)
+        try:
+            for k in content_store.list_objects(
+                    dir_prefix, list_only=True, dataset=dataset):
+                if k.endswith("/") or not k.startswith(dir_prefix):
+                    continue  # 目录标记 / 异常 key
+                rel = rel_prefix + k[len(dir_prefix):]
+                files.append((k, rel))
+        except Exception:  # noqa: BLE001
+            pass  # best-effort：无 assets/report 目录时忽略
+    return metadata_key, files
+
+
 def _instance_manifest(
     content_store,
     dataset: str,
@@ -600,15 +657,13 @@ def _instance_manifest(
     发现模式（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 目录时忽略
+    tree = discover_instance_file_tree(
+        content_store, dataset, version, instance_id, split,
+        oss_prefix=oss_prefix)
+    if tree is None:
+        return []
+    _meta_key, files = tree
+    keys = [_meta_key] + [k for k, _ in files]
     bucket = getattr(content_store, "bucket_name", "") or ""
     return [
         ManifestEntry(
@@ -657,8 +712,12 @@ def build_synthetic_instance(
     # 存在性判定用 LIST（list_only=True 仅需 ListObjects）而非 HEAD——
     # list-only STS 无 oss:GetObject，object_exists 的 HEAD 会在 STS 签发或
     # OSS 侧被拒，导致已存在的实例恒被误判为不存在。
+    # 不能用「prefix=精确 key」的 LIST（OSS 字符串前缀语义会带出兄弟对象，
+    # RAM 条件也只放行父目录形态），改父目录 LIST + 客户端成员判断。
+    parent = key.rsplit("/", 1)[0] + "/"
     try:
-        keys = content_store.list_objects(key, list_only=True)
+        keys = content_store.list_objects(
+            parent, list_only=True, dataset=dataset)
     except Exception:  # noqa: BLE001
         return None
 

{instance_repo-1.3.2.dev5 → instance_repo-1.3.5.dev0}/instance_repo.egg-info/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: instance-repo
-Version: 1.3.2.dev5
+Version: 1.3.5.dev0
 Summary: InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-Requires-Dist: irepo-artifact<0.2.0,>=0.1.1
+Requires-Dist: irepo-artifact<0.3.0,>=0.1.1
 Requires-Dist: tomli>=1.1.0; python_version < "3.11"
 Provides-Extra: oss
 Requires-Dist: oss2>=2.19; extra == "oss"

{instance_repo-1.3.2.dev5 → instance_repo-1.3.5.dev0}/instance_repo.egg-info/requires.txt

@@ -1,4 +1,4 @@
-irepo-artifact<0.2.0,>=0.1.1
+irepo-artifact<0.3.0,>=0.1.1
 
 [:python_version < "3.11"]
 tomli>=1.1.0

{instance_repo-1.3.2.dev5 → instance_repo-1.3.5.dev0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "instance-repo"
-version = "1.3.2.dev5"
+version = "1.3.5.dev0"
 description = "InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）"
 requires-python = ">=3.10"
 readme = "README.md"
 # tomllib 是 3.11 内置；3.10 上回退到 tomli（见 validate.py），故按 Python 版本条件依赖。
 dependencies = [
-    "irepo-artifact>=0.1.1,<0.2.0",
+    "irepo-artifact>=0.1.1,<0.3.0",
     "tomli>=1.1.0; python_version < '3.11'",
 ]