instance-repo 1.3.5.dev7__tar.gz → 1.4.0__tar.gz

{instance_repo-1.3.5.dev7 → instance_repo-1.4.0}/PKG-INFO

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

{instance_repo-1.3.5.dev7 → instance_repo-1.4.0}/instance_repo/__init__.py

@@ -8,8 +8,8 @@ from .loader import load_instances
 from .content import compute_source_hash
 from .models import (
     DatasetSeries, DatasetVersion, DatasetInstance, ManifestEntry,
-    OwnerReference, Feedback, Identity, PushResult,
-    RolloutReport, RolloutJob, ScaffoldConfig,
+    OwnerReference, Feedback, Identity, IngestReport, RegistrationReport,
+    PushResult, PushManyReport, RolloutReport, RolloutJob, ScaffoldConfig,
     DatasetObjectDirectory, DatasetObjectFile, DatasetObjectListResult,
     canonical_json, parse_feedbacks, append_feedback,
 )
@@ -17,15 +17,16 @@ from .errors import (
     InstanceRepoError, LayoutError, SchemaError, OwnerRefMissing, ImageMissing,
     Immutable, DigestMismatch, Forbidden, NotVisible, TargetNotAllowed,
     NetworkDenied, CredExpired, PrivateNetworkRequired, WriteOutcomeUnknown,
-    TransportError,
+    RegistrationFailed, TransportError,
 )
 
-__version__ = "1.3.5.dev7"
+__version__ = "1.4.0"
 
 __all__ = [
     "Repo", "load_instances",
     "DatasetSeries", "DatasetVersion", "DatasetInstance", "ManifestEntry",
-    "OwnerReference", "Feedback", "Identity", "PushResult",
+    "OwnerReference", "Feedback", "Identity", "IngestReport",
+    "RegistrationReport", "PushResult", "PushManyReport",
     "RolloutReport", "RolloutJob", "ScaffoldConfig",
     "DatasetObjectDirectory", "DatasetObjectFile", "DatasetObjectListResult",
     "canonical_json", "parse_feedbacks", "append_feedback",
@@ -33,6 +34,6 @@ __all__ = [
     "InstanceRepoError", "LayoutError", "SchemaError", "OwnerRefMissing",
     "ImageMissing", "Immutable", "DigestMismatch", "Forbidden", "NotVisible",
     "TargetNotAllowed", "NetworkDenied", "CredExpired",
-    "PrivateNetworkRequired", "WriteOutcomeUnknown", "TransportError",
-    "__version__",
+    "PrivateNetworkRequired", "WriteOutcomeUnknown", "RegistrationFailed",
+    "TransportError", "__version__",
 ]

{instance_repo-1.3.5.dev7 → instance_repo-1.4.0}/instance_repo/cli.py

@@ -19,9 +19,10 @@ import argparse
 import json
 import sys
 
+from . import paths as P
 from .concurrency import ItemError
 from .errors import InstanceRepoError
-from .models import OwnerReference, Feedback, RolloutReport, DatasetSeries
+from .models import DatasetSeries, Feedback, OwnerReference, RolloutReport
 from .repo import Repo
 
 _STATUS_CHOICES = ["draft", "published", "deprecated", "archived"]
@@ -42,10 +43,6 @@ 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="split_first",
-                    choices=["split_first", "version_first"],
-                    help="元数据模型；缺省 split_first（split 必填、version 选填）。"
-                         "旧数据集用 version_first（version 必填、split 选填）")
     sub = ap.add_subparsers(dest="cmd", required=True)
 
     v = sub.add_parser("validate", help="本地校验 Instance 目录")
@@ -54,7 +51,8 @@ def build_parser() -> argparse.ArgumentParser:
     p = sub.add_parser("push", help="上传 Instance（元数据先行）")
     p.add_argument("dir")
     p.add_argument("--dataset", required=True)
-    p.add_argument("--version", required=True)
+    p.add_argument("--version", default="",
+                   help="版本号；split-first 可省略为空版本")
     p.add_argument("--owner-ref", required=True, help="OwnerReference JSON")
     p.add_argument("--split", default="default")
     p.add_argument("--no-image", action="store_true")
