union-py-app 1.0.0

package/app/tools/business.py

@@ -0,0 +1,183 @@
+"""定义知识检索和运行分析 Agent 可调用的业务工具。"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Annotated
+from zoneinfo import ZoneInfo
+
+import anyio
+from pydantic import Field
+from pydantic_ai import RunContext, Tool
+from pydantic_ai.toolsets import FunctionToolset
+
+from app.agent.runtime.deps import RunDeps
+from app.utils.api_client import ToolError, ToolResult
+
+QueryDate = Annotated[str, Field(pattern=r"^\d{8}$")]
+_BIGDATA_REQUEST_TIMEOUT_SECONDS = 180
+_BIGDATA_TIMEOUT_ATTEMPTS = 3
+_BIGDATA_TOOL_TIMEOUT_SECONDS = 600
+
+
+async def knowledge_search(
+    ctx: RunContext[RunDeps],
+    query: Annotated[str, Field(min_length=1, max_length=2000)],
+    top_k: Annotated[int | None, Field(ge=1, le=20)] = None,
+) -> ToolResult:
+    """检索共享知识库中的制度、SOP、机制和名词解释证据。"""
+    if ctx.deps.rag_service is None:
+        raise ToolError("知识库当前不可用。")
+    try:
+        data, status = await anyio.to_thread.run_sync(
+            ctx.deps.rag_service.knowledge_search,
+            query,
+            top_k,
+            abandon_on_cancel=True,
+        )
+    except Exception as exc:
+        raise ToolError("知识库检索失败。") from exc
+    if status != "success":
+        raise ToolError("知识库检索失败。")
+    return ToolResult(status="success", data=data)
+
+
+async def running_analysis_resolve_member_org(
+    ctx: RunContext[RunDeps],
+    org_name: Annotated[str, Field(min_length=1, max_length=128)],
+) -> ToolResult:
+    """根据机构名称、简称或别名解析可信 orgCode。"""
+    return await ctx.deps.api_client.call(
+        path="/agent/getOrgInfo",
+        payload={"orgName": org_name},
+        timeout=10,
+    )
+
+
+async def running_analysis_query_member_metrics(
+    ctx: RunContext[RunDeps],
+    start_date: QueryDate,
+    end_date: QueryDate,
+    org_code_list: Annotated[list[str], Field(min_length=1, max_length=100)],
+) -> ToolResult:
+    """查询指定成员机构在日期范围内的每日运行指标。"""
+    _validate_metric_end_date(end_date)
+    return await ctx.deps.api_client.call(
+        path="/agent/queryBigData",
+        payload={
+            "interfaceName": "runing_cnt.bank",
+            "params": {
+                "startDate": start_date,
+                "endDate": end_date,
+                "orgCodeList": org_code_list,
+            },
+        },
+        timeout=_BIGDATA_REQUEST_TIMEOUT_SECONDS,
+        timeout_attempts=_BIGDATA_TIMEOUT_ATTEMPTS,
+    )
+
+
+async def running_analysis_query_all_member_metrics(
+    ctx: RunContext[RunDeps],
+    start_date: QueryDate,
+    end_date: QueryDate,
+) -> ToolResult:
+    """查询全部成员机构在日期范围内的每日运行指标。"""
+    _validate_metric_end_date(end_date)
+    return await ctx.deps.api_client.call(
+        path="/agent/queryBigData",
+        payload={
+            "interfaceName": "runing_cnt.bank",
+            "params": {"startDate": start_date, "endDate": end_date},
+        },
+        timeout=_BIGDATA_REQUEST_TIMEOUT_SECONDS,
+        timeout_attempts=_BIGDATA_TIMEOUT_ATTEMPTS,
+    )
+
+
+async def running_analysis_query_chain_metrics(
+    ctx: RunContext[RunDeps],
+    start_date: QueryDate,
+    end_date: QueryDate,
+) -> ToolResult:
+    """查询全链路在日期范围内的每日运行指标。"""
+    _validate_metric_end_date(end_date)
+    return await ctx.deps.api_client.call(
+        path="/agent/queryBigData",
+        payload={
+            "interfaceName": "runing_cnt.full_link",
+            "params": {"startDate": start_date, "endDate": end_date},
+        },
+        timeout=_BIGDATA_REQUEST_TIMEOUT_SECONDS,
+        timeout_attempts=_BIGDATA_TIMEOUT_ATTEMPTS,
+    )
+
+
+async def running_analysis_query_changes(
+    ctx: RunContext[RunDeps],
+    org_code: Annotated[str, Field(min_length=1, max_length=64)],
+    start_date: QueryDate,
+    end_date: QueryDate,
+) -> ToolResult:
+    """查询机构在日期范围内的变更通知、状态、评价和影响范围。"""
+    return await ctx.deps.api_client.call(
+        path="/agent/announceList",
+        payload={
+            "org_code": org_code,
+            "planned_start_time": start_date,
+            "planned_start_time_end": end_date,
+        },
+        timeout=10,
+    )
+
+
+async def running_analysis_query_faults(
+    ctx: RunContext[RunDeps],
+    org_code: Annotated[str, Field(min_length=1, max_length=64)],
+    start_date: QueryDate,
+    end_date: QueryDate,
+) -> ToolResult:
+    """查询机构在日期范围内的 Jira 故障、影响、原因及状态。"""
+    return await ctx.deps.api_client.call(
+        path="/agent/getJiraInfo",
+        payload={"orgCode": org_code, "startDate": start_date, "endDate": end_date},
+        timeout=10,
+    )
+
+
+def _validate_metric_end_date(end_date: str) -> None:
+    today = datetime.now(ZoneInfo("Asia/Shanghai")).strftime("%Y%m%d")
+    if end_date > today:
+        raise ToolError(f"运行指标结束日期不得晚于当前业务日期 {today}。")
+
+
+def knowledge_toolset(timeout: float) -> FunctionToolset[RunDeps]:
+    return FunctionToolset[RunDeps](
+        [knowledge_search],
+        timeout=timeout,
+        max_retries=2,
+    )
+
+
+def running_analysis_toolset(timeout: float) -> FunctionToolset[RunDeps]:
+    return FunctionToolset[RunDeps](
+        [
+            running_analysis_resolve_member_org,
+            Tool(
+                running_analysis_query_member_metrics,
+                timeout=_BIGDATA_TOOL_TIMEOUT_SECONDS,
+            ),
+            Tool(
+                running_analysis_query_all_member_metrics,
+                timeout=_BIGDATA_TOOL_TIMEOUT_SECONDS,
+            ),
+            Tool(
+                running_analysis_query_chain_metrics,
+                timeout=_BIGDATA_TOOL_TIMEOUT_SECONDS,
+            ),
+            running_analysis_query_changes,
+            running_analysis_query_faults,
+        ],
+        timeout=timeout,
+        max_retries=2,
+    )

package/app/utils/__init__.py

@@ -0,0 +1 @@
+"""存放不依赖 Agent 定义的通用业务 API 辅助实现。"""

package/app/utils/api_client.py

@@ -0,0 +1,108 @@
+"""封装工具调用所需的认证 HTTP 请求、结果校验与数据边界。"""
+
+from __future__ import annotations
+
+from time import monotonic
+from typing import Any, Literal
+
+import httpx
+from pydantic import BaseModel, ConfigDict
+from pydantic_ai import ModelRetry, ToolFailed
+
+from app.utils.control_auth import ControlAuth
+from app.utils.request_logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class ToolResult(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    status: Literal["success"]
+    data: Any
+
+
+class ToolError(ModelRetry):
+    pass
+
+
+class ApiClient:
+    def __init__(
+        self,
+        *,
+        http: httpx.AsyncClient,
+        base_url: str,
+        auth: ControlAuth,
+    ) -> None:
+        self._http = http
+        self._base_url = base_url.rstrip("/")
+        self._auth = auth
+
+    async def call(
+        self,
+        *,
+        path: str,
+        payload: dict[str, Any],
+        timeout: float,
+        timeout_attempts: int = 1,
+    ) -> ToolResult:
+        if timeout_attempts < 1:
+            raise ValueError("timeout_attempts must be positive")
+        started = monotonic()
+        logger.info("Tool request started path=%r", path)
+        for attempt in range(1, timeout_attempts + 1):
+            try:
+                response = await self._http.post(
+                    f"{self._base_url}{path}",
+                    json=payload,
+                    headers=self._auth.headers(),
+                    timeout=timeout,
+                )
+                break
+            except httpx.TimeoutException as exc:
+                logger.warning(
+                    "Tool request timeout path=%r attempt=%s/%s timeout_seconds=%s",
+                    path,
+                    attempt,
+                    timeout_attempts,
+                    timeout,
+                )
+                if attempt == timeout_attempts:
+                    raise ToolFailed(
+                        f"上游查询连续 {timeout_attempts} 次超时，请稍后重试。"
+                    ) from exc
+            except httpx.HTTPError as exc:
+                logger.error("Tool request failed path=%r error_type=%s", path, type(exc).__name__)
+                raise
+        try:
+            result = _tool_result(response)
+        except ToolError as exc:
+            logger.warning(
+                "Tool request rejected path=%r status=%s reason=%s",
+                path,
+                response.status_code,
+                exc,
+            )
+            raise
+        logger.info(
+            "Tool request completed path=%r status=%s elapsed_ms=%.0f",
+            path,
+            response.status_code,
+            (monotonic() - started) * 1000,
+        )
+        return result
+
+
+def _tool_result(response: httpx.Response) -> ToolResult:
+    if response.status_code >= 400:
+        raise ToolError(f"上游查询失败，HTTP {response.status_code}。")
+    try:
+        body = response.json()
+    except ValueError as exc:
+        raise ToolError("上游没有返回有效 JSON。") from exc
+    data = body.get("data") if isinstance(body, dict) else None
+    if isinstance(data, dict) and "data" in data:
+        data = data["data"]
+    if data is None:
+        raise ToolError("上游没有返回可用数据。")
+    return ToolResult(status="success", data=data)

package/app/utils/control_auth.py

@@ -0,0 +1,50 @@
+"""封装访问 Control 时互斥且不可回显的运行认证凭证。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+
+@dataclass(frozen=True)
+class ControlAuth:
+    """A server-created CAS or scheduled credential, never both."""
+
+    authentication_type: Literal["CAS", "SCHEDULED"]
+    _cas_session_id: str | None = field(default=None, repr=False)
+    _scheduled_token: str | None = field(default=None, repr=False)
+    _trusted_context: str | None = field(default=None, repr=False)
+
+    def __post_init__(self) -> None:
+        credentials = sum(
+            bool(value)
+            for value in (
+                self._cas_session_id,
+                self._scheduled_token,
+                self._trusted_context,
+            )
+        )
+        if credentials != 1:
+            raise ValueError("exactly one Control credential is required")
+        expected = "CAS" if self._cas_session_id else "SCHEDULED"
+        if self.authentication_type != expected:
+            raise ValueError("authentication type does not match credential")
+
+    @classmethod
+    def cas(cls, session_id: str) -> ControlAuth:
+        return cls("CAS", _cas_session_id=session_id)
+
+    @classmethod
+    def scheduled(cls, token: str) -> ControlAuth:
+        return cls("SCHEDULED", _scheduled_token=token)
+
+    @classmethod
+    def trusted_context(cls, context: str) -> ControlAuth:
+        return cls("SCHEDULED", _trusted_context=context)
+
+    def headers(self) -> dict[str, str]:
+        if self.authentication_type == "CAS":
+            return {"Cookie": f"CASSESSIONID={self._cas_session_id}"}
+        if self._trusted_context:
+            return {"X-Agent-Trusted-Context": self._trusted_context}
+        return {"Authorization": f"Scheduled {self._scheduled_token}"}

