instance-repo 1.3.0.dev0__tar.gz → 1.3.2__tar.gz

{instance_repo-1.3.0.dev0 → instance_repo-1.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: instance-repo
-Version: 1.3.0.dev0
+Version: 1.3.2
 Summary: InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -58,6 +58,12 @@ pip install "instance-repo[oss]"     # 需要数据面 OSS 读写时，附带 os
 `profile_overrides={"acr_namespace": ...}`；默认 namespace 由 repo-config 返回，但**必须由部署方
 在 ACR 企业版实例中预建**，SDK 不会创建）。
 
+**公网 ACR registry（runner 不在 VPC 内网时）**：默认使用 repo-config 返回的 `registry`
+（VPC 内网域名）。runner 不在对应 VPC 内时，设环境变量 `IR_ACR_PREFER_PUBLIC=1`（或
+`Repo(profile_overrides={"prefer_public_registry": True})`），SDK 会改走 `public_registry`
+（公网域名）；公网值缺失时静默回落到 VPC 值。也可用 `IR_ACR_PUBLIC_HOST` /
+`profile_overrides={"acr_public_host": ...}` 显式指定公网 registry。
+
 兼容别名表：
 
 | 旧名 | 新名或状态 | 优先级 | 告警 |

{instance_repo-1.3.0.dev0 → instance_repo-1.3.2}/README.md

@@ -44,6 +44,12 @@ pip install "instance-repo[oss]"     # 需要数据面 OSS 读写时，附带 os
 `profile_overrides={"acr_namespace": ...}`；默认 namespace 由 repo-config 返回，但**必须由部署方
 在 ACR 企业版实例中预建**，SDK 不会创建）。
 
+**公网 ACR registry（runner 不在 VPC 内网时）**：默认使用 repo-config 返回的 `registry`
+（VPC 内网域名）。runner 不在对应 VPC 内时，设环境变量 `IR_ACR_PREFER_PUBLIC=1`（或
+`Repo(profile_overrides={"prefer_public_registry": True})`），SDK 会改走 `public_registry`
+（公网域名）；公网值缺失时静默回落到 VPC 值。也可用 `IR_ACR_PUBLIC_HOST` /
+`profile_overrides={"acr_public_host": ...}` 显式指定公网 registry。
+
 兼容别名表：
 
 | 旧名 | 新名或状态 | 优先级 | 告警 |

{instance_repo-1.3.0.dev0 → instance_repo-1.3.2}/instance_repo/__init__.py

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

{instance_repo-1.3.0.dev0 → instance_repo-1.3.2}/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-1.3.0.dev0 → instance_repo-1.3.2}/instance_repo/bootstrap.py

@@ -36,7 +36,8 @@ _logger = logging.getLogger(__name__)
 DISCOVERY_TTL_SECONDS = 3600.0
 
 #: 由自动发现填充的字段（scaffold 两项不在 repo-config 返回范围内，仍须显式提供）。
-DISCOVERABLE_FIELDS = ("oss_bucket", "oss_prefix", "acr_host", "acr_namespace")
+DISCOVERABLE_FIELDS = ("oss_bucket", "oss_prefix", "acr_host",
+                       "acr_public_host", "acr_namespace")
 
 _cache = TTLCache(safety=0.0)
 _lock = threading.Lock()

{instance_repo-1.3.0.dev0 → instance_repo-1.3.2}/instance_repo/cli.py

@@ -42,7 +42,7 @@ def build_parser() -> argparse.ArgumentParser:
     ap.add_argument("--storage-env", dest="global_storage_env", default=None,
                     help="数据面存储环境（亦可用 IR_STORAGE_ENV）；SDK 据此自动向 "
                          "apiserver 的 repo-config 拉取 OSS/ACR 寻址并缓存")
