foxclaw 0.1.0 → 0.1.2

package/python/foxclaw/skills/pipeline.py

@@ -0,0 +1,386 @@
+"""
+AHS 执行链 (Execution Pipeline) —— Agent Harness Skills 标准的全面落地。
+
+把 6 个元 skill 串成一条可运行的执行链:
+
+  task → [router 选主skill] → 复杂? → [planner 拆解]
+                                    → [composition 编排多skill]
+       每步 skill 执行都过 [guard 权限] + [breaker 断路] + [hooks 钩子]
+       全程 IO 遵循 [execution-contract],结果可审计
+
+router / planner / composition 在这里实现;guard / breaker / hooks 复用
+permission.py + lifecycle.py;contract 复用 SkillResult。
+"""
+from __future__ import annotations
+import asyncio
+import inspect
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+from ..planning import planner as P   # 统一规划原语(P1-2:否定/拆分/打分单一真源)
+
+
+# ============ skill-router:委托统一引擎,候选空间=skill ============
+
+@dataclass
+class RouteResult:
+    primary: Optional[str] = None        # 选中的主 skill id
+    confidence: float = 0.0
+    candidates: list = field(default_factory=list)   # [(skill_id, score)]
+    fallback: Optional[str] = None
+    needs_composition: bool = False
+    reason: str = ""
+
+
+def route(task: str, registry, fallback_id: str = None) -> RouteResult:
+    """skill-router:把 skill 适配成通用候选,交统一引擎 trigger_route 打分选择。
+    算法(否定过滤触发命中 0.8 + 描述领域匹配 0.2)现由 foxclaw.planning 单一真源提供。"""
+    skills = registry.all()
+    if not skills:
+        return RouteResult(reason="注册表为空")
+    cands = [P.ScoredCandidate(
+                id=s.id,
+                triggers=getattr(s, "triggers", []) or [],
+                description=getattr(s, "description", "") or "")
+             for s in skills]
+    r = P.trigger_route(task, cands, fallback_id=fallback_id)
+    return RouteResult(primary=r.primary, confidence=r.confidence,
+                       candidates=r.candidates, fallback=r.fallback,
+                       needs_composition=r.needs_composition, reason=r.reason)
+
+
+# ============ planner:任务拆解 ============
+
+@dataclass
+class PlanTask:
+    id: str
+    name: str
+    suggested_skill: Optional[str] = None
+    dependencies: list = field(default_factory=list)
+
+
+@dataclass
+class Plan:
+    intent: str
+    tasks: list = field(default_factory=list)        # [PlanTask]
+    flow_type: str = "sequential"                    # sequential/parallel/hybrid
+    steps: list = field(default_factory=list)        # 执行顺序 [task_id]
+    needs_input: bool = False
+    missing: list = field(default_factory=list)
+
+
+def plan(task: str, registry) -> Plan:
+    """planner:把任务拆成结构化计划。拆分/并行标记与算法由 foxclaw.planning 单一真源提供。
+
+    - 含并行连接词(同时/分别/并行)→ 拆成**无依赖**子任务,flow_type=parallel;
+    - 含顺序连接词(然后/接着…)→ 拆成**线性依赖链**,flow_type=sequential;
+    - 都没有 → 单步。
+    依赖关系决定能否并行:parallel 的子任务 dependencies 为空,sequential 的链式依赖前一步。
+    """
+    task = (task or "").strip()
+    if not task:
+        return Plan(intent="", needs_input=True, missing=["task"])
+
+    if any(k in task for k in P.PARALLEL_TRIGGERS):
+        parts = P.split_on(task, P.PARALLEL_TRIGGERS + P.LIST_SEPS)
+        flow = "parallel" if len(parts) > 1 else "sequential"
+    else:
+        parts = P.split_on(task, P.SPLIT_MARKERS)
+        flow = "sequential"
+    if len(parts) <= 1:
+        parts, flow = [task], "sequential"
+
+    tasks, steps = [], []
+    for i, p in enumerate(parts, 1):
+        r = route(p, registry)
+        tid = f"T{i}"
+        # 顺序:依赖前一步;并行:无依赖(可同时 fork)
+        deps = [f"T{i-1}"] if (i > 1 and flow == "sequential") else []
+        tasks.append(PlanTask(id=tid, name=p, suggested_skill=r.primary,
+                              dependencies=deps))
+        steps.append(tid)
+
+    return Plan(intent=task, tasks=tasks, flow_type=flow, steps=steps)
+
+
+# ============ composition:多 skill 编排执行 ============
+
+@dataclass
+class StageResult:
+    stage: int
+    skill_id: str
+    result: dict
+
+
+@dataclass
+class CompositionResult:
+    mode: str
+    stages: list = field(default_factory=list)       # [StageResult]
+    final_output: dict = field(default_factory=dict)
+    failed: list = field(default_factory=list)
+    rolled_back: bool = False
+    rollback_clean: bool = True                       # 回滚是否干净完成(无补偿失败/无需人工)
+    rollback_log: list = field(default_factory=list)  # 回滚记录 [{skill,status,detail}]
+    needs_manual: list = field(default_factory=list)  # 需人工处理的 skill(无补偿/补偿失败)
+    # 【P2-2】待确认状态:遇到 needs_confirmation 时填充(不回滚),供调用方展示+断点续跑
+    pending_confirmation: dict = None                 # {task_id,skill_id,stage,message,args,completed_steps,resume_at}
+    # 【P2-2】已完成步骤(断点续跑所需的现场): [(task_id, skill_id, output)]
+    completed_steps: list = field(default_factory=list)
+
+    @property
+    def is_pending(self) -> bool:
+        """【P2-2】是否处于待确认暂停态。"""
+        return self.pending_confirmation is not None
+
+    @property
+    def is_failed(self) -> bool:
+        return bool(self.failed)
+
+
+def _build_args(skill, task_text: str, upstream: dict) -> dict:
+    """把任务文本映射到 skill 声明的参数。
+
+    简化策略:单参数 skill → 把任务文本(或提取的算式)塞给那个参数;
+    多参数 skill → 交给 skill 自己解析(传 task + upstream)。
+    真实系统里这一步由 LLM 做参数抽取;此处做轻量映射保证可运行。
+    """
+    params = skill.params or {}
+    if not params:
+        return {}
+    # 计算器类:从文本提取数学表达式
+    if "expression" in params:
+        m = re.search(r"[-+*/().\d\s]+", task_text)
+        expr = (m.group(0).strip() if m else task_text)
+        return {"expression": expr or task_text}
+    # 单参数 skill:把整段任务文本作为该参数
+    if len(params) == 1:
+        only = next(iter(params))
+        return {only: task_text}
+    # 多参数:传 task,让下游(或 LLM)解析;附带上游
+    return {"task": task_text, "upstream_outputs": dict(upstream)}
+
+
+def _rollback(executed, registry, res: CompositionResult):
+    """逆序回滚已执行且有副作用的步骤。
+
+    executed: [(skill_id, output)] 按执行顺序。
+    只回滚有副作用(非只读)的;有 compensate 的调用补偿,无的标记需人工处理。
+    """
+    res.rolled_back = True
+    for sid, output in reversed(executed):
+        skill = registry.get(sid)
+        if skill is None:
+            continue
+        side_effect = getattr(skill, "side_effect", "read")
+        if side_effect == "read":
+            continue   # 只读操作无副作用,无需回滚
+        comp = getattr(skill, "compensate", None)
+        if comp is not None:
+            try:
+                comp(output)
+                res.rollback_log.append({"skill": sid, "status": "compensated",
+                                         "detail": "已调用补偿动作撤销副作用"})
+            except Exception as e:
+                res.rollback_log.append({"skill": sid, "status": "compensate_failed",
+                                         "detail": f"补偿失败: {e}"})
+                res.rollback_clean = False          # 补偿失败 → 回滚不干净
+                res.needs_manual.append(sid)
+        else:
+            res.rollback_log.append({"skill": sid, "status": "manual_required",
+                                     "detail": f"{side_effect} 操作无补偿动作,需人工处理"})
+            res.rollback_clean = False              # 有副作用却无法补偿 → 不干净
+            res.needs_manual.append(sid)
+
+
+def _invoke(adapter, skill, args: dict, confirmed: bool, confirm_nonce: str):
+    """调 `adapter.invoke`,老 adapter 自动降级为 4 参旧签名。
+
+    测试/第三方 adapter 常只实现 `invoke(skill, args, confirmed=, mode=)`;用签名探测
+    而不是 try/except TypeError —— 后者会把 invoke 内部真正的 TypeError 当"签名不兼容"吞掉。
+    """
+    fn = adapter.invoke
+    try:
+        params = inspect.signature(fn).parameters
+        accepts = ("confirm_nonce" in params
+                   or any(p.kind is p.VAR_KEYWORD for p in params.values()))
+    except (TypeError, ValueError):
+        accepts = False
+    if accepts:
+        return fn(skill, args, confirmed=confirmed, confirm_nonce=confirm_nonce)
+    return fn(skill, args, confirmed=confirmed)
+
+
+def compose(plan_obj: Plan, registry, adapter, confirmed: bool = False,
+            resume_state: dict = None) -> CompositionResult:
+    """skill-composition:按计划顺序执行各 skill。
+
+    结束态三种:
+      · success —— 全部成功
+      · pending —— 遇到 needs_confirmation,**暂停(不回滚)**,待用户确认后续跑
+      · failed  —— 遇到 blocked/circuit_open/error/timeout,逆序回滚补偿
+
+    【P2-2】needs_confirmation 不再当失败处理:暂停而非回滚,避免撤销已完成的
+    有效步骤(反例:创建日程已成功、发邮件待确认,旧逻辑会把日程回滚掉)。
+    可选 resume_state(上次 compose 的 pending_confirmation)用于从断点续跑:
+    恢复已完成步骤的 upstream/executed 现场,跳过 resume_at 之前的步骤。
+    """
+    res = CompositionResult(mode=plan_obj.flow_type)
+    upstream = {}     # skill_id -> output(供下游读取)
+    executed = []     # [(skill_id, output)] 按执行顺序,供回滚
+
+    # 【P2-2】恢复已完成步骤(断点续跑)
+    resume_at = None
+    if resume_state:
+        for tid, sid, output in resume_state.get("completed_steps", []):
+            upstream[sid] = output
+            executed.append((sid, output))
+            res.completed_steps.append((tid, sid, output))
+        resume_at = resume_state.get("resume_at")
+
+    for i, t in enumerate(plan_obj.tasks, 1):
+        # 【P2-2】跳过已完成的步骤(断点续跑):resume_at 之前的步骤不重跑;
+        # 命中断点后清空 resume_at,让断点及其之后的步骤正常执行。
+        # (若照抄"!= resume_at 就 continue",断点之后的步骤会被一并跳过)
+        if resume_at:
+            if t.id != resume_at:
+                continue
+            resume_at = None
+        sid = t.suggested_skill
+        if not sid or not registry.get(sid):
+            res.failed.append(t.id); continue
+        skill = registry.get(sid)
+        call_args = _build_args(skill, t.name, upstream)
+        # 关键操作二次确认码随 resume_state 回灌:同一 nonce 只能在原动作+原参数上用一次
+        _nonce = (resume_state or {}).get("confirm_nonce", "") or ""
+        out = _invoke(adapter, skill, call_args, confirmed, _nonce)
+        res.stages.append(StageResult(stage=i, skill_id=sid, result=out.to_dict()))
+        if out.success:
+            upstream[sid] = out.output
+            executed.append((sid, out.output))
+            res.completed_steps.append((t.id, sid, out.output))
+        elif out.status == "needs_confirmation":
+            # 【P2-2】待确认 → 暂停,不回滚;把断点现场打包给调用方
+            res.pending_confirmation = {
+                "task_id": t.id,
+                "skill_id": sid,
+                "stage": i,
+                "message": out.message,
+                "args": call_args,
+                "completed_steps": list(res.completed_steps),
+                "resume_at": t.id,
+                # 关键操作:一次性确认码(绑定 skill + 本次 args,过期即废)。
+                # 续跑时把它塞回 resume_state 一起传,才能通过 adapter 的二次确认校验。
+                "confirm_nonce": getattr(out, "confirm_nonce", "") or "",
+                "confirm_expires_at": getattr(out, "confirm_expires_at", 0.0) or 0.0,
+            }
+            res.final_output = {
+                "pending": True,
+                "at": t.id,
+                "completed": [s[0] for s in res.completed_steps],
+            }
+            return res
+        else:
+            # blocked/circuit_open/error/timeout → 关键路径失败 → 逆序回滚
+            res.failed.append(t.id)
+            res.final_output = {"error": out.message, "failed_at": t.id}
+            _rollback(executed, registry, res)
+            return res
+    res.final_output = upstream
+    return res
+
+
+# ============ 编排器:把 6 个元 skill 串起来 ============
+
+@dataclass
+class PipelineResult:
+    task: str
+    route: dict
+    plan: dict
+    composition: dict
+    success: bool
+    summary: str
+
+    @property
+    def pending_confirmation(self) -> dict:
+        """【P2-2】待确认状态(若无则 None)。结构见 compose 的 pending_confirmation。"""
+        return self.composition.get("pending_confirmation")
+
+    @property
+    def is_pending(self) -> bool:
+        """【P2-2】是否处于待确认暂停态(此时 success=False,但语义是"暂停等确认")。"""
+        return self.pending_confirmation is not None
+
+
+class AHSPipeline:
+    """AHS 执行链编排器:一条龙跑通 router→planner→composition,全程过 guard+breaker+hooks。"""
+
+    def __init__(self, registry, adapter):
+        self.registry = registry
+        self.adapter = adapter
+
+    def run(self, task: str, confirmed: bool = False,
+            resume_state: dict = None, confirm_nonce: str = "") -> PipelineResult:
+        """同步执行。【P2-2】resume_state 用于从待确认状态断点续跑
+        (传上次返回的 pending_confirmation;确认后调 run(task, confirmed=True, resume_state=...))。
+
+        `confirm_nonce`(关键操作):compose 会把它并进 resume_state 传给 adapter 校验;
+        也可以直接放在 resume_state 里(pending_confirmation 已带出该字段)。
+        """
+        if confirm_nonce:
+            resume_state = {**(resume_state or {}), "confirm_nonce": confirm_nonce}
+        # session_start 钩子
+        self.adapter.hooks.fire("session_start", "", {"task": task})
+
+        # 1. router 选主 skill
+        r = route(task, self.registry)
+
+        # 2. planner 拆解(总是出计划;简单任务=单步)
+        p = plan(task, self.registry)
+
+        # 3. composition 编排执行(每步内部过 guard+breaker+hooks)
+        c = compose(p, self.registry, self.adapter,
+                    confirmed=confirmed, resume_state=resume_state)
+
+        # session_end 钩子
+        self.adapter.hooks.fire("session_end", "", {"task": task})
+
+        # 【P2-2】success 判定区分 pending:待确认不是失败,但也不是成功
+        # (旧语义:pending 会进 failed → success=False;新语义:pending 非空 → success=False。
+        #  外向结果一致,语义不同——pending 的步骤没有被回滚,可以续跑)
+        success = not c.failed and bool(c.stages) and not c.pending_confirmation
+        if c.pending_confirmation:
+            summary = (f"执行 {len(c.stages)} 步,待确认:"
+                       f"{c.pending_confirmation['skill_id']}")
+        elif c.failed:
+            summary = f"执行 {len(c.stages)} 步,部分失败:{','.join(c.failed)}"
+        else:
+            summary = f"执行 {len(c.stages)} 步,全部成功"
+        return PipelineResult(
+            task=task,
+            route={"primary": r.primary, "confidence": r.confidence,
+                   "needs_composition": r.needs_composition},
+            plan={"intent": p.intent, "steps": p.steps,
+                  "tasks": [{"id": t.id, "name": t.name, "skill": t.suggested_skill}
+                            for t in p.tasks]},
+            composition={"mode": c.mode, "stages": len(c.stages),
+                         "failed": c.failed, "final": c.final_output,
+                         "rolled_back": c.rolled_back, "rollback_clean": c.rollback_clean,
+                         "rollback_log": c.rollback_log, "needs_manual": c.needs_manual,
+                         # 【P2-2】待确认 + 已完成步骤(供前端识别/续跑)
+                         "pending_confirmation": c.pending_confirmation,
+                         "completed_steps": [s[0] for s in c.completed_steps]},
+            success=success, summary=summary)
+
+    async def run_async(self, task: str, confirmed: bool = False,
+                        resume_state: dict = None,
+                        confirm_nonce: str = "") -> PipelineResult:
+        """【P2-1】异步入口:把同步 run 放到线程池,避免阻塞事件循环。
+
+        内部用 asyncio.to_thread 包装,故 run 里的同步 IO(MCP/Web API/本地 handler)
+        不会阻塞调用方的事件循环。async 调用方(如 /api/ahs/run)应调本方法。
+        注意:asyncio.to_thread 会复制当前 contextvars 到子线程(如 skill actor),
+        子线程异常原样抛回 await 处——两者都是想要的行为。
+        """
+        return await asyncio.to_thread(self.run, task, confirmed, resume_state,
+                                       confirm_nonce)

