ap-client 0.3.1.dev2__tar.gz → 0.3.2__tar.gz

{ap_client-0.3.1.dev2 → ap_client-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ap-client
-Version: 0.3.1.dev2
+Version: 0.3.2
 Summary: Agent Platform API Client & CLI
 Requires-Python: >=3.10
 Requires-Dist: pyyaml>=6.0
@@ -9,9 +9,9 @@ Requires-Dist: rich>=13.0.0
 Requires-Dist: typer>=0.9.0
 Requires-Dist: websockets>=13.0
 Provides-Extra: all
-Requires-Dist: instance-repo[oss]>=1.1.0; extra == 'all'
+Requires-Dist: instance-repo[oss]<2.0.0,>=1.1.2; extra == 'all'
 Provides-Extra: dataset
-Requires-Dist: instance-repo[oss]>=1.1.0; extra == 'dataset'
+Requires-Dist: instance-repo[oss]<2.0.0,>=1.1.2; extra == 'dataset'
 Description-Content-Type: text/markdown
 
 A lightweight Python SDK and command line interface for Agent Platform. It provides helpers for configuring API access and managing templates, datasets, jobs, and groups.

{ap_client-0.3.1.dev2 → ap_client-0.3.2}/ap_client/cli.py

@@ -844,8 +844,6 @@ def _print_detail(data: object) -> None:
             rows.append((key, _format_nested_detail(value)))
         elif key == "image" and isinstance(value, str):
             rows.append((key, _shorten_image(value)))
-        elif value is None:
-            continue
         else:
             rows.append((key, _format_plain_value(value, max_len=0)))
     width = max((len(label) for label, _text in rows), default=0)

{ap_client-0.3.1.dev2 → ap_client-0.3.2}/ap_client/dataset_commands.py

@@ -120,6 +120,7 @@ _NO_BENCHMARK = "none"
 _FORMAT_HELP = "Output format: plain/table/json/yaml (default: AP_FORMAT or command default)"
 
 _METADATA_MODELS = ("version_first", "split_first")
+_VERSION_SPLIT_METADATA_MODEL = "version_first"
 
 #: CLI **不替 SDK 决定元数据模型**:不下发 ``metadata_model``,由 SDK 按 profile 归一
 #: (当前为 ``split_first``)。
@@ -155,10 +156,10 @@ _NO_VERSION_NOTE = "未指定 --version 表示无版本空间(split_first),不
 # ---------------------------------------------------------------------------
 
 
-def _fmt(output_format: Optional[str]) -> str:
+def _fmt(output_format: Optional[str], *, default: str = "plain") -> str:
     from .cli import _normalize_output_format
 
-    return _normalize_output_format(output_format, keep_table=True)
+    return _normalize_output_format(output_format, default=default, keep_table=True)
 
 
 def _fail(message: str, hint: str, exit_code: int = 1) -> "typer.Exit":
@@ -168,11 +169,6 @@ def _fail(message: str, hint: str, exit_code: int = 1) -> "typer.Exit":
     return typer.Exit(exit_code)
 
 
-def _note(message: str) -> None:
-    """退出码 0 的路径只用 ``note:``(设计 §5.1);一律 stderr。"""
-    typer.echo(f"note: {message}", err=True)
-
-
 def _describe(exc: BaseException) -> str:
     message = getattr(exc, "message", None)
     text = str(message or "").strip() or str(exc).strip()
@@ -412,6 +408,21 @@ def _api_biz_code(exc: BaseException) -> Optional[int]:
     return None
 
 
+def _business_code(exc: BaseException) -> Optional[int]:
+    code = getattr(exc, "biz_code", None)
+    if isinstance(code, int) and not isinstance(code, bool):
+        return code
+    return _api_biz_code(exc)
+
+
+def _last_admin_hint(dataset: str) -> str:
+    return (
+        "不能撤销或降级 dataset 的最后一个 admin;先授予另一个用户 admin："
+        f"ap dataset access grant {dataset} --user <另一工号> --role admin,"
+        "确认成功后再重试当前命令"
+    )
+
+
 #: apiserver dataset 控制面业务码 → 固定 hint(设计 §5.1)。
 _DATASET_CODE_HINTS: dict[int, str] = {
     92008: "该环境未开启 dataset 能力,请联系管理员",
@@ -524,7 +535,12 @@ def _updated_range(from_value: Optional[str], to_value: Optional[str]) -> tuple[
 
 
 def _fetch_version(
-    dataset: str, version: str, *, stage: str, environment: Optional[str] = None
+    dataset: str,
+    version: str,
+    *,
+    stage: str,
+    environment: Optional[str] = None,
+    metadata_model: str = "",
 ) -> dict:
     """读 version 详情(含内嵌 ``splits[]``);空 version 的报错必须点明"无版本空间"语义。
 
@@ -538,7 +554,12 @@ def _fetch_version(
     env = _environment(environment)
     repo = _dataset_repo()
     try:
-        detail = repo.versions.get(dataset, version, **_env_kwargs(env))
+        detail = repo.versions.get(
+            dataset,
+            version,
+            **_env_kwargs(env),
+            **({"metadata_model": metadata_model} if metadata_model else {}),
+        )
     except Exception as exc:  # noqa: BLE001 - 统一走设计 §5.1 的映射
         if version:
             hint = (
@@ -650,47 +671,6 @@ def _dataset_repo() -> "Repo":
         raise typer.Exit(2) from exc
 
 
-def _dataset_available_envs(repo: "Repo", dataset: str) -> list[str]:
-    """dataset 元数据分布的 environment 候选;详情读不到时退回固定枚举。"""
-    envs: list[str] = []
-    try:
-        detail = repo.datasets.get_detail(dataset)
-    except Exception:  # noqa: BLE001 - 引导信息尽力而为,不打断主流程
-        detail = None
-    raw = detail.get("available_envs") if isinstance(detail, dict) else None
-    if isinstance(raw, list):
-        envs = [str(env).strip() for env in raw if str(env).strip()]
-    from .irepo_sdk import DATASET_ENVIRONMENTS
-
-    for fallback in DATASET_ENVIRONMENTS:
-        if fallback not in envs:
-            envs.append(fallback)
-    return envs
-
-
-def _note_environment_distribution(repo: "Repo", dataset: str, probe, *, what: str) -> None:
-    """空结果时逐 environment 探测数据分布,引导用户换 ``--environment`` 重试。
-
-    ``probe(env)`` 返回该 environment 下的条数;读失败按 -1 计。全部为空/读失败
-    (dataset 真没数据)时不提示,避免噪声。
-    """
-    counts: list[tuple[str, int]] = []
-    for env in _dataset_available_envs(repo, dataset):
-        try:
-            counts.append((env, int(probe(env))))
-        except Exception:  # noqa: BLE001 - 旧 SDK 不接受 environment 等情况
-            counts.append((env, -1))
-    if not any(count > 0 for _env, count in counts):
-        return
-    shown = ", ".join(f"{env}={count if count >= 0 else '读失败'}" for env, count in counts)
-    with_data = [env for env, count in counts if count > 0]
-    suggest = with_data[0] if len(with_data) == 1 else f"<{'/'.join(with_data)}>"
-    _note(
-        f"{what}在本次查询的 environment 下没有数据;各 environment 探测:{shown}。"
-        f"数据可能在另一个元数据 environment,加 --environment {suggest} 重试"
-    )
-
-
 def _patch_version(
     dataset: str,
     version: str,
@@ -699,6 +679,7 @@ def _patch_version(
     stage: str,
     fallback_hint: str = "",
     environment: Optional[str] = None,
+    metadata_model: str = "",
 ) -> None:
     """split 写操作统一走 SDK;body 为 splits/split_run_types 单键。
 
@@ -710,7 +691,14 @@ def _patch_version(
 
     repo = _dataset_repo()
     try:
-        update_version_detail(repo, dataset, version, body, environment=_environment(environment))
+        update_version_detail(
+            repo,
+            dataset,
+            version,
+            body,
+            environment=_environment(environment),
+            metadata_model=metadata_model,
+        )
     except Exception as exc:  # noqa: BLE001 - 统一走设计 §5.1 的映射
         code = getattr(exc, "biz_code", None)
         if code == 94018:
@@ -846,14 +834,16 @@ def _bindings(repo, dataset: str) -> list[dict]:
 
 
 def _bindings_of(repo, dataset: str, principal_id: str, principal_type: str) -> list[dict]:
-    """某 principal 在此 dataset 上的现存绑定;读失败按"读不到"处理,不阻断主动作。"""
+    """某 principal 在此 dataset 上的现存绑定;读失败时停止变更。"""
     from .irepo_sdk import _reason
 
     try:
         rows = _bindings(repo, dataset)
-    except Exception as exc:  # noqa: BLE001 - 读不到绑定不该拦住授权本身
-        _note(f"读取现有绑定失败({_reason(exc)}),跳过角色去重")
-        return []
+    except Exception as exc:  # noqa: BLE001
+        raise _fail(
+            f"dataset {dataset} 现有授权查询失败：{_reason(exc)}",
+            "确认 dataset-admin 权限和当前集群后重试",
+        ) from exc
     return [
         row
         for row in rows
@@ -934,7 +924,7 @@ def dataset_list(
     """List datasets from the registry. Defaults to JSON; use --format table for a table."""
     from .cli import _print_formatted, get_client
 
-    output_format = _fmt(output_format)
+    output_format = _fmt(output_format, default="json")
     resolved_query = str(query or "").strip()
     legacy_search = str(search or "").strip()
     if legacy_search:
@@ -947,10 +937,6 @@ def dataset_list(
                 f"或 ap dataset list --query {query}",
                 exit_code=2,
             )
-        if not resolved_query:
-            _note(
-                f"位置参数搜索已兼容为 --query 的等价形式：ap dataset list --query {legacy_search}"
-            )
         resolved_query = legacy_search
 
     if legacy:
@@ -981,7 +967,6 @@ def dataset_list(
                 exit_code=2,
             )
         result = get_client().list_all_datasets(resolved_query or None)
-        _note("--legacy 使用旧数据源(与 ap job create --dataset 读取的一致),已自动翻页拉全量")
         if output_format == "table":
             from .cli import _print_records_table
 
@@ -1047,14 +1032,6 @@ def dataset_list(
     records, result = fetch(resolved_page)
     pagination = _pagination_envelope(result)
 
-    total = _pagination_total(pagination)
-    if total is not None and total > len(records):
-        _note(
-            f"共 {total} 个 dataset,本次返回第 {resolved_page} 页的 {len(records)} 条"
-            f"(每页 {resolved_page_size});继续翻页用 --page/--page-size,"
-            f"拉全量用 --legacy"
-        )
-
     payload: dict[str, Any] = {}
     if mine:
         payload["owned_by_me"] = True
@@ -1063,11 +1040,7 @@ def dataset_list(
     payload["datasets"] = [_legacy_dataset_record(record) for record in records]
     payload["total"] = _pagination_total(pagination, fallback=len(records))
     payload["pagination"] = pagination
-    if output_format == "table":
-        _print_table(rows, _DATASET_COLUMNS, output_format)
-    else:
-        # Legacy plain output is JSON, as for dataset versions / instances.
-        _print_formatted(payload, output_format)
+    _emit(payload, rows, _DATASET_COLUMNS, output_format)
 
 
 #: ``dataset get`` 尾部 environment 摘要表的列。
@@ -1115,6 +1088,13 @@ def dataset_get(
     """Show dataset detail, including version / split summary stats."""
     from .irepo_sdk import _reason
 
+    dataset = dataset.strip()
+    if not dataset:
+        raise _fail(
+            "dataset 查询失败：名称不能为空",
+            "传入非空 dataset 名称,例如 ap dataset get alibaba/a",
+            exit_code=2,
+        )
     output_format = _fmt(output_format)
     env = _environment(environment)
     repo = _dataset_repo()
@@ -1263,7 +1243,6 @@ def dataset_claim(
     if not detail.get("claimable", False):
         # 幂等:已认领就不是错误(设计 §4.1),stdout 仍按 --format 输出现状。
         owner = str(detail.get("owner") or "").strip() or "<unknown>"
-        _note(f"dataset {dataset} 已被认领(owner={owner}),无需重复认领")
         _emit_detail(
             {
                 "dataset": dataset,
@@ -1279,21 +1258,30 @@ def dataset_claim(
 
     if not (workspace or "").strip():
         candidates: list[Any] = []
+        candidate_error = ""
         try:
             candidates = repo.datasets.list_claim_workspaces() or []
         except Exception as exc:  # noqa: BLE001 - 列不出来不影响报用法错
-            _note(f"可选 workspace 列举失败：{_reason(exc)}")
+            candidate_error = _reason(exc)
+        choices: list[str] = []
         for item in candidates:
             queue_id = str(getattr(item, "queue_id", "") or getattr(item, "id", "") or "").strip()
             name = str(getattr(item, "name", "") or "").strip()
             if not queue_id and isinstance(item, dict):
                 queue_id = str(item.get("queue_id") or item.get("id") or "")
                 name = str(item.get("name") or "")
-            typer.echo(f"note: 可选 workspace: {queue_id}  {name}".rstrip(), err=True)
+            if queue_id:
+                choices.append(f"{queue_id} ({name})" if name else queue_id)
+        if choices:
+            hint = f"可选 workspace：{', '.join(choices)}；"
+        elif candidate_error:
+            hint = f"可选 workspace 列举失败：{candidate_error}；"
+        else:
+            hint = ""
+        hint += f"执行 ap dataset claim {dataset} --workspace <queue-id> --benchmark <benchmark>"
         raise _fail(
             f"dataset {dataset} 认领失败：服务端要求 workspace_id,但没给 --workspace",
-            "从上面的候选里挑一个：ap dataset claim "
-            f"{dataset} --workspace <queue-id> --benchmark <benchmark>",
+            hint,
             exit_code=2,
         )
 
@@ -1311,9 +1299,7 @@ def dataset_claim(
             require_benchmark=bool(benchmark_id),
         )
     except Exception as exc:  # noqa: BLE001 - 统一走设计 §5.1 的映射
-        code = getattr(exc, "biz_code", None)
-        if code is None:
-            code = _api_biz_code(exc)
+        code = _business_code(exc)
         if code == 92010:
             # 已被认领:以服务端 92010 为准(不本地推断),幂等 exit 0。
             owner = str(detail.get("owner") or "").strip()
@@ -1324,7 +1310,6 @@ def dataset_claim(
                 except Exception:  # noqa: BLE001 - 取不到 owner 不影响幂等退出
                     owner = ""
             owner = owner or "<unknown>"
-            _note(f"dataset {dataset} 已被认领(owner={owner}),无需重复认领")
             _emit_detail(
                 {
                     "dataset": dataset,
@@ -1422,7 +1407,13 @@ def dataset_access_grant(
         try:
             repo.datasets.revoke(dataset, principal_id, stale, principal_type=resolved_type)
         except Exception as exc:  # noqa: BLE001
-            if getattr(exc, "biz_code", None) != 24401:
+            code = _business_code(exc)
+            if code == 92011:
+                raise _fail(
+                    f"dataset {dataset} 旧角色 {stale} 撤销失败：{_reason(exc)}",
+                    _last_admin_hint(dataset),
+                ) from exc
+            if code != 24401:
                 raise _fail(
                     f"dataset {dataset} 旧角色 {stale} 撤销失败：{_reason(exc)}",
                     f"先手动撤销：ap dataset access revoke {dataset} "
@@ -1430,19 +1421,14 @@ def dataset_access_grant(
                 ) from exc
         else:
             replaced.append(stale)
-            _note(f"已撤销 {principal_id} 在 {dataset} 上的旧角色 {stale}")
 
     already = False
     try:
         repo.datasets.grant(dataset, principal_id, resolved_role, principal_type=resolved_type)
     except Exception as exc:  # noqa: BLE001 - 统一走设计 §5.1 的映射
-        code = getattr(exc, "biz_code", None)
+        code = _business_code(exc)
         if code == 24404:
             already = True
-            _note(
-                f"dataset {dataset} 上 {principal_id} 的 {resolved_role} 绑定已存在"
-                f"（{_reason(exc)}）"
-            )
         elif code == 24402:
             raise _fail(
                 f"dataset {dataset} 授权失败：入参非法（{_reason(exc)}）",
@@ -1516,7 +1502,6 @@ def dataset_access_revoke(
             if row["role"] in _ROLE_IDS
         ]
         if not targets:
-            _note(f"dataset {dataset} 上 {principal_id} 已无绑定,无需撤销")
             _emit_detail(
                 {
                     "dataset": dataset,
@@ -1536,14 +1521,9 @@ def dataset_access_revoke(
         try:
             repo.datasets.revoke(dataset, principal_id, target, principal_type=resolved_type)
         except Exception as exc:  # noqa: BLE001 - 统一走设计 §5.1 的映射
-            code = getattr(exc, "biz_code", None)
+            code = _business_code(exc)
             if code == 24401:
-                # 幂等:目标态已达成(设计 §5.1),不用 error: 前缀。
                 missing.append(target)
-                _note(
-                    f"dataset {dataset} 上 {principal_id} 的 {target} 绑定不存在,"
-                    f"已处于目标状态（{_reason(exc)}）"
-                )
                 continue
             if code == 24402:
                 raise _fail(
@@ -1551,6 +1531,11 @@ def dataset_access_revoke(
                     "检查工号/用户组 id 与 --principal-type 是否匹配",
                     exit_code=2,
                 ) from exc
+            if code == 92011:
+                raise _fail(
+                    f"dataset {dataset} 撤销 {target} 失败：{_reason(exc)}",
+                    _last_admin_hint(dataset),
+                ) from exc
             raise _fail(
                 f"dataset {dataset} 撤销 {target} 失败：{_reason(exc)}",
                 "撤销需要 dataset-admin;确认该环境已开启 dataset RBAC",
@@ -1615,37 +1600,6 @@ def dataset_version_list(
         ) from exc
 
     records = [_model_dict(record) for record in (getattr(result, "items", None) or [])]
-    if not records:
-        # 空结果常见根因是元数据 environment 不匹配(version 落在另一个 env),
-        # 探测一遍并引导切换,而不是只回一张空表。
-        _note_environment_distribution(
-            repo,
-            dataset,
-            lambda env: (
-                _pagination_total(
-                    _pagination_envelope(
-                        repo.versions.list_paged(
-                            dataset,
-                            status=resolved_status or None,
-                            page=1,
-                            page_size=1,
-                            environment=env,
-                        )
-                    ),
-                    fallback=0,
-                )
-                or 0
-            ),
-            what="version",
-        )
-    if records and all(
-        "split_count" not in record and "instance_count" not in record for record in records
-    ):
-        # 旧 SDK(1.0.9.dev0 及以前)的版本列表投影丢服务端统计字段:如实说明,不静默空列。
-        _note(
-            "已安装的 instance-repo 未返回版本统计(split_count/instance_count),"
-            "SPLITS/INSTANCES 两列为空;升级到 1.1.0 及以上可恢复"
-        )
     rows = [_version_row(record) for record in records]
     _emit(
         {"dataset": dataset, "versions": records, "pagination": _pagination_envelope(result)},
@@ -1673,10 +1627,15 @@ def dataset_version_get(
 def dataset_version_create(
     version: str = typer.Argument(..., help="Dataset version to create"),
     dataset: str = typer.Option(..., "--dataset", help="Dataset name"),
+    storage_path: Optional[str] = typer.Option(
+        None,
+        "--storage-path",
+        help="Explicit oss:// storage path (otherwise auto-computed from data-plane addressing)",
+    ),
     output_format: str = typer.Option(None, "--format", help=_FORMAT_HELP),
 ):
     """Create a draft version. storage_path is auto-computed from data-plane addressing."""
-    from .irepo_sdk import SdkMissing, load_repo, sdk_error_exit
+    from .irepo_sdk import SdkMissing, _is_addressing_failure, _reason, load_repo, sdk_error_exit
 
     output_format = _fmt(output_format)
     resolved = _version_value(version)
@@ -1694,9 +1653,19 @@ def dataset_version_create(
     except SdkMissing as exc:
         typer.echo(str(exc), err=True)
         raise typer.Exit(2) from exc
+    create_kwargs = {}
+    explicit_storage_path = str(storage_path or "").strip()
+    if explicit_storage_path:
+        create_kwargs["storage_path"] = explicit_storage_path
     try:
-        record = repo.versions.create(dataset, resolved)
+        record = repo.versions.create(dataset, resolved, **create_kwargs)
     except Exception as exc:  # noqa: BLE001 - 统一走设计 §5.1 的映射
+        if _is_addressing_failure(exc):
+            raise _fail(
+                f"dataset {dataset} 版本 {resolved} 创建失败：{_reason(exc)}",
+                "设置 AP_CLUSTER,或在命令前使用 ap --cluster <cluster>;"
+                "也可传 --storage-path oss://<bucket>/<prefix>/",
+            ) from exc
         sdk_error_exit(exc, what=f"dataset {dataset} 版本 {resolved}", stage="创建")
     # 与 ``version get`` 同一个视图:同一个对象在两个命令里字段集、字段顺序、空值处理
     # 必须一致(``to_dict()`` 原样输出会把 SDK 补的 False/[]/{} 也打出来)。
@@ -1746,7 +1715,11 @@ def dataset_split_list(
 
     if resolved_version:
         detail = _fetch_version(
-            dataset, resolved_version, stage="split 查询", environment=environment
+            dataset,
+            resolved_version,
+            stage="split 查询",
+            environment=environment,
+            metadata_model=_VERSION_SPLIT_METADATA_MODEL,
         )
         records = _split_records(detail)
         rows = [_split_row(record, detail) for record in records]
@@ -1755,27 +1728,6 @@ def dataset_split_list(
         rows = [_split_row(record, {}) for record in records]
     if resolved_run_type:
         rows = [row for row in rows if str(row["run_type"]).lower() == resolved_run_type]
-    if not rows and not resolved_run_type:
-        # 空结果常见根因是元数据 environment 不匹配,探测一遍并引导切换。
-        probe_repo = _dataset_repo()
-        if resolved_version:
-
-            def _probe(env: str) -> int:
-                try:
-                    detail = probe_repo.versions.get(dataset, resolved_version, environment=env)
-                except Exception:  # noqa: BLE001 - 该 env 没有这个版本
-                    return -1
-                return len(_split_records(_model_dict(detail)))
-
-        else:
-
-            def _probe(env: str) -> int:
-                page = probe_repo.splits.list(
-                    dataset, version_scope="unversioned", page_size=1, environment=env
-                )
-                return _pagination_total(_pagination_envelope(page), fallback=0) or 0
-
-        _note_environment_distribution(probe_repo, dataset, _probe, what="split")
     _emit(
         {"dataset": dataset, "version": resolved_version, "splits": rows},
         rows,
@@ -1798,7 +1750,11 @@ def dataset_split_get(
 
     if resolved_version:
         detail = _fetch_version(
-            dataset, resolved_version, stage="split 查询", environment=environment
+            dataset,
+            resolved_version,
+            stage="split 查询",
+            environment=environment,
+            metadata_model=_VERSION_SPLIT_METADATA_MODEL,
         )
         for record in _split_records(detail):
             if str(record.get("name") or "") == split:
@@ -1863,20 +1819,22 @@ def dataset_split_create(
         )
 
     detail = _fetch_version(
-        dataset, resolved_version, stage="split 创建前查询", environment=environment
+        dataset,
+        resolved_version,
+        stage="split 创建前查询",
+        environment=environment,
+        metadata_model=_VERSION_SPLIT_METADATA_MODEL,
     )
 
     existing = _split_names(detail)
     if split in existing:
         # 幂等:已存在同名 split(设计 §4.3)。
-        _note(f"dataset {dataset} 版本 {_version_label(resolved_version)} 已有 split {split}")
-        if resolved_run_type:
-            _note(f"要改 run_type 请用：ap dataset split update {split} --dataset {dataset}")
         for record in _split_records(detail):
             if str(record.get("name") or "") == split:
                 payload = dict(record)
                 payload.setdefault("dataset", dataset)
                 payload.setdefault("version", resolved_version)
+                payload["created"] = False
                 _emit_detail(payload, output_format)
                 return
         _emit_detail(
@@ -1893,6 +1851,7 @@ def dataset_split_create(
         {"splits": names},
         stage="split 创建",
         environment=environment,
+        metadata_model=_VERSION_SPLIT_METADATA_MODEL,
     )
 
     # ② run_type 只能第二次 PATCH:服务端 splits 与 split_run_types 互斥。
@@ -1910,6 +1869,7 @@ def dataset_split_create(
             # 第一段 PATCH 已建出 split,失败后的恢复动作是补打 run_type,不是重跑 create。
             fallback_hint=f"split {split} 已创建但 run_type 未设置,补打：{retry}",
             environment=environment,
+            metadata_model=_VERSION_SPLIT_METADATA_MODEL,
         )
 
     _emit_detail(
@@ -1949,8 +1909,9 @@ def dataset_split_update(
     resolved_run_type = _check_choice(run_type, _RUN_TYPES, "--run-type")
 
     if not resolved_version:
-        # 无版本空间改 run_type 走 recordsvc 的 split 记录(PATCH /datasets/splits/detail),
-        # 服务端**显式** pre 会 400;缺省不下发(SDK 不带该参数 → 服务端按 online 处理)。
+        # 无版本空间改 run_type 走 recordsvc 的 split 记录(PATCH /datasets/splits/detail):
+        # 写端点仅限 online——SDK 1.1.2 起派生/显式 pre 都会前置 SchemaError 拒绝,
+        # 不再出现"存在性检查读 pre、写入默默落 online"的读写环境撕裂。
         env = _environment(environment)
         if env == "pre":
             raise _fail(
@@ -1997,7 +1958,11 @@ def dataset_split_update(
         return
 
     detail = _fetch_version(
-        dataset, resolved_version, stage="split 更新前查询", environment=environment
+        dataset,
+        resolved_version,
+        stage="split 更新前查询",
+        environment=environment,
+        metadata_model=_VERSION_SPLIT_METADATA_MODEL,
     )
 
     if split not in _split_names(detail):
@@ -2015,6 +1980,7 @@ def dataset_split_update(
         {"split_run_types": [{"name": split, "run_type": resolved_run_type}]},
         stage="split 更新",
         environment=environment,
+        metadata_model=_VERSION_SPLIT_METADATA_MODEL,
     )
     _emit_detail(
         {

{ap_client-0.3.1.dev2 → ap_client-0.3.2}/ap_client/fs_commands.py

@@ -13,7 +13,7 @@
 
 1. ``--user`` 是**空间归主的工号**,不是被授权人;``fs access grant/revoke`` 的
    被授权主体用 ``--principal``。``--principal`` 优先;只给了 ``--user`` 时把它
-   当被授权主体、空间归主取当前用户,并在 stderr 说明这次解释。
+   当被授权主体、空间归主取当前用户,结果中的 owner/principal 字段反映最终解释。
 2. 数据面寻址(含 ACL 资源 id 里的 storage_env)对客屏蔽:用户只需配 AP 基础环境
    变量(``AP_CLUSTER`` / ``AP_API_KEY``),storage_env 由 SDK 依据 cluster 自动发现
    (``repo.profile.storage_env``)。CLI 只把它用于**回显** ``{storage_env}/{uid}``,
@@ -99,10 +99,6 @@ def _fail(message: str, hint: str, exit_code: int = 1) -> "typer.Exit":
     return typer.Exit(exit_code)
 
 
-def _note(message: str) -> None:
-    typer.echo(f"note: {message}", err=True)
-
-
 def _describe(exc: BaseException) -> str:
     message = getattr(exc, "message", None)
     text = str(message or "").strip() or str(exc).strip()
@@ -462,10 +458,6 @@ def _resolve_principal(repo, *, user: Optional[str], principal: Optional[str]) -
             exit_code=2,
         )
     owner = _resolve_uid(repo, None)
-    _note(
-        f"--principal 未给：把 --user={fallback} 当作被授权主体，"
-        f"空间归主取当前工号 {owner}；要授权别人的空间请显式写 --user <归主> --principal <主体>"
-    )
     return owner, fallback
 
 
@@ -508,7 +500,6 @@ def fs_access_grant(
         if not is_already_satisfied(exc):
             sdk_error_exit(exc, what=f"用户存储空间 {owner} 的授权", stage="授予")
         already = True
-        _note(f"用户存储空间 {owner} 上 {grantee} 的 {resolved_role} 绑定已存在：{_describe(exc)}")
 
     _emit_detail(
         {
@@ -583,7 +574,6 @@ def fs_access_revoke(
     if per_role and not targets:
         targets = _roles_of(repo, owner, grantee, resolved_type, subpath)
         if not targets:
-            _note(f"用户存储空间 {owner} 上 {grantee} 没有任何绑定,无需撤销")
             _emit_detail(
                 _revoke_payload(owner, storage_env, resolved_type, grantee, subpath, [], []),
                 output_format,
@@ -610,7 +600,6 @@ def fs_access_revoke(
             if not is_already_satisfied(exc):
                 sdk_error_exit(exc, what=f"用户存储空间 {owner} 的授权", stage="撤销")
             missing.append(target or "*")
-            _note(f"用户存储空间 {owner} 上 {grantee} 的绑定本就不存在：{_describe(exc)}")
         else:
             revoked.append(target or "*")
 

{ap_client-0.3.1.dev2 → ap_client-0.3.2}/ap_client/instance_commands.py

@@ -24,6 +24,7 @@ from __future__ import annotations
 
 import inspect
 import shutil
+import tempfile
 from pathlib import Path
 from typing import Any, List, Optional
 
@@ -120,11 +121,6 @@ def _fail(message: str, hint: str, exit_code: int = 1) -> "typer.Exit":
     return typer.Exit(exit_code)
 
 
-def _note(message: str) -> None:
-    """退出码 0 的路径只用 ``note:``(设计 §5.1);一律 stderr。"""
-    typer.echo(f"note: {message}", err=True)
-
-
 def _load_repo_or_exit():
     """懒加载 SDK;缺 extra → 安装提示 + 退出码 2(设计 §2)。"""
     from .irepo_sdk import SdkMissing, load_repo
@@ -136,6 +132,25 @@ def _load_repo_or_exit():
         raise typer.Exit(2) from exc
 
 
+def _probe_pull_private_endpoint(repo: Any, dataset: str) -> bool | None:
+    content = getattr(repo, "_content", None)
+    instances = getattr(repo, "instances", None)
+    credentials = getattr(content, "_credentials", None)
+    probe = getattr(content, "_probe_private_endpoint", None)
+    layout_factory = getattr(instances, "_layout", None)
+    if not all(callable(value) for value in (credentials, probe, layout_factory)):
+        return None
+
+    from instance_repo._routing import _plan_oss_route
+
+    layout = layout_factory()
+    sts = credentials(layout.sts_prefix(dataset), dataset)
+    route = _plan_oss_route(sts.get("endpoint", ""))
+    if not route.standard:
+        return None
+    return bool(probe(route.private_endpoint))
+
+
 #: SDK ``instance_repo.validate.detect_format`` 的取值 → 对应校验函数名。分派必须与 SDK
 #: ``InstancesClient.validate`` 一致;认不出的格式回退 ``check_layout``(与 SDK 同样的兜底)。
 _VALIDATOR_BY_FORMAT: dict[str, str] = {
@@ -217,12 +232,7 @@ def _describe(exc: BaseException) -> str:
 
 
 def _sdk_read_kwargs(sdk_obj: Any, method: str, *, environment: str, metadata_model: str) -> dict:
-    """按 SDK 能力决定是否下发 environment / metadata_model。
-
-    ``environment`` / ``metadata_model`` 的按调用覆盖是 ``feat/apcli-dataset`` 起才有的
-    (1.1.0 前只有分支构建带);用已发布的旧 SDK 时这里不下发,并在 stderr 如实说明读的是
-    profile 派生的集合——而不是让它抛 TypeError,也不是静默读错集合。
-    """
+    """按 SDK 能力下发 environment / metadata_model，不允许静默忽略显式值。"""
     fn = getattr(sdk_obj, method, None)
     accepted: set[str] = set()
     if fn is not None:
@@ -245,10 +255,10 @@ def _sdk_read_kwargs(sdk_obj: Any, method: str, *, environment: str, metadata_mo
         elif value:
             dropped.append(key)
     if dropped:
-        # 只有真正丢弃了调用方给的值才提示;无条件打印会暗示"想指定却被忽略"。
-        _note(
-            "已安装的 instance-repo 不支持按调用指定 "
-            f"{'/'.join(dropped)},本次按 profile 派生值读取;需要精确指定请升级到 1.1.0 及以上"
+        raise _fail(
+            f"已安装的 instance-repo 不支持按调用指定 {'/'.join(dropped)}",
+            "升级到 instance-repo 1.1.2 及以上后重试",
+            exit_code=2,
         )
     return kwargs
 
@@ -394,6 +404,12 @@ def instance_list(
     output_format = _fmt(output_format)
     resolved_version = _version_value(version)
     repo = _load_repo_or_exit()
+    read_kwargs = _sdk_read_kwargs(
+        repo.instances,
+        "list_paged",
+        environment=_environment(environment),
+        metadata_model=_metadata_model_for_split(metadata_model, split=split),
+    )
     try:
         result = repo.instances.list_paged(
             dataset,
@@ -401,12 +417,7 @@ def instance_list(
             split=split,
             page=page,
             page_size=page_size,
-            **_sdk_read_kwargs(
-                repo.instances,
-                "list_paged",
-                environment=_environment(environment),
-                metadata_model=_metadata_model_for_split(metadata_model, split=split),
-            ),
+            **read_kwargs,
         )
     except Exception as exc:  # noqa: BLE001 - 统一走设计 §5.1 的映射
         raise _fail(
@@ -445,18 +456,19 @@ def instance_get(
     output_format = _fmt(output_format)
     resolved_version = _version_value(version)
     repo = _load_repo_or_exit()
+    read_kwargs = _sdk_read_kwargs(
+        repo.instances,
+        "get",
+        environment=_environment(environment),
+        metadata_model=_metadata_model_for_split(metadata_model, split=split),
+    )
     try:
         record = repo.instances.get(
             dataset,
             resolved_version,
             instance,
             split=split,
-            **_sdk_read_kwargs(
-                repo.instances,
-                "get",
-                environment=_environment(environment),
-                metadata_model=_metadata_model_for_split(metadata_model, split=split),
-            ),
+            **read_kwargs,
         )
     except Exception as exc:  # noqa: BLE001 - 统一走设计 §5.1 的映射
         raise _fail(
@@ -499,7 +511,6 @@ def _confirm_version_autocreate(repo, dataset: str, version: str, split: str, *,
 
     label = _version_label(version)
     if yes:
-        _note(f"版本 {label} 不存在,上传时将由服务端自动创建(已用 --yes 跳过确认)")
         return
     if not sys.stdin.isatty():
         raise _fail(
@@ -559,6 +570,7 @@ def instance_push(
     pushed: list[dict] = []
     failed: list[dict] = []
     unconfirmed: list[str] = []
+    result_count_mismatch = False
     if len(targets) == 1:
         try:
             result = repo.instances.push(
@@ -609,15 +621,18 @@ def instance_push(
             )
         else:
             results_list = list(results_many or [])
-            if len(results_list) != len(targets):
-                _note(
-                    f"SDK 返回了 {len(results_list)}/{len(targets)} 个上传结果,摘要可能不完整;"
-                    f"用 ap instance list --dataset {dataset} --split {split} 核对实际内容"
-                )
+            result_count_mismatch = len(results_list) != len(targets)
+            if len(results_list) < len(targets):
+                unconfirmed.extend(targets[len(results_list) :])
             for path, result in zip(targets, results_list):
                 pushed.append(_push_row(path, result))
 
     _print_push_summary(dataset, resolved, split, pushed, failed, unconfirmed, output_format)
+    if result_count_mismatch:
+        raise _fail(
+            f"SDK 返回了 {len(results_list)}/{len(targets)} 个上传结果,无法确认完整写入状态",
+            f"用 ap instance list --dataset {dataset} --split {split} 核对实际内容",
+        )
 
 
 def _push_row(path: str, result: Any) -> dict:
@@ -691,19 +706,46 @@ def instance_pull(
 
     repo = _load_repo_or_exit()
     try:
-        root.mkdir(parents=True, exist_ok=True)
-        written = repo.instances.pull(dataset, resolved, instance, root, split)
+        private_endpoint_reachable = _probe_pull_private_endpoint(repo, dataset)
     except Exception as exc:  # noqa: BLE001
-        sdk_error_exit(exc, what=f"instance {instance}", stage="拉取")
+        sdk_error_exit(exc, what=f"instance {instance}", stage="拉取前私网探测")
+    if private_endpoint_reachable is False:
+        raise _fail(
+            f"instance {instance} 拉取失败：当前网络无法访问私网 OSS endpoint",
+            "instance pull 不支持公网下载;请在 AP dev cluster / ROCK VPC 内执行",
+        )
 
-    written = _place_under_target(Path(str(written)), target)
+    # SDK 的 swe/custom 下载会先往输出目录写 <id>.json 与 .probe 中间文件,再由
+    # _place_under_target 搬进 <id>/——把用户目录直接交给它,未加 --overwrite 也会
+    # 覆盖目标同级的同名文件。先落到独立临时目录,归一后再整体搬入最终目标。
+    staging = Path(tempfile.mkdtemp(prefix=f"ap-pull-{instance}-"))
+    try:
+        try:
+            written = repo.instances.pull(dataset, resolved, instance, staging, split)
+        except Exception as exc:  # noqa: BLE001
+            sdk_error_exit(exc, what=f"instance {instance}", stage="拉取")
+        staged = _place_under_target(Path(str(written)), staging / instance)
+        root.mkdir(parents=True, exist_ok=True)
+        if target.exists():
+            if not overwrite:
+                raise _fail(
+                    f"instance {instance} 拉取目标 {target} 已存在",
+                    "换一个 --output/-o 目录,或加 --overwrite 允许覆盖",
+                )
+            if target.is_dir():
+                shutil.rmtree(target)
+            else:
+                target.unlink()
+        shutil.move(str(staging / instance), str(target))
+    finally:
+        shutil.rmtree(staging, ignore_errors=True)
     payload = {
         "instance": instance,
         "dataset": dataset,
         "version": resolved,
         "split": split,
         "output": str(target),
-        "content": str(written),
+        "content": str(target / staged.name),
     }
     _emit_detail(payload, output_format)
 

{ap_client-0.3.1.dev2 → ap_client-0.3.2}/ap_client/irepo_sdk.py

@@ -24,19 +24,20 @@
   cluster 概念。
 
 因此 :func:`load_repo` 用 ``inspect.signature`` 做一次能力探测:签名支持的参数
-显式传入,不支持的回退为进程内环境变量注入(不覆盖用户已设的值),并向 stderr
-提示升级。
+显式传入,不支持的回退为进程内环境变量注入(不覆盖用户已设的值)。
 """
 
 from __future__ import annotations
 
 import inspect
+import json
 import os
+import time
 from typing import TYPE_CHECKING, Any, NoReturn
 
 import typer
 
-from .config import Config, _parse_bool
+from .config import _parse_bool, get_config
 
 if TYPE_CHECKING:  # pragma: no cover - 仅供类型检查,运行时不 import SDK
     from instance_repo import Repo
@@ -59,14 +60,6 @@ _INSTALL_HINT = (
     "Install it with: pip install 'ap-client[dataset]'"
 )
 
-#: 旧 SDK(无 ``api_base``/``cluster`` 构造参数)时的升级提示,一行 stderr。
-_LEGACY_SDK_NOTE = (
-    "note: installed instance-repo does not accept Repo(api_base=/cluster=); "
-    "falling back to INSTANCEREPO_* environment injection. "
-    "Upgrade with: pip install -U 'instance-repo[oss]>=1.1.0' "
-    "for cluster<->storage_env validation and symmetric read/write paths."
-)
-
 # storage_env 解析顺序:显式参数 > 规范环境变量(1.0.0) > 旧别名(0.8.x)。
 # **没有默认值**——猜一个 storage_env 会把数据写到错误的存储环境。
 _STORAGE_ENV_VARS = ("INSTANCE_REPO_STORAGE_ENV", "IR_STORAGE_ENV")
@@ -128,6 +121,97 @@ def _setdefault_env(name: str, value: str) -> None:
         os.environ[name] = value
 
 
+def _sdk_log_value(raw: bytes | str | None, cfg: Any) -> str:
+    if raw is None:
+        return ""
+    text = raw.decode("utf-8", errors="replace") if isinstance(raw, bytes) else raw
+    try:
+        value = json.loads(text)
+    except (TypeError, ValueError):
+        if cfg.verbose_redaction:
+            return "<non-JSON body omitted>"
+        rendered = text
+    else:
+        from .api import _redact_sensitive_data, _safe_json
+
+        value = _redact_sensitive_data(value, cfg.verbose_redaction)
+        if cfg.verbose_redaction:
+            value = _redact_sdk_tokens(value)
+        rendered = _safe_json(value)
+    if cfg.verbose_full_body or len(rendered) <= cfg.verbose_body_limit:
+        return rendered
+    return rendered[: cfg.verbose_body_limit] + "..."
+
+
+def _redact_sdk_tokens(value: Any) -> Any:
+    if isinstance(value, dict):
+        redacted = {}
+        for key, item in value.items():
+            normalized = str(key).lower().replace("_", "").replace("-", "")
+            redacted[key] = (
+                "<redacted>" if normalized.endswith("token") else _redact_sdk_tokens(item)
+            )
+        return redacted
+    if isinstance(value, list):
+        return [_redact_sdk_tokens(item) for item in value]
+    return value
+
+
+def _instrument_sdk_transport(transport: Any, cfg: Any) -> bool:
+    sender = getattr(transport, "_send", None)
+    if not callable(sender):
+        return False
+
+    from .api import _redact_headers, _redact_url_query_secrets, _safe_json, _write_stderr
+
+    def logged_send(method: str, url: str, headers: dict, body: bytes | None, timeout: float):
+        shown_url = _redact_url_query_secrets(url) if cfg.verbose_redaction else url
+        lines = [
+            f">> Request {method} {shown_url}",
+            f"   headers={_safe_json(_redact_headers(headers, cfg.verbose_redaction))}",
+        ]
+        if body is not None:
+            lines.extend((f"   body_size={len(body)}", f"   body={_sdk_log_value(body, cfg)}"))
+        _write_stderr(lines)
+        started = time.perf_counter()
+        try:
+            status, text = sender(method, url, headers, body, timeout)
+        except Exception as exc:
+            duration_ms = (time.perf_counter() - started) * 1000
+            _write_stderr(
+                [
+                    f"!! Error {method} {shown_url}",
+                    f"   duration_ms={duration_ms:.1f}",
+                    f"   error={type(exc).__name__}: {exc}",
+                ]
+            )
+            raise
+        duration_ms = (time.perf_counter() - started) * 1000
+        encoded = text.encode("utf-8", errors="replace")
+        response_lines = [
+            f"<< Response {method} {shown_url}",
+            f"   status={status}",
+            f"   duration_ms={duration_ms:.1f}",
+            f"   body_size={len(encoded)}",
+        ]
+        if text:
+            response_lines.append(f"   body={_sdk_log_value(text, cfg)}")
+        _write_stderr(response_lines)
+        return status, text
+
+    transport._send = logged_send
+    return True
+
+
+def _verbose_sdk_transport(cfg: Any, api_env: str) -> Any | None:
+    try:
+        from instance_repo.transport import Transport
+    except ImportError:
+        return None
+    transport = Transport(cfg.base_url, cfg.token_key or "", env=api_env)
+    return transport if _instrument_sdk_transport(transport, cfg) else None
+
+
 def load_repo(*, cluster: str | None = None, storage_env: str | None = None) -> "Repo":
     """按 AP ``Config`` 构造 ``instance_repo.Repo``。
 
@@ -150,7 +234,10 @@ def load_repo(*, cluster: str | None = None, storage_env: str | None = None) ->
 
     # 多 key 的 AP_API_KEYS 在这里直接抛 ConfigurationError:数据面要用这把 key 去
     # 换 STS,拿不到确定的单 key 就没法继续(与控制面同一口径)。
-    cfg = Config.from_env(cluster=cluster if cluster is not None else _api._cluster_override)
+    cfg = get_config(
+        verbose=_api._verbose_override,
+        cluster=cluster if cluster is not None else _api._cluster_override,
+    )
 
     effective_cluster = _cluster_from_headers(cfg.headers)
     effective_storage_env = _resolve_storage_env(storage_env)
@@ -168,13 +255,16 @@ def load_repo(*, cluster: str | None = None, storage_env: str | None = None) ->
         kwargs["storage_env"] = effective_storage_env
     if "api_env" in supported and api_env:
         kwargs["api_env"] = api_env
+    if cfg.verbose and "transport" in supported:
+        transport = _verbose_sdk_transport(cfg, api_env)
+        if transport is not None:
+            kwargs["transport"] = transport
 
     if "api_base" not in supported or "cluster" not in supported:
         # 0.8.x 兼容路径:构造参数缺位,只能退回环境变量契约。
         _setdefault_env(_LEGACY_API_BASE_VAR, cfg.base_url)
         _setdefault_env(_LEGACY_TOKEN_VAR, cfg.token_key or "")
         _setdefault_env(_LEGACY_STORAGE_ENV_VAR, effective_storage_env)
-        typer.echo(_LEGACY_SDK_NOTE, err=True)
 
     return _Repo(**kwargs)
 
@@ -191,7 +281,9 @@ def _init_parameters(repo_cls: type) -> frozenset[str]:
             continue
         if parameter.kind is inspect.Parameter.VAR_KEYWORD:
             # **kwargs 会吞下任何参数,当作全部支持(1.0.0 之后的宽松签名)。
-            return frozenset({"token", "api_base", "cluster", "storage_env", "api_env"})
+            return frozenset(
+                {"token", "api_base", "cluster", "storage_env", "api_env", "transport"}
+            )
         if parameter.kind is not inspect.Parameter.VAR_POSITIONAL:
             names.add(name)
     return frozenset(names)
@@ -216,7 +308,7 @@ _BIZ_CODE_RULES: dict[int, tuple[str, int]] = {
     ),
     94018: ("当前角色只读,写操作需要 writer 角色;让 admin 执行 ap dataset access grant", 1),
     94019: ("dataset 标识冲突：检查 --dataset 的取值是否与已有 dataset 重名", 1),
-    94020: ("请求未带 dataset 标识(SDK 过旧),升级：pip install -U 'instance-repo[oss]>=1.1.0'", 1),
+    94020: ("请求未带 dataset 标识(SDK 过旧),升级：pip install -U 'instance-repo[oss]>=1.1.2'", 1),
     94021: ("该 dataset 不存在,先执行：ap dataset create <dataset> --benchmark <b>", 1),
     94022: (
         "无该用户存储空间的授权,让空间主人执行：ap fs access grant --user <你的工号> --role reader",
@@ -238,7 +330,7 @@ _CODE_RULES: dict[str, tuple[str, int]] = {
     "E_DIGEST_MISMATCH": ("内容校验失败,重新拉取或重新打包该 instance 后再试", 1),
     "E_IMMUTABLE": ("已发布的版本不可修改,创建新版本再操作", 1),
     "E_FORBIDDEN": ("当前身份无权执行该操作,确认 AP_API_KEY 与 dataset 角色", 1),
-    "E_OWNER_REF_MISSING": ("缺少上游来源引用,升级：pip install -U 'instance-repo[oss]>=1.1.0'", 1),
+    "E_OWNER_REF_MISSING": ("缺少上游来源引用,升级：pip install -U 'instance-repo[oss]>=1.1.2'", 1),
     "E_LAYOUT": ("instance 目录结构不合规,先执行 ap instance validate <path> 定位问题", 1),
     "E_SCHEMA": ("instance 元数据不符合 schema,先执行 ap instance validate <path> 定位问题", 1),
     "E_CRED_EXPIRED": ("临时凭据已过期,重试该命令即可重新换取", 1),
@@ -259,6 +351,7 @@ _ADDRESSING_FIELDS = (
     "oss_prefix",
     "scaffold_bucket",
     "scaffold_root",
+    "storage_path",
 )
 _ADDRESSING_HINT = (
     "当前 AP 集群未下发数据面存储配置,确认 AP_CLUSTER 指向支持 dataset 的集群,或联系 Dataset 管理员"
@@ -297,24 +390,20 @@ def update_version_detail(
     body: dict,
     *,
     environment: str,
+    metadata_model: str = "",
 ) -> None:
-    """``PATCH /apis/v1/datasets/versions/detail``,显式下发 ``environment``。
-
-    为什么不用 ``repo.versions.update``(临时 shim,已反馈 SDK):它内部用
-    ``_version_extra_q()`` **无参**调用,只能下发 profile 派生值(dev/staging 集群
-    → ``pre``);而 CLI 的读路径与 ``versions.create`` 都在 ``online``,于是出现
-    "``version get`` 找得到、PATCH 却 404 dataset version not found"。SDK 的
-    ``get``/``list_paged``/``create``/``ingest`` 都接受显式 ``environment``,
-    只有 ``update``/``status`` 没有。SDK 补上参数后这里会自动改走 SDK 方法。
-    """
+    """``PATCH /apis/v1/datasets/versions/detail`` with explicit routing selectors."""
     update = repo.versions.update
     try:
         accepted = inspect.signature(update).parameters
     except (TypeError, ValueError):  # pragma: no cover - 内建/装饰过的可调用
         accepted = {}
-    if "environment" in accepted:
-        # 空值不传:让 SDK 按 profile 派生(与其它读路径同口径,见 dataset_commands._environment)
-        kwargs = dict(body, **({"environment": environment} if environment else {}))
+    if "environment" in accepted and "metadata_model" in accepted:
+        kwargs = dict(body)
+        if environment:
+            kwargs["environment"] = environment
+        if metadata_model:
+            kwargs["metadata_model"] = metadata_model
         update(dataset, version, **kwargs)
         return
 
@@ -323,6 +412,8 @@ def update_version_detail(
     query = f"dataset_name={quote(dataset, safe='')}&version={quote(version, safe='')}"
     if environment:
         query += f"&environment={quote(environment, safe='')}"
+    if metadata_model:
+        query += f"&metadata_model={quote(metadata_model, safe='')}"
     repo.transport.patch(f"/apis/v1/datasets/versions/detail?{query}", dict(body))
 
 
@@ -349,23 +440,17 @@ def _resolve_rule(exc: Exception) -> tuple[str, int]:
 
 
 def sdk_error_exit(exc: Exception, *, what: str, stage: str) -> NoReturn:
-    """把 SDK 异常翻译成固定两行文案 + ``typer.Exit``。
-
-    非零退出走 ``error: <what> <stage>失败:<reason>``;设计 §5.1 里判定为幂等
-    (24401/24404,已达目标态)的码退出 0,此时首行改用 ``note:``——把"成功"
-    印成 ``error:`` 会让脚本与人都误判。第二行恒为 ``hint: <可执行下一步>``。
+    """把 SDK 异常翻译成 ``error:`` / ``hint:`` 文案与 ``typer.Exit``。
 
-    ``-v/--verbose`` 时额外打印完整调用栈;默认不把 SDK traceback 当输出。
+    设计 §5.1 里判定为幂等的 24401/24404 直接以 0 退出；非零失败输出固定
+    ``error: <what> <stage>失败:<reason>`` 与可执行 ``hint:``。
     """
     hint, exit_code = _resolve_rule(exc)
-    reason = _reason(exc)
-    if exit_code == 0:
-        typer.echo(f"note: {what} {stage}：{reason}", err=True)
-    else:
-        typer.echo(f"error: {what} {stage}失败：{reason}", err=True)
-    typer.echo(f"hint: {hint}", err=True)
-    if _is_verbose():
-        import traceback
+    if exit_code != 0:
+        typer.echo(f"error: {what} {stage}失败：{_reason(exc)}", err=True)
+        typer.echo(f"hint: {hint}", err=True)
+        if _is_verbose():
+            import traceback
 
-        traceback.print_exception(type(exc), exc, exc.__traceback__)
+            traceback.print_exception(type(exc), exc, exc.__traceback__)
     raise typer.Exit(exit_code)

{ap_client-0.3.1.dev2 → ap_client-0.3.2}/ap_client/split_publish.py

@@ -8,7 +8,7 @@ from typing import Optional
 
 import typer
 
-from .dataset_commands import _emit_detail, _fail, _fmt, _note
+from .dataset_commands import _emit_detail, _fail, _fmt
 
 #: SDK 等待循环返回后不再变化的状态;其余视为等待超时。
 _TERMINAL = ("succeeded", "failed", "canceled", "awaiting_approval")
@@ -93,7 +93,6 @@ def dataset_split_publish(
     if not workflow_id:
         raise _fail("发布响应缺少 workflow id", "重跑同一命令可安全重试")
     hint = f"ap dataset split publish-status {workflow_id}"
-    _note(f"发布工作流：{workflow_id}；查询进度：{hint}")
     _emit_detail(workflow, fmt)
 
     status = str(workflow.get("status") or "")
@@ -107,8 +106,6 @@ def dataset_split_publish(
     if status not in _TERMINAL:
         # 等待窗口内未到终态:SDK 返回最后一帧,服务端工作流不受影响。
         raise _fail("发布等待超时,服务端工作流仍继续运行", hint)
-    if status == "awaiting_approval":
-        _note("发布工作流等待审批,尚未完成发布；审批信息见 approval 字段")
 
 
 def dataset_split_publish_status(
@@ -132,5 +129,3 @@ def dataset_split_publish_status(
             f"发布工作流 {workflow_id} {status}：{(workflow or {}).get('error_msg') or ''}",
             "检查输出中的 steps 和 outputs,修正失败原因后再提交发布",
         )
-    if status == "awaiting_approval":
-        _note("发布工作流等待审批,尚未完成发布；审批信息见 approval 字段")

{ap_client-0.3.1.dev2 → ap_client-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ap-client"
-version = "0.3.1.dev2"
+version = "0.3.2"
 description = "Agent Platform API Client & CLI"
 readme = { text = "A lightweight Python SDK and command line interface for Agent Platform. It provides helpers for configuring API access and managing templates, datasets, jobs, and groups.", content-type = "text/markdown" }
 requires-python = ">=3.10"
@@ -18,10 +18,10 @@ dependencies = [
 
 [project.optional-dependencies]
 dataset = [
-    "instance-repo[oss]>=1.1.0",
+    "instance-repo[oss]>=1.1.2,<2.0.0",
 ]
 all = [
-    "instance-repo[oss]>=1.1.0",
+    "instance-repo[oss]>=1.1.2,<2.0.0",
 ]
 
 [project.scripts]