foxclaw 0.1.0 → 0.1.2

package/python/foxclaw/api/routes/review.py

@@ -0,0 +1,275 @@
+"""SM-2 复习面 —— 把知识库里的 KU 直接当复习卡。
+
+设计取舍:不新建「卡片表」。复习状态写进 ``KU.extra["review"]``,与 learning
+子系统沿用同一套约定、同一个 ``SpacedRepetition`` 引擎。这样「录入 → 抽取 →
+复习」是一条链:右栏录一句 → KDE 抽出 KU → 立刻可复习,不存在知识库一份、
+学习模块又一份的双写(用户对重复存储明确反感)。
+
+Evidence 是原文出处,单独看没有回忆价值,不进队列;其余 KU 都算卡片。
+"""
+
+import asyncio
+
+from dataclasses import asdict
+from datetime import datetime
+from fastapi import HTTPException
+from pydantic import BaseModel
+
+import foxclaw.api as _api
+from .. import app
+from foxclaw.learning import ReviewState, SpacedRepetition
+
+_SR = SpacedRepetition()
+
+_CARD_TYPES = {"Concept", "Fact", "Claim", "Entity"}
+
+# 扫描上限(每种卡片类型)。之前统一 query_all(4000),一是把 Evidence 这种绝对不会
+# 成卡的原文出处也一起拉出来(大文档导入后它是绝大多数行),二是 4000 之后的部分
+# 会被静默截断 → 复习统计少算。这里只查四种卡片类型,上限给到实际用不满的量级。
+_SCAN_LIMIT = 50000
+
+# ReviewState.to_dict() 会额外塞 mastery / is_due,读回来时必须剔掉才能重建
+_STATE_FIELDS = ("repetitions", "interval", "ease_factor", "due_date",
+                 "last_review", "total_reviews", "lapses")
+
+
+def _store():
+    """惰性取 HKC 的 graph_store,None 表示知识库没装配好(降级成空队列)。"""
+    try:
+        hkc = _api._os_instance.hkc
+        if hkc is None or not hkc.available:
+            return None
+        return hkc.container.graph_store
+    except Exception:
+        return None
+
+
+def _has_state(ku) -> bool:
+    return bool((ku.extra or {}).get("review"))
+
+
+def _days_left(state) -> int:
+    """按**日历日**算还剩几天,而不是 ``timedelta.days`` 向下取整。
+
+    ``ReviewState.days_until_due`` 用的是后者:明天此刻到期会算成 0,
+    于是「未来 7 天负荷」把明天的卡记进今天,而队列的 due 又是 0 —— 两个数字
+    互相打架,界面上看起来像 bug。这里统一到日历日,和人对「明天」的直觉一致。
+    """
+    try:
+        due = datetime.fromisoformat(state.due_date).date()
+    except Exception:
+        return 0
+    return max(0, (due - datetime.now().date()).days)
+
+
+def _hours_left(state) -> float:
+    """小时级剩余,给「不到一天」的卡显示得更准(前端据此说「今晚」还是「明天」)。"""
+    try:
+        delta = datetime.fromisoformat(state.due_date) - datetime.now()
+    except Exception:
+        return 0.0
+    return round(max(0.0, delta.total_seconds() / 3600), 1)
+
+
+def _load7(learned) -> dict:
+    """未来 7 天(0..6)的复习负荷,口径与队列一致。"""
+    by_day = {}
+    for s in learned:
+        d = 0 if s.is_due else _days_left(s)
+        if d <= 6:
+            by_day[str(d)] = by_day.get(str(d), 0) + 1
+    total = sum(by_day.values())
+    return {"window_days": 7, "total_due": total,
+            "daily_avg": round(total / 7, 2), "by_day": by_day,
+            "overdue": sum(1 for s in learned if s.is_due)}
+
+
+def _status_of(ku) -> str:
+    """KU.status 是**普通字符串列**(enums 里没有 KUStatus),不是枚举。
+
+    踩过的坑:写成 ``getattr(ku.status, "value", "active")`` 时,因为 str 没有
+    ``.value`` 属性,getattr 会静默回落成默认值 "active" —— 于是「已软删的卡」也能
+    通过校验被评分,复习进度写进一条已经消失的知识里。
+    """
+    s = getattr(ku, "status", None)
+    return str(getattr(s, "value", s) or "").lower()
+
+
+def _state_from(extra, ku_id: str) -> ReviewState:
+    raw = (extra or {}).get("review") or {}
+    return ReviewState(item_id=ku_id,
+                       **{k: raw[k] for k in _STATE_FIELDS if k in raw})
+
+
+def _state_of(ku) -> ReviewState:
+    return _state_from(ku.extra, ku.ku_id)
+
+
+def _card(ku, state) -> dict:
+    extra = ku.extra or {}
+    text = (extra.get("source_text") or extra.get("statement")
+            or extra.get("definition") or ku.summary or "")
+    return {
+        "ku_id": ku.ku_id,
+        "name": ku.name,
+        "ku_type": ku.ku_type.value,
+        "domain": ku.domain or "",
+        "summary": ku.summary or "",
+        "text": str(text)[:1500],
+        "tags": list(ku.tags or []),
+        "created_at": getattr(ku, "created_at", "") or "",
+        "is_new": not _has_state(ku),
+        "mastery": state.mastery,
+        "interval": state.interval,
+        "ease_factor": state.ease_factor,
+        "repetitions": state.repetitions,
+        "lapses": state.lapses,
+        "days_until_due": _days_left(state) if _has_state(ku) else 0,
+        "due_in_hours": _hours_left(state) if _has_state(ku) else 0,
+    }
+
+
+def _card_ku_types():
+    """四种卡片类型的 KUType 枚举;拿不到(未 vendor / 未加 sys.path)返回 None。"""
+    try:
+        from hkc_core.models.enums import KUType
+        return [t for t in KUType if t.value in _CARD_TYPES]
+    except Exception:
+        return None
+
+
+def _pairs(store):
+    """所有可当复习卡的 KU + 它们当前的复习状态。
+
+    只查四类卡片:Evidence(原文出处)单看没有回忆价值,Ability 是 ACE 编译产物,
+    两者都不进队列。之前用 query_all 会把它们一起拉出来再丢掉。
+    """
+    types = _card_ku_types()
+    if types is None:
+        raws = store.query_all(_SCAN_LIMIT)
+    else:
+        raws = []
+        for t in types:
+            raws.extend(store.query_by_type(t, status="active", limit=_SCAN_LIMIT))
+
+    out, seen = [], set()
+    for ku in raws:
+        if ku.ku_id in seen or _status_of(ku) != "active":
+            continue
+        if ku.ku_type.value not in _CARD_TYPES:
+            continue
+        seen.add(ku.ku_id)
+        out.append((ku, _state_of(ku)))
+    return out
+
+
+@app.get("/api/review/stats")
+async def review_stats():
+    store = _store()
+    if store is None:
+        return {"available": False, "cards": 0, "fresh": 0, "due": 0,
+                "learned": 0, "avg_mastery": 0.0,
+                "load7": {"total_due": 0, "by_day": {}, "daily_avg": 0.0, "overdue": 0},
+                "risk": []}
+
+    def _do():
+        pairs = _pairs(store)
+        learned = [s for ku, s in pairs if _has_state(ku)]
+        due = [s for s in learned if s.is_due]
+        risk = _SR.forgetting_risk(learned, 3)[:5]
+
+        by_id = {ku.ku_id: ku.name for ku, _ in pairs}
+        by_state = {s.item_id: s for s in learned}
+        for r in risk:
+            s = by_state.get(r["item_id"])
+            r["name"] = by_id.get(r["item_id"], "")
+            if s is not None:
+                d = _days_left(s)
+                r["days_until_due"] = d
+                r["reason"] = f"掌握度仅 {s.mastery}," + ("已到期" if s.is_due else f"{d} 天内到期")
+
+        return {
+            "available": True,
+            "cards": len(pairs),
+            "learned": len(learned),
+            "fresh": len(pairs) - len(learned),
+            "due": len(due),
+            "avg_mastery": round(sum(s.mastery for s in learned) / len(learned), 3) if learned else 0.0,
+            "load7": _load7(learned),
+            "risk": risk,
+        }
+
+    return await asyncio.to_thread(_do)
+
+
+@app.get("/api/review/queue")
+async def review_queue(limit: int = 20, fresh_limit: int = 10):
+    """今日该复习什么。
+
+    到期卡先上(掌握度低的优先,最弱的先补),不够 ``limit`` 再补新卡(先录的先学)。
+    新卡数量单独由 ``fresh_limit`` 控制 —— 新知识全塞一天会让曲线失去意义。
+    """
+    store = _store()
+    if store is None:
+        return {"available": False, "cards": [], "total": 0}
+
+    def _do():
+        pairs = _pairs(store)
+        learned = [(ku, s) for ku, s in pairs if _has_state(ku)]
+        fresh = [(ku, s) for ku, s in pairs if not _has_state(ku)]
+
+        learned.sort(key=lambda p: (p[1].mastery, p[1].days_until_due))
+        fresh.sort(key=lambda p: getattr(p[0], "created_at", "") or "")
+
+        due = [(ku, s) for ku, s in learned if s.is_due][:max(0, int(limit))]
+        room = max(0, int(limit) - len(due))
+        picked = due + fresh[:min(room, max(0, int(fresh_limit)))]
+
+        return {"available": True,
+                "cards": [_card(ku, s) for ku, s in picked],
+                "due": len(due),
+                "fresh_used": max(0, len(picked) - len(due)),
+                "total": len(pairs)}
+
+    return await asyncio.to_thread(_do)
+
+
+class GradeIn(BaseModel):
+    ku_id: str
+    grade: int
+
+
+@app.post("/api/review/grade")
+async def review_grade(body: GradeIn):
+    """给一张卡打回忆质量分(0 忘 / 3 勉强 / 4 记住 / 5 轻松),SM-2 推下一次间隔。"""
+    store = _store()
+    if store is None:
+        raise HTTPException(503, "知识库未装配,复习状态无处可存")
+
+    def _do():
+        ku = store.get(body.ku_id)
+        if ku is None or _status_of(ku) != "active":
+            raise HTTPException(404, f"没有这条知识:{body.ku_id}")
+
+        # 关键:只更新 extra 这一列,而且「读 extra → SM-2 推演 → 写回」整段在
+        # graph_store 的锁里完成。走 put() 是整行 UPSERT,会把整行其它列按写入前的
+        # 快照回写 —— 知识星球正在摄入时,KEE 刚合并进去的 sources / confidence /
+        # supports 会被这次评分悄悄冲掉(反向亦然:复习进度被 KEE 写回覆盖)。
+        # 锁内做还有个好处:连点两次评分不会两次都基于同一份旧状态推演。
+        graded: list[ReviewState] = []
+
+        def _apply(extra: dict) -> dict:
+            state = _state_from(extra, body.ku_id)
+            _SR.review(state, body.grade)
+            extra["review"] = asdict(state)
+            graded.append(state)
+            return extra
+
+        new_extra = store.update_extra(body.ku_id, _apply)
+        if new_extra is None:
+            raise HTTPException(404, f"没有这条知识:{body.ku_id}")
+        state = graded[0]
+        return {"ok": True, "ku_id": body.ku_id, "name": ku.name,
+                "next_in_days": state.interval, "review": state.to_dict()}
+
+    return await asyncio.to_thread(_do)

