foxclaw 0.1.0 → 0.1.2

package/python/foxclaw/skills/hooks_spec.py

@@ -0,0 +1,73 @@
+"""
+Foxclaw — 标准生命周期钩子点 (Lifecycle Hooks Specification)
+
+借鉴 OpenClaw 的标准钩子命名体系,把原本零散的钩子点规整成清晰的生命周期。
+钩子分两类:
+  · 会话级:贯穿一次 Agent 任务(session_start → agent_start → ... → agent_end → session_end)
+  · 工具级:每次 skill 调用(before_tool_call → after_tool_call / on_error / on_loop)
+
+阻断权限:只有 before_tool_call(原 pre_skill)被授予阻断权——它是守门人。
+其余钩子是观察者(顾问不是控制器),失败不影响主链路。
+
+向后兼容:旧名(pre_skill/post_skill)仍可用,通过 ALIAS 映射到标准名。
+"""
+from __future__ import annotations
+
+
+# ── 标准钩子点(生命周期顺序)──────────────────────────────
+class Hooks:
+    """标准钩子点常量。用 Hooks.BEFORE_TOOL_CALL 而非裸字符串,避免拼写错误。"""
+
+    # 会话级
+    SESSION_START = "session_start"     # 一次任务开始
+    AGENT_START = "agent_start"         # Agent 开始处理(分诊后)
+    AGENT_END = "agent_end"             # Agent 处理完成
+    SESSION_END = "session_end"         # 一次任务结束
+
+    # 工具/skill 级
+    BEFORE_TOOL_CALL = "before_tool_call"   # 调用前(可阻断/可改参数)
+    AFTER_TOOL_CALL = "after_tool_call"     # 调用成功后
+    ON_ERROR = "on_error"                   # 调用失败
+    ON_LOOP = "on_loop"                     # 检测到死循环
+
+    # 消息级
+    BEFORE_MESSAGE_WRITE = "before_message_write"   # 写入/发送消息前(可改写)
+
+
+# 所有标准钩子点(供校验)
+ALL_HOOKS = frozenset({
+    Hooks.SESSION_START, Hooks.AGENT_START, Hooks.AGENT_END, Hooks.SESSION_END,
+    Hooks.BEFORE_TOOL_CALL, Hooks.AFTER_TOOL_CALL, Hooks.ON_ERROR, Hooks.ON_LOOP,
+    Hooks.BEFORE_MESSAGE_WRITE,
+})
+
+# 拥有阻断权的钩子(只有这些返回 {block:True} 才生效)
+BLOCKING_HOOKS = frozenset({Hooks.BEFORE_TOOL_CALL})
+
+# 可注入 additionalContext 的钩子(E2:非阻断,但其返回的 additional_context 会被并入推理上下文)。
+# agent_start = 一次 Agent 任务的推理开始点,对应范式 pre_reasoning —— 推理前注入上下文的落点。
+CONTEXT_HOOKS = frozenset({Hooks.AGENT_START})
+
+# 工具级钩子(按 skill_id 做 matcher 过滤)
+TOOL_SCOPED_HOOKS = frozenset({
+    Hooks.BEFORE_TOOL_CALL, Hooks.AFTER_TOOL_CALL, Hooks.ON_ERROR, Hooks.ON_LOOP,
+})
+
+# 向后兼容 + 语义别名 → 标准名
+ALIAS = {
+    "pre_skill": Hooks.BEFORE_TOOL_CALL,
+    "post_skill": Hooks.AFTER_TOOL_CALL,
+    # E2:推理层/会话层语义名(对齐范式 pre_reasoning / Stop),规整到已有的会话级钩子点——
+    # 顺带**复活**此前定义却从未被 fire 的 agent_start / agent_end 孤儿钩子。
+    "pre_reasoning": Hooks.AGENT_START,   # 一次 Agent 任务推理开始前(可注入 additionalContext)
+    "task_complete": Hooks.AGENT_END,     # 一次 Agent 任务结束后(只读观测/上报,对应范式 Stop)
+}
+
+
+def normalize_hook(event: str) -> str:
+    """把旧钩子名规整为标准名;已是标准名则原样返回。"""
+    return ALIAS.get(event, event)
+
+
+def is_valid_hook(event: str) -> bool:
+    return normalize_hook(event) in ALL_HOOKS

