refactor(agentstudio): migrate AgentStudio sub-SDK to v2 package structure

- Move all modules from dashscope/agentstudio to dashscope/v2/agentstudio
- Update all internal import paths to use the new package structure
- Create shared exception base class dashscope._shared._errors.DashScopeException
- Implement lazy-loading proxy wrapper for AgentStudio client for error conversion
- Move validation functions validate_region and validate_workspace_id to shared module
- Update client configuration to use new settings retrieval method
- Modify SDK identity header generation logic to adapt to new architecture
- Refactor transport layer identity to implement unified session ID management
- Rewrite import paths for pagination and helper functions
- Update documentation comments to reflect new architectural design changes

Author: luk384090-cloud

dashscope/_shared/_errors.py

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) Alibaba, Inc. and its affiliates.
+"""The one exception base class both stacks inherit from.
+
+``except dashscope.common.error.DashScopeException`` has to catch errors
+raised by the 1.x API classes *and* by the AgentStudio sub-SDK, which the
+2.0 client mounts directly. That only works if every subclass in both
+stacks derives from the same class object, so the base lives here rather
+than in either stack: copying it would silently split the hierarchy and
+let errors escape a caller's ``except`` clause.
+
+``dashscope.common.error`` re-exports this name, so the 1.x import path
+keeps working and keeps the identical class.
+"""
+
+
+class DashScopeException(Exception):
+    """Base class for every error the dashscope SDK raises."""
+
+
+__all__ = ["DashScopeException"]

dashscope/_shared/_sdk_ident.py

@@ -0,0 +1,81 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) Alibaba, Inc. and its affiliates.
+"""SDK identification headers shared by the 1.x API and the 2.0 package.
+
+``x-dashscope-sdk-client`` tells the backend which client and which
+functional area issued a request, and ``x-dashscope-sdk-session-id``
+groups every request one interpreter process makes.
+
+The client segment is process-wide *mutable* state: entry points that
+embed the SDK overwrite it (the ``dashscope`` CLI marks itself as
+``python-cli`` via ``set_sdk_client``), and every caller in both stacks
+must see the same value. Duplicating it would silently drop the override
+for whichever stack held the copy, so it lives here -- one source of
+truth, same reason as the session id in ``_shared._sdk_session``.
+
+The 2.0 transport builds its own header in
+``dashscope.v2.transport._ident`` because it appends a trailing
+generation marker (``aigc`` -> ``aigc2``) that this unmarked 1.x shape
+must not carry. Sub-SDKs that predate the marker -- AgentStudio, whose
+``agentstudio`` tag the backend already reports on -- keep using this
+module.
+
+Only the stdlib is imported at module level; ``dashscope.version`` is
+pulled in lazily and defensively so this leaf stays below both stacks.
+"""
+
+import os
+from typing import Dict
+
+from dashscope._shared._sdk_session import sdk_session_id
+
+_SDK_CLIENT = "python-sdk"
+
+# Shared with the 2.0 transport so one process reports one
+# x-dashscope-sdk-session-id across both stacks (see _shared._sdk_session;
+# acli deliberately keeps its own, it is a one-way sync copy).
+_SDK_SESSION_ID = sdk_session_id()
+
+__all__ = ["get_sdk_headers", "set_sdk_client"]
+
+
+def _sdk_version() -> str:
+    try:
+        from dashscope.version import __version__
+    except Exception:  # pragma: no cover - defensive import guard
+        return "0.0.0"
+    return __version__
+
+
+# Read once at import so the value is stable for the process lifetime.
+_VERSION = _sdk_version()
+
+
+def set_sdk_client(client: str) -> None:
+    """Override the client identifier in the x-dashscope-sdk-client header.
+
+    Process-wide, used by entry points that embed the SDK (e.g. the
+    ``dashscope`` CLI marks itself as ``python-cli``).
+    """
+    global _SDK_CLIENT  # pylint: disable=global-statement
+    if client:
+        _SDK_CLIENT = client
+
+
+def get_sdk_headers(module: str = "") -> Dict[str, str]:
+    """Structured SDK identification headers for backend statistics.
+
+    Set DASHSCOPE_DISABLE_SDK_HEADERS=1 to omit them.
+
+    Args:
+        module: Optional module name (e.g. agentstudio, rl, app).
+    """
+    if os.environ.get("DASHSCOPE_DISABLE_SDK_HEADERS"):
+        return {}
+    parts = [_SDK_CLIENT, _VERSION]
+    if module:
+        parts.append(module)
+    return {
+        "x-dashscope-sdk-client": "/".join(parts),
+        "x-dashscope-sdk-session-id": _SDK_SESSION_ID,
+    }

dashscope/_shared/_sdk_session.py

@@ -5,9 +5,9 @@
 The ``x-dashscope-sdk-session-id`` header lets server-side access logs
 group every request one SDK session makes. A process can emit requests
 through both stacks at once -- the 1.x API classes and the 2.0 transport
