refactor(shared): update shared module docs and migrate subpackage implementations

- Update _shared module documentation to clarify its role as state shared between the two stacks
- Migrate the agentstudio subpackage implementation to dashscope.v2.agentstudio
- Add a compatibility layer for agentstudio to preserve historical import paths
- Migrate aigc, app, assistants, audio, cli, common, embeddings and other subpackage implementations to their corresponding legacy_1x modules
- Add backward-compatible import shims for each subpackage
- Remove finetune/reinforcement-related demo and parser components
- Update the import structure of the finetune/reinforcement module

Author: luk384090-cloud

MANIFEST.in

@@ -1,4 +1,4 @@
-include dashscope/resources/qwen.tiktoken
+include dashscope/v2/tokenizers/qwen.tiktoken
 include dashscope/py.typed
 include dashscope/__init__.pyi
 include NOTICE

dashscope/_shared/__init__.py

@@ -2,12 +2,28 @@
 # Copyright (c) Alibaba, Inc. and its affiliates.
 """Neutral leaf layer shared by the 1.x API and the 2.0 implementation.
 
-Modules here hold state or values that must exist exactly once per
-installed distribution (the process-wide session id, the version
-number). Copying them into either stack would silently split that single
-source of truth, so both stacks import from here instead.
+What belongs here is anything the two stacks must agree on exactly once
+per installed distribution: the process-wide session id, the mutable
+client tag, the exception base class that ``except`` clauses on both
+sides match against, and the validators that keep a request pointed at
+``*.maas.aliyuncs.com``. Copying one of those into either stack would
+silently split a single source of truth, so both stacks import from
+here instead.
 
-Nothing in this package may import ``dashscope`` or any of its
-subpackages: it sits below both stacks and is the anchor that keeps them
-from forming an import cycle. Stdlib only.
+The only thing this package reaches outside itself is
+``dashscope.version``, read defensively by ``_sdk_ident``. That module
+is a bare constant with no imports of its own, and it deliberately stays
+where it is: ``setup.py`` and ``docs/source/conf.py`` ``exec()`` the
+file to read the version *without* importing the package, and turning
+it into a re-export of something here would drag the whole SDK and its
+runtime dependencies into any build environment that only wanted a
+string.
+
+What this package must never import is the 1.x business surface
+(``client``, ``common``, ``finetune``, ``audio`` and the rest).
+``common/utils`` reaches ``_sdk_ident`` while ``dashscope/__init__`` is
+still executing, so an import back into that surface would close a cycle
+through a partially initialized root. ``dashscope.version`` is safe
+precisely because it has no imports of its own; the business modules
+all have plenty.
 """

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.legacy_1x.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.legacy_1x.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,121 @@
+# -*- 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.
+
+``get_user_agent`` belongs here for the same reason as the two headers:
+it is the other half of the request identity, and it must agree with
+``get_sdk_headers`` on the version segment. It is the *1.x shape*
+(``dashscope/<version>; python/...; platform/...; processor/...``) and is
+deliberately not shared with the 2.0 transport's own
+``dashscope.v2.transport.http.default_user_agent()``
+(``dashscope-v2-python/<version>``). Those are two distinct backend
+contracts, not two spellings of one value, so they must not be merged.
+
+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
+import platform
+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", "get_user_agent", "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,
+    }
+
+
+def get_user_agent() -> str:
+    """The 1.x-shaped ``user-agent`` value.
+
+    Kept byte-identical to the pre-move implementation: the version
+    segment is ``_VERSION`` here rather than a second read of
+    ``dashscope.version``, so it can never drift from the one in
+    ``get_sdk_headers``.
+    """
+    try:
+        platform_ = (
+            platform.platform().replace("\n", "").replace("\r", "").strip()
+        )
+    except Exception:
+        platform_ = "unknown"
+
+    try:
+        processor_ = (
+            platform.processor().replace("\n", "").replace("\r", "").strip()
+        )
+    except Exception:
+        processor_ = "unknown"
+
+    ua = (
+        f"dashscope/{_VERSION}; python/{platform.python_version()}; "
+        f"platform/{platform_}; "
+        f"processor/{processor_}"
+    )
+    return ua

dashscope/_shared/_sdk_session.py

@@ -5,18 +5,18 @@
 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 sub-SDKs owned by 2.0 (AgentStudio, agentic RL) build their
+request headers from ``_shared._sdk_ident`` rather than from the v2
+transport. 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/__init__`` (and its v2 surface) into a cycle.
 
 The embedded ``acli`` deliberately keeps its own id: it is a one-way
-sync copy of the agenticCLI repo (design doc §3.2), so wiring it to this
-module would be silently reverted by the next sync and cannot be
-upstreamed as written.
+sync copy of the agenticCLI repo, so wiring it to this module would be
+silently reverted by the next sync and cannot be upstreamed as written.
 """
 
 from __future__ import annotations

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/acli/ui/tts.py

@@ -3,7 +3,7 @@
 
 Supports both streaming playback (low-latency, audio starts before synthesis
 finishes) and one-shot synthesis.  Uses
-``dashscope.audio.tts_v2.SpeechSynthesizer``.
+``dashscope.legacy_1x.audio.tts_v2.SpeechSynthesizer``.
 """
 # pylint: disable=too-many-return-statements,too-many-branches
 # pylint: disable=too-many-statements
@@ -284,7 +284,7 @@ def _synthesize_and_play(self, text: str) -> Optional[str]:
             dashscope.api_key = self.api_key
 
         try:
-            from dashscope.audio.tts_v2 import (
+            from dashscope.legacy_1x.audio.tts_v2 import (
                 AudioFormat,
                 ResultCallback,
                 SpeechSynthesizer,

dashscope/acli/ui/voice.py

@@ -58,7 +58,10 @@ class _RealtimeASR:
 
     def __init__(self, api_key: str, model: str):
         os.environ.setdefault("DASHSCOPE_API_KEY", api_key)
-        from dashscope.audio.asr import Recognition, RecognitionCallback
+        from dashscope.legacy_1x.audio.asr import (
+            Recognition,
+            RecognitionCallback,
+        )
 
         self._model = model
         self._Recognition = Recognition