foxclaw 0.1.0 → 0.1.3

package/python/foxclaw/core/token_meter.py

@@ -0,0 +1,231 @@
+"""
+Foxclaw Core — Token 计量器 (Token Meter)
+
+成本可观测性,运行时治理的一块。埋在 ModelRouter.complete() 这个唯一的 LLM
+调用咽喉处,所有模型调用自动被记录,不漏一次。
+
+为什么放这里:整个系统真正调 LLM 的入口只有 router.complete()——认知层
+(记忆/Harness/ThoughtChain/领域内核)全是本地算法不烧 token。所以只要拦住这一处,
+就能完整统计 token 消耗。
+
+token 数来源优先级(从准到糙):
+  1. API 返回的真实 usage(anthropic/openai 都带)—— 最准
+  2. tiktoken 离线估算(装了 tiktoken)
+  3. 字符数估算(兜底,中文~1.5字符/token、英文~4字符/token,混合按 ~2.2)
+
+记录维度:provider/model、agent_id、输入/输出 token、是否估算、时间。
+可按 agent / provider 聚合,可落盘(JSONL 追加,崩溃安全)。
+"""
+from __future__ import annotations
+import json
+import os
+import threading
+import time
+from dataclasses import dataclass, asdict
+
+
+def estimate_tokens(text: str, model: str = "") -> int:
+    """估算文本 token 数。优先 tiktoken,降级字符估算。"""
+    if not text:
+        return 0
+    try:
+        import tiktoken
+        try:
+            enc = tiktoken.encoding_for_model(model)
+        except Exception:
+            enc = tiktoken.get_encoding("cl100k_base")
+        return len(enc.encode(text))
+    except Exception:
+        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
+
+
+@dataclass
+class CallRecord:
+    timestamp: float
+    provider: str
+    model: str
+    agent_id: str
+    input_tokens: int
+    output_tokens: int
+    estimated: bool
+    task_kind: str = ""
+
+    @property
+    def total_tokens(self) -> int:
+        return self.input_tokens + self.output_tokens
+
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        d["total_tokens"] = self.total_tokens
+        return d
+
+
+class TokenMeter:
+    """Token 计量器。线程安全,可聚合,可落盘。"""
+
+    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
+        if log_path:
+            os.makedirs(os.path.dirname(log_path) or ".", exist_ok=True)
+
+    def record(self, provider: str, model: str, agent_id: str,
+               input_tokens: int, output_tokens: int, estimated: bool,
+               task_kind: str = "") -> CallRecord:
+        rec = CallRecord(
+            timestamp=time.time(), provider=provider, model=model,
+            agent_id=agent_id or "unknown",
+            input_tokens=int(input_tokens), output_tokens=int(output_tokens),
+            estimated=estimated, task_kind=task_kind)
+        with self._lock:
+            self._records.append(rec)
+            if len(self._records) > self.max_records:
+                self._records = self._records[-self.max_records:]
+            self._append(rec)
+        return rec
+
+    def measure_call(self, *, system: str, messages: list, output: str,
+                     provider: str, model: str, agent_id: str = "",
+                     usage: dict | None = None, task_kind: str = "") -> CallRecord:
+        """计量一次调用。优先用 API 返回的 usage,否则估算。
+
+        usage 形如 {"input_tokens": N, "output_tokens": M}(已由 router 归一化)。
+        """
+        if usage and usage.get("input_tokens") is not None:
+            return self.record(provider, model, agent_id,
+                               usage.get("input_tokens", 0),
+                               usage.get("output_tokens", 0),
+                               estimated=False, task_kind=task_kind)
+        input_text = (system or "") + "\n".join(
+            str(m.get("content", "")) for m in (messages or []))
+        in_tok = estimate_tokens(input_text, model)
+        out_tok = estimate_tokens(output or "", model)
+        return self.record(provider, model, agent_id, in_tok, out_tok,
+                           estimated=True, task_kind=task_kind)
+
+    def summary(self) -> dict:
+        """总体统计。"""
+        with self._lock:
+            recs = list(self._records)
+        if not recs:
+            return {"calls": 0, "total_tokens": 0, "input_tokens": 0,
+                    "output_tokens": 0, "estimated_ratio": 0.0}
+        total_in = sum(r.input_tokens for r in recs)
+        total_out = sum(r.output_tokens for r in recs)
+        est = sum(1 for r in recs if r.estimated)
+        return {
+            "calls": len(recs),
+            "total_tokens": total_in + total_out,
+            "input_tokens": total_in,
+            "output_tokens": total_out,
+            "avg_tokens_per_call": round((total_in + total_out) / len(recs), 1),
+            "estimated_ratio": round(est / len(recs), 2),
+        }
+
+    def by_agent(self) -> dict:
+        """按 Agent 聚合 token 消耗(找出最费 token 的 Agent)。"""
+        with self._lock:
+            recs = list(self._records)
+        agg: dict[str, dict] = {}
+        for r in recs:
+            a = agg.setdefault(r.agent_id, {"calls": 0, "total_tokens": 0,
+                                            "input_tokens": 0, "output_tokens": 0})
+            a["calls"] += 1
+            a["input_tokens"] += r.input_tokens
+            a["output_tokens"] += r.output_tokens
+            a["total_tokens"] += r.total_tokens
+        return dict(sorted(agg.items(), key=lambda kv: -kv[1]["total_tokens"]))
+
+    def by_provider(self) -> dict:
+        """按 provider/model 聚合(估算不同模型的成本分布)。"""
+        with self._lock:
+            recs = list(self._records)
+        agg: dict[str, dict] = {}
+        for r in recs:
+            key = f"{r.provider}/{r.model}"
+            a = agg.setdefault(key, {"calls": 0, "total_tokens": 0})
+            a["calls"] += 1
+            a["total_tokens"] += r.total_tokens
+        return dict(sorted(agg.items(), key=lambda kv: -kv[1]["total_tokens"]))
+
+    def estimate_cost(self, price_per_1k_input: float = 0.0,
+                      price_per_1k_output: float = 0.0) -> dict:
+        """按给定单价估算总成本(单位由调用方定,如人民币元/1k token)。
+
+        DeepSeek 等价格便宜,默认单价为 0(调用方传入实际单价才算)。
+        """
+        s = self.summary()
+        cost = (s["input_tokens"] / 1000 * price_per_1k_input +
+                s["output_tokens"] / 1000 * price_per_1k_output)
+        return {
+            "input_tokens": s["input_tokens"],
+            "output_tokens": s["output_tokens"],
+            "price_per_1k_input": price_per_1k_input,
+            "price_per_1k_output": price_per_1k_output,
+            "estimated_cost": round(cost, 4),
+        }
+
+    def report(self) -> str:
+        """人类可读的文本报告。"""
+        s = self.summary()
+        if s["calls"] == 0:
+            return "Token 计量:暂无 LLM 调用记录(可能全程 stub 模式)。"
+        lines = [
+            "═" * 40,
+            "Token 消耗报告",
+            "═" * 40,
+            f"总调用次数 : {s['calls']}",
+            f"总 token   : {s['total_tokens']:,}(输入 {s['input_tokens']:,} / 输出 {s['output_tokens']:,})",
+            f"平均每次   : {s['avg_tokens_per_call']:,} token",
+            f"估算占比   : {int(s['estimated_ratio']*100)}%(其余为 API 真实 usage)",
+            "",
+            "按 Agent:",
+        ]
+        for agent, a in self.by_agent().items():
+            lines.append(f"  {agent:12} {a['total_tokens']:>8,} token  ({a['calls']} 次)")
+        lines.append("")
+        lines.append("按模型:")
+        for key, a in self.by_provider().items():
+            lines.append(f"  {key:24} {a['total_tokens']:>8,} token  ({a['calls']} 次)")
+        lines.append("═" * 40)
+        return "\n".join(lines)
+
+    def reset(self):
+        with self._lock:
+            self._records.clear()
+
+    def _append(self, rec: CallRecord):
+        if not self.log_path:
+            return
+        try:
+            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
+        self._append_count += 1
+        if self._append_count % 100 == 0:
+            self._rotate_if_needed()
+
+    def _rotate_if_needed(self):
+        """日志文件超过上限时,保留最近一半,丢弃更早的(防无限增长)。"""
+        try:
+            if not self.log_path or not os.path.exists(self.log_path):
+                return
+            if os.path.getsize(self.log_path) < self.max_log_bytes:
+                return
+            with open(self.log_path, encoding="utf-8") as f:
+                lines = f.readlines()
+            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)
+        except Exception:
+            pass

