foxclaw 0.1.2 → 0.1.4

package/python/foxclaw/cli.py

@@ -7,6 +7,8 @@
     foxclaw serve          # 启动 API 服务(默认 http://127.0.0.1:8000)
     foxclaw config check   # 检查 .env / 环境变量:类型写错、拼错的键、互相矛盾的组合
     foxclaw config show     # 打印当前生效配置(密钥默认脱敏)
+    foxclaw skills install @owner/slug   # 装 SKILL.md 技能(ClawHub/GitHub/URL/本地包)
+    foxclaw skills list                  # 列出已装技能
     foxclaw --version      # 打印版本
 
 `serve` 用字符串目标 `foxclaw.api:app` 交给 uvicorn 导入,避免 CLI 进程
@@ -34,8 +36,6 @@ def _repo_root() -> Path:
 def _cmd_serve(args: argparse.Namespace) -> int:
     from foxclaw.core import settings
 
-    # 启动前先查配置:类型写错的值今天会崩在很远的地方(uvicorn 40 行 traceback 中间的
-    # `int()`),用户看不出是自己 .env 写错了。这里提前拦下并说清怎么改。
     issues = settings.check()
     fatal = settings.fatal_issues(issues)
     if fatal:
@@ -43,22 +43,19 @@ def _cmd_serve(args: argparse.Namespace) -> int:
         print("\n以上配置会让启动直接失败,已中止。改好后重试。", file=sys.stderr)
         return 2
     if issues:
-        # 不影响启动的问题(可疑但能跑)只提醒一次,不拦
         print(settings.format_issues(issues, limit=8), file=sys.stderr)
         print("(以上不阻断启动;`foxclaw config check` 看完整诊断)", file=sys.stderr)
 
     import uvicorn
 
-    kwargs: dict[str, object] = {
-        "host": args.host,
-        "port": args.port,
-        "log_level": args.log_level,
-    }
-    if args.reload:
-        # 只监听源码目录,避免 vendor/ 与测试临时文件触发重启
-        kwargs["reload"] = True
-        kwargs["reload_dirs"] = [str(_repo_root() / "foxclaw")]
-    uvicorn.run(APP_TARGET, **kwargs)
+    uvicorn.run(
+        APP_TARGET,
+        host=args.host,
+        port=args.port,
+        log_level=args.log_level,
+        reload=bool(args.reload),
+        reload_dirs=[str(_repo_root() / "foxclaw")] if args.reload else None,
+    )
     return 0
 
 
@@ -97,6 +94,12 @@ def _cmd_config_show(args: argparse.Namespace) -> int:
     return 0
 
 
+def _cmd_skills(args: argparse.Namespace) -> int:
+    from foxclaw.skills.install_cmd import run
+
+    return run(args)
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="foxclaw",
@@ -131,6 +134,28 @@ def build_parser() -> argparse.ArgumentParser:
                         help="显示密钥原文(默认脱敏;别在截图/日志里用)")
     c_show.set_defaults(handler=_cmd_config_show)
 
+    skills = subparsers.add_parser("skills", help="安装/查看/卸载指令技能(SKILL.md)")
+    skills_sub = skills.add_subparsers(dest="skills_action", metavar="<action>")
+
+    s_install = skills_sub.add_parser("install", help="从 ClawHub/GitHub/URL/本地包装一个技能")
+    s_install.add_argument(
+        "ref",
+        help="@owner/slug(ClawHub) | github:owner/repo[/子路径][@ref] | "
+             "http(s)://包地址 | 本地 .zip/.tar.gz/SKILL.md/目录")
+    s_install.add_argument("--yes", action="store_true",
+                           help="跳过确认(脚本/CI 必填;非终端环境没有它一定失败)")
+    s_install.add_argument("--id", default="", help="覆盖技能 id(默认取 SKILL.md 里的 name)")
+    s_install.add_argument("--json", action="store_true", help="输出 JSON")
+    s_install.set_defaults(handler=_cmd_skills)
+
+    s_list = skills_sub.add_parser("list", help="列出已安装的指令技能")
+    s_list.add_argument("--json", action="store_true", help="输出 JSON")
+    s_list.set_defaults(handler=_cmd_skills)
+
+    s_remove = skills_sub.add_parser("remove", help="卸载一个指令技能")
+    s_remove.add_argument("id", help="技能 id(`foxclaw skills list` 第一列)")
+    s_remove.set_defaults(handler=_cmd_skills)
+
     return parser
 
 
