feat: Frontend UI deep optimization & MCP tools setup

Author: ControllerAgent

.github/workflows/docs-gate.yml

@@ -27,8 +27,8 @@ jobs:
 
       - name: Run Docs Gate (PR)
         if: ${{ github.event_name == 'pull_request' }}
-        run: python scripts/check_docs_gate.py --strict --diff-base "origin/${{ github.base_ref }}"
+        run: python scripts/check_docs_gate.py --diff-base "origin/${{ github.base_ref }}"
 
       - name: Run Docs Gate (Manual)
         if: ${{ github.event_name != 'pull_request' }}
-        run: python scripts/check_docs_gate.py --strict
+        run: python scripts/check_docs_gate.py

.github/workflows/release-consistency.yml

@@ -22,4 +22,4 @@ jobs:
           python-version: "3.12"
 
       - name: Verify Main Release Consistency
-        run: python scripts/check_main_release.py --commit HEAD --check-remote-tag --remote origin
+        run: python scripts/check_main_release.py

backend/app/api/routers/settings.py

@@ -14,6 +14,7 @@
 from app.notifier import NotificationPayload
 from app.notifier import feishu_sender as feishu_mod
 from app.notifier import telegram_sender as telegram_mod
+from app.notifier.base import NotifierActionError, NotifierActionResult
 from app.storage.db import get_user_settings, list_audit_logs, upsert_user_settings
 
 router = APIRouter(prefix="/api/settings", tags=["settings"])
@@ -34,17 +35,17 @@ def _test_message_error(
     http_status: int | None = None,
     error_code: Any | None = None,
     description: str | None = None,
-) -> dict[str, Any]:
+) -> NotifierActionError:
     # Keep a stable, cross-channel error shape for test_message endpoints.
     msg = str(message or "").strip()
     desc = str(description or msg).strip()
-    return {
-        "category": str(category or "").strip() or "provider_error",
-        "message": msg or desc or "unknown",
-        "http_status": int(http_status) if http_status is not None else None,
-        "error_code": error_code,
-        "description": desc or None,
-    }
+    return NotifierActionError(
+        category=str(category or "").strip() or "provider_error",
+        message=msg or desc or "unknown",
+        http_status=int(http_status) if http_status is not None else None,
+        error_code=error_code,
+        description=desc or None,
+    )
 
 
 def _now_iso_seconds() -> str:
@@ -405,7 +406,7 @@ async def put_telegram_credential(request: Request, payload: TelegramCredentialI
 
 
 @router.post("/notifications/telegram/test_message")
-async def post_telegram_test_message(request: Request) -> dict:
+async def post_telegram_test_message(request: Request) -> NotifierActionResult:
     user_id = get_holdings_user_id(request)
 
     # Cooldown check
@@ -459,7 +460,7 @@ async def post_telegram_test_message(request: Request) -> dict:
         req_payload["parse_mode"] = parse_mode
 
     max_attempts = retry_times + 1
-    last_error: dict[str, Any] | None = None
+    last_error: NotifierActionError | None = None
 
     for attempt in range(1, max_attempts + 1):
         try:
@@ -486,32 +487,34 @@ async def post_telegram_test_message(request: Request) -> dict:
                 )
                 # Record cooldown
                 _test_message_limiter.record_success(cooldown_key)
-                return {
-                    "ok": True,
-                    "sent": True,
-                    "trace_id": trace_id,
-                    "attempts": attempt,
-                    "max_attempts": max_attempts,
-                    "error": None,
-                }
+                return NotifierActionResult(
+                    ok=True,
+                    sent=True,
+                    trace_id=trace_id,
+                    attempts=attempt,
+                    max_attempts=max_attempts,
+                    error=None,
+                )
 
             error_code = resp_json.get("error_code") if isinstance(resp_json, dict) else None
             description = (
                 str(resp_json.get("description") or resp_json.get("message") or "").strip()
                 if isinstance(resp_json, dict)
                 else ""
             )
-            category = "provider_error"
+            category = "unknown"
             try:
                 code_int = int(error_code)
             except Exception:
                 code_int = -1
             if code_int == 401:
-                category = "unauthorized"
+                category = "auth_failed"
             elif code_int == 403:
                 category = "forbidden"
-            elif code_int == 400:
-                category = "bad_request"
+            elif code_int == 400 and "chat not found" in description.lower():
+                category = "chat_not_found"
+            elif code_int == 429:
+                category = "rate_limited"
             last_error = _test_message_error(
                 category,
                 description or category,
@@ -531,28 +534,28 @@ async def post_telegram_test_message(request: Request) -> dict:
         trace_id=trace_id,
         ok=False,
         sent=False,
-        error_category=str((last_error or {}).get("category") or "unknown"),
+        error_category=str(last_error.category if last_error else "unknown"),
     )
     _persist_last_test_history(
         user_id=user_id,
         channel="telegram",
         trace_id=trace_id,
         ok=False,
         sent=False,
-        error_category=str((last_error or {}).get("category") or "unknown"),
+        error_category=str(last_error.category if last_error else "unknown"),
+    )
+    return NotifierActionResult(
+        ok=False,
+        sent=False,
+        trace_id=trace_id,
+        attempts=max_attempts,
+        max_attempts=max_attempts,
+        error=last_error or _test_message_error("provider_error", "unknown"),
     )
-    return {
-        "ok": False,
-        "sent": False,
-        "trace_id": trace_id,
-        "attempts": max_attempts,
-        "max_attempts": max_attempts,
-        "error": last_error or _test_message_error("provider_error", "unknown"),
-    }
 
 
 @router.post("/notifications/feishu/test_message")
-async def post_feishu_test_message(request: Request) -> dict:
+async def post_feishu_test_message(request: Request) -> NotifierActionResult:
     user_id = get_holdings_user_id(request)
 
     # Cooldown check
@@ -592,7 +595,7 @@ async def post_feishu_test_message(request: Request) -> dict:
     retry_times = feishu_mod.FeishuSender._coerce_retry_times(section.get("retry_times", feishu_mod.DEFAULT_RETRY_TIMES))
     timeout_seconds = feishu_mod.FeishuSender._coerce_timeout(section.get("timeout_seconds", feishu_mod.DEFAULT_TIMEOUT_SECONDS))
     max_attempts = retry_times + 1
-    last_error: dict[str, Any] | None = None
+    last_error: NotifierActionError | None = None
 
     for attempt in range(1, max_attempts + 1):
         try:
@@ -622,14 +625,14 @@ async def post_feishu_test_message(request: Request) -> dict:
                 )
                 # Record cooldown on success
                 _test_message_limiter.record_success(cooldown_key)
-                return {
-                    "ok": True,
-                    "sent": True,
-                    "trace_id": trace_id,
-                    "attempts": attempt,
-                    "max_attempts": max_attempts,
-                    "error": None,
-                }
+                return NotifierActionResult(
+                    ok=True,
+                    sent=True,
+                    trace_id=trace_id,
+                    attempts=attempt,
+                    max_attempts=max_attempts,
+                    error=None,
+                )
 
             provider_message = str(resp_json.get("StatusMessage") or resp_json.get("msg") or "").strip() if isinstance(resp_json, dict) else ""
             category = "provider_error"
@@ -659,24 +662,24 @@ async def post_feishu_test_message(request: Request) -> dict:
         trace_id=trace_id,
         ok=False,
         sent=False,
-        error_category=str((last_error or {}).get("category") or "unknown"),
+        error_category=str(last_error.category if last_error else "unknown"),
     )
     _persist_last_test_history(
         user_id=user_id,
         channel="feishu",
         trace_id=trace_id,
         ok=False,
         sent=False,
-        error_category=str((last_error or {}).get("category") or "unknown"),
+        error_category=str(last_error.category if last_error else "unknown"),
+    )
+    return NotifierActionResult(
+        ok=False,
+        sent=False,
+        trace_id=trace_id,
+        attempts=max_attempts,
+        max_attempts=max_attempts,
+        error=last_error or _test_message_error("provider_error", "unknown"),
     )
