foxclaw 0.1.2 → 0.1.4

package/python/foxclaw/core/settings.py

@@ -45,8 +45,6 @@ from functools import lru_cache
 from pathlib import Path
 from typing import Any, Iterable, Mapping, Sequence
 
-# provider → 需要的环境变量(与 core/model_router.PROVIDER_ENV 保持一致;
-# 这里重复一份是为了让 settings 不依赖 model_router —— 那会拖入 LLM SDK 的导入)。
 PROVIDER_KEY_ENV: dict[str, str] = {
     "anthropic": "ANTHROPIC_API_KEY",
     "openai": "OPENAI_API_KEY",
@@ -58,8 +56,6 @@ PROVIDER_KEY_ENV: dict[str, str] = {
     "generic": "LLM_API_KEY",
 }
 
-# 只检查这些前缀下的"未知键":它们属于本项目或本项目专用的厂商约定,
-# 出现没人读的名字几乎必然是拼错。像 `PATH` / `HOME` 这类系统变量不在此列。
 OWNED_PREFIXES = (
     "FOXCLAW_", "BAIDU_", "AMAP_", "LLM_", "GENERIC_LLM_",
     "MINIMAX_", "LOCAL_LLM_", "HKC_", "HMR_",
@@ -75,10 +71,10 @@ class Opt:
     """一个环境变量的声明。kind 只描述**解析方式**,不代表业务语义。"""
 
     name: str
-    kind: str = "str"                  # str | int | float | csv | choice
+    kind: str = "str"
     default: Any = ""
     group: str = "其他"
-    hint: str = ""                     # 期望格式 / 示例(拼进出错信息)
+    hint: str = ""
     choices: Sequence[str] = ()
     secret: bool = False
     lo: float | None = None
@@ -86,10 +82,6 @@ class Opt:
 
 
 SPECS: tuple[Opt, ...] = (
-    # lo/hi 只给**调用点自己不兜底**的项。像 TRACE_RETAIN 已有 max(100, ...)、
-    # BAIDU_SEARCH_TIMEOUT 已有 max(5, ...):在那里再报一次范围错,等于把"clamp"
-    # 变成"整条配置作废退默认",反而更糟。
-    # ── 模型 ────────────────────────────────────────────────────────────────
     Opt("LLM_PROVIDER", "choice", "", "模型",
         "anthropic / openai / deepseek / google / qwen / local / minimax / generic",
         tuple(PROVIDER_KEY_ENV)),
@@ -109,9 +101,10 @@ SPECS: tuple[Opt, ...] = (
     Opt("LLM_API_KEY", "str", "", "模型", "generic(通用 openai 兼容)的 key", secret=True),
     Opt("LLM_BASE_URL", "str", "", "模型", "generic 的 base_url,如 https://host/v1"),
     Opt("LOCAL_LLM_BASE", "str", "", "模型", "本地推理服务的 base_url"),
-    # ── 服务 ────────────────────────────────────────────────────────────────
     Opt("FOXCLAW_PORT", "int", 8000, "服务", "HTTP 监听端口", lo=1, hi=65535),
     Opt("FOXCLAW_DATA_DIR", "str", "", "服务", "数据目录(默认 <仓库>/foxclaw_data)"),
+    Opt("FOXCLAW_CLAWHUB_REGISTRY", "str", "", "服务",
+        "ClawHub 地址(默认 https://clawhub.ai;内网镜像或自建 registry 填这里)"),
     Opt("FOXCLAW_IMPORT_ROOTS", "csv", "", "服务",
         "额外允许的导入目录(逗号分隔);不配则只有数据目录内的文件可被导入"),
     Opt("FOXCLAW_API_KEY", "str", "", "服务",
@@ -127,7 +120,6 @@ SPECS: tuple[Opt, ...] = (
     Opt("FOXCLAW_STREAM_RATE", "int", 60, "服务", "流式端点每分钟上限", lo=0),
     Opt("FOXCLAW_STREAM_CONCURRENCY", "int", 4, "服务", "流式并发上限", lo=1),
     Opt("FOXCLAW_SHADOW_ROUNDS", "int", 20, "服务", "影子推演轮数", lo=1),
-    # ── 工具 / 追踪 ─────────────────────────────────────────────────────────
     Opt("FOXCLAW_TOOL_TIMEOUT", "float", 45.0, "工具",
         "单个工具调用硬超时(秒);可小于 1(测试用),调用点会兜 >0"),
     Opt("FOXCLAW_TRACE_SLOW_MS", "float", 1000.0, "追踪", "超过多少毫秒算慢请求", lo=0),
@@ -135,12 +127,10 @@ SPECS: tuple[Opt, ...] = (
         "非慢请求的采样率 0~1;超出范围由调用点 clamp,不在这里报错"),
     Opt("FOXCLAW_TRACE_RETAIN", "int", 5000, "追踪",
         "内存里保留的 trace 条数;调用点已有 max(100, ...) 兜底"),
-    # ── 搜索 ────────────────────────────────────────────────────────────────
     Opt("BAIDU_SEARCH_KEY", "str", "", "搜索", "百度 AI 搜索的 key", secret=True),
     Opt("BAIDU_SEARCH_MODEL", "str", "", "搜索", "百度搜索用的模型名"),
     Opt("BAIDU_SEARCH_BASE", "str", "", "搜索", "百度搜索的 base_url"),
     Opt("BAIDU_SEARCH_TIMEOUT", "int", 45, "搜索", "秒;调用点已有 max(5, ...) 兜底"),
-    # ── 渠道 ────────────────────────────────────────────────────────────────
     Opt("FOXCLAW_CHANNEL_TRUSTED_SENDERS", "csv", "", "渠道",
         "逗号分隔的可信发送者:<id> / <channel>:<id> / <channel>:*"),
     Opt("FOXCLAW_CHANNEL_TRUST_ALL", "str", "", "渠道",
@@ -148,27 +138,24 @@ SPECS: tuple[Opt, ...] = (
     Opt("FOXCLAW_CHANNEL_SIGNING_SECRET", "str", "", "渠道",
         "出站 HMAC 密钥;留空 = 不签", secret=True),
     Opt("FOXCLAW_CHANNEL_SIGNING_KEY_ID", "str", "", "渠道", "密钥轮换标识"),
-    # ── 浏览器 ──────────────────────────────────────────────────────────────
     Opt("FOXCLAW_BROWSER_ALLOW_PRIVATE", "str", "", "浏览器",
         "1/true/yes 才允许访问内网地址"),
 )
 
 SPEC_BY_NAME: dict[str, Opt] = {o.name: o for o in SPECS}
 
-# 会在启动/运行早期被读、且类型写错就会崩的少数几个 —— 供 serve 预检快速拦截。
 FATAL_CODES = ("type", "choice", "range")
 
 
 @dataclass
 class Issue:
-    level: str                 # "error" | "warn"
-    code: str                  # type / choice / range / provider_key / unknown_key ...
+    level: str
+    code: str
     name: str
     message: str
-    hint: str = ""             # 修复建议(可为空)
+    hint: str = ""
 
     def __str__(self) -> str:
-        # 只用 ASCII 记号:Windows 控制台默认 GBK,✓/✗/⚠ 会抛 UnicodeEncodeError
         mark = "ERROR" if self.level == "error" else " WARN"
         head = f"[{mark}] {self.name}: {self.message}" if self.name else f"[{mark}] {self.message}"
         return f"{head}\n          → {self.hint}" if self.hint else head
@@ -178,7 +165,7 @@ def _caller() -> str:
     """当前 `get_*` 的调用点(文件:行)。只在出错路径上求值,不进热路径。"""
     try:
         f = inspect.currentframe()
-        for _ in range(3):                      # 跳过 get_* → _parse → _caller 自身
+        for _ in range(3):
             if f is None:
                 return ""
             f = f.f_back
@@ -210,16 +197,16 @@ def _parse(opt: Opt, raw: str, where: str = "") -> Any:
         return value
 
     if opt.kind == "choice":
-        value = text.lower()
-        if value not in opt.choices:
+        choice = text.lower()
+        if choice not in opt.choices:
             raise ConfigError(
                 f'值 "{raw}" 不在允许范围内。可选:{" / ".join(opt.choices)}{suffix}')
-        return value
+        return choice
 
     if opt.kind == "csv":
         return [s.strip() for s in text.split(",") if s.strip()]
 
-    return raw                                  # str:保留原样(尾部空格可能有意义,如口令)
+    return raw
 
 
 def _opt(name: str) -> Opt:
@@ -251,7 +238,7 @@ _warned: set[str] = set()
 _log = logging.getLogger("foxclaw.config")
 
 
-def get_safe(name: str, default: Any = None) -> Any:
+def get_safe(name: str, default: Any | None = None) -> Any:
     """可降级的读取:值非法时**退默认值并要求日志警告一次**,不抛异常。
 
     给"配置错不该拖垮主流程"的地方用(trace 采样、工具超时、搜索超时):这些点
@@ -262,12 +249,12 @@ def get_safe(name: str, default: Any = None) -> Any:
     fallback = opt.default if default is None else default
     raw = os.environ.get(name)
     if raw is None or not raw.strip():
-        return fallback                          # 未设置/空串:用调用方给的兜底
+        return fallback
     try:
         return _parse(opt, raw, _caller())
     except ConfigError as e:
         if name not in _warned:
-            _warned.add(name)                    # 只喊一次:tracing 是每请求调用
+            _warned.add(name)
             _log.warning("[config] %s", e)
         return fallback
 
@@ -297,8 +284,6 @@ def known_keys() -> frozenset[str]:
     只在 `check()` / `show()` 这类诊断路径调用,不进请求路径;结果缓存在本进程内。
     """
     pkg = Path(__file__).resolve().parent.parent
-    # vendor/(HKC/HMR)在仓库根,不在包内:它们自己读 HMR_*/HKC_* 变量,不一起扫就会把
-    # 正常配置报成"拼错的键"。wheel 里没有 vendor/ → 扫描自然为空,不影响安装后的行为。
     roots = [pkg] + ([pkg.parent / "vendor"] if (pkg.parent / "vendor").is_dir() else [])
     found: set[str] = set(SPEC_BY_NAME)
     files: list[Path] = []
@@ -308,7 +293,7 @@ def known_keys() -> frozenset[str]:
     for path in files:
         try:
             tree = ast.parse(path.read_text(encoding="utf-8", errors="replace"))
-        except SyntaxError:                      # 语法坏掉的文件留着给 CI 报,这里跳过
+        except SyntaxError:
             continue
         for node in ast.walk(tree):
             if isinstance(node, ast.Call):
@@ -401,7 +386,6 @@ def check(env: Mapping[str, str] | None = None) -> list[Issue]:
         except ConfigError as e:
             code = "choice" if opt.kind == "choice" else (
                 "range" if ("下限" in str(e) or "上限" in str(e)) else "type")
-            # 密钥不回显原值,免得把半截口令打进日志
             msg = str(e)
             if is_secret(opt.name):
                 msg = f"值 {mask(raw)} 不合法(原始值已脱敏)"

package/python/foxclaw/core/shared_write.py

@@ -42,21 +42,12 @@ from typing import Iterable, Optional
 MODE_ENV = "FOXCLAW_SHARED_WRITE_MODE"
 VALID_MODES = ("audit", "warn", "enforce")
 
-# 与写入方无关、任何 Agent 都可写的 facet(设计上就该跨 Agent 共享的东西):
-#   preference     —— 用户偏好:base.py 明确以 shared=True 写入,意在跨会话跨 Agent 生效
-#   truth_pipeline —— 真值管线沉淀(truth_pipeline.py),写入方是 agent_id="system"
 GLOBAL_ALLOWED_FACETS = frozenset({"preference", "truth_pipeline"})
 
-# 各 Agent 的「职责域」允许 facet。facet 取自一次写入的 {type:<记忆类型>} ∪ tags,
-# 支持 fnmatch 通配(如 finance.* 可匹配 finance.budget)。
-#
-# 注意:这是**起始假设**,不是已验证的结论 —— 默认 audit 模式的目的正是用真实流量验证它。
 DEFAULT_SHARED_WRITE_ALLOWED = {
-    "supervisor": {"*"},      # 主管:分发/协调记录,语义上允许任意
-    "system":     {"*"},      # 系统(真值管线、后台任务)
+    "supervisor": {"*"},
+    "system":     {"*"},
     "finance":    {"finance.*"},
-    # 行政并入办公后,办公学习 Agent 同时拥有学习与行程两个写域;
-    # 助手已下放为技能(不再有独立 agent_id),不再单列 ACL 条目。
     "office":     {"learning.*", "itinerary.*", "schedule.*"},
 }
 
@@ -90,8 +81,8 @@ class SharedWritePolicy:
     无状态、无锁、纯函数式判定 —— 并发安全直接成立,也便于单独测试。
     """
 
-    def __init__(self, allowed: dict = None, mode: str = None,
-                 global_facets: Iterable[str] = None):
+    def __init__(self, allowed: dict | None = None, mode: str | None = None,
+                 global_facets: Iterable[str] | None = None):
         self.allowed = {k: set(v) for k, v in
                         (allowed or DEFAULT_SHARED_WRITE_ALLOWED).items()}
         self.global_facets = set(global_facets if global_facets is not None
@@ -99,13 +90,11 @@ class SharedWritePolicy:
         self.mode = self._resolve_mode(mode)
 
     @staticmethod
-    def _resolve_mode(mode: str = None) -> str:
+    def _resolve_mode(mode: str | None = None) -> str:
         """显式入参 > 环境变量 > 默认 audit。非法值一律回落到 audit(保守:不拦截)。"""
         m = (mode or os.environ.get(MODE_ENV, "") or "audit").strip().lower()
         return m if m in VALID_MODES else "audit"
 
-    # 纯标记类 tag:描述"这条记忆的归属/去向",不描述"内容是什么"。
-    # 让它们参与内容域匹配只会稀释策略表 —— 尤其 "shared" 在本闸门语境下恒为真,零信息量。
     _MARKER_TAGS = ("agent:", "shared")
 
     @staticmethod
@@ -126,9 +115,9 @@ class SharedWritePolicy:
             out.append(t)
         return tuple(dict.fromkeys(out))
 
-    def evaluate(self, agent_id: str = None, memory_type: str = "concept",
-                 tags: Iterable[str] = None) -> Decision:
-        facets = self.facets_of(memory_type, tags)
+    def evaluate(self, agent_id: str | None = None, memory_type: str = "concept",
+                 tags: Iterable[str] | None = None) -> Decision:
+        facets = self.facets_of(memory_type, tags or ())
         who = agent_id or "unknown"
 
         if any(fnmatch.fnmatchcase(f, p) for f in facets for p in self.global_facets):
@@ -142,9 +131,9 @@ class SharedWritePolicy:
         return Decision(False, f"{who} 的职责域不含 {list(facets)}", self.mode, facets)
 
 
-def guard_shared_write(backend, agent_id: str, content: str,
+def guard_shared_write(backend, agent_id: str | None, content: str,
                        memory_type: str = "concept",
-                       tags: Iterable[str] = None) -> Optional[Decision]:
+                       tags: Iterable[str] | None = None) -> Optional[Decision]:
     """共享层写入的统一闸门 —— 必须在**真正落库之前**调用。
 
     行为分三档:
@@ -170,7 +159,6 @@ def guard_shared_write(backend, agent_id: str, content: str,
                 "allowed": decision.allowed,
                 "reason": decision.reason,
                 "mode": decision.mode,
-                # 只留摘要哈希 + 短预览,不把共享层正文原样灌进事件流
                 "content_sha": hashlib.sha256(
                     str(content or "").encode("utf-8")).hexdigest()[:16],
                 "content_preview": str(content or "")[:60],
@@ -187,7 +175,7 @@ def guard_shared_write(backend, agent_id: str, content: str,
     return decision
 
 
-def attach(backend, policy: SharedWritePolicy = None, spine=None) -> SharedWritePolicy:
+def attach(backend, policy: SharedWritePolicy | None = None, spine=None) -> SharedWritePolicy:
     """把策略挂到记忆后端(HMRAdapter / MockHMR 皆可)。返回生效的策略实例。
 
     用挂载而非构造函数注入,是因为装配顺序:memory_adapter 在 event_spine **之前**创建,

package/python/foxclaw/core/steering_queue.py

@@ -21,17 +21,18 @@ import threading
 import time
 import uuid
 from dataclasses import dataclass, field
+from typing import Any
 
 
 @dataclass
 class SteeringItem:
     item_id: str
-    requester: str                 # 谁在等这个结果(主任务/会话标识)
-    source_agent: str              # 哪个子 Agent 产出的
-    payload: dict                  # 结果内容
+    requester: str
+    source_agent: str
+    payload: dict
     created: float = field(default_factory=time.time)
-    leased_until: float = 0.0      # 0 = 未租出;>0 = 租约到期时间戳
-    lease_id: str = ""             # 当前租约持有者标识
+    leased_until: float = 0.0
+    lease_id: str = ""
 
     @property
     def is_leased(self) -> bool:
@@ -60,7 +61,7 @@ class SteeringQueue:
                 source_agent=source_agent, payload=payload)
             return item_id
 
-    def lease(self, requester: str = None, max_items: int = 10) -> list[SteeringItem]:
+    def lease(self, requester: str | None = None, max_items: int = 10) -> list[SteeringItem]:
         """租走一批待处理结果(可按 requester 过滤)。
 
         原子地:挑出未被租用(或租约已过期)的项,标记为 leased,返回。
@@ -69,7 +70,7 @@ class SteeringQueue:
         with self._lock:
             self._reclaim_expired()
             now = time.time()
-            leased = []
+            leased: list[Any] = []
             lease_id = uuid.uuid4().hex[:12]
             for item in self._items.values():
                 if len(leased) >= max_items:
@@ -83,7 +84,7 @@ class SteeringQueue:
                 leased.append(item)
             return leased
 
-    def ack(self, item_id: str, lease_id: str = None) -> bool:
+    def ack(self, item_id: str, lease_id: str | None = None) -> bool:
         """消费者确认处理完 → 移除该项。
 
         校验 lease_id:只有持有当前租约的消费者能 ack(防止过期租约误删
@@ -94,7 +95,7 @@ class SteeringQueue:
             if item is None:
                 return False
             if lease_id is not None and item.lease_id != lease_id:
-                return False        # 租约不匹配(可能已过期被别人租走)
+                return False
             del self._items[item_id]
             return True
 
@@ -114,7 +115,7 @@ class SteeringQueue:
                 item.leased_until = 0.0
                 item.lease_id = ""
 
-    def pending_count(self, requester: str = None) -> int:
+    def pending_count(self, requester: str | None = None) -> int:
         """待处理(未被有效租用)的项数。"""
         with self._lock:
             self._reclaim_expired()
@@ -145,7 +146,7 @@ class SteeringQueue:
                 if item.requester != requester:
                     continue
                 if item.is_leased:
-                    continue        # 正被租用 → 留给租约消费者,drain 不碰
+                    continue
                 out.append(item.payload)
                 to_del.append(item_id)
             for item_id in to_del:

package/python/foxclaw/core/system_bus.py

@@ -73,7 +73,7 @@ class SystemBus:
     def publish(self, channel: str, payload: dict):
         return self.spine.publish(channel, payload, source="system_bus")
 
-    def history(self, channel: str = None, limit: int = 50,
+    def history(self, channel: str | None = None, limit: int = 50,
                 exact: bool = False) -> list:
         """历史事件(dict 列表)。exact=True 时只返回 topic 完全匹配的事件
         (默认前缀匹配,与 EventSpine 原生一致)。"""

package/python/foxclaw/core/thought_chain.py

@@ -16,16 +16,16 @@ from pathlib import Path
 
 
 NodeType = Literal[
-    "goal",        # 目标基线节点（根）
-    "reasoning",   # 推理步骤
-    "memory_retrieval",  # 记忆检索
-    "tool_intent", # 工具意图
-    "tool_use",    # 工具实际调用（augment.py 已在用；此前漏登记，类型面是欠账）
-    "plan",        # 显式计划（steps/flow 落在 metadata，供回显与审计）
-    "decision",    # 行动决策
-    "policy_update",  # Policy 候选更新
-    "consolidation",  # 记忆巩固写回
-    "reflection",  # 执行后反思
+    "goal",
+    "reasoning",
+    "memory_retrieval",
+    "tool_intent",
+    "tool_use",
+    "plan",
+    "decision",
+    "policy_update",
+    "consolidation",
+    "reflection",
 ]
 
 HarnessStatus = Literal["BASELINE", "PASS", "WARN", "BLOCK", "PENDING", "REGRESSION"]
@@ -39,15 +39,15 @@ class ThoughtNode:
     agent_id: str
     type: NodeType
     content: str
-    conf: float                        # 置信度 0.0-1.0
-    mem_refs: list[str]               # 引用的 HMR 记忆 ID
-    parent_ids: list[str]             # 父节点 ID（因果依赖）
+    conf: float
+    mem_refs: list[str]
+    parent_ids: list[str]
     harness_status: HarnessStatus
-    harness_reason: Optional[str]     # BLOCK/WARN 时的原因
-    harness_delta: Optional[float]    # 目标漂移量
-    dominant_dim: Optional[str]       # 主导漂移维度
-    tool_name: Optional[str]          # 如果是 tool_intent 节点
-    entities: list[str]              # 涉及的实体集合
+    harness_reason: Optional[str]
+    harness_delta: Optional[float]
+    dominant_dim: Optional[str]
+    tool_name: Optional[str]
+    entities: list[str]
     timestamp: str
     metadata: dict
 
@@ -59,11 +59,11 @@ class ThoughtNode:
         type: NodeType,
         content: str,
         conf: float = 1.0,
-        mem_refs: list[str] = None,
-        parent_ids: list[str] = None,
-        tool_name: str = None,
-        entities: list[str] = None,
-        metadata: dict = None,
+        mem_refs: list[str] | None = None,
+        parent_ids: list[str] | None = None,
+        tool_name: str | None = None,
+        entities: list[str] | None = None,
+        metadata: dict | None = None,
     ) -> "ThoughtNode":
         return cls(
             id=f"tn_{uuid.uuid4().hex[:12]}",
@@ -150,7 +150,7 @@ class ThoughtChain:
         try:
             conn.execute("PRAGMA journal_mode=WAL")
         except sqlite3.OperationalError:
-            pass  # 个别文件系统不支持 WAL(如网络盘)→ 退回默认日志模式,timeout 仍生效
+            pass
         try:
             yield conn
             conn.commit()
@@ -183,9 +183,9 @@ class ThoughtChain:
         self,
         node_id: str,
         status: HarnessStatus,
-        reason: str = None,
-        delta: float = None,
-        dominant_dim: str = None,
+        reason: str | None = None,
+        delta: float | None = None,
+        dominant_dim: str | None = None,
     ):
         """Harness 校验完成后更新节点标注"""
         with self._conn() as conn:
@@ -202,7 +202,7 @@ class ThoughtChain:
             ).fetchone()
         return self._row_to_node(row) if row else None
 
-    def get_chain(self, session_id: str, agent_id: str = None) -> list[ThoughtNode]:
+    def get_chain(self, session_id: str, agent_id: str | None = None) -> list[ThoughtNode]:
         """获取一个会话的完整推理链，按时间排序"""
         with self._conn() as conn:
             if agent_id:
@@ -217,7 +217,7 @@ class ThoughtChain:
                 ).fetchall()
         return [self._row_to_node(r) for r in rows]
 
-    def get_blocked_nodes(self, agent_id: str = None, limit: int = 50) -> list[ThoughtNode]:
+    def get_blocked_nodes(self, agent_id: str | None = None, limit: int = 50) -> list[ThoughtNode]:
         """获取被 Harness 截断的节点，用于审计"""
         with self._conn() as conn:
             if agent_id:
@@ -232,7 +232,7 @@ class ThoughtChain:
                 ).fetchall()
         return [self._row_to_node(r) for r in rows]
 
-    def search_nodes(self, keyword: str, agent_id: str = None,
+    def search_nodes(self, keyword: str, agent_id: str | None = None,
                      limit: int = 20) -> list[ThoughtNode]:
         """按关键词在推理节点内容里检索(LIKE 子串匹配)。供 HSR 的 AgentSourcePort
         把「各 Agent 想过/判过什么」连通进内部搜索。只读。"""
@@ -307,8 +307,6 @@ class ThoughtChain:
             "timestamp", "metadata"
         ]
         d = dict(zip(cols, row))
-        # JSON 字段容错:单行某字段损坏时降级为默认值,而非让整个审计链读取崩溃。
-        # 审计系统的可靠性要求"一条坏数据不拖垮全部"。
         for field, default in (("mem_refs", []), ("parent_ids", []),
                                ("entities", []), ("metadata", {})):
             try:

package/python/foxclaw/core/token_meter.py

@@ -36,7 +36,6 @@ def estimate_tokens(text: str, model: str = "") -> int:
             enc = tiktoken.get_encoding("cl100k_base")
         return len(enc.encode(text))
     except Exception:
-        # 字符估算:中文(非ASCII)按 1.1 字符/token,英文(ASCII)按 4 字符/token。
         ascii_chars = sum(1 for c in text if ord(c) < 128)
         cjk_chars = len(text) - ascii_chars
         return int(ascii_chars / 4 + cjk_chars * 1.1) + 1
@@ -50,8 +49,8 @@ class CallRecord:
     agent_id: str
     input_tokens: int
     output_tokens: int
-    estimated: bool          # True=估算,False=API真实usage
-    task_kind: str = ""      # 可选:single/multi/...
+    estimated: bool
+    task_kind: str = ""
 
     @property
     def total_tokens(self) -> int:
@@ -66,14 +65,14 @@ class CallRecord:
 class TokenMeter:
     """Token 计量器。线程安全,可聚合,可落盘。"""
 
-    def __init__(self, log_path: str = None, max_records: int = 10000,
+    def __init__(self, log_path: str | None = None, max_records: int = 10000,
                  max_log_mb: float = 10.0):
         self.log_path = log_path
         self.max_records = max_records
         self.max_log_bytes = int(max_log_mb * 1024 * 1024)
         self._records: list[CallRecord] = []
         self._lock = threading.RLock()
-        self._append_count = 0     # 触发轮转检查的计数器
+        self._append_count = 0
         if log_path:
             os.makedirs(os.path.dirname(log_path) or ".", exist_ok=True)
 
@@ -94,7 +93,7 @@ class TokenMeter:
 
     def measure_call(self, *, system: str, messages: list, output: str,
                      provider: str, model: str, agent_id: str = "",
-                     usage: dict = None, task_kind: str = "") -> CallRecord:
+                     usage: dict | None = None, task_kind: str = "") -> CallRecord:
         """计量一次调用。优先用 API 返回的 usage,否则估算。
 
         usage 形如 {"input_tokens": N, "output_tokens": M}(已由 router 归一化)。
@@ -104,7 +103,6 @@ class TokenMeter:
                                usage.get("input_tokens", 0),
                                usage.get("output_tokens", 0),
                                estimated=False, task_kind=task_kind)
-        # 估算:输入 = system + 所有 message content,输出 = output
         input_text = (system or "") + "\n".join(
             str(m.get("content", "")) for m in (messages or []))
         in_tok = estimate_tokens(input_text, model)
@@ -112,7 +110,6 @@ class TokenMeter:
         return self.record(provider, model, agent_id, in_tok, out_tok,
                            estimated=True, task_kind=task_kind)
 
-    # ── 聚合查询 ──────────────────────────────────────────
     def summary(self) -> dict:
         """总体统计。"""
         with self._lock:
@@ -211,8 +208,7 @@ class TokenMeter:
             with open(self.log_path, "a", encoding="utf-8") as f:
                 f.write(json.dumps(rec.to_dict(), ensure_ascii=False) + "\n")
         except Exception:
-            pass        # 计量落盘失败不影响主流程
-        # 每 100 次追加检查一次文件大小,超限则轮转(防磁盘无限膨胀)
+            pass
         self._append_count += 1
         if self._append_count % 100 == 0:
             self._rotate_if_needed()
@@ -226,10 +222,10 @@ class TokenMeter:
                 return
             with open(self.log_path, encoding="utf-8") as f:
                 lines = f.readlines()
-            keep = lines[len(lines) // 2:]      # 保留较新的一半
+            keep = lines[len(lines) // 2:]
             tmp = self.log_path + ".tmp"
             with open(tmp, "w", encoding="utf-8") as f:
                 f.writelines(keep)
-            os.replace(tmp, self.log_path)      # 原子替换
+            os.replace(tmp, self.log_path)
         except Exception:
-            pass        # 轮转失败不影响主流程
+            pass

package/python/foxclaw/core/tools.py

@@ -15,6 +15,7 @@ Foxclaw — 工具注册表(ToolRegistry / P2 function-calling)
 """
 from __future__ import annotations
 import os
+from typing import Any
 
 
 def _tool(name: str, description: str, properties: dict, required: list) -> dict:
@@ -33,7 +34,6 @@ def _tool(name: str, description: str, properties: dict, required: list) -> dict
     }
 
 
-# ── 首批工具声明(高价值、正好替掉现有关键词坑)──────────────────────────────
 WEB_SEARCH = _tool(
     "web_search",
     "联网搜索实时/时效性的**外部**信息:新闻、产品的版本与型号、发布动态、价格、汇率、"
@@ -113,15 +113,15 @@ class ToolRegistry:
         for k in required:
             if k not in args or args[k] in (None, ""):
                 errs.append(f"缺少必填参数 {k}")
-        _tmap = {"string": str, "integer": int, "number": (int, float),
+        _tmap: dict[str, Any] = {"string": str, "integer": int, "number": (int, float),
                  "boolean": bool, "array": list, "object": dict}
         for k, v in args.items():
             spec = props.get(k)
             if not isinstance(spec, dict):
                 continue
-            want = _tmap.get(spec.get("type"))
+            stype = spec.get("type")
+            want = _tmap.get(stype) if isinstance(stype, str) else None
             if not want or not isinstance(v, want):
-                # bool 是 int 的子类,须排除,否则 True 会被当成合法 integer
                 if not (want is not bool and isinstance(v, bool)):
                     errs.append(f"参数 {k} 类型应为 {spec.get('type')},"
                                 f"实为 {type(v).__name__}")
@@ -143,20 +143,12 @@ def default_registry() -> ToolRegistry:
     return ToolRegistry().register(WEB_SEARCH).register(RECALL_MEMORY)
 
 
-# ── 工具能力分级(供 permission.evaluate 四阶段管线判定)────────────────────────
-# 病根提醒:prompt 级隔离挡不住弱模型被块内强指令诱导(实测 flash ~2/3 被劫持),真正的
-# 安全阀在**动作级**——工具执行前过权限管线,写/副作用/不可逆动作走人在回路(HITL)。
-# 字段对齐 permission.evaluate:side_effect(read/write/send/pay)/ read_only / external / destructive。
-# parallel_safe 不在权限语义里,只用于**同轮多工具是否可并发**:置 True 表示"纯读、可与其他
-# parallel_safe 工具同时跑"(见 agents/mixins/tool_exec.py::_run_tools)。未声明 = 串行。
-# **新增任何工具都应在此声明能力;未声明者 fail-closed 当作有副作用 → 强制 HITL(见 _DEFAULT_CAP)。**
 TOOL_CAPABILITIES: dict[str, dict] = {
     "web_search":    {"side_effect": "read", "read_only": True, "external": False,
                       "destructive": False, "parallel_safe": True},
     "recall_memory": {"side_effect": "read", "read_only": True, "external": False,
                       "destructive": False, "parallel_safe": True},
 }
-# 未声明工具的兜底:当有副作用 + 外部 → permission 管线判 ask → 强制人在回路。宁误拦不漏放。
 _DEFAULT_CAP = {"side_effect": "write", "read_only": False, "external": True, "destructive": False}