foxclaw 0.1.0 → 0.1.2

package/python/foxclaw/api/__init__.py

@@ -0,0 +1,283 @@
+"""
+Foxclaw API — FastAPI 后端
+前端控制台通过这里获取所有数据
+"""
+
+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 则用系统环境变量
+
+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,
+    _is_guarded_path as _is_guarded_path,
+    _gateway_on as _gateway_on,
+    _GATEWAY as _GATEWAY,
+    _MAX_BODY as _MAX_BODY,
+    _api_key_guard as _api_key_guard,
+    _gateway_mw as _gateway_mw,
+    _trace_mw as _trace_mw,
+    _metrics_mw as _metrics_mw,
+)
+
+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
+
+
+# ── 全局 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
+
+
+def _register_spine_projection(os_instance: Foxclaw):
+    """【P0·统一事件脊柱】注册**单一投影**:EventSpine 上的每一条事件 → 线程安全队列
+    → WS 广播。取代旧的"逐 Agent 逐事件手工转发"(那时只有 harness 4 类事件能到前端,
+    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):
+        if evt.topic.startswith("agent.cognition.") or evt.topic in _WS_MUTED:
+            return
+        try:
+            _event_queue.put_nowait(
+                {"event": evt.topic, "data": _ws_safe_payload(evt.payload)})
+        except Exception:
+            pass
+    os_instance.event_spine.project(project)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    global _os_instance, _broadcast_task
+    # 启动自检:未设 FOXCLAW_API_KEY 即等于无鉴权。此处只做提醒(绑定地址由启动方式决定,
+    # 拿不到 host);__main__ 入口对「非回环 + 无鉴权」有硬拦截。
+    if not os.environ.get("FOXCLAW_API_KEY", "").strip():
+        print("[Foxclaw API] ⚠ 未设置 FOXCLAW_API_KEY —— 当前无鉴权,"
+              "仅本地回环安全;对外暴露前务必设置。")
+    _os_instance = 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。
+    try:
+        from ..core.tracing import TRACES
+        TRACES.attach_db(Path(_os_instance.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)
+    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
+    else:
+        yield
+    if _broadcast_task:
+        _broadcast_task.cancel()
+        try:
+            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()
+    print("[Foxclaw API] 关闭中...")
+
+
+async def _drain_event_queue():
+    """后台 async 循环:从线程安全队列取事件,广播到 WebSocket。"""
+    import queue as _queue_mod
+    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))
+            except _queue_mod.Empty:
+                continue
+            await manager.broadcast(event)
+        except asyncio.CancelledError:
+            break
+        except Exception:
+            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_app = _foxclaw_mcp.streamable_http_app()
+    if _mcp_agents:
+        print("[Foxclaw API] ⚠ MCP 已暴露 Agent 调度(ask_foxclaw)——外部客户端可驱动你的认知 Agent")
+    if not os.environ.get("FOXCLAW_API_KEY", "").strip():
+        print("[Foxclaw API] ⚠ 内置 MCP 服务器已开启但未设 FOXCLAW_API_KEY —— "
+              "对外暴露前务必设置,否则任何人可读你的知识/记忆")
+    if os.environ.get("FOXCLAW_CORS_ORIGINS", "").strip() == "*":
+        print("[Foxclaw API] ⚠ MCP 已开启但 CORS=* —— 生产建议用 FOXCLAW_CORS_ORIGINS 收紧允许来源")
+
+app = 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)
+
+# ── 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]"}
+    if _host not in _LOOPBACK and not os.environ.get("FOXCLAW_API_KEY", "").strip():
+        print(
+            f"\n[Foxclaw API] ⚠⚠  绑定 {_host} 但未设置 FOXCLAW_API_KEY:\n"
+            "    该端口上任何可达者都能读写记忆、执行技能、摄入文件。\n"
+            "    请设置 FOXCLAW_API_KEY,或改用 FOXCLAW_HOST=127.0.0.1。\n"
+            "    确认自担风险,可设 FOXCLAW_ALLOW_INSECURE=1 跳过此检查。\n"
+        )
+        if os.environ.get("FOXCLAW_ALLOW_INSECURE", "").strip() != "1":
+            raise SystemExit("[Foxclaw API] 已拒绝启动:非回环绑定 + 无鉴权。")
+    uvicorn.run(
+        "foxclaw.api:app",
+        host=_host,
+        port=_port,
+        reload=True,
+    )

package/python/foxclaw/api/app.py

@@ -0,0 +1,123 @@
+"""app 配置与挂载:CORS、HKC 星球数据面、前端静态文件。
+
+从 `foxclaw/api/__init__.py` 搬移出来的「挂载类」逻辑,均为接收 `app` 参数的纯函数,
+在 `__init__.py` 创建 `app` 之后按原顺序调用,保持行为不变。
+"""
+import os
+from pathlib import Path
+
+from fastapi import HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
+
+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 = ["*"]
+        _CORS_ORIGIN_REGEX = None
+    elif _cors_env:
+        _CORS_ORIGINS = [o.strip() for o in _cors_env.split(",") if o.strip()]
+        _CORS_ORIGIN_REGEX = None
+    else:
+        _CORS_ORIGINS = []
+        _CORS_ORIGIN_REGEX = r"^https?://(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$"
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=_CORS_ORIGINS,
+        allow_origin_regex=_CORS_ORIGIN_REGEX,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+
+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()
+        from hkc_api.routes.knowledge import router as _hkc_knowledge_router
+        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
+            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 已覆盖)。
+        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 等
+            _sub = "/abilities, /conflicts, /search/*"
+        except Exception as _e2:
+            _sub = f"(能力/搜索路由未挂: {_e2})"
+        print(f"[Foxclaw API] ✓ HKC 星球数据面已挂载 (/knowledge/*, /config/*, {_sub})")
+    except Exception as _e:
+        print(f"[Foxclaw API] · HKC 星球数据面未挂载(可选): {_e}")
+
+
+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
+
+    v3_index = frontend_dir / "v3" / "index.html"
+
+    @app.get("/")
+    async def serve_root():
+        """主界面。v3 未构建(没跑 npm run build)时退回旧 deck_v2,不让根路径 404。"""
+        if v3_index.exists():
+            return FileResponse(str(v3_index))
+        legacy = frontend_dir / "deck_v2.html"
+        return FileResponse(str(legacy if legacy.exists() else frontend_dir / "deck.html"))
+
+    @app.get("/classic")
+    async def serve_classic():
+        """旧界面(deck_v2,v5.34):新版出问题时的手动回退入口,也留着它的二级面板历史。"""
+        return FileResponse(str(frontend_dir / "deck_v2.html"))
+
+    @app.get("/old")
+    async def serve_deck_old():
+        return FileResponse(str(frontend_dir / "deck.html"))
+
+    app.mount("/", StaticFiles(directory=str(frontend_dir), html=True), name="frontend")