foxclaw 0.1.2 → 0.1.3

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

@@ -1,7 +1,7 @@
 """系统状态 / 模型路由 / 认知调度 / 事件总线 / 真值 / 进程 / 思考链 / Harness / 探活 / 监控与追踪。
 
-从 foxclaw/api.py 原样搬移(纯搬移,零行为变更)。共享 OS 实例经 `_api._os_instance`
-晚绑定读取(保持测试可重绑定 `api._os_instance`);路由用 `@app` 装饰器在 import 时注册。
+从 foxclaw/api.py 原样搬移(纯搬移,零行为变更)。共享 OS 实例经 `_api.current_os()`
+晚绑定读取(状态在 `_state`,测试可重绑 `_state._os_instance`);路由用 `@app` 装饰器在 import 时注册。
 """
 
 import os
@@ -16,21 +16,19 @@ from foxclaw import __version__
 import foxclaw.api as _api
 from .. import app
 from ..middleware import _gateway_on, _GATEWAY
-from ...core import settings
+from ...core import settings, update_check
 
 
-# ── 系统状态 ───────────────────────────────────────────────
-
 @app.get("/api/status")
 async def get_system_status():
     """获取所有 Agent 的状态"""
-    return _api._os_instance.get_all_status()
+    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)
+    meter = getattr(_api.current_os(), "token_meter", None)
     if meter is None:
         return {"error": "token meter 未启用"}
     return {
@@ -43,18 +41,16 @@ async def get_token_summary():
 @app.get("/api/tokens/report")
 async def get_token_report():
     """Token 消耗的人类可读文本报告。"""
-    meter = getattr(_api._os_instance, "token_meter", None)
+    meter = getattr(_api.current_os(), "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()
+    return _api.os_instance().router.info()
 
 
 @app.get("/api/config/amap")
@@ -69,24 +65,24 @@ async def get_amap_config():
 @app.get("/api/system/info")
 async def get_system_info():
     """系统级只读信息:版本、运行参数、各 Agent、模块状态(供设置面板展示)。"""
+    update_check.maybe_refresh()
     agents = {}
-    for aid, ag in _api._os_instance._agents.items():
+    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__,
+        "update": update_check.status(),
         "data_dir": os.environ.get("FOXCLAW_DATA_DIR", "./foxclaw_data"),
         "shadow_rounds": settings.get_int("FOXCLAW_SHADOW_ROUNDS"),
-        "model": _api._os_instance.router.info(),
+        "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")),
@@ -105,21 +101,19 @@ class ModelSwitchPayload(BaseModel):
 async def switch_model(p: ModelSwitchPayload):
     """运行时切换模型 provider(多模型路由核心能力)。"""
     try:
-        return _api._os_instance.router.switch(p.provider, p.model)
+        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)
+    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
 
@@ -136,14 +130,14 @@ async def scheduler_preview(payload: SchedulePreviewPayload):
 @app.get("/api/scheduler/stats")
 async def scheduler_stats():
     """调度器记账:并发配额 + 提交/运行/完成/失败/峰值(可观测性)。"""
-    return _api._os_instance.scheduler.stats()
+    return _api.os_instance().scheduler.stats()
 
 
 @app.get("/api/bus/history")
-async def bus_history(channel: str = None, limit: int = 30):
+async def bus_history(channel: str | None = None, limit: int = 30):
     """系统事件总线历史:观测执行→审计→记忆的真值流转。"""
     try:
-        return {"events": _api._os_instance.system_bus.history(channel, limit)}
+        return {"events": _api.os_instance().system_bus.history(channel, limit)}
     except Exception:
         return {"events": []}
 
@@ -151,16 +145,16 @@ async def bus_history(channel: str = None, limit: int = 30):
 @app.get("/api/truth/last")
 async def truth_last():
     """真值管线最近一次的 trace 与记忆更新。"""
-    tp = _api._os_instance.truth_pipeline
+    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):
+async def list_processes(state: str | None = None, limit: int = 30):
     """进程列表:观测任务作为"进程"的生命周期状态。"""
     try:
-        return {"processes": _api._os_instance.process_manager.list(state, limit),
-                "stats": _api._os_instance.process_manager.stats()}
+        return {"processes": _api.os_instance().process_manager.list(state, limit),
+                "stats": _api.os_instance().process_manager.stats()}
     except Exception:
         return {"processes": [], "stats": {}}
 