-    ap.add_argument("--metadata-model", default=None,
+    ap.add_argument("--metadata-model", default="split_first",
                     choices=["split_first", "version_first"],
                     help="元数据模型；缺省 split_first（split 必填、version 选填）。"
                          "旧数据集用 version_first（version 必填、split 选填）")
@@ -313,7 +313,7 @@ def build_parser() -> argparse.ArgumentParser:
                      help="split 级打标，格式 name=train,name2=eval（与 --run-type 互斥）")
     ver.add_argument("--environment", default=None,
                      help="create/get/ingest 用：覆盖 profile 派生的 environment（pre/online）")
-    ver.add_argument("--metadata-model", default=None,
+    ver.add_argument("--metadata-model", default="split_first",
                      help="create/ingest 用：显式指定元数据模型（split_first/version_first）")
     ver.add_argument("--dry-run", action="store_true",
                      help="ingest 用：只预览扫描结果不落库")
@@ -385,7 +385,7 @@ def build_parser() -> argparse.ArgumentParser:
     ds.add_argument("--environment", default=None,
                     help="get/update 覆盖 profile 派生的 environment")
     ds.add_argument("--metadata-model", choices=["split_first", "version_first"],
-                    default=None, dest="metadata_model")
+                    default="split_first", dest="metadata_model")
     # update 用（至少一项）
     ds.add_argument("--display-name", default=None, dest="display_name")
     ds.add_argument("--description", default=None)
@@ -724,13 +724,16 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
                                          tags=tags_dict, difficulty=args.difficulty,
                                          page=args.page, page_size=args.page_size)
             for inst in res.items:
-                print(f"{inst.instance_id}\t{inst.difficulty}\t{inst.docker_image}",
+                src = "\t[oss]" if not inst.registered else ""
+                print(f"{inst.instance_id}\t{inst.difficulty}\t{inst.docker_image}{src}",
                       file=out)
             print(f"page={res.page}/{(res.total+res.page_size-1)//res.page_size if res.total>0 else 1} "
                   f"total={res.total} has_more={res.has_more}", file=out)
             return 0
         for inst in r.instances.list(dataset, version, args.split):
-            print(f"{inst.instance_id}\t{inst.difficulty}\t{inst.docker_image}", file=out)
+            src = "\t[oss]" if not inst.registered else ""
+            print(f"{inst.instance_id}\t{inst.difficulty}\t{inst.docker_image}{src}",
+                  file=out)
         return 0
 
     if args.cmd == "pull":
@@ -910,7 +913,9 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
         # 实例不存在时库层返回 None（apiserver 92003），显式区分"查不到"与"字段为空"。
         if inst is None:
             raise SystemExit(f"instance {dataset}/{version}/{iid} not found")
-        print(f"{inst.instance_id}\t{inst.difficulty}\t{inst.docker_image}", file=out)
+        src = "\t[oss]" if not inst.registered else ""
+        print(f"{inst.instance_id}\t{inst.difficulty}\t{inst.docker_image}{src}",
+              file=out)
         return 0
 
     if args.cmd == "version":
@@ -931,7 +936,9 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
             dataset, _, _ = _resolve_target(args, 2)
             if args.action == "list":
                 for v in r.versions.list(dataset):
-                    print(f"{v.version}\t{v.status}\t{v.storage_path}", file=out)
+                    src = "\t[oss]" if not v.registered else ""
+                    print(f"{v.version}\t{v.status}\t{v.storage_path}{src}",
+                          file=out)
                 return 0
             if not args.version:
                 raise SystemExit("version create 需要 --version")
@@ -1026,7 +1033,8 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
                                 status=args.status,
                                 page=args.page, page_size=args.page_size)
             for s in res.items:
