ap-client 0.6.1.dev12__tar.gz → 0.7.0__tar.gz

{ap_client-0.6.1.dev12 → ap_client-0.7.0}/PKG-INFO

@@ -1,18 +1,18 @@
 Metadata-Version: 2.5
 Name: ap-client
-Version: 0.6.1.dev12
+Version: 0.7.0
 Summary: Agent Platform API Client & CLI
 Requires-Python: >=3.10
-Requires-Dist: irepo-artifact==0.2.2
+Requires-Dist: irepo-artifact==0.2.4
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: requests>=2.28.0
 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]<2.0.0,>=1.4.1.dev0; extra == 'all'
+Requires-Dist: instance-repo[oss]<2.0.0,>=1.4.0; extra == 'all'
 Provides-Extra: dataset
-Requires-Dist: instance-repo[oss]<2.0.0,>=1.4.1.dev0; extra == 'dataset'
+Requires-Dist: instance-repo[oss]<2.0.0,>=1.4.0; 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.6.1.dev12 → ap_client-0.7.0}/ap_client/cli.py

@@ -955,6 +955,25 @@ def _print_job_get_plain(job: dict) -> None:
         ]
     )
 
+    bindings = job.get("ak_bindings") or []
+    rows = [
+        {**parameter, "ak_id": binding["ak_id"]}
+        for binding in bindings
+        for parameter in binding.get("parameters", [])
+    ]
+    if "ak_bindings.parameters" in (job.get("restricted_fields") or []):
+        typer.echo("\nManaged AK parameters: content access required")
+    elif rows:
+        typer.echo("\nManaged AK parameters")
+        for row in rows:
+            typer.echo(f"  {row['parameter']}: {row['value']} -> {row['ak_id']}")
+        if any("parameters" not in binding for binding in bindings):
+            typer.echo("  Some historical parameter mappings are unavailable")
+    elif response_ak_ids(job):
+        typer.echo("\nManaged AK parameters: historical mapping unavailable")
+    elif "ak_bindings" in job:
+        typer.echo("\nManaged AK parameters\n  No managed AK used")
+
     meta_pairs = [
         ("meta_model", job.get("meta_model")),
         ("meta_job_type", job.get("meta_job_type")),

ap_client-0.7.0/ap_client/dataset_name.py

@@ -0,0 +1,104 @@
+"""DatasetName 解析 Adapter:唯一入口委托给已安装的 InstanceRepo SDK。
+
+AP CLI 不维护第三套 dataset 名解析:``instance_repo.paths.DatasetName`` 是客户端
+路径契约的唯一事实源(单段 ``A`` / 两段 ``A/B`` / 多段树形 ``A/B/C``,与
+apiserver 的 namespace guard 及 conformance 契约对齐)。SDK 缺失或过旧(没有
+``DatasetName.parse`` 能力)时,给出明确的升级提示,不静默降级、不本地重写解析规则。
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from typing import Any
+
+__all__ = [
+    "DatasetNameError",
+    "DatasetNameUpgradeRequired",
+    "parse_dataset_name",
+]
+
+#: SDK 缺失/无 DatasetName 能力时的升级提示(与 irepo_sdk 的 SdkMissing 同范式)。
+_UPGRADE_HINT = (
+    "The installed instance-repo SDK does not provide DatasetName parsing "
+    "(single-segment L1 dataset names need it).\n"
+    "Install it with: pip install 'ap-client[dataset]' --upgrade"
+)
+
+#: 多段(3+)名能力的首个 SDK 版本。旧 SDK(如 1.4.0)有 parse 但只认 1-2 段,
+#: 对多段名会抛"one or two canonical segments"——此时应提示升级而非报名称非法。
+_MULTI_LEVEL_SDK_VERSION = (1, 4, 1)
+
+
+def _sdk_supports_multi_level() -> bool:
+    """已安装 instance-repo 是否支持多段数据集名(>= 1.4.1)。版本不可读时保守视为不支持。"""
+    try:
+        from importlib.metadata import version
+
+        installed = version("instance-repo")
+    except Exception:  # noqa: BLE001 - 元数据缺失与旧 SDK 同等对待
+        return False
+    match = re.match(r"(\d+)\.(\d+)\.(\d+)", str(installed))
+    if not match:
+        return False
+    return tuple(int(part) for part in match.groups()) >= _MULTI_LEVEL_SDK_VERSION
+
+
+def _is_structurally_valid_multi_level(value: str) -> bool:
+    """值是否为"新 SDK 会接受"的 3+ 段名——即每个段都合法。
+
+    旧 SDK 对非法名(空段 a//b、非法字符 a*b)与多段名报同一文案,不能只按
+    段数判断:升级 SDK 也修不好空段/非法字符,必须保留原始校验错误。
+    这里保守复刻 SDK 的非法段规则作为 gate,只放行结构上合法的多段名。
+    """
+    parts = value.split("/")
+    if len(parts) < 3 or any(not part for part in parts):
+        return False
+    for part in parts:
+        if (
+            part in {".", ".."}
+            or "\\" in part
+            or "*" in part
+            or "?" in part
+            or any(unicodedata.category(char) == "Cc" for char in part)
+        ):
+            return False
+    return True
+
+
+class DatasetNameUpgradeRequired(RuntimeError):
+    """已安装的 instance-repo SDK 缺少 DatasetName 能力,必须升级。"""
+
+
+class DatasetNameError(ValueError):
+    """Dataset 名不符合 IR DatasetName 契约(单段或两段、无非法段)。"""
+
+
+def parse_dataset_name(value: str) -> Any:
+    """Parse ``value`` through the installed IR ``DatasetName`` capability.
+
+    Returns the SDK ``DatasetName`` (``canonical`` / ``l1`` / ``l2`` /
+    ``segments`` / ``leaf``)。Raises :class:`DatasetNameUpgradeRequired` when the
+    installed SDK lacks the capability (包括只认 1-2 段的旧 SDK 拒绝多段名);
+    raises :class:`DatasetNameError` when the value is not a valid name.
+    """
+    try:
+        from instance_repo.paths import DatasetName
+    except ImportError as exc:
+        raise DatasetNameUpgradeRequired(_UPGRADE_HINT) from exc
+    parse = getattr(DatasetName, "parse", None)
+    if not callable(parse):
+        raise DatasetNameUpgradeRequired(_UPGRADE_HINT)
+    try:
+        return parse(value)
+    except Exception as exc:  # noqa: BLE001 - SDK 校验失败统一转成 CLI 契约
+        # 旧 SDK(1.4.0 及更早)只认 1-2 段:结构上合法的多段名被拒时给出
+        # 升级提示。非法名(空段/非法字符)无论新旧 SDK 都拒绝,保留原始
+        # 校验错误为 DatasetNameError——升级修不好这类名称。
+        if (
+            isinstance(value, str)
+            and _is_structurally_valid_multi_level(value)
+            and not _sdk_supports_multi_level()
+        ):
+            raise DatasetNameUpgradeRequired(_UPGRADE_HINT) from exc
+        raise DatasetNameError(str(exc)) from exc

{ap_client-0.6.1.dev12 → ap_client-0.7.0}/ap_client/dfs_commands.py

@@ -272,13 +272,16 @@ def _fail(exc: Exception) -> None:
     if isinstance(exc, SdkMissing):
         typer.echo(str(exc), err=True)
         raise typer.Exit(2) from exc
-    message = str(exc) if isinstance(exc, ConfigurationError) else safe_error(exc)
+    input_errors = (OssUsageError, ConfigurationError, typer.BadParameter)
+    message = (
+        str(exc) if isinstance(exc, (ConfigurationError, typer.BadParameter)) else safe_error(exc)
+    )
     typer.echo("error: " + _display(message), err=True)
     if getattr(exc, "biz_code", None):
         typer.echo(f"hint: Check the Dataset access grant (API code {exc.biz_code})", err=True)
     elif getattr(exc, "code", None) == "AccessDenied":
         typer.echo("hint: Check the Dataset reader/writer grant for this operation", err=True)
-    raise typer.Exit(2 if isinstance(exc, (OssUsageError, ConfigurationError)) else 1) from exc
+    raise typer.Exit(2 if isinstance(exc, input_errors) else 1) from exc
 
 
 @dfs_app.command("ls")

{ap_client-0.6.1.dev12 → ap_client-0.7.0}/ap_client/fs_commands.py

@@ -39,6 +39,8 @@ from __future__ import annotations
 
 import inspect
 import os
+import sys
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Optional
 
@@ -270,6 +272,32 @@ def _user_data_prefix(uid: str) -> str:
     return f"swe/user-data/users/{uid}/"
 
 
+def _existing_policy(on_exist: str, overwrite: bool, skip_existing: bool):
+    policy = _check_choice(on_exist, ("prompt", "overwrite", "skip", "error"), "--on-exist")
+    if overwrite and skip_existing or (policy != "prompt" and (overwrite or skip_existing)):
+        raise _fail(
+            "Conflicting existing-file options",
+            "Choose one of --on-exist, --overwrite, --skip-existing",
+            2,
+        )
+    return "overwrite" if overwrite else "skip" if skip_existing else policy
+
+
+def _replace_existing(path: str, policy: str) -> bool:
+    if policy == "overwrite":
+        return True
+    if policy == "skip":
+        return False
+    if policy == "error" or not all(
+        stream.isatty() for stream in (sys.stdin, sys.stdout, sys.stderr)
+    ):
+        raise FileExistsError(
+            f"Destination already exists: {path}. Use --overwrite or --skip-existing; "
+            "interactive confirmation requires a terminal."
+        )
+    return typer.confirm(f"Overwrite {path}?", default=False, err=True)
+
+
 # ---------------------------------------------------------------------------
 # ap fs ls / get / put
 # ---------------------------------------------------------------------------
@@ -277,28 +305,116 @@ def _user_data_prefix(uid: str) -> str:
 
 @fs_app.command("ls")
 def fs_ls(
+    path: Optional[str] = typer.Argument(None, help="Directory to list (default: space root)"),
     directory: Optional[str] = typer.Option(None, "--dir", help="Sub-directory prefix"),
+    recursive: bool = typer.Option(False, "--recursive", "-R", help="List all descendants"),
+    all_entries: bool = typer.Option(
+        False, "--all", "-a", help="Include names starting with a dot"
+    ),
+    reverse: bool = typer.Option(False, "--reverse", "-r", help="Reverse name sort order"),
+    long: bool = typer.Option(
+        False, "--long", "-l", help="Show type, size in bytes and modified time"
+    ),
+    human_readable: bool = typer.Option(
+        False, "--human-readable", "-h", help="Use readable sizes with -l"
+    ),
+    sort: str = typer.Option(
+        "name", "--sort", help="Sort by name/size/time (size and time: largest/newest first)"
+    ),
+    directories_only: bool = typer.Option(False, "--dirs-only", help="Show directories only"),
+    files_only: bool = typer.Option(False, "--files-only", help="Show files only"),
+    limit: Optional[int] = typer.Option(
+        None, "--limit", min=1, help="Maximum number of displayed entries"
+    ),
     user: Optional[str] = typer.Option(None, "--user", help=_USER_HELP),
     output_format: str = typer.Option(None, "--format", help=_FORMAT_HELP),
 ):
-    """List objects under a user storage space."""
+    """List one directory level; use -R to include descendants."""
+    from .fs_storage import UserDataFiles
     from .irepo_sdk import sdk_error_exit
 
     output_format = _fmt(output_format)
+    sort = _check_choice(sort, ("name", "size", "time"), "--sort")
+    if path is not None and directory is not None:
+        raise _fail("Specify a path or --dir, not both", "Example: ap fs ls probe", 2)
+    if directories_only and files_only:
+        raise _fail("--dirs-only conflicts with --files-only", "Choose one type filter", 2)
+    directory = path if path is not None else directory or ""
     repo = _load_repo_or_exit()
     uid = _resolve_uid(repo, user)
     try:
-        keys = repo.list_user_data(uid, subpath=(directory or ""))
+        rows = UserDataFiles(repo).list(uid, directory, recursive=recursive)
     except Exception as exc:  # noqa: BLE001
         sdk_error_exit(exc, what=f"user storage {uid}", stage="list")
 
-    prefix = _user_data_prefix(uid)
-    rows = []
-    for key in list(keys or []):
-        text = str(key)
-        rows.append({"path": text[len(prefix) :] if text.startswith(prefix) else text, "key": text})
+    def visible(row):
+        return (
+            row.get("explicit", False)
+            or all_entries
+            or not any(part.startswith(".") for part in row["name"].split("/"))
+        )
+
+    rows = [
+        row
+        for row in rows
+        if visible(row)
+        and (not directories_only or row["type"] == "directory")
+        and (not files_only or row["type"] == "file")
+    ]
+    rows.sort(key=lambda row: row["path"])
+    if sort != "name":
+        field = "size" if sort == "size" else "modified"
+        rows.sort(key=lambda row: row[field] or 0, reverse=True)
+    if reverse:
+        rows.reverse()
+    if limit is not None:
+        rows = rows[:limit]
     payload = {"user": uid, "dir": directory or "", "files": rows}
-    _emit(payload, rows, (("path", "PATH"), ("key", "KEY")), output_format)
+    display_rows = []
+    for row in rows:
+        shown = dict(row)
+        size = row.get("size")
+        if human_readable and size is not None:
+            value = float(size)
+            for unit in ("B", "KiB", "MiB", "GiB", "TiB"):
+                if value < 1024 or unit == "TiB":
+                    shown["size"] = f"{value:g} {unit}"
+                    break
+                value /= 1024
+        if row.get("modified") is not None:
+            shown["modified"] = datetime.fromtimestamp(row["modified"], tz=timezone.utc).strftime(
+                "%Y-%m-%d %H:%M:%SZ"
+            )
+        display_rows.append(shown)
+    columns = (
+        (("name", "PATH"), ("type", "TYPE"), ("size", "BYTES"), ("modified", "MODIFIED"))
+        if long
+        else (("name", "PATH"),)
+    )
+    _emit(payload, display_rows, columns, output_format)
+
+
+@fs_app.command("mkdir")
+def fs_mkdir(
+    path: str = typer.Argument(..., help="Directory path inside the user storage space"),
+    parents: bool = typer.Option(
+        False, "--parents", "-p", help="Create missing parents; accept existing directories"
+    ),
+    user: Optional[str] = typer.Option(None, "--user", help=_USER_HELP),
+    output_format: str = typer.Option(None, "--format", help=_FORMAT_HELP),
+):
+    """Create an empty directory using an OSS directory marker."""
+    from .fs_storage import UserDataFiles
+    from .irepo_sdk import sdk_error_exit
+
+    output_format = _fmt(output_format)
+    repo = _load_repo_or_exit()
+    uid = _resolve_uid(repo, user)
+    try:
+        result = UserDataFiles(repo).mkdir(uid, path, parents=parents)
+    except Exception as exc:
+        sdk_error_exit(exc, what=f"user storage {uid} {path}", stage="mkdir")
+    _emit_detail({"user": uid, **result}, output_format)
 
 
 @fs_app.command("get")
@@ -309,6 +425,15 @@ def fs_get(
     target: Optional[str] = typer.Option(
         None, "--target", help="Local target path (default: the remote file name in CWD)"
     ),
+    overwrite: bool = typer.Option(
+        False, "--overwrite", "-f", help="Replace an existing destination"
+    ),
+    skip_existing: bool = typer.Option(
+        False, "--skip-existing", "-n", help="Keep existing destinations"
+    ),
+    on_exist: str = typer.Option(
+        "prompt", "--on-exist", help="Existing destination: prompt/overwrite/skip/error"
+    ),
     concurrency: int = typer.Option(
         8, "--concurrency", "-j", min=1, max=64, help="Maximum concurrent transfer requests"
     ),
@@ -324,23 +449,41 @@ def fs_get(
     from .irepo_sdk import sdk_error_exit
 
     output_format = _fmt(output_format)
+    policy = _existing_policy(on_exist, overwrite, skip_existing)
     repo = _load_repo_or_exit()
     uid = _resolve_uid(repo, user)
     remote = _remote_subpath(filepath, directory)
     local = Path(target) if target else Path(Path(remote).name)
-    if local.is_dir():
+    if local.is_dir() or (target and target.endswith("/")):
         local = local / Path(remote).name
+    skipped = False
     try:
+        if local.is_symlink():
+            raise ValueError("Download target must not be a symbolic link")
+        exists = local.exists()
+        if exists and not local.is_file():
+            raise ValueError("Download target must be a regular file")
+        skipped = exists and not _replace_existing(str(local), policy)
         if local.parent and str(local.parent) not in ("", "."):
             local.parent.mkdir(parents=True, exist_ok=True)
-        written = UserDataTransfer(repo, concurrency=concurrency, progress=progress).get(
-            uid, remote, local
+        written = (
+            str(local)
+            if skipped
+            else UserDataTransfer(repo, concurrency=concurrency, progress=progress).get(
+                uid, remote, local, overwrite=exists or policy == "overwrite"
+            )
         )
     except Exception as exc:  # noqa: BLE001
         sdk_error_exit(exc, what=f"user storage {uid} {remote}", stage="download")
 
     _emit_detail(
-        {"user": uid, "remote": remote, "local": str(written or local)},
+        {
+            "user": uid,
+            "remote": remote,
+            "local": str(written or local),
+            "downloaded": 0 if skipped else 1,
+            "skipped": int(skipped),
+        },
         output_format,
     )
 
@@ -353,7 +496,15 @@ def fs_put(
     source: Optional[str] = typer.Option(
         None, "--source", help="Local source path (default: <filepath> relative to CWD)"
     ),
-    overwrite: bool = typer.Option(False, "--overwrite", help="Allow overwriting remote objects"),
+    overwrite: bool = typer.Option(
+        False, "--overwrite", "-f", help="Allow overwriting remote objects"
+    ),
+    skip_existing: bool = typer.Option(
+        False, "--skip-existing", "-n", help="Keep existing remote objects"
+    ),
+    on_exist: str = typer.Option(
+        "prompt", "--on-exist", help="Existing destination: prompt/overwrite/skip/error"
+    ),
     concurrency: int = typer.Option(
         8, "--concurrency", "-j", min=1, max=64, help="Maximum concurrent transfer requests"
     ),
@@ -369,6 +520,7 @@ def fs_put(
     from .irepo_sdk import sdk_error_exit
 
     output_format = _fmt(output_format)
+    policy = _existing_policy(on_exist, overwrite, skip_existing)
     local = Path(source or filepath)
     if not local.exists():
         raise _fail(
@@ -381,21 +533,30 @@ def fs_put(
     uid = _resolve_uid(repo, user)
     remote = _remote_subpath(filepath, directory)
     is_dir = local.is_dir()
+    if filepath.endswith("/") and not is_dir:
+        remote = remote.rstrip("/") + "/" + local.name
     try:
         outcome: Any = UserDataTransfer(repo, concurrency=concurrency, progress=progress).put(
-            uid, local, remote, overwrite=overwrite
+            uid,
+            local,
+            remote,
+            overwrite=policy == "overwrite",
+            on_conflict=lambda key: _replace_existing(key, policy),
         )
     except Exception as exc:  # noqa: BLE001
         sdk_error_exit(exc, what=f"user storage {uid} {remote}", stage="upload")
 
-    uploaded = len(outcome) if isinstance(outcome, list) else 1
+    results = outcome if isinstance(outcome, list) else [outcome]
+    skipped = sum(isinstance(item, dict) and item.get("skipped", False) for item in results)
     _emit_detail(
         {
             "user": uid,
             "remote": remote,
             "local": str(local),
             "kind": "directory" if is_dir else "file",
-            "objects": uploaded,
+            "objects": len(results),
+            "uploaded": len(results) - skipped,
+            "skipped": skipped,
         },
         output_format,
     )

ap_client-0.7.0/ap_client/fs_storage.py

@@ -0,0 +1,146 @@
+"""Directory operations using the SDK's scoped OSS authorization and routing."""
+
+from __future__ import annotations
+
+from .fs_transfer import UserDataTransfer, _scope_denied
+
+
+class UserDataFiles(UserDataTransfer):
+    def list(self, uid: str, path: str = "", *, recursive: bool = False):
+        from instance_repo._routing import _OperationIntent
+
+        root = self.repo._user_data_prefix(uid)
+        prefix = root if path in ("", ".", "/") else self._key(uid, path) + "/"
+
+        def listing(bucket):
+            entries = {}
+            found = False
+            marker = ""
+            while True:
+                page = bucket.list_objects(
+                    prefix=prefix, delimiter="" if recursive else "/", marker=marker, max_keys=1000
+                )
+                found = found or bool(page.object_list or page.prefix_list)
+                for obj in page.object_list:
+                    if obj.key == prefix:
+                        continue
+                    kind = "directory" if obj.key.endswith("/") else "file"
+                    entries[obj.key] = dict(
+                        path=obj.key[len(root) :],
+                        name=obj.key[len(prefix) :],
+                        key=obj.key,
+                        type=kind,
+                        size=obj.size,
+                        modified=obj.last_modified,
+                    )
+                    if recursive:
+                        # OSS may have no marker object for a directory. Rebuild
+                        # its ancestors so -R --dirs-only includes these too.
+                        parts = obj.key[len(prefix) :].split("/")
+                        for depth in range(1, len(parts)):
+                            name = "/".join(parts[:depth]) + "/"
+                            key = prefix + name
+                            entries.setdefault(
+                                key,
+                                dict(
+                                    path=key[len(root) :],
+                                    name=name,
+                                    key=key,
+                                    type="directory",
+                                    size=None,
+                                    modified=None,
+                                ),
+                            )
+                for common in page.prefix_list:
+                    entries[common] = dict(
+                        path=common[len(root) :],
+                        name=common[len(prefix) :],
+                        key=common,
+                        type="directory",
+                        size=None,
+                        modified=None,
+                    )
+                if not page.is_truncated:
+                    break
+                if not page.next_marker or page.next_marker == marker:
+                    raise ValueError("OSS listing did not advance its pagination marker")
+                marker = page.next_marker
+            return list(entries.values()), found
+
+        try:
+            rows, found = self.content._execute_oss(
+                _OperationIntent.NON_DOWNLOAD, prefix, None, listing
+            )
+        except Exception as exc:
+            if prefix == root or not _scope_denied(exc):
+                raise
+            # A file-only grant need not permit listing the same-name directory.
+            rows, found = [], False
+        if found or prefix == root:
+            return rows
+        key = prefix.rstrip("/")
+
+        def file_entry(bucket):
+            if not bucket.object_exists(key):
+                raise FileNotFoundError(f"No such file or directory: {path}")
+            meta = bucket.head_object(key)
+            return [
+                dict(
+                    path=key[len(root) :],
+                    name=key.rsplit("/", 1)[-1],
+                    key=key,
+                    type="file",
+                    size=meta.content_length,
+                    modified=meta.last_modified,
+                    explicit=True,
+                )
+            ]
+
+        if path.endswith("/"):
+            raise FileNotFoundError(f"No such directory: {path}")
+        return self.content._execute_oss(_OperationIntent.NON_DOWNLOAD, key, None, file_entry)
+
+    def mkdir(self, uid: str, path: str, *, parents: bool = False):
+        from instance_repo._routing import _OperationIntent
+
+        clean = self.repo._clean_user_data_subpath(path)
+        segments = clean.split("/")
+        paths = ["/".join(segments[:i]) for i in range(1, len(segments) + 1)]
+
+        def exists(key):
+            return self.content._execute_oss(
+                _OperationIntent.NON_DOWNLOAD, key, None, lambda bucket: bucket.object_exists(key)
+            )
+
+        def directory_exists(key):
+            return self.content._execute_oss(
+                _OperationIntent.NON_DOWNLOAD,
+                key,
+                None,
+                lambda bucket: bool(bucket.list_objects(prefix=key, max_keys=1).object_list),
+            )
+
+        # Check all ancestors before creating any marker.
+        present = []
+        for part in paths:
+            key = self._key(uid, part)
+            if exists(key):
+                raise FileExistsError(f"A file already exists at {part}")
+            present.append(directory_exists(key + "/"))
+        if present[-1] and not parents:
+            raise FileExistsError(f"Directory already exists: {clean}; use --parents to keep it")
+        if not parents and not all(present[:-1]):
+            raise FileNotFoundError("Parent directory does not exist; use --parents/-p")
+        created = []
+        for part, found in zip(paths, present):
+            if found:
+                continue
+            key = self._key(uid, part) + "/"
+
+            def create(bucket, key=key):
+                if not bucket.object_exists(key):
+                    bucket.put_object(key, b"", headers={"x-oss-forbid-overwrite": "true"})
+
+            self.content._execute_oss(_OperationIntent.NON_DOWNLOAD, key, None, create)
+            created.append(part)
+        return {"path": clean, "created": created}

{ap_client-0.6.1.dev12 → ap_client-0.7.0}/ap_client/fs_transfer.py

@@ -6,6 +6,7 @@ import os
 import tempfile
 import threading
 from concurrent.futures import FIRST_COMPLETED, ThreadPoolExecutor, wait
+from dataclasses import replace
 from pathlib import Path
 
 from rich.console import Console
@@ -24,6 +25,25 @@ from .ossutil_io import OssOperationError, _WriteBucket
 PART_SIZE = 8 * 1024 * 1024
 
 
+def _visual_task(task):
+    # Rich treats total=0 as 0%. Count processed files for zero-byte work,
+    # while retaining actual bytes for DownloadColumn and speed calculation.
+    if task.total == 0:
+        count = task.fields["files_total"]
+        return replace(task, total=count or 1, completed=task.fields["files_done"] if count else 1)
+    return task
+
+
+class _TransferBar(BarColumn):
+    def render(self, task):
+        return super().render(_visual_task(task))
+
+
+class _TransferPercent(TaskProgressColumn):
+    def render(self, task):
+        return super().render(_visual_task(task))
+
+
 def _scope_denied(exc: Exception) -> bool:
     """Only explicit scope refusals allow a more specific authorization request."""
     seen = set()
@@ -43,12 +63,14 @@ class TransferProgress:
         console = Console(stderr=True, markup=False, highlight=False)
         self.display = Progress(
             TextColumn("{task.description}"),
-            BarColumn(),
-            TaskProgressColumn(),
+            _TransferBar(),
+            _TransferPercent(),
             DownloadColumn(),
             TransferSpeedColumn(),
             TimeRemainingColumn(),
-            TextColumn("files {task.fields[files_done]}/{task.fields[files_total]}"),
+            TextColumn(
+                "files {task.fields[files_done]}/{task.fields[files_total]} skipped {task.fields[skipped]}"
+            ),
             console=console,
             disable=not (console.is_terminal if enabled is None else enabled),
         )
@@ -57,6 +79,7 @@ class TransferProgress:
         self.sizes: dict[str, int] = {}
         self.done: dict[str, int] = {}
         self.files_done = 0
+        self.files_skipped = 0
         self.total_bytes = 0
         self.completed_bytes = 0
 
@@ -69,6 +92,7 @@ class TransferProgress:
             total=None if unknown else self.total_bytes,
             files_done=0,
             files_total=len(sizes),
+            skipped=0,
         )
         return self
 
@@ -100,6 +124,7 @@ class TransferProgress:
         with self.lock:
             self.known_total = True
             if skipped:
+                self.files_skipped += 1
                 # Skipped bytes were not transferred; do not inflate the speed.
                 self.total_bytes -= self.sizes[key]
                 self.sizes[key] = 0
@@ -115,6 +140,7 @@ class TransferProgress:
             completed=self.completed_bytes,
             total=self.total_bytes if self.known_total else None,
             files_done=self.files_done,
+            skipped=self.files_skipped,
         )
 
 
