Improve Sidecar startup and health monitoring

Author: knqiufan

README.md

@@ -123,7 +123,7 @@ npm run dev
 
 # 独立 Sidecar（可选；Tauri 默认 auto_start_sidecar 会自动预热）
 cd agent
-python -m uvicorn app.main:app --host 127.0.0.1 --port 9527
+python run.py
 ```
 
 首次使用：在 **设置 → 模型** 中添加 Provider API Key，然后在 **Chat** 新建会话即可对话。

agent/README.md

@@ -6,7 +6,7 @@ Python Sidecar for MisakaX, providing LangGraph Agent orchestration and PowerMem
 
 ```bash
 pip install -r requirements.txt
-uvicorn app.main:app --host 127.0.0.1 --port 9527
+python run.py
 ```
 
 ## Health Check

agent/app/main.py

@@ -8,7 +8,7 @@
 from app.config import bridge_provider_api_keys, get_settings
 from app.dependencies import close_checkpointer, setup_checkpointer
 from app.routers.agent import router as agent_router
-from app.routers.health import router as health_router
+from app.routers.health import cache_health_capabilities, router as health_router
 from app.routers.info import router as info_router
 from app.routers.memory import router as memory_router
 
@@ -17,6 +17,7 @@
 async def lifespan(application: FastAPI):
     """Manage startup and shutdown lifecycle."""
     application.state.startup_time = time.time()
+    cache_health_capabilities(application)
     bridge_provider_api_keys()
     await setup_checkpointer()
     try:

agent/app/routers/health.py

@@ -1,14 +1,24 @@
-"""Health check endpoint with enhanced status reporting."""
+"""Health check endpoint with cached startup capability reporting."""
 
 import time
+from dataclasses import dataclass
 
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, FastAPI, Request
 
 from app.models import HealthResponse
 
 router = APIRouter()
 
 SIDECAR_VERSION = "0.1.0"
+_HEALTH_CAPABILITIES_STATE_KEY = "health_capabilities"
+
+
+@dataclass(frozen=True)
+class HealthCapabilities:
+    """Static Sidecar capabilities determined once during application startup."""
+
+    agent_ready: bool
+    capabilities: tuple[str, ...]
 
 
 def _agent_module_ready() -> bool:
@@ -47,27 +57,45 @@ def _powermem_available() -> bool:
         return False
 
 
+def detect_health_capabilities() -> HealthCapabilities:
+    """Inspect optional integrations once; installed packages do not change at runtime."""
+    agent_ready = _agent_module_ready() and (_deepagents_available() or _langgraph_available())
+    capabilities: list[str] = ["health", "info"]
+    if agent_ready:
+        capabilities.extend(["agent", "agent_stream"])
+    if _powermem_available():
+        capabilities.append("memory")
+    return HealthCapabilities(agent_ready=agent_ready, capabilities=tuple(capabilities))
+
+
+def cache_health_capabilities(application: FastAPI) -> HealthCapabilities:
+    """Populate the application-level health capability snapshot."""
+    capabilities = detect_health_capabilities()
+    setattr(application.state, _HEALTH_CAPABILITIES_STATE_KEY, capabilities)
+    return capabilities
+
+
+def get_cached_health_capabilities(application: FastAPI) -> HealthCapabilities:
+    """Read the startup snapshot, with a safe fallback for direct ASGI tests."""
+    cached = getattr(application.state, _HEALTH_CAPABILITIES_STATE_KEY, None)
+    if isinstance(cached, HealthCapabilities):
+        return cached
+    return cache_health_capabilities(application)
+
+
 @router.get("/health", response_model=HealthResponse)
 async def health_check(request: Request) -> HealthResponse:
     """Return health status with version, uptime, and capabilities."""
     startup_time: float = getattr(request.app.state, "startup_time", 0.0)
     uptime = time.time() - startup_time if startup_time > 0 else 0.0
 
-    agent_ready = _agent_module_ready() and (
-        _deepagents_available() or _langgraph_available()
-    )
-    capabilities: list[str] = ["health", "info"]
-    if agent_ready:
-        capabilities.append("agent")
-        capabilities.append("agent_stream")
-    if _powermem_available():
-        capabilities.append("memory")
+    health_capabilities = get_cached_health_capabilities(request.app)
 
     return HealthResponse(
         status="ok",
         service="misaka-agent",
         version=SIDECAR_VERSION,
         uptime_seconds=round(uptime, 2),
-        capabilities=capabilities,
-        agent_ready=agent_ready,
+        capabilities=list(health_capabilities.capabilities),
+        agent_ready=health_capabilities.agent_ready,
     )

agent/run.py

@@ -1,11 +1,12 @@
 """Standalone entry point for Nuitka builds.
 
 When compiled with Nuitka (--standalone / --onefile), the app object must be
-passed directly to uvicorn.run() instead of using the "app.main:app" string
-form, because Nuitka cannot resolve module-string imports at runtime.
+passed directly to Uvicorn instead of using the "app.main:app" string form,
+because Nuitka cannot resolve module-string imports at runtime.
 """
 
 import multiprocessing
+import logging
 import os
 import sys
 import types
@@ -62,20 +63,60 @@ def _get_windows_console_stream(_stream, _encoding, _errors):  # noqa: ANN001, A
 
 import uvicorn  # noqa: E402  (import after DLL dir registration)
 
-from app.config import get_settings  # noqa: E402
+from app.config import Settings, get_settings  # noqa: E402
 from app.main import app  # noqa: E402
 
 
-def main() -> None:
-    multiprocessing.freeze_support()
-    settings = get_settings()
-    uvicorn.run(
+SIDECAR_HTTP_KEEP_ALIVE_SECONDS = 35
+
+
+class SuccessfulHealthCheckAccessFilter(logging.Filter):
+    """Suppress only successful local health checks from Uvicorn access logs."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        args = record.args
+        if not isinstance(args, tuple) or len(args) < 5:
+            return True
+
+        try:
+            method = str(args[1]).upper()
+            path = str(args[2]).split("?", maxsplit=1)[0]
+            status_code = int(args[4])
+        except (TypeError, ValueError):
+            return True
+
+        return not (method in {"GET", "HEAD"} and path == "/health" and 200 <= status_code < 300)
+
+
+def configure_access_log_filter() -> None:
+    """Attach the health-check filter once without disturbing other handlers."""
+    access_logger = logging.getLogger("uvicorn.access")
+    if not any(
+        isinstance(log_filter, SuccessfulHealthCheckAccessFilter)
+        for log_filter in access_logger.filters
+    ):
+        access_logger.addFilter(SuccessfulHealthCheckAccessFilter())
+
+
+def build_uvicorn_config(settings: Settings) -> uvicorn.Config:
+    """Build the common development and packaged Sidecar server configuration."""
+    return uvicorn.Config(
         app,
         host=settings.host,
         port=settings.port,
         log_level=settings.log_level,
+        timeout_keep_alive=SIDECAR_HTTP_KEEP_ALIVE_SECONDS,
+        access_log=True,
     )
 
 
+def main() -> None:
+    multiprocessing.freeze_support()
+    settings = get_settings()
+    config = build_uvicorn_config(settings)
+    configure_access_log_filter()
+    uvicorn.Server(config).run()
+
+
 if __name__ == "__main__":
     sys.exit(main() or 0)

agent/tests/test_health.py

@@ -1,6 +1,9 @@
 """Tests for the health check endpoint."""
 
 import pytest
+from fastapi import FastAPI
+
+from app.routers import health
 
 
 @pytest.mark.asyncio
@@ -29,6 +32,36 @@ async def test_health_check_has_enhanced_fields(client):
         assert "agent_stream" in data["capabilities"]
 
 
+def test_health_capabilities_are_cached(monkeypatch):
+    application = FastAPI()
+    calls = {"agent": 0, "deepagents": 0, "powermem": 0}
+
+    def agent_ready() -> bool:
+        calls["agent"] += 1
+        return True
+
+    def deepagents_available() -> bool:
+        calls["deepagents"] += 1
+        return True
+
+    def powermem_available() -> bool:
+        calls["powermem"] += 1
+        return True
+
+    monkeypatch.setattr(health, "_agent_module_ready", agent_ready)
+    monkeypatch.setattr(health, "_deepagents_available", deepagents_available)
+    monkeypatch.setattr(health, "_langgraph_available", lambda: False)
+    monkeypatch.setattr(health, "_powermem_available", powermem_available)
+
+    first = health.get_cached_health_capabilities(application)
+    second = health.get_cached_health_capabilities(application)
+
+    assert first is second
+    assert first.agent_ready is True
+    assert first.capabilities == ("health", "info", "agent", "agent_stream", "memory")
+    assert calls == {"agent": 1, "deepagents": 1, "powermem": 1}
+
+
 @pytest.mark.asyncio
 async def test_health_check_is_get_only(client):
     response = await client.post("/health")

agent/tests/test_run.py

@@ -0,0 +1,38 @@
+"""Tests for the Sidecar Uvicorn entry-point configuration."""
+
+import logging
+
+from app.config import Settings
+from run import (
+    SIDECAR_HTTP_KEEP_ALIVE_SECONDS,
+    SuccessfulHealthCheckAccessFilter,
+    build_uvicorn_config,
+)
+
+
+def _access_record(method: str, path: str, status_code: int) -> logging.LogRecord:
+    return logging.LogRecord(
+        "uvicorn.access",
+        logging.INFO,
+        __file__,
+        1,
+        '%s - "%s %s HTTP/%s" %d',
+        ("127.0.0.1:12345", method, path, "1.1", status_code),
+        None,
+    )
+
+
+def test_successful_health_access_logs_are_filtered():
+    log_filter = SuccessfulHealthCheckAccessFilter()
+
+    assert not log_filter.filter(_access_record("GET", "/health", 200))
+    assert not log_filter.filter(_access_record("HEAD", "/health?verbose=1", 204))
+    assert log_filter.filter(_access_record("GET", "/health", 500))
+    assert log_filter.filter(_access_record("GET", "/agent/chat", 200))
+
+
+def test_uvicorn_config_keeps_local_connections_alive():
+    config = build_uvicorn_config(Settings(host="127.0.0.1", port=9527))
+
+    assert config.timeout_keep_alive == SIDECAR_HTTP_KEEP_ALIVE_SECONDS
+    assert config.access_log is True

docs/guides/rust-learning-faq-modules-and-lib.md

@@ -322,7 +322,7 @@ Rust 把名字分成多种 **命名空间（namespace）**（类型的、值的
 **`start` 在仓库里实际做了什么**（与 `CLAUDE.md` 里「Python Sidecar (:9527) + uvicorn」一致，实现见 `sidecar.rs`）：
 
 1. **健康检查**：对 **`http://127.0.0.1:{port}/health`** 发 GET；若已成功响应，认为 Sidecar 已在跑，**返回 `Ok(Self { child: None })`**（不再重复拉起进程）。
