Project-N-E-K-O
diff --git a/‎app/main_server.py‎
Lines changed: 2 additions & 0 deletions b/‎app/main_server.py‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎main_routers/proactive_router.py‎
Lines changed: 292 additions & 0 deletions b/‎main_routers/proactive_router.py‎
Lines changed: 292 additions & 0 deletions
@@ -1466,6 +1466,7 @@ async def get_response(self, path, scope):
 from main_routers.characters_router import router as characters_router # noqa
 from main_routers.cloudsave_router import router as cloudsave_router # noqa
 from main_routers.config_router import router as config_router # noqa
+from main_routers.proactive_router import router as proactive_router # noqa
 from main_routers.galgame_router import router as galgame_router # noqa
 from main_routers.jukebox_router import router as jukebox_router # noqa
 from main_routers.live2d_router import router as live2d_router # noqa
@@ -1512,6 +1513,7 @@ async def beacon_shutdown():
 
 # 挂载全部路由
 app.include_router(config_router)
+app.include_router(proactive_router)
 app.include_router(characters_router)
 app.include_router(live2d_router)
 app.include_router(vrm_router)
 
@@ -0,0 +1,292 @@
+# -*- coding: utf-8 -*-
+"""
+Proactive Chat Router
+
+主动搭话（proactive chat）模式与频率的统一 API。
+
+URL convention: 路由声明不带末尾斜杠（与 ``main_routers/config_router.py``
+保持一致；由 ``scripts/check_api_trailing_slash.py`` 守门）。
+
+提供四个端点：
+
+* ``GET  /api/proactive/mode``      — 读取当前模式（off / normal / focus / frequent / custom）
+* ``POST /api/proactive/mode``      — 套用一组预设
+* ``GET  /api/proactive/settings``  — 读取主动搭话相关字段当前值
+* ``POST /api/proactive/settings``  — 更新部分主动搭话字段（白名单内）
+
+所有写入复用 ``utils.preferences.save_global_conversation_settings``，
+保证白名单/类型校验/原子写入逻辑只在一处维护。
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Mapping
+
+from fastapi import APIRouter, Request
+
+from utils.cloudsave_runtime import MaintenanceModeError
+from utils.logger_config import get_module_logger
+from utils.preferences import (
+    aload_global_conversation_settings,
+    save_global_conversation_settings,
+)
+
+
+router = APIRouter(prefix="/api/proactive", tags=["proactive"])
+logger = get_module_logger(__name__, "Main")
+
+
+# 用户绝对控制权 —— 插件和预设禁止越权修改的字段。
+# ``proactiveVisionEnabled`` 是前端"隐私模式"开关的反面
+# (``is_privacy_mode_enabled() == not proactiveVisionEnabled``)，
+# 涉及屏幕内容采集，必须由用户本人在 UI 决定，任何 API 写入路径都要拒绝。
+_USER_OWNED_FIELDS = frozenset({
+    "proactiveVisionEnabled",
+})
+
+# 主动搭话所有可调字段（白名单子集；与 utils/preferences 的
+# _ALLOWED_CONVERSATION_SETTINGS 保持同步，但只暴露搭话相关字段）。
+# 注：``_PROACTIVE_FIELDS`` 仅用于**读路径**和模式反推，写路径会额外
+# 过滤掉 ``_USER_OWNED_FIELDS``。
+_PROACTIVE_BOOL_FIELDS = (
+    "proactiveChatEnabled",
+    "proactiveVisionEnabled",
+    "proactiveVisionChatEnabled",
+    "proactiveNewsChatEnabled",
+    "proactiveVideoChatEnabled",
+    "proactivePersonalChatEnabled",
+    "proactiveMusicEnabled",
+    "proactiveMemeEnabled",
+    "proactiveMiniGameInviteEnabled",
+)
+_PROACTIVE_INT_FIELDS = (
+    "proactiveChatInterval",
+    "proactiveVisionInterval",
+)
+_PROACTIVE_FIELDS = _PROACTIVE_BOOL_FIELDS + _PROACTIVE_INT_FIELDS
+# 写路径允许的字段：从全集里剔除用户专有字段。
+_PROACTIVE_WRITABLE_FIELDS = frozenset(_PROACTIVE_FIELDS) - _USER_OWNED_FIELDS
+
+
+# 预设模式：服务器端定义，避免每个调用方自己维护一份。
+# interval 单位与前端 ``app-state.js`` 一致 —— 秒。
+# 注：预设故意不包含 ``proactiveVisionEnabled``（隐私模式）；切换 mode
+# 不会改变用户的隐私选择。
+PROACTIVE_PRESETS: dict[str, dict[str, Any]] = {
+    "off": {
+        "proactiveChatEnabled": False,
+        "proactiveVisionChatEnabled": False,
+        "proactiveNewsChatEnabled": False,
+        "proactiveVideoChatEnabled": False,
+        "proactivePersonalChatEnabled": False,
+        "proactiveMusicEnabled": False,
+        "proactiveMemeEnabled": False,
+        "proactiveMiniGameInviteEnabled": False,
+    },
+    "normal": {
+        "proactiveChatEnabled": True,
+        "proactiveVisionChatEnabled": True,
+        "proactiveNewsChatEnabled": True,
+        "proactiveVideoChatEnabled": True,
+        "proactivePersonalChatEnabled": True,
+        "proactiveMusicEnabled": True,
+        "proactiveMemeEnabled": True,
+        "proactiveMiniGameInviteEnabled": True,
+        "proactiveChatInterval": 15,
+        "proactiveVisionInterval": 10,
+    },
+    # 低打扰：保留搭话与个人动态，关掉新闻/视频/音乐等噪声源，间隔放长。
+    # 不动 vision/隐私开关——是否允许看屏幕由用户自己决定。
+    "focus": {
+        "proactiveChatEnabled": True,
+        "proactiveVisionChatEnabled": False,
+        "proactiveNewsChatEnabled": False,
+        "proactiveVideoChatEnabled": False,
+        "proactivePersonalChatEnabled": True,
+        "proactiveMusicEnabled": False,
+        "proactiveMemeEnabled": False,
+        "proactiveMiniGameInviteEnabled": False,
+        "proactiveChatInterval": 60,
+        "proactiveVisionInterval": 60,
+    },
+    # 高频：全开，间隔最短。
+    "frequent": {
+        "proactiveChatEnabled": True,
+        "proactiveVisionChatEnabled": True,
+        "proactiveNewsChatEnabled": True,
+        "proactiveVideoChatEnabled": True,
+        "proactivePersonalChatEnabled": True,
+        "proactiveMusicEnabled": True,
+        "proactiveMemeEnabled": True,
+        "proactiveMiniGameInviteEnabled": True,
+        "proactiveChatInterval": 5,
+        "proactiveVisionInterval": 5,
+    },
+}
+
+# Self-check：预设里不应混入用户绝对控制权字段，也不应有拼写错误/不可写字段。
+# 每次模块加载时校验，把"加预设时忘了筛"和"键名打错被静默忽略"这两类回归
+# 都挡在导入阶段，而不是用户调 set_mode 才暴露。
+for _mode_name, _preset in PROACTIVE_PRESETS.items():
+    _leaked = set(_preset.keys()) & _USER_OWNED_FIELDS
+    if _leaked:
+        raise RuntimeError(
+            f"PROACTIVE_PRESETS[{_mode_name!r}] 不应包含用户专有字段: {sorted(_leaked)}"
+        )
+    _unknown = set(_preset.keys()) - _PROACTIVE_WRITABLE_FIELDS
+    if _unknown:
+        raise RuntimeError(
+            f"PROACTIVE_PRESETS[{_mode_name!r}] 包含未知/不可写字段: {sorted(_unknown)}"
+        )
+
+
+def _filter_proactive_subset(settings: dict[str, Any]) -> dict[str, Any]:
+    """从完整 conversation-settings 中挑出搭话相关字段。"""
+    return {k: v for k, v in settings.items() if k in _PROACTIVE_FIELDS}
+
+
+def _value_matches(actual: Any, expected: Any) -> bool:
+    """type-aware equality：避免 Python 的 ``True == 1`` / ``False == 0`` 陷阱。
+
+    ``save_global_conversation_settings`` 的 bool 字段校验是
+    ``isinstance(v, bool)``，会拒绝整数 ``0/1``；但若仅用 ``==`` 比较，
+    磁盘上的 ``True`` 与传入的 ``1`` 仍会被判等，回报"已生效"——这是
+    Codex 指出的同类问题。要求 ``type()`` 完全一致即可彻底切断。
+    """
+    return type(actual) is type(expected) and actual == expected
+
+
+async def _readback_persisted(payload: Mapping[str, Any]) -> tuple[dict[str, Any], list[str]]:
+    """保存后回读，返回 ``(applied, rejected)``。
+
+    判定规则是**按值 + 按类型严格比较**：
+    - 按值比较：``save_global_conversation_settings`` 做第二轮过滤时，被
+      丢弃的字段会保留原磁盘旧值；若仅判断 key 是否存在，"旧值已在磁盘
+      上 + 新值被拒"会被误标为已生效。
+    - 按类型比较：Python 中 ``True == 1`` / ``False == 0``；传 int ``1``
+      给 bool 字段时 saver 会拒，但磁盘 ``True`` 与传入 ``1`` 仍会
+      ``==`` 判等。``_value_matches`` 强制 ``type()`` 一致来切断这层陷阱。
+    """
+    latest = await aload_global_conversation_settings()
+    applied: dict[str, Any] = {}
+    rejected: list[str] = []
+    for k, v in payload.items():
+        if k in latest and _value_matches(latest[k], v):
+            applied[k] = latest[k]
+        else:
+            rejected.append(k)
+    return applied, rejected
+
+
+def _infer_mode(settings: dict[str, Any]) -> str:
+    """根据当前持久化的字段反推所属预设；不匹配任何预设则返回 ``custom``。
+
+    比较时仅考察 preset 显式列出的字段，缺失字段视为不匹配。
+    """
+    for mode_name, preset in PROACTIVE_PRESETS.items():
+        if all(settings.get(k) == v for k, v in preset.items()):
+            return mode_name
+    return "custom"
+
+
+@router.get("/mode")
+async def get_proactive_mode():
+    """读取当前模式 + 当前主动搭话相关字段。"""
+    try:
+        settings = await aload_global_conversation_settings()
+        subset = _filter_proactive_subset(settings)
+        return {
+            "success": True,
+            "mode": _infer_mode(subset),
+            "available_modes": list(PROACTIVE_PRESETS.keys()),
+            "settings": subset,
+        }
+    except Exception as e:
+        logger.exception(f"获取主动搭话模式失败: {e}")
+        return {"success": False, "error": "Internal server error", "mode": "custom", "settings": {}}
+
+
+@router.post("/mode")
+async def set_proactive_mode(request: Request):
+    """套用预设模式。
+
+    请求体：``{"mode": "off" | "normal" | "focus" | "frequent"}``
+    """
+    try:
+        data = await request.json()
+        if not isinstance(data, dict):
+            return {"success": False, "error": "请求体必须为对象"}
+        mode = data.get("mode")
+        if not isinstance(mode, str) or mode not in PROACTIVE_PRESETS:
+            return {
+                "success": False,
+                "error": f"未知模式: {mode!r}；可选值: {list(PROACTIVE_PRESETS.keys())}",
+            }
+
+        preset = PROACTIVE_PRESETS[mode]
+        if not await asyncio.to_thread(save_global_conversation_settings, dict(preset)):
+            return {"success": False, "error": "保存失败"}
+
+        applied, rejected = await _readback_persisted(preset)
+        result: dict[str, Any] = {"success": True, "mode": mode, "applied": applied}
+        if rejected:
+            # 预设里所有字段都应是合法值；若仍出现 rejected，多半是
+            # _ALLOWED_CONVERSATION_SETTINGS 漂移，需要 server 端跟进。
+            result["rejected"] = rejected
+        return result
+    except MaintenanceModeError:
+        raise
+    except Exception as e:
+        logger.exception(f"切换主动搭话模式失败: {e}")
+        return {"success": False, "error": "Internal server error"}
+
+
+@router.get("/settings")
+async def get_proactive_settings():
+    """读取当前主动搭话相关字段（白名单内）。"""
+    try:
+        settings = await aload_global_conversation_settings()
+        return {"success": True, "settings": _filter_proactive_subset(settings)}
+    except Exception as e:
+        logger.exception(f"获取主动搭话设置失败: {e}")
+        return {"success": False, "error": "Internal server error", "settings": {}}
+
+
+@router.post("/settings")
+async def update_proactive_settings(request: Request):
+    """部分更新主动搭话字段。请求体仅接受 ``_PROACTIVE_WRITABLE_FIELDS``
+    内字段；用户专有字段（``proactiveVisionEnabled`` 隐私模式）会被
+    显式拒绝并通过 ``rejected_user_owned`` 报告，其他未识别字段静默忽略。
+    底层 ``save_global_conversation_settings`` 还会再做一次类型 + 范围校验。"""
+    try:
+        data = await request.json()
+        if not isinstance(data, dict):
+            return {"success": False, "error": "请求体必须为对象"}
+
+        rejected_user_owned = sorted(set(data.keys()) & _USER_OWNED_FIELDS)
+        payload = {k: v for k, v in data.items() if k in _PROACTIVE_WRITABLE_FIELDS}
+        if not payload:
+            err: dict[str, Any] = {"success": False, "error": "没有可识别的主动搭话字段"}
+            if rejected_user_owned:
+                err["rejected_user_owned"] = rejected_user_owned
+            return err
+
+        if not await asyncio.to_thread(save_global_conversation_settings, payload):
+            return {"success": False, "error": "保存失败"}
+
+        applied, rejected = await _readback_persisted(payload)
+        result: dict[str, Any] = {"success": True, "applied": applied}
+        if rejected:
+            # 字段类型/范围不合法被底层丢弃，或磁盘旧值与传入值不符。
+            # 明确告知调用方避免误判为生效。
+            result["rejected"] = rejected
+        if rejected_user_owned:
+            # 用户绝对控制权字段被拒：调用方应通过 UI 引导用户自行设置。
+            result["rejected_user_owned"] = rejected_user_owned
+        return result
+    except MaintenanceModeError:
+        raise
+    except Exception as e:
+        logger.exception(f"更新主动搭话设置失败: {e}")
+        return {"success": False, "error": "Internal server error"}