instance-repo 0.7.0__tar.gz

instance_repo-0.7.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: instance-repo
+Version: 0.7.0
+Summary: InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: tomli>=1.1.0; python_version < "3.11"
+Provides-Extra: oss
+Requires-Dist: oss2>=2.19; extra == "oss"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: coverage>=7; extra == "dev"
+
+# instance-repo
+
+InstanceRepo Python SDK 与 `irepo` 命令行工具——评测 Instance 的统一存储客户端。
+
+SDK 只负责客户端逻辑；控制面（元数据、鉴权、STS 凭据签发）由 apiserver 承载，数据面
+（OSS 读写、镜像推拉）经 apiserver 下发的临时凭据直连。SDK **不内置**任何 apiserver
+域名、环境名、OSS bucket / endpoint / region、ACR registry / namespace 等基础设施信息，
+这些值一律在运行时由调用方通过环境变量或构造参数注入（见下文“配置”）。
+
+Python SDK 与 Go SDK 功能、错误码、行为逐字对齐。
+
+## 安装
+
+```bash
+pip install instance-repo            # SDK + irepo CLI（Python ≥ 3.10）
+pip install "instance-repo[oss]"     # 需要数据面 OSS 读写时，附带 oss2
+```
+
+镜像推拉依赖外部二进制 `skopeo`；未安装时相关操作会被跳过（`push_image=False` / `--no-image`）。
+
+## 配置
+
+所有基础设施地址在运行时注入，优先级：构造参数 > 环境变量 > 空（用到时才校验并报错）。
+
+控制面：
+
+- `INSTANCEREPO_API_BASE`：apiserver 根地址（必填，无内置默认）
+- `IR_API_ENV`：下发的 `Env` 请求头值，apiserver 据此路由（原样下发，无别名映射）
+- `INSTANCEREPO_TOKEN`：身份 token（`X-API-Key`）
+- `IR_NETWORK`：数据面走 `internal`（默认）还是 `public`（VPC 外须设 `public`）
+
+数据面（按需，仅在真正读写 OSS / 镜像时才需要）：
+
+- `IR_OSS_BUCKET`、`IR_ACR_HOST`、`IR_ACR_NAMESPACE`
+- `IR_OSS_PREFIX`：bucket 内对象目录前缀，协议常量，默认 `swe/datasets`
+- `IR_SCAFFOLD_BUCKET`、`IR_SCAFFOLD_ROOT`：scaffold 包存储位置
+
+`profile` 名仅作标签，不再对应任何内置取值；也可用 `profile_overrides={...}` 传入等价字段。
+
+## 快速开始
+
+```python
+from instance_repo import Repo
+
+repo = Repo()  # 从环境变量读取 api_base / token / 数据面配置
+
+# 控制面元数据操作（不需要数据面配置）
+datasets = repo.datasets.list()
+versions = repo.versions.list("alibaba/mybench")
+state = repo.versions.status("alibaba/mybench", "v1")
+
+# 身份自查：返回当前 token 对应工号，用于拼 user-data 前缀 swe/user-data/users/{uid}/
+uid = repo.whoami()
+
+# 用户输入数据（插件 / 数据合成输入）
+repo.upload_user_data(uid, "plugin.bin", "plugins/plugin.bin")
+keys = repo.list_user_data(uid)
+```
+
+未配置 `INSTANCEREPO_API_BASE` 时，发起控制面请求会抛出明确的 `SchemaError` 引导设置该变量；
+数据面操作在真正用到某字段（如 `oss_bucket`）时才校验，纯控制面操作不受影响。
+
+## CLI
+
+```bash
+irepo --help
+# 子命令：validate / push / pull / list / get / publish / grant / feedback
+#         report / whoami / user-data / create / claim / version
+```
+
+跨环境上架的目标数据面地址通过参数显式提供（SDK 不内置任何桶/仓地址）：
+
+```bash
+irepo publish alibaba/mybench/v1 \
+  --target-bucket <your-oss-bucket> \
+  --target-acr <your-registry-host> --target-acr-namespace <your-namespace>
+```
+
+## 版本与文档
+
+版本号在 `pyproject.toml` / `instance_repo.__version__` / Go `version.go` /
+conformance golden 四处保持一致。各环境的真实配置取值、端到端示例与错误码对照，见团队内部
+部署文档。

instance_repo-0.7.0/README.md

