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

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

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

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

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

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

@@ -60,8 +60,8 @@ def build_parser() -> argparse.ArgumentParser:
     p.add_argument("--no-image", action="store_true")
     p.add_argument("--overwrite", action="store_true")
     p.add_argument("--no-register", action="store_true",
-                   help="跳过 DB 写入（register/commit），只传 OSS，之后由 ingest 扫描入库；"
-                        "apiserver 未实现实例写端点时必须用它")
+                   help="只传 OSS 不写库（默认上传后自动 ingest 写库；"
+                        "置上则跳过 ingest，之后自行 ingest 扫描入库）")
     p.add_argument("--no-verify", action="store_true",
                    help="跳过上传后的回读校验（默认校验 OSS 对象/ACR 镜像确已落库）")
 
@@ -76,7 +76,7 @@ def build_parser() -> argparse.ArgumentParser:
     pm.add_argument("--no-image", action="store_true")
     pm.add_argument("--overwrite", action="store_true")
     pm.add_argument("--register", action="store_true",
-                    help="走 register/commit 三段式写 DB（缺省不写，留给 ingest 扫描入库）")
+                    help="整批上传完成后一次 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",
@@ -285,6 +285,8 @@ def build_parser() -> argparse.ArgumentParser:
                      help="create 用：oss://{bucket}/{prefix}")
     ver.add_argument("--storage-type", choices=["oss"], default="oss")
     ver.add_argument("--splits", default=None, help="逗号分隔 split 名")
+    ver.add_argument("--split", default=None,
+                     help="status 用：查 split 级真实记录（split_first 发布状态/目标路径）")
     ver.add_argument("--status", choices=_STATUS_CHOICES, default=None,
                      help="update 用：版本状态流转")
     ver.add_argument("--run-type", choices=["train", "eval"], default=None,
@@ -454,6 +456,11 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
                                verify=not args.no_verify)
         print(f"{res.instance_id} uploaded={res.uploaded} "
               f"image_pushed={res.image_pushed}", file=out)
+        if res.ingest:
+            stats = res.ingest.get("stats", {}) or {}
+            print(f"ingest {res.ingest.get('ingest_id')} "
+                  f"status={res.ingest.get('status')} "
+                  f"instances={stats.get('instance_count')}", file=out)
         return 0
 
     if args.cmd == "push-many":
@@ -711,7 +718,13 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
             return 0
         dataset, version, _ = _resolve_target(args, 3)
         if args.action == "status":
-            print(r.versions.status(dataset, version), file=out)
+            if args.split:
+                sp = r.versions.split_detail(dataset, version, args.split)
+                print(f"{sp.get('name', args.split)}\t{sp.get('status', '')}\t"
+                      f"{sp.get('storage_path', '')}\t"
+                      f"published_at={sp.get('published_at') or ''}", file=out)
+            else:
+                print(r.versions.status(dataset, version), file=out)
             return 0
         if args.action == "set-run-type":
             r.versions.set_run_type(dataset, version,

{instance_repo-1.0.7.dev0 → instance_repo-1.0.9}/instance_repo/clients/instances.py

@@ -15,25 +15,46 @@ from pathlib import Path
 from .. import paths as P
 from ..concurrency import map_concurrent
 from ..content import pack
-from ..errors import ImageMissing, TransportError
+from ..errors import ImageMissing, SchemaError, TransportError
 from ..image import dockerfile_from, rewrite_dockerfile
 from ..layout import Layout
 from ..models import (
     DatasetInstance, ManifestEntry, OwnerReference, PushResult, Feedback,
 )
-from ..validate import check_layout, check_swe_json, detect_format, validate_instance_id
+from ..validate import (check_layout, check_swe_json, check_custom,
+                        detect_format, validate_instance_id,
+                        CUSTOM_SCHEMA_VERSION)
 
 logger = logging.getLogger(__name__)
 
 
 class InstancesClient:
     def __init__(self, transport, profile, content_store, image_store,
-                 registry) -> None:
+                 registry, ingester=None) -> None:
         self._t = transport
         self._p = profile
         self._content = content_store
         self._image = image_store
         self._reg = registry