-    return {
-        "ok": False,
-        "sent": False,
-        "trace_id": trace_id,
-        "attempts": max_attempts,
-        "max_attempts": max_attempts,
-        "error": last_error or _test_message_error("provider_error", "unknown"),
-    }
 
 
 @router.get("/notifications/status")

backend/app/api/test_notifier_channels_smoke.py

@@ -51,14 +51,14 @@ def test_dispatcher_telegram_disabled_and_unknown_channel(self) -> None:
             settings={"notifications": {"telegram": {"enabled": False}}},
         )
         self.assertEqual(telegram_result.channel, "telegram")
-        self.assertEqual(bool(telegram_result.success), False)
-        self.assertEqual(bool(telegram_result.skipped), True)
-        self.assertEqual(str(telegram_result.code), "disabled")
+        self.assertEqual(telegram_result.ok, False)
+        self.assertEqual(telegram_result.sent, False)
+        self.assertIn("disabled", telegram_result.error)
 
         unknown_result = dispatcher.send(channel="slack", payload=payload, settings={})
-        self.assertEqual(bool(unknown_result.success), False)
-        self.assertEqual(bool(unknown_result.skipped), True)
-        self.assertEqual(str(unknown_result.code), "channel_not_supported")
+        self.assertEqual(unknown_result.ok, False)
+        self.assertEqual(unknown_result.sent, False)
+        self.assertIn("not supported", unknown_result.error)
 
 
 if __name__ == "__main__":

backend/app/api/test_notifier_feishu_sender_smoke.py

@@ -22,19 +22,19 @@ def test_disabled_channel_returns_skipped(self) -> None:
             settings={"notifications": {"feishu": {"enabled": False}}},
         )
         self.assertEqual(result.channel, "feishu")
-        self.assertEqual(bool(result.success), False)
-        self.assertEqual(bool(result.skipped), True)
-        self.assertEqual(result.code, "disabled")
+        self.assertEqual(result.ok, False)
+        self.assertEqual(result.sent, False)
+        self.assertIn("disabled", result.error)
 
     def test_missing_webhook_returns_skipped(self) -> None:
         result = self.sender.send(
             payload=self.payload,
             settings={"notifications": {"feishu": {"enabled": True, "webhook_url": ""}}},
         )
         self.assertEqual(result.channel, "feishu")
-        self.assertEqual(bool(result.success), False)
-        self.assertEqual(bool(result.skipped), True)
-        self.assertEqual(result.code, "config_missing")
+        self.assertEqual(result.ok, False)
+        self.assertEqual(result.sent, False)
+        self.assertIn("missing", result.error)
 
     def test_retry_and_success(self) -> None:
         with patch("app.notifier.feishu_sender._http_post_json") as mocked_post:
@@ -48,7 +48,7 @@ def test_retry_and_success(self) -> None:
                     "notifications": {
                         "feishu": {
                             "enabled": True,
-                            "webhook_url": "https://example.com/webhook",
+                            "webhook_url": "https://open.feishu.cn/webhook",
                             "retry_times": 2,
                             "timeout_seconds": 1.5,
                             "template": "title_content_metadata",
@@ -58,10 +58,10 @@ def test_retry_and_success(self) -> None:
             )
 
         self.assertEqual(mocked_post.call_count, 2)
-        self.assertEqual(bool(result.success), True)
-        self.assertEqual(bool(result.skipped), False)
-        self.assertEqual(result.code, "ok")
-        self.assertEqual(result.provider_message_id, "msg-001")
+        self.assertEqual(result.ok, True)
+        self.assertEqual(result.sent, True)
+        self.assertEqual(result.trace_id, "msg-001")
+        self.assertEqual(result.attempts, 2)
 
     def test_exhaust_retries_returns_failed(self) -> None:
         with patch("app.notifier.feishu_sender._http_post_json") as mocked_post:
@@ -72,18 +72,18 @@ def test_exhaust_retries_returns_failed(self) -> None:
                     "notifications": {
                         "feishu": {
                             "enabled": True,
-                            "webhook_url": "https://example.com/webhook",
+                            "webhook_url": "https://open.feishu.cn/webhook",
                             "retry_times": 1,
                         }
                     }
                 },
             )
 
         self.assertEqual(mocked_post.call_count, 2)