@@ -0,0 +1,83 @@
+# instance-repo
+
+InstanceRepo Python SDK 与 `irepo` 命令行工具——评测 Instance 的统一存储客户端。
+
+SDK 只负责客户端逻辑；控制面（元数据、鉴权、STS 凭据签发）由 apiserver 承载，数据面
+（OSS 读写、镜像推拉）经 apiserver 下发的临时凭据直连。SDK **不内置**任何 apiserver
+域名、环境名、OSS bucket / endpoint / region、ACR registry / namespace 等基础设施信息，
+这些值一律在运行时由调用方通过环境变量或构造参数注入（见下文“配置”）。
+
+Python SDK 与 Go SDK 功能、错误码、行为逐字对齐。
+
+## 安装
+
+```bash
+pip install instance-repo            # SDK + irepo CLI（Python ≥ 3.10）
+pip install "instance-repo[oss]"     # 需要数据面 OSS 读写时，附带 oss2
+```
+
+镜像推拉依赖外部二进制 `skopeo`；未安装时相关操作会被跳过（`push_image=False` / `--no-image`）。
+
+## 配置
+
+所有基础设施地址在运行时注入，优先级：构造参数 > 环境变量 > 空（用到时才校验并报错）。
+
+控制面：
+
+- `INSTANCEREPO_API_BASE`：apiserver 根地址（必填，无内置默认）
+- `IR_API_ENV`：下发的 `Env` 请求头值，apiserver 据此路由（原样下发，无别名映射）
+- `INSTANCEREPO_TOKEN`：身份 token（`X-API-Key`）
+- `IR_NETWORK`：数据面走 `internal`（默认）还是 `public`（VPC 外须设 `public`）
+
+数据面（按需，仅在真正读写 OSS / 镜像时才需要）：
+
+- `IR_OSS_BUCKET`、`IR_ACR_HOST`、`IR_ACR_NAMESPACE`
+- `IR_OSS_PREFIX`：bucket 内对象目录前缀，协议常量，默认 `swe/datasets`
+- `IR_SCAFFOLD_BUCKET`、`IR_SCAFFOLD_ROOT`：scaffold 包存储位置
+
+`profile` 名仅作标签，不再对应任何内置取值；也可用 `profile_overrides={...}` 传入等价字段。
+
+## 快速开始
+
+```python
+from instance_repo import Repo
+
+repo = Repo()  # 从环境变量读取 api_base / token / 数据面配置
+
+# 控制面元数据操作（不需要数据面配置）
+datasets = repo.datasets.list()
+versions = repo.versions.list("alibaba/mybench")
+state = repo.versions.status("alibaba/mybench", "v1")
+
+# 身份自查：返回当前 token 对应工号，用于拼 user-data 前缀 swe/user-data/users/{uid}/
+uid = repo.whoami()
+
+# 用户输入数据（插件 / 数据合成输入）
+repo.upload_user_data(uid, "plugin.bin", "plugins/plugin.bin")
+keys = repo.list_user_data(uid)
+```
+
+未配置 `INSTANCEREPO_API_BASE` 时，发起控制面请求会抛出明确的 `SchemaError` 引导设置该变量；
+数据面操作在真正用到某字段（如 `oss_bucket`）时才校验，纯控制面操作不受影响。
+
+## CLI
+
+```bash
+irepo --help
+# 子命令：validate / push / pull / list / get / publish / grant / feedback
+#         report / whoami / user-data / create / claim / version
+```
+
+跨环境上架的目标数据面地址通过参数显式提供（SDK 不内置任何桶/仓地址）：
+
+```bash
+irepo publish alibaba/mybench/v1 \
+  --target-bucket <your-oss-bucket> \
+  --target-acr <your-registry-host> --target-acr-namespace <your-namespace>
+```
+
+## 版本与文档
+
+版本号在 `pyproject.toml` / `instance_repo.__version__` / Go `version.go` /
+conformance golden 四处保持一致。各环境的真实配置取值、端到端示例与错误码对照，见团队内部
+部署文档。

instance_repo-0.7.0/instance_repo/__init__.py

