instance-repo 1.1.4__tar.gz → 1.3.0.dev0__tar.gz

{instance_repo-1.1.4 → instance_repo-1.3.0.dev0}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.4
 Name: instance-repo
-Version: 1.1.4
+Version: 1.3.0.dev0
 Summary: InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
+Requires-Dist: irepo-artifact<0.2.0,>=0.1.1
 Requires-Dist: tomli>=1.1.0; python_version < "3.11"
 Provides-Extra: oss
 Requires-Dist: oss2>=2.19; extra == "oss"
@@ -81,8 +82,9 @@ pip install "instance-repo[oss]"     # 需要数据面 OSS 读写时，附带 os
 不是 default）。旧数据集显式传 `Repo(metadata_model="version_first")`，其对象布局与镜像 tag
 **逐字节不变**，存量数据无需迁移。
 
-服务端把空 `metadata_model` 归一为 `version_first`，因此 SDK 每次请求都显式下发该字段——
-不声明就会静默退回旧模型。
+服务端把空 `metadata_model` 归一为 `version_first`。数据面与读路径仍按 profile 的模型工作；
+但 `repo.versions.create(...)` 的 `metadata_model` 仅在调用方显式传入非空值时下发，不从
+profile 自动注入。显式 `split_first` 仍由服务端拒绝；创建 split 应使用 `repo.splits.create(...)`。
 
 | | `split_first`（默认） | `version_first`（旧） |
 | --- | --- | --- |
@@ -96,6 +98,29 @@ pip install "instance-repo[oss]"     # 需要数据面 OSS 读写时，附带 os
 92005 ambiguous。显式给 splits 时服务端只列举 `{split}/` 与 `{split}-assets/`，推断被完全绕过。
 确需推断时传 `allow_layout_inference=True`。
 
+## Split 创建
+
+`repo.splits.create(dataset, split, *, version=None, run_type=None, storage_path=None,
+environment=None)` 直接调用 `POST /apis/v1/datasets/splits`，body 固定为
+`{"splits":["<split>"]}`。`version` 可选；省略即创建 unversioned split，query 中不会发送
+`version=`。存储路径由服务端根据 dataset/version/split 推导。
+
+`storage_path` 只为 1.2.1 调用兼容保留（计划 1.3.0 删除）：空值允许，非空值在网络请求前抛
+`SchemaError`。提供 `run_type` 时，创建后通过 `PATCH /apis/v1/datasets/splits/detail` 更新，
+不会调用 Version PATCH；最后 GET 读回权威 Split 记录。
+
+```python
+repo.splits.create("alibaba/mybench", "test")
+repo.splits.create("alibaba/mybench", "test", version="v1", run_type="eval")
+```
+
+对应 CLI 的 `--version` 也是可选项；`--storage-path` 仅兼容旧脚本，非空值会失败：
+
+```bash
+irepo split create alibaba/mybench/test --run-type eval
+irepo split create alibaba/mybench/test --version v1
+```
+
 ## 独立镜像能力（`repo.images`，0.8 新增）
 
 ```python
@@ -152,7 +177,8 @@ irepo --help
 # 20 个子命令：validate / push / push-many / deliver / pull / list / get
 #              publish / grant / feedback / report / whoami / user-data
 #              repo-config / create / claim / version / image
-#              split（list/get/set-run-type）/ dataset（list/get/update/access/revoke/benchmarks/workflows）
+#              split（list/get/create/set-run-type；create 的 --version 可选，--storage-path 非空即拒绝）
+#              dataset（list/get/update/access/revoke/benchmarks/workflows）
 irepo image ref --dataset alibaba/mybench --instance-id inst-1 --split test
 irepo image pull '<acr>/<ns>/mybench:test-inst-1' ./out.tar
 ```
@@ -175,3 +201,36 @@ irepo publish alibaba/mybench/v1 --split test \
 版本号在 `pyproject.toml` / `instance_repo.__version__` / Go `version.go` /
 conformance golden 四处保持一致。各环境的真实配置取值、端到端示例与错误码对照，见团队内部
 部署文档。
+
+## 产物下载改造（开发版）
+
+产物下载现在委托独立 `irepo-artifact` 包，通过 AP 签发的 HTTP 链接下载，
+不再要求 OSS SDK、STS 或 artifact bucket/prefix 配置；其他存储功能的 OSS 依赖不变。
+本地开发需同时安装两个包：
+
+```bash
+python -m pip install -e ./sdk/python-artifact -e ./sdk/python
+```
+
+保留 `irepo artifact download`、`download-many`、`download-group`。三个命令均支持
+`--include-files`、`--exclude-files`（可重复、可逗号分隔）和 `--extract`。
+
+```bash
+irepo artifact download --job-id job-a --output-dir out/job-a
+irepo artifact download-many --job-ids job-a,job-b --output-dir out --extract
+irepo artifact download-group --group-id group-a --output-dir out \
+  --include-files logs,result.json --exclude-files debug.log,tmp
+```
+
+默认不解压；`--extract` 与文件筛选冲突。筛选通过 manifest 得到最终文件列表，再向 AP 获取
+各文件 URL。不开启筛选时优先 OSS，网络不可达或中断时回退 dataplane。
+
+**路径迁移：** 单 Job 的输出目录就是 Job 目录，包为 `<output_dir>/result.tgz`；
+批量／Group 为 `<output_dir>/jobs/<job_id>/result.tgz`。解压或筛选内容位于 Job 目录的
+`artifacts/output/`。旧 `<job_id>.tgz` 文件名统一为 `result.tgz`，旧脚本应使用 SDK 返回路径。
+旧 SDK 单 Job 仍返回字符串，批量仍返回路径或异常字典；旧入口维持覆盖意图，新独立客户端
+默认拒绝覆盖。请勿在旧目录尚有需保留文件时直接覆盖迁移。
+
+权限由 AP artifact 接口统一校验，SDK 不再执行 Job 详情预检查。
+更多行为与安装说明见 [独立包 README](../python-artifact/README.md)。
+独立包尚为开发版本，正式发布完整 SDK 前必须先发布可安装的独立包版本。

{instance_repo-1.1.4 → instance_repo-1.3.0.dev0}/README.md

@@ -68,8 +68,9 @@ pip install "instance-repo[oss]"     # 需要数据面 OSS 读写时，附带 os
 不是 default）。旧数据集显式传 `Repo(metadata_model="version_first")`，其对象布局与镜像 tag
 **逐字节不变**，存量数据无需迁移。
 
