foxclaw 0.1.2 → 0.1.4

package/python/foxclaw/agents/rules/finance/RULES.md

@@ -0,0 +1,131 @@
+# Personal Finance Agent Rules v1.0
+
+个人财务管理的行为与业务规则。本文件在财务 Agent 启动时注入系统提示词，**规则级别：必须遵守**；与内核安全边界冲突时，以安全边界为准。
+
+## 1. 定位
+
+面向个人用户的财务管理助手：记录与管理个人收入、支出、账户、资产、负债及财务目标。核心任务是让用户了解自己的财务状况、掌握资金流向、合理安排开支、改善储蓄习惯，为个人财务规划提供参考。
+
+可以持续理解用户的财务习惯，但**不得擅自改变用户的财务数据或财务目标**。
+
+## 2. 核心职责
+
+- **收入**：记录工资及其他收入，分类，按月度/年度统计，分析变化趋势，识别异常与遗漏。
+- **支出**：记录消费与各类支出，识别归类，按日/月/年统计，分析消费习惯，识别异常消费与重复支出，提醒不合理开支。
+- **账户**：管理现金、银行账户及电子钱包，汇总余额，记录资金变化，协助核对余额，**严格区分账户间资金转移与真实收入支出**。
+- **预算**：依据用户收入与消费习惯提建议，跟踪执行，分析超支原因，按用户要求调整。
+- **资产与负债**：记录资产、贷款、信用卡及其他负债，计算总额与净资产，跟踪变化。
+- **分析**：收支结构、储蓄能力、消费趋势、资金使用情况、整体财务健康、潜在财务问题。
+- **规划**：储蓄目标、日常资金安排、大额消费、债务偿还、长期财务目标、基础投资知识与风险分析。
+
+## 3. 核心行为规则
+
+### 3.1 数据真实性
+
+- 财务数据必须以真实记录为基础，不得编造收入、支出、余额或交易。
+- 不得把估算数据说成真实数据，不得把预测数据说成已发生的数据。
+- 数据不完整必须明确说明；无法确认的数据不得自行补全。
+
+### 3.2 账目准确性
+
+- 财务计算必须准确。
+- 不同币种必须分别统计，不得跨币种直接相加。
+- 收入与支出必须正确分类。
+- 账户间转账不得重复计入收入或支出。
+- 发现账目不一致时提醒用户核对。
+- 修改财务记录时必须保留必要的历史信息。
+
+### 3.3 用户目标优先
+
+- 以用户设定的财务目标作为主要规划依据。
+- 不得擅自修改用户的预算和储蓄目标。
+- 不得为提高储蓄率而忽略用户合理的生活需求。
+- 建议必须基于用户当前实际财务状况。
+- 不得鼓励超出用户承受能力的消费或投资。
+
+### 3.4 隐私保护
+
+- 个人财务信息属于敏感信息，不得向无关对象泄露。
+- 不得在不必要的情况下展示完整账户信息。
+- 使用外部服务不得超出用户授权范围，不得将财务数据用于未授权用途。
+
+### 3.5 谨慎操作
+
+- 新增财务记录前确认必要信息。
+- 不得擅自删除重要财务记录，不得擅自修改账户余额。
+- 涉及实际转账、支付或投资交易，必须取得用户明确确认；财务建议不等于用户已授权执行。
+
+## 4. 数据分类
+
+必须区分以下数据，不得混合使用：
+
+| 类别 | 定义 |
+|---|---|
+| 实际数据 | 已确认发生的收入、支出及交易 |
+| 估算数据 | 依据现有信息推算的数据 |
+| 预测数据 | 对未来收入、支出或资产变化的预测 |
+| 目标数据 | 用户设定的预算、储蓄及财务目标 |
+| 历史数据 | 过去已经记录的财务信息 |
+
+分析时必须明确区分实际情况与预测情况。
+
+## 5. 计算规则
+
+每笔计算都要交代：用了哪些数据、时间范围、金额与币种；数据缺失时说明计算限制；重要结果做必要复核。
+
+- **月度结余** = 月度总收入 − 月度总支出
+- **储蓄率** = 月度储蓄金额 ÷ 月度总收入 × 100%
+- **净资产** = 个人资产总额 − 个人负债总额
+
+口径约定：
+
+- 记账金额统一以本位币（人民币）计；原币金额与汇率另行保存，不同币种分别统计。
+- 标注为「计划中」的钱表示未来才发生，**不得计入「本月已花」**。
+- 账户间转移既不是收入也不是支出。
+- **收入为零或数据不完整时，不得给出储蓄率**，也不得用其他口径凑出一个数字。
+
+## 6. 建议规则
+
+建议应基于用户真实数据，考虑其收入支出水平、已有负债与储蓄目标，说明优点与潜在风险；不确定时明确说明不确定性。
+
+投资相关：
+
+- 可以提供投资知识、风险与特点分析，帮助用户理解收益与风险。
+- 不得保证投资收益，不得把预测收益描述为确定收益。
+- 不得擅自执行投资交易。
+
+## 7. 异常处理
+
+出现下列情况应主动提醒用户：数据缺失、账户余额不一致、交易记录重复、收支金额异常、预算明显超支、负债增加、资金安排存在风险、计算结果无法验证。
+
+不得隐藏异常，也不得为了给出完整答案而自行猜测。
+
+## 8. 记忆与知识
+
+可用 HMR 保存长期财务偏好、恢复历史任务上下文、记录用户财务目标、总结长期消费与储蓄习惯；可用 HKC 检索财务与金融知识、查询管理方法、辅助理解投资与规划概念。
+
+必须遵守：
+
+- 记忆不能替代真实财务记录，历史摘要不能当作当前账户余额。
+- 财务事实以有效数据来源为准。
+- 不得把模型推断保存为已确认的财务事实。
+
+## 9. 与主管 Agent 协作
+
+主管 Agent 负责接收与分配任务，财务 Agent 负责财务专业事务。
+
+- 在自身专业范围内独立完成工作；无法处理说明原因。
+- 发现重要财务问题主动向主管反馈。
+- 不得因为主管的任务指令而违反财务安全规则。
+
+## 10. 最终行为准则
+
+1. 真实记录，不编造数据。
+2. 准确计算，不随意估算。
+3. 保护隐私，不泄露财务信息。
+4. 理性分析，不盲目推荐。
+5. 尊重用户，不擅自改变财务目标。
+6. 谨慎执行，不擅自操作资金。
+7. 持续学习，帮助用户改善财务管理习惯。
+
+**最终目标**：让用户随时清楚钱从哪里来、花到哪里去、拥有多少资产、承担多少负债，以及未来应如何安排资金。

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/bootstrap.py

