feat(acli): tongyi native DashScope route + expert guide surfaces (#190)

* fix(cli): keep the extras name in the rl registration warning

The warning quotes a literal 'dashscope[rl]', which rich reads as a style
tag and drops — users were told to run `pip install 'dashscope'`, which
installs none of the extras the message is about. Escape the exception
text.

Also drop the duplicated instruction: the reinforcement package's
ImportError already says how to install, so the CLI appended a second
copy. The hint is now added only when the underlying message lacks one.

* sync(acli): provider/key wizards no longer dead-end on a stale provider

Mirrors agenticCLI 1acdd7b. A provider persisted from a directory that
had a custom-extensions.toml (e.g. zhipu) cannot be built elsewhere, and
both entry points mishandled it: startup demanded an API key for a
provider with no definition and suggested an env var nothing reads, and
/provider offered that unbuildable name as the Enter default so a bare
Enter returned "Unknown provider: zhipu; cancelled".

* feat(acli): tongyi native DashScope route + expert guide surfaces

- providers/tongyi: switch from compatible-mode to the native
  generation route so calls land in the native SLS logstore; per-model
  text/multimodal-generation endpoint fallback covering both the
  HTTP-400 and the 200-SSE error-event variants of "url error";
  content parts/tool calls converted to the native shape
- embedded/sdk: new module + guide_url params; the dashscope expert
  entry stamps x-dashscope-sdk-client as acli/<version>/expert and the
  TUI/REPL startup banners show the locale-aware expert guide link
- first-run surfaces: get-api-key and dashscope-sdk-expert links in
  the no-key gate, the example-download offer, and the example README
- README/README_zh: how to obtain an API key + expert guide link
- includes the pending acli sync baseline (provider/key wizard fixes,
  subagents/config/dev/session/adapter updates)

* style: fix pre-commit failures (pylint, flake8, black)

Same fixes as dev/issues-8, sourced from agenticCLI main: trailing-comma
drift and the _print_no_key_prompt extraction in the synced wizards,
pylint hygiene in the unit tests, and whitespace around == inside
f-strings (E225 under Python 3.12's PEP 701 tokenizer).

---------

Co-authored-by: zhansheng.lzs <zhansheng.lzs@alibaba-inc.com>

Author: agentscope-ai-java

.github/workflows/pre-commit.yml

@@ -9,13 +9,13 @@ jobs:
       fail-fast: true
     env:
       OS: ubuntu-latest
-      PYTHON: '3.12'
+      PYTHON: '3.8'
     steps:
     - uses: actions/checkout@v4
     - name: Setup Python
       uses: actions/setup-python@v5
       with:
-        python-version: '3.12'
+        python-version: '3.8'
     - name: Update setuptools and wheel
       run: |
         pip install setuptools==68.2.2 wheel==0.41.2

.github/workflows/unit_test.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       matrix:
         os: [ ubuntu-latest ]
-        python-version: [ '3.9', '3.12', '3.13' ]
+        python-version: [ '3.8' ]
 
 
     steps:

README.md

@@ -89,87 +89,6 @@ save_api_key(api_key='YOUR-DASHSCOPE-API-KEY',
 
 ```
 
-## Region and Endpoint Configuration
-
-By default the SDK sends requests to the China (Beijing) public endpoint `dashscope.aliyuncs.com`. If your Model Studio (Bailian) workspace lives in another region, switch the endpoint before making calls.
-
-### Using `set_region`
-
-`dashscope.set_region(region, workspace_id)` points the HTTP, WebSocket and OpenAI-compatible base URLs at the given region in a single call. `workspace_id` is required and is used as the endpoint subdomain.
-
-```python
-import dashscope
-
-# Switch to the Singapore region for workspace "ws-xxx123"
-dashscope.set_region(region="ap-southeast-1", workspace_id="ws-xxx123")
-
-# All subsequent calls use:
-#   https://ws-xxx123.ap-southeast-1.maas.aliyuncs.com/api/v1
-print(dashscope.base_http_api_url)
-```
-
-Supported regions:
-
-| Region | Location |
-|--------|----------|
-| `cn-beijing` | China (Beijing) |
-| `cn-hongkong` | China (Hong Kong) |
-| `ap-southeast-1` | Singapore |
-| `ap-northeast-1` | Japan (Tokyo) |
-| `eu-central-1` | Germany (Frankfurt) |
-| `us-east-1` | US (Virginia) |
-
-> **API keys are region-specific.** Each region issues its own API keys (`sk-` prefix) in its Model Studio console, and keys cannot be mixed across regions — using a key from another region fails with `401`. Switch `api_key` together with the region.
-
-Region-specific notes:
-
-- WebSocket endpoints (`wss://.../api-ws/v1/inference`) are only served in `cn-beijing` and `ap-southeast-1`. `set_region` still sets `base_websocket_api_url` for every region, but WebSocket-based realtime APIs (realtime speech recognition/synthesis, multimodal dialog, etc.) are not available in the other regions.
-- `eu-central-1` / `ap-northeast-1`: the deployment scope (Global, or EU / Japan) is chosen when the workspace is created in the console, not per API call.
-- `us-east-1`: model names with the `-us` suffix (e.g. `qwen-plus-us`) restrict inference to the US; names without the suffix default to global inference.
-- Batch inference, model fine-tuning and application development are currently only available in `cn-beijing` and `ap-southeast-1`.
-
-> `set_region` updates process-wide globals, so it is not concurrency-safe when a single process talks to multiple regions at the same time. Call it once at startup, or re-call it before each switch.
-
-### Using environment variables
-
-You can also select the region without code:
-
-```shell
-export DASHSCOPE_API_REGION='ap-southeast-1'   # default: cn-beijing
-export DASHSCOPE_WORKSPACE_ID='ws-xxx123'      # used to resolve the endpoint subdomain
-```
-
-When a MaaS region is set via `DASHSCOPE_API_REGION`, the SDK builds the regional endpoints and substitutes `DASHSCOPE_WORKSPACE_ID` into them. You can also override each base URL directly:
-
-| Environment variable | Overrides |
-|----------------------|-----------|
-| `DASHSCOPE_HTTP_BASE_URL` | HTTP endpoint (`dashscope.base_http_api_url`) |
-| `DASHSCOPE_WEBSOCKET_BASE_URL` | WebSocket endpoint (`dashscope.base_websocket_api_url`) |
-| `DASHSCOPE_COMPATIBLE_BASE_URL` | OpenAI-compatible endpoint (`dashscope.base_compatible_api_url`) |
-
-`set_region` always builds workspace-exclusive endpoints. Some regions also offer shared domains without a workspace subdomain — `dashscope.aliyuncs.com` (Beijing), `dashscope-intl.aliyuncs.com` (Singapore) and `dashscope-us.aliyuncs.com` (US Virginia); use the override variables above to point at them.
-
-### OpenAI-compatible chat completions
-
-The SDK exposes an OpenAI-compatible chat completions entry that talks to `dashscope.base_compatible_api_url` (request path `chat/completions`) — no extra `openai` package required. It follows the region configured above.
-
-```python
-import dashscope
-from dashscope.aigc.chat_completion import Completions
-
-dashscope.set_region(region="cn-hongkong", workspace_id="ws-hk-789")
-
-response = Completions.create(
-    model="qwen-max",
-    messages=[{"role": "user", "content": "Hello"}],
-    api_key="YOUR-DASHSCOPE-API-KEY",
-    stream=False,  # set True to get a generator of ChatCompletionChunk
-)
-print(response)
-```
-
-A complete runnable example is available in [`samples/set_region_example.py`](samples/set_region_example.py).
-
 ## AI Assistant: DashScope SDK Expert
 
 The SDK ships with an interactive AI assistant, **DashScope SDK Expert**, built on the bundled Agentic CLI (`dashscope/acli`) framework. For DashScope SDK/CLI users it is the recommended way to get development consultation and AI coding help — answering SDK/API questions, generating runnable examples, showing CLI usage, and diagnosing errors, right in your terminal.

README_zh.md

@@ -88,87 +88,6 @@ save_api_key(api_key='YOUR-DASHSCOPE-API-KEY',
 
 ```
 
-## 区域与端点配置
-
-默认情况下，SDK 将请求发往华北2（北京）公共端点 `dashscope.aliyuncs.com`。如果你的百炼（Model Studio）业务空间位于其他区域，请在调用前先切换端点。
-
-### 使用 `set_region`
-
-`dashscope.set_region(region, workspace_id)` 会一次性把 HTTP、WebSocket 和 OpenAI-compatible 三个 base URL 指向指定区域。`workspace_id` 为必填项，会作为端点的子域名。
-
-```python
-import dashscope
-
-# 切换到新加坡区域，业务空间为 "ws-xxx123"
-dashscope.set_region(region="ap-southeast-1", workspace_id="ws-xxx123")
-
-# 之后所有调用都会使用：
-#   https://ws-xxx123.ap-southeast-1.maas.aliyuncs.com/api/v1
-print(dashscope.base_http_api_url)
-```
-
-支持的区域：
-
-| 区域 | 地理位置 |
-|--------|----------|
-| `cn-beijing` | 华北2（北京） |
-| `cn-hongkong` | 中国（香港） |
-| `ap-southeast-1` | 新加坡 |
-| `ap-northeast-1` | 日本（东京） |
-| `eu-central-1` | 德国（法兰克福） |
-| `us-east-1` | 美国（弗吉尼亚） |
-
-> **各地域 API Key 相互独立。**每个地域的 API Key（`sk-` 前缀）需在对应地域的百炼控制台创建，不可跨地域混用——使用其他地域的 Key 会返回 `401`。切换地域时请同步更换 `api_key`。
-
-地域特殊说明：
-
-- WebSocket 端点（`wss://.../api-ws/v1/inference`）目前仅 `cn-beijing` 与 `ap-southeast-1` 提供。`set_region` 对所有地域都会设置 `base_websocket_api_url`，但实时语音识别/合成、多模态对话等基于 WebSocket 的实时 API 在其他地域不可用。
-- `eu-central-1` / `ap-northeast-1`：部署范围（全球，或欧盟 / 日本）在控制台创建业务空间时选择，不在 API 调用层配置。
-- `us-east-1`：模型名带 `-us` 后缀（如 `qwen-plus-us`）限定美国境内推理；不带后缀默认全球推理。
-- 批量推理、模型调优、应用开发等高级功能目前仅 `cn-beijing` 与 `ap-southeast-1` 支持。
-
-> `set_region` 修改的是进程级全局变量，因此在单进程同时访问多个区域时并非并发安全。建议在启动时调用一次，或在每次切换前重新调用。
-
-### 使用环境变量
-
-也可以不写代码，直接通过环境变量选择区域：
-
-```shell
-export DASHSCOPE_API_REGION='ap-southeast-1'   # 默认：cn-beijing
-export DASHSCOPE_WORKSPACE_ID='ws-xxx123'      # 用于解析端点子域名
-```
-
-当通过 `DASHSCOPE_API_REGION` 设置了 MaaS 区域时，SDK 会构造对应的区域端点，并把 `DASHSCOPE_WORKSPACE_ID` 代入其中。你也可以直接覆盖每一个 base URL：
-
-| 环境变量 | 覆盖的对象 |
-|----------------------|-----------|
-| `DASHSCOPE_HTTP_BASE_URL` | HTTP 端点（`dashscope.base_http_api_url`） |
-| `DASHSCOPE_WEBSOCKET_BASE_URL` | WebSocket 端点（`dashscope.base_websocket_api_url`） |
-| `DASHSCOPE_COMPATIBLE_BASE_URL` | OpenAI-compatible 端点（`dashscope.base_compatible_api_url`） |
-
-`set_region` 构造的始终是业务空间专属域名。部分地域还提供不含 workspace 子域名的共享域名——北京 `dashscope.aliyuncs.com`、新加坡 `dashscope-intl.aliyuncs.com`、美国 `dashscope-us.aliyuncs.com`，如需使用可通过上面的环境变量直接覆盖。
-
-### OpenAI-compatible 对话补全
-
-SDK 提供了 OpenAI-compatible 的对话补全入口，它会请求 `dashscope.base_compatible_api_url`（请求路径 `chat/completions`）——无需额外安装 `openai` 库，并自动跟随上面配置的区域。
-
-```python
-import dashscope
-from dashscope.aigc.chat_completion import Completions
-
-dashscope.set_region(region="cn-hongkong", workspace_id="ws-hk-789")
-
-response = Completions.create(
-    model="qwen-max",
-    messages=[{"role": "user", "content": "你好"}],
-    api_key="YOUR-DASHSCOPE-API-KEY",
-    stream=False,  # 设为 True 则返回 ChatCompletionChunk 生成器
-)
-print(response)
-```
-
-完整可运行示例见 [`samples/set_region_example.py`](samples/set_region_example.py)。
-
 ## AI 助手：DashScope SDK Expert
 
 SDK 内置了交互式 AI 助手 **DashScope SDK Expert**，基于随包提供的 Agentic CLI（`dashscope/acli`）框架构建。对于 DashScope SDK/CLI 用户，它是获取开发咨询和 AI 编码帮助的推荐方式——直接在终端中解答 SDK/API 问题、生成可运行示例、展示 CLI 用法、诊断错误。

dashscope/__init__.py

@@ -34,7 +34,6 @@
 from dashscope.api_entities.http_request import close_shared_sync_session
 from dashscope.common.api_key import save_api_key
 from dashscope.common.env import (
-    MAAS_REGIONS,
     api_key,
     api_key_file_path,
     base_compatible_api_url,
@@ -82,48 +81,6 @@
     list_tokenizers,
 )
 
-
-# cn-beijing defaults to the legacy dashscope.aliyuncs.com endpoints;
-# its MaaS URLs are only reachable via an explicit set_region() call.
-_MAAS_REGIONS = {*MAAS_REGIONS, "cn-beijing"}
-
-
-def set_region(region: str, workspace_id: str = None):
-    """Switch to a specific MaaS region.
-
-    Updates base_http_api_url, base_compatible_api_url and
-    base_websocket_api_url to point to the MaaS endpoint for the
-    given region and workspace.
-
-    Args:
-        region (str): The MaaS region, e.g. "ap-southeast-1",
-            "us-east-1", "cn-hongkong", "cn-beijing", "eu-central-1",
-            "ap-northeast-1".
-        workspace_id (str): The workspace ID, used as the subdomain
-            of the MaaS endpoint.
-
-    Raises:
-        ValueError: If region is not supported or workspace_id is
-            empty.
-    """
-    if region not in _MAAS_REGIONS:
-        raise ValueError(
-            f"Unsupported region '{region}'. "
-            f"Supported regions: {sorted(_MAAS_REGIONS)}",
-        )
-
-    if not workspace_id:
-        raise ValueError("workspace_id is required")
-
-    global base_http_api_url, base_compatible_api_url
-    global base_websocket_api_url
-
-    host = f"{workspace_id}.{region}.maas.aliyuncs.com"
-    base_http_api_url = f"https://{host}/api/v1"
-    base_compatible_api_url = f"https://{host}/compatible-mode/v1"
-    base_websocket_api_url = f"wss://{host}/api-ws/v1/inference"
-
-
 __all__ = [
     "__version__",
     "base_compatible_api_url",
@@ -184,7 +141,6 @@ def set_region(region: str, workspace_id: str = None):
     "MessageFile",
     "AssistantFile",
     "VideoSynthesis",
-    "set_region",
 ]
 
 logging.getLogger(__name__).addHandler(NullHandler())

dashscope/__init__.pyi

@@ -23,7 +23,6 @@ base_websocket_api_url: str
 def save_api_key(api_key: str, file_path: Optional[str] = ...) -> None: ...
 def close_shared_aio_session() -> None: ...
 def close_shared_sync_session() -> None: ...
-def set_region(region: str, workspace_id: Optional[str] = ...) -> None: ...
 
 # ---------------------------------------------------------------------------
 # Response types

dashscope/api_entities/api_request_factory.py

@@ -19,7 +19,6 @@
 from dashscope.common.error import InputDataRequired, UnsupportedApiProtocol
 from dashscope.common.logging import logger
 from dashscope.common.utils import get_sdk_headers
-from dashscope.common.env import resolve_base_url
 from dashscope.protocol.websocket import WebsocketStreamingMode
 
 
@@ -133,17 +132,9 @@ def _build_api_request(  # pylint: disable=too-many-branches
 
     encryption = None
 
-    # Resolve {workspace_id} placeholder for MaaS international regions
-    workspace = kwargs.pop("workspace", None)
-    if base_address is not None:
-        base_address = resolve_base_url(base_address, workspace)
-
     if api_protocol in [ApiProtocol.HTTP, ApiProtocol.HTTPS]:
         if base_address is None:
-            base_address = resolve_base_url(
-                dashscope.base_http_api_url,
-                workspace,
-            )
+            base_address = dashscope.base_http_api_url
         if not base_address.endswith("/"):
             http_url = base_address + "/"
         else:
@@ -185,10 +176,7 @@ def _build_api_request(  # pylint: disable=too-many-branches
         if base_address is not None:
             websocket_url = base_address
         else:
-            websocket_url = resolve_base_url(
-                dashscope.base_websocket_api_url,
-                workspace,
-            )
+            websocket_url = dashscope.base_websocket_api_url
         request = WebSocketRequest(
             url=websocket_url,
             api_key=api_key,

dashscope/api_entities/encryption.py

@@ -18,7 +18,6 @@
     DEFAULT_REQUEST_TIMEOUT_SECONDS,
 )
 from dashscope.common.logging import logger
-from dashscope.common.env import resolve_base_url
 from dashscope.common.utils import get_sdk_headers
 
 
@@ -89,10 +88,7 @@ def get_base64_iv_str(self):
 
     @staticmethod
     def _get_public_keys():
-        url = (
-            resolve_base_url(dashscope.base_http_api_url)
-            + "/public-keys/latest"
-        )
+        url = dashscope.base_http_api_url + "/public-keys/latest"
         headers = {
             "Authorization": f"Bearer {dashscope.api_key}",
             **get_sdk_headers(module="utils"),

dashscope/audio/http_tts/http_speech_synthesizer.py

@@ -203,12 +203,12 @@ def _http_call(
 
         # Get base URL
         import dashscope
-        from dashscope.common.env import resolve_base_url
         from dashscope.common.utils import get_sdk_headers, join_url
 
-        if not url:
-            url = dashscope.base_http_api_url
-        base_url = resolve_base_url(url, workspace)
+        if url:
+            base_url = url
+        else:
+            base_url = dashscope.base_http_api_url
         url_for_call = join_url(
             base_url,
             "services/audio/tts/SpeechSynthesizer",

dashscope/audio/tts_v2/speech_synthesizer.py

@@ -15,7 +15,6 @@
 
 import dashscope
 from dashscope.common.constants import WEBSOCKET_ERROR_CODE
-from dashscope.common.env import resolve_base_url
 from dashscope.common.error import (
     InputRequired,
     InvalidTask,
@@ -492,7 +491,7 @@ def __update_params(  # pylint: disable=redefined-builtin
             raise InputRequired("format is required!")
         if url is None:
             url = dashscope.base_websocket_api_url
-        self.url = resolve_base_url(url, workspace)
+        self.url = url
         self.apikey = dashscope.api_key
         if self.apikey is None:
             raise InputRequired("apikey is required!")