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 功能、错误码、行为逐字对齐。

安装

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={...} 传入等价字段。

快速开始

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

irepo --help
# 子命令：validate / push / pull / list / get / publish / grant / feedback
#         report / whoami / user-data / create / claim / version

跨环境上架的目标数据面地址通过参数显式提供（SDK 不内置任何桶/仓地址）：

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 四处保持一致。各环境的真实配置取值、端到端示例与错误码对照，见团队内部 部署文档。