@@ -168,7 +162,7 @@ async def list_processes(state: str = None, limit: int = 30):
 @app.get("/api/processes/{process_id}")
 async def get_process(process_id: str):
     """单个进程详情:含完整状态历史(state_history)。"""
-    rec = _api._os_instance.process_manager.get(process_id)
+    rec = _api.os_instance().process_manager.get(process_id)
     return rec.to_dict() if rec else {"error": "not_found"}
 
 
@@ -176,21 +170,18 @@ async def get_process(process_id: str):
 async def cognitive_state():
     """认知状态快照:系统此刻在想什么(目标/焦点/注意力/激活记忆/活跃进程)。"""
     try:
-        return _api._os_instance.cognitive_state.snapshot()
+        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):
+async def get_thought_chain(agent_id: str, session_id: str | None = None):
     """获取 Agent 的推理链"""
-    tc = _api._os_instance.thought_chain
+    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]}
 
@@ -198,7 +189,7 @@ async def get_thought_chain(agent_id: str, session_id: str = None):
 @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
+    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)}
 
@@ -206,7 +197,7 @@ async def get_blocked_nodes(agent_id: str, limit: int = 20):
 @app.get("/api/thoughtchain/{agent_id}/trend")
 async def get_drift_trend(agent_id: str, limit: int = 100):
     """获取漂移趋势数据（前端可视化用）"""
-    tc = _api._os_instance.thought_chain
+    tc = _api.os_instance().thought_chain
     trend = tc.get_delta_trend(agent_id, limit=limit)
     return {"trend": trend, "agent_id": agent_id}
 
@@ -214,15 +205,13 @@ async def get_drift_trend(agent_id: str, limit: int = 100):
 @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)
-
+    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)
+    agent = _api.os_instance().get_agent(agent_id)
     if not agent:
         raise HTTPException(404, f"Agent {agent_id} 不存在")
     return {
@@ -236,15 +225,12 @@ async def get_harness_status(agent_id: str):
 @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)
+    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):浅、快,不触发子系统。"""
@@ -255,7 +241,7 @@ async def health():
 async def health_ready():
     """就绪探针(readiness):逐子系统深度检查。**开放**(探针无需鉴权),
     组件只回 ok/stub/down,不泄露 provider 名等细节。不触发 HKC 惰性初始化。"""
-    o = _api._os_instance
+    o = _api.current_os()
     comps = {}
     comps["hmr"] = "ok" if getattr(o, "hmr", None) is not None else "down"
     _router = getattr(o, "router", None)
@@ -264,9 +250,9 @@ async def health_ready():
     elif getattr(_router, "is_stub", True):
         comps["router"] = "stub"
     else:
-        comps["router"] = "ok"                       # 不回传 provider 名(开放端点,防泄露)
+        comps["router"] = "ok"
     comps["scheduler"] = "ok" if getattr(o, "scheduler", None) is not None else "down"
-    hkc_svc = getattr(o, "_hkc_service", None)   # 只看已初始化的,不触发惰性 init
+    hkc_svc = getattr(o, "_hkc_service", None)
     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"
@@ -274,8 +260,6 @@ async def health_ready():
     return {"status": "degraded" if down else "ok", "components": comps, "version": __version__}
 
 
-# ── 监控 / 追踪 / 网关 ──────────────────────────────────────
-
 @app.get("/api/metrics")
 async def metrics_json():
     """可观测:各端点/LLM 的计数、错误率、延迟分位(p50/p95/avg)+ uptime。"""
@@ -285,7 +269,7 @@ async def metrics_json():
 
 @app.get("/api/traces")
 async def list_traces(limit: int = 30, persisted: bool = False,
-                      slow_ms: float = None, errors_only: bool = False):
+                      slow_ms: float | None = None, errors_only: bool = False):
     """请求链路。默认看内存里最近若干条;persisted=1 查**已落库的历史**
     (可加 slow_ms / errors_only 过滤)——「找出昨天那次慢请求」走这里。"""
     from ...core.tracing import TRACES

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

@@ -1,6 +1,6 @@
 """任务执行 / 流式直答 / 流式任务 路由与多模态护栏。
 