@@ -135,17 +161,23 @@ class UserDataTransfer:
             raise ValueError("uid must not be empty")
         return self.repo._user_data_prefix(uid) + self.repo._clean_user_data_subpath(path)
 
-    def put(self, uid: str, source: Path, remote: str, *, overwrite: bool = False):
+    def put(
+        self, uid: str, source: Path, remote: str, *, overwrite: bool = False, on_conflict=None
+    ):
         from instance_repo._routing import _OperationIntent
 
         source = Path(source)
         remote = self.repo._clean_user_data_subpath(remote)
         base = self._key(uid, remote)
         directory = source.is_dir()
+        if source.is_symlink():
+            raise ValueError("Symbolic link upload sources are not supported")
         files = []
         if directory:
             for root, dirs, names in os.walk(source):
                 dirs.sort()
+                if any((Path(root) / name).is_symlink() for name in dirs + names):
+                    raise ValueError("Symbolic links inside an upload directory are not supported")
                 for name in sorted(names):
                     local = Path(root) / name
                     key = self._key(
@@ -161,27 +193,33 @@ class UserDataTransfer:
         part_threads = max(1, self.concurrency // workers)
         report = TransferProgress("Uploading", self.progress).start(sizes)
         directory_scope = base.rstrip("/") + "/" if directory else None
+        conflict_lock = threading.Lock()
 
         def transfer(item):
             local, key = item
             write_started = False
+            allowed_overwrite = overwrite
             # Keep the SDK's resume records across failures and later invocations.
             store = self.oss.ResumableStore()
 
             def upload(bucket):
-                nonlocal write_started
+                nonlocal write_started, allowed_overwrite
                 if not overwrite and not write_started and bucket.object_exists(key):
-                    return {"key": key, "skipped": True}
+                    with conflict_lock:
+                        # Serialize prompts even when multiple workers find collisions.
+                        allowed_overwrite = bool(on_conflict(key)) if on_conflict else False
+                    if not allowed_overwrite:
+                        return {"key": key, "skipped": True}
                 write_started = True
                 self.oss.resumable_upload(
-                    _WriteBucket(bucket, overwrite),
+                    _WriteBucket(bucket, allowed_overwrite),
                     key,
                     str(local),
                     store=store,
                     num_threads=part_threads,
                     part_size=PART_SIZE,
                     multipart_threshold=PART_SIZE,
-                    headers={} if overwrite else {"x-oss-forbid-overwrite": "true"},
+                    headers={} if allowed_overwrite else {"x-oss-forbid-overwrite": "true"},
                     progress_callback=report.callback(key),
                 )
                 return {"key": key, "skipped": False}
@@ -251,12 +289,12 @@ class UserDataTransfer:
                 raise
         return outcomes
 
-    def get(self, uid: str, remote: str, target: Path) -> str:
+    def get(self, uid: str, remote: str, target: Path, *, overwrite: bool = True) -> str:
         from instance_repo._routing import _OperationIntent
 
         key = self._key(uid, remote)
         target = Path(target)
-        if target.exists() and not target.is_file():
+        if target.is_symlink() or (target.exists() and not target.is_file()):
             raise ValueError("Download target must be a regular file")
         target.parent.mkdir(parents=True, exist_ok=True)
         report = TransferProgress("Downloading", self.progress).start({key: 0}, unknown=True)
@@ -282,6 +320,10 @@ class UserDataTransfer:
 
             self.content._execute_oss(_OperationIntent.DOWNLOAD, key, None, download)
             partial.chmod(0o600)
-            os.replace(partial, target)
+            if overwrite:
+                os.replace(partial, target)
+            else:
+                # Atomically refuse a destination created since the CLI preflight.
+                os.link(partial, target)
             report.finish(key)
         return str(target)

{ap_client-0.6.1.dev12 → ap_client-0.7.0}/ap_client/instance_commands.py

@@ -709,7 +709,7 @@ def instance_push(
     prune: bool = typer.Option(
         False,
         "--prune",
-        help="After delivery, remove remote metadata absent from the supplied cases; OSS files remain",
+        help="Disabled: SDK safe pruning is unavailable; delete obsolete metadata explicitly",
     ),
     yes: bool = typer.Option(
         False,
@@ -1018,7 +1018,7 @@ def instance_pull(
     if private_endpoint_reachable is False:
         raise _fail(
             f"Failed to pull instance {instance}: the private OSS endpoint is unreachable from this network",
-            "instance pull does not support public download",
+            "instance pull does not support public download; run inside an AP dev cluster / ROCK VPC",
         )
 
     # SDK 的 swe/custom 下载会先往输出目录写 <id>.json 与 .probe 中间文件,再由

{ap_client-0.6.1.dev12 → ap_client-0.7.0}/ap_client/instance_options.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import inspect
 import json
-from importlib import metadata
 from pathlib import Path
 from typing import Any
 
@@ -75,14 +74,10 @@ def upload_hashes(records: list[dict], supplied: dict[str, str], skip: bool) ->
 
 
 def require_working_prune() -> None:
-    try:
-        version = metadata.version("instance-repo")
-    except metadata.PackageNotFoundError:
-        return
-    if version in {"1.3.5.dev1", "1.3.5.dev2"}:
-        raise ValueError(
-            f"instance-repo {version} cannot complete --prune; upgrade to a fixed SDK before uploading"
-        )
+    raise ValueError(
+        "--prune is disabled before uploading: instance-repo does not support safe pruning. "
+        "Upload without --prune; review and delete obsolete instance metadata explicitly."
+    )
 
 
 def progress_callback(completed: int, total: int, result: Any) -> None:

{ap_client-0.6.1.dev12 → ap_client-0.7.0}/ap_client/irepo_sdk.py

@@ -946,7 +946,7 @@ def load_repo(
             if request_timeout is not None:
                 transport.timeout = request_timeout
             kwargs["transport"] = transport
-    elif request_timeout is not None and "transport" in supported:
+    if request_timeout is not None and "transport" in supported and "transport" not in kwargs:
         # Inject a pre-configured Transport so the custom timeout is effective
         # from the very first HTTP call inside Repo.__init__ / _bind_dataset_profile.
         try:
@@ -1161,7 +1161,7 @@ _BIZ_CODE_RULES: dict[int, tuple[str, int]] = {
 # 字符串 ``code`` → (hint, 退出码)。SDK 的 ``InstanceRepoError.code``。
 _CODE_RULES: dict[str, tuple[str, int]] = {
     "E_PRIVATE_NETWORK_REQUIRED": (
-        "This operation requires private-network access; run inside an intranet environment",
+        "This operation requires private-network access; run inside an AP dev cluster / ROCK VPC",
         1,
     ),
     "E_DIGEST_MISMATCH": ("Content digest check failed; pull or repack the instance again", 1),
@@ -1195,7 +1195,9 @@ _CODE_RULES: dict[str, tuple[str, int]] = {
 }
 
 #: 无法归类时的兜底文案。
-_FALLBACK_HINT = "Rerun with -v/--verbose for the full traceback"
+_FALLBACK_HINT = (
+    "Rerun with -v/--verbose for the full traceback; contact the Agent Platform on-call if needed"
+)
 
 # 数据面寻址字段:``/apis/v1/repo-config`` 在当前 apiserver 里不存在(设计 §8.3),SDK 的
 # 自动发现是 best-effort、构造期不抛错,真正用到某字段时才由 ``bootstrap.require`` 抛

{ap_client-0.6.1.dev12 → ap_client-0.7.0}/ap_client/ossutil_io.py

@@ -7,6 +7,7 @@ import hashlib
 import json
 import os
 import re
+import stat
 import tempfile
 import time
 import unicodedata
@@ -300,9 +301,9 @@ class OssFiles:
 
         凭据请求携带 ``dataset_name``:普通调用方在控制面按它走 dataset RBAC(旧 prod
         构建也要求显式上下文)。ans:// 路径是 dataset 相对的,dataset 名就是最长前缀
-        (两段 L1/L2 优先,单段 L1 兜底);由于 ``A``(L1)与 ``A/B`` 可能同时是合法布局,
+        (任意深度的最长已注册前缀优先);由于 ``A``(L1)与 ``A/B`` 可能同时是合法布局,
         这里以**注册表为准**:候选按"最长优先"查注册,第一个命中者胜出;都未注册时退回
-        最长候选(系统白名单/平台管理员的 raw 路径与服务端的 list-only 发现都会校验
+        原有最多两段上下文(系统身份的 raw 路径与服务端的 list-only 发现都会校验
         claimed 命名空间,写操作仍由服务端拒绝)。结果按相对路径缓存,一次命令内多次
         签发只查一次。
         """
@@ -322,18 +323,16 @@ class OssFiles:
         segments = [segment for segment in relative.split("/") if segment]
         if not segments:
             return None
-        candidates = (
-            ["/".join(segments[:2]), segments[0]] if len(segments) >= 2 else [segments[0]]
-        )
+        # Validate each segment with the SDK. Older SDKs only parse one or two
+        # levels at a time; that limit must not truncate registry lookup paths.
         valid: list[str] = []
-        for candidate in candidates:
+        for index, segment in enumerate(segments):
             try:
-                parse_dataset_name(candidate)
+                parse_dataset_name(segment)
             except DatasetNameError:
-                # 段本身合法(``_relative`` 已挡空/./..、反斜杠、通配与控制字符),
-                # 这里只是防御 SDK 契约收紧;候选不合法就跳过,不整条失败。
-                continue
-            valid.append(candidate)
+                break
+            valid.append("/".join(segments[: index + 1]))
+        valid.reverse()
         if not valid:
             return None
         for candidate in valid:
@@ -344,8 +343,9 @@ class OssFiles:
                     raise
                 continue
             return candidate
-        # 无任何注册命中:退回最长候选,list-only 发现与写操作的授权判定交给服务端。
-        return valid[0]
+        # 未注册路径的 list-only 发现与写操作仍由服务端授权。
+        # Preserve the legacy raw-OSS discovery namespace when none is registered.
+        return valid[-2] if len(valid) >= 2 else valid[0]
 
     def _credentials(self, scope: str, permission: str, list_only: bool) -> dict:
         kwargs: dict[str, Any] = {}
@@ -559,7 +559,10 @@ class OssFiles:
     def cat(self, remote: RemotePath, output: Any) -> None:
         result = self.bucket(remote.key, "reader", private_only=True).get_object(remote.key)
         try:
-            while data := result.read(1024 * 1024):
+            from .ossutil_hash import _stored_content_stream
+
+            stream = _stored_content_stream(result)
+            while data := stream.read(1024 * 1024):
                 output.write(data)
         finally:
             result.resp.response.close()
@@ -654,11 +657,25 @@ class OssFiles:
             if target.exists() and not overwrite:
                 raise OssOperationError(f"Local target already exists: {target}; use --force")
             suffix = hashlib.sha256((remote.bucket + remote.key).encode()).hexdigest()[:16]
-            partial = target.with_name(f".ap-{target.name}-{suffix}.part")
-            for path in (partial, Path(str(partial) + ".tmp")):
-                fd = os.open(path, os.O_CREAT | os.O_WRONLY | getattr(os, "O_NOFOLLOW", 0), 0o600)
+            # oss2 creates random .tmp-* siblings, so protect their directory
+            # throughout the download, including interruptions and retries.
+            staging = target.with_name(f".ap-{target.name}-{suffix}.download")
+            staging.mkdir(mode=0o700, exist_ok=True)
+            directory_fd = os.open(
+                staging, os.O_RDONLY | os.O_DIRECTORY | getattr(os, "O_NOFOLLOW", 0)
+            )
+            try:
+                if os.fstat(directory_fd).st_uid != os.getuid():
+                    raise OssOperationError("Download staging directory must belong to this user")
+                os.fchmod(directory_fd, 0o700)
+            finally:
+                os.close(directory_fd)
+            partial = staging / "content.part"
+            fd = os.open(partial, os.O_CREAT | os.O_WRONLY | getattr(os, "O_NOFOLLOW", 0), 0o600)
+            try:
+                os.fchmod(fd, 0o600)
+            finally:
                 os.close(fd)
-                path.chmod(0o600)
             if self.byte_range is not None:
                 result = bucket.get_object(
                     remote.key,
@@ -682,13 +699,20 @@ class OssFiles:
                     part_size=self.part_size,
                     progress_callback=self._progress(remote.path, progress),
                 )
+            fd = os.open(partial, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
+            try:
+                if not stat.S_ISREG(os.fstat(fd).st_mode):
+                    raise OssOperationError("Download staging content must be a regular file")
+                os.fchmod(fd, 0o600)
+            finally:
+                os.close(fd)
             self._check_local_path(target)
             if overwrite:
                 os.replace(partial, target)
             else:
                 os.link(partial, target)
                 partial.unlink()
-            Path(str(partial) + ".tmp").unlink(missing_ok=True)
+            staging.rmdir()
 
     @staticmethod
     def _check_local_path(path: Path) -> None:

{ap_client-0.6.1.dev12 → ap_client-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ap-client"
-version = "0.6.1.dev12"
+version = "0.7.0"
 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"
@@ -14,15 +14,15 @@ dependencies = [
     "rich>=13.0.0",
     "PyYAML>=6.0",
     "websockets>=13.0",
-    "irepo-artifact==0.2.2",
+    "irepo-artifact==0.2.4",
 ]
 
 [project.optional-dependencies]
 dataset = [
-    "instance-repo[oss]>=1.4.1.dev0,<2.0.0",
+    "instance-repo[oss]>=1.4.0,<2.0.0",
 ]
 all = [
-    "instance-repo[oss]>=1.4.1.dev0,<2.0.0",
+    "instance-repo[oss]>=1.4.0,<2.0.0",
 ]
 
 [project.scripts]

ap_client-0.6.1.dev12/ap_client/dataset_name.py

@@ -1,53 +0,0 @@
-"""DatasetName 解析 Adapter:唯一入口委托给已安装的 InstanceRepo SDK。
-
-AP CLI 不维护第三套 dataset 名解析:``instance_repo.paths.DatasetName`` 是客户端
-路径契约的唯一事实源(单段 ``A`` / 两段 ``A/B`` / 多段树形 ``A/B/C``,与
-apiserver 的 namespace guard 及 conformance 契约对齐)。SDK 缺失或过旧(没有
-``DatasetName.parse`` 能力)时,给出明确的升级提示,不静默降级、不本地重写解析规则。
-"""
-
-from __future__ import annotations
-
-from typing import Any
-
-__all__ = [
-    "DatasetNameError",
-    "DatasetNameUpgradeRequired",
-    "parse_dataset_name",
-]
-
-#: SDK 缺失/无 DatasetName 能力时的升级提示(与 irepo_sdk 的 SdkMissing 同范式)。
-_UPGRADE_HINT = (
-    "The installed instance-repo SDK does not provide DatasetName parsing "
-    "(single-segment L1 dataset names need it).\n"
-    "Install it with: pip install 'ap-client[dataset]' --upgrade"
-)
-
-
-class DatasetNameUpgradeRequired(RuntimeError):
-    """已安装的 instance-repo SDK 缺少 DatasetName 能力,必须升级。"""
-
-
-class DatasetNameError(ValueError):
-    """Dataset 名不符合 IR DatasetName 契约(单段或两段、无非法段)。"""
-
-
-def parse_dataset_name(value: str) -> Any:
-    """Parse ``value`` through the installed IR ``DatasetName`` capability.
-
-    Returns the SDK ``DatasetName`` (``canonical`` / ``l1`` / ``l2`` /
-    ``segments`` / ``leaf``)。Raises :class:`DatasetNameUpgradeRequired` when the
-    installed SDK lacks the capability; raises :class:`DatasetNameError` when
-    the value is not a valid L1 or L1/L2 name.
-    """
-    try:
-        from instance_repo.paths import DatasetName
-    except ImportError as exc:
-        raise DatasetNameUpgradeRequired(_UPGRADE_HINT) from exc
-    parse = getattr(DatasetName, "parse", None)
-    if not callable(parse):
-        raise DatasetNameUpgradeRequired(_UPGRADE_HINT)
-    try:
-        return parse(value)
-    except Exception as exc:  # noqa: BLE001 - SDK 校验失败统一转成 CLI 契约
-        raise DatasetNameError(str(exc)) from exc