# -*- coding: utf-8 -*- """Public, persistable diagnostic result DTOs. This module deliberately has no AstrBot or plugin imports. Diagnostic results cross the page API and the on-disk troubleshooting history, so untrusted error text must never define the public payload. """ from __future__ import annotations import re import secrets from typing import Any from urllib.parse import urlparse DIAGNOSTIC_ENVELOPE_VERSION = "private_companion.diagnostic.v1" DIAGNOSTIC_PUBLIC_FIELDS = ( "diagnostic_version", "test_id", "duration_ms", "phase", "error_category", "retryable", "next_step", ) _VALID_IDENTIFIER = re.compile(r"^[a-z0-9][a-z0-9_-]{0,79}$") _VALID_TEST_ID = re.compile(r"^diag_[a-z0-9_]{1,40}_(?:[a-f0-9]{12,32}|legacy)$") _VALID_PHASES = frozenset({"completed", "failed", "scheduled", "running"}) _VALID_STEP_STATUSES = frozenset({"ok", "error", "warn", "info", "pending"}) _ISSUED_TEST_KINDS = frozenset({ "provider", "image_api_endpoint", "image_generation", "image_generation_text2img", "image_generation_selfie", "tts_generation", "screen_peek", "qzone_integration", "proactive_message", "model_diagnostics", "skill_similarity", }) _PUBLIC_TITLES = { "provider": "Provider diagnostic", "image_api_endpoint": "Image API endpoint diagnostic", "image_generation": "Image generation diagnostic", "image_generation_text2img": "Text-to-image diagnostic", "image_generation_selfie": "Reference image diagnostic", "tts_generation": "TTS generation diagnostic", "screen_peek": "Screen observation diagnostic", "qzone_integration": "QZone diagnostic", "proactive_message": "Proactive message diagnostic", "model_diagnostics": "Model data diagnostic", "skill_similarity": "Skill similarity diagnostic", "check": "Diagnostic test", } _PUBLIC_ERROR_LABELS = { "configuration": "Configuration is incomplete or incompatible.", "authorization": "Authentication or permission was not accepted.", "timeout": "The diagnostic call timed out.", "unavailable": "The required service is unavailable.", "validation": "The diagnostic target or parameters are invalid.", "provider": "The provider did not return a usable result.", "unknown": "The diagnostic did not complete.", "none": "", } _NEXT_STEPS = { "configuration": "Check the required model or service configuration, then test again.", "authorization": "Check the account authorization or credential configuration, then test again.", "timeout": "Check service load and network state, then retry the diagnostic.", "unavailable": "Confirm the related plugin, service, or provider is running, then test again.", "validation": "Refresh the operations page and check the selected test target.", "provider": "Check provider status and model configuration; use a fallback provider if needed.", "unknown": "Use the test id to inspect plugin logs, then retry after confirming configuration.", "none": "No action is needed.", } def diagnostic_test_id(test_kind: Any, *, token: str | None = None) -> str: """Create an opaque id with no user, endpoint, path, or prompt input.""" normalized = str(test_kind or "").strip().lower() normalized = normalized if normalized in _ISSUED_TEST_KINDS else "check" suffix = str(token or secrets.token_hex(6)).lower() if not re.fullmatch(r"[a-f0-9]{12,32}", suffix): suffix = secrets.token_hex(6) return f"diag_{normalized}_{suffix}" def classify_diagnostic_error(value: Any) -> str: text = str(value or "").lower() if not text: return "unknown" if any(token in text for token in ("timeout", "timed out", "超时", "等待其他", "排队")): return "timeout" if any(token in text for token in ("401", "403", "authorization", "unauthorized", "forbidden", "认证", "权限", "api key", "密钥")): return "authorization" if any(token in text for token in ("未知排障", "unknown test", "参数", "无效", "invalid", "校验")): return "validation" if any(token in text for token in ("missing", "configuration", "未配置", "缺少", "配置", "not configured")): return "configuration" if any(token in text for token in ("不可用", "未检测到", "未安装", "not available", "connection refused", "服务未启动")): return "unavailable" if any(token in text for token in ("provider", "模型", "tts", "调用失败", "generation", "rate limit", "429")): return "provider" return "unknown" def _as_int(value: Any, default: int = 0, *, ceiling: int = 86_400_000) -> int: try: parsed = int(float(value)) except (TypeError, ValueError): return default return min(max(0, parsed), ceiling) def _safe_identifier(value: Any, limit: int = 80) -> str: text = str(value or "").strip().lower() if not _VALID_IDENTIFIER.fullmatch(text): return "" return text[:limit] def _safe_label(value: Any, limit: int = 100) -> str: text = " ".join(str(value or "").replace("\r", " ").replace("\n", " ").split()) if not text: return "" if "traceback" in text.lower() or "authorization:" in text.lower() or "cookie:" in text.lower(): return "Internal detail is hidden." text = re.sub(r"(?i)(bearer\s+)[^\s,;]+", r"\1[hidden]", text) text = re.sub(r"(?i)(api[_ -]?key|token|secret|password)\s*[=:]\s*[^\s,;]+", r"\1=[hidden]", text) return text[:limit] def _safe_url(value: Any) -> str: raw = str(value or "").strip() if not raw: return "" try: parsed = urlparse(raw) if parsed.scheme not in {"http", "https"} or not parsed.hostname: return "" port = f":{parsed.port}" if parsed.port else "" return _safe_label(f"{parsed.scheme}://{parsed.hostname}{port}{parsed.path or ''}", 180) except ValueError: return "" def _safe_steps(value: Any) -> list[dict[str, str]]: if not isinstance(value, list): return [] items: list[dict[str, str]] = [] for raw in value[:12]: if not isinstance(raw, dict): continue status = _safe_identifier(raw.get("status"), 16) if status not in _VALID_STEP_STATUSES: status = "info" name = _safe_label(raw.get("name"), 40) or "Diagnostic step" detail = { "ok": "This stage completed.", "error": "This stage did not pass; see the next step below.", "warn": "This stage needs attention.", "pending": "This stage is still waiting.", "info": "This stage was recorded.", }[status] items.append({"name": name, "status": status, "detail": detail}) return items def _safe_test_id(value: Any, test_type: str) -> str: candidate = str(value or "").strip().lower() if _VALID_TEST_ID.fullmatch(candidate): return candidate return f"diag_{test_type or 'check'}_legacy" def _safe_test_kind(value: Any) -> str: candidate = _safe_identifier(value, 40) return candidate if candidate in _ISSUED_TEST_KINDS else "check" def normalize_diagnostic_result( result: dict[str, Any] | None, *, test_type: Any = "", duration_ms: Any = 0, test_id: Any = "", contract_version: Any = DIAGNOSTIC_ENVELOPE_VERSION, ) -> dict[str, Any]: """Project an internal result into the public, default-redacted DTO.""" source = dict(result) if isinstance(result, dict) else {} kind = _safe_test_kind(test_type or source.get("type")) ok = bool(source.get("ok")) pending = bool(source.get("pending")) and not ok raw_error = source.get("error") or source.get("detail") category = "none" if (ok or pending) else classify_diagnostic_error(raw_error) phase = "completed" if ok else ("scheduled" if pending else "failed") supplied_phase = _safe_identifier(source.get("phase"), 20) if supplied_phase in _VALID_PHASES and ((supplied_phase == "running" and pending) or supplied_phase == phase): phase = supplied_phase retryable = category in {"timeout", "unavailable"} if category == "provider": retryable = any(token in str(raw_error or "").lower() for token in ("429", "rate limit", "临时", "network", "connection")) supplied_id = test_id or source.get("test_id") public_id = _safe_test_id(supplied_id, kind) if not supplied_id: public_id = f"diag_{kind}_legacy" duration = _as_int(duration_ms) or _as_int(source.get("duration_ms")) or _as_int(source.get("elapsed_ms")) title = _PUBLIC_TITLES[kind] detail = "The test completed." if ok else ("The test is scheduled or running." if pending else _PUBLIC_ERROR_LABELS[category]) return { "diagnostic_version": _safe_label(contract_version, 60) or DIAGNOSTIC_ENVELOPE_VERSION, "test_id": public_id, "duration_ms": duration, "phase": phase, "error_category": category, "retryable": retryable, "next_step": _NEXT_STEPS[category], "type": kind, "test_key": _safe_identifier(source.get("test_key"), 80), "ok": ok, "pending": pending, "outcome_type": _safe_identifier(source.get("outcome_type"), 40), "title": title, "backend": _safe_label(source.get("backend"), 80), "image_model": _safe_label(source.get("image_model"), 80), "image_size": _safe_label(source.get("image_size"), 40), "endpoint_index": _as_int(source.get("endpoint_index"), -1, ceiling=10_000), "endpoint_name": _safe_label(source.get("endpoint_name"), 80), "endpoint_platform": _safe_label(source.get("endpoint_platform"), 60), "endpoint_url": _safe_url(source.get("endpoint_url")), "endpoint_status": _safe_identifier(source.get("endpoint_status"), 20), "endpoint_timeout_seconds": _as_int(source.get("endpoint_timeout_seconds")), "queue_wait_ms": _as_int(source.get("queue_wait_ms")), "workflow_kind": _safe_identifier(source.get("workflow_kind"), 20), "used_reference": bool(source.get("used_reference")), "reference_id": _safe_identifier(source.get("reference_id"), 60), "reference_kind": _safe_identifier(source.get("reference_kind"), 40), "reference_roles": [_safe_identifier(item, 40) for item in (source.get("reference_roles") if isinstance(source.get("reference_roles"), list) else [])[:8] if _safe_identifier(item, 40)], "wardrobe_mode": _safe_identifier(source.get("wardrobe_mode"), 40), "wardrobe_category": _safe_identifier(source.get("wardrobe_category"), 40), "outfit_locked": bool(source.get("outfit_locked")), "daily_outfit_removed": bool(source.get("daily_outfit_removed")), "final_presets": [_safe_identifier(item, 60) for item in (source.get("final_presets") if isinstance(source.get("final_presets"), list) else [])[:6] if _safe_identifier(item, 60)], "prompt_hash": _safe_identifier(source.get("prompt_hash"), 80), "provider": _safe_label(source.get("provider"), 100), "file_size": _as_int(source.get("file_size")), "detail": detail, "error": "" if (ok or pending) else _PUBLIC_ERROR_LABELS[category], "timeout_seconds": _as_int(source.get("timeout_seconds")), "test_timeout_seconds": _as_int(source.get("test_timeout_seconds")), "estimated_timeout_seconds": _as_int(source.get("estimated_timeout_seconds")), "timeout_budget": _safe_label(source.get("timeout_budget"), 120), "backend_preference": _safe_identifier(source.get("backend_preference"), 30), "external_timeout_seconds": _as_int(source.get("external_timeout_seconds")), "backup_external_timeout_seconds": _as_int(source.get("backup_external_timeout_seconds")), "comfyui_wait_seconds": _as_int(source.get("comfyui_wait_seconds")), "backup_external": bool(source.get("backup_external")), "external_queue_lock": bool(source.get("external_queue_lock")), "tool_call_timeout_seconds": _as_int(source.get("tool_call_timeout_seconds")), "context_chars": _as_int(source.get("context_chars")), "action": _safe_identifier(source.get("action"), 60), "reason": _safe_identifier(source.get("reason"), 40), "extra_count": _as_int(source.get("extra_count")), "local_count": _as_int(source.get("local_count")), "model_count": _as_int(source.get("model_count")), "suggestion_count": _as_int(source.get("suggestion_count")), "steps": _safe_steps(source.get("steps")), "elapsed_ms": duration, "ran_at": float(source.get("ran_at") or 0) if str(source.get("ran_at") or "").replace(".", "", 1).isdigit() else 0.0, "ran_at_text": _safe_label(source.get("ran_at_text"), 40), # Compatibility keys are deliberately blank: they can carry paths, # prompts, samples, or conversation text in historical result shapes. "path": "", "prompt_path": "", "reference_image": "", "umo": "", "prompt": "", "text": "", "sample": "", "text_preview": "", "original_text_preview": "", "final_text_preview": "", "diagnostic_detail": "", "warnings": [], "suggestions": [], "sections": [], }