package/app/utils/request_logging.py

@@ -0,0 +1,63 @@
+"""关联请求日志并记录 HTTP 生命周期，不记录请求或响应正文。"""
+
+import logging
+from contextvars import ContextVar
+from time import monotonic
+from uuid import uuid4
+
+request_id = ContextVar("request_id", default="-")
+
+
+class RequestLogger(logging.LoggerAdapter):
+    def process(self, msg, kwargs):
+        return f"request_id={request_id.get()} {msg}", kwargs
+
+
+def get_logger(name: str) -> RequestLogger:
+    return RequestLogger(logging.getLogger(name), {})
+
+
+logger = get_logger(__name__)
+
+
+class RequestLoggingMiddleware:
+    def __init__(self, app):
+        self.app = app
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] != "http" or scope["path"] == "/healthcheck.html":
+            return await self.app(scope, receive, send)
+        token = request_id.set(uuid4().hex)
+        started = monotonic()
+        status = None
+        outcome = "interrupted"
+
+        async def send_logged(message):
+            nonlocal status
+            if message["type"] == "http.response.start":
+                status = message["status"]
+                message = dict(message)
+                message["headers"] = [
+                    *message.get("headers", []),
+                    (b"x-request-id", request_id.get().encode()),
+                ]
+            await send(message)
+
+        logger.info("Request received method=%s path=%r", scope["method"], scope["path"])
+        try:
+            await self.app(scope, receive, send_logged)
+            outcome = "finished"
+        except Exception as exc:
+            outcome = "failed"
+            if status is None:
+                status = 500
+            logger.error("Request failed error_type=%s", type(exc).__name__)
+            raise
+        finally:
+            successful = outcome == "finished" and status is not None and status < 400
+            logger.log(
+                logging.INFO if successful else logging.WARNING,
+                "Request ended status=%s outcome=%s elapsed_ms=%.0f",
+                status, outcome, (monotonic() - started) * 1000,
+            )
+            request_id.reset(token)