-                src = "projected" if s.projected else "record"
+                src = "projected" if s.projected else (
+                    "oss" if not s.registered else "record")
                 print(f"{s.name}\tversion={s.version or ''}\tstatus={s.status}"
                       f"\trun_type={s.run_type or ''}\t"
                       f"instance_count={_split_instance_count(s)}\t[{src}]",
@@ -1094,13 +1102,17 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
         if args.action == "get":
             d = r.datasets.get_detail(dataset, environment=args.environment,
                                       metadata_model=args.metadata_model)
+            src = "oss" if not d.registered else "mongodb"
             print(f"dataset\t{d.dataset_name}\tid={d.dataset_id}"
-                  f"\tvisibility={d.visibility}", file=out)
+                  f"\tvisibility={d.visibility}\t[{src}]", file=out)
             print(f"version_count={d.version_count}\tsplit_count={d.split_count}"
                   f"\tlatest={d.latest_version or ''}", file=out)
             print(f"instance_count={d.stats.instance_count}"
                   f"\tfile_count={d.stats.file_count}"
                   f"\tsize_bytes={d.stats.size_bytes}", file=out)
+            if not d.registered:
+                print("warning: dataset not registered in MongoDB, "
+                      "data from OSS discovery", file=sys.stderr)
             return 0
         if args.action == "update":
             kwargs = {}

{instance_repo-1.3.0.dev0 → instance_repo-1.3.2}/instance_repo/clients/config.py

@@ -76,6 +76,11 @@ ENV_OSS_PREFIX = "IR_OSS_PREFIX"
 ENV_SCAFFOLD_BUCKET = "IR_SCAFFOLD_BUCKET"
 ENV_SCAFFOLD_ROOT = "IR_SCAFFOLD_ROOT"
 
