union-app-chat-stream 1.1.6

package/app/service/rag_service.py

@@ -0,0 +1,364 @@
+"""管理本地知识文档的 Chroma 索引、检查、重建与检索。"""
+
+import hashlib
+import json
+import logging
+import re
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+import chromadb
+import yaml
+from chromadb.errors import NotFoundError
+from chromadb.utils.embedding_functions import OpenAIEmbeddingFunction
+
+logger = logging.getLogger(__name__)
+
+
+class RagService:
+    """Markdown knowledge retrieval backed by Chroma's public API."""
+
+    def __init__(self, config):
+        self._enabled = config["RAG_ENABLED"]
+        self._top_k = self._positive_int(config["RAG_TOP_K"])
+        self._root = Path(__file__).resolve().parents[2]
+        self._persist_dir = self._root / ".chroma"
+        self._knowledge_dir = self._root / config["RAG_KNOWLEDGE_DIR"]
+        self._collection_name = config["RAG_COLLECTION"]
+        self._embedding_url = config["LLM_URL"]
+        self._embedding_key = config["LLM_KEY"]
+        self._embedding_model = config["RAG_EMBEDDING_MODEL"]
+        self._chunk_size = self._positive_int(config["RAG_CHUNK_SIZE"])
+        self._chroma = None
+        self._collection = None
+        self._embedding_function = None
+        self._embedding_incompatible = False
+        if not self._enabled:
+            return
+        missing = [
+            name
+            for name, value in {
+                "LLM_URL": self._embedding_url,
+                "LLM_KEY": self._embedding_key,
+                "RAG_EMBEDDING_MODEL": self._embedding_model,
+            }.items()
+            if not value
+        ]
+        if missing:
+            raise RuntimeError(f"RAG embedding 缺少配置: {', '.join(missing)}")
+        self._embedding_function = OpenAIEmbeddingFunction(
+            api_key=self._embedding_key,
+            api_base=self._embedding_url,
+            model_name=self._embedding_model,
+            api_key_env_var="LLM_KEY",
+        )
+        self._init_collection()
+        status = self.check()
+        logger.info(
+            "RAG 知识库状态检查完成 collection=%s status=%s is_synced=%s "
+            "needs_rebuild=%s item_counts=%s",
+            self._collection_name,
+            status.get("status"),
+            status.get("is_synced"),
+            status["needs_rebuild"],
+            status["item_counts"],
+        )
+        needs_rebuild = (
+            self._embedding_incompatible
+            or status["needs_rebuild"]
+            or status["item_counts"]["vector_chunks"] == 0
+        )
+        if needs_rebuild:
+            logger.info(
+                "RAG 知识库需要重建 collection=%s embedding_incompatible=%s",
+                self._collection_name,
+                self._embedding_incompatible,
+            )
+            self.rebuild()
+        else:
+            logger.info("RAG 知识库无需重建 collection=%s", self._collection_name)
+
+    def search(self, question: str, top_k: int | None = None) -> tuple[str, list[dict]]:
+        question = str(question or "").strip()
+        if not question or not self._ensure_collection():
+            return "", []
+        count = self._collection.count()
+        if count == 0:
+            return "", []
+        limit = min(self._parse_optional_top_k(top_k) or self._top_k, count)
+        result = self._collection.query(
+            query_texts=[question],
+            n_results=limit,
+            include=["documents", "metadatas", "distances"],
+        )
+        documents = result.get("documents", [[]])[0]
+        metadatas = result.get("metadatas", [[]])[0]
+        distances = result.get("distances", [[]])[0]
+        hits = [
+            {
+                "document": self._strip_search_prefix(document),
+                "metadata": metadata or {},
+                "distance": distances[index] if index < len(distances) else None,
+            }
+            for index, (document, metadata) in enumerate(zip(documents, metadatas))
+        ]
+        return self._format_evidence_context(hits), [self._source(hit["metadata"]) for hit in hits]
+
+    def knowledge_search(self, query: str, top_k: Any | None = None) -> tuple[dict[str, Any], str]:
+        query = str(query or "").strip()
+        if not query:
+            return {"context": "", "sources": [], "related_tools": []}, "query_empty"
+        context, sources = self.search(query, top_k=self._parse_optional_top_k(top_k))
+        return {
+            "query": query,
+            "context": context,
+            "sources": sources,
+            "related_tools": self._extract_related_tools(sources),
+        }, "success"
+
+    def rebuild(self) -> int:
+        if not self._enabled or self._chroma is None:
+            return 0
+        documents = self._load_documents()
+        logger.info(
+            "RAG 知识库开始重建（重建中） collection=%s doc_chunks=%s",
+            self._collection_name,
+            len(documents),
+        )
+        temporary_name = f"{self._collection_name}-rebuild-{uuid4().hex}"
+        new_collection = self._chroma.get_or_create_collection(
+            temporary_name,
+            embedding_function=self._embedding_function,
+        )
+        try:
+            if documents:
+                new_collection.upsert(
+                    ids=[document["id"] for document in documents],
+                    documents=[document["content"] for document in documents],
+                    metadatas=[document["metadata"] for document in documents],
+                )
+        except Exception:
+            try:
+                self._chroma.delete_collection(temporary_name)
+            except Exception:
+                logger.exception("RAG 临时集合清理失败 collection=%s", temporary_name)
+            raise
+
+        try:
+            self._chroma.delete_collection(self._collection_name)
+        except NotFoundError:
+            pass
+        except Exception:
+            try:
+                self._chroma.delete_collection(temporary_name)
+            except Exception:
+                logger.exception("RAG 临时集合清理失败 collection=%s", temporary_name)
+            raise
+
+        self._collection = new_collection
+        new_collection.modify(name=self._collection_name)
+        self._embedding_incompatible = False
+        logger.info("RAG 知识库重建完成 doc_chunks=%s", len(documents))
+        return len(documents)
+
+    def check(self) -> dict[str, Any]:
+        documents = self._load_documents()
+        expected_ids = {document["id"] for document in documents}
+        result = {
+            "enabled": self._enabled,
+            "status": "disabled" if not self._enabled else "unavailable",
+            "collection": self._collection_name,
+            "is_synced": False,
+            "needs_rebuild": bool(self._enabled),
+            "item_counts": {
+                "source_files": len(list(self._knowledge_dir.rglob("*.md"))),
+                "expected_chunks": len(expected_ids),
+                "vector_chunks": 0,
+                "missing_chunks": len(expected_ids),
+                "stale_chunks": 0,
+            },
+            "config": {
+                "embedding_model": self._embedding_model,
+                "top_k": self._top_k,
+                "chunk_size": self._chunk_size,
+            },
+        }
+        if not self._ensure_collection():
+            return result
+        count = self._collection.count()
+        stored_ids = set(self._collection.get(include=[]).get("ids", [])) if count else set()
+        missing = expected_ids - stored_ids
+        stale = stored_ids - expected_ids
+        synced = not missing and not stale and count == len(expected_ids)
+        result.update({
+            "status": "ready" if count else "empty",
+            "is_synced": synced,
+            "needs_rebuild": not synced,
+        })
+        result["item_counts"].update({
+            "vector_chunks": count,
+            "missing_chunks": len(missing),
+            "stale_chunks": len(stale),
+        })
+        return result
+
+    def _init_collection(self) -> None:
+        self._chroma = chromadb.PersistentClient(path=str(self._persist_dir))
+        try:
+            existing = self._chroma.get_collection(self._collection_name)
+        except NotFoundError:
+            pass
+        else:
+            config = existing.configuration_json or {}
+            persisted = config.get("embedding_function") or {}
+            current = self._embedding_function.get_config()
+            vector_config_keys = (
+                "model_name", "api_base", "api_type", "api_version", "deployment_id", "dimensions",
+            )
+            incompatible = persisted.get("name") != self._embedding_function.name() or any(
+                (persisted.get("config") or {}).get(key) != current.get(key)
+                for key in vector_config_keys
+            )
+            if persisted and incompatible:
+                self._embedding_incompatible = True
+                self._collection = existing
+                return
+        self._collection = self._chroma.get_or_create_collection(
+            self._collection_name,
+            embedding_function=self._embedding_function,
+        )
+
+    def _ensure_collection(self) -> bool:
+        if self._collection is not None:
+            return True
+        if not self._enabled:
+            return False
+        self._init_collection()
+        return self._collection is not None
+
+    def _load_documents(self) -> list[dict[str, Any]]:
+        documents = []
+        for path in sorted(self._knowledge_dir.rglob("*.md")):
+            metadata, body = self._read_markdown(path)
+            if metadata.get("status", "active") != "active":
+                continue
+            for index, chunk in enumerate(self._split(body)):
+                item_metadata = self._clean_metadata({
+                    **metadata,
+                    "file_path": path.relative_to(self._root).as_posix(),
+                    "chunk_index": index,
+                })
+                documents.append({
+                    "id": self._chunk_id(path, index, chunk),
+                    "content": self._searchable_content(item_metadata, chunk),
+                    "metadata": item_metadata,
+                })
+        return documents
+
+    def _parse_optional_top_k(self, value: Any | None) -> int | None:
+        if value in (None, ""):
+            return None
+        return self._positive_int(value)
+
+    @staticmethod
+    def _positive_int(value) -> int:
+        parsed = int(value)
+        if parsed < 1:
+            raise ValueError(f"配置值必须为正整数: {value}")
+        return parsed
+
+    @staticmethod
+    def _extract_related_tools(sources: list[dict]) -> list[dict[str, str]]:
+        names = set()
+        for source in sources:
+            raw = source.get("related_items", "")
+            text = raw if isinstance(raw, str) else json.dumps(raw, ensure_ascii=False)
+            names.update(re.findall(r"\b[a-zA-Z][a-zA-Z0-9_]*_[a-zA-Z0-9_]+\b", text))
+        return [
+            {"name": name, "reason": "知识库关联能力提示；是否可执行以当前工具定义为准。"}
+            for name in sorted(names)
+        ]
+
+    @staticmethod
+    def _format_evidence_context(hits: list[dict[str, Any]]) -> str:
+        blocks = []
+        for index, hit in enumerate(hits, 1):
+            metadata = hit["metadata"]
+            blocks.append(
+                f"[{index}] 标题：{metadata.get('title', '')}\n"
+                f"来源：{metadata.get('source_doc', '')} {metadata.get('source_section', '')}\n"
+                f"内容：{hit['document']}"
+            )
+        return "\n\n".join(blocks)
+
+    @staticmethod
+    def _searchable_content(metadata: dict[str, Any], chunk: str) -> str:
+        prefix = "\n".join(
+            f"{label}：{metadata.get(key, '')}"
+            for label, key in (
+                ("标题", "title"),
+                ("标签", "tags"),
+                ("知识领域", "domain"),
+                ("知识大类", "category"),
+            )
+            if metadata.get(key)
+        )
+        return f"{prefix}\n\n---CONTENT---\n{chunk}" if prefix else chunk
+
+    @staticmethod
+    def _strip_search_prefix(document: str) -> str:
+        return document.split("---CONTENT---\n", 1)[-1]
+
+    @staticmethod
+    def _read_markdown(path: Path) -> tuple[dict, str]:
+        text = path.read_text(encoding="utf-8")
+        match = re.match(r"^---\n(.*?)\n---\n(.*)$", text, re.DOTALL)
+        if not match:
+            return {"title": path.stem, "status": "active"}, text
+        return yaml.safe_load(match.group(1)) or {}, match.group(2).strip()
+
+    def _split(self, text: str) -> list[str]:
+        chunks = []
+        for section in re.split(r"\n(?=##\s+)", text):
+            section = section.strip()
+            chunks.extend(
+                section[index:index + self._chunk_size]
+                for index in range(0, len(section), self._chunk_size)
+            )
+        return [chunk for chunk in chunks if chunk]
+
+    @staticmethod
+    def _clean_metadata(metadata: dict) -> dict:
+        return {
+            key: json.dumps(value, ensure_ascii=False) if isinstance(value, (list, dict))
+            else "" if value is None
+            else value if isinstance(value, (str, int, float, bool))
+            else str(value)
+            for key, value in metadata.items()
+        }
+
+    @staticmethod
+    def _chunk_id(path: Path, index: int, chunk: str) -> str:
+        return hashlib.sha256(f"{path}:{index}:{chunk}".encode()).hexdigest()
+
+    def _source(self, metadata: dict) -> dict:
+        return {
+            key: metadata.get(key, "")
+            for key in (
+                "kb_id",
+                "title",
+                "doc_type",
+                "domain",
+                "category",
+                "category_keywords",
+                "source_doc_description",
+                "subcategory",
+                "related_items",
+                "related_categories",
+                "relation_notes",
+                "source_doc",
+                "source_section",
+                "file_path",
+            )
+        }