-2. **否则 spawn 子进程**：在当前机子上执行形如 **`python -m uvicorn app.main:app --host 127.0.0.1 --port <端口>`**，**工作目录**设为传入的 **`agent_dir`**（即仓库里的 **`agent/`** Python 工程，里面要有 `app.main:app`）。
+2. **否则 spawn 子进程**：在当前机子上执行形如 **`python <agent_dir>/run.py`**，并通过 `MISAKA_HOST=127.0.0.1` 与 `MISAKA_PORT=<port>` 传入监听地址；**工作目录**设为传入的 **`agent_dir`**（即仓库里的 **`agent/`** Python 工程）。
 3. **轮询等待**：最多约 **10 秒**，直到 **`/health`** 成功；成功则 **`Ok(Self { child: Some(child) })`**，把子进程放进管理器里。
 4. **超时**：杀掉子进程，**`Err(String)`** 说明健康检查超时。
 5. **`SidecarManager` 被 drop 时**（例如 `AppState` 释放：**`impl Drop`**）：若 **`child` 为 `Some`**，会 **kill + wait**，避免僵尸进程。

docs/guides/sidecar-nuitka-build.md

@@ -108,7 +108,7 @@ Anaconda 的 `_ssl.pyd` 依赖 `libcrypto-3-x64.dll` / `libssl-3-x64.dll`。`bui
 1. `agent/dist/misaka-agent.exe`（Windows）或 `agent/dist/misaka-agent`
 2. 当前应用 exe 同级目录的 `misaka-agent(.exe)`
 
-找到二进制时，Rust 使用 `MISAKA_HOST=127.0.0.1` 与 `MISAKA_PORT=<configured port>` 启动它；未找到时回退到开发模式的 `python -m uvicorn app.main:app --host 127.0.0.1 --port <port>`。
+找到二进制时，Rust 使用 `MISAKA_HOST=127.0.0.1` 与 `MISAKA_PORT=<configured port>` 启动它；未找到时回退到开发模式的 `python <agent-dir>/run.py`，并通过相同环境变量传递 host 与 port。
 
 因此：