ap-client 0.3.1.dev1__tar.gz → 0.3.2.dev0__tar.gz

{ap_client-0.3.1.dev1 → ap_client-0.3.2.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ap-client
-Version: 0.3.1.dev1
+Version: 0.3.2.dev0
 Summary: Agent Platform API Client & CLI
 Requires-Python: >=3.10
 Requires-Dist: pyyaml>=6.0

{ap_client-0.3.1.dev1 → ap_client-0.3.2.dev0}/ap_client/api.py

@@ -294,24 +294,6 @@ def _secret_ws_params(workspace_id: Optional[str]) -> Optional[dict]:
     return {"workspace_id": workspace_id} if workspace_id else None
 
 
-def _unwrap_data(payload: Any) -> Any:
-    """Unwrap the apiserver ``{code,message,data}`` envelope when present.
-
-    The dataset-domain detail/create/patch endpoints return a bare JSON body,
-    but the same handlers are occasionally wrapped by the generic success
-    envelope. Tolerate both so command code never has to branch: a mapping that
-    carries ``data`` alongside ``code``/``message`` is treated as an envelope,
-    anything else is returned verbatim.
-    """
-    if (
-        isinstance(payload, dict)
-        and "data" in payload
-        and ("code" in payload or "message" in payload)
-    ):
-        return payload["data"]
-    return payload
-
-
 def _split_paged(payload: Any) -> tuple[list[dict], dict]:
     """Split a ``PagedSuccess`` envelope into ``(records, pagination)``.
 

{ap_client-0.3.1.dev1 → ap_client-0.3.2.dev0}/ap_client/cli.py

@@ -815,26 +815,45 @@ def _print_json_block(data: Any) -> None:
     typer.echo(json.dumps(data, ensure_ascii=False, indent=2))
 
 
+def _format_nested_detail(value: Any) -> str:
+    """Nested dict/list for detail views: compact one-liner, pretty JSON when long.
+
+    A detail view must not silently drop data - the manifest in ``ap instance
+    get`` used to be cut mid-JSON by the one-liner preview.
+    """
+    compact = json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+    if len(compact) <= _PLAIN_VALUE_PREVIEW:
+        return compact
+    return json.dumps(value, ensure_ascii=False, indent=2)
+
+
 def _print_detail(data: object) -> None:
     """Render a single object as an aligned key/value detail view.
 
     Top-level scalars become key/value rows (``image`` fields shortened); nested
-    dict/list fields are shown as compact one-liners. Falls back to JSON for
+    dict/list fields are shown as compact one-liners, or pretty-printed across
+    multiple lines when the one-liner would not fit. Falls back to JSON for
     non-dict payloads.
     """
     if not isinstance(data, dict):
         _print_json(data)
         return
-    scalar_rows: list[tuple[str, Any]] = []
-    nested_rows: list[tuple[str, Any]] = []
+    rows: list[tuple[str, str]] = []
     for key, value in data.items():
         if isinstance(value, (dict, list)):
-            nested_rows.append((key, value))
+            rows.append((key, _format_nested_detail(value)))
         elif key == "image" and isinstance(value, str):
-            scalar_rows.append((key, _shorten_image(value)))
+            rows.append((key, _shorten_image(value)))
+        elif value is None:
+            continue
         else:
-            scalar_rows.append((key, value))
-    _print_key_values(scalar_rows + nested_rows, skip_empty=False)
+            rows.append((key, _format_plain_value(value, max_len=0)))
+    width = max((len(label) for label, _text in rows), default=0)
+    indent = " " * (width + 4)
+    for label, text in rows:
+        if "\n" in text:
+            text = text.replace("\n", f"\n{indent}")
+        typer.echo(f"  {label.ljust(width)}: {text}")
 
 
 def _print_template_get_plain(t: dict) -> None:
@@ -944,7 +963,7 @@ def _print_field_value(value: Any, output_format: str) -> None:
     _print_formatted(value, "json" if output_format == "plain" else output_format)
 
 
-def _format_plain_value(value: Any) -> str:
+def _format_plain_value(value: Any, *, max_len: int = _PLAIN_VALUE_PREVIEW) -> str:
     if value is None:
         return ""
     if isinstance(value, (dict, list)):
@@ -952,9 +971,9 @@ def _format_plain_value(value: Any) -> str:
     else:
         text = str(value)
     text = text.replace("\r", "\\r").replace("\n", "\\n")
-    if len(text) <= _PLAIN_VALUE_PREVIEW:
+    if not max_len or len(text) <= max_len:
         return text
-    return f"{text[: _PLAIN_VALUE_PREVIEW - 3]}..."
+    return f"{text[: max_len - 3]}..."
 
 
 def _print_key_values(rows: list[tuple[str, Any]], *, skip_empty: bool = True) -> None:

{ap_client-0.3.1.dev1 → ap_client-0.3.2.dev0}/ap_client/dataset_commands.py

@@ -17,6 +17,8 @@ import typer
 if TYPE_CHECKING:  # pragma: no cover - 仅用于类型标注,运行时不 import
     from datetime import datetime
 
+    from instance_repo import Repo
+
 __all__ = [
     "dataset_version_app",
     "dataset_split_app",
@@ -118,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``)。
@@ -153,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":
@@ -166,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()
@@ -410,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 能力,请联系管理员",
@@ -420,7 +433,7 @@ _DATASET_CODE_HINTS: dict[int, str] = {
 }
 
 
-def _resolve_benchmark_id(repo: Any, value: str) -> str:
+def _resolve_benchmark_id(repo: "Repo", value: str) -> str:
     """``--benchmark`` 接受名称或 ``source_id``,统一解析成 ``source_id``(设计 §9)。
 
     走 SDK ``benchmarks``:先按 source_id 点查,再按名称模糊搜一遍精确比对
@@ -522,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 的报错必须点明"无版本空间"语义。
 
@@ -536,10 +554,18 @@ 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 = f"确认版本名：ap dataset version list --dataset {dataset}"
+            hint = (
+                f"确认版本名：ap dataset version list --dataset {dataset}"
+                ";版本也可能在另一个元数据 environment,加 --environment online/pre 重试"
+            )
         else:
             hint = f"{_NO_VERSION_NOTE};要操作具体版本请加 --version <version>"
         raise _fail(
@@ -634,7 +660,7 @@ def _split_names(detail: dict) -> list[str]:
     return names
 
 
-def _dataset_repo() -> Any:
+def _dataset_repo() -> "Repo":
     """dataset 写路径统一走 InstanceRepo SDK;未装 ``dataset`` extra 时退出 2。"""
     from .irepo_sdk import SdkMissing, load_repo
 
@@ -653,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 单键。
 
@@ -664,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:
@@ -800,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
@@ -888,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:
@@ -901,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:
@@ -935,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
 
@@ -1001,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
@@ -1017,11 +1040,44 @@ 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 摘要表的列。
+_ENVIRONMENT_SUMMARY_COLUMNS: tuple[tuple[str, str], ...] = (
+    ("environment", "ENVIRONMENT"),
+    ("versions", "VERSIONS"),
+    ("splits", "SPLITS"),
+    ("latest_version", "LATEST_VERSION"),
+)
+
+
+def _print_dataset_environments(repo: "Repo", dataset: str, detail: dict) -> None:
+    """``dataset get`` 尾部按 environment 汇总 version/split,告诉用户该去哪个 env 指定。
+
+    仅人读视图(plain/table)追加;``json``/``yaml`` 恒为服务端原样。单个 env 读失败
+    (旧 SDK 不接受 environment、权限差异)显示 ``?``,不影响主输出。
+    """
+    envs = [str(env).strip() for env in detail.get("available_envs") or [] if str(env).strip()]
+    if not envs:
+        return
+    rows: list[dict] = []
+    for env in envs:
+        try:
+            env_detail = _model_dict(repo.datasets.get_detail(dataset, environment=env))
+        except Exception:  # noqa: BLE001 - 摘要尽力而为
+            rows.append({"environment": env, "versions": "?", "splits": "?", "latest_version": "?"})
+            continue
+        rows.append(
+            {
+                "environment": env,
+                "versions": env_detail.get("version_count", ""),
+                "splits": env_detail.get("split_count", ""),
+                "latest_version": env_detail.get("latest_version") or "",
+            }
+        )
+    typer.echo("\nEnvironments (add --environment <env> to target one)")
+    _print_table(rows, _ENVIRONMENT_SUMMARY_COLUMNS, "plain")
 
 
 def dataset_get(
@@ -1032,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()
@@ -1042,12 +1105,10 @@ def dataset_get(
             f"dataset {dataset} 查询失败：{_reason(exc)}",
             f"确认 dataset 名称：ap dataset list --query {dataset}",
         ) from exc
-    _emit_detail(
-        _model_dict(detail),
-        output_format,
-        order=_DATASET_DETAIL_ORDER,
-        always=("status",),
-    )
+    rendered = _model_dict(detail)
+    _emit_detail(rendered, output_format, order=_DATASET_DETAIL_ORDER, always=("status",))
+    if output_format not in ("json", "yaml"):
+        _print_dataset_environments(repo, dataset, rendered)
 
 
 def dataset_create(
@@ -1182,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,
@@ -1198,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,
         )
 
@@ -1230,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()
@@ -1243,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,
@@ -1341,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} "
@@ -1349,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)}）",
@@ -1435,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,
@@ -1455,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(
@@ -1470,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",
@@ -1534,14 +1600,6 @@ def dataset_version_list(
         ) from exc
 
     records = [_model_dict(record) for record in (getattr(result, "items", None) or [])]
-    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)},
@@ -1569,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)
@@ -1590,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/[]/{} 也打出来)。
@@ -1642,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]
@@ -1673,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:
@@ -1738,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(
@@ -1768,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 互斥。
@@ -1785,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(
@@ -1872,14 +1957,16 @@ 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):
         known = ", ".join(_split_names(detail)) or "<无>"
         hint = f"先创建：ap dataset split create {split} --dataset {dataset}(现有：{known})"
-        if not resolved_version:
-            hint = f"{hint}；{_NO_VERSION_NOTE}"
         raise _fail(
             f"dataset {dataset} 版本 {_version_label(resolved_version)} split {split} "
             f"更新失败：不存在",
@@ -1892,6 +1979,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.dev1 → ap_client-0.3.2.dev0}/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.dev1 → ap_client-0.3.2.dev0}/ap_client/instance_commands.py