--- and the 2.0 client even delegates some calls (rl, agentstudio)
-straight into 1.x. If each stack minted its own id, one logical session
-would split across several ids and the grouping breaks.
+-- and the 2.0 client still delegates some calls (rl) straight into 1.x.
+If each stack minted its own id, one logical session would split across
+several ids and the grouping breaks.
 
 This leaf module is the one source of truth both import. It depends only
 on the stdlib so it can be pulled in from anywhere without dragging

dashscope/_shared/_validation.py

@@ -0,0 +1,64 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) Alibaba, Inc. and its affiliates.
+"""Host-label validation shared by the 1.x API and the 2.0 implementation.
+
+``workspace_id`` and ``region`` are interpolated into the host of the MaaS
+endpoint, so both stacks must reject the same malformed values with the
+same rule. Keeping the check in one leaf module means a value that is
+safe for one stack is safe for the other, and neither stack has to import
+the other to get it.
+
+Stdlib only, like the rest of ``dashscope._shared``.
+"""
+
+import re
+
+# workspace_id and region become DNS labels of the MaaS endpoint host, so
+# they must not contain characters (/, ?, #, @, :, whitespace, ...) that
+# could break out of the host and redirect requests elsewhere.
+# \A...\Z rather than ^...$: $ also matches before a trailing newline.
+_WORKSPACE_ID_PATTERN = re.compile(r"\A[A-Za-z0-9][A-Za-z0-9_-]{0,63}\Z")
+# RFC 1123 hostname label: 1-63 chars, no leading/trailing hyphen. Upper
+# case is allowed because DNS is case-insensitive and httpx lowercases the
+# host, so rejecting it would break working callers for no security gain.
+_REGION_PATTERN = re.compile(
+    r"\A[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\Z",
+)
+
+__all__ = ["validate_region", "validate_workspace_id"]
+
+
+def validate_workspace_id(workspace_id):
+    """Validate that workspace_id is safe to use as a URL subdomain.
+
+    Raises:
+        ValueError: If workspace_id contains characters outside
+            [A-Za-z0-9_-], is empty, or exceeds 64 characters.
+    """
+    if not workspace_id or not _WORKSPACE_ID_PATTERN.fullmatch(
+        workspace_id,
+    ):
+        raise ValueError(
+            f"Invalid workspace_id {workspace_id!r}: must match "
+            "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$",
+        )
+    return workspace_id
+
+
+def validate_region(region):
+    """Validate that region is safe to use as a URL subdomain.
+
+    Deliberately a hostname-label check and not a MAAS_REGIONS whitelist:
+    rejecting an unknown-but-well-formed region would break callers as soon
+    as a subpackage supports a region this list has not caught up with.
+
+    Raises:
+        ValueError: If region is not a valid hostname label.
+    """
+    if not region or not _REGION_PATTERN.fullmatch(region):
+        raise ValueError(
+            f"Invalid region {region!r}: must be a hostname label "
+            "(1-63 chars of [A-Za-z0-9-], not starting or ending "
+            "with '-')",
+        )
+    return region

dashscope/agentstudio/__init__.py

@@ -1,164 +1,58 @@
 # -*- coding: utf-8 -*-
 # Copyright (c) Alibaba, Inc. and its affiliates.
-"""AgentStudio sub-SDK for the dashscope Python client.
+"""Compatibility shim; the implementation moved to ``dashscope.v2.agentstudio``.
 
-The ``agentstudio`` package wraps the AgentStudio managed-agent HTTP
-API.  All resource classes are accessed through a client instance::
+The AgentStudio sub-SDK is owned by the 2.0 package. This module keeps the
+historical import path working: every public name is re-exported, and every
+submodule is aliased in ``sys.modules`` so deep imports such as
+``from dashscope.agentstudio.resources.agents import Agents`` resolve to the
+very same module object -- and therefore the very same classes -- as the
+``dashscope.v2.agentstudio`` path.
 
