instance-repo 1.0.2__tar.gz → 1.0.7.dev0__tar.gz

{instance_repo-1.0.2 → instance_repo-1.0.7.dev0}/PKG-INFO

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

{instance_repo-1.0.2 → instance_repo-1.0.7.dev0}/instance_repo/__init__.py

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

{instance_repo-1.0.2 → instance_repo-1.0.7.dev0}/instance_repo/bootstrap.py

@@ -19,6 +19,7 @@ registry/namespace），校验并缓存。
 """
 from __future__ import annotations
 
+import logging
 import threading
 import time
 
@@ -28,6 +29,8 @@ from .clients.config import (
 )
 from .errors import InstanceRepoError, SchemaError
 
+_logger = logging.getLogger(__name__)
+
 #: 自动发现结果的缓存存活时间（秒）。寻址配置变更频率极低，一小时足够；
 #: 需要立刻生效时用 ``resolve_profile(..., refresh=True)`` 或 ``clear_cache()``。
 DISCOVERY_TTL_SECONDS = 3600.0
@@ -82,7 +85,14 @@ def discover(transport, profile: Profile, *, refresh: bool = False) -> dict:
         except (InstanceRepoError, OSError):
             # 控制面错误以及 DNS/连接层 OSError 都按延迟失败处理：构造 Repo 不应阻断
             # 纯控制面操作。记空结果避免每次数据面调用都重试，TTL 到期后仍会恢复。
-            _cache.put(key, {}, _expiry())
+            #
+            # 不缓存空结果：缓存空结果会让"修复了集群名拼写"或"network 恢复"后仍需等 1 小时。
+            # 改为每次数据面操作都重试（apiserver 的 repo-config 是轻量 GET，无副作用）。
+            _logger.warning(
+                "repo-config 自动发现失败（selector=%s=%s），后续数据面操作会报 "
+                "oss_bucket is required。如非网络问题，请检查 cluster 名是否正确："
+                "用 irepo repo-config --cluster <值> 可直接看到错误。",
+                selector_type, selector_value, exc_info=True)
             return {}
         _cache.put(key, dict(found), _expiry())
         return dict(found)
@@ -120,7 +130,10 @@ def resolve_profile(transport, profile: Profile, *, refresh: bool = False
             profile.sources["storage_env"] = "discovery"
         # 无论 storage_env 是查询所得，还是显式值经本次查询确认一致，都记录二者绑定。
         # ingest 只复用带这个证明的双 selector，避免方法级 cluster 覆盖后夹带旧环境。
-        profile.storage_env_cluster = profile.cluster
+        # 绑定值取 repo-config 响应回传的**规范 Name**（cluster 入参为 id/url_cluster 时
+        # 已被 resolve_cluster 解析），与 ingest body 下发值同源，服务端按 Name 精确匹配。
+        profile.storage_env_cluster = (
+            found.get("cluster") or profile.cluster)
 
     for field in DISCOVERABLE_FIELDS:
         value = found.get(field)

{instance_repo-1.0.2 → instance_repo-1.0.7.dev0}/instance_repo/cli.py

@@ -122,9 +122,11 @@ def build_parser() -> argparse.ArgumentParser:
 
     pub = sub.add_parser("publish", help="发布到运行时配置的目标数据面（benchmark-release）")
     pub.add_argument("ref", nargs="?",
-                     help="{L1}/{L2}/{version}（或用 --dataset/--version）")
+                     help="{L1}/{L2}/{version}；split_first 无版本 split 发布用 {L1}/{L2}"
+                          "（或用 --dataset/--version[--split]）")
     pub.add_argument("--dataset", default=None, help="{L1}/{L2}")
-    pub.add_argument("--version", default=None)
+    pub.add_argument("--version", default=None,
+                     help="版本号；split_first 的 split 发布可省略（省略时必须给 --split）")
     pub.add_argument("--instances", default=None,
                      help="逗号分隔的 KEEP 实例 id；granularity=instance 或 images=on 时必填")
     pub.add_argument("--target", default="",
@@ -515,11 +517,14 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
         return 0
 
     if args.cmd == "publish":
-        dataset, version, _ = _resolve_target(args, 3)
+        # split-first 的 split 发布：给了 --split 且没给 version 时允许只寻址 dataset
+        # （{L1}/{L2} 或 --dataset），version 置空走 dataset_distributions 协议。
+        need_version = not (args.split and not args.version)
+        dataset, version, _ = _resolve_target(args, 3 if need_version else 2)
         if args.request_json:
             with open(args.request_json, encoding="utf-8") as f:
                 body = json.load(f)
-            wf = r.versions.publish(dataset, version, request_body=body,
+            wf = r.versions.publish(dataset, version or "", request_body=body,
                                     wait_approval=args.wait_approval)
         else:
             insts = ([s.strip() for s in args.instances.split(",") if s.strip()]
@@ -533,7 +538,7 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
             if args.target_acr_namespace:
                 tgt_ovr["acr_namespace"] = args.target_acr_namespace
             wf = r.versions.publish(
-                dataset, version, instances=insts, target=args.target,
+                dataset, version or "", instances=insts, target=args.target,
                 target_overrides=(tgt_ovr or None),
                 granularity=args.granularity, images=args.images,
                 overwrite=args.overwrite, wait_approval=args.wait_approval,
@@ -693,8 +698,8 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
                 for v in r.versions.list(dataset):
                     print(f"{v.version}\t{v.status}\t{v.storage_path}", file=out)
                 return 0
-            if not args.version or not args.storage_path:
-                raise SystemExit("version create 需要 --version 与 --storage-path")
+            if not args.version:
+                raise SystemExit("version create 需要 --version")
             splits = ([s.strip() for s in args.splits.split(",") if s.strip()]
                       if args.splits else None)
             dv = r.versions.create(dataset, args.version,

{instance_repo-1.0.2 → instance_repo-1.0.7.dev0}/instance_repo/clients/config.py

@@ -26,6 +26,7 @@ OSS bucket/endpoint/region 或 ACR registry/namespace，这些一律运行时取
 """
 from __future__ import annotations
 