-服务端把空 `metadata_model` 归一为 `version_first`，因此 SDK 每次请求都显式下发该字段——
-不声明就会静默退回旧模型。
+服务端把空 `metadata_model` 归一为 `version_first`。数据面与读路径仍按 profile 的模型工作；
+但 `repo.versions.create(...)` 的 `metadata_model` 仅在调用方显式传入非空值时下发，不从
+profile 自动注入。显式 `split_first` 仍由服务端拒绝；创建 split 应使用 `repo.splits.create(...)`。
 
 | | `split_first`（默认） | `version_first`（旧） |
 | --- | --- | --- |
@@ -83,6 +84,29 @@ pip install "instance-repo[oss]"     # 需要数据面 OSS 读写时，附带 os
 92005 ambiguous。显式给 splits 时服务端只列举 `{split}/` 与 `{split}-assets/`，推断被完全绕过。
 确需推断时传 `allow_layout_inference=True`。
 
+## Split 创建
+
+`repo.splits.create(dataset, split, *, version=None, run_type=None, storage_path=None,
+environment=None)` 直接调用 `POST /apis/v1/datasets/splits`，body 固定为
+`{"splits":["<split>"]}`。`version` 可选；省略即创建 unversioned split，query 中不会发送
+`version=`。存储路径由服务端根据 dataset/version/split 推导。
+
+`storage_path` 只为 1.2.1 调用兼容保留（计划 1.3.0 删除）：空值允许，非空值在网络请求前抛
+`SchemaError`。提供 `run_type` 时，创建后通过 `PATCH /apis/v1/datasets/splits/detail` 更新，
+不会调用 Version PATCH；最后 GET 读回权威 Split 记录。
+
+```python
+repo.splits.create("alibaba/mybench", "test")
+repo.splits.create("alibaba/mybench", "test", version="v1", run_type="eval")
+```
+
+对应 CLI 的 `--version` 也是可选项；`--storage-path` 仅兼容旧脚本，非空值会失败：
+
+```bash
+irepo split create alibaba/mybench/test --run-type eval
+irepo split create alibaba/mybench/test --version v1
+```
+
 ## 独立镜像能力（`repo.images`，0.8 新增）
 
 ```python
@@ -139,7 +163,8 @@ irepo --help
 # 20 个子命令：validate / push / push-many / deliver / pull / list / get
 #              publish / grant / feedback / report / whoami / user-data
 #              repo-config / create / claim / version / image
-#              split（list/get/set-run-type）/ dataset（list/get/update/access/revoke/benchmarks/workflows）
+#              split（list/get/create/set-run-type；create 的 --version 可选，--storage-path 非空即拒绝）
+#              dataset（list/get/update/access/revoke/benchmarks/workflows）
 irepo image ref --dataset alibaba/mybench --instance-id inst-1 --split test
 irepo image pull '<acr>/<ns>/mybench:test-inst-1' ./out.tar
 ```
@@ -162,3 +187,36 @@ irepo publish alibaba/mybench/v1 --split test \
 版本号在 `pyproject.toml` / `instance_repo.__version__` / Go `version.go` /
 conformance golden 四处保持一致。各环境的真实配置取值、端到端示例与错误码对照，见团队内部
 部署文档。
+
+## 产物下载改造（开发版）
+
+产物下载现在委托独立 `irepo-artifact` 包，通过 AP 签发的 HTTP 链接下载，
+不再要求 OSS SDK、STS 或 artifact bucket/prefix 配置；其他存储功能的 OSS 依赖不变。
+本地开发需同时安装两个包：
+
+```bash
+python -m pip install -e ./sdk/python-artifact -e ./sdk/python
+```
+
+保留 `irepo artifact download`、`download-many`、`download-group`。三个命令均支持
+`--include-files`、`--exclude-files`（可重复、可逗号分隔）和 `--extract`。
+
+```bash
+irepo artifact download --job-id job-a --output-dir out/job-a
+irepo artifact download-many --job-ids job-a,job-b --output-dir out --extract
+irepo artifact download-group --group-id group-a --output-dir out \
+  --include-files logs,result.json --exclude-files debug.log,tmp
+```
+
+默认不解压；`--extract` 与文件筛选冲突。筛选通过 manifest 得到最终文件列表，再向 AP 获取
+各文件 URL。不开启筛选时优先 OSS，网络不可达或中断时回退 dataplane。
+
+**路径迁移：** 单 Job 的输出目录就是 Job 目录，包为 `<output_dir>/result.tgz`；
+批量／Group 为 `<output_dir>/jobs/<job_id>/result.tgz`。解压或筛选内容位于 Job 目录的
+`artifacts/output/`。旧 `<job_id>.tgz` 文件名统一为 `result.tgz`，旧脚本应使用 SDK 返回路径。
+旧 SDK 单 Job 仍返回字符串，批量仍返回路径或异常字典；旧入口维持覆盖意图，新独立客户端
+默认拒绝覆盖。请勿在旧目录尚有需保留文件时直接覆盖迁移。
+
+权限由 AP artifact 接口统一校验，SDK 不再执行 Job 详情预检查。
+更多行为与安装说明见 [独立包 README](../python-artifact/README.md)。
+独立包尚为开发版本，正式发布完整 SDK 前必须先发布可安装的独立包版本。

{instance_repo-1.1.4 → instance_repo-1.3.0.dev0}/instance_repo/__init__.py

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

{instance_repo-1.1.4 → instance_repo-1.3.0.dev0}/instance_repo/artifacts.py

@@ -1,19 +1,16 @@
-"""artifacts.py — AP job artifact 下载（STS 直连 OSS，绕开 dataplane）。
+"""artifacts.py — AP artifact HTTP 下载兼容入口。
 
 调用方：普通用户 / UTS SDK，透传 apikey + job_id + cluster_id。
-鉴权：AP workspace ACL（SDK 调 AP GET /api/jobs/{id} 时自动检查）。
-STS：apiserver POST /apis/v1/credentials，resource=oss，artifact 前缀强制只读。
-OSS：{ARTIFACT_PREFIX_ROOT}/{job_id}/result.tgz（前缀根经 _site_defaults 注入）。
+鉴权：由 AP 产物接口负责，SDK 不再读取 Job 详情预检查。
+下载委托独立 irepo-artifact 包；旧 bucket/key 工具保留但不参与下载。
 """
 from __future__ import annotations
 
 import json
 import logging
 import os
-import posixpath
 import urllib.error
 import urllib.request
-from concurrent.futures import ThreadPoolExecutor, as_completed
 from typing import Any
 
 from .errors import Forbidden, InstanceRepoError
@@ -216,136 +213,65 @@ def fetch_group_job_ids(api_key: str, group_id: str, cluster: str,
     return job_ids
 
 
-def _download_one(transport, bucket: str, job_id: str, output_dir: str) -> str:
-    """下载单个 job 的 artifact 到 output_dir/{job_id}/{文件名}。
+def _client(api_key: str, cluster: str, ap_endpoint: str | None):
+    from irepo_artifact import ArtifactClient
+    return ArtifactClient(ap_endpoint=_ap_endpoint(ap_endpoint), api_key=api_key, cluster=cluster)
 
