@qingflow-tech/qingflow-app-builder-mcp 1.0.0

package/src/qingflow_mcp/cli/main.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, Callable, TextIO
+
+from ..errors import QingflowApiError
+from ..public_surface import cli_public_tool_spec_from_namespace
+from ..response_trim import resolve_cli_tool_name, trim_error_response, trim_public_response
+from .context import CliContext, build_cli_context
+from .formatters import emit_json_result, emit_text_result
+from .commands import register_all_commands
+
+
+Handler = Callable[[argparse.Namespace, CliContext], dict[str, Any]]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="qingflow", description="Qingflow CLI")
+    parser.add_argument("--profile", default="default", help="会话 profile，默认 default")
+    parser.add_argument("--json", action="store_true", help="输出 JSON")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    register_all_commands(subparsers)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    raise SystemExit(run(argv))
+
+
+def run(
+    argv: list[str] | None = None,
+    *,
+    context_factory: Callable[[], CliContext] = build_cli_context,
+    stdout: TextIO | None = None,
+    stderr: TextIO | None = None,
+) -> int:
+    out = stdout or sys.stdout
+    err = stderr or sys.stderr
+    parser = build_parser()
+    normalized_argv = _normalize_global_args(list(argv) if argv is not None else sys.argv[1:])
+    try:
+        args = parser.parse_args(normalized_argv)
+    except SystemExit as exc:
+        return int(exc.code or 0)
+    handler = getattr(args, "handler", None)
+    if handler is None:
+        parser.print_help(out)
+        return 2
+    context = context_factory()
+    try:
+        if not bool(args.json):
+            _emit_cli_effective_context_notice(args, context, stream=err)
+        result = handler(args, context)
+    except RuntimeError as exc:
+        payload = trim_error_response(_parse_error_payload(exc))
+        return _emit_error(payload, json_mode=bool(args.json), stdout=out, stderr=err)
+    except QingflowApiError as exc:
+        payload = trim_error_response(exc.to_dict())
+        return _emit_error(payload, json_mode=bool(args.json), stdout=out, stderr=err)
+    finally:
+        context.close()
+
+    exit_code = _result_exit_code(result)
+    trimmed_result = trim_public_response(resolve_cli_tool_name(args), result) if isinstance(result, dict) else result
+    stream = out if bool(args.json) or exit_code == 0 else err
+    if bool(args.json):
+        emit_json_result(trimmed_result, stream=stream)
+    else:
+        emit_text_result(trimmed_result, hint=getattr(args, "format_hint", ""), stream=stream)
+    return exit_code
+
+
+def _normalize_global_args(argv: list[str]) -> list[str]:
+    global_args: list[str] = []
+    remaining: list[str] = []
+    index = 0
+    while index < len(argv):
+        token = argv[index]
+        if token == "--json":
+            global_args.append(token)
+            index += 1
+            continue
+        if token == "--profile":
+            global_args.append(token)
+            if index + 1 >= len(argv):
+                global_args.append("")
+                break
+            global_args.append(argv[index + 1])
+            index += 2
+            continue
+        if token.startswith("--profile="):
+            global_args.append(token)
+            index += 1
+            continue
+        remaining.append(token)
+        index += 1
+    return global_args + remaining
+
+
+def _parse_error_payload(exc: RuntimeError) -> dict[str, Any]:
+    raw = str(exc)
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        return {"category": "runtime", "message": raw}
+    return payload if isinstance(payload, dict) else {"category": "runtime", "message": raw}
+
+
+def _emit_error(payload: dict[str, Any], *, json_mode: bool, stdout: TextIO, stderr: TextIO) -> int:
+    exit_code = _error_exit_code(payload)
+    if json_mode:
+        emit_json_result(payload, stream=stdout)
+        return exit_code
+    lines = [
+        f"Category: {payload.get('category') or 'error'}",
+        f"Message: {payload.get('message') or 'Unknown error'}",
+    ]
+    if payload.get("backend_code") is not None:
+        lines.append(f"Backend Code: {payload.get('backend_code')}")
+    if payload.get("request_id"):
+        lines.append(f"Request ID: {payload.get('request_id')}")
+    details = payload.get("details")
+    if isinstance(details, dict):
+        for key, value in details.items():
+            if isinstance(value, (str, int, float, bool)) or value is None:
+                lines.append(f"{key}: {value}")
+    stderr.write("\n".join(lines) + "\n")
+    return exit_code
+
+
+def _error_exit_code(payload: dict[str, Any]) -> int:
+    category = str(payload.get("category") or "").lower()
+    if category in {"auth", "workspace"}:
+        return 3
+    return 4
+
+
+def _result_exit_code(result: dict[str, Any]) -> int:
+    if not isinstance(result, dict):
+        return 0
+    if result.get("ok") is False:
+        return 4
+    status = str(result.get("status") or "").lower()
+    if status in {"failed", "blocked"}:
+        return 4
+    return 0
+
+
+def _emit_cli_effective_context_notice(args: argparse.Namespace, context: CliContext, *, stream: TextIO) -> None:
+    spec = cli_public_tool_spec_from_namespace(args)
+    if spec is None or not spec.cli_show_effective_context:
+        return
+    sessions = getattr(context, "sessions", None)
+    if sessions is None or not hasattr(sessions, "get_profile"):
+        return
+    profile_name = str(getattr(args, "profile", "default") or "default")
+    try:
+        session_profile = sessions.get_profile(profile_name)
+    except Exception:
+        session_profile = None
+    workspace_id = getattr(session_profile, "selected_ws_id", None) if session_profile is not None else None
+    workspace_name = getattr(session_profile, "selected_ws_name", None) if session_profile is not None else None
+    if workspace_id is None:
+        workspace_label = "(not selected)"
+    elif workspace_name:
+        workspace_label = f"{workspace_name} ({workspace_id})"
+    else:
+        workspace_label = str(workspace_id)
+    lines = [f"Context: profile={profile_name} workspace={workspace_label}"]
+    if spec.cli_context_write and profile_name == "default":
+        lines.append("Warning: using default profile for a workspace-sensitive write command")
+    stream.write("\n".join(lines) + "\n")
+
+
+if __name__ == "__main__":
+    main()