package/python/foxclaw/api/routes/search.py

@@ -0,0 +1,37 @@
+"""认知搜索(HSR)端点:内部记忆 + 内部知识 + 联网,统一证据融合。
+
+从 foxclaw/api.py 原样搬移(纯搬移,零行为变更)。共享 OS 实例经 `_api._os_instance`
+晚绑定读取;路由用 `@app` 装饰器在 import 时注册。
+"""
+
+import asyncio
+
+from fastapi import HTTPException
+from pydantic import BaseModel
+
+import foxclaw.api as _api
+from .. import app
+
+
+# ── 认知搜索(HSR)：内部记忆 + 内部知识 + 联网,统一证据融合 ─────────
+# 一次 search() 统一"查 HMR 记忆 / 查 HKC 知识 / 联网(百度)",走 planner→retriever→
+# fusion→strategy 迭代循环(有上限),只产出证据图,不写任何持久化(边界:不代 Agent 决策)。
+
+class SearchQueryPayload(BaseModel):
+    query: str
+    agent_id: str = "supervisor"
+    context: dict = {}
+    internal_only: bool = False   # True=只查内部(HMR+HKC+Agent态势),跳过联网
+
+
+@app.post("/api/search/query")
+async def search_query(p: SearchQueryPayload):
+    """认知搜索(面向 AI/Agent 的证据管线):返回证据图 + 置信度 + 迭代轨迹。
+    internal_only=True 时只查内部三源(记忆/知识/Agent),不联网。搜索内核惰性构造。"""
+    try:
+        rt = _api._os_instance.search_runtime
+        result = await asyncio.to_thread(
+            rt.search, p.query, p.agent_id, p.context, p.internal_only)
+        return result.to_dict()
+    except Exception as e:
+        raise HTTPException(500, f"搜索失败: {e}")