@@ -143,6 +168,10 @@ def main(argv: list[str] | None = None) -> int:
         if getattr(args, "command", None) == "config":
             print("用法:`foxclaw config check` 或 `foxclaw config show`")
             return 2
+        if getattr(args, "command", None) == "skills":
+            print("用法:`foxclaw skills install <ref>` / `foxclaw skills list` / "
+                  "`foxclaw skills remove <id>`")
+            return 2
         print(f"foxclaw {__version__}")
         print("用 `foxclaw serve` 启动本地服务;`foxclaw config check` 检查配置;"
               "`foxclaw --help` 查看全部子命令。")

package/python/foxclaw/cognitive/reasoner.py

@@ -15,10 +15,10 @@ from typing import Any
 
 @dataclass
 class Evidence:
-    factor: str                 # 证据因子(如规则 id / 历史频率 / 预算余量)
-    detail: str = ""            # 具体说明
-    weight: float = 1.0         # 权重(0~1)
-    raw: Any = None             # 原始证据对象(如 PolicyVerdict),供裁决内部使用
+    factor: str
+    detail: str = ""
+    weight: float = 1.0
+    raw: Any = None
 
     def to_dict(self) -> dict:
         return {"factor": self.factor, "detail": self.detail, "weight": self.weight}
@@ -26,11 +26,11 @@ class Evidence:
 
 @dataclass
 class ReasonedVerdict:
-    decision: str               # approve | confirm | reject
-    rationale: str              # 裁决说明(人类可读)
-    evidence: list = field(default_factory=list)      # [Evidence]
-    hypotheses: list = field(default_factory=list)    # [str]
-    source: str = "rules"       # rules | llm(哪层做出的裁决)
+    decision: str
+    rationale: str
+    evidence: list = field(default_factory=list)
+    hypotheses: list = field(default_factory=list)
+    source: str = "rules"
 
     def to_dict(self) -> dict:
         return {"decision": self.decision, "rationale": self.rationale,
@@ -61,7 +61,6 @@ class DomainReasoner:
         ev = self.gather_evidence(subject, obs)
         return self.arbitrate(subject, obs, hyps, ev)
 
-    # ── 双层增强的通用工具(v2 ③ Step4:itinerary/learning 复用)────────────
     @staticmethod
     def llm_available(llm, enabled: bool) -> bool:
         """LLM 是否真正可用:启用 + 非空 + 非 stub(无真实模型时视为不可用)。"""

package/python/foxclaw/cognitive/state.py

@@ -10,6 +10,8 @@
 可驱动前端"系统在想什么"实时面板,也用于调试与回放。
 """
 from __future__ import annotations
+
+from typing import Optional
 import time
 from dataclasses import dataclass, field
 
@@ -18,19 +20,18 @@ from dataclasses import dataclass, field
 class CognitiveState:
     """系统当前认知状态快照。随事件总线上的活动自动更新。"""
 
-    active_goal: str = None                          # 当前活跃目标(最近任务)
-    active_agent: str = None                         # 当前处理的 Agent
-    semantic_focus: str = None                       # 语义焦点(调度意图类别)
-    attention_scope: list = field(default_factory=list)   # 注意力范围(关键词)
-    reasoning_depth: float = 0.0                     # 当前推理深度
-    confidence_map: dict = field(default_factory=dict)    # 置信度图(意图/优先级)
-    activated_memories: list = field(default_factory=list)  # 激活的记忆(最近召回/沉淀)
-    last_route: str = None                           # 最近路由倾向
-    active_processes: int = 0                         # 活跃进程数
-    temporal_window: str = "current_turn"            # 时间窗口
+    active_goal: Optional[str] = None
+    active_agent: Optional[str] = None
+    semantic_focus: Optional[str] = None
+    attention_scope: list = field(default_factory=list)
+    reasoning_depth: float = 0.0
+    confidence_map: dict = field(default_factory=dict)
+    activated_memories: list = field(default_factory=list)
+    last_route: Optional[str] = None
+    active_processes: int = 0
+    temporal_window: str = "current_turn"
     updated_at: float = field(default_factory=time.time)
 
-    # ── 信号摄入(由事件驱动)──
 
     def on_execution(self, payload: dict):
         """执行事件 → 更新目标/Agent/注意力。"""
@@ -54,13 +55,12 @@ class CognitiveState:
         content = mu.get("content")
         if content:
             snippet = content[:80]
-            # 去重:已存在则先移除旧的,再插到最前(LRU 式)
             existing = [m for m in self.activated_memories if m != snippet]
             self.activated_memories = [snippet] + existing[:4]
             self.temporal_window = "memory_augmented"
         self.updated_at = time.time()
 
-    def on_process_change(self, payload: dict, active_count: int = None):
+    def on_process_change(self, payload: dict, active_count: int | None = None):
         """进程状态变更 → 更新活跃进程数。"""
         if active_count is not None:
             self.active_processes = active_count
@@ -69,14 +69,12 @@ class CognitiveState:
     @staticmethod
     def _keywords(text: str, n: int = 6) -> list:
         import re
-        # 先按标点/空格切;若切出的片段仍很长(中文无空格),按 2-4 字滑窗取要点
         rough = [w for w in re.split(r"[\s,，、。!?:;]", text or "") if len(w) >= 2]
         out = []
         for seg in rough:
             if len(seg) <= 4:
                 out.append(seg)
             else:
-                # 长片段取首尾 + 中部双字,作为注意力要点
                 out.append(seg[:3])
                 if len(seg) > 6:
                     out.append(seg[len(seg)//2:len(seg)//2+2])
@@ -106,25 +104,23 @@ class CognitiveStateTracker:
         import threading
         self.state = CognitiveState()
         self.process_manager = process_manager
-        self._lock = threading.Lock()   # 事件可能跨线程触发,保护状态更新
+        self._lock = threading.Lock()
         if bus is not None:
-            # 【P4-1】前两个是精确 channel 名 → exact=True;task.lifecycle 是刻意的前缀
-            # 订阅(收 created/queued/running/... 一族),保持默认前缀匹配。
             bus.subscribe("execution.completed", self._on_exec, exact=True)
             bus.subscribe("memory.updated", self._on_mem, exact=True)
-            bus.subscribe("task.lifecycle", self._on_proc)   # Step3:统一生命周期词汇(前缀匹配)
+            bus.subscribe("task.lifecycle", self._on_proc)
 
     def _on_exec(self, msg):
         if msg is None:
             return
         with self._lock:
-            self.state.on_execution(getattr(msg, "payload", None))
+            self.state.on_execution(getattr(msg, "payload", None) or {})
 
     def _on_mem(self, msg):
         if msg is None:
             return
         with self._lock:
-            self.state.on_memory_updated(getattr(msg, "payload", None))
+            self.state.on_memory_updated(getattr(msg, "payload", None) or {})
 
     def _on_proc(self, msg):
         if msg is None:
@@ -132,15 +128,13 @@ class CognitiveStateTracker:
         active = None
         pm = self.process_manager
         if pm is not None:
-            # 【深审优化】用 pm 的 O(1) active_count(),免去每次 lifecycle 事件 stats() 遍历
-            # 全部进程(O(n))。旧 pm 无此方法则回退到 stats()(scheduled+running)。
             if hasattr(pm, "active_count"):
                 active = pm.active_count()
             else:
                 st = pm.stats().get("by_state", {})
                 active = st.get("scheduled", 0) + st.get("running", 0)
         with self._lock:
-            self.state.on_process_change(getattr(msg, "payload", None), active)
+            self.state.on_process_change(getattr(msg, "payload", None) or {}, active)
 
     def snapshot(self) -> dict:
         with self._lock:

package/python/foxclaw/core/audit_chain.py

@@ -28,10 +28,8 @@ import hashlib
 import json
 from pathlib import Path
 
-#: 首条记录的 prev_hash。用 64 个 0 而不是空串:一眼能看出「这是链头」。
 GENESIS = "0" * 64
 
-#: 从文件尾部回读的字节数:找 tail hash 只需最后一行,64KB 足够容下超长记录。
 _TAIL_WINDOW = 65536
 
 
@@ -100,7 +98,7 @@ def verify(path) -> tuple:
                     return False, n, f"第 {i} 行不是合法 JSON"
                 h = rec.get("hash")
                 if not h:
-                    continue                      # legacy 段:无链可验,跳过
+                    continue
                 if rec.get("prev_hash") != prev:
                     return False, n, (f"第 {i} 行链断:prev_hash 与上一条 hash 不符"
                                       "(中间记录被删或被挪动)")

package/python/foxclaw/core/audit_sink.py

@@ -50,10 +50,10 @@ class SharedWriteAuditSink:
     def __init__(self, path: Path):
         self.path = Path(path)
         self._lock = threading.Lock()
-        self._last_hash: str | None = None    # 链尾,首次写时从文件尾部补齐
+        self._last_hash: str | None = None
         self.path.parent.mkdir(parents=True, exist_ok=True)
 
-    def __call__(self, evt):  # EventSpine.subscribe 的 handler 形态:handler(event)
+    def __call__(self, evt):
         try:
             rec = {
                 "ts": datetime.now().isoformat(timespec="seconds"),
@@ -69,7 +69,7 @@ class SharedWriteAuditSink:
                     f.write(json.dumps(rec, ensure_ascii=False, default=str) + "\n")
                 self._last_hash = rec["hash"]
         except Exception:
-            pass  # 审计失败绝不影响写入主流程
+            pass
 
     def read(self, limit: int = 200) -> list:
         """读最近 limit 条(供诊断/工具用)。坏行跳过 —— 落盘绝不该反过来卡死读取。"""

package/python/foxclaw/core/compaction.py

@@ -25,7 +25,6 @@ import re
 from dataclasses import dataclass, field
 
 
-# 粗略 token 估算:中文约 1 字符 ≈ 1 token,英文约 4 字符 ≈ 1 token。
 def estimate_tokens(text: str) -> int:
     if not text:
         return 0
@@ -38,8 +37,6 @@ def estimate_messages_tokens(messages: list) -> int:
     return sum(estimate_tokens(str(m.get("content", ""))) for m in messages)
 
 
-# 关键标识符:不能在摘要中丢失的(ID、长数字、订单号、哈希、金额等)
-# 不用外层 \b:¥/逗号不是单词字符,会导致金额匹配失败。
 _IDENTIFIER_PAT = re.compile(
     r"[a-zA-Z]{2,}_[a-zA-Z0-9]{4,}|[a-f0-9]{8,}|[0-9]{6,}|¥[\d,]+(?:\.\d+)?")
 
@@ -56,14 +53,14 @@ def extract_identifiers(messages: list) -> list[str]:
 
 @dataclass
 class CompactionResult:
-    messages: list = field(default_factory=list)     # 压缩后的消息列表
-    method: str = "none"                             # llm_summary/partial_summary/truncate/none
+    messages: list = field(default_factory=list)
+    method: str = "none"
     original_count: int = 0
     compacted_count: int = 0
     original_tokens: int = 0
     compacted_tokens: int = 0
     preserved_identifiers: list = field(default_factory=list)
-    note: str = ""                                   # 说明(如压缩跳过原因)
+    note: str = ""
 
     def to_dict(self) -> dict:
         return {
@@ -101,8 +98,6 @@ def group_tool_calls(messages: list) -> list:
         m = messages[i]
         buf.append(m)
         if m.get("role") == "assistant" and (m.get("tool_calls") or []):
-            # 本 assistant 声明了工具调用 → 把紧随其后、id 匹配的 tool 结果
-            # 全部并入同一组,确保「声明与结果同进同出」。
             ids = {tc.get("id") for tc in (m.get("tool_calls") or [])}
             j = i + 1
             while j < n:
@@ -125,10 +120,10 @@ class Compactor:
 
     def __init__(self, router=None, max_tokens: int = 6000,
                  keep_recent: int = 4, oversized_token: int = 2000):
-        self.router = router                 # ModelRouter,用于 LLM 摘要(可空→走截断兜底)
-        self.max_tokens = max_tokens         # 超过此 token 触发压缩
-        self.keep_recent = keep_recent       # 最近保留几条原样
-        self.oversized_token = oversized_token  # 单条超此值视为"超大消息"
+        self.router = router
+        self.max_tokens = max_tokens
+        self.keep_recent = keep_recent
+        self.oversized_token = oversized_token
 
     def needs_compaction(self, messages: list) -> bool:
         return estimate_messages_tokens(messages) > self.max_tokens
@@ -146,13 +141,9 @@ class Compactor:
             res.compacted_tokens = res.original_tokens
             return res
 
-        # 分区:系统消息 / 待压缩的早期消息 / 保留的近期消息
         system_msgs = [m for m in messages if m.get("role") == "system"]
         non_system = [m for m in messages if m.get("role") != "system"]
         keep = max(0, self.keep_recent)
-        # 按**原子组**保留(而非按条数),保证 assistant.tool_calls 与其 tool 结果
-        # 同进同出。按条数切会在「一轮多工具」时把 tool 结果与其声明切散 →
-        # provider 报 400。详见 group_tool_calls docstring。
         _groups = group_tool_calls(non_system)
         if keep and _groups:
             recent = [m for g in _groups[-keep:] for m in g]
@@ -161,8 +152,6 @@ class Compactor:
             recent, to_compress = [], non_system
         else:
             recent, to_compress = [], non_system
-        # 防御:若仍不配对(极端边界/上游已产生的畸形序列),宁可放弃压缩,
-        # 也不产出非法消息序列 —— 压缩不生效只是浪费 token,发出去 400 是整轮失败。
         _declared = {tc.get("id") for m in (recent + to_compress)
                      for tc in (m.get("tool_calls") or [])}
         _orphans = [m for m in (recent + to_compress)
@@ -185,15 +174,12 @@ class Compactor:
 
         res.preserved_identifiers = extract_identifiers(to_compress)
 
-        # —— 渐进降级 ——
         summary = None
         method = "truncate"
-        # 1. LLM 完整摘要
         if self.router is not None:
             summary = self._try_summarize(to_compress, res.preserved_identifiers)
             if summary:
                 method = "llm_summary"
-        # 2. 部分摘要:排除超大消息后再试
         if summary is None and self.router is not None:
             trimmed = [m for m in to_compress
                        if estimate_tokens(str(m.get("content", ""))) <= self.oversized_token]
@@ -201,7 +187,6 @@ class Compactor:
                 summary = self._try_summarize(trimmed, res.preserved_identifiers)
                 if summary:
                     method = "partial_summary"
-        # 3. 截断兜底
         if summary is None:
             summary = self._truncate_fallback(to_compress, res.preserved_identifiers)
             method = "truncate"
@@ -211,14 +196,11 @@ class Compactor:
         compacted = system_msgs + [summary_msg] + recent
         compacted_tokens = estimate_messages_tokens(compacted)
 
-        # 校验:压缩须真的显著变小(至少省 10%),否则放弃——避免系统消息过大时
-        # 压缩无效还白加摘要导致反而更大。
         if compacted_tokens >= res.original_tokens * 0.9:
             res.messages = list(messages)
             res.method = "skipped_ineffective"
             res.compacted_count = len(messages)
             res.compacted_tokens = res.original_tokens
-            # 提示:压缩无效通常因系统消息/近期消息本身已占满预算
             sys_tokens = estimate_messages_tokens(system_msgs)
             res.note = (f"压缩跳过:有效压缩空间不足(系统消息占 {sys_tokens} token)。"
                         f"建议精简系统提示或调大上下文预算。")
@@ -242,7 +224,7 @@ class Compactor:
                 return list(messages), None
             res = self.compact(messages)
             if res.method == "none" or res.method.startswith("skipped"):
-                return list(messages), res      # 压缩没生效 → 原样,结果仅用于观测
+                return list(messages), res
             return res.messages, res
         except Exception:
             return list(messages), None

package/python/foxclaw/core/config.py

@@ -22,7 +22,7 @@ class LayeredConfig:
     """三层配置合并原语。持有各层 dict 的引用 —— 若某层的集合值是可变对象(如 SkillPolicy 的
     user deny set),原地增删会被 merged_set/policy_locked 实时反映,无需重建。"""
 
-    def __init__(self, policy: dict = None, user: dict = None, runtime: dict = None):
+    def __init__(self, policy: dict | None = None, user: dict | None = None, runtime: dict | None = None):
         self.policy = dict(policy or {})
         self.user = dict(user or {})
         self.runtime = dict(runtime or {})
@@ -61,5 +61,5 @@ def load_policy_layer(data_dir=None) -> dict:
                 d = json.loads(p.read_text(encoding="utf-8"))
                 deny |= set(d.get("deny") or [])
             except Exception:
-                pass          # policy.json 损坏不应拖垮启动;宁可少锁不错锁,由运维排查
+                pass
     return {"deny": sorted(deny)}

package/python/foxclaw/core/confirm_nonce.py

@@ -25,10 +25,9 @@ import time
 from dataclasses import dataclass, field
 from typing import Optional, Tuple
 
-#: 视为「关键操作」的副作用级别(发送/支付);destructive 无条件算关键
 CRITICAL_SIDE_EFFECTS = ("send", "pay")
 
-DEFAULT_TTL = 300.0        # 秒;确认码有效期
+DEFAULT_TTL = 300.0
 
 
 def action_fingerprint(action: str, args: dict) -> str:
@@ -78,14 +77,13 @@ class ConfirmationBroker:
         self._items: dict[str, PendingConfirm] = {}
         self._lock = threading.Lock()
 
-    # ── 签发 ────────────────────────────────────────────
     def issue(self, session: str, action: str, args: dict,
-              ttl: float = None) -> dict:
+              ttl: float | None = None) -> dict:
         """签发一个绑定到 (会话, 动作, 参数) 的一次性确认码。"""
         now = self._clock()
         ttl = self.ttl if ttl is None else float(ttl)
         item = PendingConfirm(
-            nonce=secrets.token_hex(8),          # 16 hex 字符,人类也能念出来
+            nonce=secrets.token_hex(8),
             action=action or "",
             fingerprint=action_fingerprint(action or "", args or {}),
             session=session or "",
@@ -99,9 +97,8 @@ class ConfirmationBroker:
         return {"nonce": item.nonce, "action": item.action,
                 "expires_at": item.expires, "ttl": ttl}
 
-    # ── 校验并消费 ──────────────────────────────────────
     def consume(self, session: str, nonce: str, action: str = "",
-                args: dict = None, now: float = None) -> Tuple[bool, str]:
+                args: dict | None = None, now: float | None = None) -> Tuple[bool, str]:
         """校验确认码并**立即作废**。返回 (是否通过, 原因码)。
 
         原因码:``ok`` / ``missing_nonce`` / ``unknown_nonce`` / ``already_used`` /
@@ -113,8 +110,6 @@ class ConfirmationBroker:
         now = now if now is not None else self._clock()
         with self._lock:
             item: Optional[PendingConfirm] = self._items.get(nonce)
-            # 先看这一条再清理:否则过期的码会被 _purge 抹掉,排错时只会看到
-            # unknown_nonce,分不清"从没发过"和"发过但过期了"
             if item is not None and item.expires <= now:
                 self._items.pop(nonce, None)
                 return False, "expired"
@@ -130,10 +125,9 @@ class ConfirmationBroker:
             if args is not None and item.fingerprint != action_fingerprint(item.action, args):
                 return False, "args_mismatch"
             item.used = True
-            self._items.pop(nonce, None)     # 单次使用:消费即删
+            self._items.pop(nonce, None)
             return True, "ok"
 
-    # ── 观测 ────────────────────────────────────────────
     def pending(self, session: str = "") -> list:
         """未消费且未过期的确认码(可按会话过滤),供排查/前端展示。"""
         now = self._clock()
@@ -142,7 +136,7 @@ class ConfirmationBroker:
             return [it.to_dict() for it in self._items.values()
                     if not it.used and (not session or it.session == session)]
 
-    def purge(self, now: float = None) -> int:
+    def purge(self, now: float | None = None) -> int:
         now = now if now is not None else self._clock()
         with self._lock:
             return self._purge_locked(now)