package/python/foxclaw/skills/policy.py

@@ -0,0 +1,80 @@
+"""全局技能策略:deny 封杀 + allow 白名单(治理 kill-switch,借鉴 OpenClaw plugins.deny/allow)。
+deny 压倒一切;allow 非空则只放行白名单内。user 层持久化 <data_dir>/skill_policy.json。
+E1 分层:另有 **policy 层** deny(管理员锁定,env FOXCLAW_POLICY_DENY + <data_dir>/policy.json,与
+user 层物理分开),**不可被运行时 undeny 撤销**;经 core/config.py 的 LayeredConfig 合并(policy∪user)。"""
+from __future__ import annotations
+import json
+import threading
+from pathlib import Path
+
+
+class SkillPolicy:
+    def __init__(self, data_dir):
+        self._path = Path(data_dir) / "skill_policy.json"
+        self._lock = threading.RLock()
+        self._deny: set = set()    # user 层:运行时可 deny/undeny,持久化到 skill_policy.json
+        self._allow: set = set()   # 空 = 全放行
+        # E1 分层:policy 层 deny(管理员锁定,env FOXCLAW_POLICY_DENY + <data_dir>/policy.json)。
+        # 与 user 层物理分开、不写回 skill_policy.json;**不可被 undeny 撤销**。默认空 = 现状。
+        from ..core.config import LayeredConfig, load_policy_layer
+        policy_layer = load_policy_layer(data_dir)
+        # user 层传 self._deny(set 引用)→ 运行时增删被 merged_set 实时反映,无需重建 LayeredConfig
+        self._layers = LayeredConfig(policy=policy_layer, user={"deny": self._deny})
+        self._load()
+
+    def is_blocked(self, skill_id: str) -> bool:
+        with self._lock:
+            # deny = policy 层 ∪ user 层(只增不减);deny 压倒 allow
+            if skill_id in self._layers.merged_set("deny"):
+                return True
+            if self._allow and skill_id not in self._allow:
+                return True
+            return False
+
+    def deny(self, skill_id: str):
+        with self._lock:
+            self._deny.add(skill_id)
+        self._save()
+
+    def undeny(self, skill_id: str) -> bool:
+        with self._lock:
+            if skill_id in self._layers.policy_locked("deny"):
+                return False       # E1:policy 层为管理员锁定,用户 undeny 无效(deny 铁律)
+            existed = skill_id in self._deny
+            self._deny.discard(skill_id)
+        self._save()
+        return existed
+
+    def set_allow(self, ids):
+        with self._lock:
+            self._allow = set(ids or [])
+        self._save()
+
+    def snapshot(self) -> dict:
+        with self._lock:
+            return {"deny": sorted(self._deny), "allow": sorted(self._allow),
+                    "policy_deny": sorted(self._layers.policy_locked("deny"))}  # E1:管理员锁定项(只读)
+
+    def _load(self):
+        if not self._path.exists():
+            return
+        try:
+            d = json.loads(self._path.read_text(encoding="utf-8"))
+            # 就地更新 self._deny(不重新赋值!)——LayeredConfig.user 持有本 set 的引用,
+            # 重新赋值会断开引用,导致从盘加载的 user deny 不被 merged_set 反映(E1 集成的坑)。
+            self._deny.clear()
+            self._deny.update(d.get("deny") or [])
+            self._allow = set(d.get("allow") or [])
+        except Exception:
+            pass
+
+    def _save(self):
+        with self._lock:
+            payload = {"deny": sorted(self._deny), "allow": sorted(self._allow)}
+        try:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            tmp = self._path.with_suffix(".tmp")
+            tmp.write_text(json.dumps(payload, ensure_ascii=False, indent=1), encoding="utf-8")
+            tmp.replace(self._path)
+        except Exception:
+            pass