+# 公网 ACR registry：runner 不在 VPC 内网时，可显式切换使用公网 registry。
+ENV_ACR_PUBLIC_HOST = "IR_ACR_PUBLIC_HOST"
+# 是否优先使用公网 registry（"1"/"true"/"on"，大小写不敏感）。
+ENV_ACR_PREFER_PUBLIC = "IR_ACR_PREFER_PUBLIC"
+
 #: v0.8 弃用的手工寻址环境变量 → 建议替代。scaffold 两项不在其中：scaffold 包不在
 #: repo-config 的返回范围内，仍须显式提供。
 DEPRECATED_ADDRESS_ENVS = {
@@ -179,6 +184,7 @@ class Profile:
     name: str
     oss_bucket: str = ""
     acr_host: str = ""
+    acr_public_host: str = ""
     acr_namespace: str = ""
     oss_prefix: str = DEFAULT_OSS_PREFIX
     scaffold_bucket: str = ""
@@ -197,6 +203,21 @@ class Profile:
     #: ``bootstrap.discover()`` 捕获异常时写入；``require()`` 据此在报错消息里
     #: 透传根因，避免"返回里没有 acr_host"这类误导性口径。
     discovery_error: str = ""
+    #: 优先使用公网 ACR registry（默认 False=走 VPC 内网）。runner 不在 VPC
+    #: 内网时置 True，配合 ``acr_public_host``（repo-config 的 public_registry）
+    #: 生效；公网值缺失时静默回落到 ``acr_host``。
+    prefer_public_registry: bool = False
+
+    @property
+    def effective_acr_host(self) -> str:
+        """ACR 操作实际使用的 registry host。
+
+        默认返回 ``acr_host``（repo-config 的 registry，通常是 VPC 内网域名）；
+        ``prefer_public_registry=True`` 且 ``acr_public_host`` 非空时返回公网域名。
+        """
+        if self.prefer_public_registry and self.acr_public_host:
+            return self.acr_public_host
+        return self.acr_host
 
     @property
     def dataset_environment(self) -> str:
@@ -240,12 +261,14 @@ def load_profile(name: str = "default", *, overrides: dict | None = None,
         storage_env, ENV_STORAGE_ENV, LEGACY_ENV_STORAGE_ENV)
     env_values = {k: os.environ.get(k, "") for k in
                   (ENV_OSS_BUCKET, ENV_ACR_HOST, ENV_ACR_NAMESPACE,
+                   ENV_ACR_PUBLIC_HOST,
                    ENV_OSS_PREFIX, ENV_SCAFFOLD_BUCKET, ENV_SCAFFOLD_ROOT)}
     _warn_deprecated_envs(env_values)
     cfg = {
         "oss_bucket": env_values[ENV_OSS_BUCKET],
         "acr_host": env_values[ENV_ACR_HOST],
         "acr_namespace": env_values[ENV_ACR_NAMESPACE],
+        "acr_public_host": env_values[ENV_ACR_PUBLIC_HOST],
         "oss_prefix": env_values[ENV_OSS_PREFIX] or DEFAULT_OSS_PREFIX,
         "scaffold_bucket": env_values[ENV_SCAFFOLD_BUCKET],
         "scaffold_root": env_values[ENV_SCAFFOLD_ROOT],
@@ -259,19 +282,28 @@ def load_profile(name: str = "default", *, overrides: dict | None = None,
         sources["api_env"] = "env"
     else:
         sources["api_env"] = ""
+    prefer_public = False
     if overrides:
-        # 只接受已知字段，避免把 api_env 之类误当数据面字段
-        for k in ("oss_bucket", "acr_host", "acr_namespace", "oss_prefix",
-                  "scaffold_bucket", "scaffold_root", "api_base"):
+        # 只接受已知字段，避免把 api_env 之类误当数据面字段；
+        # prefer_public_registry 单独取（非寻址字段，不进 **cfg 传 Profile）。
+        for k in ("oss_bucket", "acr_host", "acr_namespace", "acr_public_host",
+                  "oss_prefix", "scaffold_bucket", "scaffold_root", "api_base"):
             if k in overrides and overrides[k] is not None:
                 cfg[k] = overrides[k]
                 sources[k] = "explicit"
+        if overrides.get("prefer_public_registry") is not None:
+            prefer_public = bool(overrides["prefer_public_registry"])
     if cfg["api_base"]:
         cfg["api_base"] = str(cfg["api_base"]).rstrip("/")
+    if not prefer_public:
+        # 环境变量开关：IR_ACR_PREFER_PUBLIC=1/true/on（大小写不敏感）
+        prefer_public = os.environ.get(ENV_ACR_PREFER_PUBLIC, "").strip().lower() \
+            in ("1", "true", "on")
     return Profile(name=name, api_env=env,
                    cluster=str(cluster_value).strip(),
                    storage_env=normalize_storage_env(storage_value),
                    metadata_model=(metadata_model or "").strip(),
+                   prefer_public_registry=bool(prefer_public),
                    sources=sources, **cfg)
 
 
@@ -323,6 +355,8 @@ def fetch_repo_config(transport, *, cluster: str = "", storage_env: str = "") ->
     if acr := data.get("acr"):
         if acr.get("registry"):
             result["acr_host"] = acr["registry"]
+        if acr.get("public_registry"):
+            result["acr_public_host"] = acr["public_registry"]
         if acr.get("namespace"):
             result["acr_namespace"] = acr["namespace"]
     # api_env 由 apiserver 在 repo-config 响应中下发（omitempty，旧版不返回）。

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

@@ -4,6 +4,7 @@ from __future__ import annotations
 from urllib.parse import quote
 
 from ..errors import SchemaError, TransportError
+from ..layout import normalize_metadata_model
 from ..models import (ClaimWorkspace, DatasetDetail, DatasetSeries,
                       PagedResult, RoleBinding, VISIBILITY_VALUES)
 
@@ -14,8 +15,14 @@ class DatasetsClient:
     # 曾误写成 /apis/v1/datasets，该路径在 apiserver 上不存在，所有调用恒 404。
     _BASE = "/apis/v1/datasets/series"
 
-    def __init__(self, transport) -> None:
+    def __init__(self, transport, *, content_store=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` 单页对照）。
@@ -60,7 +67,7 @@ class DatasetsClient:
         ``updated_from/to`` RFC3339 闭区间；``sort_by`` updated_at（默认）|
         dataset_name；``order`` desc（默认）|asc；``benchmark_id`` 精确（
         ``"none"`` 查未绑定）；``environment`` online（默认）|pre；
-        ``metadata_model`` version_first（默认）|split_first（决定统计来源）。
+        ``metadata_model`` split_first（默认）|version_first（决定统计来源）。
 
         items 为 :class:`~instance_repo.models.DatasetSeries`（含服务端返回的
         version_count/split_count/latest_version/claimable 统计字段，见模块
@@ -106,8 +113,8 @@ class DatasetsClient:
                            "true" if include_deprecated else "false"))
         if (environment or "").strip():
             params.append(("environment", environment.strip()))
-        if (metadata_model or "").strip():
-            params.append(("metadata_model", metadata_model.strip()))
+        mm = normalize_metadata_model(metadata_model)
+        params.append(("metadata_model", mm))
         params.append(("page", str(int(page))))
         params.append(("page_size", str(int(page_size))))
         query = "&".join(f"{k}={quote(v, safe='')}" for k, v in params)
@@ -118,12 +125,21 @@ class DatasetsClient:
         items = [DatasetSeries(**_pick_series(r)) for r in rows if isinstance(r, dict)]
         return PagedResult.from_response(items, pagination, int(page), int(page_size))
 
-    def get(self, name: str) -> DatasetSeries:
-        data = self._t.get(f"{self._BASE}/detail?dataset_name={quote(name, safe='')}")
-        return DatasetSeries(**_pick_series(data))
+    def get(self, name: str, *,
+            fallback_to_oss: bool = True) -> DatasetSeries:
+        try:
+            data = self._t.get(
+                f"{self._BASE}/detail?dataset_name={quote(name, safe='')}")
+            return DatasetSeries(**_pick_series(data))
+        except TransportError as e:
+            if (e.biz_code == 92001 and fallback_to_oss
+                    and self._content is not None):
+                return self._discover_series(name)
+            raise
 
     def get_detail(self, name: str, *, environment: str | None = None,
-                   metadata_model: str | None = None) -> DatasetDetail:
+                   metadata_model: str | None = None,
+                   fallback_to_oss: bool = True) -> DatasetDetail:
         """dataset 富详情（``GET /datasets/series/detail`` 完整响应）。
 
         相比 :meth:`get` 的轻量 series 字段：新增 version_count / split_count /
@@ -134,13 +150,20 @@ class DatasetsClient:
         """
         if not (name or "").strip():
             raise SchemaError("dataset name is required for get_detail")
-        q = f"dataset_name={quote(name, safe='')}"
-        if (environment or "").strip():
-            q += f"&environment={quote(environment.strip(), safe='')}"
-        if (metadata_model or "").strip():
-            q += f"&metadata_model={quote(metadata_model.strip(), safe='')}"
-        data = self._t.get(f"{self._BASE}/detail?{q}")
-        return DatasetDetail.from_dict(data) if isinstance(data, dict) else DatasetDetail()
+        try:
+            q = f"dataset_name={quote(name, safe='')}"
+            if (environment or "").strip():
+                q += f"&environment={quote(environment.strip(), safe='')}"
+            mm = normalize_metadata_model(metadata_model)
+            q += f"&metadata_model={quote(mm, safe='')}"
+            data = self._t.get(f"{self._BASE}/detail?{q}")
+            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):
+                return self._discover_detail(name, storage_env=environment,
+                                             metadata_model=metadata_model)
+            raise
 
     def update(self, name: str, *, display_name: str | None = None,
                visibility: str | None = None, owner_team_id: str | None = None,
@@ -371,6 +394,38 @@ class DatasetsClient:
         return self._t.post(
             f"{self._BASE}/{quote(dataset_id, safe='')}/claim", body)
 
+    # ── OSS fallback discovery (private) ─────────────────────────────────
+
+    def _discover_detail(self, name: str, *,
+                         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,
+            metadata_model=metadata_model or self._metadata_model)
+        _warn_if_truncated(info, name, 500)
+        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(
+            name, info, storage_env=storage_env)
+
+    def _discover_series(self, name: str) -> DatasetSeries:
+        detail = self._discover_detail(name)
+        return DatasetSeries(
+            dataset_name=detail.dataset_name,
+            dataset_l1=detail.dataset_l1,
+            dataset_l2=detail.dataset_l2,
+            dataset_id=detail.dataset_id or None,
+            version_count=detail.version_count,
+            split_count=detail.split_count,
+            latest_version=detail.latest_version,
+            available_envs=detail.available_envs,
+            registered=False,
+        )
+
 
 # 与 apiserver `DatasetListItem`（pkg/server/dataset_service.go:231）逐字段对齐。
 _SERIES_FIELDS = ("dataset_name", "dataset_l1", "dataset_l2", "dataset_id",

{instance_repo-1.3.0.dev0 → instance_repo-1.3.2}/instance_repo/clients/images.py

@@ -48,7 +48,7 @@ class ImageClient:
         计算**目标环境**的引用，配合 :meth:`copy` 做跨环境搬运。
         """
         host = acr_host or bootstrap.require(
-            self._p, "acr_host", action="拼 ACR 镜像引用")
+            self._p, "effective_acr_host", action="拼 ACR 镜像引用")
         ns = namespace or bootstrap.require(
             self._p, "acr_namespace", action="拼 ACR 镜像引用")
         return self._layout(metadata_model).image_ref(

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

@@ -70,6 +70,8 @@ class InstancesClient:
         # 收尾改为 ingest）。ingester 形如 (dataset, version) -> ingest job dict；
         # 由 Repo 注入 versions.ingest。直接构造未注入时 register=True 会报错。
         self._ingester = ingester
+        # OSS 回退发现使用的 bucket 内根前缀（profile 可覆盖，缺省 swe/datasets）。
+        self._oss_prefix = getattr(profile, 'oss_prefix', 'swe/datasets')
 
     def _check_split_not_locked(self, dataset: str, version: str,
                                 split: str) -> None:
@@ -155,24 +157,55 @@ class InstancesClient:
     def get(self, dataset: str, version: str, instance_id: str,
             split: str | None = None, *,
             environment: str | None = None,
-            metadata_model: str | None = None) -> DatasetInstance | None:
+            metadata_model: str | None = None,
+            fallback_to_oss: bool = True) -> DatasetInstance | None:
         """取单个实例；不存在返回 None。
 
         ``environment`` / ``metadata_model`` 传 None 用 profile 派生的值（默认行为
         不变）；显式传值可覆盖本次调用——CLI 需要读 online 集合时不必重建 Repo。
+
+        **OSS 双触发回退**（设计文档 §4.4.4）：
+        a. ``TransportError(biz_code=92001)``（dataset 不存在）→ OSS 回退。
+        b. ``result is None``（registry 吞了 92003 instance 不存在）→ OSS 回退。
         """
         # 只在调用方显式指定时才下发覆盖参数:注册表是可注入实现,
         # 保持缺省调用形态与历史一致,避免破坏既有实现。
         overrides = _registry_overrides(environment, metadata_model)
-        return self._reg.get(dataset, version, instance_id, split, **overrides)
+        try:
+            result = self._reg.get(
+                dataset, version, instance_id, split, **overrides)
+        except TransportError as e:
+            # 路径 1: dataset 不存在(92001) → OSS 回退
+            if (e.biz_code == 92001
+                    and fallback_to_oss and self._content is not None):
+                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:
+            return self._discover_instance(
+                dataset, version, instance_id, split)
+        return result
 
     def list(self, dataset: str, version: str,
              split: str | None = None, *,
              environment: str | None = None,
-             metadata_model: str | None = None) -> list[DatasetInstance]:
-        """自动翻页取全量；``environment`` / ``metadata_model`` 语义同 :meth:`get`。"""
+             metadata_model: str | None = None,
+             fallback_to_oss: bool = True) -> list[DatasetInstance]:
+        """自动翻页取全量；``environment`` / ``metadata_model`` 语义同 :meth:`get`。
+
+        **OSS 回退**：当 ``TransportError(biz_code=92001)``（dataset 不存在）时，
+        若 ``fallback_to_oss=True`` 且 ``content_store`` 已注入，自动回退到 OSS
+        存储层列举实例。
+        """
         overrides = _registry_overrides(environment, metadata_model)
-        return self._reg.query(dataset, version, split, **overrides)
+        try:
+            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):
+                return self._discover_instances(dataset, version, split)
+            raise
 
     def list_paged(self, dataset: str, version: str = "", *,
                    split: str | None = None, q: str | None = None,
@@ -181,7 +214,8 @@ class InstancesClient:
                    difficulty: str | None = None,
                    page: int = 1, page_size: int = 50,
                    environment: str | None = None,
-                   metadata_model: str | None = None) -> "PagedResult":
+                   metadata_model: str | None = None,
+                   fallback_to_oss: bool = True) -> "PagedResult":
         """instance 分页列表（单页原始语义，``GET /datasets/instances``）。
 
         与 :meth:`list` 的自动翻页取全量互补：精确控制页码/过滤/搜索。
@@ -190,6 +224,9 @@ class InstancesClient:
         CSV（"k1:v1,k2:v2"，key 含 ``.``/``$`` 服务端拒绝——SDK 前置校验并
         给出修复提示）；``difficulty`` easy/medium/hard。**服务端无排序参数**
         （固定 instance_id asc），SDK 不暴露。
+
+        **OSS 回退**：当 ``TransportError(biz_code=92001)`` 时回退到 OSS 存储层，
+        在客户端做过滤（q/tags/difficulty/instance_id）+ 内存分页。
         """
         from urllib.parse import quote
         from ..models import PagedResult
@@ -235,18 +272,100 @@ class InstancesClient:
         if mm is None:
             mm = normalize_metadata_model(
                 getattr(self._p, "metadata_model", None))
-        if mm:
-            params.append(("metadata_model", mm))
+        params.append(("metadata_model", mm))
         params.append(("page", str(int(page))))
         params.append(("page_size", str(int(page_size))))
         query = "&".join(f"{k}={quote(v, safe='')}" for k, v in params)
-        data, pagination = self._t.request_with_meta(
-            "GET", f"{self._BASE}?{query}")
+        try:
+            data, pagination = self._t.request_with_meta(
+                "GET", f"{self._BASE}?{query}")
+        except TransportError as e:
+            if (e.biz_code == 92001
+                    and fallback_to_oss and self._content is not None):
+                return self._discover_instances_paged(
+                    dataset, version, split,
+                    q=q, instance_id=instance_id,
+                    tags=tags, difficulty=difficulty,
+                    page=page, page_size=page_size)
+            raise
         rows = data.get("instances", data) if isinstance(data, dict) else data
         rows = rows if isinstance(rows, list) else []
         items = [DatasetInstance.from_dict(r) for r in rows if isinstance(r, dict)]
         return PagedResult.from_response(items, pagination, int(page), int(page_size))
 
+    # ── OSS 回退发现（未注册 dataset 的 instance 合成） ──
+
+    def _discover_instances(self, dataset: str, version: str,
+                            split: str | None = None) -> list[DatasetInstance]:
+        """OSS 回退的 instances.list — 从 OSS 列举指定 version/split 下的实例。"""
+        from ..store.oss_discovery import build_synthetic_instances
+        return build_synthetic_instances(
+            self._content, dataset, version, split,
+            oss_prefix=getattr(self, '_oss_prefix', 'swe/datasets'))
+
+    def _discover_instance(self, dataset: str, version: str,
+                           instance_id: str,
+                           split: str | None = None) -> DatasetInstance | None:
+        """OSS 回退的 instances.get — 精确查找单个实例。"""
+        from ..store.oss_discovery import build_synthetic_instance
+        return build_synthetic_instance(
+            self._content, dataset, version, instance_id, split,
+            oss_prefix=getattr(self, '_oss_prefix', 'swe/datasets'))
+
+    def _discover_instances_paged(
+        self, dataset: str, version: str, split: str | None, *,
+        q: str | None, instance_id: str | None,
+        tags: dict[str, str] | str | None,
+        difficulty: str | None,
+        page: int, page_size: int,
+    ) -> "PagedResult":
+        """OSS 回退的 list_paged：全量列举 + 客户端过滤 + 内存分页。
+
+        ``instance_id`` 精确匹配时直接 GET，不列举全量。
+        """
+        from ..store.oss_discovery import _in_memory_paged
+
+        # 优化：instance_id 精确匹配时直接 GET，不列举全量
+        if instance_id:
+            inst = self._discover_instance(dataset, version, instance_id, split)
+            items: list[DatasetInstance] = [inst] if inst else []
+        else:
+            items = self._discover_instances(dataset, version, split)
+
+        # 客户端过滤
+        if q:
+            q_lower = q.lower()
+            items = [i for i in items
+                     if q_lower in i.instance_id.lower()]
+        if difficulty:
+            items = [i for i in items
+                     if i.difficulty == difficulty]
+        if tags:
+            tags_dict = (
+                tags if isinstance(tags, dict)
+                else self._parse_tags_csv(tags)
+            )
+            items = [i for i in items
+                     if all(i.tags.get(k) == v
+                            for k, v in tags_dict.items())]
+
+        return _in_memory_paged(items, int(page), int(page_size))
+
+    @staticmethod
+    def _parse_tags_csv(tags_str: str) -> dict[str, str]:
+        """解析 ``"k1:v1,k2:v2"`` 格式的 tags CSV 字符串为 dict。"""
+        result: dict[str, str] = {}
+        for pair in str(tags_str).split(","):
+            pair = pair.strip()
+            if not pair:
+                continue
+            parts = pair.split(":", 1)
+            if len(parts) == 2:
+                result[parts[0]] = parts[1]
+            else:
+                result[parts[0]] = ""
+        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,
@@ -377,7 +496,7 @@ class InstancesClient:
             if push_image:
                 # 自带 tar 且会推 ACR：docker_image 记它将被推到的 ACR 目标地址。
                 # 仅在 push_image 时记——否则该 ACR 地址指向从未推送过的镜像，是假的。
-                docker_ref = lay.image_ref(self._p.acr_host, self._p.acr_namespace,
+                docker_ref = lay.image_ref(self._p.effective_acr_host, self._p.acr_namespace,
                                            dataset, instance_id,
                                            version=version, split=split)
         else:
@@ -399,7 +518,7 @@ class InstancesClient:
         if image_release_dst_acr:
             from .. import release as _R  # 局部导入避免循环依赖
             extend_meta = _R.image_release_meta(
-                docker_ref, self._p.acr_host, image_release_dst_acr)
+                docker_ref, self._p.effective_acr_host, image_release_dst_acr)
 
         # ② 写元数据(pending) → 拿稳定 id（register=False 时跳过，用本地 id）
         meta = DatasetInstance(
@@ -702,6 +821,8 @@ class InstancesClient:
                 warm(sts_prefix)
         # 推镜像时同样预热 ACR 凭据缓存（否则首轮各 worker 会并发重复签同一 host）
         if push_image and getattr(self._p, "acr_host", None):
+            # 签名恒用 apiserver 登记的 host（acr_host，VPC）；token 实例级，
+            # 对公网 endpoint 同样有效（prefer_public 时连接走公网、签名仍走这里）。
             try:
                 self._t.get_acr_credentials(self._p.acr_host)
             except Exception:  # noqa: BLE001 — 预热失败不阻断，真正推镜像时再报