@@ -70,31 +68,34 @@ def build_parser() -> argparse.ArgumentParser:
     pm.add_argument("dirs", nargs="+",
                     help="实例路径，可给多个；整批父目录用通配展开，如 ./staging/*")
     pm.add_argument("--dataset", required=True, help="{L1}/{L2}")
-    pm.add_argument("--version", required=True)
+    pm.add_argument("--version", default="",
+                    help="版本号；split-first 可省略为空版本")
     pm.add_argument("--owner-ref", required=True, help="OwnerReference JSON（整批共用）")
     pm.add_argument("--split", default="default")
     pm.add_argument("--no-image", action="store_true")
     pm.add_argument("--overwrite", action="store_true")
     pm.add_argument("--register", action="store_true",
-                    help="整批上传完成后一次 ingest 写库（缺省只传 OSS，不写库）")
+                    help="按成功实例ID分块ingest写库（缺省只传OSS，不写库）")
     pm.add_argument("--no-verify", action="store_true")
     pm.add_argument("--concurrency", type=int, default=8)
     pm.add_argument("--continue-on-error", action="store_true",
-                    help="缺省全或无（任一失败即报错）；置上则跳过失败项并逐项汇报")
+                    help="缺省任一失败即非零退出（已完成上传不回滚）；置上则逐项汇报")
 
     dl = sub.add_parser("deliver",
-                        help="批量交付：并发上传 + 一次 ingest 入库（大规模交付推荐入口）")
+                        help="批量交付：并发上传 + 成功实例定向ingest")
     dl.add_argument("dirs", nargs="+",
                     help="实例路径，可给多个；整批父目录用通配展开，如 ./staging/*")
     dl.add_argument("--dataset", required=True, help="{L1}/{L2}")
-    dl.add_argument("--version", required=True)
+    dl.add_argument("--version", default="",
+                    help="版本号；split-first 可省略为空版本")
     dl.add_argument("--owner-ref", required=True, help="OwnerReference JSON（整批共用）")
     dl.add_argument("--split", default="default")
     dl.add_argument("--no-image", action="store_true")
     dl.add_argument("--overwrite", action="store_true")
     dl.add_argument("--concurrency", type=int, default=8)
     dl.add_argument("--continue-on-error", action="store_true",
-                    help="缺省全或无；置上则只对成功子集 ingest，失败项单独汇报")
+                    help="缺省任一失败即非零退出（已完成上传不回滚）；"
+                         "置上则只注册成功子集并逐项汇报失败")
     dl.add_argument("--no-ingest", action="store_true", help="只上传不入库")
     dl.add_argument("--publish", action="store_true",
                     help="ingest 完成后把 version 置 published")
@@ -169,8 +170,8 @@ def build_parser() -> argparse.ArgumentParser:
     iref = isub.add_parser("ref", help="按当前元数据模型算某实例的 ACR 引用")
     iref.add_argument("--dataset", required=True, help="{L1}/{L2}")
     iref.add_argument("--instance-id", required=True)
-    iref.add_argument("--split", default=None, help="split_first 下必填")
-    iref.add_argument("--version", default=None, help="version_first 下必填")
+    iref.add_argument("--split", default=None, help="split-first 正常业务下必填")
+    iref.add_argument("--version", default=None, help="可选版本号")
     iref.add_argument("--acr-host", default=None, help="缺省取自动发现结果")
     iref.add_argument("--acr-namespace", default=None, help="缺省取自动发现结果")
 
@@ -313,8 +314,9 @@ 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="split_first",
-                     help="create/ingest 用：显式指定元数据模型（split_first/version_first）")
+    ver.add_argument("--instance-id", action="append", default=None,
+                     dest="instance_ids",
+                     help="ingest用：定向注册实例ID；可重复，也可逗号分隔")
     ver.add_argument("--dry-run", action="store_true",
                      help="ingest 用：只预览扫描结果不落库")
     ver.add_argument("--publish", action="store_true",
@@ -384,8 +386,6 @@ def build_parser() -> argparse.ArgumentParser:
                     dest="include_deprecated")
     ds.add_argument("--environment", default=None,
                     help="get/update 覆盖 profile 派生的 environment")
