foxclaw 0.1.2 → 0.1.3

package/python/foxclaw/api/__init__.py

@@ -3,43 +3,31 @@ Foxclaw API — FastAPI 后端
 前端控制台通过这里获取所有数据
 """
 
+import threading
 import os
 import asyncio
 import queue
 from pathlib import Path
 from contextlib import asynccontextmanager
 
-# 加载项目根目录的 .env(若存在),让所有 Key 从配置文件读取。
-#
-# 【FOXCLAW_SKIP_DOTENV】跳过 .env,只用进程环境变量 —— 专供测试/CI 使用。
-# 为什么必须有这个逃生口:load_dotenv(override=False) 只保护「进程里已存在的键」。
-# 测试若先 pop 掉某键(如 test_gateway.py pop FOXCLAW_API_KEY 以验证「未设即开放」),
-# 再 import 本模块,.env 就会把它灌回来 → 测试实际跑在开发者的真实配置上。
-# 后果有三:(1) 同一份代码在不同机器上结果不同,回归不可复现;
-# (2) .env 里的真实 Key 会让测试真的打到外部 API(产生费用);
-# (3) FOXCLAW_DATA_DIR=./foxclaw_data 会让测试写进用户的真实数据目录。
-# 设 FOXCLAW_SKIP_DOTENV=1 后,进程环境变量成为唯一来源,测试环境完全自洽。
 try:
     from ..core.envfile import load_env_file
     _env_path = Path(__file__).parent.parent.parent / ".env"
     if os.environ.get("FOXCLAW_SKIP_DOTENV", "").strip() in ("1", "true", "True", "yes"):
         print("[Foxclaw] ○ FOXCLAW_SKIP_DOTENV=1 —— 跳过 .env,仅用进程环境变量")
     elif _env_path.exists():
-        # 非空值优先:系统环境变量里的同名旧 key 不再压住 .env(见 core/envfile.py)
         _shadows = load_env_file(_env_path)
         print("[Foxclaw] ✓ 已加载配置文件 .env")
         if _shadows:
             print("[Foxclaw] ! .env 覆盖了系统环境变量: " + ", ".join(_shadows))
 except ImportError:
-    pass  # 未装 python-dotenv 则用系统环境变量
+    pass
 
 from fastapi import FastAPI
 from typing import Optional
 
 from foxclaw import Foxclaw, __version__
 
-# 中间件实现已移至 middleware.py;此处保留符号作 re-export(测试/外部经 foxclaw.api 访问),
-# 冗余别名 `X as X` 让 ruff 识别为显式 re-export(F401 硬门)。install_middleware 在下方调用。
 from .middleware import (
     install_middleware,
     _constant_time_eq as _constant_time_eq,
@@ -55,23 +43,15 @@ from .middleware import (
 
 from .routes.ws import manager, harness_websocket as harness_websocket
 
-# 事件脊柱辅助(WS 净化 / HKC 预热)已移至 spine.py;`_register_spine_projection` 因
-# `_WS_MUTED` 源码级断言约束仍留本文件(见 test_governance_audit)。
 from .spine import _ws_safe_payload, _prewarm_hkc
-# app 挂载/配置(CORS / HKC 星球数据面 / 前端静态)已移至 app.py,在下方按原顺序调用。
-from .app import _configure_cors, _mount_hkc, _mount_frontend
+from ._state import current_os, set_os_instance
+from ._state import os_instance as os_instance
 
+from .bootstrap import _configure_cors, _mount_hkc, _mount_frontend
 
-# ── 全局 OS 实例 ───────────────────────────────────────────
-_os_instance: Optional[Foxclaw] = None
-
-# 线程安全事件队列:harness 在任意线程触发的事件先入队,
-# 由后台 async 任务统一广播到 WebSocket(解决跨线程 create_task 失败问题)
 _event_queue: "queue.Queue" = queue.Queue()
 _broadcast_task: Optional[asyncio.Task] = None
-# HKC 后台预热守护线程:关闭 lifespan 前必须 join,否则 aclose() 关闭 SQLite 连接时
-# 预热线程仍在 build_index() → use-after-free → Windows access violation(偶发崩溃)。
-_prewarm_thread = None
+_prewarm_thread: "threading.Thread | None" = None
 
 
 def _register_spine_projection(os_instance: Foxclaw):
@@ -80,10 +60,6 @@ def _register_spine_projection(os_instance: Foxclaw):
     truth/process/memory 等系统事件被漏掉)。现在 harness 事件与系统事件同经脊柱,
     一个投影全量观测。payload 经 _ws_safe_payload 净化(JSON 安全 + 有界),避免脏/大
     对象丢连接或泛洪。event/data 形状与旧版一致(前端不受影响,未知事件被忽略)。"""