package/python/foxclaw/core/tools.py

@@ -0,0 +1,164 @@
+"""
+Foxclaw — 工具注册表(ToolRegistry / P2 function-calling)
+
+病根(见 docs/internal/TOOL_USE_PLAN.md §0):系统里散落多套"用关键词猜用户意图"的
+启发式(needs_search / _model_augment / _skill_augment …),各管一摊、彼此不知情,
+加一处碰坏一处。根因是 LLM 从没机会"自己决定用哪个工具"。
+
+本模块给出**单一意图决策源**的地基:把能力声明成 function-calling 工具(JSON Schema),
+交给模型自己选。ToolRegistry 只持有**工具声明(schema)**;工具的**执行**由 Agent 侧
+`_dispatch_tool` 绑定(recall_memory 需要 agent 的 HMR、web_search 走 core.web_search),
+这样注册表保持无状态、可跨 Agent 复用。
+
+模型无关:schema 用 OpenAI tools 通用格式;ModelRouter.call_tools 负责按 provider 适配/降级。
+安全:执行前经 per-tool deny(env FOXCLAW_TOOL_DENY,逗号分隔)+ 可接 SkillPolicy 闸。
+"""
+from __future__ import annotations
+import os
+from typing import Any
+
+
+def _tool(name: str, description: str, properties: dict, required: list) -> dict:
+    """构造一个 OpenAI-format function tool 声明。"""
+    return {
+        "type": "function",
+        "function": {
+            "name": name,
+            "description": description,
+            "parameters": {
+                "type": "object",
+                "properties": properties,
+                "required": required,
+            },
+        },
+    }
+
+
+WEB_SEARCH = _tool(
+    "web_search",
+    "联网搜索实时/时效性的**外部**信息:新闻、产品的版本与型号、发布动态、价格、汇率、"
+    "股价、天气、排行等。仅当答案依赖当前外部世界、且不在本地时才调用;闲聊、常识、"
+    "以及用户自己的账本/行程/学习/记忆等**本地数据**不要调用本工具。",
+    {"query": {"type": "string", "description": "要检索的关键词或问题(尽量具体)"}},
+    ["query"],
+)
+
+RECALL_MEMORY = _tool(
+    "recall_memory",
+    "从用户的个人记忆(HMR)里语义召回既往信息:过去的对话、偏好、事实、结论等。"
+    "当回答依赖'用户之前说过/记录过什么'时调用;通用常识不需要调用。",
+    {"query": {"type": "string", "description": "召回用的语义查询"},
+     "top_k": {"type": "integer", "description": "召回条数(1-20,默认 5)"}},
+    ["query"],
+)
+
+
+class ToolRegistry:
+    """工具声明注册表(无状态,只持 schema)。执行由 Agent 侧按 name 分派。"""
+
+    def __init__(self):
+        self._tools: dict[str, dict] = {}
+
+    def register(self, schema: dict) -> "ToolRegistry":
+        name = schema["function"]["name"]
+        self._tools[name] = schema
+        return self
+
+    def names(self) -> list[str]:
+        return list(self._tools.keys())
+
+    def schemas(self) -> list[dict]:
+        """返回放行的工具 schema 列表(经 env FOXCLAW_TOOL_DENY 过滤)。"""
+        deny = _denied()
+        return [s for n, s in self._tools.items() if n not in deny]
+
+    def has(self, name: str) -> bool:
+        return name in self._tools
+
+    def param_schema(self, name: str) -> dict:
+        """取某工具的 parameters JSON Schema(供执行侧校验)。
+
+        病根:此前 schema 只用于发给模型当 `tools=` 参数,**执行侧从不校验**,
+        于是声明的 `required` 形同虚设;更严重的是 base._dispatch_tool 构造
+        permission spec 时传 `params={}`(恒空)→ permission 管线 Stage 1 的
+        必填校验**永不触发**,只靠下游手工 `if not q` 兜住。新增工具时无保护。
+
+        本访问器让「发给模型的 schema」与「执行侧校验的 schema」共用同一份
+        真源,消除声明与执行的双份真相。
+        """
+        t = self._tools.get(name)
+        if not t:
+            return {}
+        return (t.get("function") or {}).get("parameters") or {}
+
+    def validate_args(self, name: str, args: dict) -> list:
+        """轻量校验工具入参,返回错误描述列表(空列表 = 通过)。
+
+        刻意只校验三件事,不引第三方依赖(与项目「减少自研」一致,且 pyproject
+        依赖表本就没有 jsonschema):
+          1. 必填参数是否齐全;
+          2. 参数类型是否符合 schema 声明的 basic type;
+          3. (不做)未声明的额外字段 —— 放过,避免过度约束模型。
+
+        返回非空时,调用方**必须**把错误回注给模型让其自修正,不得静默用空
+        参数继续 —— 那会让模型误以为工具已执行。
+        """
+        schema = self.param_schema(name)
+        if not schema:
+            return []
+        props = schema.get("properties") or {}
+        required = schema.get("required") or []
+        args = args if isinstance(args, dict) else {}
+        errs: list[str] = []
+        for k in required:
+            if k not in args or args[k] in (None, ""):
+                errs.append(f"缺少必填参数 {k}")
+        _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
+            stype = spec.get("type")
+            want = _tmap.get(stype) if isinstance(stype, str) else None
+            if not want or not isinstance(v, want):
+                if not (want is not bool and isinstance(v, bool)):
+                    errs.append(f"参数 {k} 类型应为 {spec.get('type')},"
+                                f"实为 {type(v).__name__}")
+        return errs
+
+
+def _denied() -> set[str]:
+    """被禁用的工具名集合(env FOXCLAW_TOOL_DENY,逗号分隔)。安全 kill-switch。"""
+    raw = os.environ.get("FOXCLAW_TOOL_DENY", "")
+    return {x.strip() for x in raw.split(",") if x.strip()}
+
+
+def is_tool_denied(name: str) -> bool:
+    return name in _denied()
+
+
+def default_registry() -> ToolRegistry:
+    """首批工具:web_search + recall_memory。后续 skills/MCP 可继续 register 进来(P3)。"""
+    return ToolRegistry().register(WEB_SEARCH).register(RECALL_MEMORY)
+
+
+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},
+}
+_DEFAULT_CAP = {"side_effect": "write", "read_only": False, "external": True, "destructive": False}
+
+
+def tool_capability(name: str) -> dict:
+    """取工具能力分级;未声明 → fail-closed 兜底(有副作用,须 HITL)。"""
+    return dict(TOOL_CAPABILITIES.get(name, _DEFAULT_CAP))
+
+
+def tool_use_enabled() -> bool:
+    """是否启用 function-calling 主路径。默认关(behavior-preserving / 可逆):
+    FOXCLAW_TOOL_USE=1 开启后,支持 tools 的 provider 走 LLM 自主工具决策;
+    不支持的 provider 或关闭时,自动回退现有关键词增强链(fallback,不破坏)。"""
+    return os.environ.get("FOXCLAW_TOOL_USE", "0").strip() in ("1", "true", "True", "yes", "on")