feat: add governed public knowledge retrieval

app/core/config.py

@@ -54,6 +54,8 @@ class Settings(BaseSettings):
     model_router_config_ref: str = "local"
     model_default_endpoint: str = ""
     model_fallback_endpoint: str = ""
+    knowledge_embedding_endpoint_code: str = ""
+    knowledge_embedding_timeout_ms: int = Field(default=15000, gt=0)
     sse_heartbeat_seconds: int = Field(default=15, gt=0)
     sse_chunk_characters: int = Field(default=256, ge=1, le=4096)
     sse_max_connection_seconds: int = Field(default=300, gt=0)

app/core/knowledge_contracts.py

@@ -0,0 +1,43 @@
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+ALLOWED_KNOWLEDGE_COLLECTIONS = frozenset({
+    "fin_faq_collection",
+    "fin_product_collection",
+    "fin_policy_collection",
+})
+
+
+class KnowledgeQuery(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    query: str = Field(min_length=1, max_length=2000)
+    intents: tuple[str, ...] = Field(min_length=1, max_length=4)
+    top_k: int = Field(default=5, ge=1, le=20)
+
+    @field_validator("query")
+    @classmethod
+    def query_must_not_be_blank(cls, value: str) -> str:
+        if not value.strip():
+            raise ValueError("query must not be blank")
+        return value
+
+
+class KnowledgeHit(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    knowledge_id: str
+    collection: str
+    snippet: str
+    title: str | None = None
+    answer: str | None = None
+    score: float | None = Field(default=None, ge=0, le=1)
+    version: str | None = None
+
+
+class KnowledgeSearchResult(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    hits: tuple[KnowledgeHit, ...] = ()
+    degraded: bool = False
+    degradation_reason: str | None = None
+    searched_collections: tuple[str, ...] = ()

app/core/security.py

@@ -92,6 +92,7 @@ class JwtAuthenticator:
         if claims.get("visitor") is True:
             return RequestContext(
                 user_id=str(subject), trace_id=str(uuid4()), roles=("visitor",),
-                permissions=("agent:run",), data_scope="public",
+                # 访客仅可运行 Agent 与读取已发布的公共知识，绝不含个人数据权限。
+                permissions=("agent:run", "knowledge:query"), data_scope="public",
             )
         return RequestContext(user_id=str(claims["sub"]), trace_id=str(uuid4()))