package/python/foxclaw/skills/review.py

@@ -0,0 +1,72 @@
+"""安装审核门:技能注册前的治理审核(对齐 OpenClaw security.installPolicy)。
+非杀毒——远程 URL 无法扫描;做 SSRF 预检/域名黑名单/明文告警/副作用与信任提示,
+产出 allow|warn|deny,风险项要求用户显式确认。"""
+from __future__ import annotations
+import os
+import ipaddress
+import socket
+from urllib.parse import urlparse
+
+
+def _host_deny() -> set:
+    return {h.strip().lower() for h in os.environ.get("FOXCLAW_SKILL_HOST_DENY", "").split(",") if h.strip()}
+
+
+def _is_internal_host(host: str) -> bool:
+    if not host:
+        return True
+    if host.lower() == "localhost":
+        return True
+    try:
+        infos = socket.getaddrinfo(host, None)
+    except Exception:
+        return False   # 解析不了 → 不在安装期硬挡,交运行时 SSRF 兜底
+    for info in infos:
+        try:
+            addr = ipaddress.ip_address(info[4][0])
+        except ValueError:
+            continue
+        if addr.is_private or addr.is_loopback or addr.is_link_local or addr.is_reserved:
+            return True
+        if str(addr) == "169.254.169.254":   # 云元数据
+            return True
+    return False
+
+
+def review_install(spec) -> dict:
+    """返回 {verdict: allow|warn|deny, reasons: [...], warnings: [...]}。"""
+    reasons, warnings = [], []
+    if spec.kind == "web_api":
+        host = (urlparse(spec.endpoint).hostname or "").lower()
+        if host in _host_deny():
+            reasons.append(f"域名 {host} 在黑名单")
+        if not spec.allow_local and _is_internal_host(host):
+            reasons.append(f"endpoint 指向内网/本地/元数据地址({host or '?'}),已拦截(SSRF)")
+        if spec.endpoint.startswith("http://"):
+            warnings.append("使用明文 HTTP,传输不加密")
+    if spec.kind == "mcp":
+        warnings.append("MCP 来源为外部低信任,其返回内容不应被当作指令执行")
+    if spec.side_effect in ("write", "send", "pay") or spec.destructive:
+        warnings.append(f"该技能有副作用({spec.side_effect}{'/不可逆' if spec.destructive else ''}),会真实影响外部")
+    if reasons:
+        return {"verdict": "deny", "reasons": reasons, "warnings": warnings}
+    if warnings:
+        return {"verdict": "warn", "reasons": [], "warnings": warnings}
+    return {"verdict": "allow", "reasons": [], "warnings": []}
+
+
+def review_mcp_server(url: str) -> dict:
+    """MCP server 接入审核。外部低信任 → 恒 warn(需确认);内网/元数据/黑名单 → deny。"""
+    from urllib.parse import urlparse
+    reasons, warnings = [], []
+    host = (urlparse(url).hostname or "").lower()
+    if host in _host_deny():
+        reasons.append(f"域名 {host} 在黑名单")
+    if _is_internal_host(host):
+        reasons.append(f"MCP url 指向内网/本地/元数据地址({host or '?'}),已拦截(SSRF)")
+    if url.startswith("http://"):
+        warnings.append("使用明文 HTTP,传输不加密")
+    warnings.append("接入外部 MCP server,其返回内容为外部不可信数据,不应被当作指令执行")
+    if reasons:
+        return {"verdict": "deny", "reasons": reasons, "warnings": warnings}
+    return {"verdict": "warn", "reasons": [], "warnings": warnings}   # 外部低信任恒 warn