+        # register=True 时经 ingest 写库（apiserver :commit 端点缺失，三段式
+        # 收尾改为 ingest）。ingester 形如 (dataset, version) -> ingest job dict；
+        # 由 Repo 注入 versions.ingest。直接构造未注入时 register=True 会报错。
+        self._ingester = ingester
+
+    def _after_upload(self, register: bool, dataset: str,
+                      version: str) -> dict | None:
+        """register=True：上传成功后触发一次 ingest 写库，返回 ingest job 摘要。
+
+        register=False 返回 None（只传 OSS，由调用方决定何时 ingest）。
+        """
+        if not register:
+            return None
+        if self._ingester is None:
+            raise SchemaError(
+                "register=True 需要 ingest 回调：请通过 Repo() 构造客户端"
+                "（已注入 versions.ingest），或显式传入 ingester=...；"
+                "直接构造 InstancesClient 且未注入时请用 register=False 只传 OSS")
+        return self._ingester(dataset, version)
 
     def _layout(self, metadata_model: str | None = None) -> Layout:
         """按（显式或 profile 的）元数据模型构造布局策略。
@@ -47,10 +68,12 @@ class InstancesClient:
 
     # ── 只读 ──
     def validate(self, local_path):
-        """校验实例：自动检测格式（目录→harbor，.json→swe）。"""
+        """校验实例：自动检测格式（目录→harbor，dir-notask→custom，.json→swe）。"""
         fmt = detect_format(local_path)
         if fmt == "swe":
             return check_swe_json(local_path)
+        if fmt == "custom":
+            return check_custom(local_path)
         return check_layout(local_path)
 
     def get(self, dataset: str, version: str, instance_id: str,
@@ -82,20 +105,32 @@ class InstancesClient:
         harbor: validate → (可选)推镜像 → 上传 OSS(content.tgz + {id}.json)。
         swe: validate JSON → 上传 OSS({id}.json only)，不推镜像。
 
-        register=True（默认）走"元数据先行"三段式：register(pending)→OSS→commit(ready)。
-        register=False 为临时路径（apiserver 暂无 instance register/commit 端点）：跳过
-        DB 写入，只上传 OSS；元数据随 {id}.json 落 OSS，之后由 versions.ingest() 扫描入库。
+        register=True（默认）：上传成功后自动触发一次 versions.ingest 把元数据写库
+        （apiserver 的 :commit 端点缺失，三段式收尾由 ingest 替代；结果见
+        ``PushResult.ingest``）。register=False：只传 OSS 不写库，之后由调用方
+        自行 versions.ingest() 扫描入库。
 
         verify=True（默认）在真正发生上传后回读校验：确认 OSS 对象确实可 HEAD 到。
 
         image_release_dst_acr（可选）：目标（prod）ACR host（仅 harbor 格式有效）。
         """
         local_path = Path(local_path)
+        if register and self._ingester is None:
+            # fail-fast：register=True 需要 ingest 回调，先于任何打包/上传报错
+            raise SchemaError(
+                "register=True 需要 ingest 回调：请通过 Repo() 构造客户端"
+                "（已注入 versions.ingest），或显式传入 ingester=...；"
+                "直接构造 InstancesClient 且未注入时请用 register=False 只传 OSS")
         fmt = detect_format(local_path)
         if fmt == "swe":
             return self._push_swe(local_path, dataset, version, split=split,
                                   overwrite=overwrite, register=register,
                                   verify=verify)
+        if fmt == "custom":
+            return self._push_custom(local_path, dataset, version, split=split,
+                                     push_image=push_image,
+                                     overwrite=overwrite, register=register,
+                                     verify=verify)
         # ── harbor 路径 ──
         report = check_layout(local_path)          # ① 本地校验（缺文件即抛）
         instance_id = report.instance_id
@@ -147,23 +182,26 @@ class InstancesClient:
             instance_status="draft",
         )
         uid = instance_id
-        if register:
-            registered = self._reg.register(meta)  # 校验 schema（owner_reference 可选）
-            uid = registered.id or instance_id
-
-        image_pushed = False
-        if push_image and has_image:
-            # ③ 推 ACR（final 改写 Dockerfile）
-            self._image.push(image_tar, docker_ref, overwrite=overwrite)
-            rewrite_dockerfile(dockerfile, docker_ref, tar_role="final")
-            image_pushed = True
 
-        # ④ 打包 + 上传 OSS（排除 image.tar.gz）；{id}.json 供 pull 校验 / ingest 扫描
+        # 打包 + 构造 manifest（本地）→ register(pending) → 推 ACR → 上传 OSS。
+        # register 需要 manifest：apiserver 的 hasFile 校验要求至少一条
+        # content_type=file 项，manifest 缺失时 register 被 92005 拒（曾导致
+        # custom/harbor 主路径 push(register=True) 失败）。register 仍先于任何
+        # 远程写（元数据先行），manifest 在本地打包时即可算出 digest。
         with tempfile.TemporaryDirectory(prefix="irepo_") as td:
             tgz = Path(td) / "content.tgz"
             digest = pack(local_path, tgz, exclude_image_tar=True)
             meta.manifest = _manifest(self._p.oss_bucket, dataset, version,
                                       instance_id, split, digest, lay)
+
+            image_pushed = False
+            if push_image and has_image:
+                # ③ 推 ACR（final 改写 Dockerfile）
+                self._image.push(image_tar, docker_ref, overwrite=overwrite)
+                rewrite_dockerfile(dockerfile, docker_ref, tar_role="final")
+                image_pushed = True
+
+            # ④ 上传 OSS（排除 image.tar.gz）；{id}.json 供 pull 校验 / ingest 扫描
             put = self._content.put(instance_id, dataset, version, split, tgz,
                                     meta.to_canonical_json(), overwrite=overwrite,
                                     layout=lay)
@@ -181,22 +219,15 @@ class InstancesClient:
                 raise TransportError(
                     f"{instance_id}: ACR 回读校验失败——推送后未 inspect 到镜像 "
                     f"{docker_ref}")