package/app/skills/full-chain-quality-analysis/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: full-chain-quality-analysis
+description: 当用户要求分析全链路、端到端或整体链路在某个周期内的运行质量、风险、影响因素或原因时使用；普通指标查询、单一机构查询或知识库问答不要使用。
+---
+
+# 全链路运行质量分析
+
+先明确分析日期范围；相对日期按 Asia/Shanghai 的业务日期计算，并在结论中写明实际起止日期。
+
+使用全链路运行指标建立事实基础。为了定位影响因素，还应取得同一日期范围内全部成员机构的运行指标，从中识别需要进一步核查的机构。机构变更和故障查询要求可信 orgCode：只能使用机构指标结果中已经返回的编码，或先通过机构解析工具取得编码，不得使用 `ALL` 等虚构编码。
+
+对需要核查的机构查询同一日期范围内的变更和故障。不要为没有证据的问题编造事件或根因。
+
+输出结构：
+
+1. 分析周期和证据范围。
+2. 全链路指标趋势与关键数值。
+3. 成员机构对照和问题事件。
+4. 有证据支持的影响因素、尚不能确认的风险点。
+5. 可执行建议。
+
+工具结果没有阈值、SLA、历史基线或对照数据时，只陈述指标事实，不判定正常、异常、良好或可接受。

package/app/tools/__init__.py

@@ -0,0 +1 @@
+"""存放可供 Agent 调用的业务工具。"""

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,76 @@
+"""封装工具调用所需的认证 HTTP 请求、结果校验与数据边界。"""
+
+from __future__ import annotations
+
+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
+
+
+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")
+        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:
+                if attempt == timeout_attempts:
+                    raise ToolFailed(
+                        f"上游查询连续 {timeout_attempts} 次超时，请稍后重试。"
+                    ) from exc
+        return _tool_result(response)
+
+
+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,35 @@
+"""封装访问 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)
+
+    def __post_init__(self) -> None:
+        if bool(self._cas_session_id) == bool(self._scheduled_token):
+            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)
+
+    def headers(self) -> dict[str, str]:
+        if self.authentication_type == "CAS":
+            return {"Cookie": f"CASSESSIONID={self._cas_session_id}"}
+        return {"Authorization": f"Scheduled {self._scheduled_token}"}