package/python/foxclaw/skills/lifecycle.py

@@ -0,0 +1,278 @@
+"""
+横切机制:断路器 + 生命周期钩子 —— AHS FRAMEWORK.md 的代码落地。
+
+  CircuitBreaker  每个 skill 独立计数,连续失败 N 次 → OPEN → 停止重试 → 降级
+  HookManager     pre_skill/post_skill/on_error/session_start/session_end +
+                  agent_start(别名 pre_reasoning,可注入 additionalContext)/
+                  agent_end(别名 task_complete,只读)——认知管线 run_task 触发(E2)
+                  超时受限、容错、可审计;hook 是顾问不是控制器
+                  (例外:pre_skill 显式返回 deny 可阻断)
+
+对应 docs/internal/HARNESS_STANDARD.md 第二期(稳健性)。
+"""
+from __future__ import annotations
+import time
+import fnmatch
+import threading
+from collections import deque
+from dataclasses import dataclass
+from typing import Callable, Optional, Literal
+
+
+# ============ 断路器 ============
+
+CircuitState = Literal["closed", "open", "half_open"]
+
+
+@dataclass
+class _BreakerEntry:
+    failures: int = 0                 # closed 态的连续失败计数
+    state: CircuitState = "closed"
+    opened_at: float = 0.0            # 进入 open 的时刻(用于冷却计时)
+    probe_in_flight: bool = False     # half_open 态:是否已有探针在执行(只放一个)
+    probe_started_at: float = 0.0     # 探针放行的时刻(用于探针超时自愈)
+    probe_successes: int = 0          # half_open 态:已累计的探针成功数
+
+
+class CircuitBreaker:
+    """每个 skill 独立的断路器。标准三态机:closed / open / half_open。
+
+    - closed:正常放行。连续失败 ≥ threshold → 转 open
+    - open:停止调用。冷却 cooldown 秒后 → 转 half_open
+    - half_open:只放行 ONE 个探针请求(其余仍拒绝);
+        探针成功累计达 recovery_threshold → 转 closed(恢复);
+        任一探针失败 → 转回 open,重新计冷却
+    """
+
+    def __init__(self, threshold: int = 3, cooldown: float = 30.0,
+                 recovery_threshold: int = 1, probe_timeout: float = 60.0):
+        self.threshold = threshold
+        self.cooldown = cooldown
+        self.recovery_threshold = max(1, recovery_threshold)  # 恢复需连续成功几次
+        self.probe_timeout = probe_timeout   # 探针超过此时长未记账 → 视为丢失,释放
+        self._entries: dict[str, _BreakerEntry] = {}
+        self._lock = threading.RLock()    # allow/record 可能跨线程,需加锁
+
+    def _get(self, sid: str) -> _BreakerEntry:
+        if sid not in self._entries:
+            self._entries[sid] = _BreakerEntry()
+        return self._entries[sid]
+
+    def allow(self, sid: str) -> bool:
+        """该 skill 现在是否允许调用。
+
+        closed → True;open(冷却中)→ False;
+        open(冷却满)→ 转 half_open 并放行这一个探针;
+        half_open → 仅当没有探针在飞时放行一个,否则 False。
+        """
+        with self._lock:
+            e = self._get(sid)
+            if e.state == "closed":
+                return True
+            if e.state == "open":
+                if time.time() - e.opened_at >= self.cooldown:
+                    # 冷却满 → 真正进入 half_open,放行第一个探针
+                    e.state = "half_open"
+                    e.probe_in_flight = True
+                    e.probe_started_at = time.time()
+                    e.probe_successes = 0
+                    return True
+                return False
+            # half_open:已有探针在飞 → 拒绝其余;否则放行一个新探针
+            if e.state == "half_open":
+                if e.probe_in_flight:
+                    # 探针超时未记账(调用方崩溃/漏记)→ 视为丢失,释放以免永久卡死
+                    if time.time() - e.probe_started_at >= self.probe_timeout:
+                        e.probe_in_flight = False
+                    else:
+                        return False
+                e.probe_in_flight = True
+                e.probe_started_at = time.time()
+                return True
+            return False
+
+    def record_success(self, sid: str):
+        with self._lock:
+            e = self._get(sid)
+            if e.state == "half_open":
+                e.probe_in_flight = False
+                e.probe_successes += 1
+                if e.probe_successes >= self.recovery_threshold:
+                    # 探针连续成功达标 → 恢复
+                    e.state = "closed"
+                    e.failures = 0
+                    e.probe_successes = 0
+                # 否则保持 half_open,等下一个探针
+            else:
+                e.failures = 0
+                e.state = "closed"
+
+    def record_failure(self, sid: str):
+        with self._lock:
+            e = self._get(sid)
+            if e.state == "half_open":
+                # 探针失败 → 回到 open,重新计冷却
+                e.state = "open"
+                e.opened_at = time.time()
+                e.probe_in_flight = False
+                e.probe_successes = 0
+                return
+            e.failures += 1
+            if e.failures >= self.threshold:
+                e.state = "open"
+                e.opened_at = time.time()
+
+    def status(self, sid: str) -> dict:
+        with self._lock:
+            e = self._get(sid)
+            state = e.state
+            # open 但冷却已满 → 对外显示 half_open(下次 allow 会真正转入)
+            if e.state == "open" and time.time() - e.opened_at >= self.cooldown:
+                state = "half_open"
+            return {"state": state, "failures": e.failures,
+                    "threshold": self.threshold,
+                    "probe_successes": e.probe_successes,
+                    "recovery_threshold": self.recovery_threshold}
+
+    def is_open(self, sid: str) -> bool:
+        """只读查询:该 skill 当前是否处于「阻止调用」状态。
+
+        【P4-0】原实现写的是 `state == "open" and not self.allow(sid)` —— 但 allow() 在
+        「open 且冷却已满」时会**副作用性地**转入 half_open 并占掉唯一的探针名额。于是
+        「只想看一眼断路器开着没」的监控代码会意外消耗掉恢复探测机会,把真正该放行的探针
+        挡在外面。这里改成纯读,不做任何状态迁移。
+
+        语义:open 且冷却未满 → 阻止;open 且冷却已满 → 视作「下次调用会被放行」,不计为打开;
+        half_open 仅当探针在飞且未超时时计入。
+        """
+        with self._lock:
+            e = self._get(sid)
+            if e.state == "open":
+                return (time.time() - e.opened_at) < self.cooldown
+            if e.state == "half_open":
+                return e.probe_in_flight and (time.time() - e.probe_started_at) < self.probe_timeout
+            return False
+
+
+# ============ 生命周期钩子 ============
+
+HookEvent = Literal["before_tool_call", "after_tool_call", "on_error", "on_loop",
+                    "session_start", "agent_start", "agent_end", "session_end",
+                    "before_message_write",
+                    # 向后兼容的旧名 + E2 语义别名(内部规整为标准名)
+                    "pre_skill", "post_skill", "pre_reasoning", "task_complete"]
+
+
+@dataclass
+class Hook:
+    event: HookEvent
+    matcher: str                 # skill id / glob;'*' 匹配全部
+    handler: Callable            # 宿主提供的处理函数
+    name: str = ""
+
+    def matches(self, skill_id: str) -> bool:
+        return fnmatch.fnmatch(skill_id or "", self.matcher)
+
+
+@dataclass
+class HookResult:
+    blocked: bool = False        # 仅 pre_skill 可阻断
+    reason: str = ""
+    modified_args: Optional[dict] = None
+    additional_context: Optional[str] = None   # E2:CONTEXT_HOOKS(pre_reasoning/agent_start)注入的推理上下文
+
+
+class HookManager:
+    """生命周期钩子管理。钩子超时受限、容错、可审计。
+
+    规则(对齐 FRAMEWORK.md):
+    - 超时受限:单个 hook 超过 timeout 视为出错(不阻塞链路)
+    - 容错:hook 失败不中断 skill 链(顾问不是控制器)
+    - 例外:pre_skill 显式返回 {block:True} 可阻断(这是它被授予的权力)
+    - 可审计:每次 hook 执行记录到 audit_log
+    """
+
+    def __init__(self, timeout: float = 10.0, audit_limit: int = 2000):
+        self.timeout = timeout
+        self._hooks: list[Hook] = []
+        # 【深审修复·长期运行泄漏】audit_log 原为普通 list、只增不减:每次 skill invoke 触发
+        # pre/post/error/loop 等钩子都 append,长跑(尤其 V2 管线内 dispatch 高频用工具)无界
+        # 增长 → 内存泄漏(与 TruthCrystallizer._pending 同类)。改有界 deque:保留最近 N 条,
+        # 溢出自动丢弃最老的;deque.append 原子 ⇒ 并发 fire 也线程安全,无需额外锁。
+        self.audit_log: deque = deque(maxlen=max(100, audit_limit))
+
+    def register(self, event: HookEvent, handler: Callable,
+                 matcher: str = "*", name: str = ""):
+        from .hooks_spec import normalize_hook, is_valid_hook
+        norm = normalize_hook(event)   # 旧名(pre_skill)→ 标准名(before_tool_call)
+        if not is_valid_hook(norm):
+            # 非法钩子名(可能拼写错误)→ 记录警告,避免静默失效难以排查
+            self.audit_log.append({
+                "event": event, "hook": name or getattr(handler, "__name__", "?"),
+                "matcher": matcher, "duration_ms": 0, "timed_out": False,
+                "error": f"未知钩子点「{event}」,该钩子永不触发(请检查拼写)",
+            })
+        self._hooks.append(Hook(norm, matcher, handler, name or handler.__name__))
+
+    def _run_one(self, hook: Hook, ctx: dict) -> dict:
+        """执行单个 hook,计时 + 容错。返回 hook 的返回值(dict)或 {}。"""
+        t0 = time.time()
+        outcome, err = {}, None
+        try:
+            ret = hook.handler(ctx)
+            if isinstance(ret, dict):
+                outcome = ret
+        except Exception as e:
+            err = str(e)
+        dt = time.time() - t0
+        # 超时只记录(同步 hook 无法真正中断,但记录超时供审计)
+        timed_out = dt > self.timeout
+        self.audit_log.append({
+            "event": hook.event, "hook": hook.name, "matcher": hook.matcher,
+            "duration_ms": round(dt * 1000, 1), "timed_out": timed_out,
+            "error": err,
+        })
+        return {} if err else outcome
+
+    def fire(self, event: HookEvent, skill_id: str = "", ctx: dict = None) -> HookResult:
+        """触发某事件的所有匹配 hook。仅 before_tool_call(原 pre_skill)的 block 生效;
+        CONTEXT_HOOKS(pre_reasoning/agent_start)返回的 additional_context 会被收集拼接。
+
+        【P4-3】⚠ ctx 是**浅拷贝**(dict(...)),不是深拷贝。hook 不得原地修改 ctx 里的嵌套
+        dict(如 ctx["args"]["x"])——那会连带改掉调用方的原对象。要改参数请用返回值
+        `{"modified_args": {...}}` 整块替换(仅 before_tool_call 生效)。此处刻意不做 deepcopy,
+        以免每次工具调用都付深拷贝开销;约束靠本注释 + 钩子约定维持。
+        """
+        from .hooks_spec import (normalize_hook, BLOCKING_HOOKS, TOOL_SCOPED_HOOKS,
+                                 CONTEXT_HOOKS)
+        event = normalize_hook(event)   # 旧名/标准名统一
+        ctx = dict(ctx or {}, event=event, skill_id=skill_id)
+        result = HookResult()
+        ctx_parts = []
+        for hook in self._hooks:
+            if hook.event != event:
+                continue
+            # 工具级钩子按 skill_id 过滤(matcher)
+            if event in TOOL_SCOPED_HOOKS and not hook.matches(skill_id):
+                continue
+            out = self._run_one(hook, ctx)
+            # 仅有阻断权的钩子(before_tool_call)的 block / modified_args 生效
+            if event in BLOCKING_HOOKS:
+                if out.get("block"):
+                    result.blocked = True
+                    result.reason = out.get("reason", f"被 {event} 钩子阻断")
+                    return result
+                if out.get("modified_args") is not None:
+                    result.modified_args = out["modified_args"]
+            # 可注入上下文的钩子:收集 additional_context(兼容驼峰 additionalContext)
+            if event in CONTEXT_HOOKS:
+                inj = out.get("additional_context") or out.get("additionalContext")
+                if inj:
+                    ctx_parts.append(str(inj))
+        if ctx_parts:
+            result.additional_context = "\n".join(ctx_parts)
+        return result
+
+    def recent_audit(self, n: int = 20) -> list:
+        # deque 不支持负索引切片,先快照成 list(原子快照,并发安全)再取尾 N 条
+        return list(self.audit_log)[-n:]