-        # ⑤ commit(ready) —— 带上 manifest,保证 DB 记录与 OSS {id}.json 一致(pull 可校验)
-        #
-        # 与 Go 对齐的评审修订：put 被 skip 时（两对象已存在且未 overwrite），OSS 上是
-        # **别的生产者**（如 Go SDK）写的字节，我们无权断言其 digest。若仍提交本地算出的
-        # digest，之后任何 pull(verify=True) 必报 E_DIGEST_MISMATCH。清 digests 还不够——
-        # pull 读的是 **manifest** 里的 content_digest，故 skip 分支必须同时摘掉它。
+        # ⑤ 写库：register=True 时经 ingest 扫描入库（替代缺失的 :commit 三段式收尾）。
+        #    ingest 幂等（重扫 OSS），skip 与否都由服务端按 OSS 实际字节重算 digest，
+        #    不再有「本地 digest 覆盖别家生产者」的 skip 分支歧义。
+        ingest_result = self._after_upload(register, dataset, version)
         digests = {"content.tgz": digest}
-        if register:
-            commit_digests = None if skipped else digests
-            commit_manifest = (_manifest_without_digest(meta.manifest) if skipped
-                               else meta.manifest)
-            self._reg.commit(uid, commit_digests, manifest=commit_manifest)
         return PushResult(instance_id=instance_id, uploaded=not skipped,
                           skipped=skipped, image_pushed=image_pushed,
                           docker_image=docker_ref or None,
-                          digests=digests)
+                          digests=digests, ingest=ingest_result)
 
     def _push_swe(self, json_path: Path, dataset: str, version: str, *,
                   split: str = "default", overwrite: bool = False,
@@ -245,32 +276,105 @@ class InstancesClient:
                 raise TransportError(
                     f"{instance_id}: OSS 回读校验失败——上传后未在 OSS 找到 {idx_key}")
 
-        # ④ 可选 register/commit
-        manifest = [ManifestEntry(
-            file_path=P.oss_uri(self._p.oss_bucket, idx_key),
-            content_type="file", content_format="json",
-            content_digest=digest)]
-
-        if register:
-            # 构造结构化元数据（不含 patch/test_patch 等大字段）
-            meta = DatasetInstance(
-                instance_id=instance_id, dataset=dataset,
-                dataset_version=version, split=split,
-                docker_image=docker_image,
-                manifest=manifest,
-                extend_meta={k: str(v) for k, v in report.raw_data.items()
-                             if k in ("repo", "base_commit", "language")
-                             and v is not None},
-                instance_status="draft",
-            )
-            registered = self._reg.register(meta)
-            uid = registered.id or instance_id
-            self._reg.commit(uid, {"instance.json": digest}, manifest=manifest)
+        # ④ 写库：register=True 时经 ingest 扫描入库（替代缺失的 :commit 收尾）
+        ingest_result = self._after_upload(register, dataset, version)
 
         return PushResult(instance_id=instance_id, uploaded=not skipped,
                           skipped=skipped, image_pushed=False,
                           docker_image=docker_image or None,
-                          digests={"instance.json": digest})
+                          digests={"instance.json": digest},
+                          ingest=ingest_result)
+
+    def _push_custom(self, local_path: Path, dataset: str, version: str, *,
+                     split: str = "default", push_image: bool = True,
+                     overwrite: bool = False, register: bool = True,
+                     verify: bool = True) -> PushResult:
+        """推一个 custom 格式实例：validate → 上传元数据 JSON → (目录输入时) 上传资产。
+
+        custom 格式的两种输入：
+
+        - **目录**：SDK 生成最小元数据 JSON（``instance_id`` / ``metadata_model`` /
+          ``schema_version`` / ``created_at`` / ``updated_at``）上传到 ``{split}/{id}.json``，
+          目录内容**原样**逐文件上传到 ``{split}-assets/{id}/`` 前缀下（保持相对路径）。
+        - **``.json`` 文件**：校验后**原样**上传到 ``{split}/{id}.json``（无资产）。
+
+        custom 格式**不参与镜像流程**：``push_image=True`` 时告警并忽略（与 SWE 同口径）。
+        """
+        import datetime as _dt
+        import warnings as _warnings
+
+        if push_image:
+            _warnings.warn(
+                "custom 格式不支持 ACR 镜像推送（push_image=True 已忽略）；"
+                "如需镜像请用 harbor 格式",
+                UserWarning, stacklevel=3)
+
+        report = check_custom(local_path)           # ① 校验（含 instance_id 安全检查）
+        instance_id = report.instance_id
+        lay = self._layout()
+        idx_key = lay.metadata_key(dataset, instance_id, version=version, split=split)
+        sts_prefix = lay.sts_prefix(dataset)
+
+        if report.source == "json":
+            # JSON 输入：原样上传
+            raw_bytes = local_path.read_bytes()
+            meta_digest = "sha256:" + hashlib.sha256(raw_bytes).hexdigest()
+            put = self._content.put_object(
+                idx_key, raw_bytes, overwrite=overwrite,
+                sts_prefix=sts_prefix, dataset=dataset)
+            skipped = bool(put.get("skipped"))
+            asset_digests: dict[str, str] = {}
+        else:
+            # 目录输入：生成最小元数据 JSON + 原样上传资产
+            now_iso = _dt.datetime.now(_dt.timezone.utc).isoformat(
+                timespec="seconds").replace("+00:00", "Z")
+            meta_doc = {
+                "instance_id": instance_id,
+                "metadata_model": "custom",
+                "schema_version": CUSTOM_SCHEMA_VERSION,
+                "created_at": now_iso,
+                "updated_at": now_iso,
+            }
+            raw_bytes = json.dumps(meta_doc, ensure_ascii=False).encode("utf-8")
+            meta_digest = "sha256:" + hashlib.sha256(raw_bytes).hexdigest()
+            put = self._content.put_object(
+                idx_key, raw_bytes, overwrite=overwrite,
+                sts_prefix=sts_prefix, dataset=dataset)
+            skipped = bool(put.get("skipped"))
+
+            # 原样上传目录内所有文件到 {split}-assets/{id}/<relpath>
+            asset_prefix = (f"{lay.dataset_root(dataset)}"
+                            f"{split}-assets/{instance_id}/")
+            asset_digests = {}
+            for child in sorted(local_path.rglob("*")):
+                if not child.is_file():
+                    continue
+                rel = child.relative_to(local_path).as_posix()
+                key = asset_prefix + rel
+                data = child.read_bytes()
+                digest = "sha256:" + hashlib.sha256(data).hexdigest()
+                asset_digests[rel] = digest
+                aput = self._content.put_object(
+                    key, data, overwrite=overwrite,
+                    sts_prefix=sts_prefix, dataset=dataset)
+                if not skipped and bool(aput.get("skipped")):
+                    skipped = True  # 任一被 skip 即整体视为 skip
+
+        # ③ 回读校验（防静默成功）
+        if verify and not skipped:
+            if not self._content.object_exists(idx_key, sts_prefix=sts_prefix,
+                                               dataset=dataset):
+                raise TransportError(
+                    f"{instance_id}: OSS 回读校验失败——上传后未在 OSS 找到 {idx_key}")
+
+        # ④ 写库：register=True 时经 ingest 扫描入库（替代缺失的 :commit 收尾）
+        ingest_result = self._after_upload(register, dataset, version)
+
+        return PushResult(instance_id=instance_id, uploaded=not skipped,
+                          skipped=skipped, image_pushed=False,
+                          docker_image=None,
+                          digests={"instance.json": meta_digest},
+                          ingest=ingest_result)
 
     # ── 上架前：把生产副本的 task.toml 指向生产镜像（本地重写，不触网）──────────
     def retarget_prod_content(self, local_dir, dataset: str, version: str,
@@ -341,6 +445,10 @@ class InstancesClient:
         置 True 则不抛，返回列表中失败项以 ``ItemError`` 占位、成功项为 ``PushResult``，
         供上层（如 deliver）对成功子集继续 ingest 并单独汇报失败。结果按输入顺序。
 
+        ``register=True``：整批上传完成后触发**一次** ingest 写库（绝不逐实例
+        ingest——N 个实例 N 次全量扫描是 O(N²) 浪费）；ingest 结果不在返回列表里，
+        需要时由调用方自行调用 ``versions.ingest`` 获取（deliver/CLI 均如此）。
+
         ``owner_reference`` 整批共用同一来源引用（批量交付通常同源；需要逐实例不同来源时
         请自行循环 ``push``）。CLI 的 push / push-many / deliver 都把它设为必填——交付
         路径必须能追溯上游来源。
@@ -365,14 +473,20 @@ class InstancesClient:
                 pass
 
         def _one(d):
+            # 逐实例强制 register=False：批量 ingest 只在整批结束后执行一次
             return self.push(d, dataset, version,
                              owner_reference=owner_reference, split=split,
                              push_image=push_image, overwrite=overwrite,
-                             register=register, verify=verify,
+                             register=False, verify=verify,
                              image_release_dst_acr=image_release_dst_acr)
 
-        return map_concurrent(_one, dirs, concurrency=concurrency,
-                              return_exceptions=continue_on_error)
+        results = map_concurrent(_one, dirs, concurrency=concurrency,
+                                 return_exceptions=continue_on_error)
+        # continue_on_error=False 时 map_concurrent 已对失败项抛 ItemError，能走到
+        # 这里说明整批成功；True 时对成功子集 ingest（与 deliver 语义一致）。
+        if register:
+            self._after_upload(True, dataset, version)
+        return results
 
     def pull(self, dataset: str, version: str, instance_id: str, dest_dir,
              split: str = "default", *, verify: bool = True) -> Path:

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

@@ -216,10 +216,42 @@ class VersionsClient:
             f"&version={quote(version, safe='')}{extra}")
         return data.get("status", "")
 