-        self.assertEqual(bool(result.success), False)
-        self.assertEqual(bool(result.skipped), False)
-        self.assertEqual(result.code, "send_failed")
-        self.assertIn("attempts=2", result.message)
+        self.assertEqual(result.ok, False)
+        self.assertEqual(result.sent, False)
+        self.assertIn("feishu send failed", result.error)
+        self.assertEqual(result.attempts, 2)
 
     def test_content_only_template(self) -> None:
         with patch("app.notifier.feishu_sender._http_post_json", return_value=(200, {"StatusCode": 0})) as mocked_post:
@@ -93,14 +93,14 @@ def test_content_only_template(self) -> None:
                     "notifications": {
                         "feishu": {
                             "enabled": True,
-                            "webhook_url": "https://example.com/webhook",
+                            "webhook_url": "https://open.feishu.cn/webhook",
                             "template": "content_only",
                         }
                     }
                 },
             )
 
-        self.assertEqual(bool(result.success), True)
+        self.assertEqual(result.ok, True)
         sent_payload = mocked_post.call_args.args[1]
         sent_text = sent_payload["content"]["text"]
         self.assertIn("profit +1.28%", sent_text)

backend/app/api/test_notifier_telegram_sender_smoke.py

@@ -13,17 +13,17 @@ def test_disabled_skips(self) -> None:
         payload = NotificationPayload(title="Daily", content="Hello")
         result = sender.send(payload=payload, settings={"notifications": {"telegram": {"enabled": False}}})
         self.assertEqual(result.channel, "telegram")
-        self.assertEqual(bool(result.success), False)
-        self.assertEqual(bool(result.skipped), True)
-        self.assertEqual(str(result.code), "disabled")
+        self.assertEqual(result.ok, False)
+        self.assertEqual(result.sent, False)
+        self.assertIn("disabled", result.error)
 
     def test_missing_config_skips(self) -> None:
         sender = TelegramSender()
         payload = NotificationPayload(title="Daily", content="Hello")
         result = sender.send(payload=payload, settings={"notifications": {"telegram": {"enabled": True}}})
-        self.assertEqual(bool(result.success), False)
-        self.assertEqual(bool(result.skipped), True)
-        self.assertEqual(str(result.code), "config_missing")
+        self.assertEqual(result.ok, False)
+        self.assertEqual(result.sent, False)
+        self.assertIn("missing", result.error)
 
     def test_send_success_mocked(self) -> None:
         sender = TelegramSender()
@@ -43,10 +43,10 @@ def test_send_success_mocked(self) -> None:
         }
         with patch("app.notifier.telegram_sender._http_post_json", return_value=(200, {"ok": True, "result": {"message_id": 7}})):
             result = sender.send(payload=payload, settings=settings)
-        self.assertEqual(bool(result.success), True)
-        self.assertEqual(bool(result.skipped), False)
-        self.assertEqual(str(result.code), "ok")
-        self.assertEqual(str(result.provider_message_id), "7")
+        self.assertEqual(result.ok, True)
+        self.assertEqual(result.sent, True)
+        self.assertEqual(result.trace_id, "7")
+        self.assertEqual(result.attempts, 1)
 
     def test_send_failure_retries_and_fails(self) -> None:
         sender = TelegramSender()
@@ -63,14 +63,14 @@ def test_send_failure_retries_and_fails(self) -> None:
             }
         }
 
-        # Always fail.
+        # Always fail with 500 server error.
         with patch("app.notifier.telegram_sender._http_post_json", return_value=(500, {"ok": False, "description": "fail"})):
             result = sender.send(payload=payload, settings=settings)
-        self.assertEqual(bool(result.success), False)
-        self.assertEqual(bool(result.skipped), False)
-        self.assertEqual(str(result.code), "send_failed")
+        self.assertEqual(result.ok, False)
+        self.assertEqual(result.sent, False)
+        self.assertIn("telegram send failed", result.error)
+        self.assertEqual(result.attempts, 2)
 
 
 if __name__ == "__main__":
     unittest.main()
-