-    artifact 文件名不固定：实测两种命名（result.tgz 与 {job_id}.tgz）。
-    先 list 前缀目录找非空的 .tgz 对象，兼容所有命名；找不到 → ArtifactNotFoundError。
 
-    返回本地文件路径。失败时抛异常。
-    """
-    import oss2  # 延迟导入，避免无 oss2 环境 import 失败
-
-    prefix = artifact_prefix(job_id)
+def _legacy_error(error):
+    from irepo_artifact import AccessDenied, ArtifactNotFound, NoMatchingFiles
+    if isinstance(error, AccessDenied):
+        mapped = ArtifactPermissionError(str(error), cause=error)
+    elif isinstance(error, (ArtifactNotFound, NoMatchingFiles)):
+        mapped = ArtifactNotFoundError(str(error), cause=error)
+    else:
+        mapped = InstanceRepoError(f"{type(error).__name__}: {error}", cause=error)
+    mapped.artifact_error = error
+    mapped.error_type = type(error).__name__
+    mapped.status = getattr(error, 'status', None)
+    return mapped
 
-    # 获取 STS（同数据面多 job 共享缓存）
-    creds = transport.get_oss_credentials(bucket, prefix)
-    auth = oss2.StsAuth(
-        creds["access_key_id"],
-        creds["access_key_secret"],
-        creds["security_token"],
-    )
 
-    # 使用 credential 返回的 endpoint（通常是内网）
-    endpoint = creds.get("endpoint") or creds.get("oss_endpoint", "")
-    if not endpoint:
-        raise InstanceRepoError("STS response missing endpoint")
+def _result_path(result):
+    return str(result.files_dir if result.files_dir is not None else result.archive_path)
 
-    bkt = oss2.Bucket(auth, endpoint, bucket)
-
-    # 1. list 前缀目录，找 artifact tgz 对象（跳过 size=0 的目录占位符）
-    key = None
-    for obj in oss2.ObjectIterator(bkt, prefix=prefix):
-        if obj.size > 0 and obj.key.endswith(".tgz"):
-            key = obj.key
-            break
-    if not key:
-        raise ArtifactNotFoundError(
-            f"no artifact tgz found under {prefix!r} for job {job_id!r}")
-
-    # 2. 本地路径（保留 OSS 上的真实文件名）
-    job_dir = os.path.join(output_dir, job_id)
-    os.makedirs(job_dir, exist_ok=True)
-    local_path = os.path.join(job_dir, os.path.basename(key.rstrip("/")))
-
-    # 3. 下载（带 OSS 限流退避）
-    wait = OSS_RETRY_INITIAL_WAIT
-    for attempt in range(1, OSS_RETRY_MAX_ATTEMPTS + 1):
-        try:
-            bkt.get_object_to_file(key, local_path)
-            logger.info("downloaded %s → %s", key, local_path)
-            return local_path
-        except oss2.exceptions.ServerError as e:
-            if e.status == 503 and attempt < OSS_RETRY_MAX_ATTEMPTS:
-                logger.warning("OSS 503 for %s, retry %d/%d in %.1fs",
-                               job_id, attempt, OSS_RETRY_MAX_ATTEMPTS, wait)
-                import time
-                time.sleep(wait)
-                wait = min(wait * 2, OSS_RETRY_MAX_WAIT)
-            else:
-                raise
-    return local_path  # unreachable, but keeps type checker happy
-
-
-# ---------------------------------------------------------------------------
-# 公开 API（给 Repo 类调用）
-# ---------------------------------------------------------------------------
 
 def download_artifact(transport, api_key: str, job_id: str,
                       cluster: str, output_dir: str = ".",
-                      ap_endpoint: str | None = None) -> str:
-    """下载单个 job 的 artifact (result.tgz)。
-
-    Args:
-        transport: SDK Transport 实例（用于 apiserver STS 请求）
-        api_key: 用户 API Key（透传给 AP 做 workspace ACL 检查）
-        job_id: AP job ID
-        cluster: 数据面名
-        output_dir: 本地输出目录
-        ap_endpoint: AP 控制面 URL（默认从环境变量或常量取）
-
-    Returns:
-        下载文件的本地路径
+                      ap_endpoint: str | None = None, *,
+                      include_files: list[str] | None = None,
+                      exclude_files: list[str] | None = None,
+                      extract: bool = False) -> str:
+    """Download through AP-issued HTTP links; transport retained for compatibility.
+
+    output_dir is the Job directory. AP artifact endpoints enforce access;
+    no Job precheck, STS or object-storage SDK is used.
     """