+    # GET /apis/v1/datasets/splits/detail：split-first 叶详情（真实 split 记录）。
+    _SPLITS = "/apis/v1/datasets/splits"
+
+    def split_detail(self, dataset: str, version: str, split: str, *,
+                     environment: str | None = None) -> dict:
+        """split 级读 API（``GET /apis/v1/datasets/splits/detail``）。
+
+        直接读 split-first 记录：``status``/``published_at``/``storage_path``
+        都是真实值，不经过 version_first 兼容投影。版本级读接口
+        （:meth:`list`/:meth:`status`）只保证 version_first 语义；要看
+        split_first 的发布状态与目标路径请用本方法。
+
+        ``environment`` 缺省由 profile 派生（与读路径对称）；显式传入可覆盖，
+        例如发布后查 ``environment="online"`` 的 published 状态与目标路径。
+        """
+        if not (split or "").strip():
+            raise SchemaError("split is required for split detail")
+        mm = normalize_metadata_model(
+            self._p.metadata_model if self._p is not None else None)
+        env = (environment or "").strip()
+        if not env and self._p is not None:
+            env = (getattr(self._p, "dataset_environment", "") or "").strip()
+        query = (f"dataset_name={quote(dataset, safe='')}"
+                 f"&version={quote(version or '', safe='')}"
+                 f"&split={quote(split, safe='')}"
+                 f"&metadata_model={quote(mm, safe='')}")
+        if env:
+            query += f"&environment={quote(env, safe='')}"
+        data = self._t.get(f"{self._SPLITS}/detail?{query}")
+        return data if isinstance(data, dict) else {}
+
     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:
+               storage_type: str = "oss",
+               environment: str | None = None) -> DatasetVersion:
         """显式创建 DatasetVersion（``POST /apis/v1/datasets/versions``）。
 
         通常 version 由 ``ingest`` 扫描 OSS 时自动建；本方法用于需要**先建空版本壳**
@@ -232,20 +264,42 @@ class VersionsClient:
           splits       : 可选 split 名列表；缺省由 apiserver 按 storage_path 推导。
           status       : 版本状态，缺省 ``draft``（合法值见 VERSION_STATUS_VALUES）。
           storage_type : 存储类型，缺省 ``oss``（当前仅支持）。
-
-        注意：版本壳恒落 online 集合（apiserver 侧版本/样本直写接口按设计仅支持 online；
-        区域环境 internal-pre/external-pre 只能经 ``ingest`` 的 ``cluster`` 参数写入区域集合）。
-        故本方法不接受 cluster/environment——需要区域环境时直接用 ``ingest(cluster=...)``。
+          environment  : 可选。显式传入时原样下发；缺省时由 storage_env 派生
+            （dev/internal-dev/external-dev→pre，prod→online）。profile 未显式配置
+            storage_env 但配置了 cluster 时，会经 repo-config 解析出绑定的
+            storage_env 再派生（与 ingest 对称）；显式 environment 与派生值冲突时
+            前置拒绝。
 
         run_type 不在建版本时设置（apiserver create 不收该字段）：建好后用
         ``set_run_type`` / ``update`` 打标，或走 ``ingest(run_type=...)``。
         """
         if not version:
             raise SchemaError("version is required")
+        # 与 ingest 对称（问题1 彻底修复）：storage_env 未在 profile 里显式配置时，
+        # 经 repo-config 解析出与 cluster 绑定的 storage_env 再派生 environment；
+        # 同时复用**同一次**响应里的 bucket/prefix 计算 storage_path，避免出现
+        # 「create 落 online、push/ingest 落 pre」的读写环境撕裂。
+        selected_storage_env = ""
+        bound_bucket = bound_prefix = ""
+        if self._p is not None:
+            _, selected_storage_env, bound_bucket, bound_prefix = \
+                self._ingest_selectors(None)
+        env = (environment or "").strip()
+        if not env and self._p is not None:
+            env = (getattr(self._p, "dataset_environment", "") or "").strip()
+        derived_env = dataset_environment_for(selected_storage_env)
+        if env and derived_env and env != derived_env:
+            raise SchemaError(
+                f"environment={env!r} 与 storage_env="
+                f"{selected_storage_env!r} 派生出的 {derived_env!r} 冲突："
+                f"请只提供其中一个，或把 storage_env 改成与目标环境一致的值")
+        if not env:
+            env = derived_env
         if storage_path is None and self._p is not None:
-            bucket = getattr(self._p, "oss_bucket", "") or ""
+            bucket = (getattr(self._p, "oss_bucket", "") or "") or bound_bucket
             if bucket:
-                storage_path = self._layout().ingest_storage_path(
+                storage_path = self._layout(
+                    oss_prefix=bound_prefix or None).ingest_storage_path(
                     bucket, dataset, version)
         if not storage_path or not storage_path.startswith("oss://"):
             raise SchemaError(
@@ -264,6 +318,8 @@ class VersionsClient:
                       "storage_type": storage_type, "status": status}
         if splits:
             body["splits"] = splits
+        if env:
+            body["environment"] = env
         data = self._t.post(
             f"{self._BASE}?dataset_name={quote(dataset, safe='')}", body)
         return DatasetVersion(**_pick(data))

{instance_repo-1.0.7.dev0 → instance_repo-1.0.9}/instance_repo/content.py

@@ -8,11 +8,15 @@ from __future__ import annotations
 
 import gzip
 import hashlib
+import re
 import tarfile
 from pathlib import Path
 
 _EXCLUDE_REL = "environment/image.tar.gz"
 
+# 32 位 hex（无前缀）＝ apiserver ingest 扫描写入的 OSS ETag（简单上传即 md5）。
+_MD5_HEX_RE = re.compile(r"^[0-9a-fA-F]{32}$")
+
 
 def sha256_file(path: str | Path) -> str:
     """流式计算文件 sha-256，返回 'sha256:<hex>'。"""
@@ -23,6 +27,33 @@ def sha256_file(path: str | Path) -> str:
     return "sha256:" + h.hexdigest()
 
 
+def md5_file(path: str | Path) -> str:
+    """流式计算文件 md5，返回 32 位小写 hex。"""
+    h = hashlib.md5()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def verify_file_digest(path: str | Path, expected: str | None) -> bool:
+    """校验本地文件与 manifest ``content_digest`` 一致（两种生产者格式）。
+
+    - SDK push/commit 路径写 ``sha256:<hex>`` → 按 sha256 比对；
+    - apiserver ingest 扫描路径写 OSS ``ETag``（简单上传即 32 位 md5 hex，
+      无前缀）→ 按 md5 比对（对齐服务端契约，避免 pull(verify=True) 误报）。
+    空/缺失 digest（历史资产合并条目）视为跳过校验，返回 True。
+    """
+    if not expected:
+        return True
+    expected = expected.strip().strip('"')
+    if not expected:
+        return True
+    if _MD5_HEX_RE.match(expected):
+        return md5_file(path) == expected.lower()
+    return sha256_file(path) == expected
+
+
 def _normalize(ti: tarfile.TarInfo) -> tarfile.TarInfo:
     """归一化 tar 条目元数据，保证跨时间/机器可复现。"""
     ti.mtime = 0

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

@@ -37,9 +37,13 @@ from .errors import SchemaError
 
 MODEL_VERSION_FIRST = "version_first"
 MODEL_SPLIT_FIRST = "split_first"
+#: ``custom`` 是用户自定义格式的元数据模型：OSS 路径沿用 split_first 约定
+#: （{split}/{id}.json 元数据 + {split}-assets/{id}/ 原样目录资产），SDK 不校验具体
+#: 字段（仅强约束 instance_id），元数据 freeform。
+MODEL_CUSTOM = "custom"
 #: v0.8 起默认 split_first（v0.7.x 行为等价于显式传 version_first）。
 DEFAULT_METADATA_MODEL = MODEL_SPLIT_FIRST
-_MODELS = (MODEL_VERSION_FIRST, MODEL_SPLIT_FIRST)
+_MODELS = (MODEL_VERSION_FIRST, MODEL_SPLIT_FIRST, MODEL_CUSTOM)
 
 # ACR tag 合法字符集与长度（OCI/Docker 约定）：首字符须为字母数字或下划线，
 # 其余可含字母数字、下划线、点、连字符，总长 **< 105**（ACR tag 硬上限 128，
@@ -126,7 +130,9 @@ class Layout:
 
     @property
     def split_first(self) -> bool:
-        return self.model == MODEL_SPLIT_FIRST
+        # custom 沿用 split_first 的路径约定（{split}/{id}.json +
+        # {split}-assets/{id}/ 兄弟目录），故 path 构造上一视同仁。
+        return self.model in (MODEL_SPLIT_FIRST, MODEL_CUSTOM)
 
     # ── 目录基座 ──
     def dataset_root(self, dataset: str) -> str:

{instance_repo-1.0.7.dev0 → instance_repo-1.0.9}/instance_repo/models.py

@@ -246,6 +246,9 @@ class PushResult:
     image_pushed: bool = False
     docker_image: str | None = None
     digests: dict[str, str] = field(default_factory=dict)
+    # register=True 时经 ingest 写库：ingest job 摘要（ingest_id/status/stats）；
+    # register=False（只传 OSS）时为 None。
+    ingest: dict | None = None
 
 
 # ── RolloutReport（质检 report，服务下游 verl 训练；键名对齐 verl 无下划线口径） ──

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

@@ -75,9 +75,11 @@ class Repo:
             metadata_model=normalize_metadata_model(self.profile.metadata_model))
         self.datasets = DatasetsClient(self.transport)
         self.versions = VersionsClient(self.transport, self.profile)
+        # push(register=True) 的上传后写库经 ingest 完成（:commit 端点缺失），
+        # 注入 versions.ingest 作为 ingester 回调。
         self.instances = InstancesClient(
             self.transport, self.profile, self._content, self._image,
-            self._registry)
+            self._registry, ingester=self.versions.ingest)
         self.reports = ReportsClient(self._content, self.profile)
         # 独立镜像能力（v0.8 新增）：push / pull / copy / exists 不再依赖实例目录。
         self.images = ImageClient(self.transport, self.profile, self._image)
@@ -134,8 +136,16 @@ class Repo:
         failed = [r for r in results if isinstance(r, ItemError)]
         job = None
         if ingest and pushed:                 # 仅在有成功上传时才 ingest
-            job = self.versions.ingest(dataset, version, publish=publish,
-                                       **ingest_kwargs)
+            # 透传 split 给 ingest：用户若未通过 ingest_kwargs 显式指定 splits/split，
+            # 且 split 非默认值，则自动透传，避免 ingest 扫描所有 split 目录时
+            # 对未交付的空 split 报 92005（split path has no instance files）。
+            ingest_split_kwargs = {}
+            if "splits" not in ingest_kwargs and "split" not in ingest_kwargs:
+                if split and split != "default":
+                    ingest_split_kwargs["split"] = split
+            job = self.versions.ingest(
+                dataset, version, publish=publish,
+                **ingest_split_kwargs, **ingest_kwargs)
         return {"pushed": pushed, "failed": failed, "ingest": job}
 
     # ── 源到目标交付：上传 → 元数据入库 → 发布 workflow ────────────────────────