+import logging
 import os
 import warnings
 from dataclasses import dataclass, field
@@ -33,6 +34,8 @@ from urllib.parse import urlencode
 
 from .. import _site_defaults
 
+_logger = logging.getLogger(__name__)
+
 # ── 规范参数与兼容别名 ──
 AP_API_KEY = "AP_API_KEY"
 AP_BASE_URL = "AP_BASE_URL"
@@ -277,6 +280,11 @@ def fetch_repo_config(transport, *, cluster: str = "", storage_env: str = "") ->
     需要先有一个能发控制面请求的 transport（已配 api_base + token）。
     cluster 与 storage_env 二选一；cluster 优先（apiserver 先由 cluster 解析出 storage_env）。
 
+    如果 cluster 是集群 ID（c 前缀 + 32 位 hex）或 url_cluster，会先通过
+    ``GET /apis/v1/clusters`` 解析为集群 Name 再下发——apiserver 的 repo-config
+    只按 Name 精确匹配（大小写敏感），用户不需要区分 cluster name / cluster id /
+    url_cluster。
+
     用法示例::
 
         from instance_repo.clients.config import fetch_repo_config
@@ -287,6 +295,7 @@ def fetch_repo_config(transport, *, cluster: str = "", storage_env: str = "") ->
         repo = Repo(profile_overrides=overrides)
     """
     if cluster:
+        cluster = resolve_cluster(transport, cluster)
         query = urlencode({"cluster": cluster})
     elif storage_env:
         query = urlencode({"storage_env": storage_env})
@@ -294,8 +303,12 @@ def fetch_repo_config(transport, *, cluster: str = "", storage_env: str = "") ->
         raise ValueError("fetch_repo_config requires 'cluster' or 'storage_env'")
     data = transport.get(f"/apis/v1/repo-config?{query}")
     # 映射 apiserver 响应字段到 SDK profile_overrides 的 key；cluster 查询的顶层
-    # storage_env 是服务端解析结果，必须保留给 Profile 与 ingest 使用。
+    # storage_env 是服务端解析结果，必须保留给 Profile 与 ingest 使用。cluster 键回传
+    # 解析后的**规范 Name**（可能是 id/url_cluster 的解析结果），供 bootstrap 记录绑定
+    # 证明、ingest 下发 body——两个消费方都需要服务端按 Name 精确匹配的规范值。
     result = {}
+    if cluster:
+        result["cluster"] = cluster
     if cluster and data.get("storage_env"):
         result["storage_env"] = normalize_storage_env(data["storage_env"])
     if oss := data.get("oss"):
@@ -314,3 +327,100 @@ def fetch_repo_config(transport, *, cluster: str = "", storage_env: str = "") ->
     if isinstance(api_env_raw, str) and api_env_raw.strip():
         result["api_env"] = normalize_api_env(api_env_raw)
     return result
+
+
+# ── cluster ID / url_cluster → Name 解析 ──
+
+#: 集群列表缓存时间（秒）。集群拓扑变更频率极低，1 小时足够。
+_CLUSTER_MAP_TTL = 3600.0
+
+#: 缓存按 transport 身份（api_base + Env 头）隔离：不同控制面部署的集群拓扑各自独立，
+#: 共享一个进程里先后连两个 apiserver 时不会串味。
+_cluster_map_cache: dict = {}    # (api_base, env) → 映射表
+_cluster_map_expiry: dict = {}   # (api_base, env) → 过期时刻
+
+
+def _cluster_cache_key(transport) -> tuple:
+    return (
+        str(getattr(transport, "base_url", "") or "").rstrip("/"),
+        str(getattr(transport, "env", "") or ""),
+        id(transport) if getattr(transport, "_custom_send", False) else 0,
+    )
+
+
+def _empty_cluster_map() -> dict:
+    return {"id_to_name": {}, "url_to_name": {}, "names": set()}
+
+
+def fetch_cluster_map(transport) -> dict:
+    """从 ``GET /apis/v1/clusters`` 拉取集群列表，构建 ``id→Name`` 与 ``url_cluster→Name`` 映射。
+
+    apiserver 的 repo-config 只按集群 Name 精确匹配（大小写敏感），因此 SDK 把用户可能
+    提供的三种标识（cluster ID / url_cluster / Name）都规范化为 Name 再下发。结果缓存在
+    进程内存中（按 transport 身份隔离），TTL 与 discover 一致（3600 秒）。拉取失败不缓存
+    新结果：已有该 transport 的成功缓存时回退使用（stale 拓扑好过没有），否则返回空映射。
+    """
+    import time
+    global _cluster_map_cache, _cluster_map_expiry
+    key = _cluster_cache_key(transport)
+    now = time.time()
+    cached = _cluster_map_cache.get(key)
+    if cached is not None and now < _cluster_map_expiry.get(key, 0.0):
+        return cached
+    try:
+        data = transport.get("/apis/v1/clusters")
+        clusters = data.get("clusters", data) if isinstance(data, dict) else (data or [])
+        id_to_name: dict[str, str] = {}
+        url_to_name: dict[str, str] = {}
+        names: set[str] = set()
+        for entry in (clusters or []):
+            if not isinstance(entry, dict):
+                continue
+            cid = str(entry.get("cluster_id") or "").strip()
+            url = str(entry.get("url_cluster") or "").strip()
+            name = str(entry.get("name") or "").strip()
+            if not name:
+                continue
+            names.add(name)
+            if cid and cid not in id_to_name:
+                id_to_name[cid] = name
+            if url and url not in url_to_name:
+                url_to_name[url] = name
+        fresh = {
+            "id_to_name": id_to_name,
+            "url_to_name": url_to_name,
+            "names": names,
+        }
+        _cluster_map_cache[key] = fresh
+        _cluster_map_expiry[key] = now + _CLUSTER_MAP_TTL
+        return fresh
+    except Exception:
+        _logger.debug("fetch_cluster_map failed", exc_info=True)
+        return cached if cached is not None else _empty_cluster_map()
+
+
+def resolve_cluster(transport, cluster_value: str) -> str:
+    """将 cluster ID 或 url_cluster 解析为集群 Name；已是 Name 则原样返回。
+
+    调用 ``GET /apis/v1/clusters`` 获取映射后解析。优先级：Name 本身 > cluster ID >
+    url_cluster。映射失败时保留原值（让 apiserver 返回明确的 "unknown cluster" 错误）。
+    入参先去除首尾空白（与 Go/Java 的 ResolveCluster 一致）；纯空白直接返回，不发请求。
+    """
+    value = str(cluster_value or "").strip()
+    if not value:
+        return value
+    cmap = fetch_cluster_map(transport)
+    if value in cmap["names"]:
+        return value
+    for key in ("id_to_name", "url_to_name"):
+        resolved = cmap[key].get(value)
+        if resolved:
+            return resolved
+    return value
+
+
+def clear_cluster_map_cache() -> None:
+    """清空集群映射缓存（测试用）。"""
+    global _cluster_map_cache, _cluster_map_expiry
+    _cluster_map_cache = {}
+    _cluster_map_expiry = {}

{instance_repo-1.0.2 → instance_repo-1.0.7.dev0}/instance_repo/clients/versions.py

@@ -108,6 +108,8 @@ class VersionsClient:
         「cluster/storage_env 指向 A 数据面、storage_path 指向 B 桶」的错配请求；
         响应缺 bucket/prefix 时与 Go/Java 一样在 POST 前 fail-fast，不静默回退到
         共享 profile 的 OSS 路径。cluster 为空时沿用 profile 自身寻址。
+        返回的 cluster 是 repo-config 响应回传的**规范 Name**（id/url_cluster 会被
+        resolve_cluster 解析掉），ingest body 用它下发，服务端按 Name 精确匹配。
         """
         profile_cluster = (getattr(self._p, "cluster", "") or "").strip()
         method_cluster = (cluster or "").strip()
