feat: add governed public knowledge retrieval

2026-09-10 18:42:44 +08:00
parent ba22a2220f
commit 511a8ca18f
20 changed files with 729 additions and 7 deletions
@@ -11,3 +11,7 @@ def test_bootstrap_assembles_common_model_and_tool_services() -> None:
    assert isinstance(factory._intent_classifier, IntentClassifier)
    assert factory._intent_endpoint_resolver is not None
    assert factory._tool_executor.registry.get("check_suitability").read_only is True
+    knowledge_tool = factory._tool_executor.registry.get("query_knowledge")
+    assert knowledge_tool.required_permission == "knowledge:query"
+    assert knowledge_tool.allowed_roles == ("visitor", "customer")
+    assert knowledge_tool.read_only is True
@@ -0,0 +1,61 @@
+import pytest
+
+from app.core.knowledge_contracts import KnowledgeHit, KnowledgeQuery
+from app.service.knowledge_authority import KnowledgeMysqlAuthority
+
+
+class FakeRow:
+    id = 101
+    title = "申购规则"
+    content_text = '{"answer":"工作日确认"}'
+    version = "v2"
+    milvus_collection = "fin_policy_collection"
+
+
+class FakeSession:
+    statement = None
+
+    async def scalars(self, statement):
+        self.statement = statement
+        return [FakeRow()]
+
+
+@pytest.mark.asyncio
+async def test_authority_filters_to_published_active_effective_knowledge() -> None:
+    session = FakeSession()
+    authority = KnowledgeMysqlAuthority(session)
+
+    hits = await authority.filter_published((
+        KnowledgeHit(
+            knowledge_id="101", collection="fin_policy_collection", snippet="摘要", score=0.91,
+        ),
+    ))
+
+    statement = str(session.statement)
+    assert "review_status" in statement
+    assert "status" in statement
+    assert "effective_date" in statement
+    assert "expire_date" in statement
+    assert hits[0].answer == "工作日确认"
+    assert hits[0].version == "v2"
+
+
+@pytest.mark.asyncio
+async def test_authority_keyword_fallback_only_returns_effective_public_knowledge() -> None:
+    session = FakeSession()
+    authority = KnowledgeMysqlAuthority(session)
+
+    hits = await authority.search_keyword(
+        KnowledgeQuery(query="基金 申购确认", intents=("policy_explain",)),
+        ("fin_policy_collection",),
+        5,
+    )
+
+    statement = str(session.statement)
+    assert "milvus_collection" in statement
+    assert "content_text" in statement
+    assert "review_status" in statement
+    assert "effective_date" in statement
+    assert hits[0].knowledge_id == "101"
+    assert hits[0].collection == "fin_policy_collection"
+    assert hits[0].answer == "工作日确认"
@@ -0,0 +1,87 @@
+import pytest
+
+from app.core.contracts import RequestContext
+from app.core.errors import RecoverableAgentError
+from app.core.knowledge_contracts import KnowledgeHit, KnowledgeQuery
+from app.service.knowledge_config import KnowledgeRuntimeConfig
+from app.service.knowledge_retrieval_service import KnowledgeRetrievalService
+
+# ruff: noqa: E501
+
+
+class FakeEmbedder:
+    async def embed(self, text: str) -> list[float]:
+        assert text == "开户"
+        return [0.1] * 1024
+
+
+class FakeVectorStore:
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, int]] = []
+
+    async def search(self, collection: str, vector: list[float], top_k: int) -> list[dict[str, object]]:
+        assert len(vector) == 1024
+        self.calls.append((collection, top_k))
+        return []
+
+
+class FakeAuthority:
+    async def filter_published(self, hits: tuple[object, ...]) -> list[object]:
+        return []
+
+    async def search_keyword(self, query: object, collections: tuple[str, ...], top_k: int) -> list[object]:
+        return []
+
+
+class BrokenVectorStore:
+    async def search(self, collection: str, vector: list[float], top_k: int) -> list[dict[str, object]]:
+        raise RecoverableAgentError("知识检索不可用")
+
+
+class FallbackAuthority:
+    def __init__(self) -> None:
+        self.calls: list[tuple[tuple[str, ...], int]] = []
+
+    async def filter_published(self, hits: tuple[object, ...]) -> list[object]:
+        return []
+
+    async def search_keyword(self, query: KnowledgeQuery, collections: tuple[str, ...], top_k: int) -> list[KnowledgeHit]:
+        self.calls.append((collections, top_k))
+        return [KnowledgeHit(
+            knowledge_id="101", collection="fin_policy_collection", snippet="确认规则",
+            answer="工作日确认", score=1.0,
+        )]
+
+
+@pytest.mark.asyncio
+async def test_search_uses_faq_collection_for_faq_only() -> None:
+    vector_store = FakeVectorStore()
+    service = KnowledgeRetrievalService(
+        FakeEmbedder(), vector_store, KnowledgeRuntimeConfig(), FakeAuthority()
+    )
+
+    result = await service.search(
+        KnowledgeQuery(query="开户", intents=("faq",)),
+        RequestContext(user_id="visitor-1", trace_id="trace", roles=("visitor",), data_scope="public"),
+    )
+
+    assert vector_store.calls == [("fin_faq_collection", 3)]
+    assert result.searched_collections == ("fin_faq_collection",)
+
+
+@pytest.mark.asyncio
+async def test_milvus_failure_falls_back_to_published_active_unexpired_knowledge() -> None:
+    authority = FallbackAuthority()
+    service = KnowledgeRetrievalService(
+        FakeEmbedder(), BrokenVectorStore(), KnowledgeRuntimeConfig(), authority
+    )
+
+    result = await service.search(
+        KnowledgeQuery(query="开户", intents=("policy_explain",)),
+        RequestContext(user_id="visitor-1", trace_id="trace", roles=("visitor",), data_scope="public"),
+    )
+
+    assert authority.calls == [(("fin_policy_collection",), 5)]
+    assert result.degraded is True
+    assert result.degradation_reason == "milvus_unavailable"
+    assert result.hits[0].answer == "工作日确认"
@@ -0,0 +1,131 @@
+import pytest
+
+from app.core.contracts import RequestContext
+from app.core.knowledge_contracts import KnowledgeHit, KnowledgeQuery, KnowledgeSearchResult
+from app.service import knowledge_tool_service
+from app.service.knowledge_tool_service import DatabaseEmbeddingAdapter, query_knowledge_tool
+
+
+class FakeGateway:
+    def __init__(self) -> None:
+        self.calls: list[tuple[str, str, int]] = []
+
+    async def embed(self, *, endpoint_code: str, text: str, timeout_ms: int) -> list[float]:
+        self.calls.append((endpoint_code, text, timeout_ms))
+        return [0.1] * 1024
+
+
+@pytest.mark.asyncio
+async def test_embedding_adapter_uses_single_text_gateway_contract() -> None:
+    gateway = FakeGateway()
+    adapter = DatabaseEmbeddingAdapter("knowledge-embedding", 15000, gateway=gateway)
+
+    vector = await adapter.embed("基金开户")
+
+    assert len(vector) == 1024
+    assert gateway.calls == [("knowledge-embedding", "基金开户", 15000)]
+
+
+@pytest.mark.asyncio
+async def test_query_tool_degrades_when_embedding_endpoint_is_unconfigured(monkeypatch) -> None:
+    class Settings:
+        knowledge_embedding_endpoint_code = ""
+
+    monkeypatch.setattr("app.service.knowledge_tool_service.get_settings", lambda: Settings())
+
+    result = await query_knowledge_tool(
+        KnowledgeQuery(query="基金开户", intents=("faq",)),
+        RequestContext(
+            user_id="visitor-1", trace_id="trace", roles=("visitor",), data_scope="public"
+        ),
+    )
+
+    assert result.degraded is True
+    assert result.degradation_reason == "embedding_endpoint_unconfigured"
+
+
+@pytest.mark.asyncio
+async def test_query_tool_uses_configured_embedding_endpoint_and_read_only_dependencies(
+    monkeypatch,
+) -> None:
+    class Settings:
+        knowledge_embedding_endpoint_code = "knowledge-embedding"
+        knowledge_embedding_timeout_ms = 15000
+        milvus_uri = "http://milvus:19530"
+        milvus_token = ""
+
+    class FakeGateway:
+        calls: list[tuple[str, str, int]] = []
+
+        async def embed(
+            self, *, endpoint_code: str, text: str, timeout_ms: int
+        ) -> list[float]:
+            self.calls.append((endpoint_code, text, timeout_ms))
+            return [0.1] * 1024
+
+    class FakeMilvus:
+        def __init__(self, uri: str, token: str | None) -> None:
+            self.uri = uri
+            self.token = token
+
+    class FakeSession:
+        async def __aenter__(self) -> object:
+            return object()
+
+        async def __aexit__(self, exc_type, exc, traceback) -> None:
+            return None
+
+    class FakeAuthority:
+        def __init__(self, session: object) -> None:
+            self.session = session
+
+    class FakeRetrievalService:
+        def __init__(self, embedder, vector_store, config, authority) -> None:
+            self.embedder = embedder
+            self.vector_store = vector_store
+            self.config = config
+            self.authority = authority
+
+        async def search(
+            self, query: KnowledgeQuery, context: RequestContext
+        ) -> KnowledgeSearchResult:
+            vector = await self.embedder.embed(query.query)
+            assert len(vector) == 1024
+            assert isinstance(self.vector_store, FakeMilvus)
+            assert isinstance(self.authority, FakeAuthority)
+            assert self.config.routes["faq"] == ("fin_faq_collection", 3)
+            assert context.data_scope == "public"
+            return KnowledgeSearchResult(
+                hits=(
+                    KnowledgeHit(
+                        knowledge_id="1",
+                        collection="fin_faq_collection",
+                        snippet="snippet",
+                        answer="answer",
+                    ),
+                ),
+                searched_collections=("fin_faq_collection",),
+            )
+
+    gateway = FakeGateway()
+    monkeypatch.setattr(knowledge_tool_service, "get_settings", lambda: Settings())
+    monkeypatch.setattr(knowledge_tool_service, "DatabaseModelGateway", lambda: gateway)
+    monkeypatch.setattr(knowledge_tool_service, "MilvusKnowledgeClient", FakeMilvus)
+    monkeypatch.setattr(knowledge_tool_service, "KnowledgeMysqlAuthority", FakeAuthority)
+    monkeypatch.setattr(
+        knowledge_tool_service, "KnowledgeRetrievalService", FakeRetrievalService
+    )
+    monkeypatch.setattr(knowledge_tool_service, "SessionFactory", FakeSession)
+
+    result = await query_knowledge_tool(
+        KnowledgeQuery(query="基金开户", intents=("faq",)),
+        RequestContext(
+            user_id="visitor-1",
+            trace_id="trace",
+            roles=("visitor",),
+            data_scope="public",
+        ),
+    )
+
+    assert result.hits[0].answer == "answer"
+    assert gateway.calls == [("knowledge-embedding", "基金开户", 15000)]