-    # 1. AP workspace ACL 检查
-    fetch_job_info(api_key, job_id, cluster, ap_endpoint)
-
-    # 2. 确定 bucket
-    bucket = resolve_artifact_bucket(cluster)
-
-    # 3. 下载
-    return _download_one(transport, bucket, job_id, output_dir)
+    from irepo_artifact import ArtifactError
+    try:
+        result = _client(api_key, cluster, ap_endpoint).download(
+            job_id, output_dir, include_files=include_files,
+            exclude_files=exclude_files, extract=extract, overwrite=True)
+        return _result_path(result)
+    except ArtifactError as exc:
+        raise _legacy_error(exc) from exc
 
 
 def download_artifacts(transport, api_key: str, job_ids: list[str],
                        cluster: str, output_dir: str = ".",
                        max_concurrent: int = DEFAULT_MAX_CONCURRENT,
-                       ap_endpoint: str | None = None,
-                       ) -> dict[str, str | Exception]:
-    """批量下载多个 job 的 artifact。
-
-    并发粒度是跨 job（不是单文件内多线程）。同数据面的多个 job 共享 STS 凭据。
-
-    Args:
-        transport: SDK Transport 实例
-        api_key: 用户 API Key
-        job_ids: AP job ID 列表
-        cluster: 数据面名
-        output_dir: 本地输出目录
-        max_concurrent: 最大并发下载数
-        ap_endpoint: AP 控制面 URL
-
-    Returns:
-        {job_id: 本地文件路径 或 Exception}
-    """
-    bucket = resolve_artifact_bucket(cluster)
-    results: dict[str, str | Exception] = {}
-
-    def _do(jid: str) -> tuple[str, str | Exception]:
-        try:
-            # AP workspace ACL 检查
-            fetch_job_info(api_key, jid, cluster, ap_endpoint)
-            # 下载
-            path = _download_one(transport, bucket, jid, output_dir)
-            return jid, path
-        except Exception as e:
-            logger.error("failed to download artifact for job %s: %s", jid, e)
-            return jid, e
-
-    with ThreadPoolExecutor(max_workers=max_concurrent) as pool:
-        futures = {pool.submit(_do, jid): jid for jid in job_ids}
-        for future in as_completed(futures):
-            jid, result = future.result()
-            results[jid] = result
-
-    return results
+                       ap_endpoint: str | None = None, *,
+                       include_files: list[str] | None = None,
+                       exclude_files: list[str] | None = None,
+                       extract: bool = False) -> dict[str, str | Exception]:
+    """Download into output_dir/jobs/<job_id>; retain per-Job path/error results."""
+    from irepo_artifact import ArtifactError
+    try:
+        results = _client(api_key, cluster, ap_endpoint).download_many(
+            job_ids, output_dir, max_concurrent=max_concurrent,
+            include_files=include_files, exclude_files=exclude_files,
+            extract=extract, overwrite=True)
+    except ArtifactError as exc:
+        raise _legacy_error(exc) from exc
+    return {jid: (_legacy_error(result.error) if result.error is not None
+                  else _result_path(result)) for jid, result in results.items()}

{instance_repo-1.1.4 → instance_repo-1.3.0.dev0}/instance_repo/cli.py

@@ -341,7 +341,7 @@ def build_parser() -> argparse.ArgumentParser:
     sp.add_argument("--split", default=None,
                     help="目标 split 名（get/set-run-type 用）")
     sp.add_argument("--version", default=None,
-                    help="list 按 version 精确过滤；get 可选定位版本；create 必填")
+                    help="list 按 version 精确过滤；get/create 可选定位版本")
     sp.add_argument("--scope", choices=["unversioned", "exact", "all"], default=None,
                     help="list 跨版本策略：缺省无 version → all（SDK 取全量哲学），"
                          "有 version 省略（服务端只接受 exact）")
@@ -351,7 +351,7 @@ def build_parser() -> argparse.ArgumentParser:
                     dest="run_type",
                     help="set-run-type/create 用：train/eval 或空串清除")
     sp.add_argument("--storage-path", default=None, dest="storage_path",
-                    help="create 用：split 壳的 storage_path（缺省自动计算）")
+                    help="create 的 1.2.1 兼容参数；非空值会被拒绝，路径由服务端推导")
     sp.add_argument("--page", type=int, default=1)
     sp.add_argument("--page-size", type=int, default=50, dest="page_size")
     sp.add_argument("--environment", default=None,
@@ -407,7 +407,7 @@ def build_parser() -> argparse.ArgumentParser:
 
     # ── Artifact 下载（STS 直连 OSS，workspace ACL 鉴权）──
     art = sub.add_parser("artifact",
-                         help="AP job artifact 下载（STS 直连 OSS）")
+                         help="AP job artifact 下载（AP HTTP 链接）")
     asub = art.add_subparsers(dest="artifact_cmd", required=True)
 
     adl = asub.add_parser("download", help="下载单个 job 的 artifact")
@@ -437,6 +437,16 @@ def build_parser() -> argparse.ArgumentParser:
     adlg.add_argument("--concurrent", type=int, default=8)
     adlg.add_argument("--ap-endpoint", default=None, dest="ap_endpoint")
 
+    for artifact_parser in (adl, adlm, adlg):
+        artifact_parser.add_argument(
+            "--include-files", action="append", default=None,
+            help="Only download matching artifact files or folders (repeatable; comma-separated)")
+        artifact_parser.add_argument(
+            "--exclude-files", action="append", default=None,
+            help="Skip matching artifact files or folders (repeatable; comma-separated)")
+        artifact_parser.add_argument("--extract", action="store_true",
+                                     help="Extract the complete archive (default: keep archive only)")
+
     return ap
 
 
@@ -609,6 +619,16 @@ def _effective_cluster(args) -> str | None:
 def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
     args = _parse_args(argv)
     out = out or sys.stdout
+    if args.cmd == "artifact":
+        for name in ("include_files", "exclude_files"):
+            raw = getattr(args, name)
+            values = list(dict.fromkeys(v.strip() for item in (raw or [])
+                                        for v in item.split(",") if v.strip()))
+            if raw is not None and not values:
+                raise InstanceRepoError(f"--{name.replace('_', '-')} 至少需要一个非空的文件或目录选择器")
+            setattr(args, name, values or None)
+        if args.extract and (args.include_files or args.exclude_files):
+            raise InstanceRepoError("--extract 不能与 --include-files 或 --exclude-files 同时使用")
     cluster = _effective_cluster(args)
     r = repo or Repo(profile=args.profile, api_env=getattr(args, "api_env", None),
                      api_base=getattr(args, "api_base", None), cluster=cluster,
@@ -1015,9 +1035,6 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
             return 0
         if args.action == "create":
             dataset, split_name = _resolve_split_ref(args)
-            if not (args.version or "").strip():
-                raise SystemExit(
-                    "split create 需要 --version（apiserver CreateVersion 硬约束）")
             sp = r.splits.create(dataset, split_name,
                                  version=args.version,
                                  run_type=args.run_type,
@@ -1172,7 +1189,9 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
             path = r.download_artifact(
                 args.job_id, cluster=args.cluster,
                 output_dir=args.output_dir,
-                ap_endpoint=args.ap_endpoint)
+                ap_endpoint=args.ap_endpoint,
+                include_files=args.include_files, exclude_files=args.exclude_files,
+                extract=args.extract)
             print(str(path), file=out)
             return 0
         if args.artifact_cmd == "download-many":
@@ -1181,7 +1200,9 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
                 job_ids, cluster=args.cluster,
                 output_dir=args.output_dir,
                 max_concurrent=args.concurrent,
-                ap_endpoint=args.ap_endpoint)
+                ap_endpoint=args.ap_endpoint,
+                include_files=args.include_files, exclude_files=args.exclude_files,
+                extract=args.extract)
             ok, fail = 0, 0
             for jid, res in results.items():
                 if isinstance(res, Exception):
