dsh-cloudq 0.1.0

package/skills/cloudq/scripts/tcloud_api.py

@@ -0,0 +1,329 @@
+#!/usr/bin/env python3
+"""
+腾讯云 API 签名 v3 通用调用脚本 (Python 版)
+基于腾讯云 API 签名 v3 文档实现: https://cloud.tencent.com/document/product/213/30654
+
+纯 Python 标准库实现，支持 Windows / Linux / macOS 跨平台运行。
+不依赖 curl、openssl、jq 等外部工具。
+
+用法 (命令行):
+    python3 tcloud_api.py <service> <host> <action> <version> [payload] [region]
+
+示例:
+    python3 tcloud_api.py advisor advisor.tencentcloudapi.com DescribeArchList 2020-07-21 '{"PageNumber":1,"PageSize":10}'
+
+作为模块导入:
+    from tcloud_api import call_api
+    result = call_api("advisor", "advisor.tencentcloudapi.com",
+                      "DescribeArchList", "2020-07-21",
+                      {"PageNumber": 1, "PageSize": 10})
+
+环境变量（必须提前设置）:
+    TENCENTCLOUD_SECRET_ID  - 腾讯云 SecretId
+    TENCENTCLOUD_SECRET_KEY - 腾讯云 SecretKey
+    TENCENTCLOUD_TOKEN      - 临时密钥 Token（可选，使用临时密钥时设置）
+
+输出格式（统一 JSON）:
+    成功: {"success": true, "action": "<Action>", "data": {...}, "requestId": "xxx"}
+    失败: {"success": false, "action": "<Action>", "error": {"code": "xxx", "message": "xxx"}, "requestId": "xxx"}
+"""
+
+import hashlib
+import hmac
+import json
+import os
+import ssl
+import sys
+import time
+from datetime import datetime, timezone
+from typing import Union
+from urllib.request import Request, urlopen
+from urllib.error import URLError, HTTPError
+
+
+def _get_ssl_context():
+    """获取 SSL 上下文，兼容各平台 CA 证书差异"""
+    try:
+        import certifi
+        return ssl.create_default_context(cafile=certifi.where())
+    except ImportError:
+        # certifi 不可用时降级到系统默认 CA（Windows/Linux 系统 CA 通常可用）
+        return ssl.create_default_context()
+
+
+def _sign_tc3(key: bytes, msg: str) -> bytes:
+    """TC3 HMAC-SHA256 签名辅助函数"""
+    return hmac.new(key, msg.encode("utf-8"), hashlib.sha256).digest()
+
+
+def _output_json(obj: dict) -> str:
+    """统一 JSON 输出"""
+    return json.dumps(obj, ensure_ascii=False)
+
+
+def _make_error(action: str, code: str, message: str, request_id: str = "") -> dict:
+    """构造统一错误结果"""
+    return {
+        "success": False,
+        "action": action,
+        "error": {"code": code, "message": message},
+        "requestId": request_id,
+    }
+
+
+def _make_success(action: str, data: dict, request_id: str) -> dict:
+    """构造统一成功结果"""
+    return {
+        "success": True,
+        "action": action,
+        "data": data,
+        "requestId": request_id,
+    }
+
+
+def call_api(service: str, host: str, action: str, version: str,
+             payload: Union[dict, str] = None, region: str = "ap-guangzhou",
+             secret_id: str = None, secret_key: str = None,
+             token: str = None) -> dict:
+    """
+    调用腾讯云 API（TC3-HMAC-SHA256 签名）
+
+    Args:
+        service: 服务名（如 advisor, sts, cam）
+        host: 接口域名（如 advisor.tencentcloudapi.com）
+        action: 接口名称（如 DescribeArchList）
+        version: 接口版本（如 2020-07-21）
+        payload: 请求体，dict 或 JSON 字符串
+        region: 地域，默认 ap-guangzhou
+        secret_id: SecretId，不传则通过 credential_manager 或环境变量获取
+        secret_key: SecretKey，不传则通过 credential_manager 或环境变量获取
+        token: 临时密钥 Token，不传则通过 credential_manager 或环境变量获取
+
+    Returns:
+        dict: 统一格式的结果字典
+    """
+    # 密钥：优先使用显式传入，其次通过 credential_manager 统一获取
+    cred_source = "env"
+    if not secret_id or not secret_key:
+        try:
+            from credential_manager import (
+                get_credential, CredentialExpiredError, CredentialNotFoundError,
+            )
+            cred = get_credential()
+            secret_id = secret_id or cred["secretId"]
+            secret_key = secret_key or cred["secretKey"]
+            token = token or cred.get("token", "")
+            cred_source = cred.get("source", "env")
+        except ImportError:
+            # credential_manager 不可用，回退到环境变量
+            secret_id = secret_id or os.environ.get("TENCENTCLOUD_SECRET_ID", "")
+            secret_key = secret_key or os.environ.get("TENCENTCLOUD_SECRET_KEY", "")
+            token = token or os.environ.get("TENCENTCLOUD_TOKEN", "")
+        except CredentialExpiredError as e:
+            return _make_error(
+                action, "CredentialExpired",
+                f"OAuth 凭证已过期，需要重新授权登录。{e}"
+            )
+        except CredentialNotFoundError:
+            return _make_error(
+                action, "NeedAuth",
+                "未找到凭证，请先通过 OAuth 登录或配置 AK/SK 环境变量。"
+            )
+        except Exception as e:
+            return _make_error(
+                action, "NeedAuth", str(e)
+            )
+
+    if not secret_id or not secret_key:
+        return _make_error(
+            action, "MissingCredentials",
+            "未配置凭证。请通过 OAuth 登录或配置 AK/SK 环境变量。\n"
+            "OAuth 登录: python3 scripts/login.py\n"
+            "密钥获取: https://console.cloud.tencent.com/cam/capi"
+        )
+
+    # ---- 服务白名单限制 ----
+    # OAuth: 仅允许 advisor（OAuth 临时密钥仅有智能顾问权限）
+    # AK/SK: 允许 advisor + cam + sts（check_env/create_role/login_url 需要）
+    _OAUTH_ALLOWED_SERVICES = {"advisor"}
+    _AKSK_ALLOWED_SERVICES = {"advisor", "cam", "sts"}
+
+    if cred_source == "oauth":
+        allowed = _OAUTH_ALLOWED_SERVICES
+        deny_hint = f"如需调用 {service} 服务，请配置 AK/SK 环境变量。"
+    else:
+        allowed = _AKSK_ALLOWED_SERVICES
+        deny_hint = f"CloudQ 不支持调用 {service} 服务。"
+
+    if service not in allowed:
+        return _make_error(
+            action, "ServiceNotAllowed",
+            f"当前凭证不允许调用 {service} 服务（允许: {', '.join(sorted(allowed))}）。{deny_hint}"
+        )
+
+    # 请求体
+    if payload is None:
+        payload_str = "{}"
+    elif isinstance(payload, dict):
+        payload_str = json.dumps(payload, separators=(",", ":"))
+    else:
+        payload_str = str(payload)
+
+    # 签名参数
+    algorithm = "TC3-HMAC-SHA256"
+    timestamp = int(time.time())
+    date = datetime.fromtimestamp(timestamp, tz=timezone.utc).strftime("%Y-%m-%d")
+
+    # 步骤 1：拼接规范请求串
+    hashed_payload = hashlib.sha256(payload_str.encode("utf-8")).hexdigest()
+    canonical_request = (
+        f"POST\n"
+        f"/\n"
+        f"\n"
+        f"content-type:application/json; charset=utf-8\n"
+        f"host:{host}\n"
+        f"x-tc-action:{action.lower()}\n"
+        f"\n"
+        f"content-type;host;x-tc-action\n"
+        f"{hashed_payload}"
+    )
+
+    # 步骤 2：拼接待签名字符串
+    credential_scope = f"{date}/{service}/tc3_request"
+    hashed_canonical_request = hashlib.sha256(
+        canonical_request.encode("utf-8")
+    ).hexdigest()
+    string_to_sign = (
+        f"{algorithm}\n"
+        f"{timestamp}\n"
+        f"{credential_scope}\n"
+        f"{hashed_canonical_request}"
+    )
+
+    # 步骤 3：计算签名
+    secret_date = _sign_tc3(f"TC3{secret_key}".encode("utf-8"), date)
+    secret_service = _sign_tc3(secret_date, service)
+    secret_signing = _sign_tc3(secret_service, "tc3_request")
+    signature = hmac.new(
+        secret_signing, string_to_sign.encode("utf-8"), hashlib.sha256
+    ).hexdigest()
+
+    # 步骤 4：拼接 Authorization
+    authorization = (
+        f"{algorithm} "
+        f"Credential={secret_id}/{credential_scope}, "
+        f"SignedHeaders=content-type;host;x-tc-action, "
+        f"Signature={signature}"
+    )
+
+    # 步骤 5：发送请求
+    headers = {
+        "Authorization": authorization,
+        "Content-Type": "application/json; charset=utf-8",
+        "Host": host,
+        "X-TC-Action": action,
+        "X-TC-Timestamp": str(timestamp),
+        "X-TC-Version": version,
+        "X-TC-Region": region,
+    }
+    if token:
+        headers["X-TC-Token"] = token
+
+    req = Request(
+        f"https://{host}",
+        data=payload_str.encode("utf-8"),
+        headers=headers,
+        method="POST",
+    )
+
+    try:
+        ctx = _get_ssl_context()
+        with urlopen(req, context=ctx, timeout=30) as resp:
+            response_body = resp.read().decode("utf-8")
+    except HTTPError as e:
+        try:
+            body = e.read().decode("utf-8")
+            # 尝试解析 API 错误响应
+            data = json.loads(body)
+            response = data.get("Response", {})
+            error = response.get("Error", {})
+            if error:
+                return _make_error(
+                    action,
+                    error.get("Code", "HTTPError"),
+                    error.get("Message", f"HTTP {e.code}"),
+                    response.get("RequestId", ""),
+                )
+        except Exception:
+            pass
+        return _make_error(
+            action, "HTTPError",
+            f"HTTP 请求失败 (状态码 {e.code}): {e.reason}"
+        )
+    except URLError as e:
+        return _make_error(
+            action, "NetworkError",
+            f"网络连接失败，请检查网络和域名 {host} 是否可达: {e.reason}"
+        )
+    except Exception as e:
+        return _make_error(
+            action, "NetworkError",
+            f"请求异常: {e}"
+        )
+
+    # 步骤 6：解析响应
+    try:
+        data = json.loads(response_body)
+    except json.JSONDecodeError:
+        return _make_error(action, "ParseError", "响应不是有效的 JSON")
+
+    response = data.get("Response", {})
+    request_id = response.get("RequestId", "")
+
+    if "Error" in response:
+        err = response["Error"]
+        return _make_error(
+            action,
+            err.get("Code", "Unknown"),
+            err.get("Message", "未知错误"),
+            request_id,
+        )
+
+    # 成功：移除 RequestId 后将剩余字段作为 data
+    result_data = {k: v for k, v in response.items() if k != "RequestId"}
+    return _make_success(action, result_data, request_id)
+
+
+def main():
+    """命令行入口"""
+    args = sys.argv[1:]
+
+    if len(args) < 4:
+        print(_output_json(_make_error(
+            "", "MissingParameter",
+            "缺少必要参数。用法: python3 tcloud_api.py <service> <host> <action> <version> [payload] [region]"
+        )))
+        sys.exit(1)
+
+    service = args[0]
+    host = args[1]
+    action = args[2]
+    version = args[3]
+    payload_str = args[4] if len(args) > 4 else "{}"
+    region = args[5] if len(args) > 5 else "ap-guangzhou"
+
+    # 解析 payload
+    try:
+        payload = json.loads(payload_str)
+    except json.JSONDecodeError:
+        payload = payload_str
+
+    result = call_api(service, host, action, version, payload, region)
+    print(_output_json(result))
+
+    if not result.get("success"):
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/cloudq/scripts/tcloud_async_task.py