{instance_repo-1.0.7.dev0 → instance_repo-1.0.9}/instance_repo/store/oss.py

@@ -16,7 +16,7 @@ from .._routing import (
     _is_reachability_error,
     _plan_oss_route,
 )
-from ..content import sha256_file
+from ..content import sha256_file, verify_file_digest
 from ..errors import DigestMismatch, PrivateNetworkRequired, TransportError
 from ..retry import retry_transient
 from .base import BaseContentStore
@@ -315,12 +315,10 @@ class OssContentStore(BaseContentStore):
             dataset,
             lambda bucket: bucket.get_object_to_file(key, str(dest)),
         )
-        if expected_digest is not None:
-            actual = sha256_file(dest)
-            if actual != expected_digest:
-                raise DigestMismatch(
-                    f"{key}: content digest mismatch "
-                    f"(expected {expected_digest}, got {actual})")
+        if expected_digest is not None and not verify_file_digest(dest, expected_digest):
+            raise DigestMismatch(
+                f"{key}: content digest mismatch "
+                f"(expected {expected_digest}, got {sha256_file(dest)})")
         return dest
 
     def object_exists(self, key: str, *, sts_prefix: str | None = None,
@@ -413,10 +411,8 @@ class OssContentStore(BaseContentStore):
             dataset,
             lambda bucket: bucket.get_object_to_file(tgz_key, str(dest)),
         )
-        if expected_digest is not None:
-            actual = sha256_file(dest)
-            if actual != expected_digest:
-                raise DigestMismatch(
-                    f"{instance_id}: content digest mismatch "
-                    f"(expected {expected_digest}, got {actual})")
+        if expected_digest is not None and not verify_file_digest(dest, expected_digest):
+            raise DigestMismatch(
+                f"{instance_id}: content digest mismatch "
+                f"(expected {expected_digest}, got {sha256_file(dest)})")
         return dest

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

@@ -37,17 +37,15 @@ def _unimplemented(endpoint: str, hint: str):
 
 
 def _q(dataset: str, version: str, split: str | None = None,
-       instance_id: str | None = None) -> str:
+       instance_id: str | None = None, *, keep_default_split: bool = False) -> str:
     # 注意：apiserver 端 datasetNameFromQuery 只认 dataset_name（不是 dataset）；
-    # 用 dataset= 会 404/“dataset_name is required”。此处务必对齐服务端契约。
+    # 用 dataset= 会 404/"dataset_name is required"。此处务必对齐服务端契约。
     parts = [f"dataset_name={quote(dataset, safe='')}",
              f"version={quote(version, safe='')}"]
-    if split and split != "default":
-        # "default"/空串是 SDK 表示"无 split"的哨兵，须与写路径 _version_prefix 的
-        # `split and split != "default"` 判据**对称**：写侧 default→不加 split 段（实例落
-        # {version}/{id}.json，apiserver ingest 派生 split=""）；查侧同样 default→不发 split
-        # 参数，让 apiserver 按"省略 split→跨 split 匹配（含空 split）"命中。否则默认
-        # split="default" 会原样发 split=default，与库里 split="" 不匹配→查不到（实测 0 命中）。
+    if split and (split != "default" or keep_default_split):
+        # version_first / 未声明 metadata_model："default" 是"无 split"的哨兵 → 省略 split
+        # 参数让 apiserver 跨 split 匹配（含空 split）。split_first："default" 是真实 split
+        # 名 → 必须显式下发，否则 apiserver 在 split_first 语义下报 92005 "split is required"。
         parts.append(f"split={quote(split, safe='')}")
     if instance_id:
         parts.append(f"instance_id={quote(instance_id, safe='')}")
@@ -73,7 +71,8 @@ class ApiMetadataRegistry(BaseMetadataRegistry):
         split_first，不显式下发就会用旧语义去查 split-first 数据。environment 为空时
         省略（服务端按 online 缺省，保留未配置 storage_env 的旧行为）。
         """
-        base = _q(dataset, version, split, instance_id)
+        base = _q(dataset, version, split, instance_id,
+                  keep_default_split=(self._metadata_model == "split_first"))
         extra = []
         if self._metadata_model:
             extra.append(f"metadata_model={quote(self._metadata_model, safe='')}")
@@ -99,7 +98,11 @@ class ApiMetadataRegistry(BaseMetadataRegistry):
         据 caller 派生），故不进 body。
         """
         meta.validate()
-        split = "" if meta.split == "default" else (meta.split or "")
+        if self._metadata_model == "split_first":
+            # split_first: "default" 是真实 split 名，不作哨兵归一 → 必须显式下发
+            split = meta.split or ""
+        else:
+            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]

{instance_repo-1.0.7.dev0 → instance_repo-1.0.9}/instance_repo/validate.py

@@ -1,8 +1,10 @@
-"""validate.py — Instance 本地校验（Layout / SWE JSON），纯本地无网络。
+"""validate.py — Instance 本地校验（Layout / SWE JSON / Custom），纯本地无网络。
 