@@ -1197,7 +1218,9 @@ def main(argv=None, *, repo: Repo | None = None, out=None) -> int:
                 args.group_id, cluster=args.cluster,
                 output_dir=args.output_dir,
                 max_concurrent=args.concurrent,
-                ap_endpoint=args.ap_endpoint)
+                ap_endpoint=args.ap_endpoint,
+                include_files=args.include_files, exclude_files=args.exclude_files,
+                extract=args.extract)
             ok, fail = 0, 0
             for jid, res in results.items():
                 if isinstance(res, Exception):

{instance_repo-1.1.4 → instance_repo-1.3.0.dev0}/instance_repo/clients/splits.py

@@ -5,11 +5,11 @@
   version_scope=unversioned——只列无版本 split；跨全部版本须显式 version_scope=all）；
   status 过滤；environment（默认 online）；分页默认 page=1/page_size=50（上限 200）。
 * ``GET /datasets/splits/detail``：dataset_name+split 必填、version 可选；裸记录。
+* ``POST /datasets/splits``：dataset_name 必填、version 可选；body 为
+  ``{"splits": [...]}``，响应兼容 DatasetVersion，需再 GET split 详情确认。
 * ``PATCH /datasets/splits/detail``：dataset_split_id 或 dataset_name+split(+version)
-  寻址；body 仅 run_type（必填，"train"/"eval"，空串=清除）；仅 online 环境
-  （显式 pre 被 400 拒绝）；返回更新后的记录。
-* split 无 create/delete 端点：split 记录由 ingest 扫描 OSS 或
-  versions.create/update(splits=[...]) 间接产生——SDK 不伪造这些能力。
+  寻址；body 仅 run_type（必填，"train"/"eval"，空串=清除）；environment 与
+  POST/GET 保持一致；返回更新后的记录。
 
 设计决策（方案 D1，已评审）：``SplitsClient.list`` 在 version 为空且未显式传
 version_scope 时**默认 all**（跨全部版本+无版本 split）。理由：SDK 的 list 语义
@@ -21,9 +21,10 @@ from __future__ import annotations
 
 from urllib.parse import quote
 
-from ..errors import SchemaError, TransportError
+from ..errors import SchemaError, TransportError, WriteOutcomeUnknown
 from ..models import (DatasetSplit, PagedResult, RUN_TYPE_VALUES,
                       SPLIT_STATUS_VALUES)
+from ..retry import retry_transient
 
 # 服务端 ListSplits 认可的 version_scope 取值（recordsvc）。
 VERSION_SCOPE_VALUES = ("unversioned", "exact", "all")
@@ -222,57 +223,105 @@ class SplitsClient:
 
     # ── 写 ──
 
+    def _post_create(self, dataset: str, split: str, version: str,
+                     environment: str) -> None:
+        """创建 split；POST 非幂等，响应是 DatasetVersion 兼容体，故不解析。"""
+        q = f"dataset_name={quote(dataset, safe='')}"
+        if version:
+            q += f"&version={quote(version, safe='')}"
+        if environment:
+            q += f"&environment={quote(environment, safe='')}"
+        self._t.post(f"{self._BASE}?{q}", {"splits": [split]},
+                     idempotent=False)
+
     def create(self, dataset: str, split: str, *,
-               version: str, run_type: str | None = None,
+               version: str | None = None, run_type: str | None = None,
                storage_path: str | None = None,
                environment: str | None = None) -> DatasetSplit:
-        """创建 split 记录——组合 versions.create(splits=[split]) 的便利封装。
-
-        apiserver **没有** split create 端点（``POST /datasets/splits`` 不存在）：
-        split 记录由 ingest 扫描 OSS 或 versions.create/update(splits=[...])
-        间接产生（pre 集合 find-or-upsert ensure 真实 split record）。本方法是
-        "先建空 split 壳"的官方路径升级为 SDK 直接 API：
+        """经独立 split API 创建记录并从详情端点权威读回。
 