package/python/foxclaw/skills/store.py

@@ -0,0 +1,57 @@
+"""用户安装技能 + 内置技能启停覆盖的持久化。知识/记忆各有真源;技能注册表原为纯内存,
+本层让"安装"重启不丢。文件:<data_dir>/user_skills.json。"""
+from __future__ import annotations
+import json
+import threading
+from pathlib import Path
+from dataclasses import fields as _fields
+
+from . import SkillSpec, SkillRegistry
+
+
+class SkillStore:
+    def __init__(self, data_dir):
+        self._path = Path(data_dir) / "user_skills.json"
+        self._lock = threading.Lock()
+
+    def _spec_fields(self) -> set:
+        return {f.name for f in _fields(SkillSpec) if f.name != "handler"}
+
+    def load(self, registry: SkillRegistry):
+        """启动恢复:注册用户技能 + 应用内置启停覆盖。文件缺失/损坏 → 静默跳过(全新库)。"""
+        if not self._path.exists():
+            return
+        try:
+            data = json.loads(self._path.read_text(encoding="utf-8"))
+        except Exception:
+            return
+        allowed = self._spec_fields()
+        for d in data.get("skills", []):
+            try:
+                spec = SkillSpec(**{k: v for k, v in d.items() if k in allowed})
+                spec.source = "user"
+                registry.register(spec)
+            except Exception:
+                continue
+        for sid, ov in (data.get("overrides") or {}).items():
+            sp = registry.get(sid)
+            if sp is not None and "enabled" in ov:
+                sp.enabled = bool(ov["enabled"])
+
+    def save(self, registry: SkillRegistry):
+        """把用户技能 + 被改过 enabled 的内置技能原子写回。写盘失败不抛(内存注册仍生效)。"""
+        with self._lock:
+            user_skills, overrides = [], {}
+            for sp in registry.all_including_disabled():
+                if sp.source == "user":
+                    user_skills.append(sp.to_dict())
+                elif sp.enabled is False:
+                    overrides[sp.id] = {"enabled": False}
+            payload = {"skills": user_skills, "overrides": overrides}
+            try:
+                self._path.parent.mkdir(parents=True, exist_ok=True)
+                tmp = self._path.with_suffix(".tmp")
+                tmp.write_text(json.dumps(payload, ensure_ascii=False, indent=1), encoding="utf-8")
+                tmp.replace(self._path)
+            except Exception:
+                pass

