instance-repo 0.7.0__py3-none-any.whl

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/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/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())

instance_repo/clients/__init__.py

@@ -0,0 +1,8 @@
+"""clients — 三资源客户端 + config。"""
+from .config import Profile, load_profile
+from .datasets import DatasetsClient
+from .versions import VersionsClient
+from .instances import InstancesClient
+
+__all__ = ["Profile", "load_profile", "DatasetsClient", "VersionsClient",
+           "InstancesClient"]

instance_repo/clients/config.py

@@ -0,0 +1,103 @@
+"""clients/config.py — 运行时配置解析（**不内置任何环境/桶/域名等业务信息**）。
+
+设计原则（对外发布安全）：SDK 源码里**不硬编码**任何 apiserver 域名、环境名、OSS
+bucket、OSS endpoint、region、ACR registry / namespace 等基础设施信息。这些值一律由
+调用方在运行时提供，来源与优先级（高→低）：
+
+* 构造参数 ``profile_overrides`` / ``api_base`` / ``api_env``；
+* 环境变量（见下）；
+* 缺省为空——真正用到某字段时才校验并给出明确报错，引导查阅部署文档。
+
+两件**正交**的事分开表达：
+
+* ``profile`` 决定**数据面**落在哪：OSS bucket、ACR host/namespace、oss_prefix、
+  scaffold 桶等。``profile`` 名仅作标签，**不再对应任何内置取值**。
+* ``api_base`` / ``api_env`` 决定**控制面**：连哪个 apiserver、下发的 ``Env`` 头值。
+
+长期 AK 不落配置（数据面凭证一律由 apiserver 签发 STS）。各环境的真实取值请见
+部署文档（SDK 使用指南的“环境配置”一节），按需填入环境变量或 ``profile_overrides``。
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+# ── 控制面 ──
+ENV_API_BASE = "INSTANCEREPO_API_BASE"   # apiserver 根地址（必填，无内置默认）
+ENV_API_ENV = "IR_API_ENV"               # Env 请求头值（apiserver 据此路由；原样下发）
+
+# ── 数据面 profile 字段（均无内置默认，按需由环境变量/overrides 提供）──
+ENV_OSS_BUCKET = "IR_OSS_BUCKET"
+ENV_ACR_HOST = "IR_ACR_HOST"
+ENV_ACR_NAMESPACE = "IR_ACR_NAMESPACE"
+ENV_OSS_PREFIX = "IR_OSS_PREFIX"
+ENV_SCAFFOLD_BUCKET = "IR_SCAFFOLD_BUCKET"
+ENV_SCAFFOLD_ROOT = "IR_SCAFFOLD_ROOT"
+
+# oss_prefix 是 **bucket 内的对象目录布局约定**（与 apiserver 契约强绑定），不暴露
+# 任何基础设施位置信息，作为协议常量保留默认值；可用 IR_OSS_PREFIX / overrides 覆盖。
+DEFAULT_OSS_PREFIX = "swe/datasets"
+
+
+def normalize_api_env(env: str) -> str:
+    """规范化 Env 头取值：仅去空白、转小写。
+
+    **不做任何具名别名映射**（不内置任何具体环境名）；调用方须传服务端实际认的环境
+    标识，SDK 原样下发。
+    """
+    return (env or "").strip().lower()
+
+
+@dataclass
+class Profile:
+    name: str
+    oss_bucket: str = ""
+    acr_host: str = ""
+    acr_namespace: str = ""
+    oss_prefix: str = DEFAULT_OSS_PREFIX
+    scaffold_bucket: str = ""
+    scaffold_root: str = ""
+    api_base: str = ""
+    api_env: str = ""
+
+
+def resolve_api_base(api_env: str | None = None) -> tuple[str, str]:
+    """解析控制面，返回 ``(api_base, api_env)``。
+
+    ``api_base`` 只能来自 ``INSTANCEREPO_API_BASE``（无内置域名表）；未提供则返回空串，
+    真正发控制面请求时由 Transport 报错引导。``api_env`` 为下发的 ``Env`` 头值，来自
+    显式参数或 ``IR_API_ENV``，原样（规范化大小写后）返回。
+    """
+    base = (os.environ.get(ENV_API_BASE) or "").rstrip("/")
+    env = normalize_api_env(api_env or os.environ.get(ENV_API_ENV) or "")
+    return base, env
+
+
+def load_profile(name: str = "default", *, overrides: dict | None = None,
+                 api_env: str | None = None) -> Profile:
+    """组装运行时 Profile。``name`` 仅作标签，**不查任何内置取值**。
+
+    数据面字段来源优先级：``overrides`` > 环境变量 > 空。控制面 ``api_base`` 来自
+    ``INSTANCEREPO_API_BASE``，``api_env``（Env 头）来自参数或 ``IR_API_ENV``。
+    关键字段（如 oss_bucket / acr_host）允许为空——仅在对应数据面操作真正用到时才校验，
+    纯控制面元数据操作（list/get/create/claim）不需要它们。
+    """
+    base, env = resolve_api_base(api_env)
+    cfg = {
+        "oss_bucket": os.environ.get(ENV_OSS_BUCKET, ""),
+        "acr_host": os.environ.get(ENV_ACR_HOST, ""),
+        "acr_namespace": os.environ.get(ENV_ACR_NAMESPACE, ""),
+        "oss_prefix": os.environ.get(ENV_OSS_PREFIX) or DEFAULT_OSS_PREFIX,
+        "scaffold_bucket": os.environ.get(ENV_SCAFFOLD_BUCKET, ""),
+        "scaffold_root": os.environ.get(ENV_SCAFFOLD_ROOT, ""),
+        "api_base": base,
+    }
+    if overrides:
+        # 只接受已知字段，避免把 api_env 之类误当数据面字段
+        for k in ("oss_bucket", "acr_host", "acr_namespace", "oss_prefix",
+                  "scaffold_bucket", "scaffold_root", "api_base"):
+            if k in overrides and overrides[k] is not None:
+                cfg[k] = overrides[k]
+    if cfg["api_base"]:
+        cfg["api_base"] = str(cfg["api_base"]).rstrip("/")
+    return Profile(name=name, api_env=env, **cfg)