-        1. ``versions.create(dataset, version, splits=[split])``（version **必填**
-           ——apiserver CreateVersion 硬约束；storage_path 缺省自动计算）；
-        2. 可选 ``run_type``：create 后经 versions.update(split_run_types) 打标；
-        3. 读回 ``splits.get``（同 environment）返回记录。
-
-        参数:
-          dataset      : dataset 名（必填）。
-          split        : split 名（必填）。
-          version      : version（必填——CreateVersion 硬约束）。
-          run_type     : 可选，train/eval（create 后打标）。
-          storage_path : 可选，缺省按 profile 自动计算（与 versions.create 同源）。
-          environment  : 可选，缺省由 profile 派生（pre/online）。
-
-        返回 :class:`~instance_repo.models.DatasetSplit`（读回；pre 集合 ensure
-        的 record 或 version 内嵌投影）。
+        ``version`` 可选；空值表示 unversioned split。``storage_path`` 仅为 1.2.1
+        源码兼容保留，独立端点不接受它，因此非空值会在网络调用前拒绝。
+        POST 响应是 DatasetVersion 兼容体，不能当 DatasetSplit 解析；可选 run_type
+        PATCH 完成后始终 GET 详情，并对创建后的短暂不可见做三次有界重试。
         """
-        from .versions import VersionsClient
-        if not (dataset or "").strip():
+        dataset_name = (dataset or "").strip()
+        split_name = (split or "").strip()
+        version_name = (version or "").strip()
+        if not dataset_name:
             raise SchemaError("dataset is required for splits.create")
-        if not (split or "").strip():
+        if not split_name:
             raise SchemaError("split is required for splits.create")
-        if not (version or "").strip():
+        if (storage_path or "").strip():
             raise SchemaError(
-                "version is required for splits.create (apiserver CreateVersion "
-                "requires version; split records are created via versions.create)")
+                "storage_path is deprecated for splits.create: split creation now "
+                "uses an independent endpoint that does not accept storage paths")
         rt = (run_type or "").strip()
         if rt and rt not in RUN_TYPE_VALUES:
             raise SchemaError(
                 f"invalid run_type {rt!r}; must be one of "
                 f"{', '.join(RUN_TYPE_VALUES)} or None")
         env = self._env(environment)
-        vc = VersionsClient(self._t, self._p)
-        vc.create(dataset, version, splits=[split],
-                  storage_path=storage_path, environment=env or None)
+
+        try:
+            self._post_create(dataset_name, split_name, version_name, env)
+        except Exception as exc:
+            raise TransportError(
+                f"split create POST failed before creation was confirmed: {exc}",
+                status=getattr(exc, "status", None),
+                biz_code=getattr(exc, "biz_code", None)) from exc
+
+        coordinates = _create_coordinates(
+            dataset_name, version_name, split_name, env)
         if rt:
-            # run_type 打标与 create 互斥字段：经 split_run_types 单独打（apiserver
-            # UpdateVersion 的 run_type/split_run_types/splits 两两互斥）。
-            vc.update(dataset, version, split_run_types={split: rt})
-        return self.get(dataset, split, version=version,
-                        environment=env or None)
+            try:
+                self._update_with_environment(
+                    dataset_name, split_name, version=version_name,
+                    run_type=rt, status="", dataset_split_id=None,
+                    environment=env)
+            except Exception as exc:
+                raise TransportError(
+                    "split was created but run_type update failed; "
+                    f"the split create is NOT rolled back; {coordinates}: {exc}",
+                    status=getattr(exc, "status", None),
+                    biz_code=getattr(exc, "biz_code", None)) from exc
+
+        def readback() -> DatasetSplit:
+            found = self._read_detail_once(
+                dataset_name, split_name, version_name, env)
+            if found is None or found.name != split_name:
+                # A successful create can be briefly invisible to the detail read.
+                # Mark only this post-write condition transient; retry_transient keeps
+                # deterministic 4xx/schema failures single-shot.
+                raise TransportError(
+                    "created split is not yet visible in authoritative readback",
+                    status=503)
+            return found
+
+        try:
+            return retry_transient(readback, attempts=3)
+        except Exception as exc:
+            raise WriteOutcomeUnknown(
+                "split create succeeded but authoritative readback could not be "
+                f"confirmed; {coordinates}: {exc}",
+                cause=exc) from exc
+
+    def _read_detail_once(self, dataset: str, split: str, version: str,
+                          environment: str) -> DatasetSplit | None:
+        """Read only split detail once; never retry or project legacy version data."""
+        q = (f"dataset_name={quote(dataset, safe='')}"
+             f"&split={quote(split, safe='')}")
+        if version:
+            q += f"&version={quote(version, safe='')}"
+        if environment:
+            q += f"&environment={quote(environment, safe='')}"
+        try:
+            data = self._t._request_once("GET", f"{self._BASE}/detail?{q}")
+        except TransportError as exc:
+            if exc.status == 404:
+                return None
+            raise
+        return DatasetSplit.from_dict(data) if isinstance(data, dict) and data else None
 
     def update(self, dataset: str, split: str | None = None, *,
                version: str | None = None, run_type: str = "",
@@ -290,19 +339,24 @@ class SplitsClient:
         典型用法：锁定 split（``status="published"``）后 push(overwrite=True)
         会被 instances 侧前置检查拒绝，解锁用 ``status="draft"``。
 
-        写端点**仅限 online**（apiserver 对显式 pre 返回 400；pre 环境 split 的
-        run_type 变更经 ``versions.update(split_run_types=...)`` 走集合路由）。
-
         ``environment`` 语义与 :meth:`get`/:meth:`list` 对齐：显式参数优先，
-        缺省由 profile 派生。派生/显式为 ``pre`` 时**前置拒绝**（SchemaError）
-        ——避免「存在性检查读 pre、写入却落 online」的读写环境撕裂（AP CLI
-        review 真机锤实：读 pre 查到、写 online 报 not found 或改错记录）。
-        显式 ``"online"`` 会拼进 query，请求自文档化；为空（无 profile）时
-        不拼参，服务端默认 online（向后兼容）。
+        缺省由 profile 派生。任何非空有效环境均拼入 query，使独立 create 的
+        POST、可选 run_type PATCH 与权威 GET 始终访问同一集合；为空时沿用
+        服务端默认环境。
 
         寻址二选一：``dataset_split_id``（优先，split-first 精确记录 id）或
         ``dataset``+``split``（+可选 ``version``）name 三元组。
         """
+        return self._update_with_environment(
+            dataset, split, version=version, run_type=run_type, status=status,
+            dataset_split_id=dataset_split_id,
+            environment=self._env(environment))
+
+    def _update_with_environment(self, dataset: str, split: str | None, *,
+                                 version: str | None, run_type: str, status: str,
+                                 dataset_split_id: str | None,
+                                 environment: str) -> DatasetSplit:
+        """PATCH using an already-resolved environment, including frozen empty."""
         if dataset_split_id:
             q = f"dataset_split_id={quote(dataset_split_id, safe='')}"
         else:
@@ -313,15 +367,8 @@ class SplitsClient:
                  f"&split={quote(split, safe='')}")
             if (version or "").strip():
                 q += f"&version={quote(version, safe='')}"