-    ds.add_argument("--metadata-model", choices=["split_first", "version_first"],
-                    default="split_first", dest="metadata_model")
     # update 用（至少一项）
     ds.add_argument("--display-name", default=None, dest="display_name")
     ds.add_argument("--description", default=None)
@@ -487,16 +487,15 @@ def _resolve_split_ref(args) -> tuple[str, str]:
                      "--dataset/--split")
 
 
-def _split_dataset(dataset: str) -> list[str]:
-    """校验 dataset 为 ``{L1}/{L2}`` 两段式。
-
-    与 ``_split_ref(x, 2)`` 的区别只在报错文案：用户传的是 ``--dataset`` 时，
-    "ref must have 2 segments" 会指向一个他根本没用的参数名。
-    """
-    segs = dataset.split("/")
-    if len(segs) != 2:
-        raise SystemExit(f"--dataset must be {{L1}}/{{L2}}, got {dataset!r}")
-    return segs
+def _split_dataset(dataset: str) -> tuple[str, str]:
+    """校验 ``--dataset`` 并返回模型回显所需的 ``(L1, L2)``。"""
+    try:
+        name = P.DatasetName.parse(dataset)
+    except InstanceRepoError as exc:
+        raise SystemExit(
+            f"--dataset must be one or two canonical segments, got "
+            f"{dataset!r}") from exc
+    return name.l1, name.l2
 
 
 _TARGET_SHAPE = {
@@ -632,8 +631,7 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
     cluster = _effective_cluster(args)
     r = repo or Repo(profile=args.profile, api_env=getattr(args, "api_env", None),
                      api_base=getattr(args, "api_base", None), cluster=cluster,
-                     storage_env=getattr(args, "global_storage_env", None),
-                     metadata_model=getattr(args, "metadata_model", None))
+                     storage_env=getattr(args, "global_storage_env", None))
 
     if args.cmd == "validate":
         rep = r.instances.validate(args.dir)
@@ -655,6 +653,9 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
             print(f"ingest {res.ingest.get('ingest_id')} "
                   f"status={res.ingest.get('status')} "
                   f"instances={stats.get('instance_count')}", file=out)
+        if not args.no_register:
+            status = ((res.ingest or {}).get("status") or "").lower()
+            return 0 if status == "completed" else 1
         return 0
 
     if args.cmd == "push-many":
@@ -679,8 +680,14 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
             else:
                 print(f"{res.instance_id}\tuploaded={res.uploaded}\t"
                       f"image_pushed={res.image_pushed}", file=out)
+        unfinished_registration = (
+            args.register and any(
+                not isinstance(res, Exception)
+                and ((res.ingest or {}).get("status") or "").lower()
+                != "completed"
+                for res in results))
         print(f"pushed={len(results) - failed} failed={failed}", file=out)
-        return 1 if failed else 0
+        return 1 if failed or unfinished_registration else 0
 
     if args.cmd == "deliver":
         if args.concurrency < 1:
@@ -699,10 +706,19 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
             print(f"FAILED\t{getattr(e, 'item', '?')}\t{getattr(e, 'error', e)}",
                   file=out)
         job = res.get("ingest") or {}
+        registration = res.get("registration")
+        pending = len(getattr(registration, "pending", []))
+        reg_failed = len(getattr(registration, "failed", []))
+        unknown = len(getattr(registration, "unknown", []))
+        not_submitted = len(getattr(registration, "not_submitted", []))
         print(f"pushed={len(res['pushed'])} failed={len(res['failed'])} "
-              f"ingest={job.get('ingest_id', '-')} status={job.get('status', '-')}",
-              file=out)
-        return 1 if res["failed"] else 0
+              f"skipped={len(res.get('skipped', []))} jobs={len(res.get('ingests', []))} "
+              f"ingest={job.get('ingest_id', '-')} status={job.get('status', '-')} "
+              f"pending={pending} registration_failed={reg_failed} "
+              f"unknown={unknown} not_submitted={not_submitted}", file=out)
+        unfinished = (res["failed"] or pending or reg_failed
+                      or unknown or not_submitted)
+        return 1 if unfinished else 0
 
     if args.cmd == "list":
         dataset, version, _ = _resolve_target(args, 3)