@@ -120,11 +120,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 +131,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 +231,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:
@@ -237,14 +246,18 @@ def _sdk_read_kwargs(sdk_obj: Any, method: str, *, environment: str, metadata_mo
                 accepted.add(name)
 
     kwargs: dict[str, str] = {}
+    dropped: list[str] = []
     for key, value in (("environment", environment), ("metadata_model", metadata_model)):
         # 空值不下发:CLI 不替 SDK 决定 metadata_model(见 dataset_commands._metadata_model)。
         if key in accepted and value:
             kwargs[key] = value
-    if "environment" not in accepted:
-        _note(
-            "已安装的 instance-repo 不支持按调用指定 environment/metadata_model,"
-            "本次按 profile 派生值读取;需要精确指定请升级到 1.1.0 及以上"
+        elif value:
+            dropped.append(key)
+    if dropped:
+        raise _fail(
+            f"已安装的 instance-repo 不支持按调用指定 {'/'.join(dropped)}",
+            "升级到 instance-repo 1.1.0 及以上后重试",
+            exit_code=2,
         )
     return kwargs
 
@@ -390,6 +403,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,
@@ -397,12 +416,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(
@@ -441,18 +455,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(
@@ -467,9 +482,12 @@ def instance_get(
     _emit_detail(_instance_record(record), output_format)
 
 
+def _confirm_version_autocreate(repo, dataset: str, version: str, split: str, *, yes: bool) -> None:
+    """version 不存在时 push 会触发服务端自动创建;要求二次确认(可 ``-y/--yes`` 跳过)。
 
-def _confirm_version_autocreate(dataset: str, version: str, split: str, *, yes: bool) -> None:
-    """version 不存在时 push 会触发服务端自动创建;要求二次确认(可 ``-y/--yes`` 跳过)。"""
+    ``repo`` 由调用方构造并复用:``Repo.__init__`` 会做一次 best-effort 的
+    repo-config 自动发现(HTTP),确认与推送共用一个实例,不重复触网。
+    """
     import sys
 
     from .dataset_commands import _env_kwargs, _environment, _version_label
@@ -478,7 +496,6 @@ def _confirm_version_autocreate(dataset: str, version: str, split: str, *, yes:
     if not str(version or "").strip():
         # 无版本空间:没有"版本会被自动创建"这回事(数据面由 ingest 处理)。
         return
-    repo = _load_repo_or_exit()
     try:
         repo.versions.get(dataset, version, **_env_kwargs(_environment(None)))
     except Exception as exc:  # noqa: BLE001 - 统一走设计 §5.1 的映射
@@ -493,7 +510,6 @@ def _confirm_version_autocreate(dataset: str, version: str, split: str, *, yes:
 
     label = _version_label(version)
     if yes:
-        _note(f"版本 {label} 不存在,上传时将由服务端自动创建(已用 --yes 跳过确认)")
         return
     if not sys.stdin.isatty():
         raise _fail(
@@ -547,13 +563,13 @@ def instance_push(
     # ② 版本不存在时 push 会在服务端自动创建;先确认,避免误建。
     #   (split 已发布不可写由**服务端**裁决——pre 环境里 ingest 产出的 split 记录状态
     #    就是 published,客户端按它预判会把正常的二次上传全拦掉。)
-    _confirm_version_autocreate(dataset, resolved, split, yes=yes)
-
-    # ③ 数据面推送。
+    # ③ 数据面推送(repo 只构造一次,确认与推送复用,见 _confirm_version_autocreate)。
     repo = _load_repo_or_exit()
+    _confirm_version_autocreate(repo, dataset, resolved, split, yes=yes)
     pushed: list[dict] = []
     failed: list[dict] = []
     unconfirmed: list[str] = []
+    result_count_mismatch = False
     if len(targets) == 1:
         try:
             result = repo.instances.push(
@@ -603,10 +619,19 @@ def instance_push(
                 exc, what=f"dataset {dataset} 的 {len(targets)} 个 instance", stage="上传"
             )
         else:
-            for path, result in zip(targets, list(results_many or [])):
+            results_list = list(results_many or [])
+            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:
@@ -679,6 +704,16 @@ def instance_pull(
         )
 
     repo = _load_repo_or_exit()
+    try:
+        private_endpoint_reachable = _probe_pull_private_endpoint(repo, dataset)
+    except Exception as exc:  # noqa: BLE001
+        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 内执行",
+        )
+
     try:
         root.mkdir(parents=True, exist_ok=True)
         written = repo.instances.pull(dataset, resolved, instance, root, split)

{ap_client-0.3.1.dev1 → ap_client-0.3.2.dev0}/ap_client/irepo_sdk.py

@@ -24,24 +24,31 @@
   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
 
-__all__ = ["SdkMissing", "is_already_satisfied", "load_repo", "sdk_error_exit"]
+__all__ = [
+    "SdkMissing",
+    "is_already_satisfied",
+    "load_repo",
+    "sdk_error_exit",
+    "update_version_detail",
+]
 
 #: 数据集元数据的环境枚举(服务端 ``dataset environment``)。
 DATASET_ENVIRONMENTS = ("online", "pre")
@@ -53,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.0.9' "
-    "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")
@@ -122,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``。
 
@@ -144,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)
@@ -162,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)
 
@@ -185,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)
@@ -210,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.0.9'", 1),
+    94020: ("请求未带 dataset 标识(SDK 过旧),升级：pip install -U 'instance-repo[oss]>=1.1.0'", 1),
     94021: ("该 dataset 不存在,先执行：ap dataset create <dataset> --benchmark <b>", 1),
     94022: (
         "无该用户存储空间的授权,让空间主人执行：ap fs access grant --user <你的工号> --role reader",
@@ -232,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.0.9'", 1),
+    "E_OWNER_REF_MISSING": ("缺少上游来源引用,升级：pip install -U 'instance-repo[oss]>=1.1.0'", 1),
     "E_LAYOUT": ("instance 目录结构不合规,先执行 ap instance validate <path> 定位问题", 1),
     "E_SCHEMA": ("instance 元数据不符合 schema,先执行 ap instance validate <path> 定位问题", 1),
     "E_CRED_EXPIRED": ("临时凭据已过期,重试该命令即可重新换取", 1),
@@ -253,6 +351,7 @@ _ADDRESSING_FIELDS = (
     "oss_prefix",
     "scaffold_bucket",
     "scaffold_root",
+    "storage_path",
 )
 _ADDRESSING_HINT = (
     "当前 AP 集群未下发数据面存储配置,确认 AP_CLUSTER 指向支持 dataset 的集群,或联系 Dataset 管理员"
@@ -291,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
 
@@ -317,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))
 
 
@@ -343,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.dev1 → ap_client-0.3.2.dev0}/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")
@@ -44,7 +44,10 @@ def dataset_split_publish(
     if not yes:
         if not sys.stdin.isatty():
             raise _fail("非交互发布需要确认", "加 --yes 确认将该 split 发布到 online", 2)
-        if not typer.confirm(f"Publish {dataset}/{resolved_version}/{split} to online?"):
+        target = (
+            f"{dataset}/{resolved_version}/{split}" if resolved_version else f"{dataset}/{split}"
+        )
+        if not typer.confirm(f"Publish {target} to online?"):
             raise _fail("发布已取消,未提交工作流", "确认后重跑", 1)
 
     try:
@@ -90,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 "")
@@ -104,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(
@@ -129,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.dev1 → ap_client-0.3.2.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ap-client"
-version = "0.3.1.dev1"
+version = "0.3.2.dev0"
 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"