-        env = self._env(environment)
-        if env == "pre":
-            raise SchemaError(
-                "splits.update is online-only: the split record write endpoint "
-                "(PATCH /datasets/splits/detail) only accepts the online "
-                "environment. To change the run_type of a pre split, use "
-                "versions.update(split_run_types={split: run_type}) instead.")
-        if env == "online":
-            q += "&environment=online"
+        if environment:
+            q += f"&environment={quote(environment, safe='')}"
         rt = run_type or ""
         if rt and rt not in RUN_TYPE_VALUES:   # 空串=清除，合法
             raise SchemaError(
@@ -347,6 +394,13 @@ class SplitsClient:
         return env
 
 
+def _create_coordinates(dataset: str, version: str, split: str,
+                        environment: str) -> str:
+    """Stable recovery coordinates for post-write partial-completion errors."""
+    return (f"dataset={dataset}, version={version or '<unversioned>'}, "
+            f"split={split}, environment={environment or '<server-default>'}")
+
+
 def normalize_split_version_scope(version: str | None,
                                   version_scope: str | None) -> str:
     """纯函数：供 conformance 跨语言比对 scope 缺省规则（version 空 → all）。"""

{instance_repo-1.1.4 → instance_repo-1.3.0.dev0}/instance_repo/clients/versions.py

@@ -329,16 +329,21 @@ class VersionsClient:
             storage_env 但配置了 cluster 时，会经 repo-config 解析出绑定的
             storage_env 再派生（与 ingest 对称）；显式 environment 与派生值冲突时
             前置拒绝。
-          metadata_model: 可选。显式传入时下发给 apiserver（``split_first`` /
-            ``version_first``）；缺省时由 profile 的 metadata_model 派生。
-            split_first 数据集建版本时必须传 ``split_first``（或由 profile 派生），
-            否则 apiserver 按 version_first 路由写入 legacy 集合。
+          metadata_model: 可选。显式非空值归一后下发（``split_first`` /
+            ``version_first``）；空值回退到 profile 的 ``metadata_model``
+            （再空取 SDK 默认 ``split_first``），与 ingest/list/update 一致。
 
         run_type 不在建版本时设置（apiserver create 不收该字段）：建好后用
         ``set_run_type`` / ``update`` 打标，或走 ``ingest(run_type=...)``。
         """
         if not version:
             raise SchemaError("version is required")
+        # metadata_model：显式非空值先校验（确保非法值在任何 repo-config 探测或
+        # POST 前失败）；空值回退到 profile（与 ingest/list/update 一致）。
+        if metadata_model is not None and metadata_model.strip():
+            normalize_metadata_model(metadata_model)  # early reject invalid
+        else:
+            metadata_model = None
         # 与 ingest 对称（问题1 彻底修复）：storage_env 未在 profile 里显式配置时，
         # 经 repo-config 解析出与 cluster 绑定的 storage_env 再派生 environment；
         # 同时复用**同一次**响应里的 bucket/prefix 计算 storage_path，避免出现
@@ -385,15 +390,18 @@ class VersionsClient:
         # environment 必须放 query（apiserver createVersionRequest 无该字段，
         # 只从 datasetEnvironmentFromQuery 读）；放 body 会被静默丢弃导致
         # 版本落到默认 online 而 list/get/update 走 profile 派生的 pre。
-        # metadata_model 同理：apiserver 从 query 读取用于路由到 split_first 集合。
+        # metadata_model 与 ingest/list/update 对齐：显式值优先，空值从 profile
+        # 派生（apiserver d7275ab7 起已放开 split_first Version 创建限制）。
+        mm = metadata_model
+        if mm is None and self._p is not None:
+            mm = normalize_metadata_model(
+                self._p.metadata_model if self._p else None)
+        if mm is None:
+            mm = normalize_metadata_model(None)
         q = f"dataset_name={quote(dataset, safe='')}"
         if env:
             q += f"&environment={quote(env, safe='')}"
-        mm = metadata_model
-        if mm is None and self._p is not None:
-            mm = normalize_metadata_model(self._p.metadata_model)
-        if mm:
-            q += f"&metadata_model={quote(mm, safe='')}"
+        q += f"&metadata_model={quote(mm, safe='')}"
         data = self._t.post(f"{self._BASE}?{q}", body)
         return DatasetVersion(**_pick(data))
 

{instance_repo-1.1.4 → instance_repo-1.3.0.dev0}/instance_repo/repo.py

@@ -462,14 +462,17 @@ class Repo:
             pfx += self._clean_user_data_subpath(subpath)
         return self._content.list_objects(pfx)
 
-    # ── Artifact 下载（STS 直连 OSS，workspace ACL 鉴权）──
+    # ── Artifact 下载（AP HTTP 链接，由服务端执行权限校验）──
 
     def download_artifact(self, job_id: str, cluster: str | None = None,
                           output_dir: str = ".", *,
-                          ap_endpoint: str | None = None) -> str:
+                          ap_endpoint: str | None = None,
+                          include_files: list[str] | None = None,
+                          exclude_files: list[str] | None = None,
+                          extract: bool = False) -> str:
         """下载单个 job 的 artifact (result.tgz) 到本地。
 
-        鉴权：AP workspace ACL（SDK 调 AP GET /api/jobs/{id} 时自动检查）。
+        鉴权：由 AP artifact 接口执行，SDK 不再查询 Job 详情作预检查。
         并发模型：单 job = 单文件单线程。
 
         Args:
@@ -484,17 +487,21 @@ class Repo:
         from .artifacts import download_artifact as _dl
         cluster = cluster or self.profile.cluster or ""
         return _dl(self.transport, self.transport.token, job_id,
-                   cluster, output_dir, ap_endpoint)
+                   cluster, output_dir, ap_endpoint,
+                   include_files=include_files, exclude_files=exclude_files, extract=extract)
 
     def download_artifacts(self, job_ids: list[str],
                            cluster: str | None = None,
                            output_dir: str = ".", *,
                            max_concurrent: int = 8,
                            ap_endpoint: str | None = None,
+                           include_files: list[str] | None = None,
+                           exclude_files: list[str] | None = None,
+                           extract: bool = False,
                            ) -> dict[str, str | Exception]:
         """批量下载多个 job 的 artifact。
 
-        并发粒度是跨 job（不是单文件内多线程）。同数据面的多个 job 共享 STS 凭据。
+        并发粒度是跨 job（不是单文件内多线程）。下载使用 AP 返回的 HTTP 链接。
 
         Args:
             job_ids: AP job ID 列表
@@ -509,13 +516,17 @@ class Repo:
         from .artifacts import download_artifacts as _dl_many
         cluster = cluster or self.profile.cluster or ""
         return _dl_many(self.transport, self.transport.token, job_ids,
-                        cluster, output_dir, max_concurrent, ap_endpoint)
+                        cluster, output_dir, max_concurrent, ap_endpoint,
+                        include_files=include_files, exclude_files=exclude_files, extract=extract)
 
     def download_artifacts_from_group(self, group_id: str,
                                       cluster: str | None = None,
                                       output_dir: str = ".", *,
                                       max_concurrent: int = 8,
                                       ap_endpoint: str | None = None,
+                                      include_files: list[str] | None = None,
+                                      exclude_files: list[str] | None = None,
+                                      extract: bool = False,
                                       ) -> dict[str, str | Exception]:
         """下载某个 group 下全部 job 的 artifact。
 