@@ -0,0 +1,345 @@
+#!/usr/bin/env python3
+"""
+CloudQ 异步任务管理脚本
+
+用于管理 CloudQ 异步对话任务（Async=true 模式）：
+- DescribeCloudQAsyncTask：查询异步任务执行状态和结果
+- CancelCloudQAsyncTask：取消异步后台编排任务
+
+通过 tcloud_api.call_api() 调用标准腾讯云 API（非 SSE）。
+
+用法 (命令行):
+    # 查询任务状态
+    python3 tcloud_async_task.py query <chat_id> <session_id>
+
+    # 取消任务
+    python3 tcloud_async_task.py cancel <chat_id> [session_id]
+
+    # Poll 轮询直到完成（自动循环 query，内部自适应间隔）
+    python3 tcloud_async_task.py poll <chat_id> <session_id> [timeout=1200]
+
+示例:
+    python3 tcloud_async_task.py query chat-7f3a9b2e1d4c sess-e5b8c1a0f6d2
+    python3 tcloud_async_task.py cancel chat-7f3a9b2e1d4c sess-e5b8c1a0f6d2
+    python3 tcloud_async_task.py poll chat-7f3a9b2e1d4c sess-e5b8c1a0f6d2
+
+作为模块导入:
+    from tcloud_async_task import query_async_task, cancel_async_task, poll_until_complete
+
+    result = query_async_task("chat-xxx", "sess-xxx")
+    if result["success"]:
+        status = result["data"]["Status"]
+        content = result["data"]["Content"]
+
+    result = cancel_async_task("chat-xxx", "sess-xxx")
+    if result["success"]:
+        print("任务已取消")
+
+输出格式（统一 JSON）:
+    成功: {"success": true, "action": "...", "data": {...}, "requestId": "..."}
+    失败: {"success": false, "action": "...", "error": {...}, "requestId": "..."}
+"""
+
+import json
+import sys
+import time
+
+# ---------------------------------------------------------------------------
+# 固定参数
+# ---------------------------------------------------------------------------
+SERVICE = "advisor"
+HOST = "advisor.ai.tencentcloudapi.com"
+VERSION = "2020-07-21"
+ACTION_QUERY = "DescribeCloudQAsyncTask"
+ACTION_CANCEL = "CancelCloudQAsyncTask"
+
+# 轮询参数
+DEFAULT_POLL_INTERVAL = 5   # 秒（固定 5s 间隔）
+DEFAULT_POLL_TIMEOUT = 1200 # 秒（CloudQ 长任务最长可达 20 分钟）
+FIXED_POLL_INTERVAL = 5     # 秒（固定，不允许用户自定义）
+
+
+# ---------------------------------------------------------------------------
+# 公共函数
+# ---------------------------------------------------------------------------
+
+def _output_json(obj: dict) -> str:
+    return json.dumps(obj, ensure_ascii=False)
+
+
+# ---------------------------------------------------------------------------
+# DescribeCloudQAsyncTask - 查询异步任务状态
+# ---------------------------------------------------------------------------
+
+def query_async_task(chat_id: str, session_id: str,
+                     secret_id: str = None, secret_key: str = None,
+                     token: str = None) -> dict:
+    """
+    查询异步任务状态。
+
+    Args:
+        chat_id:    异步任务 ID（由 accepted 帧 ChatId 返回）
+        session_id: 会话 ID（由 accepted 帧 SessionId 返回）
+        secret_id:  SecretId，不传则自动获取
+        secret_key: SecretKey，不传则自动获取
+        token:      临时密钥 Token
+
+    Returns:
+        dict: {
+            "success": true/false,
+            "action": "DescribeCloudQAsyncTask",
+            "data": {
+                "Status": "running|completed|failed|cancelled|timeout|not_found",
+                "FinishReason": "stop|user_stopped|timeout|error" (running/not_found时为空),
+                "Content": "分析结果...",
+                "SessionID": "sess-xxx",
+                "ChatID": "chat-xxx"
+            },
+            "requestId": "..."
+        }
+    """
+    if not chat_id:
+        return {
+            "success": False,
+            "action": ACTION_QUERY,
+            "error": {"code": "MissingParameter", "message": "ChatID 为必填参数"},
+            "requestId": "",
+        }
+    if not session_id:
+        return {
+            "success": False,
+            "action": ACTION_QUERY,
+            "error": {"code": "MissingParameter", "message": "SessionID 为必填参数"},
+            "requestId": "",
+        }
+
+    try:
+        from tcloud_api import call_api
+    except ImportError:
+        return {
+            "success": False,
+            "action": ACTION_QUERY,
+            "error": {
+                "code": "ImportError",
+                "message": "无法导入 tcloud_api 模块，请确保 scripts 目录在 Python 路径中"
+            },
+            "requestId": "",
+        }
+
+    payload = {"ChatID": chat_id, "SessionID": session_id}
+
+    result = call_api(
+        service=SERVICE, host=HOST, action=ACTION_QUERY,
+        version=VERSION, payload=payload,
+        secret_id=secret_id, secret_key=secret_key, token=token,
+    )
+    return result
+
+
+# ---------------------------------------------------------------------------
+# CancelCloudQAsyncTask - 取消异步任务
+# ---------------------------------------------------------------------------
+
+def cancel_async_task(chat_id: str, session_id: str = "",
+                      secret_id: str = None, secret_key: str = None,
+                      token: str = None) -> dict:
+    """
+    取消异步后台编排任务。
+
+    Args:
+        chat_id:    异步任务 ID（由 accepted 帧 ChatId 返回）
+        session_id: 会话 ID（可选，仅用于日志关联）
+        secret_id:  SecretId，不传则自动获取
+        secret_key: SecretKey，不传则自动获取
+        token:      临时密钥 Token
+
+    Returns:
+        dict: {
+            "success": true/false,
+            "action": "CancelCloudQAsyncTask",
+            "data": {"Success": true/false},
+            "requestId": "..."
+        }
+    """
+    if not chat_id:
+        return {
+            "success": False,
+            "action": ACTION_CANCEL,
+            "error": {"code": "MissingParameter", "message": "ChatID 为必填参数"},
+            "requestId": "",
+        }
+
+    try:
+        from tcloud_api import call_api
+    except ImportError:
+        return {
+            "success": False,
+            "action": ACTION_CANCEL,
+            "error": {
+                "code": "ImportError",
+                "message": "无法导入 tcloud_api 模块，请确保 scripts 目录在 Python 路径中"
+            },
+            "requestId": "",
+        }
+
+    payload = {"ChatID": chat_id}
+    if session_id:
+        payload["SessionID"] = session_id
+
+    result = call_api(
+        service=SERVICE, host=HOST, action=ACTION_CANCEL,
+        version=VERSION, payload=payload,
+        secret_id=secret_id, secret_key=secret_key, token=token,
+    )
+    return result
+
+
+# ---------------------------------------------------------------------------
+# 便捷轮询函数
+# ---------------------------------------------------------------------------
+
+def poll_until_complete(chat_id: str, session_id: str,
+                        timeout: int = DEFAULT_POLL_TIMEOUT,
+                        on_status=None) -> dict:
+    """
+    轮询异步任务直到完成、失败或超时。
+
+    Args:
+        chat_id:    异步任务 ID
+        session_id: 会话 ID
+        interval:   轮询间隔（秒），范围 [2, 5]
+        timeout:    总超时（秒），默认 120
+        on_status:  可选回调，status 变更时调用 on_status(status, result)
+
+    Returns:
+        dict: 最后一次 query_async_task 的返回结果
+    """
+    interval = FIXED_POLL_INTERVAL
+    elapsed = 0
+    last_status = None
+    terminal_statuses = {"completed", "failed", "cancelled", "timeout", "not_found"}
+    retried = False
+
+    while elapsed < timeout:
+        result = query_async_task(chat_id, session_id)
+
+        if not result.get("success"):
+            if not retried:
+                retried = True
+                time.sleep(1)
+                continue  # 重试一次
+            # 重试后仍失败，返回错误
+            return result
+
+        status = result.get("data", {}).get("Status", "unknown")
+
+        # 状态变更回调
+        if on_status and status != last_status:
+            on_status(status, result)
+
+        # 到达终态
+        if status in terminal_statuses:
+            return result
+
+        # 等待后继续轮询
+        time.sleep(interval)
+        elapsed += interval
+        last_status = status
+
+    # 超时
+    return {
+        "success": False,
+        "action": "PollTimeout",
+        "error": {
+            "code": "PollTimeout",
+            "message": f"轮询超时（{timeout}秒），任务可能仍在执行中"
+        },
+        "requestId": "",
+    }
+
+
+# ---------------------------------------------------------------------------
+# 命令行入口
+# ---------------------------------------------------------------------------
+
+def _print_usage():
+    print(_output_json({
+        "success": False,
+        "action": ACTION_QUERY,
+        "error": {
+            "code": "MissingParameter",
+            "message": (
+                "用法:\n"
+                "  python3 tcloud_async_task.py query <chat_id> <session_id>\n"
+                "  python3 tcloud_async_task.py cancel <chat_id> [session_id]\n"
+                "  python3 tcloud_async_task.py poll <chat_id> <session_id> [timeout]"
+            )
+        },
+        "requestId": "",
+    }))
+
+
+def main():
+    """命令行入口"""
+    import io
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+    else:
+        sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
+        sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8", errors="replace")
+
+    args = sys.argv[1:]
+    if len(args) < 2:
+        _print_usage()
+        sys.exit(1)
+
+    command = args[0].lower()
+    chat_id = args[1] if len(args) > 1 else ""
+
+    if command == "query":
+        session_id = args[2] if len(args) > 2 else ""
+        result = query_async_task(chat_id, session_id)
+        print(_output_json(result))
+        if not result.get("success"):
+            sys.exit(1)
+
+    elif command == "cancel":
+        session_id = args[2] if len(args) > 2 else ""
+        result = cancel_async_task(chat_id, session_id)
+        print(_output_json(result))
+        if not result.get("success"):
+            sys.exit(1)
+
+    elif command == "poll":
+        session_id = args[2] if len(args) > 2 else ""
+        try:
+            timeout = int(args[3]) if len(args) > 3 else DEFAULT_POLL_TIMEOUT
+        except (ValueError, TypeError):
+            print(_output_json({
+                "success": False, "action": ACTION_QUERY,
+                "error": {"code": "InvalidParameter",
+                          "message": "timeout 必须是整数"},
+                "requestId": "",
+            }))
+            sys.exit(1)
+
+        def on_status(status, result):
+            print(f"[poll] Status: {status}", file=sys.stderr, flush=True)
+
+        result = poll_until_complete(
+            chat_id, session_id,
+            timeout=timeout,
+            on_status=on_status,
+        )
+        print(_output_json(result))
+        if not result.get("success"):
+            sys.exit(1)
+
+    else:
+        _print_usage()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()