package/app/utils/state_client.py

@@ -0,0 +1,68 @@
+"""封装 Agent 会话、运行结果与记忆状态的远端操作。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from app.utils.control_auth import ControlAuth
+from app.utils.request_logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class AgentStateError(RuntimeError):
+    pass
+
+
+class AgentStateClient:
+    """访问远端 Agent 状态接口的认证客户端。"""
+
+    def __init__(
+        self,
+        *,
+        http: httpx.AsyncClient,
+        base_url: str,
+        auth: ControlAuth,
+    ) -> None:
+        self._http = http
+        self._base_url = base_url.rstrip("/")
+        self._auth = auth
+
+    @property
+    def headers(self) -> dict[str, str]:
+        return self._auth.headers()
+
+    async def post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        try:
+            response = await self._http.post(
+                f"{self._base_url}{path}",
+                json=payload,
+                headers=self.headers,
+                timeout=15,
+            )
+        except httpx.HTTPError as exc:
+            logger.warning("State request failed path=%r error_type=%s", path, type(exc).__name__)
+            raise
+        if response.status_code >= 400:
+            logger.warning("State request rejected path=%r status=%s", path, response.status_code)
+            raise AgentStateError(f"state request failed: {response.status_code}")
+        body = response.json()
+        if not isinstance(body, dict):
+            raise AgentStateError("state service returned a non-object response")
+        return body
+
+    async def load_messages(self, conversation_id: str) -> list[dict[str, Any]]:
+        body = await self.post(
+            "/agent/getConversationMessages",
+            {"conversationId": conversation_id},
+        )
+        messages = body.get("messages", [])
+        return messages if isinstance(messages, list) else []
+
+    async def complete_run(
+        self,
+        payload: dict[str, Any],
+    ) -> None:
+        await self.post("/agent/completeRun", payload)

package/app/views/__init__.py

@@ -0,0 +1 @@
+"""存放 ASGI 应用的 HTTP 路由与请求边界处理。"""

package/app/views/auth.py

@@ -0,0 +1,208 @@
+"""校验 CAS 与定时任务身份并构造可信运行身份。"""
+
+from __future__ import annotations
+
+import json
+import re
+from base64 import b64decode
+from binascii import Error as Base64Error
+from datetime import datetime, timezone
+from http.cookies import CookieError, SimpleCookie
+from zoneinfo import ZoneInfo
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+from starlette.requests import Request
+
+from app.utils.control_auth import ControlAuth
+from app.utils.request_logging import get_logger
+
+from app.views.errors import RouteError
+
+logger = get_logger(__name__)
+
+_COOKIE_VALUE = re.compile(r"^[A-Za-z0-9._:@+-]{1,256}$")
+_SCHEDULED_TOKEN = re.compile(r"^[A-Za-z0-9_-]{43}$")
+_FORBIDDEN_SCHEDULED_HEADERS = {
+    "x-agent-scheduled-run-id",
+    "x-agent-user-id",
+    "x-agent-org-code",
+    "x-agent-effective-at",
+    "x-agent-effective-timezone",
+}
+
+
+class ScheduledIdentity(BaseModel):
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    authentication_type: str = Field(alias="authenticationType")
+    run_id: int = Field(alias="runId", strict=True, gt=0)
+    task_id: int = Field(alias="taskId", strict=True, gt=0)
+    user_id: str = Field(alias="userId", min_length=1, max_length=256)
+    org_code: str = Field(alias="orgCode", min_length=1, max_length=64)
+    role_id: str = Field(alias="roleId", min_length=1, max_length=64)
+    prompt: str = Field(min_length=1, max_length=65536)
+    scheduled_at: datetime = Field(alias="scheduledAt")
+    timezone: str = Field(min_length=1, max_length=128)
+    expires_at: datetime = Field(alias="expiresAt")
+    trusted_context: str = Field(alias="trustedContext", min_length=1, max_length=256)
+
+
+class _ScheduledEnvelope(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    success: bool
+    data: ScheduledIdentity
+
+
+async def authenticate_user(request: Request, runtime):
+    session_id = _cookies(request.headers.get("cookie", "")).get("CASSESSIONID")
+    if not session_id:
+        logger.warning("Authentication rejected reason=missing_session")
+        raise RouteError(401, "auth error")
+    try:
+        response = await runtime.http.get(
+            f"{runtime.settings.union_base_url}/common/getUserInfo",
+            headers={"Cookie": f"CASSESSIONID={session_id}"},
+            timeout=10,
+        )
+        body = response.json()
+        data = body.get("data", {}) if response.status_code < 400 else {}
+    except (httpx.HTTPError, ValueError) as exc:
+        logger.warning(
+            "Authentication failed reason=identity_lookup error_type=%s",
+            type(exc).__name__,
+        )
+        raise RouteError(401, "auth error")
+    if (
+        not isinstance(data, dict)
+        or not isinstance(data.get("userId"), str)
+        or not data["userId"]
+    ):
+        logger.warning(
+            "Authentication rejected reason=invalid_identity upstream_status=%s",
+            response.status_code,
+        )
+        raise RouteError(401, "auth error")
+    permissions = data.get("permissions") or []
+    if isinstance(permissions, str):
+        permissions = [permissions]
+    required = runtime.settings.required_permission
+    if required and required not in permissions:
+        logger.warning("Authentication rejected reason=missing_permission")
+        raise RouteError(403, "auth error")
+    logger.info("Authentication succeeded type=CAS")
+    return {
+        "authentication_type": "CAS",
+        "user_id": data["userId"],
+        "org_code": data.get("orgCode", ""),
+        "permissions": tuple(permissions),
+        "control_auth": ControlAuth.cas(session_id),
+    }
+
+
+def reject_scheduled_on_cas_endpoint(request: Request) -> None:
+    authorization = request.headers.get("authorization")
+    if not authorization or not authorization.lower().startswith("scheduled "):
+        return
+    if request.headers.get("cookie") is not None:
+        raise RouteError(400, "mixed_authentication")
+    raise RouteError(401, "auth error")
+
+
+def scheduled_token(request: Request) -> str:
+    authorizations = request.headers.getlist("authorization")
+    if len(authorizations) != 1:
+        raise RouteError(401, "scheduled_auth_error")
+    authorization = authorizations[0]
+    cookie_present = request.headers.get("cookie") is not None
+    is_scheduled = bool(
+        authorization and authorization.lower().startswith("scheduled ")
+    )
+    if cookie_present and is_scheduled:
+        raise RouteError(400, "mixed_authentication")
+    if cookie_present or not authorization:
+        raise RouteError(401, "scheduled_auth_error")
+    scheme, separator, token = authorization.partition(" ")
+    if separator != " " or scheme.lower() != "scheduled" or not _valid_token(token):
+        raise RouteError(401, "scheduled_auth_error")
+    return token
+
+
+async def strict_scheduled_body(request: Request) -> None:
+    if _FORBIDDEN_SCHEDULED_HEADERS.intersection(request.headers.keys()):
+        raise RouteError(422, "invalid_scheduled_request")
+    try:
+        payload = json.loads(await request.body())
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        raise RouteError(422, "invalid_scheduled_request")
+    if not isinstance(payload, dict) or payload:
+        raise RouteError(422, "invalid_scheduled_request")
+
+
+async def authenticate_scheduled_run(runtime, token: str) -> ScheduledIdentity:
+    try:
+        response = await runtime.http.post(
+            f"{runtime.settings.union_base_url}/agent/scheduledTaskAuthorize",
+            headers=ControlAuth.scheduled(token).headers(),
+            json={},
+            timeout=10,
+        )
+    except (httpx.TimeoutException, httpx.NetworkError) as exc:
+        raise RouteError(503, "scheduled_identity_unavailable") from exc
+    if response.status_code == 401:
+        raise RouteError(401, "scheduled_auth_error")
+    if response.status_code == 403:
+        raise RouteError(403, "forbidden")
+    if response.status_code >= 500:
+        raise RouteError(503, "scheduled_identity_unavailable")
+    if response.status_code >= 400:
+        raise RouteError(502, "scheduled_identity_unavailable")
+    try:
+        envelope = _ScheduledEnvelope.model_validate(response.json())
+        identity = envelope.data
+        if not envelope.success or identity.authentication_type != "SCHEDULED":
+            raise ValueError
+        if identity.scheduled_at.tzinfo is None or identity.expires_at.tzinfo is None:
+            raise ValueError
+        if identity.expires_at <= datetime.now(timezone.utc):
+            raise ValueError
+        if identity.trusted_context != f"Scheduled {token}":
+            raise ValueError
+        ZoneInfo(identity.timezone)
+        if any(
+            not value.strip()
+            for value in (
+                identity.user_id,
+                identity.org_code,
+                identity.role_id,
+                identity.prompt,
+            )
+        ):
+            raise ValueError
+    except (ValidationError, ValueError, KeyError, json.JSONDecodeError):
+        raise RouteError(502, "scheduled_identity_unavailable")
+    logger.info("Authentication succeeded type=SCHEDULED")
+    return identity
+
+
+def _valid_token(token: str) -> bool:
+    if not _SCHEDULED_TOKEN.fullmatch(token):
+        return False
+    try:
+        return len(b64decode(token + "=", altchars=b"-_", validate=True)) == 32
+    except (Base64Error, ValueError):
+        return False
+
+
+def _cookies(header: str) -> dict[str, str]:
+    try:
+        cookie = SimpleCookie()
+        cookie.load(header)
+    except CookieError:
+        return {}
+    return {
+        name: morsel.value
+        for name, morsel in cookie.items()
+        if _COOKIE_VALUE.fullmatch(morsel.value)
+    }