@@ -539,7 +550,8 @@ class Repo:
             logger.warning("group %s has no jobs", group_id)
             return {}
         return _dl_many(self.transport, self.transport.token, job_ids,
-                        cluster, output_dir, max_concurrent, ap_endpoint)
+                        cluster, output_dir, max_concurrent, ap_endpoint,
+                        include_files=include_files, exclude_files=exclude_files, extract=extract)
 
     # ── 用户数据 ACL（role-bindings 接口，resource_type=user_data）──
     _USER_DATA_ROLE_MAP = {

{instance_repo-1.1.4 → instance_repo-1.3.0.dev0}/instance_repo.egg-info/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.4
 Name: instance-repo
-Version: 1.1.4
+Version: 1.3.0.dev0
 Summary: InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
+Requires-Dist: irepo-artifact<0.2.0,>=0.1.1
 Requires-Dist: tomli>=1.1.0; python_version < "3.11"
 Provides-Extra: oss
 Requires-Dist: oss2>=2.19; extra == "oss"
@@ -81,8 +82,9 @@ pip install "instance-repo[oss]"     # 需要数据面 OSS 读写时，附带 os
 不是 default）。旧数据集显式传 `Repo(metadata_model="version_first")`，其对象布局与镜像 tag
 **逐字节不变**，存量数据无需迁移。
 
-服务端把空 `metadata_model` 归一为 `version_first`，因此 SDK 每次请求都显式下发该字段——
-不声明就会静默退回旧模型。
+服务端把空 `metadata_model` 归一为 `version_first`。数据面与读路径仍按 profile 的模型工作；
+但 `repo.versions.create(...)` 的 `metadata_model` 仅在调用方显式传入非空值时下发，不从
+profile 自动注入。显式 `split_first` 仍由服务端拒绝；创建 split 应使用 `repo.splits.create(...)`。
 
 | | `split_first`（默认） | `version_first`（旧） |
 | --- | --- | --- |
@@ -96,6 +98,29 @@ pip install "instance-repo[oss]"     # 需要数据面 OSS 读写时，附带 os
 92005 ambiguous。显式给 splits 时服务端只列举 `{split}/` 与 `{split}-assets/`，推断被完全绕过。
 确需推断时传 `allow_layout_inference=True`。
 
+## Split 创建
+
+`repo.splits.create(dataset, split, *, version=None, run_type=None, storage_path=None,
+environment=None)` 直接调用 `POST /apis/v1/datasets/splits`，body 固定为
+`{"splits":["<split>"]}`。`version` 可选；省略即创建 unversioned split，query 中不会发送
+`version=`。存储路径由服务端根据 dataset/version/split 推导。
+
+`storage_path` 只为 1.2.1 调用兼容保留（计划 1.3.0 删除）：空值允许，非空值在网络请求前抛
+`SchemaError`。提供 `run_type` 时，创建后通过 `PATCH /apis/v1/datasets/splits/detail` 更新，
+不会调用 Version PATCH；最后 GET 读回权威 Split 记录。
+
+```python
+repo.splits.create("alibaba/mybench", "test")
+repo.splits.create("alibaba/mybench", "test", version="v1", run_type="eval")
+```
+
+对应 CLI 的 `--version` 也是可选项；`--storage-path` 仅兼容旧脚本，非空值会失败：
+
+```bash
+irepo split create alibaba/mybench/test --run-type eval
+irepo split create alibaba/mybench/test --version v1
+```
+
 ## 独立镜像能力（`repo.images`，0.8 新增）
 
 ```python
@@ -152,7 +177,8 @@ irepo --help
 # 20 个子命令：validate / push / push-many / deliver / pull / list / get
 #              publish / grant / feedback / report / whoami / user-data
 #              repo-config / create / claim / version / image
-#              split（list/get/set-run-type）/ dataset（list/get/update/access/revoke/benchmarks/workflows）
+#              split（list/get/create/set-run-type；create 的 --version 可选，--storage-path 非空即拒绝）
+#              dataset（list/get/update/access/revoke/benchmarks/workflows）
 irepo image ref --dataset alibaba/mybench --instance-id inst-1 --split test
 irepo image pull '<acr>/<ns>/mybench:test-inst-1' ./out.tar
 ```
@@ -175,3 +201,36 @@ irepo publish alibaba/mybench/v1 --split test \
 版本号在 `pyproject.toml` / `instance_repo.__version__` / Go `version.go` /
 conformance golden 四处保持一致。各环境的真实配置取值、端到端示例与错误码对照，见团队内部
 部署文档。
+
+## 产物下载改造（开发版）
+
+产物下载现在委托独立 `irepo-artifact` 包，通过 AP 签发的 HTTP 链接下载，
+不再要求 OSS SDK、STS 或 artifact bucket/prefix 配置；其他存储功能的 OSS 依赖不变。
+本地开发需同时安装两个包：
+
+```bash
+python -m pip install -e ./sdk/python-artifact -e ./sdk/python
+```
+
+保留 `irepo artifact download`、`download-many`、`download-group`。三个命令均支持
+`--include-files`、`--exclude-files`（可重复、可逗号分隔）和 `--extract`。
+
+```bash
+irepo artifact download --job-id job-a --output-dir out/job-a
+irepo artifact download-many --job-ids job-a,job-b --output-dir out --extract
+irepo artifact download-group --group-id group-a --output-dir out \
+  --include-files logs,result.json --exclude-files debug.log,tmp
+```
+
+默认不解压；`--extract` 与文件筛选冲突。筛选通过 manifest 得到最终文件列表，再向 AP 获取
+各文件 URL。不开启筛选时优先 OSS，网络不可达或中断时回退 dataplane。
+
+**路径迁移：** 单 Job 的输出目录就是 Job 目录，包为 `<output_dir>/result.tgz`；
+批量／Group 为 `<output_dir>/jobs/<job_id>/result.tgz`。解压或筛选内容位于 Job 目录的
+`artifacts/output/`。旧 `<job_id>.tgz` 文件名统一为 `result.tgz`，旧脚本应使用 SDK 返回路径。
+旧 SDK 单 Job 仍返回字符串，批量仍返回路径或异常字典；旧入口维持覆盖意图，新独立客户端
+默认拒绝覆盖。请勿在旧目录尚有需保留文件时直接覆盖迁移。
+
+权限由 AP artifact 接口统一校验，SDK 不再执行 Job 详情预检查。
+更多行为与安装说明见 [独立包 README](../python-artifact/README.md)。
+独立包尚为开发版本，正式发布完整 SDK 前必须先发布可安装的独立包版本。

{instance_repo-1.1.4 → instance_repo-1.3.0.dev0}/instance_repo.egg-info/requires.txt

@@ -1,3 +1,4 @@
+irepo-artifact<0.2.0,>=0.1.1
 
 [:python_version < "3.11"]
 tomli>=1.1.0

{instance_repo-1.1.4 → instance_repo-1.3.0.dev0}/pyproject.toml

@@ -4,12 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "instance-repo"
-version = "1.1.4"
+version = "1.3.0.dev0"
 description = "InstanceRepo SDK — 评测 Instance 统一存储客户端（SDK-only；控制面由 apiserver 承载）"
 requires-python = ">=3.10"
 readme = "README.md"
 # tomllib 是 3.11 内置；3.10 上回退到 tomli（见 validate.py），故按 Python 版本条件依赖。
 dependencies = [
+    "irepo-artifact>=0.1.1,<0.2.0",
     "tomli>=1.1.0; python_version < '3.11'",
 ]