union-py-app 1.0.0

package/app/config/settings.py

@@ -0,0 +1,67 @@
+"""读取并校验应用运行所需的环境变量配置。"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+def _integer(name: str, default: int) -> int:
+    try:
+        return int(os.getenv(name, str(default)))
+    except ValueError:
+        return default
+
+
+def _floating(name: str, default: float) -> float:
+    try:
+        return float(os.getenv(name, str(default)))
+    except ValueError:
+        return default
+
+
+@dataclass(frozen=True)
+class AgentSettings:
+    union_base_url: str
+    llm_url: str
+    llm_key: str
+    llm_model: str
+    llm_context_window: int
+    request_limit: int
+    tool_calls_limit: int
+    input_tokens_limit: int
+    output_tokens_limit: int
+    tool_timeout_seconds: float
+    subagent_timeout_seconds: float
+    max_run_seconds: float
+    required_permission: str
+    rag_enabled: bool
+    rag_knowledge_dir: str
+    rag_collection: str
+    rag_embedding_model: str
+    rag_top_k: int
+    rag_chunk_size: int
+
+    @classmethod
+    def from_env(cls) -> AgentSettings:
+        return cls(
+            union_base_url=os.getenv("UNION_BASE_URL", "http://127.0.0.1:8080").rstrip("/"),
+            llm_url=os.getenv("LLM_URL", "").rstrip("/"),
+            llm_key=os.getenv("LLM_KEY", ""),
+            llm_model=os.getenv("LLM_MODEL", ""),
+            llm_context_window=_integer("LLM_CONTEXT_WINDOW", 131072),
+            request_limit=_integer("AGENT_REQUEST_LIMIT", 30),
+            tool_calls_limit=_integer("AGENT_TOOL_CALLS_LIMIT", 40),
+            input_tokens_limit=_integer("AGENT_INPUT_TOKENS_LIMIT", 120000),
+            output_tokens_limit=_integer("AGENT_OUTPUT_TOKENS_LIMIT", 16000),
+            tool_timeout_seconds=_floating("AGENT_TOOL_TIMEOUT_SECONDS", 300.0),
+            subagent_timeout_seconds=_floating("SUBAGENT_TIMEOUT_SECONDS", 900.0),
+            max_run_seconds=_floating("AGENT_MAX_RUN_SECONDS", 900.0),
+            required_permission=os.getenv("PERMISSIONS", ""),
+            rag_enabled=os.getenv("RAG_ENABLED", "true").lower() in {"1", "true", "yes", "on"},
+            rag_knowledge_dir=os.getenv("RAG_KNOWLEDGE_DIR", "knowledge"),
+            rag_collection=os.getenv("RAG_COLLECTION", "ops_knowledge"),
+            rag_embedding_model=os.getenv("RAG_EMBEDDING_MODEL", "embedding-3"),
+            rag_top_k=_integer("RAG_TOP_K", 5),
+            rag_chunk_size=_integer("RAG_CHUNK_SIZE", 1200),
+        )

package/app/memory/__init__.py

@@ -0,0 +1 @@
+"""存放 Agent 个人记忆的存储适配实现。"""

package/app/memory/store.py

@@ -0,0 +1,154 @@
+"""将远端记忆接口适配为 Harness 记忆存储协议。"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic_ai_harness.memory import (
+    MemoryConflictError,
+    MemoryFile,
+    MemoryMutation,
+    MemoryOperation,
+    MemoryOperationConflictError,
+    MemorySearchMatch,
+    MemorySearchResult,
+)
+
+from app.utils.state_client import AgentStateClient, AgentStateError
+
+
+class AgentMemoryStore:
+    """HTTP adapter for the official SearchableMemoryStore protocol."""
+
+    def __init__(self, state_client: AgentStateClient) -> None:
+        self._state_client = state_client
+
+    async def _call(self, action: str, payload: dict[str, Any]) -> dict[str, Any]:
+        body = await self._state_client.post(f"/agent/memoryStore/{action}", payload)
+        code = body.get("errorCode")
+        if code == "version_conflict":
+            raise MemoryConflictError(body.get("errorMsg", "memory version conflict"))
+        if code == "operation_conflict":
+            raise MemoryOperationConflictError(body.get("errorMsg", "memory operation conflict"))
+        if body.get("success") is False:
+            raise AgentStateError(body.get("errorMsg", "memory store request failed"))
+        return body
+
+    async def read(self, path: str, *, max_chars: int) -> MemoryFile | None:
+        body = await self._call("read", {"path": path, "maxChars": max_chars})
+        item = body.get("file")
+        if item is None:
+            return None
+        return MemoryFile(
+            content=str(item["content"]),
+            version=str(item["version"]),
+            operation_id=item.get("operationId"),
+            truncated=bool(item.get("truncated", False)),
+        )
+
+    async def list_paths(self, prefix: str = "", *, limit: int) -> list[str]:
+        body = await self._call("list", {"prefix": prefix, "limit": limit})
+        return [str(path) for path in body.get("paths", [])]
+
+    async def get_operation(self, operation: MemoryOperation) -> MemoryMutation | None:
+        body = await self._call(
+            "operation",
+            {"operationId": operation.id, "fingerprint": operation.fingerprint},
+        )
+        return self._mutation(body.get("mutation"))
+
+    async def write(
+        self,
+        path: str,
+        content: str,
+        *,
+        expected_version: str | None,
+        operation: MemoryOperation | None = None,
+    ) -> MemoryMutation:
+        return self._required_mutation(
+            await self._call(
+                "write",
+                {
+                    "path": path,
+                    "content": content,
+                    "expectedVersion": expected_version,
+                    "operation": self._operation(operation),
+                },
+            )
+        )
+
+    async def delete(
+        self,
+        path: str,
+        *,
+        expected_version: str | None,
+        operation: MemoryOperation | None = None,
+    ) -> MemoryMutation:
+        return self._required_mutation(
+            await self._call(
+                "delete",
+                {
+                    "path": path,
+                    "expectedVersion": expected_version,
+                    "operation": self._operation(operation),
+                },
+            )
+        )
+
+    async def search(
+        self,
+        prefix: str,
+        query: str,
+        *,
+        limit: int,
+        max_files: int,
+        max_chars: int,
+        max_file_chars: int,
+    ) -> MemorySearchResult:
+        body = await self._call(
+            "search",
+            {
+                "prefix": prefix,
+                "query": query,
+                "limit": limit,
+                "maxFiles": max_files,
+                "maxChars": max_chars,
+                "maxFileChars": max_file_chars,
+            },
+        )
+        result = body.get("result") or {}
+        return MemorySearchResult(
+            matches=[
+                MemorySearchMatch(
+                    path=str(item["path"]),
+                    snippet=str(item["snippet"]),
+                    score=float(item["score"]),
+                )
+                for item in result.get("matches", [])
+            ],
+            scanned=int(result.get("scanned", 0)),
+            truncated=bool(result.get("truncated", False)),
+        )
+
+    @staticmethod
+    def _operation(operation: MemoryOperation | None) -> dict[str, str] | None:
+        if operation is None:
+            return None
+        return {"id": operation.id, "fingerprint": operation.fingerprint}
+
+    @staticmethod
+    def _mutation(value: Any) -> MemoryMutation | None:
+        if value is None:
+            return None
+        return MemoryMutation(
+            version=str(value["version"]) if value.get("version") is not None else None,
+            replayed=bool(value.get("replayed", False)),
+            existed=bool(value.get("existed", False)),
+        )
+
+    @classmethod
+    def _required_mutation(cls, body: dict[str, Any]) -> MemoryMutation:
+        mutation = cls._mutation(body.get("mutation"))
+        if mutation is None:
+            raise AgentStateError("state service omitted memory mutation result")
+        return mutation

package/app/service/rag_service.py

@@ -0,0 +1,365 @@
+"""管理本地知识文档的 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, item_metadata),
+                    "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, metadata: dict) -> str:
+        fingerprint = json.dumps([str(path), index, chunk, metadata], sort_keys=True)
+        return hashlib.sha256(fingerprint.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 调用的业务工具。"""