package/python/frontend/deck/auth.js

@@ -0,0 +1,32 @@
+/* 鉴权注入:后端若设了 FOXCLAW_API_KEY,同源 /api、/knowledge 请求需带 X-API-Key。
+   从 localStorage.foxclawApiKey 读取并包一层 fetch 自动注入。
+   必须最先加载(在 settings.js 等业务模块之前),否则模块顶层提前发出的请求
+   (如 settings.js 的 loadModel → /api/model)会漏带 key 被 401。 */
+(function(){
+  if(window.__foxclawFetchPatched) return;
+  const _fetch=window.fetch.bind(window);
+  let _authHinted=false;
+  window.fetch=function(url,opts){
+    try{
+      const key=localStorage.getItem('foxclawApiKey');
+      const u=String(url||'');
+      // /knowledge/* 与 /api/* 一样受后端可选鉴权守护,两者都要注入 key
+      // /stats 是 HKC 统计数据面,后端已纳入守护,同样需要注入
+      if(key && (u.indexOf('/api')>=0 || u.indexOf('/knowledge')>=0 || u.indexOf('/stats')>=0)){
+        opts=opts||{}; opts.headers=Object.assign({}, opts.headers, {'X-API-Key':key});
+      }
+    }catch(e){}
+    const p=_fetch(url,opts);
+    // 401 检测:后端开了鉴权但本机浏览器没配 key(或 key 错)→ 弹提示条引导(只弹一次)
+    try{
+      p.then(r=>{
+        if(r && r.status===401 && !_authHinted){
+          _authHinted=true;
+          if(typeof window.__foxclawAuthHint==='function') window.__foxclawAuthHint();
+        }
+      }).catch(()=>{});
+    }catch(e){}
+    return p;
+  };
+  window.__foxclawFetchPatched=true;
+})();