-两种格式自动检测（detect_format）：
-    - harbor（目录）：instruction.md · task.toml · environment/Dockerfile · tests/test.sh|test.ps1
+三种格式自动检测（detect_format）：
+    - harbor（目录 + task.toml）：instruction.md · task.toml · environment/Dockerfile · tests/test.sh|test.ps1
     - swe（单 JSON 文件）：instance_id + docker_image 必备；数据和元数据合一
+    - custom（目录无 task.toml / 单 JSON 文件 freeform）：仅强约束 instance_id；
+      元数据 freeform，push 时目录输入由 SDK 生成最小 JSON、JSON 输入原样上传
 
 测试脚本兼容 Linux（tests/test.sh）与 Windows（tests/test.ps1），二者至少其一。
 """
@@ -50,21 +52,25 @@ def validate_instance_id(instance_id: str, source: str = "") -> None:
 
 # ── 格式检测 ─────────────────────────────────────────────────────────────────
 
-def detect_format(local_path: str | Path) -> Literal["harbor", "swe"]:
-    """自动检测输入格式：目录→harbor，.json 文件→swe。
+def detect_format(local_path: str | Path) -> Literal["harbor", "swe", "custom"]:
+    """自动检测输入格式：
 
-    不做内容校验（那是 check_layout / check_swe_json 的责任），只按路径形态判断。
+    - 目录 + 含 task.toml → harbor
+    - 目录 + 不含 task.toml → custom（用户自定义格式，SDK 不校验具体字段）
+    - .json 文件 → swe
+
+    不做内容校验（那是 check_layout / check_swe_json / check_custom 的责任）。
     """
     p = Path(local_path)
     if p.is_dir():
-        return "harbor"
+        return "harbor" if (p / "task.toml").is_file() else "custom"
     if p.is_file() and p.suffix.lower() == ".json":
         return "swe"
     if not p.exists():
         raise LayoutError(f"path does not exist: {p}")
     raise SchemaError(
         f"unrecognized instance format: {p} "
-        f"(expected a directory for harbor or a .json file for swe)")
+        f"(expected a directory for harbor/custom or a .json file for swe)")
 
 
 # ── Harbor 格式校验 ──────────────────────────────────────────────────────────
@@ -204,3 +210,70 @@ def check_swe_json(json_path: str | Path) -> SWEValidationReport:
     return SWEValidationReport(
         instance_id=instance_id, ok=True, warnings=warnings,
         metadata=metadata, raw_data=data)
+
+
+# ── Custom 格式校验（用户自定义，freeform） ─────────────────────────────────
+
+CUSTOM_SCHEMA_VERSION = "1.0"
+
+
+@dataclass
+class CustomValidationReport:
+    """Custom 格式校验结果。"""
+    instance_id: str
+    format: str = "custom"
+    ok: bool = True
+    metadata: dict = field(default_factory=dict)  # 目录输入时 SDK 生成；JSON 输入时原样解析
+    raw_data: dict = field(default_factory=dict)  # JSON 输入时的原始数据；目录输入时为空
+    source: str = "directory"                     # "directory" 或 "json"
+
+
+def check_custom(local_path: str | Path) -> CustomValidationReport:
+    """校验 custom 格式输入。
+
+    两种输入形态：
+
+    - 目录：``instance_id`` = 目录名（强约束 charset），元数据由 SDK push 时生成
+      （最小 schema：``instance_id`` / ``metadata_model`` / ``schema_version`` /
+      ``created_at`` / ``updated_at``）。
+    - ``.json`` 文件：必须含 ``instance_id`` 字段且与文件名 stem 一致；其余字段
+      freeform，push 时原样上传。
+    """
+    p = Path(local_path)
+    if p.is_dir():
+        instance_id = p.name
+        validate_instance_id(instance_id, source=str(p))
+        return CustomValidationReport(
+            instance_id=instance_id, source="directory")
+    if p.is_file() and p.suffix.lower() == ".json":
+        try:
+            with open(p, "r", encoding="utf-8") as f:
+                data = json.load(f)
+        except UnicodeDecodeError as e:
+            raise SchemaError(
+                f"{p.name}: not valid UTF-8: {e}") from e
+        except json.JSONDecodeError as e:
+            raise SchemaError(f"{p.name}: invalid JSON: {e}") from e
+        if not isinstance(data, dict):
+            raise SchemaError(
+                f"{p.name}: JSON root must be an object, got {type(data).__name__}")
+        raw_id = data.get("instance_id")
+        if not raw_id or (isinstance(raw_id, str) and not raw_id.strip()):
+            raise SchemaError(f"{p.name}: required field 'instance_id' missing or empty")
+        if not isinstance(raw_id, str):
+            raise SchemaError(
+                f"{p.name}: instance_id must be a string, got {type(raw_id).__name__}")
+        instance_id = raw_id.strip()
+        validate_instance_id(instance_id, source=p.name)
+        stem = p.stem
+        if stem != instance_id:
+            raise SchemaError(
+                f"{p.name}: filename stem '{stem}' does not match instance_id "
+                f"'{instance_id}' — file must be named '{instance_id}.json'")
+        return CustomValidationReport(
+            instance_id=instance_id, source="json",
+            metadata=dict(data), raw_data=dict(data))
+    if not p.exists():
+        raise LayoutError(f"path does not exist: {p}")
+    raise SchemaError(
+        f"custom format expects a directory or .json file, got: {p}")

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

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

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

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