-    from dashscope.agentstudio import Client
-    from dashscope.agentstudio.types import (
-        user_message, user_tool_result,
-    )
-
-Example
--------
->>> from dashscope.agentstudio import Client
->>> from dashscope.agentstudio.types import user_message
->>> client = Client(api_key="sk-xxx")
->>> agent = client.agents.create(name="demo", model="qwen-plus")
->>> session = client.sessions.create(agent=agent.id)
->>> client.sessions.events.send(session.id, [user_message("Hello!")])
->>> with client.sessions.events.stream(session.id) as stream:
-...     for event in stream:
-...         print(event.type, event.to_dict())
-...         if event.type == "session_status":
-...             break
+Import from ``dashscope.v2.agentstudio`` in new code.
 """
 
-# yapf: disable
+import pkgutil
+import sys
 
-from .client import Client, AsyncClient
-from .transport import APIResponse, RequestOptions
-from . import types
-from .exceptions import (
-    AgentStudioError,
-    APIConnectionError,
-    APIStatusError,
-    APITimeoutError,
-    AuthenticationError,
-    ConflictError,
-    InternalServerError,
-    InvalidRequestError,
-    NotFoundError,
-    OverloadedError,
-    PermissionDeniedError,
-    RateLimitError,
-    StreamClosedError,
-    StreamError,
-)
-from .pagination import (
-    AsyncCursorPage,
-    CursorPage,
-)
-from .types import (
-    Memory,
-    MemoryStore,
-    MemoryVersion,
-    Message,
-    PermissionPolicy,
-    SecurityAlert,
-    SecurityAlertList,
-    SecurityOverview,
-    ServerEvent,
-    SessionResource,
-    StopReason,
-    user_define_outcome,
-    user_interrupt,
-    user_message,
-    user_tool_approval_response,
-    user_custom_tool_result,
-    user_tool_result,
-)
-from .types.params import (
-    AgentCreateParams,
-    AgentUpdateParams,
-    SessionCreateParams,
-    SessionUpdateParams,
-    EnvironmentCreateParams,
-    EnvironmentUpdateParams,
-    DeploymentCreateParams,
-    DeploymentUpdateParams,
-    SessionEventSendParams,
-    WebhookEndpointCreateParams,
-    WebhookEndpointUpdateParams,
-    WebhookEventListParams,
-)
-from .constants import (
-    PermissionPolicyType,
-    SSEEventType,
-    SessionStatus,
-    StopReasonType,
-    WebhookDeliveryStatus,
-    WebhookDisabledReason,
-    WebhookEventType,
-    WebhookStatus,
+# Importing the package runs its own eager imports, so every submodule is
+# already in sys.modules by the time the walk below starts.
+from dashscope.v2 import agentstudio as _impl
+
+# pylint: disable-next=wildcard-import,unused-wildcard-import
+from dashscope.v2.agentstudio import *  # noqa: F401,F403
+
+# The wildcard only carries the names in the implementation's __all__, which
+# lists classes and helpers but not its submodules. Naming them here keeps
+# ``from dashscope.agentstudio import exceptions`` resolvable statically; at
+# runtime they are already imported by the package's own eager imports.
+# pylint: disable-next=unused-import
+from dashscope.v2.agentstudio import (  # noqa: F401
+    client,
+    constants,
+    exceptions,
+    pagination,
+    resources,
+    streaming,
+    transport,
+    types,
 )
 
-__all__ = [
-    # client
-    "Client",
-    "AsyncClient",
-    # base types
-    "RequestOptions",
-    "APIResponse",
-    # exceptions
-    "AgentStudioError",
-    "APIConnectionError",
-    "APIStatusError",
-    "APITimeoutError",
-    "AuthenticationError",
-    "ConflictError",
-    "InternalServerError",
-    "InvalidRequestError",
-    "NotFoundError",
-    "OverloadedError",
-    "PermissionDeniedError",
-    "RateLimitError",
-    "StreamError",
-    "StreamClosedError",
-    # pagination
-    "CursorPage",
-    "AsyncCursorPage",
-    # unified message type
-    "Memory",
-    "MemoryStore",
-    "MemoryVersion",
-    "Message",
-    "PermissionPolicy",
-    "SecurityAlert",
-    "SecurityAlertList",
-    "SecurityOverview",
-    "ServerEvent",
-    "SessionResource",
-    "StopReason",
-    # client event helpers (re-exported for convenience)
-    "user_message",
-    "user_interrupt",
-    "user_tool_approval_response",
-    "user_custom_tool_result",
-    "user_tool_result",
-    "user_define_outcome",
-    # typing module
-    "types",
-    # params (commonly used request-body types)
-    "AgentCreateParams",
-    "AgentUpdateParams",
-    "SessionCreateParams",
-    "SessionUpdateParams",
-    "EnvironmentCreateParams",
-    "EnvironmentUpdateParams",
-    "DeploymentCreateParams",
-    "DeploymentUpdateParams",
-    "SessionEventSendParams",
-    "WebhookEndpointCreateParams",
-    "WebhookEndpointUpdateParams",
-    "WebhookEventListParams",
-    "WebhookStatus",
-    "WebhookDisabledReason",
-    "WebhookDeliveryStatus",
-    "WebhookEventType",
-    "SSEEventType",
-    "SessionStatus",
-    "StopReasonType",
-    "PermissionPolicyType",
-]
+_V2_PACKAGE = _impl.__name__
+
+__all__ = list(_impl.__all__)
+
+# Alias each submodule under the old dotted path. Registering in
+# sys.modules alone is not enough: the import system skips a module it
+# finds there, so the attribute on the parent would never be set and
+# ``dashscope.agentstudio.resources`` would raise AttributeError.
+for _info in pkgutil.walk_packages(_impl.__path__, prefix=_V2_PACKAGE + "."):
+    _module = sys.modules.get(_info.name)
+    if _module is None:  # pragma: no cover - walk_packages imports as it goes
+        continue
+    _alias = __name__ + _info.name[len(_V2_PACKAGE) :]
+    sys.modules.setdefault(_alias, _module)
+    _parent_name, _, _leaf = _alias.rpartition(".")
+    _parent = sys.modules.get(_parent_name)
+    if _parent is not None:
+        setattr(_parent, _leaf, _module)