@@ -948,8 +964,7 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
                                    storage_path=args.storage_path, splits=splits,
                                    status=args.status or "draft",
                                    storage_type=args.storage_type,
-                                   environment=args.environment,
-                                   metadata_model=args.metadata_model)
+                                   environment=args.environment)
             print(f"created version {dv.dataset}/{dv.version} status={dv.status}",
                   file=out)
             return 0
@@ -959,11 +974,59 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
             dataset, _, _ = _resolve_target(args, 2)
             splits = ([s.strip() for s in args.splits.split(",") if s.strip()]
                       if args.splits else None)
+            selected_ids = None
+            if args.instance_ids is not None:
+                unsupported = []
+                if args.dry_run:
+                    unsupported.append("--dry-run")
+                if args.publish:
+                    unsupported.append("--publish")
+                if args.allow_layout_inference:
+                    unsupported.append("--allow-layout-inference")
+                if args.storage_path is not None:
+                    unsupported.append("--storage-path")
+                if args.run_type is not None:
+                    unsupported.append("--run-type")
+                if args.split_run_types is not None:
+                    unsupported.append("--split-run-types")
+                if unsupported:
+                    raise SystemExit(
+                        "--instance-id selected ingest 不支持 "
+                        + ", ".join(unsupported))
+                selected_ids = sorted(set(
+                    value.strip()
+                    for item in args.instance_ids
+                    for value in item.split(",") if value.strip()))
+                if not selected_ids:
+                    raise SystemExit("--instance-id 至少需要一个非空ID")
+                if splits:
+                    raise SystemExit(
+                        "--instance-id 只允许一个 --split，不能与 --splits 同用")
+                registration = r.instances.ingest(
+                    dataset, args.version or None, selected_ids,
+                    split=args.split or "default",
+                    environment=args.environment,
+                    wait=not args.no_wait, poll_sec=args.poll_sec,
+                    timeout_sec=args.timeout_sec, cluster=args.cluster)
+                print(
+                    f"jobs={len(registration.ingests)} "
+                    f"completed={len(registration.completed)} "
+                    f"pending={len(registration.pending)} "
+                    f"failed={len(registration.failed)} "
+                    f"unknown={len(registration.unknown)} "
+                    f"not_submitted={len(registration.not_submitted)}",
+                    file=out)
+                unfinished = (registration.pending or registration.failed
+                              or registration.unknown
+                              or registration.not_submitted
+                              or len(registration.completed)
+                              != len(registration.selected_ids))
+                return 1 if unfinished else 0
+
             job = r.versions.ingest(
                 dataset, args.version or None,
                 storage_path=args.storage_path, splits=splits,
-                split=args.split, metadata_model=args.metadata_model,
-                environment=args.environment,
+                split=args.split, environment=args.environment,
                 allow_layout_inference=args.allow_layout_inference,
                 publish=args.publish, dry_run=args.dry_run,
                 wait=not args.no_wait, poll_sec=args.poll_sec,
@@ -974,11 +1037,12 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
                           f"instances={dv.get('instance_count') or 0}"
                           f"\tsplits={len(dv.get('splits') or [])}", file=out)
                 return 0
+            status = (job.get("status") or "").lower()
             print(f"ingest {job.get('ingest_id', '')} "
                   f"status={job.get('status', '')} "
                   f"instances={job.get('stats', {}).get('instance_count') or 0}",
                   file=out)
-            return 0
+            return 0 if status == "completed" else 1
         dataset, version, _ = _resolve_target(args, 3)
         if args.action == "status":
             if args.split:
@@ -1086,7 +1150,6 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
                 sort_by=args.sort_by, order=args.order,
                 include_deprecated=args.include_deprecated or None,
                 environment=args.environment,