-从 foxclaw/api.py 原样搬移(纯搬移,零行为变更)。共享 OS 实例经 `_api._os_instance`
+从 foxclaw/api.py 原样搬移(纯搬移,零行为变更)。共享 OS 实例经 `_api.current_os()`
 晚绑定读取;路由用 `@app` 装饰器在 import 时注册。流式限流器 `_STREAM_LIMITER` 为
 模块级单例,`__init__.py` 会 re-export(测试复位其桶容量)。
 """
@@ -19,18 +19,14 @@ from ...mcp_server import _RateLimiter as _RL
 from ...core import settings
 
 
-# ── 请求模型 ───────────────────────────────────────────────
-
 class TaskRequest(BaseModel):
     task: str
     agent_id: str = "supervisor"
     context: dict = {}
-    images: list = []       # 多模态对话:[{media_type,data(base64)}];仅 /chat/stream 消费
-    history: list = []      # 多轮上下文:[{role:'user'/'assistant',content}];前端带最近几轮,
-                            # 后端拼进 LLM messages,让对话连贯(否则每轮无状态、记不住上一句)
-    session_id: str = ""    # 会话归属:非空则本轮问答落盘到该会话(供"会话历史"回看)
-    attachments: list = []  # 聊天附件:[{name,size,mime,url,text}];text 为提取正文(可为空),
-                            # 仅 /chat/stream 消费;随问题注入 LLM + 落盘会话供回看
+    images: list = []
+    history: list = []
+    session_id: str = ""
+    attachments: list = []
 
 
 class GoalRequest(BaseModel):
@@ -40,8 +36,6 @@ class GoalRequest(BaseModel):
     entities: list[str] = []
 
 
-# ── 任务执行 ───────────────────────────────────────────────
-
 @app.post("/api/task")
 async def run_task(req: TaskRequest):
     """执行任务，返回结果 + ThoughtChain 摘要。