package/python/foxclaw/skills/markdown_skill.py

@@ -0,0 +1,174 @@
+"""SKILL.md 指令技能:注入 Agent 提示词的 markdown 指令(非可调用工具)。无代码执行。"""
+from __future__ import annotations
+import re
+import threading
+from dataclasses import dataclass, field, asdict
+import yaml
+
+
+@dataclass
+class MarkdownSkill:
+    id: str
+    name: str
+    description: str
+    triggers: list = field(default_factory=list)
+    body: str = ""
+    enabled: bool = True
+    source: str = "user"
+    version: str = ""                                  # OpenClaw 包的版本(_meta.json/frontmatter),可空
+    builtin: bool = False                              # 随包分发的内置技能(repo skills/*/SKILL.md)
+
+    def to_dict(self) -> dict:
+        d = asdict(self); d["trust"] = "low"; return d   # 指令注入=提示词操纵面,信任=低
+
+    def to_meta(self) -> dict:
+        d = self.to_dict(); d.pop("body", None); return d
+
+
+def _slug(s: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "_", (s or "").lower()).strip("_") or "skill"
+
+
+def parse_skill_md(text: str, id: str = None) -> MarkdownSkill:
+    """解析 SKILL.md(--- yaml frontmatter --- + 正文)。缺 name/description → ValueError。"""
+    text = (text or "").lstrip("").strip()
+    m = re.match(r"^---\s*\n(.*?)\n---\s*\n?(.*)$", text, re.DOTALL)
+    if not m:
+        raise ValueError("缺少 --- frontmatter ---")
+    try:
+        fm = yaml.safe_load(m.group(1)) or {}
+    except Exception as e:
+        raise ValueError(f"frontmatter 非法 YAML: {e}")
+    if not isinstance(fm, dict):
+        raise ValueError("frontmatter 需为键值对")
+    name = str(fm.get("name") or "").strip()
+    desc = str(fm.get("description") or "").strip()
+    if not name or not desc:
+        raise ValueError("SKILL.md 必须含 name 和 description")
+    trig = fm.get("triggers") or []
+    if isinstance(trig, str):
+        trig = [t.strip() for t in trig.split(",") if t.strip()]
+    trig = [str(t) for t in trig]
+    builtin = bool(fm.get("builtin", False))
+    return MarkdownSkill(id=id or _slug(name), name=name, description=desc,
+                         triggers=trig, body=m.group(2).strip(),
+                         source="builtin" if builtin else "user",
+                         version=str(fm.get("version") or "").strip(),
+                         builtin=builtin)
+
+
+def load_builtin_dir(reg: MarkdownSkillRegistry, root) -> list:
+    """加载随包分发的指令技能:`<root>/<name>/SKILL.md` 中 **frontmatter 标了 builtin: true** 的。
+
+    为什么只认 builtin 标记:仓库 `skills/` 下还有 `execution-contract` 之类的**开发者文档**,
+    全量注入会把每轮 prompt 撑肿。显式标记 = 只把"真给模型执行的指令"注入。
+    用户已安装的同 id 技能优先(不覆盖),内置只是缺省值。
+    """
+    from pathlib import Path
+    loaded = []
+    try:
+        base = Path(root)
+        if not base.is_dir():
+            return loaded
+        for p in sorted(base.glob("*/SKILL.md")):
+            try:
+                s = parse_skill_md(p.read_text(encoding="utf-8", errors="replace"))
+            except Exception:
+                continue                   # 单个技能坏掉不影响其余
+            if not s.builtin or reg.get(s.id) is not None:
+                continue
+            reg.register(s)
+            loaded.append(s.id)
+    except Exception:
+        pass
+    return loaded
+
+
+class MarkdownSkillRegistry:
+    def __init__(self):
+        self._skills = {}
+        self._lock = threading.RLock()
+        self.policy = None                     # 全局封杀策略(宿主注入);被封的不参与注入
+
+    def register(self, s: MarkdownSkill):
+        with self._lock:
+            self._skills[s.id] = s
+
+    def unregister(self, sid: str) -> bool:
+        with self._lock:
+            return self._skills.pop(sid, None) is not None
+
+    def get(self, sid: str):
+        with self._lock:
+            return self._skills.get(sid)
+
+    def all(self) -> list:
+        with self._lock:
+            return list(self._skills.values())
+
+    def catalog(self) -> list:
+        return [s.to_meta() for s in self.all()]
+
+    def match(self, task: str) -> list:
+        """有 triggers → 按 triggers(子串);无 triggers(原味 OpenClaw)→ 按 name+description 描述相关。"""
+        t_raw = task or ""
+        t_low = t_raw.lower()
+        out = []
+        pol = self.policy
+        for s in self.all():
+            if not s.enabled:
+                continue
+            if pol is not None and pol.is_blocked(s.id):
+                continue                       # 被封杀 → 不注入(kill-switch)
+            if s.triggers:
+                if any(k.lower() in t_low for k in s.triggers):
+                    out.append(s)
+            elif _desc_relevant(s, t_low, t_raw):
+                out.append(s)
+        return out
+
+
+_ASCII_WORD = re.compile(r"[a-z0-9]{3,}")
+_CJK_RUN = re.compile(r"[一-鿿]{2,}")
+
+
+def _desc_relevant(skill, t_low: str, t_raw: str) -> bool:
+    """无 triggers 时:技能 name+description 与任务是否关键词重叠。
+    ASCII 词按词边界(避免 knowledge⊃now 式误命中);中文按 2-gram 子串。"""
+    blob = f"{skill.name} {skill.description}"
+    for w in set(_ASCII_WORD.findall(blob.lower())):
+        if re.search(rf"\b{re.escape(w)}\b", t_low):
+            return True
+    for run in _CJK_RUN.findall(blob):
+        for i in range(len(run) - 1):
+            if run[i:i + 2] in t_raw:
+                return True
+    return False
+
+
+def extract_skill_package(zip_bytes: bytes, max_uncompressed: int = 2_000_000):
+    """从 OpenClaw 包(zip)按名读取 SKILL.md(+可选 _meta.json)。
+    仅按名 read,不 extractall → 无 zip-slip;累计解压超上限 → 防 zip bomb。
+    返回 (skill_md_text, meta_dict)。找不到 SKILL.md → ValueError。"""
+    import io
+    import json as _json
+    import zipfile
+    try:
+        zf = zipfile.ZipFile(io.BytesIO(zip_bytes))
+    except Exception as e:
+        raise ValueError(f"不是合法 zip: {e}")
+    total = sum(i.file_size for i in zf.infolist())
+    if total > max_uncompressed:
+        raise ValueError(f"解压体积超上限({total} > {max_uncompressed})")
+    skill_name = next((n for n in zf.namelist() if n.lower().endswith("skill.md")), None)
+    if not skill_name:
+        raise ValueError("包内未找到 SKILL.md")
+    skill_md = zf.read(skill_name).decode("utf-8", "replace")
+    meta = {}
+    meta_name = next((n for n in zf.namelist() if n.lower().endswith("_meta.json")), None)
+    if meta_name:
+        try:
+            meta = _json.loads(zf.read(meta_name).decode("utf-8", "replace")) or {}
+        except Exception:
+            meta = {}
+    return skill_md, meta

package/python/foxclaw/skills/markdown_store.py

@@ -0,0 +1,39 @@
+"""SKILL.md 指令技能持久化。<data_dir>/markdown_skills.json。"""
+from __future__ import annotations
+import json
+import threading
+from pathlib import Path
+from dataclasses import fields as _fields
+
+from .markdown_skill import MarkdownSkill, MarkdownSkillRegistry
+
+
+class MarkdownStore:
+    def __init__(self, data_dir):
+        self._path = Path(data_dir) / "markdown_skills.json"
+        self._lock = threading.Lock()
+
+    def load(self, reg: MarkdownSkillRegistry):
+        if not self._path.exists():
+            return
+        try:
+            data = json.loads(self._path.read_text(encoding="utf-8"))
+        except Exception:
+            return
+        allowed = {f.name for f in _fields(MarkdownSkill)}
+        for d in data.get("skills", []):
+            try:
+                reg.register(MarkdownSkill(**{k: v for k, v in d.items() if k in allowed}))
+            except Exception:
+                continue
+
+    def save(self, reg: MarkdownSkillRegistry):
+        with self._lock:
+            payload = {"skills": [s.to_dict() for s in reg.all()]}
+            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