package/python/foxclaw/api/routes/system.py

@@ -0,0 +1,327 @@
+"""系统状态 / 模型路由 / 认知调度 / 事件总线 / 真值 / 进程 / 思考链 / Harness / 探活 / 监控与追踪。
+
+从 foxclaw/api.py 原样搬移(纯搬移,零行为变更)。共享 OS 实例经 `_api._os_instance`
+晚绑定读取(保持测试可重绑定 `api._os_instance`);路由用 `@app` 装饰器在 import 时注册。
+"""
+
+import os
+from typing import Optional
+
+from fastapi import HTTPException
+from fastapi.responses import PlainTextResponse
+from pydantic import BaseModel
+
+from foxclaw import __version__
+
+import foxclaw.api as _api
+from .. import app
+from ..middleware import _gateway_on, _GATEWAY
+from ...core import settings
+
+
+# ── 系统状态 ───────────────────────────────────────────────
+
+@app.get("/api/status")
+async def get_system_status():
+    """获取所有 Agent 的状态"""
+    return _api._os_instance.get_all_status()
+
+
+@app.get("/api/tokens")
+async def get_token_summary():
+    """Token 消耗摘要(成本可观测性):总量、按 Agent、按模型。"""
+    meter = getattr(_api._os_instance, "token_meter", None)
+    if meter is None:
+        return {"error": "token meter 未启用"}
+    return {
+        "summary": meter.summary(),
+        "by_agent": meter.by_agent(),
+        "by_provider": meter.by_provider(),
+    }
+
+
+@app.get("/api/tokens/report")
+async def get_token_report():
+    """Token 消耗的人类可读文本报告。"""
+    meter = getattr(_api._os_instance, "token_meter", None)
+    if meter is None:
+        return {"error": "token meter 未启用"}
+    return {"report": meter.report()}
+
+
+# ── 模型路由与系统信息 ─────────────────────────────────────
+
+@app.get("/api/model")
+async def get_model():
+    """当前模型路由状态 + 可用 provider 列表。"""
+    return _api._os_instance.router.info()
+
+
+@app.get("/api/config/amap")
+async def get_amap_config():
+    """下发前端高德 JSAPI Key + 安全密钥(从 .env 读取,不硬编码在前端)。"""
+    return {
+        "js_key": os.environ.get("AMAP_JS_KEY", ""),
+        "js_scode": os.environ.get("AMAP_JS_SCODE", ""),
+    }
+
+
+@app.get("/api/system/info")
+async def get_system_info():
+    """系统级只读信息:版本、运行参数、各 Agent、模块状态(供设置面板展示)。"""
+    agents = {}
+    for aid, ag in _api._os_instance._agents.items():
+        h = ag.harness
+        agents[aid] = {
+            "name": getattr(ag, "AGENT_NAME", aid),
+            "shadow_mode": h.is_shadow_mode,
+            "shadow_rounds": h.shadow_rounds,
+            "run_count": getattr(h, "_run_count", 0),
+            # 降级可见性(B 类修复):语义维度停用时,漂移检测只剩 tool/scope 两维,
+            # 跑题不会被拦截 —— 前端需据此提示,不能只在服务端日志里静默。
+            "semantic_degraded": getattr(h, "semantic_degraded", False),
+            "embedding_mode": getattr(getattr(h, "sem_drift", None), "mode", "unknown"),
+        }
+    return {
+        "version": __version__,
+        "data_dir": os.environ.get("FOXCLAW_DATA_DIR", "./foxclaw_data"),
+        "shadow_rounds": settings.get_int("FOXCLAW_SHADOW_ROUNDS"),
+        "model": _api._os_instance.router.info(),
+        "amap": {
+            "web_key": bool(os.environ.get("AMAP_MAPS_API_KEY")),
+            "js_key": bool(os.environ.get("AMAP_JS_KEY")),
+            "js_scode": bool(os.environ.get("AMAP_JS_SCODE")),
+        },
+        "agents": agents,
+    }
+
+
+class ModelSwitchPayload(BaseModel):
+    provider: str
+    model: Optional[str] = None
+
+
+@app.post("/api/model/switch")
+async def switch_model(p: ModelSwitchPayload):
+    """运行时切换模型 provider(多模型路由核心能力)。"""
+    try:
+        return _api._os_instance.router.switch(p.provider, p.model)
+    except Exception as e:
+        raise HTTPException(400, f"切换失败: {e}")
+
+
+@app.get("/api/agents/{agent_id}/status")
+async def get_agent_status(agent_id: str):
+    agent = _api._os_instance.get_agent(agent_id)
+    if not agent:
+        raise HTTPException(404, f"Agent {agent_id} 不存在")
+    return agent.get_status()
+
+
+# ── 认知调度 / 事件总线 / 真值 / 进程 / 认知状态 ─────────────
+
+class SchedulePreviewPayload(BaseModel):
+    task: str
+
+
+@app.post("/api/scheduler/preview")
+async def scheduler_preview(payload: SchedulePreviewPayload):
+    """认知调度预览:给一个任务,返回调度决策(优先级/意图/路由/抢占),不实际执行。"""
+    from foxclaw.core.scheduler import CognitiveScheduler, SystemContext
+    sch = CognitiveScheduler()
+    d = sch.schedule(payload.task, SystemContext())
+    return d.to_dict()
+
+
+@app.get("/api/scheduler/stats")
+async def scheduler_stats():
+    """调度器记账:并发配额 + 提交/运行/完成/失败/峰值(可观测性)。"""
+    return _api._os_instance.scheduler.stats()
+
+
+@app.get("/api/bus/history")
+async def bus_history(channel: str = None, limit: int = 30):
+    """系统事件总线历史:观测执行→审计→记忆的真值流转。"""
+    try:
+        return {"events": _api._os_instance.system_bus.history(channel, limit)}
+    except Exception:
+        return {"events": []}
+
+
+@app.get("/api/truth/last")
+async def truth_last():
+    """真值管线最近一次的 trace 与记忆更新。"""
+    tp = _api._os_instance.truth_pipeline
+    return {"last_trace": tp.last_trace, "last_memory_update": tp.last_memory_update}
+
+
+@app.get("/api/processes")
+async def list_processes(state: str = None, limit: int = 30):
+    """进程列表:观测任务作为"进程"的生命周期状态。"""
+    try:
+        return {"processes": _api._os_instance.process_manager.list(state, limit),
+                "stats": _api._os_instance.process_manager.stats()}
+    except Exception:
+        return {"processes": [], "stats": {}}
+
+
+@app.get("/api/processes/{process_id}")
+async def get_process(process_id: str):
+    """单个进程详情:含完整状态历史(state_history)。"""
+    rec = _api._os_instance.process_manager.get(process_id)
+    return rec.to_dict() if rec else {"error": "not_found"}
+
+
+@app.get("/api/cognitive/state")
+async def cognitive_state():
+    """认知状态快照:系统此刻在想什么(目标/焦点/注意力/激活记忆/活跃进程)。"""
+    try:
+        return _api._os_instance.cognitive_state.snapshot()
+    except Exception as e:
+        return {"error": str(e)}
+
+
+# ── ThoughtChain 查询 ──────────────────────────────────────
+
+@app.get("/api/thoughtchain/{agent_id}/chain")
+async def get_thought_chain(agent_id: str, session_id: str = None):
+    """获取 Agent 的推理链"""
+    tc = _api._os_instance.thought_chain
+    if session_id:
+        nodes = tc.get_chain(session_id, agent_id)
+    else:
+        # 返回最近 20 个节点
+        nodes = tc.get_blocked_nodes(agent_id, limit=20)
+    return {"nodes": [n.to_dict() for n in nodes]}
+
+
+@app.get("/api/thoughtchain/{agent_id}/blocked")
+async def get_blocked_nodes(agent_id: str, limit: int = 20):
+    """获取被 Harness 截断的节点（审计用）"""
+    tc = _api._os_instance.thought_chain
+    nodes = tc.get_blocked_nodes(agent_id, limit=limit)
+    return {"blocked": [n.to_dict() for n in nodes], "count": len(nodes)}
+
+
+@app.get("/api/thoughtchain/{agent_id}/trend")
+async def get_drift_trend(agent_id: str, limit: int = 100):
+    """获取漂移趋势数据（前端可视化用）"""
+    tc = _api._os_instance.thought_chain
+    trend = tc.get_delta_trend(agent_id, limit=limit)
+    return {"trend": trend, "agent_id": agent_id}
+
+
+@app.get("/api/thoughtchain/{agent_id}/summary")
+async def get_thought_summary(agent_id: str):
+    """获取 ThoughtChain 健康摘要"""
+    return _api._os_instance.thought_chain.get_summary(agent_id)
+
+
+# ── Harness 状态 ───────────────────────────────────────────
+
+@app.get("/api/harness/{agent_id}/status")
+async def get_harness_status(agent_id: str):
+    """获取 Harness 状态：阈值、shadow mode、policy 摘要"""
+    agent = _api._os_instance.get_agent(agent_id)
+    if not agent:
+        raise HTTPException(404, f"Agent {agent_id} 不存在")
+    return {
+        "agent_id": agent_id,
+        "thresholds": agent.harness.thresholds,
+        "policy": agent.harness.get_policy_summary(),
+        "weights": agent.harness.weights,
+    }
+
+
+@app.get("/api/harness/{agent_id}/policy")
+async def get_policy(agent_id: str):
+    """获取 Agent 的 Policy YAML（完整内容）"""
+    agent = _api._os_instance.get_agent(agent_id)
+    if not agent:
+        raise HTTPException(404, f"Agent {agent_id} 不存在")
+    return agent.harness._policy
+
+
+# ── 健康探活 ───────────────────────────────────────────────
+# 标准探活端点(开放,不在鉴权前缀内、不触发 HKC 装配)。星球 UI 的 connect() 用它探活,
+# 也供部署/监控用。放在静态挂载("/")之前,否则会被 StaticFiles 的 catch-all 吞成 404。
+@app.get("/health")
+async def health():
+    """存活探针(liveness):浅、快,不触发子系统。"""
+    return {"status": "ok", "service": "foxclaw", "version": __version__}
+
+
+@app.get("/health/ready")
+async def health_ready():
+    """就绪探针(readiness):逐子系统深度检查。**开放**(探针无需鉴权),
+    组件只回 ok/stub/down,不泄露 provider 名等细节。不触发 HKC 惰性初始化。"""
+    o = _api._os_instance
+    comps = {}
+    comps["hmr"] = "ok" if getattr(o, "hmr", None) is not None else "down"
+    _router = getattr(o, "router", None)
+    if _router is None:
+        comps["router"] = "down"
+    elif getattr(_router, "is_stub", True):
+        comps["router"] = "stub"
+    else:
+        comps["router"] = "ok"                       # 不回传 provider 名(开放端点,防泄露)
+    comps["scheduler"] = "ok" if getattr(o, "scheduler", None) is not None else "down"
+    hkc_svc = getattr(o, "_hkc_service", None)   # 只看已初始化的,不触发惰性 init
+    comps["hkc"] = ("ok" if (hkc_svc is not None and getattr(hkc_svc, "available", False))
+                    else ("uninitialized" if hkc_svc is None else "degraded"))
+    comps["mcp_server"] = "on" if getattr(o, "mcp_manager", None) is not None else "off"
+    down = [k for k, v in comps.items() if v == "down"]
+    return {"status": "degraded" if down else "ok", "components": comps, "version": __version__}
+
+
+# ── 监控 / 追踪 / 网关 ──────────────────────────────────────
+
+@app.get("/api/metrics")
+async def metrics_json():
+    """可观测:各端点/LLM 的计数、错误率、延迟分位(p50/p95/avg)+ uptime。"""
+    from ...core.metrics import METRICS
+    return METRICS.snapshot()
+
+
+@app.get("/api/traces")
+async def list_traces(limit: int = 30, persisted: bool = False,
+                      slow_ms: float = None, errors_only: bool = False):
+    """请求链路。默认看内存里最近若干条;persisted=1 查**已落库的历史**
+    (可加 slow_ms / errors_only 过滤)——「找出昨天那次慢请求」走这里。"""
+    from ...core.tracing import TRACES
+    limit = max(1, min(limit, 200))
+    if persisted or slow_ms is not None or errors_only:
+        return {"traces": TRACES.query(limit=limit, slow_ms=slow_ms,
+                                       errors_only=errors_only), "source": "persisted"}
+    return {"traces": TRACES.list(limit=limit), "source": "memory"}
+
+
+@app.get("/api/traces/stats")
+async def traces_stats():
+    """OTLP 导出状态(未配 FOXCLAW_OTLP_ENDPOINT 则 enabled=false,完全不启用)。
+    注意:本路由必须定义在 /api/traces/{trace_id} **之前**,否则 "stats" 会被当成 trace_id。"""
+    from ...core.tracing import OTLP
+    return {"otlp": OTLP.stats()}
+
+
+@app.get("/api/traces/{trace_id}")
+async def get_trace(trace_id: str):
+    """单条链路详情:各 span 的耗时/成败(定位这次慢在哪)。内存未命中则回落到库。"""
+    from ...core.tracing import TRACES
+    d = TRACES.get_dict(trace_id)
+    if d is None:
+        raise HTTPException(404, "trace 不存在(内存环已滚出且未被采样落库)")
+    return d
+
+
+@app.get("/api/gateway/stats")
+async def gateway_stats():
+    """API 网关状态:是否启用 + 每分钟/每小时额度 + 当前追踪的 client 数 + 累计拒绝数。"""
+    return {"enabled": _gateway_on(), **_GATEWAY.stats()}
+
+
+@app.get("/metrics")
+async def metrics_prometheus():
+    """Prometheus 文本格式(供 scrape)。"""
+    from ...core.metrics import METRICS
+    return PlainTextResponse(METRICS.prometheus_text())