@@ -53,33 +47,31 @@ async def run_task(req: TaskRequest):
       同一线程池,故无嵌套线程池死锁;
     · harness 累积态已在 harness.py 用 RLock 保护(嵌入在锁外,故并行不受锁影响)。"""
     def _work():
-        # 经微内核调度器准入(默认无上限=直通;设了 FOXCLAW_MAX_CONCURRENCY 才背压)+ 生命周期事件
-        return _api._os_instance.scheduler.run(
-            lambda: asyncio.run(_api._os_instance.run(req.task, req.agent_id,
+        return _api.os_instance().scheduler.run(
+            lambda: asyncio.run(_api.os_instance().run(req.task, req.agent_id,
                                                       context=req.context)),
             agent_id=req.agent_id, task=req.task)
     return await asyncio.to_thread(_work)
 
 
-# 流式限流 + 并发上限(防刷爆/资源耗尽;env 可配)
-_STREAM_LIMITER = _RL(settings.get_int("FOXCLAW_STREAM_RATE"))                   # 次/分
+_STREAM_LIMITER = _RL(settings.get_int("FOXCLAW_STREAM_RATE"))
 _STREAM_SEM = _threading.Semaphore(settings.get_int("FOXCLAW_STREAM_CONCURRENCY"))
 
 
 _MAX_IMAGES = 6
-_MAX_IMG_B64 = 10 * 1024 * 1024        # 单图 base64 上限 ~10MB(≈7.5MB 原图)
-_MAX_IMG_TOTAL = 20 * 1024 * 1024      # 所有图 base64 累计上限(防 6×10MB=60MB 聚合 payload)
+_MAX_IMG_B64 = 10 * 1024 * 1024
+_MAX_IMG_TOTAL = 20 * 1024 * 1024
 _ALLOWED_IMG_MT = {"image/png", "image/jpeg", "image/webp", "image/gif"}
 
-_MAX_ATTACHMENTS = 6                   # 单次问答最多附件数
-_ATTACH_TEXT_MAX = 20000               # 单附件提取正文上限
-_ATTACH_TEXT_TOTAL = 60000             # 全部附件正文累计上限(≈1.5 万 token,防撑爆上下文)
+_MAX_ATTACHMENTS = 6
+_ATTACH_TEXT_MAX = 20000
+_ATTACH_TEXT_TOTAL = 60000
 
 
 def _sanitize_images(images):
     """校验/裁剪前端传来的多模态图片:限数量、限单图大小、限累计总量、白名单类型。
     防超大 payload/OOM(前端已缩放,这是对直连/恶意客户端的后端自保)。"""
-    out = []
+    out: list[dict] = []
     total = 0
     if not isinstance(images, list):
         return out
@@ -92,7 +84,7 @@ def _sanitize_images(images):
             continue
         if not isinstance(d, str) or not d or len(d) > _MAX_IMG_B64:
             continue
-        if total + len(d) > _MAX_IMG_TOTAL:    # 累计超总上限 → 停(丢弃其余)
+        if total + len(d) > _MAX_IMG_TOTAL:
             break
         total += len(d)
         out.append({"media_type": mt, "data": d})
@@ -103,7 +95,7 @@ def _sanitize_attachments(attachments):
     """校验/裁剪前端传来的聊天附件:限数量、字段清洗、正文长度上限 + 累计上限。
     附件是前端经 /api/upload 上传后带回的引用({name,size,mime,url,text});这里只做
     直连/恶意客户端的自保,不信任 text 之外任何字段用于文件系统操作(下载按 url 里的 id 白名单)。"""
-    out = []
+    out: list[dict] = []
     total = 0
     if not isinstance(attachments, list):
         return out
@@ -114,11 +106,12 @@ def _sanitize_attachments(attachments):
         text = str(a.get("text") or "")[:_ATTACH_TEXT_MAX]
         if not name and not text:
             continue
-        if total + len(text) > _ATTACH_TEXT_TOTAL:   # 累计正文超总上限 → 截断(丢弃后续正文)
+        if total + len(text) > _ATTACH_TEXT_TOTAL:
             text = text[:_ATTACH_TEXT_TOTAL - total]
         total += len(text)
-        try:                                        # size 可能是脏值("big"/None),护栏绝不因此抛异常
-            size = int(a.get("size")) if a.get("size") else 0
+        try:
+            raw_size = a.get("size")
+            size = int(raw_size) if raw_size else 0
         except (TypeError, ValueError):
             size = 0
         out.append({
@@ -142,12 +135,12 @@ async def chat_stream(req: TaskRequest, request: Request):
             yield "data: " + json.dumps({"error": "rate limited"}) + "\n\n"
         return StreamingResponse(_rl(), media_type="text/event-stream")
 
-    agent = _api._os_instance._agents.get(req.agent_id) or _api._os_instance.supervisor
+    agent = _api.os_instance()._agents.get(req.agent_id) or _api.os_instance().supervisor
     imgs = _sanitize_images(req.images)
     atts = _sanitize_attachments(req.attachments)
 
     async def async_sse():
-        if not _STREAM_SEM.acquire(blocking=False):   # 超并发上限 → 拒(不排队)
+        if not _STREAM_SEM.acquire(blocking=False):
             yield "data: " + json.dumps({"error": "busy, try again later"}) + "\n\n"
             return
         q: asyncio.Queue = asyncio.Queue()
@@ -158,12 +151,9 @@ async def chat_stream(req: TaskRequest, request: Request):
             _parts = []
 
             def _on_thinking(delta: str) -> None:
-                # 推理走独立事件,不混进正文:前端折叠展示,正文仍只收 {"delta"}。
                 loop.call_soon_threadsafe(q.put_nowait, {"thinking": delta})
 
             def _on_evidence(evs: list) -> None:
-                # 执行证据(核验结论 + 来源链接/文件)整块送:前端挂在答案下方供核对,
-                # 不进正文(正文是给用户读的答案,证据是给人查的凭据)。
                 loop.call_soon_threadsafe(q.put_nowait, {"evidence": evs})
 
             try:
@@ -177,22 +167,21 @@ async def chat_stream(req: TaskRequest, request: Request):
             except Exception as e:
                 loop.call_soon_threadsafe(q.put_nowait, {"error": str(e)})
             finally:
-                # 落盘会话历史(问 + 答),供"会话/所有会话"回看。断连中止也保留已生成部分。
                 if req.session_id:
                     try:
-                        _api._os_instance.sessions.append(req.session_id, "user", req.task, attachments=atts)
+                        _api.os_instance().sessions.append(req.session_id, "user", req.task, attachments=atts)
                         _reply = "".join(_parts)
                         if _reply:
-                            _api._os_instance.sessions.append(req.session_id, "assistant", _reply)
+                            _api.os_instance().sessions.append(req.session_id, "assistant", _reply)
                     except Exception:
                         pass
-                loop.call_soon_threadsafe(q.put_nowait, None)   # 结束哨兵
+                loop.call_soon_threadsafe(q.put_nowait, None)
 
         _threading.Thread(target=_producer, daemon=True, name="chat-stream").start()
         try:
             while True:
                 if await request.is_disconnected():
-                    stop.set(); break                 # 断连 → 终止 LLM 流
+                    stop.set(); break
                 try:
                     item = await asyncio.wait_for(q.get(), timeout=0.5)
                 except asyncio.TimeoutError:
@@ -200,15 +189,11 @@ async def chat_stream(req: TaskRequest, request: Request):
                 if item is None:
                     break
                 if "thinking" in item:
-                    # 命名事件(SSE 规范):event: thinking + data。老客户端只认 data: 行也不会被
-                    # 误导成正文(delta 字段不存在);新前端按事件名折叠展示。
                     yield ("event: thinking\ndata: "
                            + json.dumps({"thinking": item["thinking"]}, ensure_ascii=False)
                            + "\n\n")
                     continue
                 if "evidence" in item:
-                    # 与 thinking 同理走命名事件:老客户端拿不到这个事件名也不会把凭据
-                    # 当成正文拼进回答。
                     yield ("event: evidence\ndata: "
                            + json.dumps({"evidence": item["evidence"]}, ensure_ascii=False)
                            + "\n\n")
@@ -235,16 +220,13 @@ async def task_stream(req: TaskRequest, request: Request):
             yield "data: " + json.dumps({"error": "rate limited"}) + "\n\n"
         return StreamingResponse(_rl(), media_type="text/event-stream")
 
-    agent = _api._os_instance._agents.get(req.agent_id)
-    # 【P3-3】P1-1 落地后主管走统一 pipeline(supervisor_stages),支持 run_task_stream,
-    # 不再回落 assistant(助手已下放为技能)。未知 agent_id 仍回落主管兼容旧客户端
-    # (旧前端可能还传 "assistant"/"admin"),但打 warning 不静默。
+    agent = _api.os_instance()._agents.get(req.agent_id)
     if agent is None:
         print(f"[Foxclaw API] ⚠ /api/task/stream 收到未知 agent_id={req.agent_id},回落 supervisor")
-        agent = _api._os_instance.supervisor
+        agent = _api.os_instance().supervisor
 
     async def async_sse():
-        if not _STREAM_SEM.acquire(blocking=False):   # 超并发上限 → 拒(不排队)
+        if not _STREAM_SEM.acquire(blocking=False):
             yield "data: " + json.dumps({"error": "busy, try again later"}) + "\n\n"
             return
         q: asyncio.Queue = asyncio.Queue()
@@ -259,13 +241,13 @@ async def task_stream(req: TaskRequest, request: Request):
             except Exception as e:
                 loop.call_soon_threadsafe(q.put_nowait, {"error": str(e)})
             finally:
-                loop.call_soon_threadsafe(q.put_nowait, None)   # 结束哨兵
+                loop.call_soon_threadsafe(q.put_nowait, None)
 
         _threading.Thread(target=_producer, daemon=True, name="task-stream-sse").start()
         try:
             while True:
                 if await request.is_disconnected():
-                    stop.set(); break                 # 断连 → 停管线 + 停 act LLM
+                    stop.set(); break
                 try:
                     item = await asyncio.wait_for(q.get(), timeout=0.5)
                 except asyncio.TimeoutError:

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

@@ -45,21 +45,17 @@ async def harness_websocket(websocket: WebSocket):
     """
     api_key = os.environ.get("FOXCLAW_API_KEY", "").strip()
     if api_key:
-        # 【P3-loopback】与 HTTP 中间件同口径:本机(127.0.0.1 / ::1)WS 客户端免 ?key=
-        # 设 FOXCLAW_LOOPBACK_BYPASS=0 可关。详见 foxclaw.api.middleware._loopback_bypass_on
         ws_host = websocket.client.host if websocket.client else ""
         if not (_loopback_bypass_on() and _is_loopback_client(ws_host)):
             provided = (websocket.query_params.get("key")
                         or websocket.headers.get("x-api-key"))
-            # 【P3-1】常量时间比较(与 HTTP 中间件同一辅助函数);None 由 or "" 兜底——
-            # api_key 非空时 not eq("", api_key) 必为 True,与原 None != api_key 行为一致
             if not _constant_time_eq(provided or "", api_key):
-                await websocket.close(code=1008)   # policy violation
+                await websocket.close(code=1008)
                 return
     await manager.connect(websocket)
     try:
         while True:
-            await websocket.receive_text()  # 保持连接
+            await websocket.receive_text()
     except WebSocketDisconnect:
         manager.disconnect(websocket)
 

package/python/foxclaw/api/spine.py

@@ -35,11 +35,9 @@ def _prewarm_hkc(osi):
     def _run():
         t0 = _t.time()
         try:
-            svc = getattr(osi, "hkc", None)      # 访问即触发 HKC 惰性装配
+            svc = getattr(osi, "hkc", None)
             if not svc or not getattr(svc, "available", False):
                 return