package/src/qingflow_mcp/config.py

@@ -0,0 +1,513 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlsplit, urlunsplit
+
+DEFAULT_PROFILE = "default"
+DEFAULT_TIMEOUT_SECONDS = 30.0
+DEFAULT_USER_AGENT = "qingflow-mcp/1.0"
+DEFAULT_RECORD_LIST_TYPE = 8
+ATTACHMENT_QUESTION_TYPE = 13
+DEFAULT_BASE_URL = "https://qingflow.com/api"
+DEFAULT_FEEDBACK_APP_KEY = "e0d017kju002"
+DEFAULT_FEEDBACK_QSOURCE_TOKEN = "mcp-feedback-7755d14748fc"
+DEFAULT_REPOSITORY_GIT_REMOTE_TEMPLATE = "git@hackers.oalite.com:{group}/{repo}.git"
+DEFAULT_REPOSITORY_PREVIEW_ADDRESS_TEMPLATE = "https://%s.preview.oalite.com"
+DEFAULT_REPOSITORY_DEVELOP_BRANCH = "develop"
+DEFAULT_REPOSITORY_PROD_BRANCH = "prod"
+DEFAULT_REPOSITORY_AUTHOR_NAME = "qingflow-mcp"
+DEFAULT_REPOSITORY_AUTHOR_EMAIL = "qingflow-mcp@local.invalid"
+DEFAULT_REPOSITORY_INTERNAL_SHARE_TOKEN_KEY = "tokenKey"
+DEFAULT_CREDIT_BALANCE_PATH = "/ultron/internal/credit/balance"
+DEFAULT_CREDIT_USAGE_RECORD_PATH = "/share/workspace/credit/usage/record"
+DEFAULT_CREDIT_WINGS_TOKEN_HEADER_KEY = "wingsTokenKey"
+DEFAULT_CREDIT_APAAS_TOKEN_HEADER_KEY = "serviceToken"
+DEFAULT_CREDIT_WS_ID_HEADER_KEY = "wsId"
+DEFAULT_CREDIT_USAGE_AMOUNT = "1"
+DEFAULT_CREDIT_APAAS_TOKEN_VALUE = "729ed3cc-8eea-11ec-b585-52540009137b"
+
+
+def get_mcp_home() -> Path:
+    custom_home = os.getenv("QINGFLOW_MCP_HOME")
+    return Path(custom_home).expanduser() if custom_home else Path.home() / ".qingflow-mcp"
+
+
+def get_profiles_path() -> Path:
+    return get_mcp_home() / "profiles.json"
+
+
+def get_repository_metadata_dir() -> Path:
+    return get_mcp_home() / "repository-metadata"
+
+
+def get_config_file_paths() -> list[Path]:
+    """
+    获取可能的配置文件路径列表，按优先级排序：
+    1. 环境变量 QINGFLOW_MCP_CONFIG_PATH 指定的路径
+    2. 当前工作目录下的 qingflow-mcp.config.json
+    3. MCP home 目录下的 config.json
+    4. 系统级配置 (Linux/Mac: /etc/qingflow-mcp/config.json)
+    """
+    paths: list[Path] = []
+
+    # 1. 环境变量
+    env_config = os.getenv("QINGFLOW_MCP_CONFIG_PATH")
+    if env_config:
+        paths.append(Path(env_config).expanduser())
+
+    # 2. 当前工作目录
+    paths.append(Path.cwd() / "qingflow-mcp.config.json")
+
+    # 3. MCP home 目录
+    paths.append(get_mcp_home() / "config.json")
+
+    # 4. 系统级配置 (仅非 Windows)
+    if os.name != "nt":
+        paths.append(Path("/etc/qingflow-mcp/config.json"))
+
+    return paths
+
+
+def load_config_file() -> dict[str, Any]:
+    """
+    加载第一个存在的配置文件
+
+    Returns:
+        配置字典，如果没有找到配置文件则返回空字典
+    """
+    for path in get_config_file_paths():
+        if path.exists():
+            try:
+                with open(path, "r", encoding="utf-8") as f:
+                    content = f.read()
+                    # 移除 JSON 注释 (简单的行注释处理)
+                    lines = []
+                    for line in content.split("\n"):
+                        stripped = line.strip()
+                        if not stripped.startswith("//") and not stripped.startswith("#"):
+                            lines.append(line)
+                    return json.loads("\n".join(lines))
+            except (json.JSONDecodeError, IOError) as e:
+                # 配置文件存在但读取失败，记录警告但不中断
+                print(f"Warning: Failed to load config from {path}: {e}")
+                continue
+    return {}
+
+
+def get_config_value(key: str, env_var: str | None = None, default: Any = None) -> Any:
+    """
+    获取配置值，优先级：环境变量 > 配置文件 > 默认值
+
+    Args:
+        key: 配置文件中的键名 (支持点号分隔的嵌套键，如 "profiles.default.name")
+        env_var: 环境变量名
+        default: 默认值
+
+    Returns:
+        配置值
+    """
+    # 1. 环境变量
+    if env_var:
+        env_value = os.getenv(env_var)
+        if env_value is not None:
+            return env_value
+
+    # 2. 配置文件
+    config = load_config_file()
+    keys = key.split(".")
+    value = config
+    for k in keys:
+        if isinstance(value, dict) and k in value:
+            value = value[k]
+        else:
+            value = None
+            break
+
+    if value is not None:
+        return value
+
+    # 3. 默认值
+    return default
+
+
+def get_default_base_url() -> str | None:
+    """获取默认的 Qingflow 后端地址"""
+    value = get_config_value(
+        "default_base_url",
+        env_var="QINGFLOW_MCP_DEFAULT_BASE_URL",
+        default=DEFAULT_BASE_URL
+    )
+    return normalize_base_url(value) if value else None
+
+
+def get_default_qf_version() -> str | None:
+    """获取默认的 qfVersion 路由值"""
+    value = get_config_value(
+        "default_qf_version",
+        env_var="QINGFLOW_MCP_DEFAULT_QF_VERSION",
+        default=None,
+    )
+    if value is None:
+        return None
+    normalized = str(value).strip()
+    return normalized or None
+
+
+def get_feedback_qsource_token() -> str | None:
+    """获取反馈 q-source 被动入口 token"""
+    value = get_config_value(
+        "feedback.qsource_token",
+        env_var="QINGFLOW_MCP_FEEDBACK_QSOURCE_TOKEN",
+        default=DEFAULT_FEEDBACK_QSOURCE_TOKEN,
+    )
+    if value is None:
+        return None
+    normalized = str(value).strip()
+    return normalized or None
+
+
+def get_feedback_base_url() -> str | None:
+    """获取反馈 q-source 使用的 base URL"""
+    value = get_config_value(
+        "feedback.base_url",
+        env_var="QINGFLOW_MCP_FEEDBACK_BASE_URL",
+        default=None,
+    )
+    if value is None:
+        return get_default_base_url()
+    normalized = normalize_base_url(value)
+    return normalized or get_default_base_url()
+
+
+def get_feedback_app_key() -> str:
+    """获取内部反馈表 app_key"""
+    value = get_config_value(
+        "feedback.app_key",
+        env_var="QINGFLOW_MCP_FEEDBACK_APP_KEY",
+        default=DEFAULT_FEEDBACK_APP_KEY,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_FEEDBACK_APP_KEY
+
+
+def get_timeout_seconds() -> float:
+    """获取 HTTP 超时秒数"""
+    value = get_config_value(
+        "timeout_seconds",
+        env_var="QINGFLOW_MCP_TIMEOUT_SECONDS",
+        default=DEFAULT_TIMEOUT_SECONDS
+    )
+    try:
+        return float(value)
+    except (ValueError, TypeError):
+        return DEFAULT_TIMEOUT_SECONDS
+
+
+def get_log_level() -> str:
+    """获取日志级别"""
+    return get_config_value(
+        "log_level",
+        env_var="QINGFLOW_MCP_LOG_LEVEL",
+        default="INFO"
+    )
+
+
+def get_credit_meter_enabled() -> bool:
+    value = get_config_value(
+        "credit_meter.enabled",
+        env_var="QINGFLOW_MCP_CREDIT_METER_ENABLED",
+        default="true",
+    )
+    normalized = str(value or "").strip().lower()
+    return normalized in {"1", "true", "yes", "on"}
+
+
+def get_credit_shared_token_key() -> str:
+    value = get_config_value(
+        "credit_meter.shared_token_key",
+        env_var="QINGFLOW_MCP_CREDIT_TOKEN_KEY",
+        default=DEFAULT_CREDIT_APAAS_TOKEN_HEADER_KEY,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_CREDIT_APAAS_TOKEN_HEADER_KEY
+
+
+def get_credit_shared_token_value() -> str | None:
+    value = get_config_value(
+        "credit_meter.shared_token_value",
+        env_var="QINGFLOW_MCP_CREDIT_TOKEN_VALUE",
+        default=None,
+    )
+    normalized = str(value or "").strip()
+    return normalized or None
+
+
+def get_credit_shared_ws_id_header_key() -> str:
+    value = get_config_value(
+        "credit_meter.shared_ws_id_header_key",
+        env_var="QINGFLOW_MCP_CREDIT_WS_ID_HEADER_KEY",
+        default=DEFAULT_CREDIT_WS_ID_HEADER_KEY,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_CREDIT_WS_ID_HEADER_KEY
+
+
+def get_credit_balance_base_url() -> str | None:
+    value = get_config_value(
+        "credit_meter.wings.base_url",
+        env_var="QINGFLOW_MCP_CREDIT_WINGS_BASE_URL",
+        default=None,
+    )
+    normalized = normalize_base_url(value)
+    return normalized or None
+
+
+def get_credit_balance_path() -> str:
+    value = get_config_value(
+        "credit_meter.wings.path",
+        env_var="QINGFLOW_MCP_CREDIT_WINGS_PATH",
+        default=DEFAULT_CREDIT_BALANCE_PATH,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_CREDIT_BALANCE_PATH
+
+
+def get_credit_balance_token_key() -> str:
+    value = get_config_value(
+        "credit_meter.wings.token_key",
+        env_var="QINGFLOW_MCP_CREDIT_WINGS_TOKEN_KEY",
+        default=DEFAULT_CREDIT_WINGS_TOKEN_HEADER_KEY,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_CREDIT_WINGS_TOKEN_HEADER_KEY
+
+
+def get_credit_balance_token_value() -> str | None:
+    value = get_config_value(
+        "credit_meter.wings.token_value",
+        env_var="QINGFLOW_MCP_CREDIT_WINGS_TOKEN_VALUE",
+        default=None,
+    )
+    normalized = str(value or "").strip()
+    return normalized or None
+
+
+def get_credit_balance_ws_id_header_key() -> str:
+    return get_credit_shared_ws_id_header_key()
+
+
+def get_credit_usage_base_url() -> str | None:
+    value = get_config_value(
+        "credit_meter.apaas.base_url",
+        env_var="QINGFLOW_MCP_CREDIT_APAAS_BASE_URL",
+        default=None,
+    )
+    normalized = normalize_base_url(value)
+    return normalized or None
+
+
+def get_credit_usage_path() -> str:
+    value = get_config_value(
+        "credit_meter.apaas.path",
+        env_var="QINGFLOW_MCP_CREDIT_APAAS_PATH",
+        default=DEFAULT_CREDIT_USAGE_RECORD_PATH,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_CREDIT_USAGE_RECORD_PATH
+
+
+def get_credit_usage_token_key() -> str:
+    value = get_config_value(
+        "credit_meter.apaas.token_key",
+        env_var="QINGFLOW_MCP_CREDIT_APAAS_TOKEN_KEY",
+        default=DEFAULT_CREDIT_APAAS_TOKEN_HEADER_KEY,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_CREDIT_APAAS_TOKEN_HEADER_KEY
+
+
+def get_credit_usage_token_value() -> str | None:
+    value = get_config_value(
+        "credit_meter.apaas.token_value",
+        env_var="QINGFLOW_MCP_CREDIT_APAAS_TOKEN_VALUE",
+        default=DEFAULT_CREDIT_APAAS_TOKEN_VALUE,
+    )
+    normalized = str(value or "").strip()
+    return normalized or None
+
+
+def get_credit_usage_ws_id_header_key() -> str:
+    return get_credit_shared_ws_id_header_key()
+
+
+def get_credit_usage_amount() -> str:
+    value = get_config_value(
+        "credit_meter.apaas.amount",
+        env_var="QINGFLOW_MCP_CREDIT_APAAS_AMOUNT",
+        default=DEFAULT_CREDIT_USAGE_AMOUNT,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_CREDIT_USAGE_AMOUNT
+
+
+def get_repository_default_group() -> str | None:
+    value = get_config_value(
+        "repository.default_group",
+        env_var="QINGFLOW_MCP_REPOSITORY_DEFAULT_GROUP",
+        default=None,
+    )
+    normalized = str(value or "").strip()
+    return normalized or None
+
+
+def get_repository_git_remote_template() -> str:
+    value = get_config_value(
+        "repository.git_remote_template",
+        env_var="QINGFLOW_MCP_REPOSITORY_GIT_REMOTE_TEMPLATE",
+        default=DEFAULT_REPOSITORY_GIT_REMOTE_TEMPLATE,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_REPOSITORY_GIT_REMOTE_TEMPLATE
+
+
+def get_repository_preview_address_template() -> str:
+    value = get_config_value(
+        "repository.preview_address_template",
+        env_var="QINGFLOW_MCP_REPOSITORY_PREVIEW_ADDRESS_TEMPLATE",
+        default=DEFAULT_REPOSITORY_PREVIEW_ADDRESS_TEMPLATE,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_REPOSITORY_PREVIEW_ADDRESS_TEMPLATE
+
+
+def get_repository_develop_branch() -> str:
+    value = get_config_value(
+        "repository.develop_branch",
+        env_var="QINGFLOW_MCP_REPOSITORY_DEVELOP_BRANCH",
+        default=DEFAULT_REPOSITORY_DEVELOP_BRANCH,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_REPOSITORY_DEVELOP_BRANCH
+
+
+def get_repository_prod_branch() -> str:
+    value = get_config_value(
+        "repository.prod_branch",
+        env_var="QINGFLOW_MCP_REPOSITORY_PROD_BRANCH",
+        default=DEFAULT_REPOSITORY_PROD_BRANCH,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_REPOSITORY_PROD_BRANCH
+
+
+def get_repository_author_name() -> str:
+    value = get_config_value(
+        "repository.author_name",
+        env_var="QINGFLOW_MCP_REPOSITORY_AUTHOR_NAME",
+        default=DEFAULT_REPOSITORY_AUTHOR_NAME,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_REPOSITORY_AUTHOR_NAME
+
+
+def get_repository_author_email() -> str:
+    value = get_config_value(
+        "repository.author_email",
+        env_var="QINGFLOW_MCP_REPOSITORY_AUTHOR_EMAIL",
+        default=DEFAULT_REPOSITORY_AUTHOR_EMAIL,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_REPOSITORY_AUTHOR_EMAIL
+
+
+def get_repository_internal_base_url() -> str | None:
+    value = get_config_value(
+        "repository.internal_base_url",
+        env_var="QINGFLOW_MCP_REPOSITORY_INTERNAL_BASE_URL",
+        default=None,
+    )
+    if value is None:
+        return None
+    normalized = normalize_base_url(str(value).strip())
+    return normalized or None
+
+
+def get_repository_internal_share_token() -> str | None:
+    value = get_config_value(
+        "repository.internal_share_token",
+        env_var="QINGFLOW_MCP_REPOSITORY_INTERNAL_SHARE_TOKEN",
+        default=None,
+    )
+    normalized = str(value or "").strip()
+    return normalized or None
+
+
+def get_repository_internal_share_token_key() -> str:
+    value = get_config_value(
+        "repository.internal_share_token_key",
+        env_var="QINGFLOW_MCP_REPOSITORY_INTERNAL_SHARE_TOKEN_KEY",
+        default=DEFAULT_REPOSITORY_INTERNAL_SHARE_TOKEN_KEY,
+    )
+    normalized = str(value or "").strip()
+    return normalized or DEFAULT_REPOSITORY_INTERNAL_SHARE_TOKEN_KEY
+
+
+def get_repository_generate_default_agent_id() -> int | None:
+    value = get_config_value(
+        "repository.generate.default_agent_id",
+        env_var="QINGFLOW_MCP_REPOSITORY_GENERATE_DEFAULT_AGENT_ID",
+        default=None,
+    )
+    if value is None:
+        return None
+    try:
+        return int(str(value).strip())
+    except (TypeError, ValueError):
+        return None
+
+
+def get_repository_generate_default_route_prefix() -> str | None:
+    value = get_config_value(
+        "repository.generate.default_route_prefix",
+        env_var="QINGFLOW_MCP_REPOSITORY_GENERATE_DEFAULT_ROUTE_PREFIX",
+        default=None,
+    )
+    normalized = str(value or "").strip()
+    return normalized or None
+
+
+def get_repository_generate_default_token_name() -> str | None:
+    value = get_config_value(
+        "repository.generate.default_token_name",
+        env_var="QINGFLOW_MCP_REPOSITORY_GENERATE_DEFAULT_TOKEN_NAME",
+        default=None,
+    )
+    normalized = str(value or "").strip()
+    return normalized or None
+
+
+def normalize_base_url(base_url: str | None) -> str | None:
+    """规范化 base URL"""
+    if base_url is None:
+        return None
+    normalized = base_url.strip()
+    if not normalized:
+        return None
+    normalized = normalized.rstrip("/")
+    try:
+        parsed = urlsplit(normalized)
+    except ValueError:
+        return normalized
+    if not parsed.scheme or not parsed.netloc:
+        return normalized
+
+    hostname = parsed.hostname or ""
+    if hostname.lower() == "www.qingflow.com":
+        netloc = "qingflow.com"
+        if parsed.port is not None:
+            netloc = f"{netloc}:{parsed.port}"
+        normalized = urlunsplit((parsed.scheme, netloc, parsed.path, parsed.query, parsed.fragment))
+    return normalized