-                metadata_model=args.metadata_model,
                 page=args.page, page_size=args.page_size)
             for ds in res.items:
                 print(f"{ds.dataset_name}\tvisibility={ds.visibility}"
@@ -1100,8 +1163,7 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
         if args.action in ("get", "update", "access", "revoke") and not dataset:
             raise SystemExit(f"dataset {args.action} 需要 --dataset 或位置 ref")
         if args.action == "get":
-            d = r.datasets.get_detail(dataset, environment=args.environment,
-                                      metadata_model=args.metadata_model)
+            d = r.datasets.get_detail(dataset, environment=args.environment)
             src = "oss" if not d.registered else "mongodb"
             print(f"dataset\t{d.dataset_name}\tid={d.dataset_id}"
                   f"\tvisibility={d.visibility}\t[{src}]", file=out)

{instance_repo-1.3.5.dev7 → instance_repo-1.4.0}/instance_repo/clients/config.py

@@ -148,6 +148,29 @@ def normalize_storage_env(storage_env: str | None) -> str:
     return (storage_env or "").strip().lower()
 
 
+def business_metadata_model(metadata_model: str | None) -> str:
+    """Normalize a normal business entry to the only supported model.
+
+    ``None``, the empty compatibility value, and ``split_first`` are accepted.
+    ``version_first`` remains available only through low-level ``Layout`` and
+    legacy discovery helpers, never through Repo/client business I/O.
+    """
+    from ..errors import SchemaError
+
+    if metadata_model is not None and not isinstance(metadata_model, str):
+        raise SchemaError("metadata_model must be a string or None")
+    requested = (metadata_model or "").strip()
+    if requested not in ("", "split_first"):
+        if requested == "version_first":
+            raise SchemaError(
+                "normal business entry is fixed to metadata_model=split_first; "
+                "version_first is retained only for low-level legacy reads")
+        raise SchemaError(
+            f"invalid metadata_model {requested!r}; normal business entry only "
+            "accepts split_first")
+    return "split_first"
+
+
 def dataset_environment_for(storage_env: str | None) -> str:
     """由 storage_env 派生 ingest 的 ``environment``；无法派生时返回空串。
 
@@ -255,6 +278,7 @@ def load_profile(name: str = "default", *, overrides: dict | None = None,
     关键字段（如 oss_bucket / acr_host）允许为空——仅在对应数据面操作真正用到时才校验，
     纯控制面元数据操作（list/get/create/claim/whoami）不需要它们。
     """
+    requested_model = business_metadata_model(metadata_model)
     base, env = resolve_api_base(api_env, api_base=api_base)
     cluster_value = resolve_config_value(cluster, ENV_CLUSTER)
     storage_value = resolve_config_value(
@@ -302,7 +326,7 @@ def load_profile(name: str = "default", *, overrides: dict | None = None,
     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(),
+                   metadata_model=requested_model,
                    prefer_public_registry=bool(prefer_public),
                    sources=sources, **cfg)
 

{instance_repo-1.3.5.dev7 → instance_repo-1.4.0}/instance_repo/clients/datasets.py

@@ -3,8 +3,8 @@ from __future__ import annotations
 
 from urllib.parse import quote
 
+from .config import Profile, business_metadata_model
 from ..errors import SchemaError, TransportError
-from ..layout import normalize_metadata_model
 from ..models import (ClaimWorkspace, DatasetDetail, DatasetSeries,
                       PagedResult, RoleBinding, VISIBILITY_VALUES)
 
@@ -15,14 +15,15 @@ class DatasetsClient:
     # 曾误写成 /apis/v1/datasets，该路径在 apiserver 上不存在，所有调用恒 404。
     _BASE = "/apis/v1/datasets/series"
 
-    def __init__(self, transport, *, content_store=None,
+    def __init__(self, transport, *, profile: Profile | None = None, content_store=None,
                  oss_prefix: str = "swe/datasets",
                  metadata_model: str | None = None) -> None:
         self._t = transport
+        self._p = profile
         self._content = content_store
         self._oss_prefix = oss_prefix
-        # OSS 回退探测的布局语义（split_first 默认；version_first 显式切换）
-        self._metadata_model = metadata_model or "split_first"
+        # 正常Dataset业务客户端固定split_first；legacy discovery仍可直接调用低层helper。
+        self._metadata_model = business_metadata_model(metadata_model)
 
     def list(self, l1: str | None = None) -> list[DatasetSeries]:
         """列出 dataset（便利语义：自动翻页取全量，见 :meth:`list_paged` 单页对照）。
@@ -67,7 +68,7 @@ class DatasetsClient:
         ``updated_from/to`` RFC3339 闭区间；``sort_by`` updated_at（默认）|
         dataset_name；``order`` desc（默认）|asc；``benchmark_id`` 精确（
         ``"none"`` 查未绑定）；``environment`` online（默认）|pre；
-        ``metadata_model`` split_first（默认）|version_first（决定统计来源）。
+        ``metadata_model`` 为兼容参数，正常业务只接受并显式发送 split_first。
 
         items 为 :class:`~instance_repo.models.DatasetSeries`（含服务端返回的
         version_count/split_count/latest_version/claimable 统计字段，见模块
@@ -113,7 +114,7 @@ class DatasetsClient:
                            "true" if include_deprecated else "false"))
         if (environment or "").strip():
             params.append(("environment", environment.strip()))
-        mm = normalize_metadata_model(metadata_model)
+        mm = business_metadata_model(metadata_model)
         params.append(("metadata_model", mm))
         params.append(("page", str(int(page))))
         params.append(("page_size", str(int(page_size))))
@@ -125,15 +126,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, *,
+    def get(self, name: str, *, environment: str | None = None,
+            metadata_model: str | None = None,
             fallback_to_oss: bool = True) -> DatasetSeries:
+        mm = business_metadata_model(metadata_model)
         try:
-            data = self._t.get(
-                f"{self._BASE}/detail?dataset_name={quote(name, safe='')}")
+            q = (f"dataset_name={quote(name, safe='')}"
+                 f"&metadata_model={quote(mm, safe='')}")
+            if (environment or "").strip():
+                q += f"&environment={quote(environment.strip(), safe='')}"
+            data = self._t.get(f"{self._BASE}/detail?{q}")
             return DatasetSeries(**_pick_series(data))
         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_series(name)
             raise
 
@@ -150,11 +157,11 @@ class DatasetsClient:
         """
         if not (name or "").strip():
             raise SchemaError("dataset name is required for get_detail")
+        mm = business_metadata_model(metadata_model)
         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()

{instance_repo-1.3.5.dev7 → instance_repo-1.4.0}/instance_repo/clients/images.py

@@ -8,9 +8,9 @@ v0.8 之前，镜像推送只作为「推实例」的内部副作用存在：没
 * :meth:`copy`   registry → registry（跨环境搬运，digest 固定）
 * :meth:`exists` 存在性探测（带一致性重试）
 
-命名不用调用方自己拼：:meth:`ref_for` 按当前元数据模型产出引用——``version_first``
-为 ``{host}/{ns}/{sanitize(L2)}:{version}-{id}``，``split_first`` 为
-``{host}/{ns}/{sanitize(L2)}:{split}-{id}``。
+命名不用调用方自己拼：正常业务固定 ``split_first``，:meth:`ref_for` 经
+``DatasetName`` 解析后产出 ``{host}/{ns}/{sanitize(leaf)}:{split}-{id}``
+（单段 L1 与两段 L1/L2 均支持）。旧布局仅由低层 ``Layout`` 读取存量数据。
 
 网络策略沿用数据面统一口径：push / copy / exists 私网优先、连通性失败时受限回退公网；
 **pull 归类为下载动作，强制私网**，公网回退被禁用，不可达即抛
@@ -21,8 +21,10 @@ from __future__ import annotations
 from pathlib import Path
 
 from .. import bootstrap
+from .. import paths as P
 from ..errors import SchemaError
 from ..layout import Layout
+from .config import business_metadata_model
 
 
 class ImageClient:
@@ -47,12 +49,18 @@ class ImageClient:
         ``acr_host`` / ``namespace`` 缺省取当前 profile（含自动发现结果）；显式传入可用于
         计算**目标环境**的引用，配合 :meth:`copy` 做跨环境搬运。
         """
+        requested_model = metadata_model
+        if requested_model is None:
+            requested_model = self._p.metadata_model
+        model = business_metadata_model(requested_model)
         host = acr_host or bootstrap.require(
             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(
-            host, ns, dataset, instance_id, version=version, split=split)
+        name = P.DatasetName.parse(dataset)
+        return self._layout(model).image_ref(
+            host, ns, name.canonical, instance_id,
+            version=version, split=split)
 
     # ── 动作 ──
     def push(self, tar_path, ref: str, *, overwrite: bool = False) -> str: