update for mcp

Add per-tool in-memory call counters to the MCP module and a
GET /api/v1/status/mcp endpoint that joins them with the live tool
registry and endpoint config, then render it as a new card on the
System Status page with a one-click client-config copy button.

- app/mcp/stats.py: lock-guarded MCPStatsTracker (the mcp SDK runs sync
  tool bodies via anyio.to_thread.run_sync, so this is genuinely
  multi-threaded, unlike the async REST routes)
- app/mcp/server.py: instrument search_regulations, add get_mcp_status()
- app/config/settings.py: optional MCP_PUBLIC_URL override, required
  because the Vite proxy and reverse proxies rewrite the Host header
- StatusPage.tsx: MCP Server card, joins the existing parallel fetch

Counters are process-local by design; token usage is already persisted
by ModelUsageTracker since MCP calls route through ask().

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

.env

@@ -55,9 +55,16 @@ DOCUMENT_REPOSITORY_BACKEND=postgres
 USE_CELERY_WORKER=false
 
 # ===== 法规感知爬取配置 =====
+# 单次 HTTP 请求超时（秒），含正文抓取（fetch_full_text）。
 PERCEPTION_CRAWL_TIMEOUT_SECONDS=120
+# 每个数据源单次爬取的最大条目数。
 PERCEPTION_MAX_EVENTS_PER_SOURCE=100
-PERCEPTION_DIFF_SIMILARITY_THRESHOLD=0.85
+# 变更判定的次要闸门：段落改动字符占比达到该阈值才送 LLM 分类。
+# 数字变化（如 30米->20米）或情态词变化（应当/宜/不得等）无视此阈值，始终判定为显著变更。
+PERCEPTION_DIFF_MIN_CHANGE_RATIO=0.02
+# 定时全量爬取的执行间隔（秒），默认 21600 = 6 小时。
+# 仅当 Celery Beat 进程在运行时才生效（./dev.sh start beat），Beat 未启动则完全不会自动爬取。
+PERCEPTION_CRAWL_INTERVAL_SECONDS=21600
 
 # ===== API配置 =====
 API_HOST=0.0.0.0
@@ -125,5 +132,18 @@ CORS_ALLOW_ORIGINS=http://localhost:5173
 HYDE_ENABLED=true
 HYDE_MAX_TOKENS=200
 HYDE_LLM_PROVIDER=qwen
-HYDE_LLM_MODEL=qwen3.5-flash
+HYDE_LLM_MODEL=qwen3.6-flash
 
+
+# ===== MCP 服务配置 =====
+# MCP SDK 在传输层绑定回环地址时会自动启用 DNS 重绑定防护：Host 头不在下表内的
+# 请求一律返回 HTTP 421，且发生在进入工具逻辑之前。部署在 6.86.80.9 必须显式列出
+# 该地址，否则所有远程 MCP 客户端（Claude Desktop / IDE 等）100% 连不上。
+# 语法：`:*` 后缀匹配任意端口；填 `*` 表示彻底关闭该防护（不推荐）。
+MCP_ALLOWED_HOSTS=6.86.80.9:*,127.0.0.1:*,localhost:*,[::1]:*
+
+# 系统状态页 MCP 卡片展示、以及"复制接入配置"按钮写入的对外访问地址。
+# 留空则由后端从请求 Host 头推导；但前端经 Vite 代理（changeOrigin: true）转发后
+# Host 会被改写成 API_HOST:API_PORT，推导结果是 0.0.0.0/127.0.0.1，客户端无法使用，
+# 因此远程部署必须显式指定。结尾的斜杠不能省略。
+MCP_PUBLIC_URL=http://6.86.80.9:8000/mcp/

.env.example

@@ -60,9 +60,16 @@ DOCUMENT_REPOSITORY_BACKEND=json
 USE_CELERY_WORKER=false
 
 # ===== 法规感知爬取配置 =====
+# 单次 HTTP 请求超时（秒），含正文抓取（fetch_full_text）。
 PERCEPTION_CRAWL_TIMEOUT_SECONDS=120
+# 每个数据源单次爬取的最大条目数。
 PERCEPTION_MAX_EVENTS_PER_SOURCE=100
-PERCEPTION_DIFF_SIMILARITY_THRESHOLD=0.85
+# 变更判定的次要闸门：段落改动字符占比达到该阈值才送 LLM 分类。
+# 数字变化（如 30米->20米）或情态词变化（应当/宜/不得等）无视此阈值，始终判定为显著变更。
+PERCEPTION_DIFF_MIN_CHANGE_RATIO=0.02
+# 定时全量爬取的执行间隔（秒），默认 21600 = 6 小时。
+# 仅当 Celery Beat 进程在运行时才生效（./dev.sh start beat），Beat 未启动则完全不会自动爬取。
+PERCEPTION_CRAWL_INTERVAL_SECONDS=21600
 
 # ===== 阿里云文档解析 =====
 ALIBABA_ACCESS_KEY_ID=your_aliyun_access_key_id
@@ -147,7 +154,7 @@ HYDE_ENABLED=true
 HYDE_MAX_TOKENS=200
 # ?????? LLM;???????????????
 HYDE_LLM_PROVIDER=qwen
-HYDE_LLM_MODEL=qwen3.5-flash
+HYDE_LLM_MODEL=qwen3.6-flash
 
 # ===== Agentic RAG 配置 (P0-1) =====
 # 以下参数控制 /api/v1/agent/agentic/stream 多步推理管线
@@ -166,3 +173,19 @@ AGENTIC_GROUNDING_MAX_TOKENS=250
 # 逗号分隔的允许跨域来源列表，生产环境绝不能使用 *
 CORS_ALLOW_ORIGINS=http://localhost:5173
 
+# ===== MCP (Model Context Protocol) =====
+# MCP 端点（/mcp/）的 Host 头白名单，逗号分隔。MCP SDK 默认开启 DNS rebinding
+# 防护，任何不在此列表中的 Host 都会被直接返回 HTTP 421，请求根本到不了鉴权和
+# 工具逻辑。因此**远程部署必须把真实访问地址写进来**，否则所有外部 MCP 客户端
+# （Claude Desktop / IDE 等）100% 连不上。
+# 语法：`:*` 后缀表示匹配任意端口；填 `*` 表示彻底关闭该防护（不推荐）。
+# 例如部署在 6.86.80.9:8000 时：
+# MCP_ALLOWED_HOSTS=6.86.80.9:*,127.0.0.1:*,localhost:*
+MCP_ALLOWED_HOSTS=127.0.0.1:*,localhost:*,[::1]:*
+
+# 系统状态页展示、以及"复制接入配置"按钮所使用的 MCP 外部访问地址。
+# 留空则由后端从请求的 Host 头推导；当前端经 Vite 代理（changeOrigin: true）
+# 或反向代理改写了 Host 时，推导结果会是 127.0.0.1，此时必须显式指定。
+# MCP_PUBLIC_URL=http://6.86.80.9:8000/mcp/
+MCP_PUBLIC_URL=
+

backend/app/api/main.py

@@ -1,6 +1,6 @@
 """FastAPI application entrypoint."""
 
-from contextlib import asynccontextmanager
+from contextlib import AsyncExitStack, asynccontextmanager
 
 from fastapi import FastAPI, Request
 from fastapi.encoders import jsonable_encoder
@@ -13,6 +13,7 @@ from app.api.models import ErrorResponse
 from app.api.routes import api_router
 from app.config.logging import setup_logging
 from app.config.settings import settings
+from app.mcp.server import build_mcp_asgi_app
 from app.shared.bootstrap import cleanup_runtime_dependencies, preload_runtime_dependencies
 from app.shared.errors import VectorStoreSchemaError
 # Keep module behavior explicit so the backend flow stays easy to audit.
@@ -20,10 +21,23 @@ from app.shared.errors import VectorStoreSchemaError
 
 setup_logging(level="INFO" if not settings.debug else "DEBUG")
 
+# Built once at module scope so both lifespan() and app.mount() below reference
+# the same instance — mounting a second, separately-built instance would start
+# a second, unrelated MCP session manager.
+mcp_app = build_mcp_asgi_app()
+
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     """Application lifecycle hooks."""
+    # FastMCP-style servers own a session manager that only starts via its own
+    # lifespan context. app.mount() does NOT propagate nested ASGI lifespans
+    # automatically (confirmed Starlette/ASGI limitation) — without this,
+    # every search_regulations call would fail because the MCP session
+    # manager was never started.
+    async with AsyncExitStack() as stack:
+        await stack.enter_async_context(mcp_app.router.lifespan_context(mcp_app))
+
         logger.info(f"启动 {settings.app_name} v{settings.app_version}")
         logger.info(f"调试模式: {settings.debug}")
         logger.info("预加载LLM客户端...")
@@ -65,6 +79,7 @@ app.add_middleware(
 app.add_middleware(AuditMiddleware)
 
 app.include_router(api_router, prefix="/api/v1")
+app.mount("/mcp", mcp_app)
 
 
 @app.exception_handler(VectorStoreSchemaError)

backend/app/api/routes/perception.py

@@ -7,7 +7,12 @@ import json
 from fastapi import APIRouter, Depends, Query
 from fastapi.responses import StreamingResponse
 
-from app.shared.bootstrap import get_crawl_service, get_event_store, get_perception_service
+from app.shared.bootstrap import (
+    get_crawl_service,
+    get_event_store,
+    get_notification_store,
+    get_perception_service,
+)
 from app.api.dependencies.auth import get_current_user
 from app.domain.auth.models import UserClaims
 from app.shared.async_utils import iter_in_thread
@@ -141,3 +146,26 @@ async def get_event_diff(event_id: str):
         "previous_hash": event.get("previous_hash"),
         "content_hash": event.get("content_hash"),
     }
+
+
+@router.get("/notifications")
+async def list_notifications(
+    limit: int = Query(default=20, ge=1, le=100),
+    current_user: UserClaims = Depends(get_current_user),
+):
+    """Return the newest in-app notifications plus this user's unread count.
+
+    Every logged-in user sees the same broadcast feed — there is no per-role
+    or per-topic subscription. "read" per item and the aggregate unread_count
+    both reflect only the calling user's own read receipts.
+    """
+    store = get_notification_store()
+    items = store.list_for_user(current_user.user_id, limit=limit)
+    return {"items": items, "unread_count": store.unread_count(current_user.user_id)}
+
+
+@router.post("/notifications/read")
+async def mark_notifications_read(current_user: UserClaims = Depends(get_current_user)):
+    """Mark every currently-unread notification read for the calling user."""
+    marked = get_notification_store().mark_all_read(current_user.user_id)
+    return {"marked": marked}

backend/app/api/routes/status.py

@@ -4,10 +4,11 @@ import asyncio
 import time
 from typing import Any
 
-from fastapi import APIRouter
+from fastapi import APIRouter, Request
 
 from app.config.settings import settings
 from app.domain.retrieval import RetrievedChunk
+from app.mcp.server import get_mcp_status
 from app.services.llm.llm_factory import get_llm_client, get_llm_factory
 from app.shared.bootstrap import (
     get_bm25_retriever,
@@ -280,3 +281,17 @@ async def ping_model_connections():
     ]
     await asyncio.gather(*tasks, return_exceptions=True)
     return {"models": [_build_model_status(role) for role in _MODEL_ROLES]}
+
+
+@router.get("/mcp")
+async def get_mcp_server_status(request: Request):
+    """Return MCP endpoint config, advertised tools, and per-tool call counters.
+
+    This route is a thin HTTP adapter: everything MCP-specific is assembled by
+    app.mcp.server.get_mcp_status(). The only thing decided here is the public
+    URL, because only the HTTP layer knows how the client reached us.
+    """
+    # request.base_url already carries scheme/host/port and a trailing slash;
+    # strip it before appending so the result is ".../mcp/", not ".../mcp//".
+    public_url = settings.mcp_public_url or f"{str(request.base_url).rstrip('/')}/mcp/"
+    return await get_mcp_status(public_url)

backend/app/application/agent/hyde_expander.py

@@ -73,7 +73,7 @@ class HyDEExpander:
             return query
 
         # Use the dedicated HyDE model when configured; fall back to main LLM.
-        # A lightweight model (e.g. qwen3.5-flash) is sufficient for generating
+        # A lightweight model (e.g. qwen3.6-flash) is sufficient for generating
         # a short hypothetical passage and significantly reduces cost + latency.
         provider = settings.hyde_llm_provider or settings.llm_provider
         model = settings.hyde_llm_model or settings.llm_model

backend/app/application/perception/crawl_service.py

@@ -7,9 +7,13 @@ from typing import Any, Generator
 
 from loguru import logger
 
+from app.config.settings import settings
+from app.domain.documents import ParsedDocument
 from app.infrastructure.perception.base_event_store import BaseEventStore
+from app.infrastructure.perception.base_notification_store import BaseNotificationStore
 from app.infrastructure.perception.crawlers.base import BaseCrawler, RawEvent
 from app.infrastructure.perception.llm_pipeline import LlmPipeline
+from app.infrastructure.parser.local_chunk_builder import LocalRegulationChunkBuilder
 
 
 def _event_id(source: str, standard_code: str) -> str:
@@ -21,7 +25,68 @@ def _content_hash(raw_text: str) -> str:
     return hashlib.sha256(raw_text.encode()).hexdigest()
 
 
-def _raw_to_dict(raw: RawEvent, event_id: str, content_hash: str) -> dict:
+def _is_significant(changed_sections: list[dict]) -> bool:
+    """Report whether any changed section is worth notifying every user about.
+
+    changed_sections legitimately includes cosmetic edits — the differ
+    (subproject 1) still reports a fixed typo or a dropped trailing period as
+    a change, it just doesn't send those to the LLM. Broadcasting a
+    notification for every cosmetic edit would train people to ignore it, so
+    this reuses the same significance test the differ's own LLM gate applies:
+    a numeric or deontic change, or a whole paragraph added or removed.
+    """
+    return any(
+        section.get("numeric_changed")
+        or section.get("deontic_changed")
+        or section.get("change_type") in ("added", "removed")
+        for section in changed_sections
+    )
+
+
+def _index_in_knowledge_base(event: dict, *, embedding_provider: Any, vector_index: Any) -> None:
+    """Chunk, embed, and upsert a regulation's text into the shared knowledge base.
+
+    Always uses the local markdown chunker, never get_chunk_builder() — that
+    bootstrap function resolves to AliyunVectorChunkBuilder when
+    settings.chunk_backend == "aliyun" (the deployed value), which consumes
+    Aliyun DocMind's structured parse output. Crawled text has no such parse
+    output; it is already plain text (trafilatura, subproject 1), which is
+    exactly what LocalRegulationChunkBuilder chunks directly.
+
+    delete_by_document runs unconditionally before upsert — a no-op for a
+    brand-new event, and the only way to keep a changed regulation from
+    leaving its superseded text retrievable alongside the new version.
+    """
+    vector_index.delete_by_document(event["id"])
+
+    parsed = ParsedDocument(
+        doc_id=event["id"],
+        doc_name=event.get("title", ""),
+        structure_nodes=[],
+        semantic_blocks=[],
+        vector_chunks=[],
+        parser_name="perception_crawl",
+        raw_text=event.get("raw_text") or "",
+    )
+    builder = LocalRegulationChunkBuilder(
+        chunk_size=settings.chunk_size, chunk_overlap=settings.chunk_overlap,
+    )
+    chunks = builder.build(
+        parsed_document=parsed,
+        # regulation_type/version fill the same slots a manually uploaded
+        # document's form fields would, so the two intake paths are
+        # indistinguishable to retrieval and compliance analysis.
+        regulation_type=event.get("category", ""),
+        version=event.get("standard_code", ""),
+    )
+    if not chunks:
+        return
+
+    vectors = embedding_provider.embed_texts([c.embedding_text for c in chunks])
+    vector_index.upsert(chunks, vectors)
+
+
+def _raw_to_dict(raw: RawEvent, event_id: str, content_hash: str, raw_text: str) -> dict:
     return {
         "id": event_id,
         "source": raw.source,
@@ -36,6 +101,10 @@ def _raw_to_dict(raw: RawEvent, event_id: str, content_hash: str) -> dict:
         "effective_at": raw.effective_at,
         "category": raw.category,
         "tags": raw.tags,
+        # Persisted so the next crawl has a baseline to diff against. Without
+        # this the change detector has nothing to compare and every update
+        # looks like a first sighting.
+        "raw_text": raw_text,
         "content_hash": content_hash,
         "previous_hash": None,
     }
@@ -50,11 +119,17 @@ class CrawlService:
         event_store: BaseEventStore,
         llm_pipeline: LlmPipeline,
         retrieval_service: Any,
+        notification_store: BaseNotificationStore,
+        embedding_provider: Any,
+        vector_index: Any,
     ) -> None:
         self._crawlers = crawlers
         self._store = event_store
         self._pipeline = llm_pipeline
         self._retrieval = retrieval_service
+        self._notifications = notification_store
+        self._embedding_provider = embedding_provider
+        self._vector_index = vector_index
 
     def run_crawl(
         self, sources: list[str] | None = None
@@ -72,7 +147,7 @@ class CrawlService:
 
             yield {"event": "progress", "data": {"source": source_key, "stage": "fetching"}}
             try:
-                raw_events = crawler.fetch(limit=100)
+                raw_events = crawler.fetch(limit=settings.perception_max_events_per_source)
             except Exception as exc:
                 logger.exception("Crawler failed source={}", source_key)
                 yield {"event": "error", "data": {"source": source_key, "message": str(exc)}}
@@ -88,17 +163,21 @@ class CrawlService:
 
             for raw in raw_events:
                 eid = _event_id(raw.source, raw.standard_code)
-                new_hash = _content_hash(raw.raw_text or raw.title)
+                # List pages carry only a code and a title, which is not enough
+                # to detect a change in the regulation itself. Fetch the body,
+                # degrading to whatever the list page gave us if that fails.
+                body_text = crawler.fetch_full_text(raw.full_text_url) or raw.raw_text or raw.title
+                new_hash = _content_hash(body_text)
                 existing = self._store.get(eid)
 
                 if existing and existing.get("content_hash") == new_hash:
                     continue
 
                 is_update = existing is not None
-                old_text = existing.get("summary", "") if is_update else ""
+                old_body = existing.get("raw_text") or "" if is_update else ""
                 previous_hash = existing.get("content_hash") if is_update else None
 
-                event_dict = _raw_to_dict(raw, eid, new_hash)
+                event_dict = _raw_to_dict(raw, eid, new_hash, body_text)
                 event_dict["previous_hash"] = previous_hash
 
                 try:
@@ -113,9 +192,11 @@ class CrawlService:
                 except Exception as exc:
                     logger.warning("Impact assessment failed id={} err={}", eid, exc)
 
-                if is_update and old_text and raw.raw_text:
+                # Events stored before raw_text was persisted have no baseline,
+                # so they are treated as a first sighting and establish one now.
+                if is_update and old_body and body_text:
                     try:
-                        diff = self._pipeline.compute_diff(old_text, raw.raw_text)
+                        diff = self._pipeline.compute_diff(old_body, body_text)
                         event_dict["change_summary"] = diff.get("change_summary")
                         event_dict["changed_sections"] = diff.get("changed_sections")
                     except Exception as exc:
@@ -123,6 +204,33 @@ class CrawlService:
 
                 self._store.upsert(event_dict)
 
+                should_index = not is_update or _is_significant(event_dict.get("changed_sections") or [])
+
+                try:
+                    if not is_update:
+                        self._notifications.create(
+                            event_id=eid, kind="new", title=raw.title,
+                            impact_level=event_dict.get("impact_level"), summary=None,
+                        )
+                    elif should_index:  # significant change, already computed above
+                        self._notifications.create(
+                            event_id=eid, kind="changed", title=raw.title,
+                            impact_level=event_dict.get("impact_level"),
+                            summary=event_dict.get("change_summary"),
+                        )
+                except Exception as exc:
+                    logger.warning("Notification create failed id={} err={}", eid, exc)
+
+                if should_index:
+                    try:
+                        _index_in_knowledge_base(
+                            event_dict,
+                            embedding_provider=self._embedding_provider,
+                            vector_index=self._vector_index,
+                        )
+                    except Exception as exc:
+                        logger.warning("Knowledge base indexing failed id={} err={}", eid, exc)
+
                 if is_update:
                     updated_count += 1
                 else:

backend/app/config/settings.py

@@ -94,9 +94,21 @@ class Settings(BaseSettings):
     perception_max_events_per_source: int = Field(
         default=100, description="Maximum events fetched per source per crawl run."
     )
-    perception_diff_similarity_threshold: float = Field(
+    perception_diff_min_change_ratio: float = Field(
-        default=0.85,
+        default=0.02,
-        description="Cosine similarity below which a paragraph is flagged as changed.",
+        description=(
+            "Fraction of characters that must differ before an otherwise "
+            "unremarkable paragraph edit is worth an LLM classification call. "
+            "Numeric and deontic changes bypass this gate entirely."
+        ),
+    )
+    perception_crawl_interval_seconds: int = Field(
+        default=21600,
+        description=(
+            "How often Celery Beat runs the scheduled crawl-all-sources task, "
+            "in seconds. Default 21600 = 6 hours. Only takes effect when a "
+            "Beat process is running (./dev.sh start beat)."
+        ),
     )
 
     # Keep configuration setup explicit so runtime behavior is easy to reason about.
@@ -117,7 +129,7 @@ class Settings(BaseSettings):
     # Keep configuration setup explicit so runtime behavior is easy to reason about.
     qwen_api_key: str = Field(default="", description="Qwen API密钥")
     qwen_base_url: str = Field(default="http://6.86.80.4:30080/v1", description="Qwen API地址")
-    qwen_model: str = Field(default="qwen3.5-flash", description="Qwen文本模型")
+    qwen_model: str = Field(default="qwen3.6-flash", description="Qwen文本模型")
     qwen_vl_model: str = Field(default="qwen3-vl-plus", description="Qwen视觉模型")
 
     # Keep configuration setup explicit so runtime behavior is easy to reason about.
@@ -198,6 +210,32 @@ class Settings(BaseSettings):
         description="Comma-separated allowed CORS origins. Never use * in production.",
     )
 
+    # ── MCP ───────────────────────────────────────────────────────────────────
+    # The MCP SDK enables DNS-rebinding protection whenever the transport is
+    # bound to a loopback host, which rejects any Host header not in this list
+    # with HTTP 421. Deployments reachable by a real hostname/IP must list it
+    # here or every remote MCP client is refused before the handler runs.
+    mcp_allowed_hosts: str = Field(
+        default="127.0.0.1:*,localhost:*,[::1]:*",
+        description=(
+            "Comma-separated Host header values accepted by the MCP endpoint. "
+            "A ':*' suffix matches any port. Set to '*' to disable DNS-rebinding "
+            "protection entirely (not recommended)."
+        ),
+    )
+
+    # Optional override for the URL shown on the System Status page and copied
+    # into client configs. Needed because request.base_url reflects the Host
+    # header, which the Vite dev proxy (changeOrigin: true) and reverse proxies
+    # that do not forward the original Host both rewrite.
+    mcp_public_url: str = Field(
+        default="",
+        description=(
+            "Externally reachable MCP endpoint URL, e.g. http://6.86.80.9:8000/mcp/. "
+            "Leave empty to derive it from the incoming request."
+        ),
+    )
+
 @lru_cache
 def get_settings() -> Settings:
     """Return settings."""

backend/app/infrastructure/perception/base_notification_store.py

@@ -0,0 +1,47 @@
+"""Abstract base class for in-app regulatory-signal notifications.
+
+A notification is created once per triggering event (a brand-new regulation,
+or a significant change to an existing one) and broadcast to every logged-in
+user. There is no per-user subscription targeting — see the design doc for why.
+Per-user "read" state is tracked separately from the notification itself, so
+one notification row serves every user rather than being fanned out on create.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class BaseNotificationStore(ABC):
+    """Port interface for perception notification persistence."""
+
+    @abstractmethod
+    def create(
+        self,
+        *,
+        event_id: str,
+        kind: str,
+        title: str,
+        impact_level: str | None,
+        summary: str | None,
+    ) -> None:
+        """Record a new notification. kind is 'new' or 'changed'."""
+
+    @abstractmethod
+    def list_for_user(self, user_id: str, limit: int = 20) -> list[dict]:
+        """Return the most recent notifications, newest first.
+
+        Each item includes a "read" boolean reflecting whether `user_id` has
+        marked it read.
+        """
+
+    @abstractmethod
+    def unread_count(self, user_id: str) -> int:
+        """Return how many notifications `user_id` has not yet read."""
+
+    @abstractmethod
+    def mark_all_read(self, user_id: str) -> int:
+        """Mark every currently-unread notification read for `user_id`.
+
+        Returns the number of notifications newly marked.
+        """

backend/app/infrastructure/perception/crawlers/base.py

@@ -5,6 +5,12 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 
+import httpx
+import trafilatura
+from loguru import logger
+
+from app.config.settings import settings
+
 
 @dataclass
 class RawEvent:
@@ -21,7 +27,10 @@ class RawEvent:
     effective_at: str | None
     category: str
     tags: list[str] = field(default_factory=list)
-    raw_text: str = ""    # full crawled text for hashing + LLM
+    # Whatever text the list page yields. CrawlService upgrades this by calling
+    # fetch_full_text(full_text_url); this value is the fallback when that
+    # fails. Used for change hashing and for the version diff.
+    raw_text: str = ""
 
 
 class BaseCrawler(ABC):
@@ -30,3 +39,37 @@ class BaseCrawler(ABC):
     @abstractmethod
     def fetch(self, limit: int = 50) -> list[RawEvent]:
         """Fetch up to `limit` recent events from the data source."""
+
+    def fetch_full_text(self, url: str) -> str:
+        """Download a regulation detail page and extract its body text.
+
+        Change detection is only as good as the text it compares, and list
+        pages carry nothing but a standard code and a title. This default
+        implementation serves all current sources; a source that needs PDF
+        extraction or authentication overrides this one method.
+
+        Returns an empty string on any failure rather than raising, so one
+        unreachable page cannot abort a whole crawl run. The caller decides how
+        to degrade.
+        """
+        if not url:
+            return ""
+        try:
+            response = httpx.get(
+                url,
+                timeout=settings.perception_crawl_timeout_seconds,
+                follow_redirects=True,
+            )
+            response.raise_for_status()
+        except Exception as exc:  # noqa: BLE001 - any transport error degrades the same way
+            logger.warning("Full-text fetch failed url={} err={}", url, exc)
+            return ""
+
+        # trafilatura scores 0.92 F1 on government pages against 0.78 for
+        # readability-lxml, and handles CJK content; include_tables matters
+        # because regulatory limits are frequently tabulated.
+        extracted = trafilatura.extract(response.text, include_tables=True)
+        if not extracted:
+            logger.warning("Full-text extraction returned nothing url={}", url)
+            return ""
+        return extracted.strip()

backend/app/infrastructure/perception/crawlers/catarc_crawler.py

@@ -8,6 +8,7 @@ import httpx
 from bs4 import BeautifulSoup
 from loguru import logger
 
+from app.config.settings import settings
 from app.infrastructure.perception.crawlers.base import BaseCrawler, RawEvent
 from ._utils import extract_tags, parse_date
 
@@ -33,7 +34,11 @@ class CatarcCrawler(BaseCrawler):
         while len(events) < limit and page <= max_pages:
             url = f"{_BASE_URL}?page={page}"
             try:
-                resp = httpx.get(url, timeout=30, follow_redirects=True)
+                resp = httpx.get(
+                    url,
+                    timeout=settings.perception_crawl_timeout_seconds,
+                    follow_redirects=True,
+                )
                 resp.raise_for_status()
             except Exception as exc:
                 logger.warning("CATARC fetch failed page={} err={}", page, exc)

backend/app/infrastructure/perception/crawlers/eurlex_crawler.py

@@ -9,6 +9,7 @@ import httpx
 from bs4 import BeautifulSoup
 from loguru import logger
 
+from app.config.settings import settings
 from app.infrastructure.perception.crawlers.base import BaseCrawler, RawEvent
 from ._utils import parse_date
 
@@ -53,7 +54,11 @@ class EurlexCrawler(BaseCrawler):
             if len(events) >= limit:
                 break
             try:
-                resp = httpx.get(rss_url, timeout=30, follow_redirects=True)
+                resp = httpx.get(
+                    rss_url,
+                    timeout=settings.perception_crawl_timeout_seconds,
+                    follow_redirects=True,
+                )
                 resp.raise_for_status()
             except Exception as exc:
                 logger.warning("EUR-Lex RSS fetch failed url={} err={}", rss_url, exc)

backend/app/infrastructure/perception/crawlers/guobiao_crawler.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import httpx
 from loguru import logger
 
+from app.config.settings import settings
 from app.infrastructure.perception.crawlers.base import BaseCrawler, RawEvent
 from ._utils import extract_tags, parse_date
 
@@ -22,7 +23,12 @@ def _fetch_page(std_type: int, page: int, page_size: int) -> list[dict]:
         "p.p7": page_size,
     }
     try:
-        resp = httpx.get(_BASE_URL, params=params, headers=_HEADERS, timeout=30)
+        resp = httpx.get(
+            _BASE_URL,
+            params=params,
+            headers=_HEADERS,
+            timeout=settings.perception_crawl_timeout_seconds,
+        )
         resp.raise_for_status()
         data = resp.json()
         return data.get("rows", []) or []

backend/app/infrastructure/perception/llm_pipeline.py

@@ -3,14 +3,14 @@
 from __future__ import annotations
 
 import json
-import math
 from typing import Any
 
 from loguru import logger
 
 from app.config.settings import settings
-from app.infrastructure.embedding.openai_compatible_embedding_provider import (
+from app.infrastructure.perception.regulation_differ import (
-    OpenAICompatibleEmbeddingProvider,
+    ParagraphChange,
+    RegulationDiffer,
 )
 from app.services.llm.llm_factory import get_llm_client
 
@@ -27,21 +27,31 @@ _ASSESS_SYSTEM = (
 )
 
 _DIFF_SYSTEM = (
-    "You are a regulatory change analyst. Given an old and new version of a regulation paragraph, "
+    "You are a regulatory change analyst. You are given the OLD and NEW version of "
-    "classify the type of change and summarise it. "
+    "one regulation paragraph, with the exact edits marked <DEL>removed</DEL> and "
-    "Return JSON only: {\"change_type\": \"tightened|relaxed|added|removed\", \"summary\": \"...\"}"
+    "<INS>added</INS>. Classify the legal effect of the change. "
+    "Return JSON only: {\"change_type\": \"tightened|relaxed|numeric|clarified|scope\", "
+    "\"legal_effect\": \"one sentence on what this means for compliance\"}"
 )
 
-_SIMILARITY_THRESHOLD = 0.85
 
+def _marked_diff(change: ParagraphChange) -> str:
+    """Render a paragraph change with the exact edits marked for the model.
 
-def _cosine(a: list[float], b: list[float]) -> float:
+    The model is shown where the edit is rather than being asked to find it,
-    dot = sum(x * y for x, y in zip(a, b))
+    and is never asked to reproduce the changed text — the differ already
-    norm_a = math.sqrt(sum(x * x for x in a))
+    computed those spans exactly, so there is nothing for the model to
-    norm_b = math.sqrt(sum(x * x for x in b))
+    hallucinate.
-    if norm_a == 0 or norm_b == 0:
+    """
-        return 0.0
+    marked = "".join(
-    return dot / (norm_a * norm_b)
+        text if op == 0 else (f"<DEL>{text}</DEL>" if op < 0 else f"<INS>{text}</INS>")
+        for op, text in change.diff_spans
+    )
+    return (
+        f"OLD: {change.old_text[:500]}\n"
+        f"NEW: {change.new_text[:500]}\n"
+        f"MARKED: {marked[:800]}"
+    )
 
 
 def _llm_json(client: Any, messages: list[dict]) -> Any:
@@ -67,7 +77,9 @@ class LlmPipeline:
             provider=settings.llm_provider,
             model=settings.llm_model,
         )
-        self._embedder = OpenAICompatibleEmbeddingProvider()
+        # Change detection is deterministic; the differ needs no model and no
+        # network, so the pipeline no longer constructs an embedding provider.
+        self._differ = RegulationDiffer()
 
     # ------------------------------------------------------------------
     # Step 1: Structure extraction
@@ -166,76 +178,68 @@ For each document, assess impact and recommend action. Return JSON array:
         return doc_excerpts
 
     # ------------------------------------------------------------------
-    # Step 3: Semantic diff
+    # Step 3: Deterministic diff with gated LLM classification
     # ------------------------------------------------------------------
 
     def compute_diff(self, old_text: str, new_text: str) -> dict:
-        """Compare old and new regulation text; return changed sections and summary."""
+        """Compare old and new regulation text; return changed sections and summary.
-        old_paras = [p.strip() for p in old_text.split("\n") if p.strip()]
-        new_paras = [p.strip() for p in new_text.split("\n") if p.strip()]
 
-        if not old_paras or not new_paras:
+        Detection is deterministic — see regulation_differ for why embedding
-            return {"changed_sections": [], "change_summary": "No comparable text."}
+        similarity was removed. The LLM is called only for paragraphs the
+        differ marked significant, and only to explain the legal effect of a
+        change that has already been located exactly.
+        """
+        changes = self._differ.diff(old_text, new_text)
+        if not changes:
+            return {
+                "changed_sections": [],
+                "change_summary": "No substantive changes detected between versions.",
+            }
 
-        all_paras = old_paras + new_paras
+        changed_sections = [self._describe(change) for change in changes]
-        try:
-            all_embeddings = self._embedder.embed_texts(all_paras)
-        except Exception as exc:
-            logger.warning("Embedding for diff failed: {}", exc)
-            return {"changed_sections": [], "change_summary": "Diff unavailable (embedding error)."}
 
-        old_embeddings = all_embeddings[: len(old_paras)]
+        types = sorted({section["change_type"] for section in changed_sections})
-        new_embeddings = all_embeddings[len(old_paras):]
+        gated = sum(1 for change in changes if change.needs_llm)
-
-        changed_sections: list[dict] = []
-        max_len = max(len(old_paras), len(new_paras))
-
-        for i in range(max_len):
-            if i >= len(old_paras):
-                # New paragraph added
-                changed_sections.append({
-                    "old_text": "",
-                    "new_text": new_paras[i][:300],
-                    "similarity": 0.0,
-                    "change_type": "added",
-                    "summary": "New paragraph added.",
-                })
-                continue
-            if i >= len(new_paras):
-                # Old paragraph removed
-                changed_sections.append({
-                    "old_text": old_paras[i][:300],
-                    "new_text": "",
-                    "similarity": 0.0,
-                    "change_type": "removed",
-                    "summary": "Paragraph removed.",
-                })
-                continue
-            # Both exist — compare via embeddings
-            sim = _cosine(old_embeddings[i], new_embeddings[i])
-            if sim < _SIMILARITY_THRESHOLD:
-                messages = [
-                    {"role": "system", "content": _DIFF_SYSTEM},
-                    {"role": "user", "content": f"OLD: {old_paras[i][:500]}\nNEW: {new_paras[i][:500]}"},
-                ]
-                classification = _llm_json(self._client, messages) or {}
-                changed_sections.append({
-                    "old_text": old_paras[i][:300],
-                    "new_text": new_paras[i][:300],
-                    "similarity": round(sim, 3),
-                    "change_type": classification.get("change_type", "modified"),
-                    "summary": classification.get("summary", ""),
-                })
-
-        if not changed_sections:
-            change_summary = "No substantive changes detected between versions."
-        else:
-            types = [s["change_type"] for s in changed_sections]
         change_summary = (
-                f"{len(changed_sections)} paragraph(s) changed: "
+            f"{len(changed_sections)} paragraph(s) changed ({', '.join(types)}); "
-                + ", ".join(f"{t}" for t in set(types))
+            f"{gated} significant. "
-                + ". "
+            + (changed_sections[0].get("summary") or "")
-                + (changed_sections[0].get("summary", "") if changed_sections else "")
+        ).strip()
-            )
 
         return {"changed_sections": changed_sections, "change_summary": change_summary}
+
+    def _describe(self, change: ParagraphChange) -> dict:
+        """Turn one detected change into the API payload, classifying if warranted."""
+        section = {
+            "old_text": change.old_text[:300],
+            "new_text": change.new_text[:300],
+            "change_type": change.change_type,
+            "change_ratio": round(change.change_ratio, 3),
+            "numeric_changed": change.numeric_changed,
+            "deontic_changed": change.deontic_changed,
+            "summary": "",
+        }
+
+        if not change.needs_llm:
+            return section
+
+        classification = _llm_json(
+            self._client,
+            [
+                {"role": "system", "content": _DIFF_SYSTEM},
+                {"role": "user", "content": _marked_diff(change)},
+            ],
+        )
+        if isinstance(classification, dict):
+            section["change_type"] = classification.get("change_type") or change.change_type
+            section["summary"] = classification.get("legal_effect") or ""
+        # A failed or malformed model response must not discard a change that
+        # deterministic analysis already proved real; the section keeps its
+        # spans, flags, and alignment-derived type with an empty summary.
+
+        if change.numeric_changed:
+            # Models routinely label a changed threshold as "clarified". The
+            # deterministic pass already knows a number moved, so it wins.
+            section["change_type"] = "numeric"
+
+        return section

backend/app/infrastructure/perception/mock_notification_store.py

@@ -0,0 +1,66 @@
+"""In-memory notification store used when Postgres is not configured.
+
+Mirrors MockEventStore's role for BaseEventStore: keeps the feature usable in
+local dev and in tests without a live database, and matches
+DOCUMENT_REPOSITORY_BACKEND's existing Mock/Postgres split.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from app.infrastructure.perception.base_notification_store import BaseNotificationStore
+
+
+class MockNotificationStore(BaseNotificationStore):
+    """Dict-backed notification store. Data does not survive a process restart."""
+
+    def __init__(self) -> None:
+        """Start with an empty feed and no read receipts."""
+        self._notifications: list[dict] = []
+        self._next_id = 1
+        # (notification_id, user_id) pairs — presence means read.
+        self._reads: set[tuple[int, str]] = set()
+
+    def create(
+        self,
+        *,
+        event_id: str,
+        kind: str,
+        title: str,
+        impact_level: str | None,
+        summary: str | None,
+    ) -> None:
+        """Append a notification with an auto-incrementing id."""
+        self._notifications.append({
+            "id": self._next_id,
+            "event_id": event_id,
+            "kind": kind,
+            "title": title,
+            "impact_level": impact_level,
+            "summary": summary,
+            "created_at": datetime.now(UTC).isoformat(),
+        })
+        self._next_id += 1
+
+    def list_for_user(self, user_id: str, limit: int = 20) -> list[dict]:
+        """Return the newest `limit` notifications with this user's read state."""
+        ordered = sorted(self._notifications, key=lambda n: n["id"], reverse=True)
+        return [
+            {**n, "read": (n["id"], user_id) in self._reads}
+            for n in ordered[:limit]
+        ]
+
+    def unread_count(self, user_id: str) -> int:
+        """Count notifications this user has not yet read."""
+        return sum(1 for n in self._notifications if (n["id"], user_id) not in self._reads)
+
+    def mark_all_read(self, user_id: str) -> int:
+        """Add a read receipt for every currently-unread notification."""
+        marked = 0
+        for n in self._notifications:
+            key = (n["id"], user_id)
+            if key not in self._reads:
+                self._reads.add(key)
+                marked += 1
+        return marked

backend/app/infrastructure/perception/postgres_event_store.py

@@ -40,7 +40,8 @@ CREATE TABLE IF NOT EXISTS regulation_events (
     affected_docs    JSONB,
     crawled_at       TIMESTAMPTZ DEFAULT now(),
     processed_at     TIMESTAMPTZ,
-    raw_storage_key  TEXT
+    raw_storage_key  TEXT,
+    raw_text         TEXT
 );
 CREATE INDEX IF NOT EXISTS reg_events_source_date
     ON regulation_events (source, published_at DESC);
@@ -48,12 +49,16 @@ CREATE INDEX IF NOT EXISTS reg_events_impact_date
     ON regulation_events (impact_level, published_at DESC);
 """
 
+_ADD_COLUMNS = """
+ALTER TABLE regulation_events ADD COLUMN IF NOT EXISTS raw_text TEXT;
+"""
+
 _ALL_COLUMNS = (
     "id", "source", "source_label", "standard_code", "title", "summary",
     "full_text_url", "status", "impact_level", "published_at", "effective_at",
     "category", "tags", "obligations", "deadlines", "scope", "penalties",
     "content_hash", "previous_hash", "change_summary", "changed_sections",
-    "affected_docs", "crawled_at", "processed_at", "raw_storage_key",
+    "affected_docs", "crawled_at", "processed_at", "raw_storage_key", "raw_text",
 )
 
 
@@ -97,6 +102,10 @@ class PostgresEventStore(BaseEventStore):
             try:
                 with conn.cursor() as cur:
                     cur.execute(_CREATE_TABLE)
+                    # CREATE TABLE IF NOT EXISTS is a no-op on deployments that
+                    # already have this table, so new columns must be added
+                    # explicitly or existing installations silently lack them.
+                    cur.execute(_ADD_COLUMNS)
                 conn.commit()
             except Exception:
                 conn.rollback()

backend/app/infrastructure/perception/postgres_notification_store.py

@@ -0,0 +1,157 @@
+"""PostgreSQL-backed notification store.
+
+One row per triggering event, shared by every user; a separate read-receipt
+table tracks per-user read state so broadcasting to everyone needs no fan-out
+insert per user. See base_notification_store.py for the port contract and the
+design doc for why this shape was chosen over per-user subscriptions.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Any
+
+import psycopg2
+import psycopg2.extras
+from psycopg2.pool import ThreadedConnectionPool
+
+from app.config.settings import settings
+from app.infrastructure.perception.base_notification_store import BaseNotificationStore
+
+_CREATE_TABLES = """
+CREATE TABLE IF NOT EXISTS perception_notifications (
+    id           SERIAL PRIMARY KEY,
+    event_id     TEXT NOT NULL REFERENCES regulation_events(id) ON DELETE CASCADE,
+    kind         TEXT NOT NULL,
+    title        TEXT NOT NULL,
+    impact_level TEXT,
+    summary      TEXT,
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS perception_notification_reads (
+    notification_id INTEGER NOT NULL REFERENCES perception_notifications(id) ON DELETE CASCADE,
+    user_id          TEXT NOT NULL,
+    read_at          TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (notification_id, user_id)
+);
+CREATE INDEX IF NOT EXISTS perception_notif_created
+    ON perception_notifications (created_at DESC);
+"""
+
+
+def _row_to_dict(row: dict[str, Any]) -> dict:
+    """Convert a psycopg2 RealDictRow to a plain dict with an ISO timestamp."""
+    d = dict(row)
+    if d.get("created_at") is not None:
+        d["created_at"] = d["created_at"].isoformat()
+    return d
+
+
+class PostgresNotificationStore(BaseNotificationStore):
+    """Notification store backed by PostgreSQL."""
+
+    def __init__(self) -> None:
+        """Open a connection pool and ensure both tables exist."""
+        self._pool = ThreadedConnectionPool(
+            minconn=1,
+            maxconn=5,
+            host=settings.postgres_host,
+            port=settings.postgres_port,
+            user=settings.postgres_user,
+            password=settings.postgres_password,
+            dbname=settings.postgres_db,
+        )
+        self._ensure_schema()
+
+    def _ensure_schema(self) -> None:
+        with self._conn() as conn:
+            try:
+                with conn.cursor() as cur:
+                    cur.execute(_CREATE_TABLES)
+                conn.commit()
+            except Exception:
+                conn.rollback()
+                raise
+
+    @contextmanager
+    def _conn(self):
+        conn = None
+        try:
+            conn = self._pool.getconn()
+            yield conn
+        finally:
+            if conn is not None:
+                self._pool.putconn(conn)
+
+    def create(
+        self,
+        *,
+        event_id: str,
+        kind: str,
+        title: str,
+        impact_level: str | None,
+        summary: str | None,
+    ) -> None:
+        """Insert one notification row for the triggering event."""
+        with self._conn() as conn:
+            with conn.cursor() as cur:
+                cur.execute(
+                    "INSERT INTO perception_notifications "
+                    "(event_id, kind, title, impact_level, summary) "
+                    "VALUES (%s, %s, %s, %s, %s)",
+                    (event_id, kind, title, impact_level, summary),
+                )
+            conn.commit()
+
+    def list_for_user(self, user_id: str, limit: int = 20) -> list[dict]:
+        """Return the newest notifications with this user's read state joined in."""
+        with self._conn() as conn:
+            with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
+                cur.execute(
+                    """
+                    SELECT n.*, (r.user_id IS NOT NULL) AS read
+                    FROM perception_notifications n
+                    LEFT JOIN perception_notification_reads r
+                        ON r.notification_id = n.id AND r.user_id = %s
+                    ORDER BY n.created_at DESC
+                    LIMIT %s
+                    """,
+                    (user_id, limit),
+                )
+                return [_row_to_dict(r) for r in cur.fetchall()]
+
+    def unread_count(self, user_id: str) -> int:
+        """Count notifications with no read receipt for this user."""
+        with self._conn() as conn:
+            with conn.cursor() as cur:
+                cur.execute(
+                    """
+                    SELECT COUNT(*) FROM perception_notifications n
+                    WHERE NOT EXISTS (
+                        SELECT 1 FROM perception_notification_reads r
+                        WHERE r.notification_id = n.id AND r.user_id = %s
+                    )
+                    """,
+                    (user_id,),
+                )
+                return cur.fetchone()[0]
+
+    def mark_all_read(self, user_id: str) -> int:
+        """Insert a read receipt for every notification this user hasn't read."""
+        with self._conn() as conn:
+            with conn.cursor() as cur:
+                cur.execute(
+                    """
+                    INSERT INTO perception_notification_reads (notification_id, user_id)
+                    SELECT n.id, %s FROM perception_notifications n
+                    WHERE NOT EXISTS (
+                        SELECT 1 FROM perception_notification_reads r
+                        WHERE r.notification_id = n.id AND r.user_id = %s
+                    )
+                    ON CONFLICT (notification_id, user_id) DO NOTHING
+                    """,
+                    (user_id, user_id),
+                )
+                marked = cur.rowcount
+            conn.commit()
+        return marked

backend/app/infrastructure/perception/regulation_differ.py

@@ -0,0 +1,224 @@
+"""Deterministic change detection between two versions of a regulation.
+
+This module deliberately contains no LLM call, no network access, and no
+embedding lookup. It exists because the previous implementation decided whether
+a paragraph had changed by comparing embedding cosine similarity against a 0.85
+threshold, which is blind to exactly the edits that matter in regulation.
+Measured against the deployed text-embedding-v3 gateway, tightening a braking
+limit from 30米 to 20米 scores 0.9153 and relaxing 应当 to 宜 scores 0.9162 —
+both far above the threshold, both undetected — while an entirely unrelated
+clause scores 0.6862 and is the only thing that fires. Cosine is scale
+invariant, so it cannot represent a change in magnitude or certainty
+(arXiv:2403.05440, ACM Web Conference 2024); no threshold recovers the signal.
+
+The replacement is the production consensus for legal text: align paragraphs
+with a longest-common-subsequence matcher, run a literal character diff on the
+aligned pairs, and let cheap deterministic rules decide whether a change is
+significant enough to spend an LLM call classifying.
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from dataclasses import dataclass, field
+
+from diff_match_patch import diff_match_patch
+from difflib import SequenceMatcher
+
+from app.config.settings import settings
+
+# Chinese regulatory drafting uses a small, near-unambiguous set of deontic
+# markers, so a regex pre-pass identifies legally significant edits without an
+# LLM. Adding or removing any of these changes what the provision compels.
+_DEONTIC_PATTERN = re.compile(r"应当|须|禁止|不得|可以|允许|宜")
+
+# Matches digit runs including decimals, so "30" -> "20" and "0.85" -> "0.9"
+# are both treated as numeric changes.
+_NUMBER_PATTERN = re.compile(r"\d+(?:\.\d+)?")
+
+# diff_match_patch operation codes.
+_DMP_DELETE = -1
+_DMP_INSERT = 1
+_DMP_EQUAL = 0
+
+
+@dataclass(frozen=True)
+class ParagraphChange:
+    """One detected difference between the old and new version of a regulation.
+
+    `needs_llm` is the gate: it records whether this change is worth the cost of
+    an LLM classification call. The deterministic flags that drive it are kept
+    on the record so downstream code can act on them even when the LLM call
+    fails or is skipped.
+    """
+
+    change_type: str
+    old_text: str
+    new_text: str
+    numeric_changed: bool
+    deontic_changed: bool
+    change_ratio: float
+    needs_llm: bool
+    # (op, text) pairs from diff_match_patch, for rendering a redline view.
+    diff_spans: list[tuple[int, str]] = field(default_factory=list)
+
+
+def _split_paragraphs(text: str) -> list[str]:
+    """Split regulation text into comparable units, dropping blank lines.
+
+    ponytail: newline splitting, not clause parsing. Upgrade to 第X条 / X.X.X
+    segmentation only if paragraph granularity proves too coarse in practice.
+    """
+    return [line.strip() for line in (text or "").split("\n") if line.strip()]
+
+
+def _numbers_differ(old: str, new: str) -> bool:
+    """Report whether the two spans contain a different sequence of numbers."""
+    return _NUMBER_PATTERN.findall(old) != _NUMBER_PATTERN.findall(new)
+
+
+def _deontic_differs(old: str, new: str) -> bool:
+    """Report whether obligation markers were added, removed, or swapped."""
+    return sorted(_DEONTIC_PATTERN.findall(old)) != sorted(_DEONTIC_PATTERN.findall(new))
+
+
+def _is_cosmetic(spans: list[tuple[int, str]]) -> bool:
+    """Report whether the edit touched nothing but punctuation and whitespace.
+
+    A change ratio alone cannot answer this for Chinese regulation text. Clauses
+    run 20-60 characters, so deleting a single 。 is a 4% change and clears any
+    threshold low enough to still catch real edits in longer paragraphs. Testing
+    what actually changed is both cheaper and exact.
+    """
+    changed = "".join(text for op, text in spans if op != _DMP_EQUAL)
+    # Unicode categories P (punctuation), Z (separator) and C (control) cover
+    # Chinese and ASCII punctuation plus every flavour of whitespace.
+    return all(unicodedata.category(char)[0] in {"P", "Z", "C"} for char in changed)
+
+
+class RegulationDiffer:
+    """Align two regulation versions and classify what changed, without an LLM."""
+
+    def __init__(self, min_change_ratio: float | None = None) -> None:
+        """Store the gate threshold, defaulting to the configured value.
+
+        The explicit argument exists so tests never depend on the deployed .env.
+        """
+        self._min_change_ratio = (
+            settings.perception_diff_min_change_ratio
+            if min_change_ratio is None
+            else min_change_ratio
+        )
+        self._dmp = diff_match_patch()
+
+    def diff(self, old_text: str, new_text: str) -> list[ParagraphChange]:
+        """Return every changed paragraph between two versions.
+
+        Unchanged paragraphs are not returned. An empty old version means there
+        is no baseline to compare against — the caller's first crawl — so no
+        changes are reported rather than the whole document being called new.
+        """
+        old_paras = _split_paragraphs(old_text)
+        new_paras = _split_paragraphs(new_text)
+
+        if not old_paras or not new_paras:
+            return []
+
+        # autojunk=False is load-bearing: the default treats any element
+        # appearing in over 1% of a sequence of 200+ items as junk, and
+        # regulations repeat boilerplate paragraphs that alignment depends on
+        # as anchors.
+        matcher = SequenceMatcher(None, old_paras, new_paras, autojunk=False)
+
+        changes: list[ParagraphChange] = []
+        for tag, i1, i2, j1, j2 in matcher.get_opcodes():
+            if tag == "equal":
+                continue
+            if tag == "insert":
+                changes.extend(self._added(p) for p in new_paras[j1:j2])
+            elif tag == "delete":
+                changes.extend(self._removed(p) for p in old_paras[i1:i2])
+            elif tag == "replace":
+                changes.extend(self._replaced(old_paras[i1:i2], new_paras[j1:j2]))
+
+        return changes
+
+    def _added(self, paragraph: str) -> ParagraphChange:
+        """Build a record for a provision present only in the new version."""
+        return ParagraphChange(
+            change_type="added",
+            old_text="",
+            new_text=paragraph,
+            numeric_changed=False,
+            deontic_changed=bool(_DEONTIC_PATTERN.search(paragraph)),
+            change_ratio=1.0,
+            # A new provision always carries new obligations, so it is always
+            # worth classifying.
+            needs_llm=True,
+            diff_spans=[(_DMP_INSERT, paragraph)],
+        )
+
+    def _removed(self, paragraph: str) -> ParagraphChange:
+        """Build a record for a provision dropped from the new version."""
+        return ParagraphChange(
+            change_type="removed",
+            old_text=paragraph,
+            new_text="",
+            numeric_changed=False,
+            deontic_changed=bool(_DEONTIC_PATTERN.search(paragraph)),
+            change_ratio=1.0,
+            needs_llm=True,
+            diff_spans=[(_DMP_DELETE, paragraph)],
+        )
+
+    def _replaced(self, old_block: list[str], new_block: list[str]) -> list[ParagraphChange]:
+        """Compare a run of rewritten paragraphs pairwise, reporting the remainder.
+
+        SequenceMatcher emits `replace` for a whole run at once, and the two
+        sides may differ in length. Pairing by position within the run is safe
+        here because alignment has already established that this run as a whole
+        corresponds; any surplus on either side is a genuine insertion or
+        deletion.
+        """
+        results: list[ParagraphChange] = []
+        for index in range(max(len(old_block), len(new_block))):
+            if index >= len(old_block):
+                results.append(self._added(new_block[index]))
+            elif index >= len(new_block):
+                results.append(self._removed(old_block[index]))
+            else:
+                results.append(self._modified(old_block[index], new_block[index]))
+        return results
+
+    def _modified(self, old: str, new: str) -> ParagraphChange:
+        """Character-diff an aligned pair and decide whether it warrants an LLM call."""
+        spans = self._dmp.diff_main(old, new)
+        # Merges single-character edits into human-meaningful chunks so the
+        # redline view and the change ratio both reflect real edits.
+        self._dmp.diff_cleanupSemantic(spans)
+
+        changed_chars = sum(len(text) for op, text in spans if op != _DMP_EQUAL)
+        denominator = max(len(old), len(new), 1)
+        change_ratio = changed_chars / denominator
+
+        numeric_changed = _numbers_differ(old, new)
+        deontic_changed = _deontic_differs(old, new)
+
+        # A changed limit or obligation marker is always significant no matter
+        # how few characters moved. Everything else must be substantive and
+        # clear the ratio gate to be worth a model call.
+        significant = numeric_changed or deontic_changed or (
+            not _is_cosmetic(spans) and change_ratio >= self._min_change_ratio
+        )
+
+        return ParagraphChange(
+            change_type="modified",
+            old_text=old,
+            new_text=new,
+            numeric_changed=numeric_changed,
+            deontic_changed=deontic_changed,
+            change_ratio=change_ratio,
+            needs_llm=significant,
+            diff_spans=[(op, text) for op, text in spans],
+        )

backend/app/infrastructure/storage/postgres_model_usage_store.py

@@ -0,0 +1,142 @@
+"""Postgres-backed persistence for cumulative AI model usage counters.
+
+Keeps ModelUsageTracker (an in-memory, process-lifetime-only registry defined
+in app/shared/model_usage_tracker.py) from losing its counters on every
+backend restart. This store only ever persists the *current cumulative
+snapshot* per provider+model — not a historical time-series log — matching
+the "durable counters" scope decided in
+docs/superpowers/specs/2026-07-23-status-model-usage-hardening-design.md.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+
+import psycopg2
+import psycopg2.extras
+from psycopg2.pool import ThreadedConnectionPool
+
+from app.config.settings import settings
+from app.shared.model_usage_tracker import ModelUsageEntry
+
+# Table creation follows the same CREATE TABLE IF NOT EXISTS idiom used by
+# every other Postgres store in this codebase — no migration framework.
+_CREATE_TABLE = """
+CREATE TABLE IF NOT EXISTS model_usage_stats (
+    provider          VARCHAR(64)  NOT NULL,
+    model             VARCHAR(128) NOT NULL,
+    total_tokens      BIGINT       NOT NULL DEFAULT 0,
+    prompt_tokens     BIGINT       NOT NULL DEFAULT 0,
+    completion_tokens BIGINT       NOT NULL DEFAULT 0,
+    call_count_ok     BIGINT       NOT NULL DEFAULT 0,
+    call_count_error  BIGINT       NOT NULL DEFAULT 0,
+    last_called_at    TIMESTAMPTZ,
+    last_latency_ms   INTEGER,
+    last_error        TEXT,
+    updated_at        TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
+    PRIMARY KEY (provider, model)
+);
+"""
+
+_UPSERT = """
+INSERT INTO model_usage_stats
+    (provider, model, total_tokens, prompt_tokens, completion_tokens,
+     call_count_ok, call_count_error, last_called_at, last_latency_ms, last_error, updated_at)
+VALUES
+    (%(provider)s, %(model)s, %(total_tokens)s, %(prompt_tokens)s, %(completion_tokens)s,
+     %(call_count_ok)s, %(call_count_error)s, %(last_called_at)s, %(last_latency_ms)s, %(last_error)s, NOW())
+ON CONFLICT (provider, model) DO UPDATE SET
+    total_tokens = EXCLUDED.total_tokens,
+    prompt_tokens = EXCLUDED.prompt_tokens,
+    completion_tokens = EXCLUDED.completion_tokens,
+    call_count_ok = EXCLUDED.call_count_ok,
+    call_count_error = EXCLUDED.call_count_error,
+    last_called_at = EXCLUDED.last_called_at,
+    last_latency_ms = EXCLUDED.last_latency_ms,
+    last_error = EXCLUDED.last_error,
+    updated_at = NOW();
+"""
+
+
+class PostgresModelUsageStore:
+    """Load and flush ModelUsageTracker snapshots to/from a Postgres table."""
+
+    def __init__(self) -> None:
+        """Open a small connection pool and ensure the table exists."""
+        self._pool = ThreadedConnectionPool(
+            minconn=1,
+            maxconn=3,
+            host=settings.postgres_host,
+            port=settings.postgres_port,
+            user=settings.postgres_user,
+            password=settings.postgres_password,
+            dbname=settings.postgres_db,
+        )
+        self._ensure_schema()
+
+    def _ensure_schema(self) -> None:
+        """Create the model_usage_stats table if it does not already exist."""
+        with self._conn() as conn:
+            with conn.cursor() as cur:
+                cur.execute(_CREATE_TABLE)
+            conn.commit()
+
+    @contextmanager
+    def _conn(self):
+        """Borrow a pooled connection and always return it, even on error."""
+        conn = self._pool.getconn()
+        try:
+            yield conn
+        finally:
+            self._pool.putconn(conn)
+
+    def load_all(self) -> dict[str, ModelUsageEntry]:
+        """Return every persisted row as {"provider:model": ModelUsageEntry}."""
+        with self._conn() as conn:
+            with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
+                cur.execute("SELECT * FROM model_usage_stats")
+                rows = cur.fetchall()
+        entries: dict[str, ModelUsageEntry] = {}
+        for row in rows:
+            entry = ModelUsageEntry(
+                provider=row["provider"],
+                model=row["model"],
+                total_tokens=row["total_tokens"],
+                prompt_tokens=row["prompt_tokens"],
+                completion_tokens=row["completion_tokens"],
+                call_count_ok=row["call_count_ok"],
+                call_count_error=row["call_count_error"],
+                last_called_at=row["last_called_at"],
+                last_latency_ms=row["last_latency_ms"],
+                last_error=row["last_error"],
+            )
+            entries[f"{entry.provider}:{entry.model}"] = entry
+        return entries
+
+    def flush(self, entries: dict[str, ModelUsageEntry]) -> None:
+        """Upsert the current cumulative snapshot of every tracked entry.
+
+        A no-op for an empty snapshot — avoids opening a connection for nothing
+        (e.g. before any LLM/embedding/reranker call has happened yet).
+        """
+        if not entries:
+            return
+        with self._conn() as conn:
+            with conn.cursor() as cur:
+                for entry in entries.values():
+                    cur.execute(
+                        _UPSERT,
+                        {
+                            "provider": entry.provider,
+                            "model": entry.model,
+                            "total_tokens": entry.total_tokens,
+                            "prompt_tokens": entry.prompt_tokens,
+                            "completion_tokens": entry.completion_tokens,
+                            "call_count_ok": entry.call_count_ok,
+                            "call_count_error": entry.call_count_error,
+                            "last_called_at": entry.last_called_at,
+                            "last_latency_ms": entry.last_latency_ms,
+                            "last_error": entry.last_error,
+                        },
+                    )
+            conn.commit()

backend/app/infrastructure/tasks/celery_app.py

@@ -28,7 +28,10 @@ celery_app = Celery(
     "compliance_hub",
     broker=_BROKER,
     backend=_BACKEND,
-    include=["app.infrastructure.tasks.document_tasks"],
+    include=[
+        "app.infrastructure.tasks.document_tasks",
+        "app.infrastructure.tasks.perception_tasks",
+    ],
 )
 
 celery_app.conf.update(
@@ -42,4 +45,12 @@ celery_app.conf.update(
     task_reject_on_worker_lost=True,
     # Keep results for 1 hour for status polling.
     result_expires=3600,
+    # Scheduled counterpart to the Perception page's manual "Refresh" button.
+    # Only takes effect while a Beat process is running (./dev.sh start beat).
+    beat_schedule={
+        "crawl-regulations-periodic": {
+            "task": "app.infrastructure.tasks.perception_tasks.crawl_regulations_task",
+            "schedule": settings.perception_crawl_interval_seconds,
+        },
+    },
 )

backend/app/infrastructure/tasks/perception_tasks.py

@@ -0,0 +1,63 @@
+"""Celery task for scheduled regulatory source crawling.
+
+This is the scheduled counterpart to the Perception page's manual "Refresh"
+button (POST /perception/crawl). Every architecture reference document
+describes source monitoring as continuous ("定时爬取"), not operator-triggered,
+so this task is what Celery Beat runs on a fixed interval once an operator
+starts a Beat process.
+"""
+
+from __future__ import annotations
+
+from loguru import logger
+
+from app.infrastructure.tasks.celery_app import celery_app
+
+
+@celery_app.task(
+    name="app.infrastructure.tasks.perception_tasks.crawl_regulations_task",
+    bind=True,
+)
+def crawl_regulations_task(self) -> dict:
+    """Crawl every registered regulatory source and enrich new/changed events.
+
+    Drains CrawlService.run_crawl(), which already isolates each source's
+    fetch and each event's enrichment behind its own try/except — a source
+    outage or a single bad event yields an "error" progress item and the
+    generator continues. Re-catching those here would only hide problems the
+    service has already handled, so this task's job is limited to counting
+    them and logging a summary.
+
+    No automatic retry is configured. An exception escaping run_crawl itself
+    means something broke in a way the service's own error handling did not
+    anticipate; the next scheduled tick already provides a retry within
+    settings.perception_crawl_interval_seconds, so an immediate retry against
+    the same failure is not worth the added complexity.
+
+    ponytail: relies on a single worker process to serialize scheduled runs
+    (Celery's default concurrency processes one task at a time, so a run that
+    outlasts the interval delays the next tick rather than overlapping it).
+    Add a Redis-based lock (e.g. SETNX on a per-task key) if this queue is
+    ever served by more than one worker.
+    """
+    from app.shared.bootstrap import get_crawl_service
+
+    error_count = 0
+    new_count = 0
+    updated_count = 0
+
+    for item in get_crawl_service().run_crawl():
+        event = item.get("event")
+        if event == "error":
+            error_count += 1
+            logger.warning("Scheduled crawl source error: {}", item.get("data"))
+        elif event == "done":
+            data = item.get("data") or {}
+            new_count = data.get("total_new", 0)
+            updated_count = data.get("total_updated", 0)
+
+    logger.info(
+        "Scheduled crawl finished: new={} updated={} source_errors={}",
+        new_count, updated_count, error_count,
+    )
+    return {"new": new_count, "updated": updated_count, "source_errors": error_count}

backend/app/mcp/__init__.py

@@ -0,0 +1,8 @@
+"""MCP (Model Context Protocol) server module.
+
+Exposes selected read-only platform capabilities — currently only regulation
+search — as MCP tools so external MCP clients (Claude Desktop, GitHub Copilot,
+Cursor, etc.) can query this platform's compliance knowledge base directly.
+"""
+# Kept deliberately empty beyond this docstring — see server.py for the
+# actual FastMCP instance and tool/middleware definitions.

backend/app/mcp/server.py

@@ -0,0 +1,201 @@
+"""MCPServer instance exposing the compliance knowledge base as an MCP tool.
+
+This module is a pure protocol adapter: search_regulations() below calls the
+existing AgentConversationService.ask() (the same application service backing
+the /api/v1/agent/ask REST endpoint) and reshapes its result into a plain
+dict. No new retrieval, ranking, or LLM orchestration logic lives here.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Annotated
+
+from mcp.server import MCPServer
+from mcp.server.transport_security import TransportSecuritySettings
+from pydantic import Field
+from starlette.responses import PlainTextResponse
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from app.config.settings import settings
+from app.mcp.stats import get_mcp_stats_tracker
+from app.shared.bootstrap import get_agent_conversation_service, get_jwt_handler
+
+logger = logging.getLogger(__name__)
+
+# Single shared MCPServer instance — analogous to the single shared FastAPI
+# `app` instance in app/api/main.py. Tools registered via @mcp.tool() below.
+# Note: the installed mcp SDK (2.0.0) renamed the older "FastMCP" class to
+# "MCPServer" (mcp.server.mcpserver.MCPServer); the .tool()/.streamable_http_app()
+# API surface used here is unchanged across that rename.
+mcp = MCPServer("ai-regulations")
+
+
+@mcp.tool()
+def search_regulations(
+    query: Annotated[str, Field(min_length=1, max_length=2000)],
+    top_k: Annotated[int, Field(ge=1, le=20)] = 5,
+) -> dict:
+    """Search the compliance knowledge base and return a grounded answer.
+
+    query: Natural-language search question, e.g. "国六排放标准最新要求".
+    top_k: Maximum number of cited sources to return (1-20, default 5).
+    """
+    # Bounds mirror AskRequest in app/api/models/agent.py so the MCP path cannot
+    # be used to bypass the REST endpoint's limits. They matter more here than
+    # there: KnowledgeRetrievalService amplifies top_k (candidate_k = top_k * 4)
+    # when reranking, and an LLM client can easily hallucinate a huge value.
+    # Declaring them via Annotated puts them in the advertised JSON schema too,
+    # so well-behaved clients never send an out-of-range value in the first place.
+    #
+    # No session_id is passed: this keeps each call stateless (no
+    # ConversationStore reads/writes), matching "search" semantics rather
+    # than multi-turn chat semantics.
+    started = time.perf_counter()
+    try:
+        _, result = get_agent_conversation_service().ask(query=query, top_k=top_k)
+    except Exception:
+        # Record the failure, then re-raise unchanged so the MCP SDK still
+        # converts it into a protocol-level error for the client. Swallowing
+        # it here would report success to the caller.
+        get_mcp_stats_tracker().record(
+            tool="search_regulations",
+            duration_ms=(time.perf_counter() - started) * 1000,
+            success=False,
+        )
+        raise
+    get_mcp_stats_tracker().record(
+        tool="search_regulations",
+        duration_ms=(time.perf_counter() - started) * 1000,
+        success=True,
+    )
+    return {
+        "answer": result.answer,
+        "sources": [source.__dict__ for source in result.sources],
+    }
+
+
+class MCPAuthMiddleware:
+    """Reject unauthenticated requests before they reach the MCP protocol handler.
+
+    Mirrors the existing get_current_user dependency's behavior (auth.py) but
+    implemented as raw ASGI middleware, since the mounted MCP app is a plain
+    ASGI app, not a FastAPI/APIRouter instance that supports Depends().
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        """Store the wrapped ASGI app to delegate to once auth passes."""
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """Validate the bearer token for HTTP requests; pass non-HTTP scopes through."""
+        # Only HTTP requests carry an Authorization header to check; lifespan
+        # and other scope types must always pass through untouched.
+        if scope["type"] != "http" or not settings.auth_enabled:
+            await self.app(scope, receive, send)
+            return
+
+        headers = dict(scope["headers"])
+        # ASGI header values are raw bytes specified as latin-1, not UTF-8;
+        # decoding strictly as UTF-8 would raise on a malformed byte and turn a
+        # bad request into an unhandled 500.
+        auth_header = headers.get(b"authorization", b"").decode("latin-1")
+        token = auth_header.removeprefix("Bearer ").strip()
+        try:
+            get_jwt_handler().decode_token(token)
+        except ValueError as exc:
+            # Reject before the MCP session/protocol layer ever sees the request.
+            # WWW-Authenticate matches the get_current_user dependency (auth.py)
+            # and is required by RFC 7235 so clients can tell "needs credentials"
+            # apart from a generic failure.
+            response = PlainTextResponse(
+                str(exc), status_code=401, headers={"WWW-Authenticate": "Bearer"}
+            )
+            await response(scope, receive, send)
+            return
+
+        await self.app(scope, receive, send)
+
+
+def _parse_allowed_hosts() -> list[str]:
+    """Split the configured MCP host allow-list into individual entries."""
+    # Shared by the transport-security builder and the status endpoint so the
+    # panel can never display an allow-list different from the enforced one.
+    return [h.strip() for h in settings.mcp_allowed_hosts.split(",") if h.strip()]
+
+
+def _build_transport_security() -> TransportSecuritySettings:
+    """Translate the configured MCP host allow-list into SDK transport settings.
+
+    Without this the SDK infers its own allow-list from the bind host, which
+    defaults to 127.0.0.1 and therefore rejects every remote client with HTTP
+    421 — fatal for a remotely deployed backend.
+    """
+    allowed = _parse_allowed_hosts()
+    if "*" in allowed:
+        # Explicit, logged opt-out. Kept as an escape hatch for environments
+        # behind a proxy that rewrites Host unpredictably, but never the default.
+        logger.warning(
+            "MCP DNS-rebinding protection is disabled (mcp_allowed_hosts='*'). "
+            "Set MCP_ALLOWED_HOSTS to the real deployment host(s) instead."
+        )
+        return TransportSecuritySettings(enable_dns_rebinding_protection=False)
+    return TransportSecuritySettings(
+        enable_dns_rebinding_protection=True,
+        allowed_hosts=allowed,
+        # Browser clients send Origin; reuse the already-maintained CORS list so
+        # there is one place to declare trusted web origins. Non-browser MCP
+        # clients send no Origin at all, which the SDK treats as allowed.
+        allowed_origins=[o.strip() for o in settings.cors_allow_origins.split(",") if o.strip()],
+    )
+
+
+def build_mcp_asgi_app() -> ASGIApp:
+    """Return the Streamable HTTP ASGI app for the MCP server, auth-guarded.
+
+    streamable_http_path="/" is required here: MCPServer.streamable_http_app()
+    registers its own internal route at "/mcp" by default, and this app is
+    itself mounted at "/mcp" in api/main.py — without overriding the internal
+    path to "/", the effective external path would be the confusing "/mcp/mcp"
+    instead of "/mcp".
+    """
+    asgi_app = mcp.streamable_http_app(
+        streamable_http_path="/",
+        transport_security=_build_transport_security(),
+    )
+    asgi_app.add_middleware(MCPAuthMiddleware)
+    return asgi_app
+
+
+async def get_mcp_status(public_url: str) -> dict:
+    """Assemble the MCP status payload shown on the System Status page.
+
+    Owned by this module rather than the status route so that MCP internals
+    (the tool registry, the allow-list format, the stats tracker) stay behind
+    one boundary; the route only supplies public_url, which is the one value
+    only the HTTP layer can know.
+    """
+    stats = get_mcp_stats_tracker().snapshot()
+    # list_tools() reads the in-memory registry populated by @mcp.tool() at
+    # import time, so the panel always reflects what is actually advertised
+    # rather than a hand-maintained duplicate list.
+    tools = await mcp.list_tools()
+    return {
+        "endpoint_url": public_url,
+        "auth_required": settings.auth_enabled,
+        "allowed_hosts": _parse_allowed_hosts(),
+        "tools": [
+            {
+                "name": tool.name,
+                "description": (tool.description or "").strip().split("\n")[0],
+                "calls": entry.calls if entry else 0,
+                "errors": entry.errors if entry else 0,
+                "avg_duration_ms": entry.avg_duration_ms if entry else None,
+                "last_called_at": (
+                    entry.last_called_at.isoformat() if entry and entry.last_called_at else None
+                ),
+            }
+            for tool, entry in ((tool, stats.get(tool.name)) for tool in tools)
+        ],
+    }

backend/app/mcp/stats.py

@@ -0,0 +1,91 @@
+"""In-memory per-tool call counters for the MCP server.
+
+Lives in `app/mcp/` rather than `app/shared/` because these counters are
+meaningful only for the MCP transport: they answer "is anything actually
+calling our MCP endpoint, and does it work?" for the System Status page.
+Token consumption is deliberately not tracked here — MCP tool calls route
+through AgentConversationService.ask() like every other caller, so the
+existing ModelUsageTracker already accounts for it.
+
+Counters are process-local and reset on restart. That is an accepted
+tradeoff, recorded in the design spec: nothing billable depends on them.
+"""
+
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from functools import lru_cache
+
+from loguru import logger
+
+
+@dataclass
+class MCPToolStats:
+    """Accumulated call outcomes for a single MCP tool."""
+
+    calls: int = 0
+    errors: int = 0
+    total_duration_ms: float = 0.0
+    last_called_at: datetime | None = None
+
+    @property
+    def avg_duration_ms(self) -> float | None:
+        """Mean call duration, or None when the tool has never been called.
+
+        Returning None rather than 0.0 keeps "never called" distinguishable
+        from "called, but instantaneous" in the status UI.
+        """
+        if self.calls == 0:
+            return None
+        return self.total_duration_ms / self.calls
+
+
+class MCPStatsTracker:
+    """Thread-safe registry of per-tool MCP call statistics.
+
+    The lock is load-bearing, not defensive habit: the mcp SDK dispatches
+    synchronous tool functions through anyio.to_thread.run_sync, so tool
+    bodies genuinely run on multiple worker threads at once — unlike the
+    async REST routes, which are serialized by the event loop.
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty registry guarded by a single lock."""
+        self._tools: dict[str, MCPToolStats] = {}
+        # One coarse lock is enough: record() runs once per MCP tool call and
+        # snapshot() is only read by the low-traffic status endpoint.
+        self._lock = threading.Lock()
+
+    def record(self, *, tool: str, duration_ms: float, success: bool) -> None:
+        """Record the outcome of one MCP tool invocation.
+
+        Never raises: a defect in observability code must not turn a working
+        tool call into a protocol error for the client.
+        """
+        try:
+            # Coerce outside the lock so a bad argument cannot abort mid-update
+            # and leave calls incremented but duration unaccounted for.
+            duration = float(duration_ms)
+            now = datetime.now(timezone.utc)
+            with self._lock:
+                stats = self._tools.setdefault(tool, MCPToolStats())
+                stats.calls += 1
+                if not success:
+                    stats.errors += 1
+                stats.total_duration_ms += duration
+                stats.last_called_at = now
+        except Exception as exc:  # noqa: BLE001 - tracking must never break a real call
+            logger.warning("MCPStatsTracker.record failed for tool {} - {}", tool, exc)
+
+    def snapshot(self) -> dict[str, MCPToolStats]:
+        """Return a shallow copy of all tracked tools, safe to read outside the lock."""
+        with self._lock:
+            return dict(self._tools)
+
+
+@lru_cache
+def get_mcp_stats_tracker() -> MCPStatsTracker:
+    """Return the process-wide singleton tracker (mirrors get_model_usage_tracker())."""
+    return MCPStatsTracker()

backend/app/services/llm/deepseek_client.py

@@ -5,7 +5,7 @@ from the model response so that callers can dispatch tool invocations.
 """
 
 import time
-from typing import List, Dict, Optional
+from typing import List, Dict, Optional, Generator
 from loguru import logger
 import httpx
 
@@ -130,8 +130,14 @@ class DeepSeekClient(BaseLLMClient):
         max_tokens: Optional[int] = None,
         temperature: Optional[float] = None,
         **kwargs
-    ):
+    ) -> Generator[str, None, Optional[Dict[str, int]]]:
-        """Stream chat for the Deep Seek Client instance."""
+        """Stream chat for the Deep Seek Client instance.
+
+        Returns the trailing token-usage dict as the generator's return value
+        (read via StopIteration.value when manually driven with next()) when
+        the gateway sends one via stream_options.include_usage, else None.
+        """
+        usage: Optional[Dict[str, int]] = None
         try:
             payload = {
                 "model": self.config.model,
@@ -139,7 +145,8 @@ class DeepSeekClient(BaseLLMClient):
                 "max_tokens": max_tokens or self.config.max_tokens,
                 "temperature": temperature or self.config.temperature,
                 "top_p": kwargs.get("top_p", self.config.top_p),
-                "stream": True
+                "stream": True,
+                "stream_options": {"include_usage": True}
             }
 
             with self._client.stream("POST", "/chat/completions", json=payload) as response:
@@ -168,6 +175,9 @@ class DeepSeekClient(BaseLLMClient):
                             content = delta.get("content", "")
                             if content:
                                 yield content
+                        elif data.get("usage"):
+                            # Trailing usage-only chunk — no content to yield, just capture it.
+                            usage = data["usage"]
                     except json.JSONDecodeError:
                         continue
 
@@ -178,6 +188,8 @@ class DeepSeekClient(BaseLLMClient):
             logger.error(f"DeepSeek Stream调用失败: {e}")
             yield ""
 
+        return usage
+
     def get_available_models(self) -> List[str]:
         """Return available models for the Deep Seek Client instance."""
         return self.SUPPORTED_MODELS

backend/app/services/llm/llm_factory.py

@@ -16,7 +16,7 @@ from app.shared.model_usage_tracker import get_model_usage_tracker
 # Keep provider-specific behavior explicit so debugging stays straightforward.
 DEFAULT_MODELS = {
     LLMProvider.DEEPSEEK: "deepseek-v4-flash",
-    LLMProvider.QWEN: "qwen3.5-flash",
+    LLMProvider.QWEN: "qwen3.6-flash",
     LLMProvider.QWEN_VL: "qwen3-vl-plus"
 }
 
@@ -101,6 +101,8 @@ class LLMFactory:
             "qwen-max": LLMProvider.QWEN,
             "qwen3.5-flash": LLMProvider.QWEN,
             "qwen3.5-plus": LLMProvider.QWEN,
+            "qwen3.6-flash": LLMProvider.QWEN,
+            "qwen3.6-plus": LLMProvider.QWEN,
             "qwen_vl": LLMProvider.QWEN_VL,
             "qwen-vl": LLMProvider.QWEN_VL,
             "qwen-vl-plus": LLMProvider.QWEN_VL,

backend/app/services/llm/qwen_client.py

@@ -27,6 +27,8 @@ class QwenClient(BaseLLMClient):
         "qwen-long",
         "qwen3.5-flash",
         "qwen3.5-plus",
+        "qwen3.6-flash",
+        "qwen3.6-plus",
         "qwen3-plus",
         "qwen2.5-72b-instruct",
         "qwen2.5-32b-instruct",
@@ -140,8 +142,14 @@ class QwenClient(BaseLLMClient):
         max_tokens: Optional[int] = None,
         temperature: Optional[float] = None,
         **kwargs
-    ) -> Generator[str, None, None]:
+    ) -> Generator[str, None, Optional[Dict[str, int]]]:
-        """Stream chat for the Qwen Client instance."""
+        """Stream chat for the Qwen Client instance.
+
+        Returns the trailing token-usage dict as the generator's return value
+        (read via StopIteration.value when manually driven with next()) when
+        the gateway sends one via stream_options.include_usage, else None.
+        """
+        usage: Optional[Dict[str, int]] = None
         try:
             # Keep provider-specific behavior explicit so debugging stays straightforward.
             payload = {
@@ -150,7 +158,8 @@ class QwenClient(BaseLLMClient):
                 "max_tokens": max_tokens or self.config.max_tokens,
                 "temperature": temperature or self.config.temperature,
                 "top_p": kwargs.get("top_p", self.config.top_p),
-                "stream": True  # Keep provider-specific behavior explicit so debugging stays straightforward.
+                "stream": True,  # Keep provider-specific behavior explicit so debugging stays straightforward.
+                "stream_options": {"include_usage": True}
             }
 
             # Keep provider-specific behavior explicit so debugging stays straightforward.
@@ -167,6 +176,9 @@ class QwenClient(BaseLLMClient):
                                 data = json.loads(data_str)
                                 choices = data.get("choices", [])
                                 if not choices:
+                                    if data.get("usage"):
+                                        # Trailing usage-only chunk — capture it, nothing to yield.
+                                        usage = data["usage"]
                                     continue  # Keep provider-specific behavior explicit so debugging stays straightforward.
                                 delta = choices[0].get("delta", {})
                                 content = delta.get("content", "")
@@ -183,6 +195,8 @@ class QwenClient(BaseLLMClient):
             logger.error(f"Qwen流式调用失败: {e}")
             yield f"[ERROR: {str(e)}]"
 
+        return usage
+
     async def async_stream_chat(
         self,
         messages: List[Dict[str, str]],
@@ -299,8 +313,14 @@ class QwenVLClient(BaseLLMClient):
         max_tokens: Optional[int] = None,
         temperature: Optional[float] = None,
         **kwargs
-    ) -> Generator[str, None, None]:
+    ) -> Generator[str, None, Optional[Dict[str, int]]]:
-        """Stream chat for the Qwen V L Client instance."""
+        """Stream chat for the Qwen V L Client instance.
+
+        Returns the trailing token-usage dict as the generator's return value
+        (read via StopIteration.value when manually driven with next()) when
+        the gateway sends one via stream_options.include_usage, else None.
+        """
+        usage: Optional[Dict[str, int]] = None
         try:
             payload = {
                 "model": self.config.model,
@@ -308,7 +328,8 @@ class QwenVLClient(BaseLLMClient):
                 "max_tokens": max_tokens or self.config.max_tokens,
                 "temperature": temperature or self.config.temperature,
                 "top_p": kwargs.get("top_p", self.config.top_p),
-                "stream": True
+                "stream": True,
+                "stream_options": {"include_usage": True}
             }
 
             with self._client.stream("POST", "/chat/completions", json=payload) as response:
@@ -323,6 +344,9 @@ class QwenVLClient(BaseLLMClient):
                                 data = json.loads(data_str)
                                 choices = data.get("choices", [])
                                 if not choices:
+                                    if data.get("usage"):
+                                        # Trailing usage-only chunk — capture it, nothing to yield.
+                                        usage = data["usage"]
                                     continue  # Keep provider-specific behavior explicit so debugging stays straightforward.
                                 delta = choices[0].get("delta", {})
                                 content = delta.get("content", "")
@@ -335,6 +359,8 @@ class QwenVLClient(BaseLLMClient):
             logger.error(f"QwenVL流式调用失败: {e}")
             yield f"[ERROR: {str(e)}]"
 
+        return usage
+
     def get_available_models(self) -> List[str]:
         """Return available models for the Qwen V L Client instance."""
         return self.SUPPORTED_MODELS
@@ -347,7 +373,7 @@ class QwenVLClient(BaseLLMClient):
 
 def create_qwen_client(
     api_key: str,
-    model: str = "qwen3.5-flash",
+    model: str = "qwen3.6-flash",
     base_url: str = "http://6.86.80.4:30080/v1",
     **kwargs
 ) -> QwenClient:

backend/app/services/llm/tracked_client.py

@@ -56,18 +56,24 @@ class TrackedLLMClient:
         return response
 
     def stream_chat(self, messages: List[Dict[str, str]], *args: Any, **kwargs: Any):
-        """Delegate to the wrapped client's stream_chat(), recording call outcome only.
+        """Delegate to the wrapped client's stream_chat(), recording call outcome and usage.
 
-        Token usage is NOT recorded here: none of the current provider
+        Drives the inner generator manually (instead of a plain `for` loop) so
-        stream_chat() implementations parse a trailing usage chunk from the
+        it can capture the generator's return value via StopIteration.value —
-        gateway (see the design doc's Known Limitations), so accumulating a
+        the trailing token-usage dict the inner client captures from a
-        token count here would silently be wrong. Only call success/failure
+        stream_options.include_usage chunk, if the gateway sent one.
-        and latency are tracked for streaming calls.
         """
         start = time.time()
         error: Optional[str] = None
+        usage: Optional[Dict[str, int]] = None
+        gen = self._inner.stream_chat(messages, *args, **kwargs)
         try:
-            for chunk in self._inner.stream_chat(messages, *args, **kwargs):
+            while True:
+                try:
+                    chunk = next(gen)
+                except StopIteration as stop:
+                    usage = stop.value
+                    break
                 yield chunk
         except Exception as exc:  # noqa: BLE001 - report, then re-raise unchanged
             error = str(exc)
@@ -77,6 +83,7 @@ class TrackedLLMClient:
                 provider=self._inner.config.provider.value,
                 model=self._inner.config.model,
                 success=error is None,
+                usage=usage,
                 latency_ms=int((time.time() - start) * 1000),
                 error=error,
             )

backend/app/shared/bootstrap.py

@@ -2,9 +2,12 @@
 
 from __future__ import annotations
 
+import asyncio
 from functools import lru_cache
 from typing import Callable
 
+from loguru import logger
+
 from app.application.agent import AgentConversationService, AgentSessionService
 from app.application.agent.agentic_service import AgenticConversationService
 from app.application.documents import DocumentCommandService, DocumentQueryService
@@ -20,8 +23,10 @@ from app.infrastructure.parser.local_chunk_builder import LocalRegulationChunkBu
 from app.infrastructure.parser.local_document_parser import LocalDocumentParser
 from app.infrastructure.parser.vector_chunk_builder import AliyunVectorChunkBuilder
 from app.infrastructure.perception.mock_event_store import MockEventStore
+from app.infrastructure.perception.mock_notification_store import MockNotificationStore
 from app.application.perception.crawl_service import CrawlService
 from app.infrastructure.perception.base_event_store import BaseEventStore
+from app.infrastructure.perception.base_notification_store import BaseNotificationStore
 from app.infrastructure.perception.crawlers.catarc_crawler import CatarcCrawler
 from app.infrastructure.perception.crawlers.guobiao_crawler import (
     GuobiaoMandatoryCrawler,
@@ -36,6 +41,7 @@ from app.infrastructure.storage.minio_binary_store import MinioDocumentBinarySto
 from app.infrastructure.storage.postgres_document_processing_store import PostgresDocumentProcessingStore
 from app.infrastructure.storage.postgres_document_repository import PostgresDocumentRepository
 from app.infrastructure.storage.postgres_parse_artifact_store import PostgresParseArtifactStore
+from app.infrastructure.storage.postgres_model_usage_store import PostgresModelUsageStore
 from app.infrastructure.vectorstore.bm25_retriever import BM25Retriever
 from app.infrastructure.vectorstore.cross_encoder_reranker import OpenAICompatibleReranker
 from app.infrastructure.vectorstore.dense_retriever import DenseRetriever
@@ -43,6 +49,7 @@ from app.infrastructure.vectorstore.milvus_vector_index import MilvusVectorIndex
 from app.services.llm.llm_factory import LLMFactory
 from app.domain.compliance.ports import ComplianceRepository
 from app.infrastructure.compliance.repository import PostgresComplianceRepository
+from app.shared.model_usage_tracker import get_model_usage_tracker
 # Keep shared wiring centralized so dependency construction remains consistent.
 
 
@@ -162,6 +169,14 @@ def get_parse_artifact_store():
     return None
 
 
+@lru_cache
+def get_model_usage_store():
+    """Return the Postgres model-usage store, or None when postgres backend is not enabled."""
+    if settings.document_repository_backend == "postgres":
+        return PostgresModelUsageStore()
+    return None
+
+
 @lru_cache
 def get_document_processing_store():
     """Return document processing store for the active repository backend."""
@@ -314,6 +329,22 @@ def get_event_store() -> BaseEventStore:
     return MockEventStore()
 
 
+@lru_cache
+def get_notification_store() -> BaseNotificationStore:
+    """Return notification store selected by DOCUMENT_REPOSITORY_BACKEND setting.
+
+    Mirrors get_event_store()'s gate: Mock in-memory when Postgres isn't
+    configured, so the feature works in local dev and tests without a
+    database.
+    """
+    if settings.document_repository_backend == "postgres":
+        from app.infrastructure.perception.postgres_notification_store import (
+            PostgresNotificationStore,
+        )
+        return PostgresNotificationStore()
+    return MockNotificationStore()
+
+
 @lru_cache
 def get_compliance_repository() -> ComplianceRepository:
     """Return the compliance analysis repository.
@@ -357,6 +388,9 @@ def get_crawl_service() -> CrawlService:
         event_store=get_event_store(),
         llm_pipeline=LlmPipeline(),
         retrieval_service=get_retrieval_service(),
+        notification_store=get_notification_store(),
+        embedding_provider=get_embedding_provider(),
+        vector_index=get_vector_index(),
     )
 
 
@@ -412,8 +446,67 @@ def get_user_store():
 def preload_runtime_dependencies() -> None:
     """Warm dependencies that are safe and useful to preload during startup."""
     LLMFactory.preload_clients(["qwen", "deepseek"])
+    _start_model_usage_persistence()
 
 
 def cleanup_runtime_dependencies() -> None:
     """Release runtime dependencies that expose explicit cleanup hooks."""
     LLMFactory.cleanup()
+    _stop_model_usage_persistence()
+
+
+_model_usage_flush_task: "asyncio.Task | None" = None
+
+
+def _start_model_usage_persistence() -> None:
+    """Seed ModelUsageTracker from Postgres and start its periodic flush loop.
+
+    No-op when document_repository_backend != "postgres" — ModelUsageTracker
+    then keeps behaving exactly as it always has: purely in-memory, reset on
+    every restart. Never raises: persistence must not block app startup.
+    """
+    global _model_usage_flush_task
+    try:
+        store = get_model_usage_store()
+    except Exception as exc:  # noqa: BLE001 - persistence must never block startup
+        logger.warning("Failed to initialize model usage persistence: {}", exc)
+        return
+    if store is None:
+        return
+
+    tracker = get_model_usage_tracker()
+    try:
+        tracker.seed(store.load_all())
+    except Exception as exc:  # noqa: BLE001 - a bad load must not block startup
+        logger.warning("Failed to load persisted model usage stats: {}", exc)
+
+    async def _flush_loop() -> None:
+        """Snapshot the tracker into Postgres every 60 seconds until cancelled."""
+        while True:
+            await asyncio.sleep(60)
+            try:
+                await asyncio.to_thread(store.flush, tracker.snapshot())
+            except Exception as exc:  # noqa: BLE001 - one bad cycle must not kill the loop
+                logger.warning("Failed to flush model usage stats: {}", exc)
+
+    _model_usage_flush_task = asyncio.create_task(_flush_loop())
+
+
+def _stop_model_usage_persistence() -> None:
+    """Cancel the periodic flush task and perform one best-effort final flush."""
+    global _model_usage_flush_task
+    if _model_usage_flush_task is not None:
+        _model_usage_flush_task.cancel()
+        _model_usage_flush_task = None
+
+    try:
+        store = get_model_usage_store()
+    except Exception as exc:  # noqa: BLE001 - shutdown must not crash on this
+        logger.warning("Failed to access model usage store during shutdown: {}", exc)
+        return
+    if store is None:
+        return
+    try:
+        store.flush(get_model_usage_tracker().snapshot())
+    except Exception as exc:  # noqa: BLE001 - shutdown must not crash on a flush failure
+        logger.warning("Failed final model usage flush: {}", exc)

backend/app/shared/model_usage_tracker.py

@@ -97,6 +97,16 @@ class ModelUsageTracker:
         except Exception as exc:  # noqa: BLE001 - tracking must never break a real call
             logger.warning("ModelUsageTracker.record failed for {}:{} - {}", provider, model, exc)
 
+    def seed(self, entries: dict[str, ModelUsageEntry]) -> None:
+        """Bulk-load persisted entries (called once at startup, before any traffic).
+
+        Unlike record(), this replaces entries wholesale rather than
+        accumulating deltas — it exists to restore counters saved by a
+        previous process run, not to record a new call.
+        """
+        with self._lock:
+            self._entries.update(entries)
+
     def snapshot(self) -> dict[str, ModelUsageEntry]:
         """Return a shallow copy of all tracked entries, safe to mutate by the caller."""
         with self._lock:

backend/requirements.txt

@@ -2,6 +2,10 @@
 fastapi>=0.110.0
 uvicorn[standard]>=0.27.0
 python-multipart>=0.0.9
+# MCP server module (backend/app/mcp/) — pin >=2.0.0: that release renamed the
+# older "FastMCP" class to "MCPServer" (mcp.server.MCPServer), which is the
+# class actually used in app/mcp/server.py.
+mcp>=2.0.0
 
 # ── Config & utilities ────────────────────────────────────────────────────────
 pydantic>=2.0.0
@@ -13,6 +17,11 @@ beautifulsoup4>=4.12.0
 lxml>=5.0.0
 tiktoken>=0.5.0
 tenacity>=8.2.0
+# Regulatory signal crawling (backend/app/infrastructure/perception/) — main-content
+# extraction from crawled regulation detail pages and character-level diff for change
+# detection. Import name for diff-match-patch is diff_match_patch (underscored).
+trafilatura>=2.0.0
+diff-match-patch>=20241021
 
 # ── Auth ──────────────────────────────────────────────────────────────────────
 python-jose[cryptography]>=3.3.0

backend/tests/conftest.py

@@ -0,0 +1,27 @@
+"""Shared pytest fixtures and import-time guards for the backend test suite.
+
+pytest imports this file before any test module beneath backend/tests/, which
+makes it the only reliable place to install import-time guards: individual test
+modules cannot guarantee they run first, because collection order follows
+directory names.
+"""
+
+from __future__ import annotations
+
+import sys
+from unittest.mock import MagicMock
+
+# app/shared/bootstrap.py (the composition root) eagerly imports the Postgres
+# store modules, which do `import psycopg2` at their own module scope and later
+# open a real connection pool. Any test that transitively imports bootstrap
+# would therefore bind the real driver and attempt a live TCP connection to the
+# configured production database, surfacing as a multi-second timeout rather
+# than an obvious error. Binding mocks here — before the first test module is
+# imported — makes that impossible regardless of collection order.
+# setdefault (not assignment) keeps a real psycopg2 in place if something has
+# already imported it deliberately.
+_mock_psycopg2 = MagicMock()
+_mock_psycopg2.extras = MagicMock()
+sys.modules.setdefault("psycopg2", _mock_psycopg2)
+sys.modules.setdefault("psycopg2.extras", _mock_psycopg2.extras)
+sys.modules.setdefault("psycopg2.pool", MagicMock())

backend/tests/mcp/__init__.py

@@ -0,0 +1,2 @@
+"""Test package for the MCP module (backend/app/mcp/)."""
+# Empty package marker — no shared fixtures needed yet for this small test suite.

backend/tests/mcp/test_mcp_auth_middleware.py

@@ -0,0 +1,93 @@
+"""Unit tests for MCPAuthMiddleware.
+
+Wraps a minimal dummy ASGI app (not the real MCP app) so these tests exercise
+only the auth gate, not the MCP protocol itself — keeps the test fast and
+independent of FastMCP internals.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+from starlette.applications import Starlette
+from starlette.responses import PlainTextResponse
+from starlette.routing import Route
+from starlette.testclient import TestClient
+
+from app.mcp.server import MCPAuthMiddleware
+
+
+def _dummy_app() -> Starlette:
+    """Build a minimal Starlette app that MCPAuthMiddleware can wrap."""
+    async def _ok(request):
+        """Return a fixed 200 response so tests can assert pass-through."""
+        return PlainTextResponse("ok")
+
+    app = Starlette(routes=[Route("/ping", _ok)])
+    app.add_middleware(MCPAuthMiddleware)
+    return app
+
+
+def test_missing_token_rejected_when_auth_enabled():
+    """No Authorization header + auth_enabled=True -> 401."""
+    with patch("app.mcp.server.settings") as fake_settings:
+        fake_settings.auth_enabled = True
+        client = TestClient(_dummy_app())
+        response = client.get("/ping")
+    assert response.status_code == 401
+
+
+def test_invalid_token_rejected_when_auth_enabled():
+    """A token that fails decode_token() -> 401, request never reaches the app."""
+    fake_handler = type("H", (), {"decode_token": lambda self, t: (_ for _ in ()).throw(ValueError("bad token"))})()
+    with patch("app.mcp.server.settings") as fake_settings, \
+         patch("app.mcp.server.get_jwt_handler", return_value=fake_handler):
+        fake_settings.auth_enabled = True
+        client = TestClient(_dummy_app())
+        response = client.get("/ping", headers={"Authorization": "Bearer garbage"})
+    assert response.status_code == 401
+
+
+def test_valid_token_passes_through_when_auth_enabled():
+    """A token that decodes successfully -> request reaches the wrapped app."""
+    fake_handler = type("H", (), {"decode_token": lambda self, t: object()})()
+    with patch("app.mcp.server.settings") as fake_settings, \
+         patch("app.mcp.server.get_jwt_handler", return_value=fake_handler):
+        fake_settings.auth_enabled = True
+        client = TestClient(_dummy_app())
+        response = client.get("/ping", headers={"Authorization": "Bearer good"})
+    assert response.status_code == 200
+    assert response.text == "ok"
+
+
+def test_auth_disabled_always_passes_through():
+    """auth_enabled=False (dev mode) -> no token needed, matches get_current_user's dev bypass."""
+    with patch("app.mcp.server.settings") as fake_settings:
+        fake_settings.auth_enabled = False
+        client = TestClient(_dummy_app())
+        response = client.get("/ping")
+    assert response.status_code == 200
+
+
+def test_401_includes_www_authenticate_header():
+    """RFC 7235 requires WWW-Authenticate on 401 so clients can tell why they failed."""
+    with patch("app.mcp.server.settings") as fake_settings:
+        fake_settings.auth_enabled = True
+        client = TestClient(_dummy_app())
+        response = client.get("/ping")
+    assert response.status_code == 401
+    assert response.headers["WWW-Authenticate"] == "Bearer"
+
+
+def test_non_utf8_authorization_header_is_rejected_not_crashed():
+    """A non-UTF-8 header byte must yield a clean 401, not an unhandled 500.
+
+    ASGI header values are latin-1 bytes, so any remote client could otherwise
+    trigger a UnicodeDecodeError inside the middleware at will.
+    """
+    with patch("app.mcp.server.settings") as fake_settings:
+        fake_settings.auth_enabled = True
+        client = TestClient(_dummy_app(), raise_server_exceptions=False)
+        # Bypass the http client's own header encoding by writing raw bytes.
+        response = client.get("/ping", headers={"Authorization": b"Bearer \xff\xfe"})
+    assert response.status_code == 401

backend/tests/mcp/test_mcp_stats.py

@@ -0,0 +1,100 @@
+"""Tests for the in-memory MCP per-tool statistics tracker.
+
+These pin the two properties the status panel depends on: counters stay exact
+under the concurrent thread dispatch the mcp SDK uses, and recording never
+raises into a live tool call.
+"""
+
+from __future__ import annotations
+
+import threading
+
+from app.mcp.stats import MCPStatsTracker, MCPToolStats, get_mcp_stats_tracker
+
+
+def test_avg_duration_is_none_before_any_call():
+    """A never-called tool reports None, not 0.0, so the UI can distinguish them."""
+    assert MCPToolStats().avg_duration_ms is None
+
+
+def test_avg_duration_is_the_mean_of_recorded_durations():
+    """Average is computed over all calls, successful or not."""
+    tracker = MCPStatsTracker()
+    for duration in (100.0, 200.0, 300.0):
+        tracker.record(tool="search_regulations", duration_ms=duration, success=True)
+
+    stats = tracker.snapshot()["search_regulations"]
+    assert stats.calls == 3
+    assert stats.avg_duration_ms == 200.0
+
+
+def test_failures_increment_both_calls_and_errors():
+    """errors is a subset of calls, so the UI can show "2 of 3 failed" honestly."""
+    tracker = MCPStatsTracker()
+    tracker.record(tool="t", duration_ms=1.0, success=True)
+    tracker.record(tool="t", duration_ms=1.0, success=False)
+    tracker.record(tool="t", duration_ms=1.0, success=False)
+
+    stats = tracker.snapshot()["t"]
+    assert stats.calls == 3
+    assert stats.errors == 2
+
+
+def test_last_called_at_is_set_and_timezone_aware():
+    """The panel renders this as a local time, which requires an aware datetime."""
+    tracker = MCPStatsTracker()
+    tracker.record(tool="t", duration_ms=1.0, success=True)
+
+    last_called = tracker.snapshot()["t"].last_called_at
+    assert last_called is not None
+    assert last_called.tzinfo is not None
+
+
+def test_concurrent_record_calls_are_not_lost():
+    """8 threads x 100 calls must total exactly 800.
+
+    Without the lock this loses increments non-deterministically. The mcp SDK
+    runs synchronous tool bodies via anyio.to_thread.run_sync, so this is the
+    real dispatch model, not a hypothetical.
+    """
+    tracker = MCPStatsTracker()
+
+    def hammer() -> None:
+        for _ in range(100):
+            tracker.record(tool="search_regulations", duration_ms=1.0, success=True)
+
+    threads = [threading.Thread(target=hammer) for _ in range(8)]
+    for thread in threads:
+        thread.start()
+    for thread in threads:
+        thread.join()
+
+    stats = tracker.snapshot()["search_regulations"]
+    assert stats.calls == 800
+    assert stats.total_duration_ms == 800.0
+
+
+def test_record_swallows_bad_input_instead_of_raising():
+    """A malformed duration must not propagate into the caller's tool call."""
+    tracker = MCPStatsTracker()
+    tracker.record(tool="t", duration_ms="not-a-number", success=True)  # type: ignore[arg-type]
+
+    # Coercion happens before the lock is taken, so the entry is never created
+    # in a half-updated state.
+    assert tracker.snapshot() == {}
+
+
+def test_snapshot_is_a_copy_not_the_live_dict():
+    """Callers mutating the snapshot must not corrupt the tracker."""
+    tracker = MCPStatsTracker()
+    tracker.record(tool="t", duration_ms=1.0, success=True)
+
+    snapshot = tracker.snapshot()
+    snapshot.clear()
+
+    assert "t" in tracker.snapshot()
+
+
+def test_get_mcp_stats_tracker_returns_a_singleton():
+    """Instrumentation and the status route must observe the same counters."""
+    assert get_mcp_stats_tracker() is get_mcp_stats_tracker()

backend/tests/mcp/test_mcp_status.py

@@ -0,0 +1,79 @@
+"""Tests for get_mcp_status(), the payload behind the System Status MCP card.
+
+Covers the join between the live tool registry and the stats tracker, plus
+the two values the route supplies or the settings decide.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from unittest.mock import patch
+
+from app.mcp.stats import MCPStatsTracker
+
+
+def _status(tracker: MCPStatsTracker | None = None, **setting_overrides) -> dict:
+    """Call get_mcp_status() with an isolated tracker and patched settings.
+
+    The real tracker is a process-wide singleton, so tests must inject their
+    own instance or they leak counters into each other.
+    """
+    from app.mcp.server import get_mcp_status, settings
+
+    patched = settings.model_copy(update=setting_overrides)
+    with (
+        patch("app.mcp.server.settings", patched),
+        patch("app.mcp.server.get_mcp_stats_tracker", return_value=tracker or MCPStatsTracker()),
+    ):
+        return asyncio.run(get_mcp_status("http://6.86.80.9:8000/mcp/"))
+
+
+def test_public_url_is_passed_through_unmodified():
+    """The route owns URL resolution; get_mcp_status() must not rewrite it."""
+    assert _status()["endpoint_url"] == "http://6.86.80.9:8000/mcp/"
+
+
+def test_auth_required_follows_settings():
+    """The panel's auth badge must reflect live config, not a hard-coded value."""
+    assert _status(auth_enabled=True)["auth_required"] is True
+    assert _status(auth_enabled=False)["auth_required"] is False
+
+
+def test_allowed_hosts_are_split_and_stripped():
+    """Displayed allow-list must match the one the transport actually enforces."""
+    status = _status(mcp_allowed_hosts="6.86.80.9:* , 127.0.0.1:*,")
+    assert status["allowed_hosts"] == ["6.86.80.9:*", "127.0.0.1:*"]
+
+
+def test_tools_come_from_the_live_registry_with_zeroed_stats():
+    """An advertised but never-called tool reports zeros, not absence."""
+    tools = {tool["name"]: tool for tool in _status()["tools"]}
+
+    assert "search_regulations" in tools
+    assert tools["search_regulations"]["calls"] == 0
+    assert tools["search_regulations"]["errors"] == 0
+    assert tools["search_regulations"]["avg_duration_ms"] is None
+    assert tools["search_regulations"]["last_called_at"] is None
+
+
+def test_recorded_stats_are_joined_onto_the_matching_tool():
+    """Counters recorded by the instrumented tool must surface on that tool's row."""
+    tracker = MCPStatsTracker()
+    tracker.record(tool="search_regulations", duration_ms=120.0, success=True)
+    tracker.record(tool="search_regulations", duration_ms=80.0, success=False)
+
+    tool = next(t for t in _status(tracker)["tools"] if t["name"] == "search_regulations")
+
+    assert tool["calls"] == 2
+    assert tool["errors"] == 1
+    assert tool["avg_duration_ms"] == 100.0
+    # Serialized for JSON transport; the frontend parses it with new Date().
+    assert isinstance(tool["last_called_at"], str)
+
+
+def test_description_is_the_first_docstring_line():
+    """Multi-line tool docstrings must not blow up the card's row height."""
+    tool = next(t for t in _status()["tools"] if t["name"] == "search_regulations")
+
+    assert "\n" not in tool["description"]
+    assert tool["description"].startswith("Search the compliance knowledge base")

backend/tests/mcp/test_mcp_transport_security.py

@@ -0,0 +1,107 @@
+"""Tests for the MCP endpoint's DNS-rebinding (Host header) protection.
+
+The MCP SDK auto-enables DNS-rebinding protection and derives its allow-list
+from the bind host, which defaults to 127.0.0.1. Left alone, that rejects every
+request whose Host header is the real deployment address (6.86.80.9:8000) with
+HTTP 421 — before the auth middleware or the tool ever runs. These tests pin
+the configured allow-list behavior so that failure mode cannot come back.
+"""
+
+from __future__ import annotations
+
+import json
+from contextlib import contextmanager
+from unittest.mock import patch
+
+from starlette.testclient import TestClient
+
+from app.mcp.server import _build_transport_security, build_mcp_asgi_app
+
+# A minimal JSON-RPC initialize call. Reaching the MCP handler at all is what
+# matters here; transport security rejects the request long before this body is
+# parsed, so its exact contents only need to be structurally valid.
+_INITIALIZE = {
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "initialize",
+    "params": {
+        "protocolVersion": "2025-06-18",
+        "capabilities": {},
+        "clientInfo": {"name": "test", "version": "1.0"},
+    },
+}
+
+_HEADERS = {
+    "Content-Type": "application/json",
+    "Accept": "application/json, text/event-stream",
+}
+
+
+@contextmanager
+def _mcp_client(allowed_hosts: str):
+    """Yield a TestClient over the real MCP app with auth off and hosts configured.
+
+    The settings patch must stay active for the requests themselves, not just
+    for app construction, because MCPAuthMiddleware reads settings per request.
+    Entering the TestClient as a context manager is also required: it runs the
+    app's lifespan, without which the SDK's session manager task group is never
+    initialized and every request raises RuntimeError.
+    """
+    with patch("app.mcp.server.settings") as fake_settings:
+        fake_settings.mcp_allowed_hosts = allowed_hosts
+        fake_settings.cors_allow_origins = "http://localhost:5173"
+        fake_settings.auth_enabled = False
+        with TestClient(build_mcp_asgi_app()) as client:
+            yield client
+
+
+def test_remote_host_allowed_when_configured():
+    """A configured non-loopback Host must reach the MCP handler, not 421."""
+    with _mcp_client("6.86.80.9:*,127.0.0.1:*") as client:
+        response = client.post(
+            "/", json=_INITIALIZE, headers={**_HEADERS, "Host": "6.86.80.9:8000"}
+        )
+    assert response.status_code == 200
+    assert "Invalid Host header" not in response.text
+
+
+def test_unconfigured_host_still_rejected():
+    """Protection must stay on: a Host outside the allow-list is refused with 421."""
+    with _mcp_client("6.86.80.9:*") as client:
+        response = client.post(
+            "/", json=_INITIALIZE, headers={**_HEADERS, "Host": "evil.example.com"}
+        )
+    assert response.status_code == 421
+
+
+def test_initialize_response_is_event_stream():
+    """Sanity check that a permitted request really completes the MCP handshake."""
+    with _mcp_client("6.86.80.9:*") as client:
+        response = client.post(
+            "/", json=_INITIALIZE, headers={**_HEADERS, "Host": "6.86.80.9:8000"}
+        )
+    assert response.status_code == 200
+    # The Streamable HTTP transport replies as SSE; the JSON-RPC result is
+    # embedded in a "data:" line rather than being the whole body.
+    payload = json.loads(response.text.split("data:", 1)[1].strip())
+    assert payload["result"]["serverInfo"]["name"] == "ai-regulations"
+
+
+def test_wildcard_disables_protection_explicitly():
+    """'*' is the documented opt-out; it must disable the check, not allow-list '*'."""
+    with patch("app.mcp.server.settings") as fake_settings:
+        fake_settings.mcp_allowed_hosts = "*"
+        fake_settings.cors_allow_origins = "http://localhost:5173"
+        security = _build_transport_security()
+    assert security.enable_dns_rebinding_protection is False
+
+
+def test_allow_list_is_parsed_into_transport_settings():
+    """Comma-separated config must become the SDK's allowed_hosts list verbatim."""
+    with patch("app.mcp.server.settings") as fake_settings:
+        fake_settings.mcp_allowed_hosts = "6.86.80.9:*, localhost:* ,"
+        fake_settings.cors_allow_origins = "http://localhost:5173"
+        security = _build_transport_security()
+    assert security.enable_dns_rebinding_protection is True
+    assert security.allowed_hosts == ["6.86.80.9:*", "localhost:*"]
+    assert security.allowed_origins == ["http://localhost:5173"]

backend/tests/mcp/test_search_regulations_tool.py

@@ -0,0 +1,98 @@
+"""Unit tests for the search_regulations MCP tool function.
+
+Mocks AgentConversationService so no real retrieval/LLM call happens —
+verifies only the protocol-adapter contract: correct call shape in,
+correct dict shape out.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from unittest.mock import MagicMock, patch
+
+
+@dataclass
+class _FakeSource:
+    """Minimal stand-in for a real Source dataclass (only __dict__ is used)."""
+
+    # A dataclass, not a MagicMock: the adapter serializes sources via
+    # source.__dict__, and a MagicMock's __dict__ is full of internal mock
+    # attributes, which would make the assertions meaningless.
+    doc_id: str
+    doc_title: str
+    score: float
+
+
+@dataclass
+class _FakeAnswerResult:
+    """Minimal stand-in for AnswerResult — only .answer/.sources are read."""
+
+    answer: str
+    sources: list
+
+
+def test_search_regulations_calls_agent_ask_without_session():
+    """search_regulations must call ask() with no session_id (stateless search)."""
+    from app.mcp.server import search_regulations
+
+    fake_service = MagicMock()
+    fake_service.ask.return_value = (
+        None,
+        _FakeAnswerResult(answer="国六排放标准要求...", sources=[_FakeSource("doc-1", "国六标准", 0.9)]),
+    )
+
+    with patch("app.mcp.server.get_agent_conversation_service", return_value=fake_service):
+        search_regulations(query="国六排放标准最新要求", top_k=3)
+
+    fake_service.ask.assert_called_once_with(query="国六排放标准最新要求", top_k=3)
+    assert "session_id" not in fake_service.ask.call_args.kwargs
+
+
+def test_search_regulations_shapes_response_dict():
+    """The returned dict must expose 'answer' and 'sources' (list of plain dicts)."""
+    from app.mcp.server import search_regulations
+
+    fake_service = MagicMock()
+    fake_service.ask.return_value = (
+        None,
+        _FakeAnswerResult(answer="答案文本", sources=[_FakeSource("doc-2", "国标GB1589", 0.8)]),
+    )
+
+    with patch("app.mcp.server.get_agent_conversation_service", return_value=fake_service):
+        result = search_regulations(query="q")
+
+    assert result == {
+        "answer": "答案文本",
+        "sources": [{"doc_id": "doc-2", "doc_title": "国标GB1589", "score": 0.8}],
+    }
+
+
+def test_search_regulations_default_top_k():
+    """top_k defaults to 5 when the caller omits it."""
+    from app.mcp.server import search_regulations
+
+    fake_service = MagicMock()
+    fake_service.ask.return_value = (None, _FakeAnswerResult(answer="a", sources=[]))
+
+    with patch("app.mcp.server.get_agent_conversation_service", return_value=fake_service):
+        search_regulations(query="q")
+
+    assert fake_service.ask.call_args.kwargs["top_k"] == 5
+
+
+def test_advertised_schema_bounds_top_k_and_query():
+    """The advertised JSON schema must carry the same bounds as AskRequest.
+
+    Bounds declared via Annotated are what the SDK validates against and what
+    clients see, so asserting on the generated schema is the only way to catch
+    a regression that silently drops them.
+    """
+    from app.mcp.server import mcp
+
+    schema = asyncio.run(mcp.list_tools())[0].input_schema["properties"]
+
+    assert schema["top_k"]["minimum"] == 1
+    assert schema["top_k"]["maximum"] == 20
+    assert schema["query"]["minLength"] == 1
+    assert schema["query"]["maxLength"] == 2000

backend/tests/observability/test_model_usage_bootstrap.py

@@ -0,0 +1,104 @@
+"""Unit tests for the model-usage persistence wiring in app.shared.bootstrap.
+
+get_model_usage_store()'s settings-gating is tested the same way
+tests/test_reranker_bootstrap.py tests get_reranker() — by patching
+"app.shared.bootstrap.settings" wholesale, matching this codebase's
+established convention for testing @lru_cache settings-gated factories.
+The remaining tests isolate _start_model_usage_persistence() /
+_stop_model_usage_persistence() from get_model_usage_store() entirely (via
+monkeypatch on the module-level function), so no real database or event loop
+is needed anywhere in this file — asyncio.create_task itself is also mocked.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+# psycopg2 is mocked centrally in backend/tests/conftest.py, which pytest
+# imports before any test module regardless of collection order.
+from app.shared import bootstrap
+from app.shared.model_usage_tracker import ModelUsageEntry, ModelUsageTracker
+
+
+def test_get_model_usage_store_returns_none_when_not_postgres_backend():
+    """get_model_usage_store() must be None unless document_repository_backend == 'postgres'."""
+    bootstrap.get_model_usage_store.cache_clear()
+
+    with patch("app.shared.bootstrap.settings") as mock_settings:
+        mock_settings.document_repository_backend = "json"
+        result = bootstrap.get_model_usage_store()
+
+    bootstrap.get_model_usage_store.cache_clear()
+    assert result is None
+
+
+def test_get_model_usage_store_returns_instance_when_postgres_backend():
+    """get_model_usage_store() must return a PostgresModelUsageStore when enabled.
+
+    ThreadedConnectionPool is mocked so no real connection is attempted; the
+    postgres_host/port/user/password/db values PostgresModelUsageStore reads
+    come from app.config.settings.settings directly (not from the
+    app.shared.bootstrap.settings reference mocked below), so they don't need
+    to be set here — only document_repository_backend gates this factory.
+    """
+    bootstrap.get_model_usage_store.cache_clear()
+
+    with patch("psycopg2.pool.ThreadedConnectionPool"), \
+         patch(
+             "app.infrastructure.storage.postgres_model_usage_store.PostgresModelUsageStore._ensure_schema"
+         ), \
+         patch("app.shared.bootstrap.settings") as mock_settings:
+        mock_settings.document_repository_backend = "postgres"
+        result = bootstrap.get_model_usage_store()
+
+    bootstrap.get_model_usage_store.cache_clear()
+    from app.infrastructure.storage.postgres_model_usage_store import PostgresModelUsageStore
+    assert isinstance(result, PostgresModelUsageStore)
+
+
+def test_start_model_usage_persistence_seeds_tracker_and_starts_flush_loop(monkeypatch):
+    """When a store is available, startup must seed the tracker and schedule the flush task."""
+    fake_store = MagicMock()
+    fake_store.load_all.return_value = {
+        "deepseek:deepseek-v4-flash": ModelUsageEntry(
+            provider="deepseek", model="deepseek-v4-flash", total_tokens=99,
+        ),
+    }
+    tracker = ModelUsageTracker()
+    monkeypatch.setattr(bootstrap, "get_model_usage_store", lambda: fake_store)
+    monkeypatch.setattr(bootstrap, "get_model_usage_tracker", lambda: tracker)
+
+    with patch("asyncio.create_task") as mock_create_task:
+        bootstrap._start_model_usage_persistence()
+        # Close the coroutine object passed to the mock so pytest doesn't warn
+        # about "coroutine was never awaited" — it was never meant to run here.
+        mock_create_task.call_args[0][0].close()
+
+    assert tracker.get("deepseek", "deepseek-v4-flash").total_tokens == 99
+    mock_create_task.assert_called_once()
+
+    bootstrap._stop_model_usage_persistence()  # reset the module-level task handle
+
+
+def test_start_model_usage_persistence_is_a_no_op_without_a_store(monkeypatch):
+    """No store configured (json backend) — startup must not touch asyncio or the tracker."""
+    monkeypatch.setattr(bootstrap, "get_model_usage_store", lambda: None)
+
+    with patch("asyncio.create_task") as mock_create_task:
+        bootstrap._start_model_usage_persistence()
+
+    mock_create_task.assert_not_called()
+
+
+def test_stop_model_usage_persistence_cancels_task_and_flushes(monkeypatch):
+    """Shutdown must cancel the running flush task and perform one final flush."""
+    fake_store = MagicMock()
+    monkeypatch.setattr(bootstrap, "get_model_usage_store", lambda: fake_store)
+    fake_task = MagicMock()
+    bootstrap._model_usage_flush_task = fake_task
+
+    bootstrap._stop_model_usage_persistence()
+
+    fake_task.cancel.assert_called_once()
+    fake_store.flush.assert_called_once()
+    assert bootstrap._model_usage_flush_task is None

backend/tests/observability/test_model_usage_persistence.py

@@ -0,0 +1,102 @@
+"""Unit tests for PostgresModelUsageStore, using a mocked psycopg2 pool.
+
+Mirrors the mocking pattern in backend/tests/perception/test_postgres_event_store.py
+— no real database is needed.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from unittest.mock import MagicMock, patch
+
+# psycopg2 is mocked centrally in backend/tests/conftest.py, so importing the
+# module under test here never binds the real driver.
+from app.shared.model_usage_tracker import ModelUsageEntry
+
+
+def _cursor_returning(rows):
+    """Build a MagicMock standing in for a psycopg2 cursor context manager."""
+    cursor = MagicMock()
+    cursor.__enter__ = lambda s: s
+    cursor.__exit__ = MagicMock(return_value=False)
+    cursor.fetchall.return_value = rows
+    return cursor
+
+
+@patch("app.infrastructure.storage.postgres_model_usage_store.PostgresModelUsageStore._ensure_schema")
+@patch("app.infrastructure.storage.postgres_model_usage_store.ThreadedConnectionPool")
+def test_load_all_returns_entries_keyed_by_provider_model(mock_pool_class, mock_ensure):
+    """load_all() must turn each row into a ModelUsageEntry keyed by 'provider:model'."""
+    row = {
+        "provider": "deepseek",
+        "model": "deepseek-v4-flash",
+        "total_tokens": 100,
+        "prompt_tokens": 60,
+        "completion_tokens": 40,
+        "call_count_ok": 5,
+        "call_count_error": 1,
+        "last_called_at": datetime(2026, 7, 23, tzinfo=timezone.utc),
+        "last_latency_ms": 250,
+        "last_error": None,
+    }
+    mock_pool = MagicMock()
+    mock_pool_class.return_value = mock_pool
+    conn = MagicMock()
+    conn.__enter__ = lambda s: s
+    conn.__exit__ = MagicMock(return_value=False)
+    conn.cursor.return_value = _cursor_returning([row])
+    mock_pool.getconn.return_value = conn
+
+    from app.infrastructure.storage.postgres_model_usage_store import PostgresModelUsageStore
+    store = PostgresModelUsageStore()
+    entries = store.load_all()
+
+    assert "deepseek:deepseek-v4-flash" in entries
+    entry = entries["deepseek:deepseek-v4-flash"]
+    assert isinstance(entry, ModelUsageEntry)
+    assert entry.total_tokens == 100
+    assert entry.call_count_error == 1
+
+
+@patch("app.infrastructure.storage.postgres_model_usage_store.PostgresModelUsageStore._ensure_schema")
+@patch("app.infrastructure.storage.postgres_model_usage_store.ThreadedConnectionPool")
+def test_flush_upserts_every_entry(mock_pool_class, mock_ensure):
+    """flush() must execute one UPSERT per tracked entry and commit once."""
+    mock_pool = MagicMock()
+    mock_pool_class.return_value = mock_pool
+    conn = MagicMock()
+    conn.__enter__ = lambda s: s
+    conn.__exit__ = MagicMock(return_value=False)
+    cursor = MagicMock()
+    cursor.__enter__ = lambda s: s
+    cursor.__exit__ = MagicMock(return_value=False)
+    conn.cursor.return_value = cursor
+    mock_pool.getconn.return_value = conn
+
+    from app.infrastructure.storage.postgres_model_usage_store import PostgresModelUsageStore
+    store = PostgresModelUsageStore()
+    entries = {
+        "deepseek:deepseek-v4-flash": ModelUsageEntry(
+            provider="deepseek", model="deepseek-v4-flash", total_tokens=100, call_count_ok=5,
+        ),
+    }
+
+    store.flush(entries)
+
+    assert cursor.execute.call_count == 1
+    conn.commit.assert_called_once()
+
+
+@patch("app.infrastructure.storage.postgres_model_usage_store.PostgresModelUsageStore._ensure_schema")
+@patch("app.infrastructure.storage.postgres_model_usage_store.ThreadedConnectionPool")
+def test_flush_with_no_entries_does_not_touch_the_database(mock_pool_class, mock_ensure):
+    """flush({}) must be a no-op — no point opening a connection for nothing."""
+    mock_pool = MagicMock()
+    mock_pool_class.return_value = mock_pool
+
+    from app.infrastructure.storage.postgres_model_usage_store import PostgresModelUsageStore
+    store = PostgresModelUsageStore()
+
+    store.flush({})
+
+    mock_pool.getconn.assert_not_called()

backend/tests/observability/test_model_usage_tracker.py

@@ -77,3 +77,33 @@ def test_snapshot_returns_independent_copy():
 def test_get_model_usage_tracker_returns_singleton():
     """get_model_usage_tracker() always returns the same process-wide instance."""
     assert get_model_usage_tracker() is get_model_usage_tracker()
+
+
+def test_seed_populates_registry_from_persisted_entries():
+    """seed() must bulk-load entries (e.g. from Postgres at startup) into the registry."""
+    tracker = ModelUsageTracker()
+    persisted = {
+        "deepseek:deepseek-v4-flash": ModelUsageEntry(
+            provider="deepseek", model="deepseek-v4-flash", total_tokens=500, call_count_ok=20,
+        ),
+    }
+
+    tracker.seed(persisted)
+
+    entry = tracker.get("deepseek", "deepseek-v4-flash")
+    assert entry.total_tokens == 500
+    assert entry.call_count_ok == 20
+
+
+def test_seed_then_record_accumulates_on_top_of_seeded_value():
+    """A call recorded after seeding must add to the seeded total, not replace it."""
+    tracker = ModelUsageTracker()
+    tracker.seed({
+        "deepseek:deepseek-v4-flash": ModelUsageEntry(
+            provider="deepseek", model="deepseek-v4-flash", total_tokens=500,
+        ),
+    })
+
+    tracker.record(provider="deepseek", model="deepseek-v4-flash", success=True, usage={"total_tokens": 10})
+
+    assert tracker.get("deepseek", "deepseek-v4-flash").total_tokens == 510

backend/tests/observability/test_stream_chat_usage_capture.py

@@ -0,0 +1,116 @@
+"""Unit tests verifying stream_chat() captures a trailing usage-only SSE chunk.
+
+Exercises DeepSeekClient, QwenClient, and QwenVLClient directly (not through
+TrackedLLMClient) by mocking the underlying httpx.Client.stream() call — none
+of these tests make a real network call.
+"""
+
+from __future__ import annotations
+
+import json
+from unittest.mock import MagicMock
+
+from app.services.llm.base_client import LLMConfig, LLMProvider
+from app.services.llm.deepseek_client import DeepSeekClient
+
+
+def _sse_lines(*chunks: str, usage: dict | None = None) -> list[str]:
+    """Build raw SSE 'data: ...' lines the way an OpenAI-compatible gateway sends them."""
+    lines = [
+        f'data: {json.dumps({"choices": [{"delta": {"content": c}}]})}'
+        for c in chunks
+    ]
+    if usage is not None:
+        # Trailing usage-only chunk, as sent when stream_options.include_usage=true.
+        lines.append(f'data: {json.dumps({"choices": [], "usage": usage})}')
+    lines.append("data: [DONE]")
+    return lines
+
+
+def _mock_streaming_client(lines: list[str]) -> MagicMock:
+    """Build a MagicMock standing in for httpx.Client, configured for .stream()."""
+    fake_response = MagicMock()
+    fake_response.raise_for_status.return_value = None
+    fake_response.iter_lines.return_value = lines
+
+    stream_cm = MagicMock()
+    stream_cm.__enter__.return_value = fake_response
+    stream_cm.__exit__.return_value = False
+
+    client = MagicMock()
+    client.stream.return_value = stream_cm
+    return client
+
+
+def _drain(gen):
+    """Manually drive a generator, returning (yielded_chunks, stop_iteration_value)."""
+    chunks = []
+    value = None
+    while True:
+        try:
+            chunks.append(next(gen))
+        except StopIteration as stop:
+            value = stop.value
+            break
+    return chunks, value
+
+
+def test_deepseek_stream_chat_returns_usage_from_trailing_chunk():
+    """DeepSeekClient.stream_chat() must return the trailing usage dict."""
+    config = LLMConfig(provider=LLMProvider.DEEPSEEK, model="deepseek-v4-flash", api_key="k", base_url="http://x/v1")
+    client = DeepSeekClient(config)
+    usage = {"prompt_tokens": 5, "completion_tokens": 3, "total_tokens": 8}
+    client._client = _mock_streaming_client(_sse_lines("Hello", " world", usage=usage))
+
+    chunks, returned_usage = _drain(client.stream_chat([{"role": "user", "content": "hi"}]))
+
+    assert chunks == ["Hello", " world"]
+    assert returned_usage == usage
+    # The gateway must actually be asked to include usage in the stream.
+    sent_payload = client._client.stream.call_args.kwargs["json"]
+    assert sent_payload["stream_options"] == {"include_usage": True}
+
+
+def test_deepseek_stream_chat_without_usage_chunk_returns_none():
+    """If the gateway never sends a usage chunk, the generator returns None (unchanged behavior)."""
+    config = LLMConfig(provider=LLMProvider.DEEPSEEK, model="deepseek-v4-flash", api_key="k", base_url="http://x/v1")
+    client = DeepSeekClient(config)
+    client._client = _mock_streaming_client(_sse_lines("Hi"))
+
+    chunks, returned_usage = _drain(client.stream_chat([{"role": "user", "content": "hi"}]))
+
+    assert chunks == ["Hi"]
+    assert returned_usage is None
+
+
+from app.services.llm.qwen_client import QwenClient, QwenVLClient
+
+
+def test_qwen_stream_chat_returns_usage_from_trailing_chunk():
+    """QwenClient.stream_chat() must return the trailing usage dict."""
+    config = LLMConfig(provider=LLMProvider.QWEN, model="qwen3.5-flash", api_key="k", base_url="http://x/v1")
+    client = QwenClient(config)
+    usage = {"prompt_tokens": 10, "completion_tokens": 4, "total_tokens": 14}
+    client._client = _mock_streaming_client(_sse_lines("Bonjour", usage=usage))
+
+    chunks, returned_usage = _drain(client.stream_chat([{"role": "user", "content": "hi"}]))
+
+    assert chunks == ["Bonjour"]
+    assert returned_usage == usage
+    sent_payload = client._client.stream.call_args.kwargs["json"]
+    assert sent_payload["stream_options"] == {"include_usage": True}
+
+
+def test_qwen_vl_stream_chat_returns_usage_from_trailing_chunk():
+    """QwenVLClient.stream_chat() must return the trailing usage dict."""
+    config = LLMConfig(provider=LLMProvider.QWEN_VL, model="qwen3-vl-plus", api_key="k", base_url="http://x/v1")
+    client = QwenVLClient(config)
+    usage = {"prompt_tokens": 20, "completion_tokens": 6, "total_tokens": 26}
+    client._client = _mock_streaming_client(_sse_lines("Describing image", usage=usage))
+
+    chunks, returned_usage = _drain(client.stream_chat([{"role": "user", "content": "describe"}]))
+
+    assert chunks == ["Describing image"]
+    assert returned_usage == usage
+    sent_payload = client._client.stream.call_args.kwargs["json"]
+    assert sent_payload["stream_options"] == {"include_usage": True}

backend/tests/observability/test_tracked_client.py

@@ -83,3 +83,23 @@ def test_stream_chat_records_call_without_token_usage():
     entry = tracker.get("deepseek", "deepseek-v4-flash")
     assert entry.call_count_ok == 1
     assert entry.total_tokens == 0
+
+
+def test_stream_chat_records_usage_from_generator_return_value():
+    """stream_chat() must forward the inner generator's returned usage dict to record()."""
+    inner = _make_inner()
+
+    def fake_stream(*args, **kwargs):
+        yield "chunk-1"
+        yield "chunk-2"
+        return {"prompt_tokens": 6, "completion_tokens": 2, "total_tokens": 8}
+
+    inner.stream_chat.side_effect = fake_stream
+    tracker = ModelUsageTracker()
+
+    chunks = list(TrackedLLMClient(inner, tracker).stream_chat([{"role": "user", "content": "hi"}]))
+
+    assert chunks == ["chunk-1", "chunk-2"]
+    entry = tracker.get("deepseek", "deepseek-v4-flash")
+    assert entry.total_tokens == 8
+    assert entry.call_count_ok == 1

backend/tests/perception/test_crawl_service.py

@@ -6,6 +6,7 @@ import pytest
 
 from app.infrastructure.perception.crawlers.base import RawEvent
 from app.infrastructure.perception.mock_event_store import MockEventStore
+from app.infrastructure.perception.mock_notification_store import MockNotificationStore
 
 
 def _make_raw_event(code="TST-001"):
@@ -17,11 +18,18 @@ def _make_raw_event(code="TST-001"):
     )
 
 
+def _make_crawler(raw_events, full_text="full body text"):
+    """Build a mock crawler. `full_text=""` simulates a failed detail fetch."""
+    mock_crawler = MagicMock()
+    mock_crawler.fetch.return_value = raw_events
+    mock_crawler.fetch_full_text.return_value = full_text
+    return mock_crawler
+
+
 def _make_service(raw_events):
     from app.application.perception.crawl_service import CrawlService
 
-    mock_crawler = MagicMock()
+    mock_crawler = _make_crawler(raw_events)
-    mock_crawler.fetch.return_value = raw_events
 
     mock_pipeline = MagicMock()
     mock_pipeline.extract_structure.return_value = {
@@ -41,6 +49,9 @@ def _make_service(raw_events):
         event_store=store,
         llm_pipeline=mock_pipeline,
         retrieval_service=mock_retrieval,
+        notification_store=MockNotificationStore(),
+        embedding_provider=MagicMock(),
+        vector_index=MagicMock(),
     )
 
 
@@ -54,8 +65,7 @@ def test_crawl_yields_progress_and_done():
 def test_crawl_upserts_to_store():
     store = MockEventStore()
     from app.application.perception.crawl_service import CrawlService
-    mock_crawler = MagicMock()
+    mock_crawler = _make_crawler([_make_raw_event("NEW-001")])
-    mock_crawler.fetch.return_value = [_make_raw_event("NEW-001")]
     mock_pipeline = MagicMock()
     mock_pipeline.extract_structure.return_value = {
         "obligations": [], "deadlines": [], "scope": "",
@@ -70,6 +80,9 @@ def test_crawl_upserts_to_store():
         event_store=store,
         llm_pipeline=mock_pipeline,
         retrieval_service=MagicMock(),
+        notification_store=MockNotificationStore(),
+        embedding_provider=MagicMock(),
+        vector_index=MagicMock(),
     )
     list(svc.run_crawl())
     result = store.get_by_standard_code("NEW-001")
@@ -80,7 +93,8 @@ def test_crawl_upserts_to_store():
 def test_crawl_skips_unchanged_events():
     store = MockEventStore()
     raw = _make_raw_event("SKIP-001")
-    content_hash = hashlib.sha256(raw.raw_text.encode()).hexdigest()
+    body = "full body text"
+    content_hash = hashlib.sha256(body.encode()).hexdigest()
     store.upsert({
         "id": hashlib.sha256(f"TEST-SKIP-001".encode()).hexdigest()[:12],
         "standard_code": "SKIP-001",
@@ -99,13 +113,341 @@ def test_crawl_skips_unchanged_events():
     })
     mock_pipeline = MagicMock()
     from app.application.perception.crawl_service import CrawlService
-    mock_crawler = MagicMock()
+    mock_crawler = _make_crawler([raw], full_text=body)
-    mock_crawler.fetch.return_value = [raw]
     svc = CrawlService(
         crawlers={"TEST": mock_crawler},
         event_store=store,
         llm_pipeline=mock_pipeline,
         retrieval_service=MagicMock(),
+        notification_store=MockNotificationStore(),
+        embedding_provider=MagicMock(),
+        vector_index=MagicMock(),
     )
     list(svc.run_crawl())
     mock_pipeline.extract_structure.assert_not_called()
+
+
+def test_crawl_stores_the_fetched_body_for_the_next_diff():
+    """The body must be persisted, or the next crawl has no baseline to compare."""
+    store = MockEventStore()
+    from app.application.perception.crawl_service import CrawlService
+    mock_pipeline = MagicMock()
+    mock_pipeline.extract_structure.return_value = {}
+    mock_pipeline.assess_impact.return_value = []
+    svc = CrawlService(
+        crawlers={"TEST": _make_crawler([_make_raw_event("BODY-001")], full_text="第一条 正文内容。")},
+        event_store=store,
+        llm_pipeline=mock_pipeline,
+        retrieval_service=MagicMock(),
+        notification_store=MockNotificationStore(),
+        embedding_provider=MagicMock(),
+        vector_index=MagicMock(),
+    )
+    list(svc.run_crawl())
+
+    stored = store.get_by_standard_code("BODY-001")
+    assert stored["raw_text"] == "第一条 正文内容。"
+
+
+def test_crawl_falls_back_when_full_text_fetch_fails():
+    """An unreachable detail page degrades to the list-page text, never crashes."""
+    store = MockEventStore()
+    from app.application.perception.crawl_service import CrawlService
+    mock_pipeline = MagicMock()
+    mock_pipeline.extract_structure.return_value = {}
+    mock_pipeline.assess_impact.return_value = []
+    svc = CrawlService(
+        crawlers={"TEST": _make_crawler([_make_raw_event("FALL-001")], full_text="")},
+        event_store=store,
+        llm_pipeline=mock_pipeline,
+        retrieval_service=MagicMock(),
+        notification_store=MockNotificationStore(),
+        embedding_provider=MagicMock(),
+        vector_index=MagicMock(),
+    )
+    list(svc.run_crawl())
+
+    stored = store.get_by_standard_code("FALL-001")
+    assert stored is not None
+    assert stored["raw_text"] == "full text"
+
+
+def test_crawl_skips_diff_when_no_previous_body_exists():
+    """Rows stored before raw_text was persisted must not be diffed against nothing."""
+    store = MockEventStore()
+    from app.application.perception.crawl_service import CrawlService
+    event_id = hashlib.sha256(b"TEST-OLD-001").hexdigest()[:12]
+    store.upsert({
+        "id": event_id,
+        "standard_code": "OLD-001",
+        "source": "TEST",
+        "title": "Test OLD-001",
+        "summary": "legacy row",
+        "impact_level": "low",
+        "published_at": "2026-01-01",
+        "tags": [],
+        "content_hash": "stale-hash-from-before-this-change",
+    })
+    mock_pipeline = MagicMock()
+    mock_pipeline.extract_structure.return_value = {}
+    mock_pipeline.assess_impact.return_value = []
+    svc = CrawlService(
+        crawlers={"TEST": _make_crawler([_make_raw_event("OLD-001")], full_text="第一条 新正文。")},
+        event_store=store,
+        llm_pipeline=mock_pipeline,
+        retrieval_service=MagicMock(),
+        notification_store=MockNotificationStore(),
+        embedding_provider=MagicMock(),
+        vector_index=MagicMock(),
+    )
+    list(svc.run_crawl())
+
+    mock_pipeline.compute_diff.assert_not_called()
+    assert store.get(event_id)["raw_text"] == "第一条 新正文。"
+
+
+def test_new_event_creates_a_new_notification():
+    """A brand-new event must produce exactly one kind='new' notification."""
+    from app.application.perception.crawl_service import CrawlService
+
+    store = MockEventStore()
+    notifications = MockNotificationStore()
+    mock_pipeline = MagicMock()
+    mock_pipeline.extract_structure.return_value = {}
+    mock_pipeline.assess_impact.return_value = []
+    svc = CrawlService(
+        crawlers={"TEST": _make_crawler([_make_raw_event("NOTIF-NEW")])},
+        event_store=store,
+        llm_pipeline=mock_pipeline,
+        retrieval_service=MagicMock(),
+        notification_store=notifications,
+        embedding_provider=MagicMock(),
+        vector_index=MagicMock(),
+    )
+    list(svc.run_crawl())
+
+    items = notifications.list_for_user("any-user")
+    assert len(items) == 1
+    assert items[0]["kind"] == "new"
+
+
+def test_significant_change_creates_a_changed_notification():
+    """A numeric or deontic change must produce a kind='changed' notification."""
+    from app.application.perception.crawl_service import CrawlService
+
+    store = MockEventStore()
+    event_id = hashlib.sha256(b"TEST-SIG-001").hexdigest()[:12]
+    store.upsert({
+        "id": event_id, "standard_code": "SIG-001", "source": "TEST",
+        "title": "Test SIG-001", "summary": "", "impact_level": "medium",
+        "published_at": "2026-01-01", "tags": [],
+        "content_hash": "old-hash", "raw_text": "old body",
+    })
+    notifications = MockNotificationStore()
+    mock_pipeline = MagicMock()
+    mock_pipeline.extract_structure.return_value = {}
+    mock_pipeline.assess_impact.return_value = []
+    mock_pipeline.compute_diff.return_value = {
+        "changed_sections": [{"change_type": "modified", "numeric_changed": True, "deontic_changed": False}],
+        "change_summary": "1 paragraph changed (numeric).",
+    }
+    svc = CrawlService(
+        crawlers={"TEST": _make_crawler([_make_raw_event("SIG-001")], full_text="new body")},
+        event_store=store,
+        llm_pipeline=mock_pipeline,
+        retrieval_service=MagicMock(),
+        notification_store=notifications,
+        embedding_provider=MagicMock(),
+        vector_index=MagicMock(),
+    )
+    list(svc.run_crawl())
+
+    items = notifications.list_for_user("any-user")
+    assert len(items) == 1
+    assert items[0]["kind"] == "changed"
+
+
+def test_cosmetic_only_change_creates_no_notification():
+    """A change with no numeric/deontic/added/removed section must not notify."""
+    from app.application.perception.crawl_service import CrawlService
+
+    store = MockEventStore()
+    event_id = hashlib.sha256(b"TEST-COS-001").hexdigest()[:12]
+    store.upsert({
+        "id": event_id, "standard_code": "COS-001", "source": "TEST",
+        "title": "Test COS-001", "summary": "", "impact_level": "low",
+        "published_at": "2026-01-01", "tags": [],
+        "content_hash": "old-hash", "raw_text": "old body.",
+    })
+    notifications = MockNotificationStore()
+    mock_pipeline = MagicMock()
+    mock_pipeline.extract_structure.return_value = {}
+    mock_pipeline.assess_impact.return_value = []
+    mock_pipeline.compute_diff.return_value = {
+        "changed_sections": [{"change_type": "modified", "numeric_changed": False, "deontic_changed": False}],
+        "change_summary": "cosmetic only",
+    }
+    svc = CrawlService(
+        crawlers={"TEST": _make_crawler([_make_raw_event("COS-001")], full_text="old body")},
+        event_store=store,
+        llm_pipeline=mock_pipeline,
+        retrieval_service=MagicMock(),
+        notification_store=notifications,
+        embedding_provider=MagicMock(),
+        vector_index=MagicMock(),
+    )
+    list(svc.run_crawl())
+
+    assert notifications.list_for_user("any-user") == []
+
+
+def test_notification_store_failure_does_not_abort_the_crawl():
+    """A broken notification store must not stop the crawl or raise."""
+    from app.application.perception.crawl_service import CrawlService
+
+    store = MockEventStore()
+    broken_notifications = MagicMock()
+    broken_notifications.create.side_effect = RuntimeError("notification db down")
+    mock_pipeline = MagicMock()
+    mock_pipeline.extract_structure.return_value = {}
+    mock_pipeline.assess_impact.return_value = []
+    svc = CrawlService(
+        crawlers={"TEST": _make_crawler([_make_raw_event("BROKEN-001")])},
+        event_store=store,
+        llm_pipeline=mock_pipeline,
+        retrieval_service=MagicMock(),
+        notification_store=broken_notifications,
+        embedding_provider=MagicMock(),
+        vector_index=MagicMock(),
+    )
+    events = list(svc.run_crawl())
+
+    assert any(e.get("event") == "done" for e in events)
+    assert store.get_by_standard_code("BROKEN-001") is not None
+
+
+def test_new_event_is_indexed_in_the_knowledge_base():
+    """A brand-new event must be chunked, embedded, and upserted into Milvus."""
+    from app.application.perception.crawl_service import CrawlService
+
+    body = "第一条 本标准规定了车辆制动系统的技术要求。\n第二条 车辆制动系统应在时速50公里条件下于30米内完全停止。"
+    embedding_provider = MagicMock()
+    embedding_provider.embed_texts.return_value = [[0.1] * 8]
+    vector_index = MagicMock()
+    mock_pipeline = MagicMock()
+    mock_pipeline.extract_structure.return_value = {}
+    mock_pipeline.assess_impact.return_value = []
+    svc = CrawlService(
+        crawlers={"TEST": _make_crawler([_make_raw_event("IDX-NEW")], full_text=body)},
+        event_store=MockEventStore(),
+        llm_pipeline=mock_pipeline,
+        retrieval_service=MagicMock(),
+        notification_store=MockNotificationStore(),
+        embedding_provider=embedding_provider,
+        vector_index=vector_index,
+    )
+    list(svc.run_crawl())
+
+    event_id = hashlib.sha256(b"TEST-IDX-NEW").hexdigest()[:12]
+    vector_index.delete_by_document.assert_called_once_with(event_id)
+    vector_index.upsert.assert_called_once()
+    chunks_arg = vector_index.upsert.call_args.args[0]
+    assert len(chunks_arg) > 0
+
+
+def test_significant_change_reindexes_the_knowledge_base():
+    """A numeric/deontic change must delete the stale chunks and upsert new ones."""
+    from app.application.perception.crawl_service import CrawlService
+
+    store = MockEventStore()
+    event_id = hashlib.sha256(b"TEST-IDX-SIG").hexdigest()[:12]
+    store.upsert({
+        "id": event_id, "standard_code": "IDX-SIG", "source": "TEST",
+        "title": "Test IDX-SIG", "summary": "", "impact_level": "medium",
+        "published_at": "2026-01-01", "tags": [],
+        "content_hash": "old-hash", "raw_text": "old body",
+    })
+    embedding_provider = MagicMock()
+    embedding_provider.embed_texts.return_value = [[0.1] * 8]
+    vector_index = MagicMock()
+    mock_pipeline = MagicMock()
+    mock_pipeline.extract_structure.return_value = {}
+    mock_pipeline.assess_impact.return_value = []
+    mock_pipeline.compute_diff.return_value = {
+        "changed_sections": [{"change_type": "modified", "numeric_changed": True, "deontic_changed": False}],
+        "change_summary": "numeric change",
+    }
+    svc = CrawlService(
+        crawlers={"TEST": _make_crawler([_make_raw_event("IDX-SIG")], full_text="new body with a number 20米")},
+        event_store=store,
+        llm_pipeline=mock_pipeline,
+        retrieval_service=MagicMock(),
+        notification_store=MockNotificationStore(),
+        embedding_provider=embedding_provider,
+        vector_index=vector_index,
+    )
+    list(svc.run_crawl())
+
+    vector_index.delete_by_document.assert_called_once_with(event_id)
+    vector_index.upsert.assert_called_once()
+
+
+def test_cosmetic_only_change_does_not_touch_the_knowledge_base():
+    """A punctuation-only edit must not trigger embedding or a Milvus write."""
+    from app.application.perception.crawl_service import CrawlService
+
+    store = MockEventStore()
+    event_id = hashlib.sha256(b"TEST-IDX-COS").hexdigest()[:12]
+    store.upsert({
+        "id": event_id, "standard_code": "IDX-COS", "source": "TEST",
+        "title": "Test IDX-COS", "summary": "", "impact_level": "low",
+        "published_at": "2026-01-01", "tags": [],
+        "content_hash": "old-hash", "raw_text": "old body.",
+    })
+    embedding_provider = MagicMock()
+    vector_index = MagicMock()
+    mock_pipeline = MagicMock()
+    mock_pipeline.extract_structure.return_value = {}
+    mock_pipeline.assess_impact.return_value = []
+    mock_pipeline.compute_diff.return_value = {
+        "changed_sections": [{"change_type": "modified", "numeric_changed": False, "deontic_changed": False}],
+        "change_summary": "cosmetic only",
+    }
+    svc = CrawlService(
+        crawlers={"TEST": _make_crawler([_make_raw_event("IDX-COS")], full_text="old body")},
+        event_store=store,
+        llm_pipeline=mock_pipeline,
+        retrieval_service=MagicMock(),
+        notification_store=MockNotificationStore(),
+        embedding_provider=embedding_provider,
+        vector_index=vector_index,
+    )
+    list(svc.run_crawl())
+
+    embedding_provider.embed_texts.assert_not_called()
+    vector_index.upsert.assert_not_called()
+
+
+def test_vector_index_failure_does_not_abort_the_crawl():
+    """A broken vector index must not stop the crawl or raise."""
+    from app.application.perception.crawl_service import CrawlService
+
+    broken_vector_index = MagicMock()
+    broken_vector_index.upsert.side_effect = RuntimeError("milvus unreachable")
+    store = MockEventStore()
+    mock_pipeline = MagicMock()
+    mock_pipeline.extract_structure.return_value = {}
+    mock_pipeline.assess_impact.return_value = []
+    svc = CrawlService(
+        crawlers={"TEST": _make_crawler([_make_raw_event("IDX-FAIL")], full_text="第一条 正文内容。")},
+        event_store=store,
+        llm_pipeline=mock_pipeline,
+        retrieval_service=MagicMock(),
+        notification_store=MockNotificationStore(),
+        embedding_provider=MagicMock(embed_texts=MagicMock(return_value=[[0.1] * 8])),
+        vector_index=broken_vector_index,
+    )
+    events = list(svc.run_crawl())
+
+    assert any(e.get("event") == "done" for e in events)
+    assert store.get_by_standard_code("IDX-FAIL") is not None

backend/tests/perception/test_llm_pipeline.py

@@ -1,28 +1,34 @@
-"""Unit tests for LlmPipeline — mock LLM client and embedding provider."""
+"""Unit tests for LlmPipeline with a mocked LLM client.
+
+The pipeline no longer constructs an embedding provider: change detection moved
+to the deterministic RegulationDiffer, and the LLM is called only to explain
+changes that determinism already located. These tests pin that gating contract.
+"""
 from __future__ import annotations
+
 from unittest.mock import MagicMock, patch
-import json
-import pytest
 
 
-def _make_pipeline():
+def _make_pipeline(content: str | None = None):
-    with patch("app.infrastructure.perception.llm_pipeline.get_llm_client") as mock_llm_fn, \
+    """Build a pipeline whose LLM client is a mock returning `content`."""
-         patch("app.infrastructure.perception.llm_pipeline.OpenAICompatibleEmbeddingProvider") as mock_emb_cls:
+    default = (
-
+        '{"obligations":[{"text":"test obligation","deontic":"must","subject":"OEM",'
+        '"object":"system","condition":""}],"deadlines":[{"date":"2026-07-01",'
+        '"description":"实施截止"}],"scope":"适用于M1类车辆","penalties":"罚款",'
+        '"impact_level":"high"}'
+    )
+    with patch("app.infrastructure.perception.llm_pipeline.get_llm_client") as mock_llm_fn:
         mock_client = MagicMock()
-        mock_client.chat.return_value = MagicMock(content='{"obligations":[{"text":"test obligation","deontic":"must","subject":"OEM","object":"system","condition":""}],"deadlines":[{"date":"2026-07-01","description":"实施截止"}],"scope":"适用于M1类车辆","penalties":"罚款","impact_level":"high"}')
+        mock_client.chat.return_value = MagicMock(content=content or default)
         mock_llm_fn.return_value = mock_client
 
-        mock_emb = MagicMock()
-        mock_emb.embed_texts.return_value = [[0.1] * 1024, [0.9] * 1024]
-        mock_emb_cls.return_value = mock_emb
-
         from app.infrastructure.perception.llm_pipeline import LlmPipeline
-        return LlmPipeline(), mock_client, mock_emb
+        return LlmPipeline(), mock_client
 
 
 def test_extract_structure_returns_dict():
-    pipeline, mock_client, _ = _make_pipeline()
+    """Structure extraction still returns the enrichment keys callers expect."""
+    pipeline, _ = _make_pipeline()
     event = {
         "id": "evt-001",
         "standard_code": "GB 18384-2025",
@@ -38,8 +44,11 @@ def test_extract_structure_returns_dict():
 
 
 def test_assess_impact_returns_list():
-    pipeline, mock_client, _ = _make_pipeline()
+    """Impact assessment still returns a list of affected documents."""
-    mock_client.chat.return_value = MagicMock(content='[{"doc_id":"d1","doc_name":"Safety Manual","score":0.85,"key_clauses":"§4.2","recommendation":"更新第4章"}]')
+    pipeline, _ = _make_pipeline(
+        '[{"doc_id":"d1","doc_name":"Safety Manual","score":0.85,'
+        '"key_clauses":"§4.2","recommendation":"更新第4章"}]'
+    )
     mock_retrieval = MagicMock()
     chunk = MagicMock()
     chunk.doc_id = "d1"
@@ -53,25 +62,103 @@ def test_assess_impact_returns_list():
         "title": "电动汽车安全要求",
         "obligations": [{"text": "OEM shall comply"}],
     }
-    result = pipeline.assess_impact(event, mock_retrieval)
+    assert isinstance(pipeline.assess_impact(event, mock_retrieval), list)
-    assert isinstance(result, list)
 
 
-def test_compute_diff_no_change():
+def test_compute_diff_no_change_costs_no_llm_call():
-    pipeline, _, mock_emb = _make_pipeline()
+    """Identical text must short-circuit before reaching the model."""
-    mock_emb.embed_texts.return_value = [[0.5] * 1024, [0.5] * 1024]
+    pipeline, mock_client = _make_pipeline()
-    result = pipeline.compute_diff("paragraph one", "paragraph one")
+    mock_client.chat.reset_mock()
-    assert isinstance(result, dict)
+
-    assert "changed_sections" in result
+    result = pipeline.compute_diff("第一条 保持不变的条款。", "第一条 保持不变的条款。")
-    assert "change_summary" in result
+
+    assert result["changed_sections"] == []
+    assert "No substantive changes" in result["change_summary"]
+    mock_client.chat.assert_not_called()
 
 
-def test_compute_diff_detects_change():
+def test_compute_diff_classifies_a_real_change():
-    pipeline, mock_client, mock_emb = _make_pipeline()
+    """A gated change is classified and the model's legal_effect is surfaced."""
-    mock_emb.embed_texts.return_value = [
+    pipeline, _ = _make_pipeline(
-        [1.0] + [0.0] * 1023,
+        '{"change_type":"tightened","legal_effect":"Requirement tightened."}'
-        [0.0] + [1.0] + [0.0] * 1022,
+    )
-    ]
+    result = pipeline.compute_diff(
-    mock_client.chat.return_value = MagicMock(content='{"change_type":"tightened","summary":"Requirement tightened"}')
+        "第三条 生产企业应当每年开展一次安全评估。",
-    result = pipeline.compute_diff("old paragraph text", "new tighter requirement text")
+        "第三条 生产企业宜每年开展一次安全评估。",
-    assert isinstance(result["changed_sections"], list)
+    )
+
+    sections = result["changed_sections"]
+    assert len(sections) == 1
+    assert sections[0]["change_type"] == "tightened"
+    assert sections[0]["summary"] == "Requirement tightened."
+
+
+def test_numeric_change_overrides_the_model_label():
+    """A moved number wins over the model, which routinely calls it 'clarified'."""
+    pipeline, _ = _make_pipeline(
+        '{"change_type":"clarified","legal_effect":"Minor wording update."}'
+    )
+    result = pipeline.compute_diff(
+        "第二条 车辆制动系统应在30米内完全停止。",
+        "第二条 车辆制动系统应在20米内完全停止。",
+    )
+
+    section = result["changed_sections"][0]
+    assert section["numeric_changed"] is True
+    assert section["change_type"] == "numeric"
+
+
+def test_cosmetic_change_is_never_sent_to_the_model():
+    """Punctuation-only edits are recorded but must not cost a model call."""
+    pipeline, mock_client = _make_pipeline()
+    mock_client.chat.reset_mock()
+
+    result = pipeline.compute_diff(
+        "第五条 本标准由全国汽车标准化技术委员会归口管理。",
+        "第五条 本标准由全国汽车标准化技术委员会归口管理",
+    )
+
+    assert len(result["changed_sections"]) == 1
+    mock_client.chat.assert_not_called()
+
+
+def test_llm_failure_preserves_the_deterministic_record():
+    """A model error must not discard a change deterministic analysis proved real."""
+    pipeline, mock_client = _make_pipeline()
+    mock_client.chat.side_effect = RuntimeError("gateway down")
+
+    result = pipeline.compute_diff(
+        "第二条 车辆制动系统应在30米内完全停止。",
+        "第二条 车辆制动系统应在20米内完全停止。",
+    )
+
+    section = result["changed_sections"][0]
+    assert section["numeric_changed"] is True
+    assert section["change_type"] == "numeric"
+    assert section["summary"] == ""
+    assert "第二条" in section["old_text"]
+
+
+def test_only_gated_paragraphs_reach_the_model():
+    """One significant change among cosmetic ones yields exactly one model call."""
+    pipeline, mock_client = _make_pipeline(
+        '{"change_type":"tightened","legal_effect":"Tighter limit."}'
+    )
+    mock_client.chat.reset_mock()
+
+    old = "\n".join([
+        "第一条 本标准规定了车辆制动系统的技术要求。",
+        "第二条 车辆制动系统应在30米内完全停止。",
+        "第三条 本标准由全国汽车标准化技术委员会归口管理。",
+    ])
+    new = "\n".join([
+        "第一条 本标准规定了车辆制动系统的技术要求。",
+        "第二条 车辆制动系统应在20米内完全停止。",
+        "第三条 本标准由全国汽车标准化技术委员会归口管理",
+    ])
+
+    result = pipeline.compute_diff(old, new)
+
+    # Two paragraphs changed; only the numeric one clears the gate.
+    assert len(result["changed_sections"]) == 2
+    assert mock_client.chat.call_count == 1

backend/tests/perception/test_notification_store.py

@@ -0,0 +1,83 @@
+"""Tests for the notification store's per-user read-state contract.
+
+These pin the core property that makes broadcast-to-everyone work without a
+subscription model: one notification row is shared by all users, and each
+user's read state is tracked independently against it.
+"""
+from __future__ import annotations
+
+from app.infrastructure.perception.mock_notification_store import MockNotificationStore
+
+
+def _store_with_one_notification() -> MockNotificationStore:
+    store = MockNotificationStore()
+    store.create(
+        event_id="evt-001",
+        kind="new",
+        title="《电动汽车安全要求》国家标准第三版正式发布",
+        impact_level="high",
+        summary=None,
+    )
+    return store
+
+
+def test_a_new_notification_is_unread_for_everyone():
+    """Nobody has read it yet, so unread_count is 1 for any user."""
+    store = _store_with_one_notification()
+    assert store.unread_count("user-a") == 1
+    assert store.unread_count("user-b") == 1
+
+
+def test_mark_all_read_zeroes_the_count_for_that_user():
+    """Reading clears the count for the user who read it."""
+    store = _store_with_one_notification()
+    marked = store.mark_all_read("user-a")
+    assert marked == 1
+    assert store.unread_count("user-a") == 0
+
+
+def test_one_users_read_state_does_not_affect_another():
+    """The whole point of read receipts over per-user fan-out: independence."""
+    store = _store_with_one_notification()
+    store.mark_all_read("user-a")
+    assert store.unread_count("user-a") == 0
+    assert store.unread_count("user-b") == 1
+
+
+def test_list_for_user_reports_the_read_flag_correctly():
+    """The list endpoint must reflect this user's own read state per item."""
+    store = _store_with_one_notification()
+    store.mark_all_read("user-a")
+
+    items_a = store.list_for_user("user-a")
+    items_b = store.list_for_user("user-b")
+
+    assert len(items_a) == 1
+    assert items_a[0]["read"] is True
+    assert items_b[0]["read"] is False
+
+
+def test_list_for_user_orders_newest_first():
+    """Notifications appear most-recent-first regardless of creation order."""
+    store = MockNotificationStore()
+    store.create(event_id="evt-1", kind="new", title="first", impact_level="low", summary=None)
+    store.create(event_id="evt-2", kind="new", title="second", impact_level="low", summary=None)
+
+    items = store.list_for_user("user-a")
+
+    assert [item["title"] for item in items] == ["second", "first"]
+
+
+def test_mark_all_read_is_a_no_op_on_an_empty_feed():
+    """Reading an empty feed must not raise and reports zero marked."""
+    store = MockNotificationStore()
+    assert store.mark_all_read("user-a") == 0
+
+
+def test_mark_all_read_does_not_recount_already_read_notifications():
+    """Calling mark_all_read twice must not double-count as newly marked."""
+    store = _store_with_one_notification()
+    first = store.mark_all_read("user-a")
+    second = store.mark_all_read("user-a")
+    assert first == 1
+    assert second == 0

backend/tests/perception/test_perception_notification_routes.py

@@ -0,0 +1,72 @@
+"""Tests for the notification API routes.
+
+Follows the same direct-call convention as backend/tests/mcp/test_mcp_status.py:
+patch the bootstrap singleton getter where the route module imports it, then
+call the async route function directly with asyncio.run rather than standing
+up a FastAPI TestClient — this repo has no existing TestClient harness, and
+these route handlers are thin enough that exercising them directly tests the
+same logic without inventing a new testing convention for two pass-through
+endpoints.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from unittest.mock import patch
+
+from app.domain.auth.models import UserClaims, UserRole
+from app.infrastructure.perception.mock_notification_store import MockNotificationStore
+
+
+def _user(user_id: str) -> UserClaims:
+    return UserClaims(user_id=user_id, username=user_id, role=UserRole.READONLY)
+
+
+def _list_notifications(store, user_id: str, limit: int = 20) -> dict:
+    from app.api.routes.perception import list_notifications
+
+    with patch("app.api.routes.perception.get_notification_store", return_value=store):
+        return asyncio.run(list_notifications(limit=limit, current_user=_user(user_id)))
+
+
+def _mark_read(store, user_id: str) -> dict:
+    from app.api.routes.perception import mark_notifications_read
+
+    with patch("app.api.routes.perception.get_notification_store", return_value=store):
+        return asyncio.run(mark_notifications_read(current_user=_user(user_id)))
+
+
+def test_a_fresh_user_sees_the_notification_as_unread():
+    """GET .../notifications reports the caller's own unread_count."""
+    store = MockNotificationStore()
+    store.create(event_id="evt-1", kind="new", title="新法规发布", impact_level="high", summary=None)
+
+    result = _list_notifications(store, "user-a")
+
+    assert result["unread_count"] == 1
+    assert len(result["items"]) == 1
+    assert result["items"][0]["read"] is False
+
+
+def test_mark_read_zeroes_a_subsequent_get():
+    """POST .../read must clear unread_count for the next GET by the same user."""
+    store = MockNotificationStore()
+    store.create(event_id="evt-1", kind="new", title="新法规发布", impact_level="high", summary=None)
+
+    marked = _mark_read(store, "user-a")
+    result = _list_notifications(store, "user-a")
+
+    assert marked == {"marked": 1}
+    assert result["unread_count"] == 0
+    assert result["items"][0]["read"] is True
+
+
+def test_mark_read_for_one_user_does_not_affect_another():
+    """Read state is per-user — the whole point of the read-receipt design."""
+    store = MockNotificationStore()
+    store.create(event_id="evt-1", kind="new", title="新法规发布", impact_level="high", summary=None)
+
+    _mark_read(store, "user-a")
+    result_b = _list_notifications(store, "user-b")
+
+    assert result_b["unread_count"] == 1

backend/tests/perception/test_perception_tasks.py

@@ -0,0 +1,77 @@
+"""Tests for the scheduled crawl Celery task.
+
+These pin the draining contract: the task must consume every item from
+CrawlService.run_crawl(), tally per-source errors without raising on them, and
+let a genuine whole-crawl exception propagate rather than swallowing it.
+
+Patches target app.shared.bootstrap.get_crawl_service — not
+perception_tasks.get_crawl_service — because the task imports it inside its
+own function body (see perception_tasks.py's docstring for why), so there is
+no module-level name in perception_tasks to intercept.
+"""
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+
+def _fake_crawl_service(events):
+    """Build a fake whose run_crawl() yields the given fixed event sequence."""
+    service = MagicMock()
+    service.run_crawl.return_value = iter(events)
+    return service
+
+
+def test_task_drains_generator_and_summarizes_errors():
+    """One source error among two must not stop the run or raise."""
+    events = [
+        {"event": "progress", "data": {"source": "CATARC", "stage": "fetching"}},
+        {"event": "error", "data": {"source": "CATARC", "message": "timeout"}},
+        {"event": "progress", "data": {"source": "EUR-Lex", "stage": "fetching"}},
+        {"event": "done", "data": {"total_new": 2, "total_updated": 1}},
+    ]
+    with patch(
+        "app.shared.bootstrap.get_crawl_service",
+        return_value=_fake_crawl_service(events),
+    ):
+        from app.infrastructure.tasks.perception_tasks import crawl_regulations_task
+        result = crawl_regulations_task()
+
+    assert result == {"new": 2, "updated": 1, "source_errors": 1}
+
+
+def test_task_reports_zero_errors_on_a_clean_run():
+    """A run with no source errors must report source_errors: 0."""
+    events = [
+        {"event": "progress", "data": {"source": "CATARC", "stage": "fetching"}},
+        {"event": "done", "data": {"total_new": 0, "total_updated": 0}},
+    ]
+    with patch(
+        "app.shared.bootstrap.get_crawl_service",
+        return_value=_fake_crawl_service(events),
+    ):
+        from app.infrastructure.tasks.perception_tasks import crawl_regulations_task
+        result = crawl_regulations_task()
+
+    assert result == {"new": 0, "updated": 0, "source_errors": 0}
+
+
+def test_whole_crawl_exception_is_not_swallowed():
+    """A failure below run_crawl's own error handling must propagate.
+
+    Per-source failures are already handled inside run_crawl and never raise;
+    an exception escaping the generator entirely means something unexpected
+    broke, and Celery's own failure handling — not a silent catch here — is
+    the intended backstop.
+    """
+    broken_service = MagicMock()
+    broken_service.run_crawl.side_effect = RuntimeError("event store unreachable")
+
+    with patch(
+        "app.shared.bootstrap.get_crawl_service",
+        return_value=broken_service,
+    ):
+        from app.infrastructure.tasks.perception_tasks import crawl_regulations_task
+        with pytest.raises(RuntimeError, match="event store unreachable"):
+            crawl_regulations_task()

backend/tests/perception/test_postgres_event_store.py

@@ -4,14 +4,8 @@ import json
 from unittest.mock import MagicMock, patch
 import pytest
 
-# Patch psycopg2 before importing the module under test
+# psycopg2 is mocked centrally in backend/tests/conftest.py, so importing the
-import sys
+# module under test here never binds the real driver.
-mock_psycopg2 = MagicMock()
-mock_psycopg2.extras = MagicMock()
-sys.modules.setdefault("psycopg2", mock_psycopg2)
-sys.modules.setdefault("psycopg2.extras", mock_psycopg2.extras)
-sys.modules.setdefault("psycopg2.pool", MagicMock())
-
 from app.infrastructure.perception.base_event_store import BaseEventStore
 
 

backend/tests/perception/test_regulation_differ.py

@@ -0,0 +1,157 @@
+"""Tests for the deterministic regulation differ.
+
+These tests pin the behaviour that the previous cosine-similarity implementation
+could not deliver: real regulatory edits (numeric limits, deontic modals) must be
+detected, and inserting a paragraph must not report unrelated paragraphs as
+changed. Everything here runs offline — no LLM, no network, no embeddings.
+"""
+
+from __future__ import annotations
+
+from app.infrastructure.perception.regulation_differ import RegulationDiffer
+
+
+def _differ() -> RegulationDiffer:
+    """Build a differ with an explicit ratio so tests never depend on .env."""
+    return RegulationDiffer(min_change_ratio=0.02)
+
+
+def test_identical_documents_report_no_changes():
+    """An unchanged regulation must produce an empty change list."""
+    text = "第一条 车辆制动系统应在时速50公里条件下于30米内完全停止。\n第二条 驾驶员座椅面料的阻燃性能应符合附录B的规定。"
+    assert _differ().diff(text, text) == []
+
+
+def test_numeric_tightening_is_detected():
+    """A changed numeric limit is the case cosine similarity scored 0.9153 and missed."""
+    old = "第一条 车辆制动系统应在时速50公里条件下于30米内完全停止。"
+    new = "第一条 车辆制动系统应在时速50公里条件下于20米内完全停止。"
+
+    changes = _differ().diff(old, new)
+
+    assert len(changes) == 1
+    change = changes[0]
+    assert change.change_type == "modified"
+    assert change.numeric_changed is True
+    assert change.needs_llm is True
+
+
+def test_deontic_relaxation_is_detected():
+    """Weakening 应当 to 宜 changes the legal force and must be flagged."""
+    old = "第三条 生产企业应当每年开展一次安全评估。"
+    new = "第三条 生产企业宜每年开展一次安全评估。"
+
+    changes = _differ().diff(old, new)
+
+    assert len(changes) == 1
+    assert changes[0].deontic_changed is True
+    assert changes[0].needs_llm is True
+
+
+def test_prohibition_removal_is_detected():
+    """Dropping 不得 flips a prohibition into a permission."""
+    old = "第四条 车辆不得使用未经认证的电池组。"
+    new = "第四条 车辆可以使用经备案的电池组。"
+
+    changes = _differ().diff(old, new)
+
+    assert len(changes) == 1
+    assert changes[0].deontic_changed is True
+
+
+def test_inserted_paragraph_does_not_shift_the_rest():
+    """Regression test for positional alignment.
+
+    The previous implementation compared old[i] to new[i], so inserting one
+    paragraph at the top reported every following paragraph as changed. With
+    sequence alignment only the inserted paragraph is new.
+    """
+    old = "\n".join([
+        "第一条 本标准规定了车辆制动系统的技术要求。",
+        "第二条 车辆制动系统应在时速50公里条件下于30米内完全停止。",
+        "第三条 驾驶员座椅面料的阻燃性能应符合附录B的规定。",
+    ])
+    new = "\n".join([
+        "第零条 本标准适用于所有M1类车辆。",
+        "第一条 本标准规定了车辆制动系统的技术要求。",
+        "第二条 车辆制动系统应在时速50公里条件下于30米内完全停止。",
+        "第三条 驾驶员座椅面料的阻燃性能应符合附录B的规定。",
+    ])
+
+    changes = _differ().diff(old, new)
+
+    assert len(changes) == 1, f"expected only the inserted paragraph, got {changes}"
+    assert changes[0].change_type == "added"
+    assert "第零条" in changes[0].new_text
+    assert changes[0].old_text == ""
+
+
+def test_deleted_paragraph_is_reported_once():
+    """Removing a provision yields exactly one 'removed' record."""
+    old = "\n".join([
+        "第一条 本标准规定了车辆制动系统的技术要求。",
+        "第二条 车辆制动系统应在时速50公里条件下于30米内完全停止。",
+        "第三条 驾驶员座椅面料的阻燃性能应符合附录B的规定。",
+    ])
+    new = "\n".join([
+        "第一条 本标准规定了车辆制动系统的技术要求。",
+        "第三条 驾驶员座椅面料的阻燃性能应符合附录B的规定。",
+    ])
+
+    changes = _differ().diff(old, new)
+
+    assert len(changes) == 1
+    assert changes[0].change_type == "removed"
+    assert "第二条" in changes[0].old_text
+    assert changes[0].new_text == ""
+    assert changes[0].needs_llm is True
+
+
+def test_trivial_edit_is_not_sent_to_the_llm():
+    """A cosmetic edit with no number or modal change must not cost an LLM call."""
+    old = "第五条 本标准由全国汽车标准化技术委员会归口管理。"
+    new = "第五条 本标准由全国汽车标准化技术委员会归口管理"
+
+    changes = _differ().diff(old, new)
+
+    for change in changes:
+        assert change.numeric_changed is False
+        assert change.deontic_changed is False
+        assert change.needs_llm is False, f"trivial edit was gated to the LLM: {change}"
+
+
+def test_large_rewrite_is_sent_to_the_llm():
+    """A substantial rewrite clears the change-ratio gate even without numbers or modals."""
+    old = "第六条 本标准参考了国际同类标准的相关内容。"
+    new = "第六条 本条款描述了完全不同的主题内容，涉及整车认证流程与型式试验的组织安排。"
+
+    changes = _differ().diff(old, new)
+
+    assert len(changes) == 1
+    assert changes[0].change_ratio >= 0.02
+    assert changes[0].needs_llm is True
+
+
+def test_empty_old_text_yields_no_changes():
+    """A first crawl has no baseline, so there is nothing to diff."""
+    assert _differ().diff("", "第一条 任意内容。") == []
+
+
+def test_unchanged_paragraphs_are_never_returned():
+    """Only changed paragraphs appear; equal ones are dropped."""
+    old = "\n".join([
+        "第一条 保持不变的条款。",
+        "第二条 车辆制动距离不得超过30米。",
+        "第三条 另一条保持不变的条款。",
+    ])
+    new = "\n".join([
+        "第一条 保持不变的条款。",
+        "第二条 车辆制动距离不得超过20米。",
+        "第三条 另一条保持不变的条款。",
+    ])
+
+    changes = _differ().diff(old, new)
+
+    assert len(changes) == 1
+    assert changes[0].numeric_changed is True
+    assert "第二条" in changes[0].old_text

docs/architecture/backend-project-architecture.md

@@ -206,6 +206,7 @@
 ```text
 backend/app/
   api/
+  mcp/
   application/
     documents/
     knowledge/
@@ -314,6 +315,53 @@ backend/app/
 - `backend/app/shared/bootstrap.py` 是现阶段的 composition root，负责把端口实现、基础设施适配器和 application service 连接起来。
 - 后续如果新增 wiring 入口，应继续保持在同一类装配边界内，不要把依赖装配拆回各个路由或 service 构造函数中。
 
+### 4.6 `mcp`
+
+职责：
+
+- 以 Model Context Protocol 对外暴露平台已有能力
+- MCP tool 注册与入参 schema 绑定
+- MCP 专用鉴权（复用现有 JWT）与 Streamable HTTP 子 ASGI 应用装配
+- MCP 传输自身的可观测性：进程内 per-tool 调用计数（`stats.py`），以及供 System Status 页面读取的状态汇总 `get_mcp_status()`
+
+非职责：
+
+- 不实现任何新的检索、问答或业务编排逻辑
+- 不直接访问 Milvus、MinIO、LLM SDK
+- 不统计 token 消耗 —— MCP 调用经由 `AgentConversationService.ask()`，已由 `shared/model_usage_tracker.py` 记账
+
+说明：
+
+- `mcp` 与 `api` 是并列的两个 transport 适配层：`api` 面向 HTTP REST 客户端，`mcp` 面向 MCP 客户端（Claude Desktop、IDE 等）。二者共用同一套 application service。
+- 它独立成顶层模块而不是放进 `api/routes/`，因为 MCP 使用装饰器式 tool 注册和自带的子 ASGI 应用，与 `APIRouter` 是不同的传输机制。
+- 当前实现见 `backend/app/mcp/server.py`，只暴露 `search_regulations` 一个 tool，内部直接调用 `get_agent_conversation_service()`。
+- `api/routes/status.py` 的 `GET /status/mcp` 是薄适配层：它只负责解析对外可达的 URL（`settings.mcp_public_url` 或从请求推导），其余全部交给 `mcp.server.get_mcp_status()`，路由不得直接读取 MCP 内部结构。
+
+### 4.7 `perception`
+
+职责：
+
+- 爬取外部法规源（CATARC、国标委强制性/推荐性、EUR-Lex）的列表页与正文（`infrastructure/perception/crawlers/`）
+- 基于内容哈希的变更检测入口，以及**确定性**的段落级差异分析（`regulation_differ.py`：对齐 + 字符级 diff + 数字/情态词/新增删除闸门），只有通过闸门的段落才调用 LLM 分类（`llm_pipeline.py`）
+- 站内通知的广播存储与每用户已读状态（`base_notification_store.py` 及 Mock/Postgres 实现）——广播给所有登录用户，不做订阅/角色过滤
+- 通过 Celery Beat 定时调度全量爬取（`infrastructure/tasks/perception_tasks.py`），调度间隔由 `perception_crawl_interval_seconds` 配置
+- 新事件或"显著变更"（数字/情态词变化，或整段增删）自动写入知识库：本地 markdown 分块（`LocalRegulationChunkBuilder`，与 `chunk_backend=aliyun` 的上传流程无关）→ 复用既有 `embedding_provider`/`vector_index` → 写入与 `/documents` 上传管线**同一个** Milvus collection
+
+非职责：
+
+- 不维护第二套知识库或第二套向量索引——爬取入库与手动上传共用 `get_embedding_provider()` / `get_vector_index()` 这两个端口实现，二者在检索侧不可区分
+- 不做外部推送渠道（Email/Teams/飞书/钉钉）——当前部署无 SMTP/Webhook 凭据，做了也无法验证；只做站内通知
+- 不做订阅/偏好引擎——所有登录用户收到同一份广播，按用户区分的只有"已读"状态
+- 不做整改任务追踪（责任人、期限、验收、证据归档）——PPT 原文将其标注为"扩展功能"，规模上属独立子项目，尚未开始
+- 变更检测判据不依赖 embedding 余弦相似度——该方法被证明无法区分数值/情态词变化（如"30米"→"20米"、"应当"→"宜"），已被字符级 diff + 语言学规则取代
+
+说明：
+
+- `application/perception/crawl_service.py` 的 `CrawlService.run_crawl()` 是本模块的核心编排：单个事件的每一步（结构抽取、影响评估、diff、通知、知识库索引）各自 try/except 包裹，任一步失败只记警告、不中断整次爬取。
+- `_is_significant()` 与 `should_index` 是同一份判据，被通知创建和知识库索引两处复用，避免出现"值得通知"和"值得入库"两套互相漂移的标准。
+- `postgres_event_store.py` / `postgres_notification_store.py` 与对应的 Mock 实现共享同一个开关 `settings.document_repository_backend == "postgres"`，与文档处理模块的 backend 切换方式一致。
+- MinIO 上的 `raw_storage_key` 字段（schema 中声明）目前无人写入；正文改为直接存 `regulation_events.raw_text` 列，供下次爬取做基线对比。
+
 ## 5. Module Responsibilities
 
 ### 5.1 `api`
@@ -637,6 +685,7 @@ infrastructure -> external systems
 具体规则如下：
 
 - `api` 可以依赖 `application` 和 API 自己的 request/response models
+- `mcp` 与 `api` 同级，只能依赖 `application` 和 composition root，不能依赖 `infrastructure` 或反过来被 `application` 依赖
 - `application` 只能依赖 `domain`、端口接口，以及通过 composition root 注入进来的实现实例
 - `domain` 不能依赖 `api` 或 `infrastructure`
 - `infrastructure` 可以依赖 `domain` 定义的端口和数据模型，但不能反向驱动 application 逻辑

docs/superpowers/plans/2026-07-29-mcp-search-regulations.md

@@ -0,0 +1,486 @@
+# MCP Regulation Search Server — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [x]`) syntax for tracking.
+
+**Goal:** Expose the existing compliance knowledge base as an MCP tool (`search_regulations`) via a standalone `backend/app/mcp/` module, mounted into the existing FastAPI backend over Streamable HTTP, reusing existing JWT auth and the existing `AgentConversationService`.
+
+**Architecture:** A new top-level `backend/app/mcp/server.py` builds a `FastMCP` instance with one `@mcp.tool()`-decorated `search_regulations` function that calls the existing `get_agent_conversation_service().ask(...)` (zero new business logic). A small `MCPAuthMiddleware` ASGI middleware validates the existing JWT bearer scheme in front of the mounted MCP app. `backend/app/api/main.py` mounts the resulting ASGI app at `/mcp` and wires its lifespan into the existing `lifespan()` function via `AsyncExitStack` (required — `app.mount()` does not propagate nested ASGI lifespans, so without this the MCP session manager never starts and every tool call fails).
+
+**Tech Stack:** Python 3.12, FastAPI, Starlette, official `mcp` SDK (`mcp.server.fastmcp.FastMCP`), pytest, unittest.mock, Starlette `TestClient`.
+
+## Global Constraints
+
+- Design source of truth: `docs/superpowers/specs/2026-07-29-mcp-search-regulations-design.md`.
+- **Correction discovered during implementation:** the `mcp` package's latest release is `2.0.0`, which renamed `FastMCP` to `MCPServer` (`mcp.server.MCPServer`) and its client helper `streamablehttp_client` to `streamable_http_client`. `mcp>=2.0.0` is pinned in `requirements.txt` (not `>=1.9.0` as originally estimated below) since the shipped code uses the `MCPServer` name. Also discovered: `MCPServer.streamable_http_app()` defaults to registering its route at `/mcp`, requiring `streamable_http_path="/"` to avoid a doubled `/mcp/mcp` when mounted at `/mcp`; the effective client URL is `/mcp/` (trailing slash, due to Starlette's `Mount` redirect behavior).
+- All comments and docstrings in `backend/**/*.py` must be in English; every function/method needs a docstring; every file (including `__init__.py`) needs a module docstring + at least one meaningful `#` comment (`AGENTS.md`).
+- No new business orchestration — `search_regulations` is a thin protocol adapter over the existing `AgentConversationService`, same tier as `app/api/routes/agent.py`.
+- Python interpreter for this repo checkout: `C:\software\Python312\python.exe` (no `.venv` present in this checkout; this is the interpreter with all project dependencies already installed and is what the previous session's work was verified against).
+- Verified baseline test command (run from repo root, before any change in this plan): `C:\software\Python312\python.exe -m pytest backend/tests -q` → `69 passed` (9.10s). Re-run this after every task.
+- Confirmed via direct import check: `starlette` is installed and `starlette.testclient.TestClient` works; the `mcp` package is **not yet installed** (`ModuleNotFoundError: No module named 'mcp'`) — Task 3 installs it.
+- Latest published `mcp` version on PyPI at plan time: `2.0.0`. Pin `mcp>=1.9.0` in requirements (first version line with stable `streamable_http_app()` support) and let pip resolve to latest.
+
+---
+
+### Task 1: `search_regulations` MCP tool
+
+**Files:**
+- Create: `backend/app/mcp/__init__.py`
+- Create: `backend/app/mcp/server.py` (tool definition only — middleware and ASGI app builder added in Task 2)
+- Create: `backend/tests/mcp/__init__.py`
+- Create: `backend/tests/mcp/test_search_regulations_tool.py`
+
+**Interfaces:**
+- Consumes: `app.shared.bootstrap.get_agent_conversation_service()` (existing, returns `AgentConversationService`).
+- Produces: `app.mcp.server.search_regulations(query: str, top_k: int = 5) -> dict` — a plain function (before the `@mcp.tool()` decorator is applied, it remains directly callable/testable; the decorator only adds MCP schema metadata, it does not change the function's Python call signature or return value).
+
+- [x] **Step 1: Write the failing test**
+
+Create `backend/tests/mcp/__init__.py`:
+
+```python
+"""Test package for the MCP module (backend/app/mcp/)."""
+# Empty package marker — no shared fixtures needed yet for this small test suite.
+```
+
+Create `backend/tests/mcp/test_search_regulations_tool.py`:
+
+```python
+"""Unit tests for the search_regulations MCP tool function.
+
+Mocks AgentConversationService so no real retrieval/LLM call happens —
+verifies only the protocol-adapter contract: correct call shape in,
+correct dict shape out.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from unittest.mock import MagicMock, patch
+
+
+@dataclass
+class _FakeSource:
+    """Minimal stand-in for a real Source dataclass (only __dict__ is used)."""
+
+    doc_id: str
+    doc_title: str
+    score: float
+
+
+@dataclass
+class _FakeAnswerResult:
+    """Minimal stand-in for AnswerResult — only .answer/.sources are read."""
+
+    answer: str
+    sources: list
+
+
+def test_search_regulations_calls_agent_ask_without_session():
+    """search_regulations must call ask() with no session_id (stateless search)."""
+    from app.mcp.server import search_regulations
+
+    fake_service = MagicMock()
+    fake_service.ask.return_value = (
+        None,
+        _FakeAnswerResult(answer="国六排放标准要求...", sources=[_FakeSource("doc-1", "国六标准", 0.9)]),
+    )
+
+    with patch("app.mcp.server.get_agent_conversation_service", return_value=fake_service):
+        result = search_regulations(query="国六排放标准最新要求", top_k=3)
+
+    fake_service.ask.assert_called_once_with(query="国六排放标准最新要求", top_k=3)
+    assert "session_id" not in fake_service.ask.call_args.kwargs
+
+
+def test_search_regulations_shapes_response_dict():
+    """The returned dict must expose 'answer' and 'sources' (list of plain dicts)."""
+    from app.mcp.server import search_regulations
+
+    fake_service = MagicMock()
+    fake_service.ask.return_value = (
+        None,
+        _FakeAnswerResult(answer="答案文本", sources=[_FakeSource("doc-2", "国标GB1589", 0.8)]),
+    )
+
+    with patch("app.mcp.server.get_agent_conversation_service", return_value=fake_service):
+        result = search_regulations(query="q")
+
+    assert result == {
+        "answer": "答案文本",
+        "sources": [{"doc_id": "doc-2", "doc_title": "国标GB1589", "score": 0.8}],
+    }
+
+
+def test_search_regulations_default_top_k():
+    """top_k defaults to 5 when the caller omits it."""
+    from app.mcp.server import search_regulations
+
+    fake_service = MagicMock()
+    fake_service.ask.return_value = (None, _FakeAnswerResult(answer="a", sources=[]))
+
+    with patch("app.mcp.server.get_agent_conversation_service", return_value=fake_service):
+        search_regulations(query="q")
+
+    assert fake_service.ask.call_args.kwargs["top_k"] == 5
+```
+
+Run it — confirm it fails on import (`app.mcp.server` does not exist yet):
+
+```powershell
+C:\software\Python312\python.exe -m pytest backend/tests/mcp/test_search_regulations_tool.py -v
+```
+
+- [x] **Step 2: Implement the tool**
+
+Create `backend/app/mcp/__init__.py`:
+
+```python
+"""MCP (Model Context Protocol) server module.
+
+Exposes selected read-only platform capabilities — currently only regulation
+search — as MCP tools so external MCP clients (Claude Desktop, GitHub Copilot,
+Cursor, etc.) can query this platform's compliance knowledge base directly.
+"""
+# Kept deliberately empty beyond this docstring — see server.py for the
+# actual FastMCP instance and tool/middleware definitions.
+```
+
+Create `backend/app/mcp/server.py`:
+
+```python
+"""FastMCP server exposing the compliance knowledge base as an MCP tool.
+
+This module is a pure protocol adapter: search_regulations() below calls the
+existing AgentConversationService.ask() (the same application service backing
+the /api/v1/agent/ask REST endpoint) and reshapes its result into a plain
+dict. No new retrieval, ranking, or LLM orchestration logic lives here.
+"""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+
+from app.shared.bootstrap import get_agent_conversation_service
+
+# Single shared FastMCP instance — analogous to the single shared FastAPI
+# `app` instance in app/api/main.py. Tools registered via @mcp.tool() below.
+mcp = FastMCP("ai-regulations")
+
+
+@mcp.tool()
+def search_regulations(query: str, top_k: int = 5) -> dict:
+    """Search the compliance knowledge base and return a grounded answer.
+
+    query: Natural-language search question, e.g. "国六排放标准最新要求".
+    top_k: Maximum number of cited sources to return (default 5).
+    """
+    # No session_id is passed: this keeps each call stateless (no
+    # ConversationStore reads/writes), matching "search" semantics rather
+    # than multi-turn chat semantics.
+    _, result = get_agent_conversation_service().ask(query=query, top_k=top_k)
+    return {
+        "answer": result.answer,
+        "sources": [source.__dict__ for source in result.sources],
+    }
+```
+
+- [x] **Step 3: Run the test — confirm it passes**
+
+```powershell
+C:\software\Python312\python.exe -m pytest backend/tests/mcp/test_search_regulations_tool.py -v
+```
+
+Expected: 3 passed. Note: this step imports `mcp.server.fastmcp`, which is not yet installed — if it fails with `ModuleNotFoundError: No module named 'mcp'`, that is expected until Task 3 installs the dependency; run `C:\software\Python312\python.exe -m pip install "mcp>=1.9.0"` locally first so this task's tests can actually execute now (Task 3 formalizes the requirements.txt entry — installing it now is just so this task's own tests are green before moving on).
+
+---
+
+### Task 2: `MCPAuthMiddleware` — reuse existing JWT auth
+
+**Files:**
+- Modify: `backend/app/mcp/server.py` (add middleware + ASGI app builder)
+- Create: `backend/tests/mcp/test_mcp_auth_middleware.py`
+
+**Interfaces:**
+- Consumes: `app.config.settings.settings.auth_enabled` (existing), `app.shared.bootstrap.get_jwt_handler()` (existing, returns `JWTHandler`).
+- Produces: `app.mcp.server.MCPAuthMiddleware` (ASGI middleware class), `app.mcp.server.build_mcp_asgi_app() -> ASGIApp` (returns `mcp.streamable_http_app()` with the middleware already attached). Task 3's `main.py` change consumes `build_mcp_asgi_app()` directly — it does not need to attach the middleware itself.
+
+- [x] **Step 1: Write the failing test**
+
+Create `backend/tests/mcp/test_mcp_auth_middleware.py`:
+
+```python
+"""Unit tests for MCPAuthMiddleware.
+
+Wraps a minimal dummy ASGI app (not the real MCP app) so these tests exercise
+only the auth gate, not the MCP protocol itself — keeps the test fast and
+independent of FastMCP internals.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import patch
+
+from starlette.applications import Starlette
+from starlette.responses import PlainTextResponse
+from starlette.routing import Route
+from starlette.testclient import TestClient
+
+from app.mcp.server import MCPAuthMiddleware
+
+
+def _dummy_app() -> Starlette:
+    """Build a minimal Starlette app that MCPAuthMiddleware can wrap."""
+    async def _ok(request):
+        """Return a fixed 200 response so tests can assert pass-through."""
+        return PlainTextResponse("ok")
+
+    app = Starlette(routes=[Route("/ping", _ok)])
+    app.add_middleware(MCPAuthMiddleware)
+    return app
+
+
+def test_missing_token_rejected_when_auth_enabled():
+    """No Authorization header + auth_enabled=True -> 401."""
+    with patch("app.mcp.server.settings") as fake_settings:
+        fake_settings.auth_enabled = True
+        client = TestClient(_dummy_app())
+        response = client.get("/ping")
+    assert response.status_code == 401
+
+
+def test_invalid_token_rejected_when_auth_enabled():
+    """A token that fails decode_token() -> 401, request never reaches the app."""
+    fake_handler = type("H", (), {"decode_token": lambda self, t: (_ for _ in ()).throw(ValueError("bad token"))})()
+    with patch("app.mcp.server.settings") as fake_settings, \
+         patch("app.mcp.server.get_jwt_handler", return_value=fake_handler):
+        fake_settings.auth_enabled = True
+        client = TestClient(_dummy_app())
+        response = client.get("/ping", headers={"Authorization": "Bearer garbage"})
+    assert response.status_code == 401
+
+
+def test_valid_token_passes_through_when_auth_enabled():
+    """A token that decodes successfully -> request reaches the wrapped app."""
+    fake_handler = type("H", (), {"decode_token": lambda self, t: object()})()
+    with patch("app.mcp.server.settings") as fake_settings, \
+         patch("app.mcp.server.get_jwt_handler", return_value=fake_handler):
+        fake_settings.auth_enabled = True
+        client = TestClient(_dummy_app())
+        response = client.get("/ping", headers={"Authorization": "Bearer good"})
+    assert response.status_code == 200
+    assert response.text == "ok"
+
+
+def test_auth_disabled_always_passes_through():
+    """auth_enabled=False (dev mode) -> no token needed, matches get_current_user's dev bypass."""
+    with patch("app.mcp.server.settings") as fake_settings:
+        fake_settings.auth_enabled = False
+        client = TestClient(_dummy_app())
+        response = client.get("/ping")
+    assert response.status_code == 200
+```
+
+Run it — confirm it fails (`MCPAuthMiddleware` does not exist yet):
+
+```powershell
+C:\software\Python312\python.exe -m pytest backend/tests/mcp/test_mcp_auth_middleware.py -v
+```
+
+- [x] **Step 2: Implement the middleware and ASGI app builder**
+
+Append to `backend/app/mcp/server.py`:
+
+```python
+from starlette.responses import PlainTextResponse
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from app.config.settings import settings
+from app.shared.bootstrap import get_jwt_handler
+
+
+class MCPAuthMiddleware:
+    """Reject unauthenticated requests before they reach the MCP protocol handler.
+
+    Mirrors the existing get_current_user dependency's behavior (auth.py) but
+    implemented as raw ASGI middleware, since the mounted MCP app is a plain
+    ASGI app, not a FastAPI/APIRouter instance that supports Depends().
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        """Store the wrapped ASGI app to delegate to once auth passes."""
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """Validate the bearer token for HTTP requests; pass non-HTTP scopes through."""
+        # Only HTTP requests carry an Authorization header to check; lifespan
+        # and other scope types must always pass through untouched.
+        if scope["type"] != "http" or not settings.auth_enabled:
+            await self.app(scope, receive, send)
+            return
+
+        headers = dict(scope["headers"])
+        auth_header = headers.get(b"authorization", b"").decode()
+        token = auth_header.removeprefix("Bearer ").strip()
+        try:
+            get_jwt_handler().decode_token(token)
+        except ValueError as exc:
+            # Reject before the MCP session/protocol layer ever sees the request.
+            response = PlainTextResponse(str(exc), status_code=401)
+            await response(scope, receive, send)
+            return
+
+        await self.app(scope, receive, send)
+
+
+def build_mcp_asgi_app() -> ASGIApp:
+    """Return the Streamable HTTP ASGI app for the MCP server, auth-guarded."""
+    asgi_app = mcp.streamable_http_app()
+    asgi_app.add_middleware(MCPAuthMiddleware)
+    return asgi_app
+```
+
+- [x] **Step 3: Run the test — confirm it passes**
+
+```powershell
+C:\software\Python312\python.exe -m pytest backend/tests/mcp/test_mcp_auth_middleware.py -v
+```
+
+Expected: 4 passed.
+
+---
+
+### Task 3: Mount into the FastAPI app
+
+**Files:**
+- Modify: `backend/requirements.txt` (add `mcp` dependency)
+- Modify: `backend/app/api/main.py` (mount `/mcp`, wire lifespan via `AsyncExitStack`)
+
+**Interfaces:**
+- Consumes: `app.mcp.server.build_mcp_asgi_app()` (from Task 2).
+- Produces: a running `/mcp` Streamable HTTP endpoint on the existing FastAPI app/port — no new port, process, or deployment step.
+
+- [x] **Step 1: Add the dependency**
+
+In `backend/requirements.txt`, add to the "Web framework" section (or a new small section — either is fine, keep it near `fastapi`/`uvicorn` since it is another transport-layer concern):
+
+```
+mcp>=1.9.0
+```
+
+Install it (already done ad hoc in Task 1 to unblock those tests — this step just formalizes the pin in the manifest; re-run install to be certain the pinned version resolves cleanly):
+
+```powershell
+C:\software\Python312\python.exe -m pip install -r backend/requirements.txt
+```
+
+- [x] **Step 2: Mount the MCP app and fix the lifespan gap**
+
+In `backend/app/api/main.py`, add the import and build the ASGI app at module scope (before `lifespan()` is defined, since `lifespan()` needs to reference it):
+
+```python
+from contextlib import AsyncExitStack
+
+from app.mcp.server import build_mcp_asgi_app
+```
+
+Add right after the existing imports, before `@asynccontextmanager def lifespan(...)`:
+
+```python
+# Built once at module scope so both lifespan() and app.mount() below reference
+# the same instance — mounting a second, separately-built instance would start
+# a second, unrelated MCP session manager.
+mcp_app = build_mcp_asgi_app()
+```
+
+Replace the existing `lifespan()` function body:
+
+```python
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifecycle hooks."""
+    # FastMCP's streamable_http_app() owns a session manager that only starts
+    # via its own lifespan context. app.mount() does NOT propagate nested ASGI
+    # lifespans automatically (confirmed Starlette/ASGI limitation — see
+    # https://github.com/modelcontextprotocol/python-sdk/issues/1367) — without
+    # this, every search_regulations call fails because the session manager
+    # was never started.
+    async with AsyncExitStack() as stack:
+        await stack.enter_async_context(mcp_app.router.lifespan_context(mcp_app))
+
+        logger.info(f"启动 {settings.app_name} v{settings.app_version}")
+        logger.info(f"调试模式: {settings.debug}")
+        logger.info("预加载LLM客户端...")
+        preload_runtime_dependencies()
+
+        yield
+
+        logger.info("应用关闭，执行清理...")
+        cleanup_runtime_dependencies()
+```
+
+Add the mount call right after the existing `app.include_router(api_router, prefix="/api/v1")` line:
+
+```python
+app.include_router(api_router, prefix="/api/v1")
+app.mount("/mcp", mcp_app)
+```
+
+- [x] **Step 3: Run the full backend test suite**
+
+```powershell
+C:\software\Python312\python.exe -m pytest backend/tests -q
+```
+
+Expected: `76 passed` (69 existing + 3 + 4 new from Tasks 1–2). No regressions.
+
+- [x] **Step 4: Manual end-to-end verification (not automated)**
+
+Start the backend the normal way (`dev.bat start api --foreground` or the documented `uvicorn` command) and, from a separate shell, run:
+
+```powershell
+C:\software\Python312\python.exe -c "
+import asyncio
+from mcp import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+
+async def main():
+    url = 'http://127.0.0.1:8000/mcp'
+    headers = {'Authorization': 'Bearer <put a real JWT here if AUTH_ENABLED=true>'}
+    async with streamablehttp_client(url, headers=headers) as (read, write, _):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            tools = await session.list_tools()
+            print([t.name for t in tools.tools])
+            result = await session.call_tool('search_regulations', {'query': '国六排放标准'})
+            print(result)
+
+asyncio.run(main())
+"
+```
+
+Confirm `search_regulations` appears in the tool list and returns a real answer + sources. If `AUTH_ENABLED=false` locally, omit the `headers` argument entirely.
+
+---
+
+## Summary
+
+| Task | New files | Modified files | Tests added |
+|---|---|---|---|
+| 1 | `app/mcp/__init__.py`, `app/mcp/server.py`, `tests/mcp/__init__.py`, `tests/mcp/test_search_regulations_tool.py` | — | 3 |
+| 2 | `tests/mcp/test_mcp_auth_middleware.py` | `app/mcp/server.py` | 4 |
+| 3 | — | `requirements.txt`, `api/main.py` | 0 (full-suite regression check + manual e2e) |
+
+## Task 4 (post-review): code-review fixes
+
+Added after a code review of the three implementation commits. Findings and resolutions:
+
+- [x] **Critical — every remote client rejected with HTTP 421.** The MCP SDK auto-enables DNS-rebinding protection when its `host` parameter is left at the `127.0.0.1` default, hard-coding a loopback-only `Host` allow-list; a client at `http://6.86.80.9:8000/mcp/` was refused before auth or the tool ran, making the feature non-functional in the only deployment it targets. Fixed by passing an explicit `TransportSecuritySettings` built from a new `MCP_ALLOWED_HOSTS` setting (`app/config/settings.py`, documented in `.env.example`), with `*` as a logged, explicit opt-out. Deliberately *not* fixed by passing `host="0.0.0.0"`, which would silently disable the protection.
+- [x] **Important — `top_k` unbounded on the MCP path.** `AskRequest` constrains the same parameter to 1–20, but the tool accepted any integer and `KnowledgeRetrievalService` amplifies it (`top_k * 4`), so `top_k=100000` would request 400,000 Milvus candidates. Fixed with `Annotated[int, Field(ge=1, le=20)]` (and `query` bounded to 1–2000 chars), which also publishes the bounds in the advertised JSON schema.
+- [x] **Important — order-dependent `psycopg2` test guard.** The guard was duplicated across four test modules and only worked because of pytest's alphabetical collection order; any new test package sorting earlier would have reintroduced a multi-second TCP timeout against the production database. Moved into a single `backend/tests/conftest.py` (imported before any test module regardless of order) and the four in-file copies deleted. `bootstrap.py`'s eager imports were left alone — restructuring the composition root every route depends on is disproportionate to a test-harness ordering problem.
+- [x] **Minor — non-UTF-8 `Authorization` header caused a 500.** ASGI header values are latin-1; strict UTF-8 decoding let any remote client trigger an unhandled `UnicodeDecodeError`. Now decoded as latin-1, yielding a clean 401.
+- [x] **Minor — 401 missing `WWW-Authenticate`.** Added `WWW-Authenticate: Bearer`, matching `get_current_user` and RFC 7235.
+- [x] **Minor — missing `#` comment** in `tests/mcp/test_search_regulations_tool.py` (AGENTS.md requires at least one per file). Added.
+
+Reviewer-confirmed as correct, no change needed: the `AsyncExitStack` lifespan wiring (including its failure path), the absence of auth-bypass vectors, and the statelessness of `ask()` without a `session_id`.
+
+New tests: `tests/mcp/test_mcp_transport_security.py` (5, exercising the real MCP app end-to-end) plus 3 more across the existing two files — 84 backend tests pass. Verified against a live server: `Host: 6.86.80.9:8000` → 200 with a valid `initialize` result, `Host: evil.example.com` → 421, no token → 401 with `WWW-Authenticate: Bearer`.

docs/superpowers/plans/2026-08-03-mcp-status-panel.md

@@ -0,0 +1,89 @@
+# MCP Status Panel — Implementation Plan
+
+Spec: `docs/superpowers/specs/2026-08-03-mcp-status-panel-design.md`
+
+Backend first (tests alongside), then frontend, then verify. Each task is
+independently reviewable.
+
+## Task 1 — `app/mcp/stats.py`
+
+- [x] `MCPToolStats` dataclass: `calls: int = 0`, `errors: int = 0`,
+      `total_duration_ms: float = 0.0`, `last_called_at: datetime | None = None`;
+      `avg_duration_ms` property returning `None` when `calls == 0`.
+- [x] `MCPStatsTracker` with `threading.Lock`, `record(tool, duration_ms, success)`,
+      `snapshot()` returning a shallow copy.
+- [x] `record()` wraps its body in `try/except Exception` → `logger.warning`, never raises.
+- [x] `get_mcp_stats_tracker()` with `@lru_cache`.
+- [x] Module docstring + at least one `#` comment (AGENTS.md).
+
+## Task 2 — `backend/tests/mcp/test_mcp_stats.py`
+
+- [x] 8 threads × 100 `record()` calls → `calls == 800` exactly.
+- [x] `avg_duration_ms` is `None` at zero calls, correct mean afterwards.
+- [x] `success=False` increments `errors` and `calls`.
+- [x] `record()` with a non-numeric duration logs and does not raise.
+
+## Task 3 — instrument `app/mcp/server.py`
+
+- [x] Wrap `search_regulations` body: `time.perf_counter()` start,
+      `try/except` records `success=False` and re-raises, `finally` not needed
+      once both branches record.
+- [x] `async def get_mcp_status(public_url: str) -> dict` returning
+      `{endpoint_url, auth_required, allowed_hosts, tools: [...]}` where each
+      tool is `{name, description, calls, errors, avg_duration_ms, last_called_at}`.
+- [x] `allowed_hosts` parsed from `settings.mcp_allowed_hosts` with the same
+      split/strip logic `_build_transport_security()` already uses.
+- [x] `last_called_at` serialized as ISO-8601 string or `None`.
+
+## Task 4 — `mcp_public_url` setting
+
+- [x] `app/config/settings.py`: `mcp_public_url: str = ""` in the existing `# ── MCP ──` block.
+- [x] `.env.example`: documented under the existing MCP section, in Chinese,
+      with the `http://6.86.80.9:8000/mcp/` example and a note that it is only
+      needed when a proxy rewrites `Host`.
+
+## Task 5 — `GET /status/mcp`
+
+- [x] Add route to `backend/app/api/routes/status.py`, taking `request: Request`.
+- [x] `public_url = settings.mcp_public_url or f"{str(request.base_url).rstrip('/')}/mcp/"`.
+- [x] Delegate to `get_mcp_status()`; no MCP internals in the route.
+
+## Task 6 — `backend/tests/mcp/test_mcp_status.py`
+
+- [x] Tool advertised with zeroed stats before any call.
+- [x] Stats reflected after `record()`.
+- [x] `auth_required` follows a patched `settings.auth_enabled`.
+- [x] `public_url` passes through unmodified.
+
+## Task 7 — frontend types + client
+
+- [x] `frontend/src/api/index.ts`: `MCPToolEntry`, `MCPStatusResponse`.
+- [x] `frontend/src/api/status.ts`: `getMCPStatus()` + re-export.
+
+## Task 8 — MCP Server card
+
+- [x] Add `getMCPStatus()` to the existing `Promise.allSettled` batch in
+      `StatusPage.tsx`, with its own `mcpLoading` state.
+- [x] Card below "AI Models": endpoint row + one row per tool.
+- [x] Copy-config button: builds the `mcpServers` JSON, embeds the
+      `localStorage` token when `auth_required`, writes via
+      `navigator.clipboard.writeText`, and reflects success/failure in its label
+      for ~2s.
+- [x] `handleExport()` includes `mcp`.
+- [x] Reuse `card` / `card-header` / `service-row` / `StatusIcon`. No new CSS.
+
+## Task 9 — i18n
+
+- [x] `locales/zh.ts` and `locales/en.ts`: `cardMcp`, `mcpEndpoint`,
+      `mcpAuthRequired`, `mcpAuthDisabled`, `mcpAllowedHosts`, `mcpCopyConfig`,
+      `mcpCopied`, `mcpCopyFailed`, `mcpCalls`, `mcpErrors`, `mcpAvgDuration`,
+      `mcpNoTools`, `mcpUnavailable`.
+- [x] Both files must stay structurally identical (`en.ts` is typed against `zh.ts`).
+
+## Task 10 — verify
+
+- [x] `python -m pytest backend/tests -q` — all pass.
+- [x] `npm --prefix frontend run lint`.
+- [x] `npm --prefix frontend run build`.
+- [x] Live check: start uvicorn, `GET /api/v1/status/mcp`, confirm the tool is
+      listed and counters move after a real MCP `tools/call`.

docs/superpowers/specs/2026-07-23-status-model-usage-hardening-design.md

@@ -0,0 +1,139 @@
+# System Status — AI Models Panel Hardening Design
+
+**Date:** 2026-07-23
+**Scope:** Close three gaps left open by the already-shipped "AI Models" card on the System Status page (`docs/superpowers/specs/2026-07-02-status-llm-model-usage-design.md`): streaming calls don't report token usage, the Cross-Encoder reranker is still disabled, and usage counters reset on every backend restart.
+**Relationship to existing roadmap:** This is a direct continuation of the 2026-07-02 feature, not a new module. It also closes two long-standing "Quick Win" items from `AI_Agent_优化分析报告_2026-06-18.md` (reranker enablement, and — partially — observability of RAG quality). It does not attempt full Langfuse/Ragas tracing (`P0-A` in that roadmap); that remains a separate, larger effort.
+
+---
+
+## Goals
+
+1. **A1 — Streaming token capture.** `stream_chat()` calls (the default interaction mode for the main RAG chat UI) currently report call success/latency but not token usage — an explicitly documented gap in the 2026-07-02 design. Close it using the OpenAI-compatible `stream_options: {include_usage: true}` mechanism, so streaming and non-streaming calls are accounted for consistently.
+2. **A2 — Enable the reranker.** `reranker_enabled` has been `False` by default since before the first internal analysis report (2026-06-11); both that report and the 2026-06-18 follow-up flag it as the single highest-ROI, lowest-risk unfinished item (+15–25% retrieval precision, typically a one-line config change).
+3. **A3 — Durable usage counters.** `ModelUsageTracker` is in-memory only; counts reset on every restart/redeploy. Persist them so the Status page reflects cumulative usage across the process lifetime, not just since the last restart.
+
+## Non-Goals
+
+- Cost/spend estimation in currency (still no reliable pricing for the internal gateway).
+- Per-session/per-user token attribution.
+- Historical time-series / usage-over-time charts (explicitly deferred by user decision during brainstorming — this iteration persists **current cumulative counters only**, not a time-series log).
+- Full Langfuse/Ragas distributed tracing and faithfulness scoring (`P0-A`, separate future effort).
+
+---
+
+## A1 — Streaming Token Capture
+
+### Current behavior (confirmed by reading the code)
+
+`DeepSeekClient.stream_chat()` and both `QwenClient.stream_chat()` / `QwenVLClient.stream_chat()` (`backend/app/services/llm/deepseek_client.py`, `backend/app/services/llm/qwen_client.py`) parse each SSE `data: {...}` line, and today explicitly skip any chunk whose `choices` array is empty:
+
+```python
+choices = data.get("choices", [])
+if not choices:
+    continue   # <- a trailing usage-only chunk is silently dropped here today
+delta = choices[0].get("delta", {})
+content = delta.get("content", "")
+```
+
+`TrackedLLMClient.stream_chat()` (`backend/app/services/llm/tracked_client.py`) wraps this with a plain `for chunk in self._inner.stream_chat(...): yield chunk`, then records call success/latency only — by design, since "none of the current provider `stream_chat()` implementations parse a trailing usage chunk."
+
+### Change
+
+1. Add `"stream_options": {"include_usage": True}` to the request payload built in each of the three `stream_chat()` implementations. This is the standard OpenAI-compatible mechanism: the gateway appends one final chunk with `"choices": []` and a populated `"usage"` object after the normal content chunks.
+2. In each generator, when a parsed chunk has empty `choices` **and** a non-empty `usage` field, capture it into a local variable (function-local — safe even though the underlying client instance is a shared/cached singleton, because each call to `stream_chat()` creates its own generator frame). At the end of the generator, `return` that captured usage dict instead of falling off the end with an implicit `None`. This is accessible to a manual consumer via `StopIteration.value`.
+3. Per-chunk content yields are **unchanged** — this keeps the change backward compatible for all seven existing call sites (`api/routes/rag.py`, `compliance.py`, `agent.py`, `application/perception/services.py`, `infrastructure/llm/openai_compatible_answer_generator.py`, `services/agent/qa_agent.py`) that just do `for chunk in stream_chat(...): ...` and will continue to work untouched, silently ignoring the new return value.
+4. `TrackedLLMClient.stream_chat()` is the **only** call site that needs the return value. Replace its plain `for` loop with a manually-driven loop (`next()` in a `try/except StopIteration`) so it can capture `StopIteration.value` and pass it into the **same existing** `self._tracker.record(...)` call in its `finally` block — no new tracker call, no double-counting of `call_count_ok`/`call_count_error`.
+
+### Known limitation carried forward
+
+If the gateway does not honor `stream_options.include_usage` (some OpenAI-compatible proxies ignore unknown fields silently rather than erroring), streaming usage will simply remain absent, same as today — this is a graceful no-op, not a new failure mode.
+
+---
+
+## A2 — Enable the Reranker
+
+### Current behavior (confirmed)
+
+`.env` has `RERANKER_ENABLED=false`. `OpenAICompatibleReranker` (`backend/app/infrastructure/vectorstore/cross_encoder_reranker.py`) already:
+- Tries TEI format (`POST /rerank`), falls back to Cohere format (`POST /v1/rerank`) on 400/404.
+- On any failure, logs a warning, records the failure into `ModelUsageTracker` (`provider="reranker"`), and **falls back to the original unranked order** rather than raising — retrieval keeps working even if the reranker is broken.
+
+### Change
+
+Flip `RERANKER_ENABLED=true` in root `.env`. No code change. `rag_retrieval_top_k=20` / `rag_top_k=5` are already set to reasonable pre/post-rerank values (`backend/app/config/settings.py:124-125`).
+
+### Verification
+
+Use the already-shipped `POST /status/models/ping` endpoint to actively confirm the gateway's rerank endpoint responds before considering this done. If it errors, the Status page's "AI Models" card will show the reranker row as `error` (existing behavior, not new) — revert the flag in that case rather than leaving retrieval silently degraded to "reranker enabled but always failing over."
+
+---
+
+## A3 — Durable Usage Counters
+
+### Current behavior (confirmed)
+
+`ModelUsageTracker` (`backend/app/shared/model_usage_tracker.py`) holds all state in an in-memory `dict` guarded by a `threading.Lock`. Nothing writes it to disk; a restart or redeploy zeroes every counter.
+
+### Design decision (confirmed with user during brainstorming)
+
+Persist **current cumulative counters only** — one row per `provider:model`, no historical/time-series log. This is the smaller, already-shaped slice of what the 2026-07-02 spec deferred; a time-series log can be layered on top later if trend charts are ever requested, without reworking this table.
+
+### Data model
+
+New table, created the same way every other Postgres store in this codebase creates its table — a `CREATE TABLE IF NOT EXISTS` string executed on first use, no migration framework (matches `postgres_event_store.py`, `postgres_document_repository.py`, `postgres_document_processing_store.py`, `user_store.py`, `compliance/repository.py` — all follow this idiom):
+
+```sql
+CREATE TABLE IF NOT EXISTS model_usage_stats (
+    provider          VARCHAR(64)  NOT NULL,
+    model             VARCHAR(128) NOT NULL,
+    total_tokens      BIGINT       NOT NULL DEFAULT 0,
+    prompt_tokens     BIGINT       NOT NULL DEFAULT 0,
+    completion_tokens BIGINT       NOT NULL DEFAULT 0,
+    call_count_ok     BIGINT       NOT NULL DEFAULT 0,
+    call_count_error  BIGINT       NOT NULL DEFAULT 0,
+    last_called_at    TIMESTAMPTZ,
+    last_latency_ms   INTEGER,
+    last_error        TEXT,
+    updated_at        TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
+    PRIMARY KEY (provider, model)
+);
+```
+
+### Gating — reuse the existing backend toggle, don't add a new one
+
+Gate persistence behind the **existing** `settings.document_repository_backend == "postgres"` flag (the same one `documents`/`compliance` already key off in `backend/app/shared/bootstrap.py`), rather than introducing a new setting. When it is `"json"` (today's default), `ModelUsageTracker` behaves exactly as it does today — purely in-memory, zero new hard requirement on a running Postgres for local/dev use.
+
+### Write strategy: periodic snapshot flush, not per-call write-through
+
+**Single-worker assumption:** this design assumes a single backend worker process. In a multi-worker deployment (e.g., multiple Uvicorn workers or replicas), each worker holds its own in-memory `ModelUsageTracker` and its own periodic flush will overwrite the same `(provider, model)` row with only that worker's partial counts (last-writer-wins semantics), so persisted totals would under-count versus true cross-worker totals — a pre-existing limitation of `ModelUsageTracker` being per-process, now also reflected in what gets persisted.
+
+Rejected: writing to Postgres synchronously inside `record()` on every single LLM/embedding/reranker call — this would add blocking DB I/O to the hot path of every chat/RAG/compliance request, contradicting the tracker's own documented principle that tracking "must never disrupt a real user-facing call."
+
+Chosen approach:
+- **On startup** (in the existing `lifespan()` hook in `backend/app/api/main.py`, alongside the existing `preload_runtime_dependencies()` call): if the postgres backend is active, load existing `model_usage_stats` rows and seed `ModelUsageTracker`'s in-memory dict, so counts continue cumulatively instead of restarting at zero.
+- **Every 60 seconds**, a background `asyncio` task (started at the same point, cancelled in the existing shutdown/`cleanup_runtime_dependencies()` path) snapshots the tracker (`tracker.snapshot()`, already exists) and `UPSERT`s each entry (`INSERT ... ON CONFLICT (provider, model) DO UPDATE`) — overwriting with the current cumulative value, not incrementing, so a missed cycle is never double-counted.
+- **Best-effort flush on shutdown** as a bonus on top of the periodic flush (not the primary durability mechanism — a `SIGKILL`/OOM crash will not trigger it, which is an acceptable, explicitly-noted gap for an observability feature: worst case, up to 60s of counters are lost, not corrupted).
+
+---
+
+## Error Handling
+
+- A1: if a client's `stream_chat()` never emits a trailing usage chunk (gateway doesn't support `stream_options`), the generator simply returns `None`; `TrackedLLMClient` already treats "no usage" as a no-op for the token fields (existing `record()` behavior — `usage or {}`).
+- A2: unchanged — already-shipped graceful fallback and error surfacing.
+- A3: the flush task wraps each cycle in `try/except Exception: logger.warning(...)` — a transient Postgres blip must not crash the flush loop or the app; it simply retries on the next 60s tick. Startup load failure (e.g., Postgres unreachable at boot) logs a warning and leaves the tracker empty, exactly as it behaves today with no persistence at all — it does not block app startup.
+
+## Testing
+
+Mirrors existing conventions (`backend/tests/observability/`, `backend/tests/perception/test_postgres_event_store.py` for the mocked-psycopg2 pattern — no real database needed):
+
+- Extend `backend/tests/observability/test_tracked_client.py`: streaming usage now flows into the same `record()` call (assert the returned `StopIteration.value` path is wired correctly).
+- New tests for `DeepSeekClient.stream_chat()` / `QwenClient.stream_chat()` / `QwenVLClient.stream_chat()`: trailing usage chunk is parsed and returned; ordinary content chunks are unaffected; a stream with no usage chunk still returns `None` without error.
+- New `backend/tests/observability/test_model_usage_persistence.py`: mocked `psycopg2` (same pattern as `test_postgres_event_store.py`) — verifies startup load seeds the tracker, the flush cycle upserts a snapshot, and everything is a no-op when `document_repository_backend != "postgres"`.
+- A2 needs no new test — it is a configuration change exercised by existing reranker tests and manual `/status/models/ping` verification.
+
+## Out of Scope (deferred to future iterations)
+
+- Time-series/historical usage log and trend charts (explicit user decision this iteration — durable counters only).
+- Cost/spend estimation in currency.
+- Per-session/per-user attribution.
+- Full Langfuse/Ragas tracing and LLM-as-judge faithfulness scoring (`P0-A`, tracked separately).

docs/superpowers/specs/2026-07-29-mcp-search-regulations-design.md

@@ -0,0 +1,205 @@
+# MCP Regulation Search Server — Design
+
+**Date:** 2026-07-29
+**Scope:** Expose the existing compliance knowledge base as a standalone Model Context Protocol (MCP) server module, mounted into the existing FastAPI backend, so external MCP clients (Claude Desktop, GitHub Copilot, Cursor, etc.) can call a single `search_regulations` tool over the network.
+**Relationship to existing roadmap:** This is the first half ("Direction A" — expose our data) of the MCP integration opportunity identified during the 2026-07-29 brainstorming session. "Direction B" (consuming external MCP servers, e.g. for US/UK regulatory data) was researched and explicitly rejected for this iteration — no existing open-source regulation MCP server covers this platform's actual sources (国标委/GB standards, CATARC, EUR-Lex); the closest match (`lamcearber-spec/eu-legal-mcp`) is a 0-star, month-old project that only duplicates EUR-Lex data this platform already crawls itself. Direction B is deferred until a concrete need for a jurisdiction this platform doesn't already cover arises.
+
+---
+
+## Goals
+
+1. Expose exactly one MCP tool, `search_regulations`, backed by the **existing** `AgentConversationService.ask()` application service (`backend/app/application/agent/services.py`) — the same code path already used by the `/api/v1/agent/ask` REST endpoint. Zero new retrieval/answering logic.
+2. Package the MCP server as its own self-contained module (`backend/app/mcp/`), then mount it into the existing FastAPI app (`backend/app/api/main.py`) so it ships with the current deployment — no new process, no new deployment pipeline.
+3. Use the Streamable HTTP transport (not stdio) — the backend is deployed remotely (6.86.80.9), so external MCP clients must connect over the network, not via a locally-spawned subprocess.
+4. Reuse the existing JWT auth mechanism — no new auth system. Any authenticated user (any of the four roles) may call `search_regulations`, matching the existing `/agent/ask` endpoint's access level and the `UserRole` docstring ("knowledge query" is available to all four roles including `READONLY`).
+
+## Non-Goals
+
+- Direction B (this platform's agent consuming external MCP servers) — deferred, see rejection rationale above.
+- Additional tools beyond `search_regulations` (e.g. perception event queries, compliance checks) — explicit user decision to ship the minimal viable version first.
+- Role-based restriction of the tool (e.g. ADMIN-only) — all four roles already have knowledge-query access per the existing RBAC model; no new restriction needed.
+- stdio transport / local-only usage — not useful for a remotely-deployed backend.
+- Rate limiting or per-client quotas on the MCP endpoint — no existing precedent in this codebase for any endpoint; out of scope until a concrete abuse case appears.
+
+---
+
+## Architecture
+
+> **Implementation note (post-design correction):** the `mcp` PyPI package released version `2.0.0` shortly before implementation and renamed the `FastMCP` class referenced below to `MCPServer` (import path `mcp.server.MCPServer` instead of `mcp.server.fastmcp.FastMCP`). The `.tool()` / `.streamable_http_app()` API surface used throughout this doc is otherwise unchanged. `backend/app/mcp/server.py` uses the actual shipped `MCPServer` name — treat every `FastMCP` mention below as that rename. Two other corrections discovered during implementation: (1) `MCPServer.streamable_http_app()` registers its own internal route at a fixed `/mcp` path, so mounting it at `/mcp` in `api/main.py` would double the path to `/mcp/mcp` — fixed by calling `mcp.streamable_http_app(streamable_http_path="/")`; (2) the effective external URL for clients is `/mcp/` (**with** a trailing slash) — Starlette's `Mount` 307-redirects the bare `/mcp` to `/mcp/`, which most HTTP clients follow automatically, but it is more robust to configure clients with the trailing slash directly.
+
+### Module layout
+
+```
+backend/app/mcp/
+  __init__.py
+  server.py     # FastMCP instance, search_regulations tool, auth wrapper, ASGI app builder
+```
+
+This sits as a new top-level package alongside `app/api/`, `app/application/`, `app/services/`, `app/shared/` — not nested inside `app/api/routes/`, because MCP tool registration (decorator-based schema binding) and its own sub-ASGI-app are a fundamentally different transport mechanism from the FastAPI `APIRouter` REST routes there. Keeping it as its own top-level module satisfies "list MCP as its own module" and keeps the REST route directory free of non-REST concerns.
+
+`server.py` contains **zero new business logic** — it is a protocol adapter that calls the existing composition root (`app.shared.bootstrap.get_agent_conversation_service()`), the same function `backend/app/api/routes/agent.py` already calls. This is consistent with the architecture rule that new business orchestration belongs in `application/`, not scattered across transport adapters — there is no new orchestration here at all.
+
+### Tool definition
+
+```python
+# backend/app/mcp/server.py
+from mcp.server.fastmcp import FastMCP
+from app.shared.bootstrap import get_agent_conversation_service
+
+mcp = FastMCP("ai-regulations")
+
+@mcp.tool()
+def search_regulations(query: str, top_k: int = 5) -> dict:
+    """检索法规知识库，返回基于检索结果生成的答案及引用来源。
+
+    query: 自然语言检索问题，例如"国六排放标准最新要求"。
+    top_k: 返回的引用来源条数上限，默认5条。
+    """
+    _, result = get_agent_conversation_service().ask(query=query, top_k=top_k)
+    return {
+        "answer": result.answer,
+        "sources": [source.__dict__ for source in result.sources],
+    }
+```
+
+Calling `ask()` **without** `session_id` is intentional: it skips all `ConversationStore` reads/writes (see `AgentConversationService.ask()` — history/session logic is only engaged when `session_id` is passed), so each MCP tool call is stateless and side-effect-free, matching the "search" semantics (not a multi-turn chat).
+
+### Transport & mounting
+
+```python
+# backend/app/mcp/server.py (continued)
+def build_mcp_asgi_app():
+    """Return the mounted MCP ASGI app (Streamable HTTP transport)."""
+    return mcp.streamable_http_app()
+```
+
+```python
+# backend/app/api/main.py (modified)
+from contextlib import AsyncExitStack
+from app.mcp.server import build_mcp_asgi_app, MCPAuthMiddleware
+
+mcp_app = build_mcp_asgi_app()
+mcp_app.add_middleware(MCPAuthMiddleware)  # see Auth section
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application lifecycle hooks."""
+    async with AsyncExitStack() as stack:
+        # FastMCP's streamable_http_app() owns a session manager that must be
+        # started via its own lifespan context. app.mount() does NOT propagate
+        # nested ASGI lifespans automatically (confirmed Starlette/ASGI limitation:
+        # https://github.com/modelcontextprotocol/python-sdk/issues/1367) — without
+        # this, every search_regulations call would fail because the MCP session
+        # manager was never started.
+        await stack.enter_async_context(mcp_app.router.lifespan_context(mcp_app))
+
+        logger.info(f"启动 {settings.app_name} v{settings.app_version}")
+        preload_runtime_dependencies()
+        yield
+        cleanup_runtime_dependencies()
+
+app.mount("/mcp", mcp_app)
+```
+
+This is the one non-obvious infrastructure detail in this design: naively mounting `mcp.streamable_http_app()` via `app.mount()` without wiring its lifespan results in tool calls failing at runtime because the MCP session manager was never started — this is not a hypothetical, it is a confirmed, documented limitation of nested ASGI apps. Using stdlib `AsyncExitStack` inside the **existing** `lifespan()` function avoids adding any new dependency to solve it.
+
+### Auth
+
+The `/mcp` mount point is protected by a small ASGI middleware (not a FastAPI `Depends`, since the mounted app is not a `FastAPI`/`APIRouter` instance) that:
+
+1. Reads the `Authorization: Bearer <token>` header from the incoming ASGI scope.
+2. When `settings.auth_enabled` is `False` (dev mode) — passes through unchanged, matching the existing `get_current_user` dev bypass behavior.
+3. When `settings.auth_enabled` is `True` — validates the token via the **existing** `get_jwt_handler().decode_token(token)` (`backend/app/infrastructure/auth/jwt_handler.py`). On `ValueError` (expired/invalid/missing), returns an HTTP 401 before the request ever reaches the MCP protocol handler. On success, the request proceeds — no role check, since all roles already have knowledge-query access.
+
+```python
+# backend/app/mcp/server.py (continued)
+from starlette.types import ASGIApp, Receive, Scope, Send
+from starlette.responses import PlainTextResponse
+from app.config.settings import settings
+from app.shared.bootstrap import get_jwt_handler
+
+class MCPAuthMiddleware:
+    """Reject unauthenticated requests to the mounted MCP app before they reach FastMCP."""
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http" or not settings.auth_enabled:
+            await self.app(scope, receive, send)
+            return
+
+        headers = dict(scope["headers"])
+        auth_header = headers.get(b"authorization", b"").decode()
+        token = auth_header.removeprefix("Bearer ").strip()
+        try:
+            get_jwt_handler().decode_token(token)
+        except ValueError as exc:
+            response = PlainTextResponse(str(exc), status_code=401)
+            await response(scope, receive, send)
+            return
+
+        await self.app(scope, receive, send)
+```
+
+**Operational consequence:** to connect an external MCP client (Claude Desktop, Copilot, etc.) to this server, the user must configure a static bearer token (a JWT obtained via the existing `/api/v1/auth/login` flow) in that client's MCP server config, e.g.:
+
+```json
+{
+  "mcpServers": {
+    "ai-regulations": {
+      "url": "http://6.86.80.9:8000/mcp/",
+      "headers": { "Authorization": "Bearer <jwt>" }
+    }
+  }
+}
+```
+
+JWTs expire after `expire_minutes` (480 by default, see `JWTHandler`) — long-lived external tool connections will need a token refresh story, but that is an existing limitation of the JWT scheme generally (not new to MCP), so it is not addressed differently here.
+
+### Transport security (Host allow-list)
+
+> **Added post-design after code review.** This was missed in the original design and would have made the feature 100% non-functional in the target deployment.
+
+The MCP SDK enables DNS-rebinding protection automatically whenever the transport's bind host is a loopback address (its `host` parameter defaults to `127.0.0.1`), and then hard-codes the allow-list to `127.0.0.1:*`, `localhost:*`, `[::1]:*`. `TransportSecurityMiddleware` rejects any request whose `Host` header is not on that list with **HTTP 421**, *before* `MCPAuthMiddleware` or the tool runs. A client pointed at `http://6.86.80.9:8000/mcp/` sends `Host: 6.86.80.9:8000` and is therefore refused every time.
+
+The module resolves this by passing an explicit `TransportSecuritySettings` built from a new setting, `MCP_ALLOWED_HOSTS` (comma-separated, `:*` suffix matches any port, documented in `.env.example`):
+
+- Default `127.0.0.1:*,localhost:*,[::1]:*` — safe for local development.
+- Deployments must add their real address, e.g. `MCP_ALLOWED_HOSTS=6.86.80.9:*,127.0.0.1:*,localhost:*`.
+- The literal value `*` disables the protection entirely. This is deliberately an explicit, log-warned opt-out rather than the default, since binding to `0.0.0.0` to sidestep the check would silently switch DNS-rebinding protection off.
+- `allowed_origins` reuses the existing `CORS_ALLOW_ORIGINS` list, so trusted browser origins are declared in exactly one place. Non-browser MCP clients send no `Origin` header, which the SDK treats as allowed.
+
+### Tool input bounds
+
+`search_regulations` declares `query` as 1–2000 characters and `top_k` as 1–20 via `Annotated[..., Field(...)]`, matching `AskRequest` in `app/api/models/agent.py`. This is load-bearing rather than cosmetic: `KnowledgeRetrievalService.retrieve()` amplifies the value (`candidate_k = max(top_k * 4, 20)`) when reranking is active, so an unbounded `top_k` is a cheap resource-exhaustion vector — and an LLM client hallucinating a large value is the likelier trigger than an attacker. Declaring the bounds via `Annotated` also publishes them in the advertised JSON schema, so well-behaved clients never send an out-of-range value at all.
+
+---
+
+## Error Handling
+
+- **Auth failure** (missing/expired/invalid token, when `auth_enabled=True`): HTTP 401 from `MCPAuthMiddleware`, before the MCP protocol layer is invoked at all. The response carries `WWW-Authenticate: Bearer`, matching the `get_current_user` dependency and RFC 7235.
+- **Malformed `Authorization` header bytes**: ASGI header values are latin-1, so the middleware decodes as latin-1; a non-UTF-8 byte yields a normal 401 rather than an unhandled `UnicodeDecodeError`/500.
+- **Rejected `Host` header**: HTTP 421 from the SDK's transport-security middleware (see above), before auth.
+- **Tool execution failure** (e.g. the underlying retrieval/LLM call raises): FastMCP's own tool-call error handling catches exceptions raised inside `@mcp.tool()`-decorated functions and returns them as a normal MCP tool-error result to the calling client — no special handling needed in `search_regulations` itself, consistent with how `/agent/ask`'s REST handler already lets the global FastAPI exception handler in `main.py` catch unexpected errors.
+- **Lifespan startup failure** (e.g. `mcp_app`'s session manager fails to start): surfaces the same way any other `lifespan()` failure does today — the app fails to start, visible immediately in logs, not a silent partial-degradation.
+
+## Testing
+
+- `backend/tests/mcp/test_search_regulations_tool.py` — unit test for the tool function with a mocked `AgentConversationService` (same mocking style as existing `application/agent` tests): asserts `search_regulations()` calls `.ask(query=..., top_k=...)` with no `session_id`, shapes the returned dict correctly (`answer`, `sources`), and that the advertised JSON schema carries the `query`/`top_k` bounds.
+- `backend/tests/mcp/test_mcp_auth_middleware.py` — unit test for `MCPAuthMiddleware`: no token → 401; invalid/expired token → 401; valid token → request passed through to the wrapped app; `auth_enabled=False` → always passed through; 401 carries `WWW-Authenticate`; non-UTF-8 header bytes → 401 not 500. Uses Starlette's `TestClient` against a minimal dummy inner ASGI app, no real MCP protocol handshake needed.
+- `backend/tests/mcp/test_mcp_transport_security.py` — exercises the **real** MCP app over `TestClient`: a configured remote `Host` completes a real JSON-RPC `initialize` handshake; an unconfigured `Host` is refused with 421; `*` disables protection; the comma-separated setting parses correctly. These run the app's lifespan via `with TestClient(...)`, without which the SDK's session-manager task group is uninitialized.
+- `backend/tests/conftest.py` — mocks `psycopg2` at import time for the whole suite. Individual test modules cannot do this reliably, because whether a module runs before the one that needs the mock depends on alphabetical collection order; `conftest.py` is imported before any test module in the tree.
+- **Manual end-to-end verification** (not automated): use the official `mcp` Python client (`mcp.client.streamable_http.streamable_http_client` + `mcp.ClientSession`) to connect to a locally running instance, call `list_tools()`, then call `search_regulations` with a real query, confirming a real answer + sources come back. This is a one-time manual check, not a CI test.
+
+## Dependencies
+
+- Add `mcp` (official Model Context Protocol Python SDK, provides `mcp.server.fastmcp.FastMCP`) to `backend/requirements.txt`. No existing dependency implements the MCP protocol (JSON-RPC 2.0 framing + Streamable HTTP transport + capability negotiation); hand-rolling this would be substantially more code and more fragile than the official SDK.
+
+## Out of Scope (deferred to future iterations)
+
+- Direction B: consuming external MCP servers from this platform's own Agentic RAG pipeline.
+- Additional MCP tools (perception event queries, compliance checks).
+- Per-role tool restrictions.
+- Token refresh / long-lived credential story for external MCP clients beyond the existing JWT expiry behavior.
+- Rate limiting on the `/mcp` endpoint.

docs/superpowers/specs/2026-08-03-mcp-status-panel-design.md

@@ -0,0 +1,198 @@
+# MCP Status Panel — Design
+
+Date: 2026-08-03
+Status: Approved
+
+## Problem
+
+`app/mcp/` already exposes the compliance knowledge base over MCP
+(`search_regulations`, Streamable HTTP at `/mcp/`, JWT-guarded, Host
+allow-listed). It is completely invisible from the product: an operator
+looking at the System Status page cannot tell whether the MCP endpoint is
+enabled, what URL a client should point at, which tools are advertised, or
+whether anything has ever called it.
+
+This design adds that visibility, and only that.
+
+## Goals
+
+- Show MCP endpoint configuration (public URL, auth on/off, Host allow-list).
+- Show the advertised tool list, read from the live MCP registry rather than
+  hard-coded.
+- Show per-tool call counters: total calls, errors, average duration, last
+  call time.
+- Give the operator a one-click "copy client config" JSON they can paste into
+  Claude Desktop / Cursor.
+
+## Non-Goals
+
+- No persistence. Counters are in-memory and reset on restart. Token
+  consumption caused by MCP calls is already persisted by the existing
+  `ModelUsageTracker` (MCP calls route through `AgentConversationService.ask()`
+  like every other caller), so nothing billable is lost.
+- No historical trends or time-series charts.
+- No active-client / session list. That would require hooking the MCP SDK's
+  internal `StreamableHTTPSessionManager`, which is private API and breaks on
+  SDK upgrades.
+- No per-client attribution.
+- No new frontend test framework — the project has none, and this change does
+  not justify introducing one.
+
+## Architecture
+
+Module boundary is unchanged: everything new on the backend lands inside the
+existing `app/mcp/` module, plus one thin HTTP adapter route.
+
+```
+frontend/src/pages/Status/StatusPage.tsx
+        │  GET /api/v1/status/mcp
+        ▼
+backend/app/api/routes/status.py        ← HTTP adapter only
+        │  get_mcp_status(public_url)
+        ▼
+backend/app/mcp/server.py               ← assembles the status payload
+        ├── settings (endpoint / auth / allowed hosts)
+        ├── mcp.list_tools()            ← live tool registry
+        └── app/mcp/stats.py            ← in-memory counters
+```
+
+The status route must not reach into the MCP server's internals. It passes in
+the resolved public URL (the one thing only the HTTP layer knows) and receives
+a finished dict. This keeps the MCP protocol details in one module.
+
+## Components
+
+### `app/mcp/stats.py` (new)
+
+Mirrors `app/shared/model_usage_tracker.py` in shape and in defensive posture.
+
+- `MCPToolStats` dataclass: `calls`, `errors`, `last_called_at`,
+  `total_duration_ms`; `avg_duration_ms` computed as a property.
+- `MCPStatsTracker`: one `threading.Lock` guarding a
+  `dict[str, MCPToolStats]`. `record(tool, duration_ms, success)` and
+  `snapshot()`.
+- `get_mcp_stats_tracker()`, `@lru_cache` singleton.
+
+The lock is not optional. The mcp SDK (2.0.0) dispatches synchronous tool
+functions via `anyio.to_thread.run_sync`, so `search_regulations` genuinely
+runs on multiple worker threads concurrently — unlike the async REST routes,
+which serialize on the event loop.
+
+`record()` swallows and logs its own exceptions, matching `ModelUsageTracker`:
+a defect in observability code must never fail a real MCP tool call.
+
+### `app/mcp/server.py` (modified)
+
+- `search_regulations` gets a `try/except/finally` wrapper that measures
+  elapsed time with `time.perf_counter()` and records success or failure. The
+  exception is re-raised after recording — the MCP SDK still needs to turn it
+  into a protocol-level error.
+- New `async def get_mcp_status(public_url: str) -> dict` merges three
+  sources: settings, `await mcp.list_tools()`, and the stats snapshot. Tools
+  are matched to their stats by name; a tool that has never been called
+  reports zeros.
+
+### `app/api/routes/status.py` (modified)
+
+`GET /status/mcp` resolves the public URL, then delegates:
+
+```python
+public_url = settings.mcp_public_url or f"{str(request.base_url).rstrip('/')}/mcp/"
+return await get_mcp_status(public_url)
+```
+
+### `app/config/settings.py` + `.env.example` (modified)
+
+New optional `mcp_public_url: str = ""`.
+
+This override is required, not cosmetic. The Vite dev proxy sets
+`changeOrigin: true` (`frontend/vite.config.ts`), which rewrites the `Host`
+header to the proxy target, so `request.base_url` on the backend reads
+`http://127.0.0.1:8000/` in development regardless of how the operator
+actually reached the page. Deployments behind a reverse proxy that does not
+forward the original Host have the same problem. When unset, the derived
+value is correct for the common same-origin case.
+
+### Frontend
+
+- `api/index.ts`: `MCPToolEntry` and `MCPStatusResponse` types, alongside the
+  existing `ModelUsageEntry` / `SystemHealth` types.
+- `api/status.ts`: `getMCPStatus()`, using the typed `fetchAPI` client.
+- `StatusPage.tsx`: new "MCP Server" card in the left column, directly below
+  the existing "AI Models" card. It joins the existing
+  `Promise.allSettled([...])` batch, so it refreshes with the page's existing
+  Refresh button and needs no independent polling. `handleExport()` includes
+  the MCP payload.
+  - Header row: title + "copy client config" button.
+  - Endpoint row: `StatusIcon` + monospace URL + auth badge + Host allow-list.
+  - One row per tool: name, calls, errors, average duration, last call time.
+  - Reuses the existing `card`, `card-header`, `service-row` classes and the
+    `StatusIcon` component. No new CSS.
+- `locales/zh.ts` / `locales/en.ts`: new keys under the existing `status`
+  section.
+
+### Copy client config
+
+Produces the Streamable HTTP form both Claude Desktop and Cursor accept:
+
+```json
+{
+  "mcpServers": {
+    "ai-regulations": {
+      "url": "http://6.86.80.9:8000/mcp/",
+      "headers": { "Authorization": "Bearer <token>" }
+    }
+  }
+}
+```
+
+The real JWT from `localStorage` is embedded, because a config with a
+placeholder does not work when pasted and defeats the button's purpose. This
+is the operator's own token, already present in their own browser; the button
+moves it from one local store to another local store on the same machine. The
+`headers` key is omitted entirely when `auth_required` is false.
+
+## Data Flow
+
+1. StatusPage mounts (or Refresh is pressed) → `getMCPStatus()` in the
+   existing parallel batch.
+2. Route resolves the public URL and calls `get_mcp_status()`.
+3. `get_mcp_status()` reads settings, awaits `mcp.list_tools()`, snapshots
+   stats, joins tools to stats by name.
+4. Card renders. Counters advance only when a real MCP client calls a tool.
+
+## Error Handling
+
+- `GET /status/mcp` fails or times out → `Promise.allSettled` leaves the state
+  `null` → card renders a muted "unavailable" body. This is the same pattern
+  the existing model-usage card already uses; one failing status endpoint must
+  never blank the whole page.
+- `mcp.list_tools()` reads an in-memory registry populated at import time and
+  has no failure mode worth special-casing; an unexpected exception surfaces
+  as a 500 on this one endpoint and is contained by the point above.
+- `MCPStatsTracker.record()` never raises (logged and swallowed).
+- `navigator.clipboard.writeText` rejects on insecure origins and when
+  permission is denied. The button reports failure in its own label rather
+  than throwing — a silent no-op would leave the operator believing they
+  copied something.
+
+## Testing
+
+`backend/tests/mcp/test_mcp_stats.py`:
+
+- Concurrent `record()` from multiple threads yields an exact total (proves
+  the lock).
+- `avg_duration_ms` is correct across several calls, and is `None` with zero
+  calls (no division by zero).
+- Successes and failures land in `calls` vs `errors` correctly.
+- `record()` on malformed input logs instead of raising.
+
+`backend/tests/mcp/test_mcp_status.py`:
+
+- `get_mcp_status()` returns the advertised tool with zeroed stats before any
+  call, and reflects recorded stats after.
+- `auth_required` follows `settings.auth_enabled`.
+- The passed-in `public_url` appears unmodified in the payload.
+
+Frontend: no new tests; verified via `npm --prefix frontend run lint` and
+`npm --prefix frontend run build`.

frontend/src/api/index.ts

@@ -333,4 +333,22 @@ export interface ModelUsageResponse {
   models: ModelUsageEntry[];
 }
 
+/** One tool advertised by the MCP server, joined with its in-memory call counters. */
+export interface MCPToolEntry {
+  name: string;
+  description: string;
+  calls: number;
+  errors: number;
+  /** null when the tool has never been called — distinct from an average of 0. */
+  avg_duration_ms: number | null;
+  last_called_at: string | null;
+}
+
+export interface MCPStatusResponse {
+  endpoint_url: string;
+  auth_required: boolean;
+  allowed_hosts: string[];
+  tools: MCPToolEntry[];
+}
+
 export { API_BASE_URL };

frontend/src/api/perception.ts

@@ -52,6 +52,39 @@ export interface AnalysisSSEMessage {
   text?: string;
 }
 
+export interface PerceptionNotification {
+  id: number;
+  event_id: string;
+  kind: 'new' | 'changed';
+  title: string;
+  impact_level: string | null;
+  summary: string | null;
+  created_at: string;
+  read: boolean;
+}
+
+export interface NotificationListResponse {
+  items: PerceptionNotification[];
+  unread_count: number;
+}
+
+/** Broadcast feed shared by every logged-in user; read state is per-caller. */
+export async function getNotifications(limit = 20): Promise<NotificationListResponse> {
+  const res = await fetch(`${PERCEPTION_API_BASE}/perception/notifications?limit=${limit}`, { headers: authHeader() });
+  if (!res.ok) throw new Error(`notifications failed: ${res.status}`);
+  return res.json() as Promise<NotificationListResponse>;
+}
+
+/** Marks every currently-unread notification read for the calling user. */
+export async function markNotificationsRead(): Promise<{ marked: number }> {
+  const res = await fetch(`${PERCEPTION_API_BASE}/perception/notifications/read`, {
+    method: 'POST',
+    headers: authHeader(),
+  });
+  if (!res.ok) throw new Error(`mark read failed: ${res.status}`);
+  return res.json() as Promise<{ marked: number }>;
+}
+
 export async function getPerceptionStats(): Promise<PerceptionStats> {
   const res = await fetch(`${PERCEPTION_API_BASE}/perception/stats`, { headers: authHeader() });
   if (!res.ok) throw new Error(`stats failed: ${res.status}`);

frontend/src/api/status.ts

@@ -1,4 +1,4 @@
-import { fetchAPI, type ModelUsageResponse, type SystemConfig, type SystemHealth, type SystemStats } from './index';
+import { fetchAPI, type MCPStatusResponse, type ModelUsageResponse, type SystemConfig, type SystemHealth, type SystemStats } from './index';
 
 export async function getSystemStats(): Promise<SystemStats> {
   return fetchAPI<SystemStats>('/status/stats');
@@ -22,4 +22,9 @@ export async function pingModelConnections(): Promise<ModelUsageResponse> {
   return fetchAPI<ModelUsageResponse>('/status/models/ping', { method: 'POST' });
 }
 
-export type { ModelUsageResponse, SystemConfig, SystemHealth, SystemStats };
+/** MCP endpoint config, advertised tools, and per-tool call counters. */
+export async function getMCPStatus(): Promise<MCPStatusResponse> {
+  return fetchAPI<MCPStatusResponse>('/status/mcp');
+}
+
+export type { MCPStatusResponse, ModelUsageResponse, SystemConfig, SystemHealth, SystemStats };

frontend/src/components/layout/Sidebar.tsx

@@ -1,3 +1,4 @@
+import { useEffect, useState } from 'react';
 import { NavLink } from 'react-router-dom';
 import {
   LayoutDashboard, Radio, Monitor, FileText,
@@ -6,6 +7,12 @@ import {
 import { useTheme } from '../../contexts/ThemeContext';
 import { useAuth } from '../../contexts/AuthContext';
 import { useLanguage } from '../../contexts/LanguageContext';
+import { getNotifications } from '../../api/perception';
+
+// How often the sidebar re-checks the unread count. A plain UI refresh
+// cadence, not an infrastructure setting — unlike the crawl interval, this
+// never needs to be tuned per deployment.
+const UNREAD_POLL_MS = 60_000;
 
 interface NavItem {
   to: string;
@@ -47,10 +54,24 @@ export function Sidebar() {
   const { theme, toggleTheme } = useTheme();
   const { user, logout } = useAuth();
   const { lang, t, toggleLang } = useLanguage();
+  const [unreadSignals, setUnreadSignals] = useState(0);
+
+  // Sidebar only mounts inside RequireAuth, so a token always exists here.
+  // Polling (not push) keeps this simple — at one crawl every 6 hours, a
+  // 60s badge refresh is more than fast enough to feel current.
+  useEffect(() => {
+    let cancelled = false;
+    function poll() {
+      getNotifications().then(r => { if (!cancelled) setUnreadSignals(r.unread_count); }).catch(() => {});
+    }
+    poll();
+    const timer = setInterval(poll, UNREAD_POLL_MS);
+    return () => { cancelled = true; clearInterval(timer); };
+  }, []);
 
   const mainNav: NavItem[] = [
     { to: '/', icon: <LayoutDashboard size={16} />, label: t.nav.overview },
-    { to: '/signals', icon: <Radio size={16} />, label: t.nav.signals },
+    { to: '/signals', icon: <Radio size={16} />, label: t.nav.signals, badge: unreadSignals },
     { to: '/status', icon: <Monitor size={16} />, label: t.nav.status },
   ];
 

frontend/src/contexts/PageStateContext.tsx

@@ -12,6 +12,7 @@
  */
 
 import React, { createContext, useContext, useState, useCallback, useRef } from 'react';
+import { COMPLIANCE_INIT } from './pageStateDefaults';
 
 // ── RagChat types ─────────────────────────────────────────────────────────────
 
@@ -122,22 +123,6 @@ export interface ComplianceState {
   conflicts: ComplianceConflict[];
 }
 
-const COMPLIANCE_INIT: ComplianceState = {
-  status: 'idle',
-  stageLabel: '',
-  stageKey: '',
-  meta: null,
-  sources: [],
-  findings: [],
-  done: null,
-  errorText: '',
-  analysisId: null,
-  isReadOnly: false,
-  activeFindingId: null,
-  progress: null,
-  conflicts: [],
-};
-
 // ── Perception types ──────────────────────────────────────────────────────────
 
 export interface PerceptionSignal {

frontend/src/contexts/index.ts

@@ -2,6 +2,7 @@ export { ThemeProvider, useTheme } from './ThemeContext';
 export { AuthProvider, useAuth } from './AuthContext';
 export type { AuthUser } from './AuthContext';
 export { PageStateProvider, usePageState } from './PageStateContext';
+export { COMPLIANCE_INIT } from './pageStateDefaults';
 export { LanguageProvider, useLanguage } from './LanguageContext';
 export type { Lang } from './LanguageContext';
 export type {

frontend/src/contexts/pageStateDefaults.ts

@@ -0,0 +1,27 @@
+/**
+ * Default values for PageStateContext slices.
+ *
+ * These live outside PageStateContext.tsx because that file exports React
+ * components, and `react-refresh/only-export-components` requires shared
+ * constants to sit in their own module. Keeping the defaults here also gives
+ * consumers a single canonical initial state to spread from, instead of each
+ * page maintaining its own copy that silently drifts when a field is added.
+ */
+
+import type { ComplianceState } from './PageStateContext';
+
+export const COMPLIANCE_INIT: ComplianceState = {
+  status: 'idle',
+  stageLabel: '',
+  stageKey: '',
+  meta: null,
+  sources: [],
+  findings: [],
+  done: null,
+  errorText: '',
+  analysisId: null,
+  isReadOnly: false,
+  activeFindingId: null,
+  progress: null,
+  conflicts: [],
+};

frontend/src/locales/en.ts

@@ -143,6 +143,19 @@ export interface Translations {
     modelStatusDisabled: string;
     sharesUsageWithMain: string;
     lastCalledNever: string;
+    cardMcp: string;
+    mcpEndpoint: string;
+    mcpAuthRequired: string;
+    mcpAuthDisabled: string;
+    mcpAllowedHosts: string;
+    mcpCopyConfig: string;
+    mcpCopied: string;
+    mcpCopyFailed: string;
+    mcpCalls: string;
+    mcpErrors: string;
+    mcpAvgDuration: string;
+    mcpNoTools: string;
+    mcpUnavailable: string;
   };
   docs: {
     topbarTitle: string;
@@ -415,6 +428,19 @@ export const en: Translations = {
     modelStatusDisabled: 'Disabled',
     sharesUsageWithMain: 'Shares usage with main LLM',
     lastCalledNever: 'Never',
+    cardMcp: 'MCP Server',
+    mcpEndpoint: 'Endpoint',
+    mcpAuthRequired: 'Auth required',
+    mcpAuthDisabled: 'No auth',
+    mcpAllowedHosts: 'Allowed hosts',
+    mcpCopyConfig: 'Copy client config',
+    mcpCopied: 'Copied',
+    mcpCopyFailed: 'Copy failed',
+    mcpCalls: 'calls',
+    mcpErrors: 'errors',
+    mcpAvgDuration: 'avg',
+    mcpNoTools: 'No MCP tools registered',
+    mcpUnavailable: 'MCP status endpoint unavailable',
   },
   docs: {
     topbarTitle: 'Document Management',

frontend/src/locales/zh.ts

@@ -144,6 +144,19 @@ export const zh: Translations = {
     modelStatusDisabled: '已禁用',
     sharesUsageWithMain: '与主 LLM 共用统计',
     lastCalledNever: '从未',
+    cardMcp: 'MCP 服务',
+    mcpEndpoint: '接入端点',
+    mcpAuthRequired: '需鉴权',
+    mcpAuthDisabled: '未鉴权',
+    mcpAllowedHosts: 'Host 白名单',
+    mcpCopyConfig: '复制接入配置',
+    mcpCopied: '已复制',
+    mcpCopyFailed: '复制失败',
+    mcpCalls: '调用',
+    mcpErrors: '失败',
+    mcpAvgDuration: '平均',
+    mcpNoTools: '未注册任何 MCP 工具',
+    mcpUnavailable: 'MCP 状态接口不可用',
   },
   docs: {
     topbarTitle: '文档管理',

frontend/src/pages/Compliance/CompliancePage.tsx

@@ -7,7 +7,7 @@ import { useComplianceAnalysis } from './useComplianceAnalysis';
 import { usePageState } from '../../contexts';
 import { HistoryRail } from './HistoryRail';
 import { FindingChatDrawer } from './FindingChatDrawer';
-import type { FindingEvent, SourceEvent, AnalysisMeta } from './useComplianceAnalysis';
+import type { FindingEvent, SourceEvent } from './useComplianceAnalysis';
 
 const TOKEN_KEY = 'auth_token';
 function authHeader(): Record<string, string> {

frontend/src/pages/Compliance/useComplianceAnalysis.ts

@@ -7,7 +7,7 @@
  */
 
 import { useCallback } from 'react';
-import { usePageState } from '../../contexts';
+import { usePageState, COMPLIANCE_INIT } from '../../contexts';
 import type {
   ComplianceMeta,
   ComplianceState,
@@ -28,21 +28,6 @@ function authHeader(): Record<string, string> {
   return t ? { Authorization: `Bearer ${t}` } : {};
 }
 
-const INITIAL_STATE: ComplianceState = {
-  status: 'idle',
-  stageLabel: '',
-  stageKey: '',
-  meta: null,
-  sources: [],
-  findings: [],
-  done: null,
-  errorText: '',
-  analysisId: null,
-  isReadOnly: false,
-  progress: null,
-  conflicts: [],
-};
-
 export function useComplianceAnalysis() {
   const { complianceState: state, setComplianceState: setState, complianceAbortRef, resetCompliance: reset } = usePageState();
 
@@ -51,7 +36,7 @@ export function useComplianceAnalysis() {
     const ctrl = new AbortController();
     complianceAbortRef.current = ctrl;
 
-    setState({ ...INITIAL_STATE, status: 'streaming', stageLabel: 'Starting…', meta });
+    setState({ ...COMPLIANCE_INIT, status: 'streaming', stageLabel: 'Starting…', meta });
 
     try {
       const res = await fetch('/api/v1/compliance/analyze-stream', {

frontend/src/pages/Login/LoginPage.tsx

@@ -1,4 +1,4 @@
-import React, { FormEvent, useState } from 'react';
+import { useState, type FormEvent } from 'react';
 import { useAuth } from '../../contexts';
 
 export function LoginPage() {

frontend/src/pages/Perception/PerceptionPage.tsx

@@ -1,4 +1,4 @@
-import { useState, useEffect, useRef } from 'react';
+import { useState, useEffect } from 'react';
 import { Topbar } from '../../components/layout/Topbar';
 import { RefreshCw, Play, Square, ExternalLink } from 'lucide-react';
 import { usePageState } from '../../contexts';
@@ -15,23 +15,24 @@ interface Stats {
   total: number;
   high_impact: number;
   medium_impact: number;
-  last_90_days: number;
+  recent_90d: number;
 }
 
-const SOURCES = ['All', 'MIIT', 'UN-ECE', 'ISO', 'GB Comm.', 'EUR-Lex', 'IATF'];
 const IMPACTS = ['All', 'High', 'Medium', 'Low'];
 
 // Backend event → Signal
 function mapEvent(e: Record<string, unknown>): PerceptionSignal {
   const impact = String(e.impact_level ?? '').toLowerCase();
+  // The backend publishes a lifecycle stage, not a severity. Mapping it through
+  // an impact-level vocabulary sent every real value to the default branch,
+  // which renders as "已发布" — so consultation drafts were labelled as enacted.
   const backendStatus = String(e.status ?? '').toLowerCase();
   return {
     id: String(e.id ?? e.event_id ?? ''),
     source: String(e.source ?? ''),
     standard: String(e.standard ?? e.standard_code ?? e.regulation_id ?? ''),
-    status: backendStatus === 'high' || backendStatus === 'urgent' ? 'risk'
+    status: backendStatus === 'enacted' ? 'ok'
-          : backendStatus === 'medium' || backendStatus === 'draft' ? 'warn'
+          : backendStatus === 'draft' || backendStatus === 'consultation' ? 'warn'
-          : backendStatus === 'low' || backendStatus === 'final' ? 'ok'
           : 'info',
     title: String(e.title ?? ''),
     summary: String(e.summary ?? e.description ?? ''),
@@ -80,7 +81,13 @@ export function PerceptionPage() {
     fetch('/api/v1/perception/stats', { headers: authHeader() })
       .then(r => r.json())
       .then(setStats)
-      .catch(() => setStats({ total: 47, high_impact: 7, medium_impact: 18, last_90_days: 14 }));
+      .catch(() => setStats({ total: 47, high_impact: 7, medium_impact: 18, recent_90d: 14 }));
+  }, []);
+
+  // Landing on this page is the acknowledgement — clear the sidebar badge by
+  // marking every currently-unread notification read. No dismiss UI needed.
+  useEffect(() => {
+    fetch('/api/v1/perception/notifications/read', { method: 'POST', headers: authHeader() }).catch(() => {});
   }, []);
 
   // Fetch signal list on first mount only (if empty), otherwise preserve context state
@@ -114,6 +121,17 @@ export function PerceptionPage() {
 
   const selected = signals.find(s => s.id === selectedId) ?? null;
 
+  // Derived from the loaded data rather than hardcoded. The previous fixed list
+  // was written against the mock fixtures, so the two sources the crawlers
+  // actually produce — CATARC and 国标委 — had no chip and could never be
+  // filtered. Deriving them also means a new crawler needs no frontend change.
+  // sourceFilter survives navigation in PageStateContext, so a filter chosen
+  // against an earlier dataset is kept in the list; dropping it would strand
+  // the user on an empty list with no chip to click their way out of.
+  const sources = ['All', ...Array.from(
+    new Set([...signals.map(s => s.source), sourceFilter].filter(s => s && s !== 'All')),
+  ).sort()];
+
   const filtered = signals.filter(s => {
     if (sourceFilter !== 'All' && s.source !== sourceFilter) return false;
     if (impactFilter !== 'All' && s.impact !== impactFilter) return false;
@@ -178,6 +196,11 @@ export function PerceptionPage() {
   }
 
   async function runCrawl() {
+    // A crawl already in flight is superseded — cancel it so its SSE reader
+    // stops writing status text for a run the user has replaced.
+    perceptionCrawlAbortRef.current?.abort();
+    const ctrl = new AbortController();
+    perceptionCrawlAbortRef.current = ctrl;
     setCrawling(true);
     setPerceptionState(s => ({ ...s, crawlStatus: t.signals.statusConnecting }));
     try {
@@ -185,6 +208,7 @@ export function PerceptionPage() {
         method: 'POST',
         headers: { 'Content-Type': 'application/json', ...authHeader() },
         body: JSON.stringify({}),
+        signal: ctrl.signal,
       });
       if (!res.body) {
         setPerceptionState(s => ({ ...s, crawlStatus: 'No stream' }));
@@ -232,11 +256,15 @@ export function PerceptionPage() {
         }
       }
     } catch (e: unknown) {
+      // An abort is a deliberate supersede, not a backend failure — leaving the
+      // status untouched avoids reporting "connection failed" to the user.
+      if (!(e instanceof DOMException && e.name === 'AbortError')) {
         setPerceptionState(s => ({
           ...s,
           crawlStatus: t.signals.statusConnFailed.replace('{message}', e instanceof Error ? e.message : String(e)),
         }));
       }
+    }
     setCrawling(false);
   }
 
@@ -293,14 +321,14 @@ export function PerceptionPage() {
           <span className="sbar-lbl">{t.signals.statMedium}</span>
         </div>
         <div className="sbar-cell accent">
-          <span className="sbar-val">{stats?.last_90_days ?? '—'}</span>
+          <span className="sbar-val">{stats?.recent_90d ?? '—'}</span>
           <span className="sbar-lbl">{t.signals.statLast90}</span>
         </div>
       </div>
 
       <div className="filter-bar">
         <div className="chip-group">
-          {SOURCES.map(s => (
+          {sources.map(s => (
             <button
               key={s}
               className={`chip${sourceFilter === s ? ' active' : ''}`}
@@ -365,7 +393,7 @@ export function PerceptionPage() {
                   <span className={`status ${selected.status}`}>
                     {selected.status === 'risk' ? t.signals.badgeUrgent : selected.status === 'warn' ? t.signals.badgeDraft : t.signals.badgePublished}
                   </span>
-                  {selectedFull?.change_summary && (
+                  {Boolean(selectedFull?.change_summary) && (
                     <span className="status warn" style={{ marginLeft: 'auto' }}>CHANGED</span>
                   )}
                 </div>
@@ -411,9 +439,9 @@ export function PerceptionPage() {
                   <p className="detail-summary" style={{ marginTop: 8 }}>
                     {(selectedFull?.scope as string) || selected.summary}
                   </p>
-                  {selectedFull?.penalties && (
+                  {Boolean(selectedFull?.penalties) && (
                     <p style={{ fontSize: 13, color: 'var(--danger)', marginTop: 6 }}>
-                      ⚠ {selectedFull.penalties as string}
+                      ⚠ {selectedFull?.penalties as string}
                     </p>
                   )}
                 </div>
@@ -486,8 +514,8 @@ export function PerceptionPage() {
                                 {String(d.doc_name || '')}
                                 <span className="doc-clause">{String(d.key_clauses || d.clause || '')}</span>
                               </div>
-                              {d.snippet && <div className="doc-snippet">{String(d.snippet)}</div>}
+                              {Boolean(d.snippet) && <div className="doc-snippet">{String(d.snippet)}</div>}
-                              {d.recommendation && (
+                              {Boolean(d.recommendation) && (
                                 <div style={{ fontSize: 12, color: 'var(--accent)', marginTop: 2 }}>→ {String(d.recommendation)}</div>
                               )}
                             </div>
@@ -523,7 +551,7 @@ export function PerceptionPage() {
                             {String(s.new_text || '')}
                           </div>
                         </div>
-                        {s.summary && <p style={{ fontSize: 12, marginTop: 6, color: 'var(--text-secondary)' }}>{String(s.summary)}</p>}
+                        {Boolean(s.summary) && <p style={{ fontSize: 12, marginTop: 6, color: 'var(--text-secondary)' }}>{String(s.summary)}</p>}
                       </div>
                     ));
                   })()}

frontend/src/pages/Status/StatusPage.tsx

@@ -1,10 +1,10 @@
 import { useState, useEffect } from 'react';
 import { Topbar } from '../../components/layout/Topbar';
-import { Search, Upload, Download, RefreshCw, CheckCircle, XCircle, AlertTriangle, Info } from 'lucide-react';
+import { Search, Upload, Download, RefreshCw, CheckCircle, XCircle, AlertTriangle, Info, Copy } from 'lucide-react';
 import { UploadModal } from '../Docs/UploadModal';
 import { useLanguage } from '../../contexts/LanguageContext';
-import { getModelUsage, pingModelConnections } from '../../api/status';
+import { getMCPStatus, getModelUsage, pingModelConnections } from '../../api/status';
-import type { ModelUsageEntry } from '../../api/index';
+import type { MCPStatusResponse, ModelUsageEntry } from '../../api/index';
 
 const TOKEN_KEY = 'auth_token';
 function authHeader(): Record<string, string> {
@@ -90,11 +90,15 @@ export function StatusPage() {
   const [lastRefresh, setLastRefresh] = useState<Date | null>(null);
   const [modelUsage, setModelUsage] = useState<ModelUsageEntry[] | null>(null);
   const [pinging, setPinging] = useState(false);
+  const [mcp, setMcp] = useState<MCPStatusResponse | null>(null);
+  const [mcpLoading, setMcpLoading] = useState(true);
+  const [copyState, setCopyState] = useState<'idle' | 'ok' | 'fail'>('idle');
 
   useEffect(() => {
     setLoading(true);
     setHealthLoading(true);
     setModelsLoading(true);
+    setMcpLoading(true);
 
     // Fetch all endpoints in parallel. The first three use raw fetch() (legacy
     // pattern already established in this file); model usage uses the typed
@@ -104,7 +108,8 @@ export function StatusPage() {
       fetch('/api/v1/status/health', { headers: authHeader() }).then(r => r.json()),
       fetch('/api/v1/status/config', { headers: authHeader() }).then(r => r.json()),
       getModelUsage(),
-    ]).then(([statsRes, healthRes, configRes, modelsRes]) => {
+      getMCPStatus(),
+    ]).then(([statsRes, healthRes, configRes, modelsRes, mcpRes]) => {
       if (statsRes.status === 'fulfilled') setStats(statsRes.value);
       else setStats({ documents_total: 0, documents_indexed: 0, documents_failed: 0, chunks_total: 0 });
 
@@ -112,10 +117,13 @@ export function StatusPage() {
       if (configRes.status === 'fulfilled') setConfig(configRes.value);
       if (modelsRes.status === 'fulfilled') setModelUsage(modelsRes.value.models);
       else setModelUsage(null);
+      // A failing MCP endpoint must degrade to a muted card, never blank the page.
+      setMcp(mcpRes.status === 'fulfilled' ? mcpRes.value : null);
 
       setLoading(false);
       setHealthLoading(false);
       setModelsLoading(false);
+      setMcpLoading(false);
       setLastRefresh(new Date());
     });
   }, [refreshKey]);
@@ -140,7 +148,7 @@ export function StatusPage() {
 
   // ── Export ───────────────────────────────────────────────────────────────
   function handleExport() {
-    const data = { stats, health, config, exportedAt: new Date().toISOString() };
+    const data = { stats, health, config, mcp, exportedAt: new Date().toISOString() };
     const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' });
     const url = URL.createObjectURL(blob);
     const a = document.createElement('a');
@@ -180,6 +188,34 @@ export function StatusPage() {
     return new Date(entry.last_called_at).toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit' });
   }
 
+  /** Build the mcpServers block Claude Desktop / Cursor accept for a Streamable HTTP server. */
+  function buildMCPClientConfig(status: MCPStatusResponse): string {
+    const token = localStorage.getItem(TOKEN_KEY);
+    const server: Record<string, unknown> = { url: status.endpoint_url };
+    // Omit the header entirely when the backend runs unauthenticated, so the
+    // pasted config never carries a stale "Bearer null".
+    if (status.auth_required && token) server.headers = { Authorization: `Bearer ${token}` };
+    return JSON.stringify({ mcpServers: { 'ai-regulations': server } }, null, 2);
+  }
+
+  async function handleCopyMCPConfig() {
+    if (!mcp) return;
+    try {
+      await navigator.clipboard.writeText(buildMCPClientConfig(mcp));
+      setCopyState('ok');
+    } catch {
+      // clipboard.writeText rejects on insecure origins and denied permissions.
+      // Surface it: a silent no-op would leave the operator pasting stale data.
+      setCopyState('fail');
+    }
+    setTimeout(() => setCopyState('idle'), 2000);
+  }
+
+  function mcpDurationLabel(ms: number | null): string {
+    if (ms === null) return '—';
+    return ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${Math.round(ms)}ms`;
+  }
+
   return (
     <div className="status-page">
       <Topbar
@@ -344,6 +380,65 @@ export function StatusPage() {
               )}
             </div>
 
+            {/* MCP server — endpoint config + advertised tools + call counters */}
+            <div className="card">
+              <div className="card-header" style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
+                <span>{t.status.cardMcp}</span>
+                <button className="btn sm" onClick={handleCopyMCPConfig} disabled={!mcp}>
+                  <Copy size={13} />
+                  {copyState === 'ok' ? t.status.mcpCopied : copyState === 'fail' ? t.status.mcpCopyFailed : t.status.mcpCopyConfig}
+                </button>
+              </div>
+
+              {mcpLoading ? (
+                <div style={{ padding: '12px 0', display: 'flex', flexDirection: 'column', gap: 10 }}>
+                  {[1, 2].map(i => <div key={i} className="loading-shimmer" style={{ height: 28, borderRadius: 6 }} />)}
+                </div>
+              ) : mcp ? (
+                <>
+                  <div className="service-row">
+                    <StatusIcon status="ok" />
+                    <span className="service-name" style={{ marginLeft: 8 }}>{t.status.mcpEndpoint}</span>
+                    <span style={{ fontSize: 11, color: 'var(--muted)', marginLeft: 6, fontFamily: 'var(--font-mono)', wordBreak: 'break-all' }}>
+                      {mcp.endpoint_url}
+                    </span>
+                    <span className={`status ${mcp.auth_required ? 'ok' : 'warn'}`} style={{ marginLeft: 'auto' }}>
+                      {mcp.auth_required ? t.status.mcpAuthRequired : t.status.mcpAuthDisabled}
+                    </span>
+                  </div>
+
+                  <div className="service-row">
+                    <StatusIcon status="info" />
+                    <span className="service-name" style={{ marginLeft: 8 }}>{t.status.mcpAllowedHosts}</span>
+                    <span style={{ fontSize: 11, color: 'var(--muted)', marginLeft: 6, fontFamily: 'var(--font-mono)', wordBreak: 'break-all' }}>
+                      {mcp.allowed_hosts.join(', ') || '—'}
+                    </span>
+                  </div>
+
+                  {mcp.tools.length === 0 ? (
+                    <div style={{ padding: '12px 0', color: 'var(--muted)', fontSize: 13 }}>{t.status.mcpNoTools}</div>
+                  ) : mcp.tools.map(tool => (
+                    <div className="service-row" key={tool.name}>
+                      <StatusIcon status={tool.errors > 0 ? 'warn' : tool.calls > 0 ? 'ok' : 'info'} />
+                      <span className="service-name" style={{ marginLeft: 8, fontFamily: 'var(--font-mono)' }}>{tool.name}</span>
+                      <span style={{ fontSize: 11, color: 'var(--muted)', marginLeft: 6 }}>
+                        {`${t.status.mcpCalls} ${tool.calls}`}
+                        {tool.errors > 0 && ` · ${t.status.mcpErrors} ${tool.errors}`}
+                        {` · ${t.status.mcpAvgDuration} ${mcpDurationLabel(tool.avg_duration_ms)}`}
+                      </span>
+                      <span style={{ marginLeft: 'auto', fontFamily: 'var(--font-mono)', fontSize: 11, color: 'var(--muted)' }}>
+                        {tool.last_called_at
+                          ? new Date(tool.last_called_at).toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit' })
+                          : t.status.lastCalledNever}
+                      </span>
+                    </div>
+                  ))}
+                </>
+              ) : (
+                <div style={{ padding: '12px 0', color: 'var(--muted)', fontSize: 13 }}>{t.status.mcpUnavailable}</div>
+              )}
+            </div>
+
             {/* System config (collapsible) */}
             <div className="card">
               <button

pyproject.toml

@@ -26,6 +26,8 @@ dependencies = [
     "httpx>=0.24.0",
     "beautifulsoup4>=4.12.0",
     "lxml>=5.0.0",
+    "trafilatura>=2.0.0",
+    "diff-match-patch>=20241021",
     "alibabacloud-docmind-api20220711>=1.0.6",
     "alibabacloud-tea-openapi>=0.3.11",
     "alibabacloud-tea-util>=0.3.13",

tests/test_celery_tasks.py

@@ -33,6 +33,20 @@ def test_process_document_task_is_registered():
     )
 
 
+def test_crawl_regulations_task_is_registered():
+    """crawl_regulations_task must be discoverable in the Celery task registry.
+
+    This is the scheduled counterpart to the manual "Refresh" button — Beat
+    has nothing to run on its interval unless this task is registered.
+    """
+    import app.infrastructure.tasks.perception_tasks  # noqa: F401 — triggers task registration
+    from app.infrastructure.tasks.celery_app import celery_app
+    registered = list(celery_app.tasks.keys())
+    assert any("crawl_regulations_task" in name for name in registered), (
+        f"crawl_regulations_task not found in {registered}"
+    )
+
+
 def test_document_command_service_has_process_document():
     """DocumentCommandService must expose _process_document method."""
     from app.application.documents.services import DocumentCommandService