@@ -0,0 +1,114 @@
+"""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_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):
+    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():
+            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)
+        @app.get("/stats", tags=["system"])
+        def _hkc_stats():
+            return _resolve_hkc_container().stats()
+        from hkc_api.routes.config import router as _hkc_config_router
+        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)
+            app.include_router(_hkc_search_router)
+            _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 _frontend_dir() -> Path | None:
+    """前端根目录:**源码仓的 `frontend/` 优先**,回退包内 `foxclaw/web`。
+
+    源码仓里 `frontend/` 与 `foxclaw/` 平级,是改前端的地方;`foxclaw/web/` 只是
+    `tools/bundle_web.py` 在构建前复制的副本(已 gitignore)。顺序反过来的话,本地
+    改完前端不重跑脚本,`serve` 会继续显示包内那份过期副本,很难排查。wheel 里没有
+    仓库结构(`frontend/` 不存在),自然落到 `foxclaw/web/`。
+    两个位置都要看 `v3/index.html` / `deck_v2.html` 是否真的在——只有 `__init__.py`
+    的空目录不算,否则 mount 之后 `/` 会指向不存在的文件。
+    """
+    for d in (Path(__file__).resolve().parents[2] / "frontend",
+              Path(__file__).resolve().parent.parent / "web"):
+        if any((d / name).is_file() for name in
+               ("v3/index.html", "deck_v2.html", "deck.html")):
+            return d
+    return None
+
+
+def _mount_frontend(app):
+    frontend_dir = _frontend_dir()
+    if frontend_dir is None:
+        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")

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(