@@ -0,0 +1,32 @@
+"""instance_repo — 评测 Instance 统一存储 SDK（Python）。
+
+唯一入口：所有 OSS/ACR 操作经 SDK，先向 apiserver 换 STS 再直连。控制面
+（鉴权/元数据/STS/审计/release）全在 apiserver。
+"""
+from .repo import Repo
+from .loader import load_instances
+from .models import (
+    DatasetSeries, DatasetVersion, DatasetInstance, ManifestEntry,
+    OwnerReference, Feedback, Identity, PushResult,
+    RolloutReport, RolloutJob, ScaffoldConfig,
+    canonical_json, parse_feedbacks, append_feedback,
+)
+from .errors import (
+    InstanceRepoError, LayoutError, SchemaError, OwnerRefMissing, ImageMissing,
+    Immutable, DigestMismatch, Forbidden, NotVisible, TargetNotAllowed,
+    NetworkDenied, CredExpired, TransportError,
+)
+
+__version__ = "0.7.0"
+
+__all__ = [
+    "Repo", "load_instances",
+    "DatasetSeries", "DatasetVersion", "DatasetInstance", "ManifestEntry",
+    "OwnerReference", "Feedback", "Identity", "PushResult",
+    "RolloutReport", "RolloutJob", "ScaffoldConfig",
+    "canonical_json", "parse_feedbacks", "append_feedback",
+    "InstanceRepoError", "LayoutError", "SchemaError", "OwnerRefMissing",
+    "ImageMissing", "Immutable", "DigestMismatch", "Forbidden", "NotVisible",
+    "TargetNotAllowed", "NetworkDenied", "CredExpired", "TransportError",
+    "__version__",
+]

instance_repo-0.7.0/instance_repo/cache.py

@@ -0,0 +1,57 @@
+"""cache.py — 线程安全 TTL 缓存（复用 STS 凭据与 oss2 Bucket）。
+
+按 key 缓存 value + 过期 epoch；命中要求 now < expiry - safety。expiry=None 视为不过期。
+STS 凭据按 (resource,bucket,prefix)/(acr,host) 缓存、按签发返回的 Expiration 失效；
+oss2 Bucket 按 (bucket,prefix,security_token) 缓存以复用底层连接池。
+"""
+from __future__ import annotations
+
+import threading
+import time
+from datetime import datetime, timezone
+from typing import Any
+
+
+def parse_expiry(rfc3339: str | None) -> float | None:
+    """RFC3339（如 ``2026-08-06T16:32:26Z``）→ epoch 秒；空/不可解析返回 None。
+
+    无时区信息（naive）的字符串按 UTC 解释，避免被本地时区偏移影响过期判断。
+    """
+    if not rfc3339:
+        return None
+    s = rfc3339.strip().replace("Z", "+00:00")
+    try:
+        dt = datetime.fromisoformat(s)
+    except ValueError:
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.timestamp()
+
+
+class TTLCache:
+    """线程安全 TTL 缓存。"""
+
+    def __init__(self, *, safety: float = 60.0) -> None:
+        self._d: dict[Any, tuple[Any, float | None]] = {}
+        self._lock = threading.Lock()
+        self._safety = safety
+
+    def get(self, key: Any) -> Any | None:
+        with self._lock:
+            item = self._d.get(key)
+            if item is None:
+                return None
+            value, exp = item
+            if exp is not None and time.time() >= exp - self._safety:
+                self._d.pop(key, None)
+                return None
+            return value
+
+    def put(self, key: Any, value: Any, expiry: float | None) -> None:
+        with self._lock:
+            self._d[key] = (value, expiry)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._d.clear()

instance_repo-0.7.0/instance_repo/cli.py