@@ -130,10 +132,14 @@ class VersionsClient:
                     profile_bucket, profile_prefix)
 
         found = fetch_repo_config(self._t, cluster=effective_cluster)
+        # fetch_repo_config 已把 cluster 入参（可能是 id/url_cluster）解析为规范 Name 并
+        # 回传；ingest body 与 profile 绑定证明都用这个值，服务端按 Name 精确匹配。
+        # 报错文案也统一用规范 Name（与 Go/Java 的 binding.cluster 一致）。
+        resolved_cluster = (found.get("cluster") or effective_cluster).strip()
         resolved_storage_env = normalize_storage_env(found.get("storage_env"))
         if not resolved_storage_env:
             raise SchemaError(
-                f"cluster={effective_cluster!r} 的 repo-config 响应缺少非空 "
+                f"cluster={resolved_cluster!r} 的 repo-config 响应缺少非空 "
                 "storage_env；已中止 ingest，避免发送未绑定的双 selector")
 
         storage_source = (getattr(self._p, "sources", {}) or {}).get(
@@ -141,7 +147,7 @@ class VersionsClient:
         if profile_storage_env and storage_source != "discovery" \
                 and profile_storage_env != resolved_storage_env:
             raise SchemaError(
-                f"cluster={effective_cluster!r} 与显式 profile storage_env="
+                f"cluster={resolved_cluster!r} 与显式 profile storage_env="
                 f"{profile_storage_env!r} 冲突：服务端解析为 "
                 f"{resolved_storage_env!r}")
 
@@ -150,7 +156,7 @@ class VersionsClient:
         if not bound_bucket or not bound_prefix:
             missing = "oss_bucket" if not bound_bucket else "oss_prefix"
             raise SchemaError(
-                f"cluster={effective_cluster!r} 的 repo-config 响应缺少非空 "
+                f"cluster={resolved_cluster!r} 的 repo-config 响应缺少非空 "
                 f"{missing}；已中止 ingest，避免回退到其他数据面的 OSS 路径")
 
         # 只有解析的是 profile 自身 cluster 时才回填绑定；方法级覆盖不能篡改 profile
@@ -159,9 +165,9 @@ class VersionsClient:
             if not profile_storage_env or storage_source == "discovery":
                 self._p.storage_env = resolved_storage_env
                 self._p.sources["storage_env"] = "discovery"
-            self._p.storage_env_cluster = effective_cluster
+            self._p.storage_env_cluster = resolved_cluster
 
-        return (effective_cluster, resolved_storage_env,
+        return (resolved_cluster, resolved_storage_env,
                 bound_bucket, bound_prefix)
 
     def _recorded_images(self, dataset: str, version: str,
@@ -210,7 +216,8 @@ class VersionsClient:
             f"&version={quote(version, safe='')}{extra}")
         return data.get("status", "")
 
-    def create(self, dataset: str, version: str, *, storage_path: str,
+    def create(self, dataset: str, version: str, *,
+               storage_path: str | None = None,
                splits: list[str] | None = None, status: str = "draft",
                storage_type: str = "oss") -> DatasetVersion:
         """显式创建 DatasetVersion（``POST /apis/v1/datasets/versions``）。
@@ -219,7 +226,9 @@ class VersionsClient:
         （例如先建再 PATCH run_type、或先建再单独 ingest）的场景。
 
         参数:
-          storage_path : 必填，``oss://{bucket}/{prefix}`` 形式（apiserver 要求）。
+          storage_path : 可选。缺省时按 profile 自动计算
+            （``oss://{bucket}/{prefix}/{L1}/{L2}/{version}/``，与 ingest 同源）。
+            显式传入时原样下发（特殊桶/自定义布局场景覆盖）。
           splits       : 可选 split 名列表；缺省由 apiserver 按 storage_path 推导。
           status       : 版本状态，缺省 ``draft``（合法值见 VERSION_STATUS_VALUES）。
           storage_type : 存储类型，缺省 ``oss``（当前仅支持）。
@@ -233,9 +242,16 @@ class VersionsClient:
         """
         if not version:
             raise SchemaError("version is required")
+        if storage_path is None and self._p is not None:
+            bucket = getattr(self._p, "oss_bucket", "") or ""
+            if bucket:
+                storage_path = self._layout().ingest_storage_path(
+                    bucket, dataset, version)
         if not storage_path or not storage_path.startswith("oss://"):
             raise SchemaError(
-                f"storage_path must be an oss:// URL, got {storage_path!r}")
+                f"storage_path must be an oss:// URL, got {storage_path!r}; "
+                f"未显式提供且 profile 无 oss_bucket 时无法自动计算，"
+                f"请配置 INSTANCE_REPO_STORAGE_ENV 或用 profile_overrides 提供")
         if status not in VERSION_STATUS_VALUES:
             raise SchemaError(
                 f"invalid status '{status}'; valid values: "
@@ -528,7 +544,7 @@ class VersionsClient:
         wf = self.publish(dataset, version, instances=instances, images=images, **kw)
         return wf, skipped
 
-    def publish(self, dataset: str, version: str, *,
+    def publish(self, dataset: str, version: str = "", *,
                 instances: list[str] | None = None,
                 target: str = "",
                 target_overrides: dict | None = None,
@@ -548,6 +564,15 @@ class VersionsClient:
                 sleep=time.sleep) -> dict:
         """提交 benchmark-release workflow（运行时源地址→目标地址）并轮询到终态。
 
+        按元数据模型选择发布协议（v1.0.5 起）：
+
+        * **split_first 且给了 split**（granularity≠instance）：走 apiserver master 的
+          ``dataset_distributions`` 发布协议。split 必填、version 可选——无 version 即
+          无版本 split 发布，有 version 即版本化 split 发布；目标路径由服务端从 online
+          Dataset base 派生，发布成功后服务端只 ingest 该 split 并置 published。
+        * **其余情况**（version_first / 未给 split / granularity=instance）：保留旧
+          ``oss_distributions`` 纯前缀拷贝语义，行为与 v0.8~v1.0.4 一致。
+
         默认按业务意图构造请求体（SDK 内部拼 workflow body，隐藏 distributions/幂等 key/
         registry host 改写）。源 OSS/ACR 地址来自当前 Repo 的运行时环境或构造参数；目标
         OSS/ACR 地址必须通过 ``target_overrides`` 显式提供。若地址来自 repo-config，调用方
@@ -556,32 +581,57 @@ class VersionsClient:
         环境，也没有隐式目标地址。``request_body`` 为直接透传自定义 workflow body 的逃生舱。
 
         参数:
+          dataset         : {L1}/{L2}
+          version         : 版本号。dataset_distributions 协议下可选（split_first 无版本
+                            split 发布）；旧协议下必填
           instances       : KEEP 实例 id；granularity='instance' 或 images='on' 时必填
           target          : 目标标签；只用于标识，不解析或选择数据面地址
           target_overrides: 目标 oss_bucket/acr_host/acr_namespace 等运行时地址
-          granularity     : 'dataset'(整前缀一条,payload 最小) | 'instance'(逐实例枚举)
-          images          : 'off'(仅 OSS) | 'on'(按实例枚举 ACR 镜像分发)
+          granularity     : 旧协议专用（'dataset' 整前缀一条 | 'instance' 逐实例枚举）；
+                            dataset_distributions 协议恒为整 split 目录
+          images          : 'off'(仅 OSS) | 'on'(按实例枚举 ACR 镜像分发，可与
+                            dataset_distributions 同单下发)
+          split           : **必须与 push 时一致**；split_first 协议下必填
           approval_mode   : 'internal' 时 workflow 停在 awaiting_approval;wait_approval=False
                             即在该状态返回(交人工审批),True 则继续等到 succeeded/failed
-          split           : **必须与 push 时一致**(默认 'default')。instance 粒度按
-                            {version}-assets/{split}/{id}/… 拼源路径;传错会让上架 validate
-                            报 source_path does not exist(真机踩过)。dataset 粒度不受影响。
         """
         if request_body is None:
             if self._p is None:
                 raise SchemaError("typed publish 需要源 profile（用 Repo().versions，"
                                   "或改用 request_body 逃生舱）")
+            model = normalize_metadata_model(
+                metadata_model or (self._p.metadata_model if self._p else None))
+            use_dataset_protocol = (model == MODEL_SPLIT_FIRST
+                                    and bool(split.strip())
+                                    and granularity != "instance")
             dst = load_profile(target or "target", overrides=target_overrides)
-            if not dst.oss_bucket:
-                raise SchemaError(
-                    "publish 需要目标 oss_bucket；SDK 不内置任何环境的桶地址，请通过 "
-                    "target_overrides={'oss_bucket': ..., 'acr_host': ...} 提供（见文档）")
-            lay = self._layout(metadata_model)
-            oss_dists = R.build_oss_distributions(
-                dataset, version, instances or [],
-                src_bucket=self._p.oss_bucket, dst_bucket=dst.oss_bucket,
-                granularity=granularity, overwrite=overwrite, split=split,
-                instance_objects=instance_objects, layout=lay)
+            lay = self._layout(model)
+            dataset_dists: list[dict] = []
+            oss_dists: list[dict] = []
+            if use_dataset_protocol:
+                if not dst.oss_bucket:
+                    raise SchemaError(
+                        "publish 需要目标 oss_bucket；SDK 不内置任何环境的桶地址，请通过 "
+                        "target_overrides={'oss_bucket': ..., 'acr_host': ...} 提供（见文档）")
+                dataset_dists = R.build_dataset_distributions(
+                    dataset, split=split, version=version,
+                    metadata_model=model,
+                    src_bucket=self._p.oss_bucket,
+                    overwrite=overwrite, layout=lay)
+            else:
+                if not version:
+                    raise SchemaError(
+                        f"version is required when metadata_model={model!r} "
+                        f"且未指定 split；split_first 的 split 发布请显式传 split")
+                if not dst.oss_bucket:
+                    raise SchemaError(
+                        "publish 需要目标 oss_bucket；SDK 不内置任何环境的桶地址，请通过 "
+                        "target_overrides={'oss_bucket': ..., 'acr_host': ...} 提供（见文档）")
+                oss_dists = R.build_oss_distributions(
+                    dataset, version, instances or [],
+                    src_bucket=self._p.oss_bucket, dst_bucket=dst.oss_bucket,
+                    granularity=granularity, overwrite=overwrite, split=split,
+                    instance_objects=instance_objects, layout=lay)
             image_dists: list[dict] = []
             if images == "on":
                 if not instances:
@@ -599,12 +649,16 @@ class VersionsClient:
                     layout=lay, split=split)
             elif images != "off":
                 raise SchemaError(f"unknown images {images!r} (use 'off'|'on')")
-            scope = "dataset" if granularity == "dataset" else f"n{len(instances or [])}"
-            idem = R.make_idempotency_key(dataset, version, scope, oss_dists, image_dists)
+            scope = ("split" if dataset_dists
+                     else "dataset" if granularity == "dataset"
+                     else f"n{len(instances or [])}")
+            idem = R.make_idempotency_key(dataset, version, scope,
+                                          oss_dists, image_dists, dataset_dists)
             request_body = R.build_release_request(
                 idempotency_key=idem,
-                description=description or f"release {dataset}/{version} ({granularity})",
+                description=description or f"release {dataset}/{version} ({scope})",
                 oss_dists=oss_dists, image_dists=image_dists,
+                dataset_dists=dataset_dists,
                 approval_mode=approval_mode, backend=backend)
 
         wf = self._t.post(self._WORKFLOWS, request_body)

{instance_repo-1.0.2 → instance_repo-1.0.7.dev0}/instance_repo/layout.py

@@ -42,10 +42,11 @@ DEFAULT_METADATA_MODEL = MODEL_SPLIT_FIRST
 _MODELS = (MODEL_VERSION_FIRST, MODEL_SPLIT_FIRST)
 
 # ACR tag 合法字符集与长度（OCI/Docker 约定）：首字符须为字母数字或下划线，
-# 其余可含字母数字、下划线、点、连字符，总长 ≤128。**大小写敏感**，不做小写化
-# —— 小写化会静默改变镜像身份，进而指向一个从未推送过的引用。
+# 其余可含字母数字、下划线、点、连字符，总长 **< 105**（ACR tag 硬上限 128，
+# 预留 {version}-{id} 拼接余量，超长片段由 sanitize 截断）。**大小写敏感**，
+# 不做小写化——小写化会静默改变镜像身份，进而指向一个从未推送过的引用。
 _TAG_RE = re.compile(r"^[A-Za-z0-9_][A-Za-z0-9_.\-]*$")
-_TAG_MAX_LEN = 128
+_TAG_MAX_LEN = 104
 _TAG_BAD_CHARS = re.compile(r"[^A-Za-z0-9_.\-]+")
 _TAG_BAD_HEAD = re.compile(r"^[^A-Za-z0-9_]+")
 

{instance_repo-1.0.2 → instance_repo-1.0.7.dev0}/instance_repo/release.py

@@ -174,21 +174,75 @@ def build_image_distributions(dataset: str, version: str, instances: list[str],
     return dists
 
 
+def build_dataset_distributions(dataset: str, *,
+                                split: str = "",
+                                version: str = "",
+                                metadata_model: str = "",
+                                src_bucket: str,
+                                overwrite: bool = False,
+                                layout: "L.Layout | None" = None) -> list[dict]:
+    """构造 ``dataset_distributions`` 数组（apiserver master 的 dataset release 协议）。
+
+    与 :func:`build_oss_distributions` 的纯前缀拷贝不同，本协议每项携带
+    ``metadata_model/dataset/split/version/source_path``，服务端据此解析发布单元、
+    从 online Dataset base 派生目标路径（SDK 不提供 target_path），发布成功后以
+    ``publish_after_validation=true`` 只 ingest 该单元并置 published。
+
+    模型约定（对齐 apiserver ``ResolveDatasetRelease``）：
+
+    * ``split_first``：split 必填、version 可选。无 version 时源目录必须是整个
+      split 目录 ``swe/datasets/<L1>/<L2>/<split>/``；有 version 时是
+      ``swe/datasets/<L1>/<L2>/<version>/<split>/``。
+    * ``version_first``：version 必填，源目录为整个版本目录
+      ``swe/datasets/<L1>/<L2>/<version>/``。
+
+    返回单元素数组（一次发布一个 split/版本）；多个单元多次调用后合并提交。
+    """
+    lay = layout or L.Layout()
+    model = L.normalize_metadata_model(metadata_model) or lay.model
+    ver, spl = L.check_locator(model, version, split)
+    if model == L.MODEL_SPLIT_FIRST:
+        key = f"{lay.dataset_root(dataset)}{ver + '/' if ver else ''}{spl}/"
+    else:
+        key = f"{lay.dataset_root(dataset)}{ver}/"
+    return [{
+        "source_path": P.oss_uri(src_bucket, key),
+        "dataset": dataset,
+        "metadata_model": model,
+        "version": ver,
+        "split": spl if model == L.MODEL_SPLIT_FIRST else "",
+        "overwrite": overwrite,
+    }]
+
+
 def make_idempotency_key(dataset: str, version: str, scope: str,
-                         oss_dists: list[dict], image_dists: list[dict]) -> str:
+                         oss_dists: list[dict], image_dists: list[dict],
+                         dataset_dists: list[dict] | None = None) -> str:
     """内容寻址幂等 key：相同内容→相同 key→平台复用已有 workflow（安全重试）。
-    形如 ``<sanitize(dataset)>-<version>-release-<scope>-<sha1[:10]>``。"""
-    payload = json.dumps({"oss": oss_dists, "image": image_dists},
-                         sort_keys=True, ensure_ascii=False)
-    digest = hashlib.sha1(payload.encode("utf-8")).hexdigest()[:10]
+    形如 ``<sanitize(dataset)>-<version>-release-<scope>-<sha1[:10]>``。
+
+    ``dataset_dists`` 为空时不进载荷——保持与三语言 conformance golden 的旧 key
+    逐字节一致（纯拷贝协议的既有调用方 key 不变）；非空时才参与哈希，使两种协议
+    互不串用同一个 workflow。
+    """
+    payload = {"oss": oss_dists, "image": image_dists}
+    if dataset_dists:
+        payload["dataset"] = dataset_dists
+    text = json.dumps(payload, sort_keys=True, ensure_ascii=False)
+    digest = hashlib.sha1(text.encode("utf-8")).hexdigest()[:10]
     return f"{P.sanitize_repo(dataset)}-{version}-release-{scope}-{digest}"
 
 
 def build_release_request(*, idempotency_key: str, description: str,
                           oss_dists: list[dict], image_dists: list[dict],
+                          dataset_dists: list[dict] | None = None,
                           approval_mode: str = "internal",
                           backend: str = "acr") -> dict:
-    """组装 benchmark-release workflow 请求体；空的分发数组省略（两者均可选）。
+    """组装 benchmark-release workflow 请求体；空的分发数组省略（均可选）。
+
+    ``dataset_dists`` 走 apiserver master 的 ``dataset_distributions`` 发布协议
+    （split-first 的 split 发布 / version-first 的版本发布），与 ``oss_dists``
+    的纯前缀拷贝语义不同：前者发布成功后由服务端 ingest 并置 published。
 
     ``backend`` 自 v0.8 起默认 ``"acr"``（v0.7.x 为 ``"bp"``）：镜像分发的真实执行后端就是
     ACR 仓库同步，默认值应与之一致，避免调用方每次都要显式纠正。
@@ -196,6 +250,8 @@ def build_release_request(*, idempotency_key: str, description: str,
     spec: dict = {"approval_mode": approval_mode, "backend": backend}
     if image_dists:
         spec["image_distributions"] = image_dists
+    if dataset_dists:
+        spec["dataset_distributions"] = dataset_dists
     if oss_dists:
         spec["oss_distributions"] = oss_dists
     return {

{instance_repo-1.0.2 → instance_repo-1.0.7.dev0}/instance_repo/repo.py

@@ -568,33 +568,31 @@ class Repo:
     def my_user_data_permissions(self, uid: str, subpath: str = "") -> list[str]:
         """返回当前用户对某用户数据资源（uid 级或子路径级）拥有的角色名列表。
 
-        通过 principal_id=whoami() 查询 role-bindings，再把 role_id 反向映射回短名。
-        只统计 resource_id 恰好等于 {storage_env}/{uid}[/{subpath}] 的绑定——
-        uid 级绑定（subpath=""）与各子路径级绑定是独立条目，互不包含；查 uid
-        级权限请再以 subpath="" 调用一次。
+        经 GET /apis/v1/me/resource-permissions 自查有效动作（get=读、use=写、
+        assign=管 ACL），再映射回短名：assign→admin、use→writer、get→reader
+        （取能力最高档）。目录主人恒为 admin（与服务端 owner 快路径语义一致）。
+
+        历史实现走 GET /apis/v1/role-bindings 列表再客户端过滤，但该端点对非
+        owner 调用方有 assign 门控，被授权者查自己 principal 恒得空列表，故改用
+        /me/resource-permissions 自查端点。
         """
         if not str(uid).strip():
             raise SchemaError("uid must not be empty")
         from urllib.parse import quote
+        # 先构造 resource_id：subpath 校验在任何网络请求之前完成（对称 Go/Java）。
         resource_id = self._user_data_acl_resource_id(uid, subpath)
-        my_uid = self.whoami()
-        path = (f"/apis/v1/role-bindings?scope=resource"
-                f"&resource_type=user_data"
-                f"&principal_id={quote(my_uid, safe='')}")
+        if str(uid).strip() == str(self.whoami()).strip():
+            return ["admin"]
+        path = (f"/apis/v1/me/resource-permissions?resource_type=user_data"
+                f"&resource_id={quote(resource_id, safe='')}")
         data = self.transport.get(path)
-        bindings = data if isinstance(data, list) else (
-            data.get("role_bindings", data.get("items", []))
-            if isinstance(data, dict) else [])
-        # 反向映射 role_id → 短名（未识别的 role_id 原样保留）
-        _REV = {v: k for k, v in self._USER_DATA_ROLE_MAP.items()}
-        roles: list[str] = []
-        for b in (bindings or []):
-            rid = b.get("role_id", "") if isinstance(b, dict) else ""
-            roles.append(_REV.get(rid, rid))
-        # 只保留与该资源（uid 级或子路径级 resource_id）精确匹配的条目
-        matched: list[str] = []
-        for b, role_name in zip(bindings or [], roles):
-            rid = b.get("resource_id", "") if isinstance(b, dict) else ""
-            if rid == resource_id:
-                matched.append(role_name)
-        return matched
+        actions = data.get("actions", []) if isinstance(data, dict) else []
+        if not actions:
+            return []
+        if "assign" in actions:
+            return ["admin"]
+        if "use" in actions:
+            return ["writer"]
+        if "get" in actions:
+            return ["reader"]
+        return []

{instance_repo-1.0.2 → instance_repo-1.0.7.dev0}/instance_repo/store/registry.py

@@ -82,11 +82,40 @@ class ApiMetadataRegistry(BaseMetadataRegistry):
         return base + ("&" + "&".join(extra) if extra else "")
 
     def register(self, meta: DatasetInstance) -> DatasetInstance:
+        """注册实例元数据（pending）。
+
+        apiserver 契约（POST /apis/v1/datasets/instances）：
+
+        * dataset / version / split 走 **query string**（``dataset_name`` /
+          ``version`` / ``split``），body 里没有 dataset 字段——handler 用
+          ``DisallowUnknownFields`` 解码，发 ``dataset``/``dataset_version`` 会被
+          400 拒；query 缺 dataset_name 则在 split_first 定位时 92005。
+        * body 只接受 ``instance_id`` / ``split`` / ``manifest`` / ``tags`` /
+          ``difficulty`` / ``docker_image`` / ``extend_meta``（
+          createDatasetInstanceRequest 白名单）。
+        * split 的 ``default`` 哨兵归一为空串（与写路径 _version_prefix 对称）。
+
+        owner_reference 等其余字段在 register 端点无承接位（owner 由 apiserver
+        据 caller 派生），故不进 body。
+        """
         meta.validate()
+        split = "" if meta.split == "default" else (meta.split or "")
+        body: dict = {"instance_id": meta.instance_id, "split": split}
+        if meta.manifest:
+            body["manifest"] = [m.to_dict() for m in meta.manifest]
+        if meta.tags:
+            body["tags"] = meta.tags
+        if meta.difficulty is not None:
+            body["difficulty"] = meta.difficulty
+        if meta.docker_image:
+            body["docker_image"] = meta.docker_image
+        if meta.extend_meta:
+            body["extend_meta"] = meta.extend_meta
+        path = f"{self._BASE}?{self._q(meta.dataset, meta.dataset_version, split)}"
         with _unimplemented(
                 "POST /apis/v1/datasets/instances（实例注册）",
                 "当前可用路径：push(register=False) 只传 OSS，再用 versions.ingest() 扫描入库。"):
-            data = self._t.post(self._BASE, meta.to_dict())
+            data = self._t.post(path, body)
         return DatasetInstance.from_dict(data)
 
     def commit(self, instance_uid: str, digests: dict | None,

{instance_repo-1.0.2 → instance_repo-1.0.7.dev0}/instance_repo/transport.py

@@ -171,6 +171,9 @@ class Transport:
         self.env = env
         self.timeout = timeout
         self._send = http_send or _KeepAliveSender()
+        # 自定义发送器身份参与缓存键（见 config._cluster_cache_key）：注入过 fake/代理的
+        # transport 即使 base/env 相同也各自隔离，与 Go/Java 的 customSend 语义一致。
+        self._custom_send = http_send is not None
         self._retry_attempts = retry_attempts
         # STS 凭据缓存：key=("oss",bucket,prefix,duration) / ("acr",host,duration)，
         # 按签发返回的 Expiration 失效（留 60s 安全余量）。关缓存则每次现签。

{instance_repo-1.0.2 → instance_repo-1.0.7.dev0}/instance_repo.egg-info/PKG-INFO

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

{instance_repo-1.0.2 → instance_repo-1.0.7.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "instance-repo"
-version = "1.0.2"
+version = "1.0.7.dev0"
 description = "InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）"
 requires-python = ">=3.10"
 readme = "README.md"