-    # 高频事件:给重放/审计用(仍在脊柱 history + robot sink),不广播到 WS 以免泛洪。
-    #   · agent.cognition.*：逐 stage 认知事件
-    #   · knowledge.created/updated：HKC 批量摄入一本书→数百条,量大;merged/conflict/
-    #     ability/agent.used_ability 等"有意义"的知识事件仍广播(低频、可观测知识演化)。
     _WS_MUTED = ("knowledge.created", "knowledge.updated")
 
     def project(evt):
@@ -99,32 +75,25 @@ def _register_spine_projection(os_instance: Foxclaw):
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
-    global _os_instance, _broadcast_task
-    # 启动自检:未设 FOXCLAW_API_KEY 即等于无鉴权。此处只做提醒(绑定地址由启动方式决定,
-    # 拿不到 host);__main__ 入口对「非回环 + 无鉴权」有硬拦截。
+    global _broadcast_task
     if not os.environ.get("FOXCLAW_API_KEY", "").strip():
         print("[Foxclaw API] ⚠ 未设置 FOXCLAW_API_KEY —— 当前无鉴权,"
               "仅本地回环安全;对外暴露前务必设置。")
-    _os_instance = Foxclaw(
+    os_inst = Foxclaw(
         data_dir=os.environ.get("FOXCLAW_DATA_DIR", "./foxclaw_data"),
         shadow_rounds=settings.get_int("FOXCLAW_SHADOW_ROUNDS"),
     )
-    _register_spine_projection(_os_instance)
-    # trace 落库(与其它 SQLite 同放 data_dir):内存环只留最近若干条且重启即失,
-    # 落库后才能"查昨天那次慢请求"。只留慢的/出错的 + 采样,见 tracing._should_persist。
+    set_os_instance(os_inst)
+    _register_spine_projection(os_inst)
     try:
         from ..core.tracing import TRACES
-        TRACES.attach_db(Path(_os_instance.data_dir) / "traces.db")
+        TRACES.attach_db(Path(os_inst.data_dir) / "traces.db")
     except Exception as e:
         print(f"[Foxclaw API] ⚠ trace 持久化未启用: {e}")
-    # 后台任务:把队列里的事件广播到所有 WebSocket
     _broadcast_task = asyncio.create_task(_drain_event_queue())
     print("[Foxclaw API] ✓ 事件广播任务已启动")
-    # 预热 HKC:开机后台加载知识核心(装配 + HKC 多语言 embedding 模型 + 搜索索引 over 全量 KU),
-    # 免得"重启后第一次知识查询"触发冷装配卡 ~1 分钟。后台守护线程跑、不阻塞启动;失败静默。
-    _prewarm_hkc(_os_instance)
+    _prewarm_hkc(os_inst)
     if _foxclaw_mcp is not None:
-        # 内置 MCP 服务器的 session_manager 需在 app lifespan 内 run()
         async with _foxclaw_mcp.session_manager.run():
             print("[Foxclaw API] ✓ 内置 MCP 服务器已挂载 /api/mcp/")
             yield
@@ -136,13 +105,11 @@ async def lifespan(app: FastAPI):
             await _broadcast_task
         except asyncio.CancelledError:
             pass
-    # 释放持有原生资源的子系统(浏览器专用线程/会话),避免进程无法干净退出。
-    # 先 join HKC 预热线程:预热在后台线程对 SQLite 建索引,若不 join 就直接 aclose()
-    # 关闭 SQLite 连接,会与预热线程产生 use-after-free → Windows access violation。
     if _prewarm_thread is not None and _prewarm_thread.is_alive():
         _prewarm_thread.join(timeout=120.0)
-    if _os_instance is not None:
-        await _os_instance.aclose()
+    live = current_os()
+    if live is not None:
+        await live.aclose()
     print("[Foxclaw API] 关闭中...")
 
 
@@ -152,8 +119,6 @@ async def _drain_event_queue():
     loop = asyncio.get_running_loop()
     while True:
         try:
-            # 带超时地阻塞取队列:超时让线程周期性醒来,
-            # 以便被 cancel 时 executor 线程能干净退出(否则进程无法结束)
             try:
                 event = await loop.run_in_executor(
                     None, lambda: _event_queue.get(timeout=0.5))
@@ -166,14 +131,12 @@ async def _drain_event_queue():
             await asyncio.sleep(0.1)
 
 
-# ── 内置 MCP 服务器(默认关;FOXCLAW_MCP_SERVER=1 开)──────────
-# 把只读知识+记忆暴露成 MCP 工具,挂 /api/mcp/(自动受 X-API-Key 中间件保护)。
 _foxclaw_mcp = None
 _foxclaw_mcp_app = None
 if os.environ.get("FOXCLAW_MCP_SERVER", "0").strip() in ("1", "true", "True"):
     from ..mcp_server import build_foxclaw_mcp
     _mcp_agents = os.environ.get("FOXCLAW_MCP_AGENTS", "0").strip() in ("1", "true", "True")
-    _foxclaw_mcp = build_foxclaw_mcp(lambda: _os_instance, expose_agents=_mcp_agents)
+    _foxclaw_mcp = build_foxclaw_mcp(lambda: current_os(), expose_agents=_mcp_agents)
     _foxclaw_mcp_app = _foxclaw_mcp.streamable_http_app()
     if _mcp_agents:
         print("[Foxclaw API] ⚠ MCP 已暴露 Agent 调度(ask_foxclaw)——外部客户端可驱动你的认知 Agent")
@@ -183,86 +146,64 @@ if os.environ.get("FOXCLAW_MCP_SERVER", "0").strip() in ("1", "true", "True"):
     if os.environ.get("FOXCLAW_CORS_ORIGINS", "").strip() == "*":
         print("[Foxclaw API] ⚠ MCP 已开启但 CORS=* —— 生产建议用 FOXCLAW_CORS_ORIGINS 收紧允许来源")
 
-app = FastAPI(
+app: FastAPI = FastAPI(
     title="Foxclaw API",
     version=__version__,
     description="Cognitive Agent Operating System",
     lifespan=lifespan,
 )
 if _foxclaw_mcp_app is not None:
-    app.mount("/api/mcp", _foxclaw_mcp_app)   # 受 _api_key_guard 保护(startswith /api)
+    app.mount("/api/mcp", _foxclaw_mcp_app)
 
-# ── CORS 收紧:实现已移至 app.py ───────────────────────────
 _configure_cors(app)
 
 
-# ── 中间件注册(鉴权/网关限流/追踪/指标):实现已移至 middleware.py,这里按原顺序集中挂载 ──
 install_middleware(app)
 
-# ── WebSocket 路由:实现已移至 routes/ws.py ────────────────
 from .routes import ws as _ws
 _ws.register(app)
 
-# ── 系统/监控/追踪路由:实现已移至 routes/system.py(import 即注册) ────────────────
 from .routes import system  # noqa: F401
 
-# ── AHS 执行链路由:实现已移至 routes/ahs.py(import 即注册) ────────────────
 from .routes import ahs  # noqa: F401
 
-# ── 记忆/会话/偏好:routes/memory.py(import 即注册) ────────────────
 from .routes import memory  # noqa: F401
 
-# ── 任务执行/流式直答/流式任务:routes/task.py(import 即注册) ────────────────
 from .routes import task  # noqa: F401
 
-# ── 领域内核(财务/学习/行程):routes/domain.py(import 即注册) ────────────────
 from .routes import domain  # noqa: F401
 
-# ── 断点续跑现场:routes/recovery.py(import 即注册) ────────────────
 from .routes import recovery  # noqa: F401
 
-# ── 主管编排:routes/orchestration.py(import 即注册) ────────────────
 from .routes import orchestration  # noqa: F401
 
-# ── 浏览器子系统:routes/browser.py(import 即注册) ────────────────
 from .routes import browser  # noqa: F401
 
-# ── 知识核心(HKC):routes/knowledge.py(import 即注册) ────────────────
 from .routes import knowledge  # noqa: F401
 
-# ── SM-2 复习面:routes/review.py(import 即注册) ────────────────
 from .routes import review  # noqa: F401
 
-# ── 认知搜索(HSR):routes/search.py(import 即注册) ────────────────
 from .routes import search  # noqa: F401
 
-# ── 聊天附件上传/下载(多模态渲染·步骤7):routes/attachments.py(import 即注册) ────────────────
 from .routes import attachments  # noqa: F401
 
-# ── 前端 LLM 管理(下拉式选模型 + 自定义):routes/llm_admin.py(import 即注册) ──────
 from .routes import llm_admin  # noqa: F401
 
-# 搬移前这些是 api 模块级符号,测试/外部仍经 foxclaw.api 访问 → re-export
 from .routes.task import _sanitize_images, _sanitize_attachments, _MAX_IMAGES, _MAX_IMG_B64, _STREAM_LIMITER  # noqa: F401
 from .routes.domain import _parse_import_rows  # noqa: F401
 from .routes.knowledge import knowledge_ability as knowledge_ability, _HKCInsuffCov as _HKCInsuffCov  # noqa: F401
 from ..core import settings
 
 
-# ── HKC 星球数据面:实现已移至 app.py ─────────────────────
 _mount_hkc(app)
 
 
-# ── 前端静态文件:实现已移至 app.py ─────────────────────────
 _mount_frontend(app)
 
 
 if __name__ == "__main__":
     import uvicorn
 
-    # 默认只绑回环地址(本地开发)。对外暴露必须显式设 FOXCLAW_HOST,且应同时设置 FOXCLAW_API_KEY——
-    # 否则该端口上任何可达者都能读写记忆、执行技能、摄入文件(这些端点全部无鉴权)。
-    # 用 `python -m uvicorn foxclaw.api:app --host ...` 启动时会绕过本检查,故 lifespan 另有软提醒。
     _host = os.environ.get("FOXCLAW_HOST", "127.0.0.1").strip() or "127.0.0.1"
     _port = settings.get_int("FOXCLAW_PORT")
     _LOOPBACK = {"127.0.0.1", "localhost", "::1", "[::1]"}

package/python/foxclaw/api/_state.py

@@ -0,0 +1,43 @@
+"""API 层共享 OS 实例的状态与访问器。
+
+为什么独立成模块
+----------------
+`foxclaw/api/__init__.py` 受 15KB 单文件体积门（tools/size_check.py）约束，装配逻辑
+已贴着上限。把「状态 + 访问器」放这里，既让 13 个路由文件能统一取实例，也不让主装配
+文件继续膨胀。
+
+读写契约
+--------
+写入只有 `set_os_instance()`（lifespan 启动时调用一次）；读取两个入口：
+
+  - `os_instance()`：要求实例必须就绪，未就绪抛 503（可重试），用于正常请求路径
+  - `current_os()`：允许未就绪返回 None，用于「无 OS 也要降级返回」的只读路径
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional
+
+from fastapi import HTTPException
+
+if TYPE_CHECKING:
+    from foxclaw import Foxclaw
+
+_os_instance: Optional["Foxclaw"] = None
+
+
+def set_os_instance(inst: "Foxclaw") -> None:
+    global _os_instance
+    _os_instance = inst
+
+
+def current_os() -> Optional["Foxclaw"]:
+    return _os_instance
+
+
+def os_instance() -> "Foxclaw":
+    """取共享 OS 实例;未就绪时抛 503 而不是让调用方吃到 NoneType 属性错误。"""
+    inst = _os_instance
+    if inst is None:
+        raise HTTPException(
+            status_code=503, detail="service is starting up, retry shortly")
+    return inst

package/python/foxclaw/api/{app.py → bootstrap.py}

@@ -15,14 +15,6 @@ import foxclaw.api as _api
 
 
 def _configure_cors(app):
-    # ── 可选鉴权 + CORS 收紧（部署安全）──────────────────────────
-    # FOXCLAW_API_KEY 未设 → 开放(本地默认,保持现状,既有测试/前端不受影响)。
-    # 设了 → 所有 /api/* 请求必须带正确的 X-API-Key,否则 401。
-    # 注意:http 中间件**看不到 websocket scope**,故 /ws 的鉴权在 WS 端点内单独做
-    # (见 harness_websocket,用 ?key= 查询参数)。前端(静态)与 /docs 始终开放。
-    # 默认只放行回环来源(本地开发足够:前端与 API 是同源挂载,同源请求本就不经 CORS)。
-    # 需要跨源时设 FOXCLAW_CORS_ORIGINS=来源1,来源2(逗号分隔);显式设 "*" 才会全开(不推荐,
-    # 与未鉴权叠加等于把 API 交给任意网页)。收紧默认值属于「默认安全」:不再默认 allow_origins=["*"]。
     _cors_env = os.environ.get("FOXCLAW_CORS_ORIGINS", "").strip()
     if _cors_env == "*":
         _CORS_ORIGINS = ["*"]
@@ -44,12 +36,6 @@ def _configure_cors(app):
 
 
 def _mount_hkc(app):
-    # ── HKC 星球数据面:挂载 HKC 自带的 /knowledge REST 路由 ──────────────────
-    # 星球 UI(frontend/planet)需要 /knowledge/graph、/ku/{id}、/ku/{id}/neighbors、
-    # /ingest/*、/reset 等。HKC 在本进程装配,这里把它自带的 knowledge 路由挂上,并用
-    # dependency_overrides 把 get_container 指向 **Foxclaw 已装配的同一个容器**(依赖倒置,
-    # 不另开一套;保持惰性:首个 /knowledge 请求才触发 HKC 装配)。鉴权由上面中间件覆盖 /knowledge。
-    # 缺 vendor/hkc 或导入失败 → 静默跳过(星球无数据但不影响主应用)。
     try:
         from foxclaw.knowledge import _ensure_hkc_importable as _ensure_hkc
         _ensure_hkc()
@@ -57,33 +43,24 @@ def _mount_hkc(app):
         from hkc_api.container import get_container as _hkc_get_container
 
         def _resolve_hkc_container():
-            svc = _api._os_instance.hkc if _api._os_instance is not None else None
+            os_inst = _api.current_os()
+            svc = os_inst.hkc if os_inst is not None else None
             if svc is None or not getattr(svc, "available", False):
                 raise HTTPException(503, "HKC 未启用(未 vendor 或缺依赖)")
             return svc.container
 
         app.dependency_overrides[_hkc_get_container] = _resolve_hkc_container
         app.include_router(_hkc_knowledge_router)
-        # /stats 系统统计:独立 hkc-api 在 main.py 顶层 @app.get("/stats") 定义,不在任何
-        # router 里,嵌入式挂载时会漏掉 → 星球 UI 的 updateDataInfo 调 /stats 404,
-        # 「数据目录 / 全库知识总数」提示失效。这里补挂,复用同一容器 override(惰性装配)。
         @app.get("/stats", tags=["system"])
         def _hkc_stats():
             return _resolve_hkc_container().stats()
-        # 连接设置(星球 UI 左下的「连接设置」面板)POST /config/llm 做运行时 LLM 配置,
-        # 覆盖 .env 的 HKC_LLM_*。独立 hkc-api 有这个路由,嵌入式 foxclaw 之前没挂 → 前端
-        # 报「模型配置失败:404」且改配置无效。这里补挂 config 路由(同一容器 override 已覆盖),
-        # 让「连接设置」的「知识抽取模型」段在 foxclaw 下真正生效。
         from hkc_api.routes.config import router as _hkc_config_router
-        app.include_router(_hkc_config_router)   # /config/llm(GET 读配置 / POST 改配置)
-        # 星球副面板(冲突裁决/能力编译/最短路径)用的 HKC 路由。不挂的话 /conflicts、
-        # /abilities、/search/path 在 Foxclaw 下 404 → 星球「冲突裁决」面板拉不到数据、
-        # 永远显示 0(误导),能力/路径面板同样空。这里补挂(同一容器 override 已覆盖)。
+        app.include_router(_hkc_config_router)
         try:
             from hkc_api.routes.ability import router as _hkc_ability_router
             from hkc_api.routes.search  import router as _hkc_search_router
-            app.include_router(_hkc_ability_router)   # /abilities, /conflicts
-            app.include_router(_hkc_search_router)     # /search/path 等
+            app.include_router(_hkc_ability_router)
+            app.include_router(_hkc_search_router)
             _sub = "/abilities, /conflicts, /search/*"
         except Exception as _e2:
             _sub = f"(能力/搜索路由未挂: {_e2})"
@@ -93,10 +70,6 @@ def _mount_hkc(app):
 
 
 def _mount_frontend(app):
-    # ── 前端静态文件 ───────────────────────────────────────────
-    # frontend/ 下现在并存三套:frontend/v3(Vue,当前主界面)、deck_v2.html(旧主界面)、
-    # deck.html(最早的一版)。根路径必须给 v3 —— 之前一直指向 deck_v2,新版只能手输 /v3/,
-    # 等于新界面根本没上线。
     frontend_dir = Path(__file__).parent.parent.parent / "frontend"
     if not frontend_dir.exists():
         return

package/python/foxclaw/api/middleware.py

@@ -60,7 +60,7 @@ def _loopback_bypass_on() -> bool:
         return False
     if v == "1":
         return True
-    return True  # 默认开
+    return True
 
 
 def _host_header_allowed(host_header: str) -> bool:
@@ -80,8 +80,8 @@ def _host_header_allowed(host_header: str) -> bool:
     """
     raw = (host_header or "").strip().lower()
     if not raw:
-        return True                     # 无 Host(HTTP/1.0 或测试直连)→ 不在此拦
-    if raw.startswith("["):             # [::1]:8000
+        return True
+    if raw.startswith("["):
         hostname = raw.split("]")[0].lstrip("[")
     else:
         hostname = raw.rsplit(":", 1)[0] if raw.count(":") == 1 else raw
@@ -90,7 +90,7 @@ def _host_header_allowed(host_header: str) -> bool:
         return True
 
     import ipaddress
-    try:                                # IP 字面量:只放行回环/私网
+    try:
         ip = ipaddress.ip_address(hostname)
     except ValueError:
         ip = None
@@ -104,7 +104,7 @@ def _host_header_allowed(host_header: str) -> bool:
             return True
         if hostname == pat:
             return True
-    return "." not in hostname            # 单标签主机名(localhost/testserver/机器名)放行
+    return "." not in hostname
 
 
 def _is_guarded_path(path: str) -> bool:
@@ -131,8 +131,6 @@ async def _api_key_guard(request, call_next):
     校验 X-API-Key。详见 _loopback_bypass_on。"""
     api_key = os.environ.get("FOXCLAW_API_KEY", "").strip()
     path = request.url.path
-    # 【P3-rebind】与是否配 key 无关:本机开发(无 key、回环监听)才是 DNS rebinding
-    # 的典型受害场景,所以这层放在 api_key 分支之外,默认部署也生效。
     if _is_guarded_path(path):
         _client = request.client.host if request.client else ""
         if _is_loopback_client(_client) and not _host_header_allowed(
@@ -142,21 +140,13 @@ async def _api_key_guard(request, call_next):
                 {"error": "forbidden: Host 头不是本机地址(已启用 DNS rebinding 防护)。"
                           "自建域名请加入 FOXCLAW_ALLOWED_HOSTS。"}, status_code=403)
     if api_key:
-        # /knowledge/* 是 HKC 星球的数据面(graph/ingest/reset),必须同 /api 一起鉴权,
-        # 否则 ingest/reset/graph 对公众开放(泄密+可乱写)。/ws 由端点内部鉴权。
         if _is_guarded_path(path):
-            # CORS 预检(OPTIONS + Access-Control-Request-Method)按规范**不携带**自定义请求头,
-            # 浏览器也不会给它带 X-API-Key。必须放行交给 CORSMiddleware 处理;否则一旦启用鉴权,
-            # 跨源请求会在预检阶段被 401 拦死(且响应无 CORS 头,浏览器只报 CORS 错误,极难定位)。
             if request.method == "OPTIONS" and request.headers.get("access-control-request-method"):
                 return await call_next(request)
-            # 【P3-loopback】本机回环自动放行:与 docs 哲学「回环地址安全」对齐,
-            # 避免本地开发时浏览器填 key 的体验摩擦。设 FOXCLAW_LOOPBACK_BYPASS=0 可关。
             if _loopback_bypass_on():
                 client_host = request.client.host if request.client else ""
                 if _is_loopback_client(client_host):
                     return await call_next(request)
-            # 【P3-1】常量时间比对,防对 API Key 的计时攻击(MCP 暴露后更重要)
             if not _constant_time_eq(request.headers.get("X-API-Key", "") or "", api_key):
                 from fastapi.responses import JSONResponse
                 return JSONResponse(
@@ -164,13 +154,10 @@ async def _api_key_guard(request, call_next):
     return await call_next(request)
 
 
-# ── 统一 API 网关:per-client 限流 + 配额(把散落的单点限流收敛成一层)──────────
 _GATEWAY = Gateway(
     rate_per_min=settings.get_int("FOXCLAW_GATEWAY_RATE"),
     quota_per_hour=settings.get_int("FOXCLAW_GATEWAY_QUOTA"),
 )
-# 请求体硬顶(始终生效,不依赖限流开关):防超大 body 在解析/sanitize 前就吃满内存。
-# 最大合法体是文件摄入(路由内 20MB 上限),故 32MB 顶对正常流量无感。
 _MAX_BODY = settings.get_int("FOXCLAW_MAX_BODY_MB") * 1024 * 1024
 
 
@@ -220,21 +207,16 @@ async def _gateway_mw(request, call_next):
     超限 → 429 + Retry-After。默认关(本地);配鉴权或显式开启才生效。"""
     path = request.url.path
     guarded = _is_guarded_path(path)
-    # ① 请求体大小硬顶(始终生效):Content-Length 超限 → 413,在读 body 前拦下
     if guarded:
         cl = request.headers.get("content-length")
         if cl and cl.isdigit() and int(cl) > _MAX_BODY:
             from fastapi.responses import JSONResponse
             return JSONResponse(
                 {"error": f"payload too large (>{_MAX_BODY // 1048576}MB)"}, status_code=413)
-        # chunked / 无 Content-Length:靠流上累计兜底(头检查只是快路径)
         _wrap_body_limit(request, _MAX_BODY)
-    # ② per-client 限流 + 配额(网关启用时)
     if guarded and _gateway_on():
         valid = os.environ.get("FOXCLAW_API_KEY", "").strip()
         hdr = (request.headers.get("X-API-Key") or "").strip()
-        # 【P3-1】常量时间比较:普通 == 的短路耗时可被用来逐位猜 key,
-        # 把请求从 ip:* 伪造成 k:* 身份绕过 IP 限流
         client = ("k:" + hdr) if (valid and _constant_time_eq(hdr, valid)) \
             else ("ip:" + (request.client.host if request.client else "anon"))
         allowed, retry, reason = _GATEWAY.check(client)
@@ -258,8 +240,6 @@ async def _trace_mw(request, call_next):
     path = request.url.path
     if not _is_guarded_path(path):
         return await call_next(request)
-    # 跨进程接链:外部(如经 /api/mcp 调进来的 Agent)带了 W3C traceparent 就复用其 trace_id,
-    # 这样两边的链路能对齐;非法/缺失则自己开一条(不信外部输入)。
     inbound = parse_traceparent(request.headers.get("traceparent"))
     tr = start_trace(f"{request.method} {path}", trace_id=inbound)
     try:
@@ -286,7 +266,6 @@ async def _metrics_mw(request, call_next):
         return resp
     finally:
         ms = (_t.perf_counter() - t0) * 1000.0
-        # 只按已匹配的路由模板分组;未匹配(404)统一记 "unmatched",防攻击者刷不同路径撑爆 key
         route = request.scope.get("route")
         ep = getattr(route, "path", None) or "unmatched"
         try:
@@ -302,8 +281,6 @@ def install_middleware(app):
     顺序即执行顺序(Starlette 中间件后加先执行),必须与搬移前完全一致:
     _api_key_guard → _gateway_mw → _trace_mw → _metrics_mw。
     """
-    # 【P3-loopback】启动审计日志:鉴权开启 + loopback bypass 默认开 → 打一行告知
-    # 运维者。设了 FOXCLAW_API_KEY 但又不想本机免密,显式 FOXCLAW_LOOPBACK_BYPASS=0。
     if os.environ.get("FOXCLAW_API_KEY", "").strip() and _loopback_bypass_on():
         import logging
         logging.getLogger("foxclaw").info(