@@ -0,0 +1,401 @@
+"""cli.py — irepo 命令行入口。
+
+子命令：validate / push / list / get / pull / publish / grant / feedback / report /
+create / claim / version。纯参数解析 + 分发到 Repo；便于单测（main(argv, repo=注入)）。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .errors import InstanceRepoError
+from .models import OwnerReference, Feedback, RolloutReport, DatasetSeries
+from .repo import Repo
+
+_STATUS_CHOICES = ["draft", "published", "deprecated", "archived"]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(prog="irepo", description="InstanceRepo CLI")
+    ap.add_argument("--profile", default="default",
+                    help="数据面 profile 标签（仅作标识；OSS bucket / ACR host 等经 "
+                         "IR_OSS_BUCKET / IR_ACR_HOST 等环境变量提供，见部署文档）")
+    ap.add_argument("--api-env", default=None,
+                    help="下发的 Env 请求头值（服务端据此路由；亦可用 IR_API_ENV）；"
+                         "apiserver 根地址用 INSTANCEREPO_API_BASE 提供")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    v = sub.add_parser("validate", help="本地校验 Instance 目录")
+    v.add_argument("dir")
+
+    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("--owner-ref", required=True, help="OwnerReference JSON")
+    p.add_argument("--split", default="default")
+    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 未实现实例写端点时必须用它")
+    p.add_argument("--no-verify", action="store_true",
+                   help="跳过上传后的回读校验（默认校验 OSS 对象/ACR 镜像确已落库）")
+
+    lst = sub.add_parser("list", help="列出 dataset/version 下实例")
+    lst.add_argument("ref", help="{L1}/{L2}/{version}")
+    lst.add_argument("--split", default=None,
+                     help="按 split 过滤；缺省为跨 split 检索")
+
+    pl = sub.add_parser("pull", help="拉取并解包（digest 校验）")
+    pl.add_argument("ref", help="{L1}/{L2}/{version}/{id}")
+    pl.add_argument("-o", "--out", default="./work")
+    pl.add_argument("--split", default="default",
+                    help="实例所在 split（写入时用了非默认 split 就必须带上）")
+
+    pub = sub.add_parser("publish", help="上架到生产（benchmark-release）")
+    pub.add_argument("ref", help="{L1}/{L2}/{version}")
+    pub.add_argument("--instances", default=None,
+                     help="逗号分隔的 KEEP 实例 id；granularity=instance 或 images=on 时必填")
+    pub.add_argument("--target", default="", help="目标 profile 标签（仅作标识）")
+    pub.add_argument("--target-bucket", default=None,
+                     help="目标 OSS bucket（跨环境上架必填；SDK 不内置任何桶地址）")
+    pub.add_argument("--target-acr", default=None, help="目标 ACR host（images=on 时用）")
+    pub.add_argument("--target-acr-namespace", default=None, help="目标 ACR namespace")
+    pub.add_argument("--granularity", choices=["dataset", "instance"], default="dataset")
+    pub.add_argument("--images", choices=["off", "on"], default="off")
+    pub.add_argument("--overwrite", action="store_true")
+    pub.add_argument("--wait-approval", action="store_true", help="等待人工审批直到终态")
+    pub.add_argument("--description", default="")
+    pub.add_argument("--request-json", default=None,
+                     help="逃生舱：直接透传 workflow 请求体 JSON 文件（给定时忽略上面 typed 参数）")
+
+    g = sub.add_parser("grant", help="授权")
+    g.add_argument("dataset")
+    g.add_argument("--user", required=True)
+    g.add_argument("--role", required=True)
+
+    fb = sub.add_parser("feedback", help="回写反馈（append）")
+    fb.add_argument("ref", help="{L1}/{L2}/{version}/{id}")
+    fb.add_argument("--type", required=True)
+    fb.add_argument("--id", required=True)
+    fb.add_argument("--score", type=float, required=True)
+    fb.add_argument("--message", default="")
+
+    rp = sub.add_parser("report", help="质检 report 存取（OSS）")
+    rp.add_argument("action", choices=["get", "put", "assemble"])
+    rp.add_argument("ref", help="get/put: {L1}/{L2}/{version}/{id}；assemble: {L1}/{L2}/{version}")
+    rp.add_argument("--file", default=None, help="put: 输入 report.jsonl；get: 输出(缺省打印)；assemble: 输出 jsonl")
+    rp.add_argument("--instances", default=None, help="assemble: 逗号分隔的实例 id")
+    rp.add_argument("--overwrite", action="store_true")
+
+    sub.add_parser("whoami", help="打印当前 apikey 对应的工号(user_id)")
+
+    ud = sub.add_parser("user-data", help="用户输入数据(插件/合成输入) put/get/ls")
+    ud.add_argument("action", choices=["put", "get", "ls"])
+    ud.add_argument("pos", nargs="*",
+                    help="put: <local> <remote>；get: <remote> <local>；ls: [subpath]")
+    ud.add_argument("--uid", default=None,
+                    help="目标 uid（缺省=自己 whoami；系统白名单读他人时指定）")
+    ud.add_argument("--overwrite", action="store_true", help="put 时覆盖已存在对象")
+
+    cr = sub.add_parser("create", help="创建 DatasetSeries")
+    cr.add_argument("dataset", help="{L1}/{L2}")
+    cr.add_argument("--benchmark-id", default=None,
+                    help="绑定的 benchmark source_id（默认必填；apiserver 据它派生 teacher）")
+    cr.add_argument("--visibility", choices=["public", "private"], default="private")
+    cr.add_argument("--display-name", default=None)
+    cr.add_argument("--description", default=None)
+    cr.add_argument("--default-scaffold", default=None)
+    cr.add_argument("--owner", default=None, help="归属人工号（缺省取调用方）")
+    cr.add_argument("--owner-team-id", default=None)
+    cr.add_argument("--workspace-id", default=None, help="归属 workspace/queue（可选）")
+    cr.add_argument("--no-require-benchmark", action="store_true",
+                    help="跳过 benchmark_id 本地必填校验（仅服务端关掉强制绑定时用）")
+
+    cl = sub.add_parser("claim", help="认领 dataset（成为 admin）")
+    cl.add_argument("dataset_id", help="dataset 业务 ID（ds- 前缀）")
+    cl.add_argument("--workspace-id", required=True, help="归属 workspace/queue ID")
+    cl.add_argument("--benchmark-id", default=None,
+                    help="绑定的 benchmark source_id（默认必填；apiserver 据它派生 teacher）")
+    cl.add_argument("--owner", default=None,
+                    help="归属人工号（缺省取调用方；已有非空 owner 不会被覆盖）")
+    cl.add_argument("--no-require-benchmark", action="store_true",
+                    help="跳过 benchmark_id 本地必填校验（仅服务端关掉强制绑定时用）")
+
+    gt = sub.add_parser("get", help="取单个实例元数据")
+    gt.add_argument("ref", help="{L1}/{L2}/{version}/{id}")
+    gt.add_argument("--split", default=None,
+                    help="实例所在 split；缺省为跨 split 检索")
+
+    ver = sub.add_parser("version", help="版本管理（create/list/status/update/set-run-type）")
+    ver.add_argument("action",
+                     choices=["create", "list", "status", "update", "set-run-type"])
+    ver.add_argument("ref",
+                     help="create/list: {L1}/{L2}；"
+                          "status/update/set-run-type: {L1}/{L2}/{version}")
+    ver.add_argument("--version", default=None, help="create 用：版本号")
+    ver.add_argument("--storage-path", default=None,
+                     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("--status", choices=_STATUS_CHOICES, default=None,
+                     help="update 用：版本状态流转")
+    ver.add_argument("--run-type", choices=["train", "eval"], default=None,
+                     help="version 级用途标签")
+    ver.add_argument("--split-run-types", default=None,
+                     help="split 级打标，格式 name=train,name2=eval（与 --run-type 互斥）")
+    return ap
+
+
+def _split_ref(ref: str, parts: int) -> list[str]:
+    segs = ref.split("/")
+    if len(segs) != parts:
+        raise SystemExit(f"ref must have {parts} segments, got {ref!r}")
+    return segs
+
+
+def _parse_split_run_types(s: str) -> list[dict]:
+    """解析 CLI 的 ``name=train,name2=eval`` 格式为 [{name, run_type}] 列表。
+
+    run_type 合法性交由 SDK versions.update 校验（会列出合法值）。"""
+    out: list[dict] = []
+    for pair in s.split(","):
+        pair = pair.strip()
+        if not pair:
+            continue
+        if "=" not in pair:
+            raise SystemExit(
+                f"--split-run-types 每项须为 name=run_type，got {pair!r}")
+        name, rt = pair.split("=", 1)
+        out.append({"name": name.strip(), "run_type": rt.strip()})
+    return out
+
+
+def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
+    args = build_parser().parse_args(argv)
+    out = out or sys.stdout
+    r = repo or Repo(profile=args.profile, api_env=getattr(args, "api_env", None))
+
+    if args.cmd == "validate":
+        rep = r.instances.validate(args.dir)
+        print(f"OK {rep.instance_id} (metadata keys: {sorted(rep.metadata)})", file=out)
+        return 0
+
+    if args.cmd == "push":
+        owner = OwnerReference.from_json(args.owner_ref)
+        res = r.instances.push(args.dir, args.dataset, args.version,
+                               owner_reference=owner, split=args.split,
+                               push_image=not args.no_image,
+                               overwrite=args.overwrite,
+                               register=not args.no_register,
+                               verify=not args.no_verify)
+        print(f"{res.instance_id} uploaded={res.uploaded} "
+              f"image_pushed={res.image_pushed}", file=out)
+        return 0
+
+    if args.cmd == "list":
+        l1, l2, version = _split_ref(args.ref, 3)
+        for inst in r.instances.list(f"{l1}/{l2}", version, args.split):
+            print(f"{inst.instance_id}\t{inst.difficulty}\t{inst.docker_image}", file=out)
+        return 0
+
+    if args.cmd == "pull":
+        l1, l2, version, iid = _split_ref(args.ref, 4)
+        path = r.instances.pull(f"{l1}/{l2}", version, iid, args.out,
+                                split=args.split)
+        print(str(path), file=out)
+        return 0
+
+    if args.cmd == "publish":
+        l1, l2, version = _split_ref(args.ref, 3)
+        if args.request_json:
+            with open(args.request_json, encoding="utf-8") as f:
+                body = json.load(f)
+            wf = r.versions.publish(f"{l1}/{l2}", version, request_body=body,
+                                    wait_approval=args.wait_approval)
+        else:
+            insts = ([s.strip() for s in args.instances.split(",") if s.strip()]
+                     if args.instances else None)
+            # 目标数据面配置由 CLI 显式提供（SDK 不内置任何环境的桶/仓地址）。
+            tgt_ovr = {}
+            if args.target_bucket:
+                tgt_ovr["oss_bucket"] = args.target_bucket
+            if args.target_acr:
+                tgt_ovr["acr_host"] = args.target_acr
+            if args.target_acr_namespace:
+                tgt_ovr["acr_namespace"] = args.target_acr_namespace
+            wf = r.versions.publish(
+                f"{l1}/{l2}", version, 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,
+                description=args.description)
+        print(f"workflow {wf.get('id','')} status={wf.get('status','')}", file=out)
+        return 0
+
+    if args.cmd == "whoami":
+        print(r.whoami(), file=out)
+        return 0
+
+    if args.cmd == "user-data":
+        uid = args.uid or r.whoami()
+        if args.action == "put":
+            if len(args.pos) < 2:
+                raise SystemExit("user-data put 需要 <local> <remote>")
+            res = r.upload_user_data(uid, args.pos[0], args.pos[1],
+                                     overwrite=args.overwrite)
+            tag = "skipped (exists): " if res.get("skipped") else "put: "
+            print(tag + res.get("key", ""), file=out)
+            return 0
+        if args.action == "get":
+            if len(args.pos) < 2:
+                raise SystemExit("user-data get 需要 <remote> <local>")
+            path = r.download_user_data(uid, args.pos[0], args.pos[1])
+            print(f"got: {path}", file=out)
+            return 0
+        # ls
+        subpath = args.pos[0] if args.pos else ""
+        for k in r.list_user_data(uid, subpath):
+            print(k, file=out)
+        return 0
+
+    if args.cmd == "grant":
+        r.datasets.grant(args.dataset, args.user, args.role)
+        print(f"granted {args.role} to {args.user} on {args.dataset}", file=out)
+        return 0
+
+    if args.cmd == "report":
+        if args.action == "assemble":
+            l1, l2, version = _split_ref(args.ref, 3)
+            insts = [s.strip() for s in (args.instances or "").split(",") if s.strip()]
+            dest = args.file or "train.jsonl"
+            path = r.reports.assemble_jsonl(f"{l1}/{l2}", version, insts, dest)
+            print(str(path), file=out)
+            return 0
+        l1, l2, version, iid = _split_ref(args.ref, 4)
+        if args.action == "put":
+            with open(args.file, encoding="utf-8") as f:
+                rpt = RolloutReport.from_jsonl_line(f.read().strip())
+            # ref 与 report 内容必须一致，否则会把 report 写到与 ref 不符的 key（静默错位）
+            if rpt.datasetname != f"{l1}/{l2}" or rpt.instanceid != iid:
+                raise SystemExit(
+                    f"ref {args.ref} 与 report 内容不一致 "
+                    f"(report={rpt.datasetname}/{rpt.instanceid})")
+            r.reports.put(rpt, version, overwrite=args.overwrite)
+            print(f"report put {rpt.instanceid}", file=out)
+            return 0
+        # get
+        rpt = r.reports.get(f"{l1}/{l2}", version, iid)
+        line = rpt.to_jsonl_line()
+        if args.file:
+            with open(args.file, "w", encoding="utf-8") as f:
+                f.write(line + "\n")
+            print(str(args.file), file=out)
+        else:
+            print(line, file=out)
+        return 0
+
+    if args.cmd == "feedback":
+        l1, l2, version, iid = _split_ref(args.ref, 4)
+        fb = Feedback(type=args.type, id=args.id, score=args.score, message=args.message)
+        r.instances.add_feedback(f"{l1}/{l2}", version, iid, fb)
+        print(f"feedback appended to {iid}", file=out)
+        return 0
+
+    if args.cmd == "create":
+        l1, l2 = _split_ref(args.dataset, 2)
+        # teacher 由 apiserver 从 benchmark 派生，CLI 不再提供 teacher 参数。
+        series = DatasetSeries(
+            dataset_name=args.dataset, dataset_l1=l1, dataset_l2=l2,
+            benchmark_id=args.benchmark_id,
+            visibility=args.visibility,
+            display_name=args.display_name,
+            description=args.description,
+            default_scaffold=args.default_scaffold,
+            owner=args.owner,
+            owner_team_id=args.owner_team_id,
+            workspace_id=args.workspace_id)
+        created = r.datasets.create(
+            series, require_benchmark=not args.no_require_benchmark)
+        print(f"created {created.dataset_name} (dataset_id={created.dataset_id})",
+              file=out)
+        return 0
+
+    if args.cmd == "claim":
+        res = r.datasets.claim(
+            args.dataset_id, args.workspace_id, args.benchmark_id or "",
+            owner=args.owner,
+            require_benchmark=not args.no_require_benchmark)
+        print(f"claimed {res.get('dataset_id', args.dataset_id)} "
+              f"by {res.get('user_id', '')}", file=out)
+        return 0
+
+    if args.cmd == "get":
+        l1, l2, version, iid = _split_ref(args.ref, 4)
+        inst = r.instances.get(f"{l1}/{l2}", version, iid, args.split)
+        # 实例不存在时库层返回 None（apiserver 92003），显式区分"查不到"与"字段为空"。
+        if inst is None:
+            raise SystemExit(f"instance {args.ref} not found")
+        print(f"{inst.instance_id}\t{inst.difficulty}\t{inst.docker_image}", file=out)
+        return 0
+
+    if args.cmd == "version":
+        srt = (_parse_split_run_types(args.split_run_types)
+               if args.split_run_types else None)
+        if args.action in ("create", "list"):
+            l1, l2 = _split_ref(args.ref, 2)
+            dataset = f"{l1}/{l2}"
+            if args.action == "list":
+                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")
+            splits = ([s.strip() for s in args.splits.split(",") if s.strip()]
+                      if args.splits else None)
+            dv = r.versions.create(dataset, args.version,
+                                   storage_path=args.storage_path, splits=splits,
+                                   status=args.status or "draft",
+                                   storage_type=args.storage_type)
+            print(f"created version {dv.dataset}/{dv.version} status={dv.status}",
+                  file=out)
+            return 0
+        l1, l2, version = _split_ref(args.ref, 3)
+        dataset = f"{l1}/{l2}"
+        if args.action == "status":
+            print(r.versions.status(dataset, version), file=out)
+            return 0
+        if args.action == "set-run-type":
+            r.versions.set_run_type(dataset, version,
+                                    run_type=args.run_type, split_run_types=srt)
+            print(f"run_type set on {dataset}/{version}", file=out)
+            return 0
+        # update
+        splits = ([s.strip() for s in args.splits.split(",") if s.strip()]
+                  if args.splits else None)
+        r.versions.update(dataset, version, status=args.status,
+                          splits=splits, run_type=args.run_type,
+                          split_run_types=srt)
+        print(f"updated {dataset}/{version}", file=out)
+        return 0
+
+    return 2  # pragma: no cover - argparse 已保证 cmd 合法
+
+
+def cli_main(argv=None) -> int:
+    """入口包装：把 SDK 异常收敛成单行报错，不向用户抛 Python traceback。
+
+    与 Go CLI 的 ``irepo: error: …`` 输出对齐。``main()`` 保持原样抛异常，
+    便于单测直接断言异常类型。
+    """
+    try:
+        return main(argv)
+    except InstanceRepoError as e:
+        print(f"irepo: error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(cli_main())