-            # 搜索索引已在 assemble() 内构建(向量索引持久化加载优先,避免每次启动全量
-            # embedding 把 CPU 打满、启动卡几分钟),这里不再重复 build_index。
             try:
                 lr = getattr(osi, "learning_runtime", None)
                 if lr is not None:
@@ -50,6 +48,5 @@ def _prewarm_hkc(osi):
         except Exception as e:
             print(f"[Foxclaw API] · HKC 预热未启用(可选): {e}")
 
-    # 晚绑定:把守护线程挂到主模块 `__init__.py` 的 `_prewarm_thread`(lifespan 关闭前需 join)。
     _api._prewarm_thread = threading.Thread(target=_run, name="hkc-prewarm", daemon=True)
     _api._prewarm_thread.start()

package/python/foxclaw/browser/action/action_executor.py

@@ -21,10 +21,8 @@ class ActionExecutor:
         return handler(action)
 
     def _do_navigate(self, action: WebAction):
-        # URL 准入:此前直接把模型给的字符串交给 driver → file:// 读本机文件、
-        # javascript: 执行脚本、内网/云元数据 SSRF。ValueError 由 service.act 转成错误返回。
         from .url_policy import validate_navigate_url
-        target = validate_navigate_url(action.target)
+        target = validate_navigate_url(action.target or "")
         self.driver.navigate(target)
         return {"navigated_to": target}
 
@@ -44,8 +42,6 @@ class ActionExecutor:
         return {"scrolled": direction}
 
     def _do_extract(self, action: WebAction):
-        # extract 本身不改变页面状态，只是触发一次重新语义化，
-        # 具体的语义化交给上层 WebAdapter 统一处理，这里返回空占位即可
         return {"extract_requested": True}
 
     def _do_wait(self, action: WebAction):

package/python/foxclaw/browser/action/action_types.py

@@ -9,7 +9,6 @@ from dataclasses import dataclass, field
 from typing import Optional, Any
 
 
-# HIR-Browser 支持的动作类型，故意保持极简，不做扩展性设计
 SUPPORTED_ACTIONS = ("navigate", "click", "type", "scroll", "extract", "wait")
 
 

package/python/foxclaw/browser/action/url_policy.py

@@ -30,12 +30,8 @@ from urllib.parse import urlparse
 
 ALLOWED_SCHEMES = ("http", "https")
 
-# 页面内部 scheme:内容由页面自身生成(data:/blob:),或压根不是网络请求(about:)。
-# 它们不经过网络栈,构不成 SSRF;拦下只会让内联图片 / 媒体源加载失败。
 INTERNAL_SCHEMES = ("data", "blob", "about")
 
-# 解析结果缓存:一个页面动辄几十个子资源,每次都 getaddrinfo 会让加载慢一个量级。
-# 带 TTL 而不是永久缓存 —— 永久缓存会让「先公网后内网」的切换永远不被重查。
 _RESOLVE_TTL = 60.0
 _MAX_CACHE = 512
 _resolve_cache: dict[str, tuple[bool, float]] = {}
@@ -67,7 +63,7 @@ def _resolve_internal(host: str) -> bool:
         return False
     internal = False
     for info in infos:
-        addr = str(info[4][0]).split("%", 1)[0]        # IPv6 可能带 scope id
+        addr = str(info[4][0]).split("%", 1)[0]
         try:
             parsed = ipaddress.ip_address(addr)
         except ValueError:

package/python/foxclaw/browser/adapter/web_adapter.py

@@ -18,7 +18,7 @@ from ..action.action_types import WebAction, SUPPORTED_ACTIONS
 class WebAdapter(BaseAdapter):
 
     def __init__(self, headless: bool = True):
-        self._session = None
+        self._session: "SessionManager | None" = None
         self._headless = headless
 
     def _ensure_session(self):