foxclaw 0.1.0 → 0.1.3

package/python/foxclaw/core/vec_recall_adapter.py

@@ -0,0 +1,477 @@
+"""
+VecRecall 适配层 — 可选记忆后端，对外接口与 `HMRAdapter` 完全一致。
+
+为什么要这一层：业务代码只认 `HMRAdapter` 的 9 个方法（ingest / recall /
+recall_by_tag / delete_memory / get_workspace / save_workspace /
+save_runtime_state / restore_runtime_state / recent / stats）。
+`VecRecall` 的 API 形状与之不同，直接替换会让调用方炸在一个与被调用能力无关的地方。
+
+几处**按源码**而非按文档写的映射（v2.1 实测）：
+  Foxclaw                     VecRecall 2.1
+  ─────────────────────────   ───────────────────────────────────────────
+  ingest(...)                 add(content, memory_type=, visibility=, owner=, ...)
+  recall(query, agent_id=)    build_context(query, viewer=agent_id) 的 L2+L3
+  recall_by_tag("preference") query_by_topic_key("preference")
+  delete_memory(id)           delete(id)
+  recent(limit)               list_memories(sort="recent", full=True)
+  get_workspace(agent_id)     无对应概念 → 返回空壳(字段无人读,见 agents/base.py)
+
+注意两点与直觉相反的地方：
+1. `VecRecall.recall(memory_id)` **不是检索**，是"复习并增强记忆强度"。检索入口是
+   `build_context`(带 viewer 隔离) / `search`(不做任何隔离)。用错名字会得到
+   TypeError 或越权召回。
+2. 隔离走 `owner` + `visibility`，在**召回前**生效 —— 这正好修掉 HMR 路径
+   "全局召回 K 条再按 tag 筛"的完整性缺陷(别人的记忆挤满 top-k 时自己的召不回)。
+"""
+import os
+import re
+import sys
+import threading
+from pathlib import Path
+from types import SimpleNamespace
+
+from .shared_write import guard_shared_write
+from typing import Any
+
+_FOXCLAW_TO_VR = {
+    "concept": "semantic",
+    "project": "semantic",
+    "task": "semantic",
+    "agent_memory": "semantic",
+    "reflection": "semantic",
+    "workflow": "procedural",
+    "decision": "episodic",
+    "runtime": "episodic",
+    "execution": "episodic",
+}
+_VR_TO_FOXCLAW = {
+    "semantic": "concept",
+    "procedural": "workflow",
+    "episodic": "concept",
+}
+_VALID_TYPES = set(_FOXCLAW_TO_VR)
+
+_PREFERENCE_TAG = "preference"
+
+
+def _ensure_vendor_importable():
+    """把 vendor/ 与 vendor/hkc 加入 sys.path，使内嵌 HKC 的共享 embedding 可用。"""
+    vendor = Path(__file__).resolve().parent.parent.parent / "vendor"
+    for p in (vendor, vendor / "hkc"):
+        if p.exists() and str(p) not in sys.path:
+            sys.path.insert(0, str(p))
+
+
+class _HKCSharedEmbedding:
+    """与 HMR 共用同一个 SentenceTransformer 实例。
+
+    两套后端跑同一个模型才能让影子对比有意义（维度、分数可比）；若各自
+    `SentenceTransformer(...)` 一次，bge-m3 级别的模型会多占约 1GB 常驻内存。
+    HKC 的 `get_st_model` 已经是进程级缓存，这里只做一层薄包装。
+    """
+
+    backend = "hkc-shared"
+
+    def __init__(self, model_name: str):
+        self.model_name = model_name
+        self._model = None
+        self._dim: int | None = None
+
+    def _load(self):
+        if self._model is None:
+            _ensure_vendor_importable()
+            from hkc_search.embedding_backends import get_st_model
+            model = get_st_model(self.model_name)
+            if model is None:
+                raise RuntimeError(
+                    f"embedding 模型不可用: {self.model_name}(HKC 共享缓存加载失败)")
+            self._model = model
+        return self._model
+
+    def embed(self, text: str):
+        vec = self._load().encode([text or ""], normalize_embeddings=True)[0]
+        return [float(x) for x in vec]
+
+    def embed_batch(self, texts):
+        arr = self._load().encode(list(texts), normalize_embeddings=True)
+        return [[float(x) for x in row] for row in arr]
+
+    @property
+    def dim(self):
+        if self._dim is None:
+            try:
+                model = self._load()
+                getter = (getattr(model, "get_embedding_dimension", None)
+                          or getattr(model, "get_sentence_embedding_dimension", None))
+                self._dim = (int(getter() or 0) or None) if getter else None
+            except Exception:
+                self._dim = None
+        return self._dim
+
+
+class VecRecallAdapter:
+    """把 vecRecall v2.1 包装成 Foxclaw 期望的记忆接口。"""
+
+    backend = "vecRecall"
+
+    def __init__(self, storage_path: str = "./vecrecall_data", wing: str = "foxclaw",
+                 use_chain: bool = False, embedding_model: str | None = None,
+                 dedup: bool = True, embedding_backend=None, vector_backend=None):
+        """`embedding_backend` / `vector_backend` 用于注入（测试传轻量实现）。
+
+        默认为 None 时走生产配置：HKC 共享的 SentenceTransformer + vecRecall 默认
+        的 sqlite 向量库。测试若不注入，会去加载 bge-m3 级别模型，命令长时间无输出
+        —— 看起来像死锁，实际是在下载/加载权重。
+        """
+        from vecrecall import VecRecall
+
+        self.wing = wing
+        self.storage_path = str(storage_path)
+        self.version = self._resolve_version()
+        self._lock = threading.RLock()
+
+        self._emb = embedding_backend or _HKCSharedEmbedding(
+            self._resolve_model(embedding_model))
+        self._assert_dim_matches()
+
+        extra = {"vector_backend": vector_backend} if vector_backend is not None else {}
+        self._vr = VecRecall(
+            base_dir=self.storage_path,
+            wing=wing,
+            embedding_backend=self._emb,
+            use_blockchain=use_chain,
+            dedup=dedup,
+            **extra,
+        )
+
+    @staticmethod
+    def _resolve_version() -> str:
+        try:
+            import vecrecall as _pkg
+            return str(getattr(_pkg, "__version__", "unknown"))
+        except Exception:
+            return "unknown"
+
+    @staticmethod
+    def _resolve_model(embedding_model: str | None = None) -> str:
+        """与 HMRAdapter 同一条解析链，保证两套后端用同一个模型（分数与维度可比）。"""
+        return (embedding_model
+                or os.environ.get("EMBEDDING_MODEL")
+                or os.environ.get("HKC_EMBEDDING_MODEL")
+                or os.environ.get("FOXCLAW_EMBEDDING_MODEL")
+                or "all-MiniLM-L6-v2")
+
+    def _assert_dim_matches(self) -> None:
+        """已有向量维度与当前嵌入维度不一致时明确失败。
+
+        vecRecall 的 SqliteVectorBackend 与 HMR 一样用 zip() 求内积：两侧维度不同时
+        短的一侧被静默截断，分数照常返回、不抛错。症状是"换了 embedding 模型之后
+        召回突然变成噪声"，比直接崩更难定位。
+        """
+        db = Path(self.storage_path) / "vectors.db"
+        if not db.exists():
+            return
+        import sqlite3
+        try:
+            conn = sqlite3.connect(str(db))
+            rows = conn.execute("SELECT DISTINCT dim FROM vectors LIMIT 2").fetchall()
+            conn.close()
+        except Exception:
+            return
+        dims = {int(r[0]) for r in rows}
+        want = getattr(self._emb, "dim", None)
+        if dims and want and dims != {int(want)}:
+            raise RuntimeError(
+                f"已有向量维度 {sorted(dims)} 与当前嵌入维度 {want} 不一致。"
+                f"换 embedding 模型必须重建索引：删除 {self.storage_path} 后重启"
+            )
+
+    _AUTO_TITLE = re.compile(r"^[A-Za-z_]+\s+\d{1,2}:\d{2}$")
+
+    @staticmethod
+    def _derive_title(content: str) -> str:
+        s = str(content or "").strip()
+        if not s:
+            return ""
+        for pfx in ("对话:", "对话：", "用户偏好:", "用户偏好：", "任务:", "任务："):
+            if s.startswith(pfx):
+                s = s[len(pfx):].strip()
+                break
+        for sep in ("→", "->"):
+            if sep in s:
+                s = s.split(sep, 1)[0].strip()
+                break
+        s = re.split(r"[。！？!?\n\r]", s, 1)[0].strip()
+        return " ".join(s.split())[:80]
+
+    def ingest(self, content: str, type: str = "concept", agent_id: str | None = None,
+               title: str | None = None, tags: list | None = None, shared: bool = False, **kwargs):
+        """统一摄入。签名与 `HMRAdapter.ingest` 一致。
+
+        隔离承载：`agent_id` → owner，`shared=True` → visibility="shared"。
+        不再依赖 tag 前缀做隔离，但 tag 仍然写进 metadata（前端展示与偏好查询要用）。
+        """
+        meta_tags = list(tags or [])
+        if agent_id:
+            meta_tags.append(f"agent:{agent_id}")
+        if shared:
+            meta_tags.append("shared")
+
+        mtype = type if type in _VALID_TYPES else "concept"
+        if not title:
+            title = self._derive_title(content) or ""
+
+        if shared:
+            guard_shared_write(self, agent_id, content, mtype, meta_tags)
+
+        metadata = {"tags": meta_tags, "foxclaw_type": mtype}
+        if "confidence" in kwargs:
+            metadata["confidence"] = kwargs["confidence"]
+
+        retention = "immutable" if mtype == "execution" else "decay"
+        topic_key = kwargs.get("topic_key") or (
+            _PREFERENCE_TAG if _PREFERENCE_TAG in meta_tags else "")
+
+        with self._lock:
+            return self._vr.add(
+                content=content,
+                wing=self.wing,
+                importance=kwargs.get("importance"),
+                ui_summary=(title or "")[:200],
+                metadata=metadata,
+                memory_type=_FOXCLAW_TO_VR.get(mtype, "semantic"),
+                visibility="shared" if shared else "private",
+                owner=(agent_id or "") if not shared else "",
+                retention_policy=retention,
+                topic_key=topic_key,
+            )
+
+    def _visible(self, mem, agent_id: str | None, include_shared: bool) -> bool:
+        """可见性判定，与 vecRecall `_visible_to` 规则保持同源。
+
+        - shared 记忆：仅当 include_shared 时可见
+        - private 记忆：owner 为空(老数据)视为公开；否则必须等于当前 agent
+        - agent_id 为空：不过滤（与 HMR 路径 `if agent_id:` 的行为一致）
+        """
+        vis = getattr(mem, "visibility", "private") or "private"
+        owner = getattr(mem, "owner", "") or ""
+        if not agent_id:
+            return True
+        if vis == "shared":
+            return include_shared
+        return owner == agent_id or not owner
+
+    def recall(self, query: str = "", agent_id: str | None = None, top_k: int = 5,
+               include_shared: bool = True, **kwargs):
+        """统一召回，返回 list[dict]。
+
+        走 `build_context(viewer=...)` 而不是 `search()`：前者在 L1/L2/L3 全层按
+        visibility+owner 过滤，是**召回前**生效的隔离；`search()` 源码里明写
+        "不经过任何结构过滤"，拿它做按 Agent 召回会越权。
+
+        只取 L2+L3：L1 是"全库 importance top-15 + immutable 全额并入"，与当前
+        query 无关，混进来会挤占 top_k。
+        """
+        fetch_k = min(max(top_k * 5, 20), 100) if agent_id else top_k
+        results = []
+        try:
+            with self._lock:
+                bundle = self._vr.build_context(
+                    current_query=query or "",
+                    load_l2=True,
+                    load_l3=bool(query and query.strip()),
+                    viewer=agent_id,
+                )
+                results = list(getattr(bundle, "l2_topic_context", []) or []) + \
+                          list(getattr(bundle, "l3_deep_results", []) or [])
+                if not results and (query or "").strip():
+                    results = list(self._vr.search(query, n=fetch_k) or [])
+        except Exception:
+            return []
+
+        out, seen = [], set()
+        for r in results:
+            mem = getattr(r, "memory", None)
+            if mem is None:
+                continue
+            mid = getattr(mem, "id", "")
+            if not mid or mid in seen:
+                continue
+            if not self._visible(mem, agent_id, include_shared):
+                continue
+            seen.add(mid)
+            row = self._memory_to_row(mem)
+            row["score"] = round(float(getattr(r, "score", 0.0) or 0.0), 4)
+            out.append(row)
+
+        out.sort(key=lambda x: x.get("score", 0.0), reverse=True)
+        return out[:top_k]
+
+    def _memory_to_row(self, mem) -> dict:
+        """Memory → Foxclaw 的召回结果结构。"""
+        meta = getattr(mem, "metadata", None) or {}
+        tags = [t for t in (meta.get("tags") or []) if isinstance(t, str)]
+        owner = getattr(mem, "owner", "") or ""
+        if owner and f"agent:{owner}" not in tags:
+            tags.append(f"agent:{owner}")
+        shared = (getattr(mem, "visibility", "") == "shared")
+        if shared and "shared" not in tags:
+            tags.append("shared")
+        ftype = (meta.get("foxclaw_type")
+                 or _VR_TO_FOXCLAW.get(getattr(mem, "memory_type", ""), "concept"))
+        return {
+            "id": getattr(mem, "id", ""),
+            "title": (getattr(mem, "ui_summary", "") or "")[:120],
+            "content": getattr(mem, "content", "") or "",
+            "type": ftype,
+            "confidence": meta.get("confidence", 1.0),
+            "tags": tags,
+            "shared": shared,
+        }
+
+    def recall_by_tag(self, agent_id=None, tag="preference", limit=8, include_shared=True):
+        """按 tag 精确拉取（不做语义排序），用于"总是注入"的偏好类记忆。
+
+        vecRecall 的硬边界禁止用 wing/topic 结构过滤**检索**，但偏好本来就不该做
+        语义模糊匹配 —— 它走 `query_by_topic_key`（精确、时间序），语义反而更准。
+        非偏好 tag 退化为全量列表筛选，避免调用方拿到静默的空结果。
+        """
+        mems = []
+        try:
+            with self._lock:
+                if tag == _PREFERENCE_TAG:
+                    mems = list(self._vr.query_by_topic_key(tag, wing=self.wing) or [])
+                if not mems:
+                    listed = self._vr.list_memories(wing=self.wing, limit=500,
+                                                    full=True, sort="recent")
+                    for d in (listed.get("memories") or []):
+                        t = (d.get("metadata") or {}).get("tags") or []
+                        if tag in t:
+                            mems.append(SimpleNamespace(
+                                id=d.get("id", ""), content=d.get("content", ""),
+                                metadata=d.get("metadata") or {},
+                                visibility=d.get("visibility", "private"),
+                                owner="", timestamp=d.get("timestamp", ""),
+                                ui_summary=d.get("ui_summary", ""),
+                                memory_type=d.get("memory_type", ""),
+                            ))
+        except Exception:
+            return []
+
+        rows = []
+        for m in mems:
+            if not self._visible(m, agent_id, include_shared):
+                continue
+            row = self._memory_to_row(m)
+            row["_ts"] = getattr(m, "timestamp", "") or ""
+            rows.append(row)
+
+        rows.sort(key=lambda x: str(x.get("_ts")), reverse=True)
+        deduped, seen_c = [], set()
+        for x in rows:
+            if x["content"] in seen_c:
+                continue
+            seen_c.add(x["content"])
+            deduped.append(x)
+        return deduped[:limit]
+
+    def delete_memory(self, memory_id):
+        with self._lock:
+            try:
+                return bool(self._vr.delete(memory_id))
+            except Exception:
+                return False
+
+    def recent(self, limit: int = 20) -> list:
+        """最近的记忆条目（新→旧），供前端右栏"记忆信息条"。"""
+        rows = []
+        try:
+            with self._lock:
+                listed = self._vr.list_memories(wing=self.wing, limit=max(1, int(limit)),
+                                                full=True, sort="recent")
+        except Exception:
+            return []
+        for d in (listed.get("memories") or []):
+            meta = d.get("metadata") or {}
+            tags = [t for t in (meta.get("tags") or []) if isinstance(t, str)]
+            agent = ""
+            for t in tags:
+                if t.startswith("agent:"):
+                    agent = t.split(":", 1)[1]
+                    break
+            title = (d.get("ui_summary") or "").strip()
+            if not title or self._AUTO_TITLE.match(title):
+                title = self._derive_title(d.get("content") or "") or title
+            rows.append({
+                "id": d.get("id", ""),
+                "type": meta.get("foxclaw_type") or _VR_TO_FOXCLAW.get(
+                    d.get("memory_type", ""), ""),
+                "title": title[:120],
+                "summary": (d.get("ui_summary") or d.get("content_preview")
+                            or d.get("content") or "")[:180],
+                "agent": agent,
+                "shared": d.get("visibility") == "shared",
+                "created_at": str(d.get("timestamp") or ""),
+            })
+        return rows
+
+    def get_workspace(self, agent_id: str):
+        return SimpleNamespace(agent_id=agent_id, active_goal="", status="idle",
+                               push_task=lambda _t: None)
+
+    def save_workspace(self, agent_id: str):
+        return None
+
+    def save_runtime_state(self, **kwargs):
+        return None
+
+    def restore_runtime_state(self):
+        return None
+
+    def get_system_status(self):
+        return {"backend": self.backend, "version": self.version, "wing": self.wing}
+
+    def stats(self) -> dict:
+        """记忆统计：前端记忆中心展示真实数字。字段与 HMRAdapter.stats 一致。"""
+        total = shared_count = relations = 0
+        by_agent: dict[str, Any] = {}
+        embedding = type(self._emb).__name__
+        try:
+            with self._lock:
+                listed = self._vr.list_memories(wing=self.wing, limit=5000,
+                                                full=True, sort="recent")
+                mems = listed.get("memories") or []
+                total = int(listed.get("total") or len(mems))
+                for d in mems:
+                    if d.get("visibility") == "shared":
+                        shared_count += 1
+                    for t in ((d.get("metadata") or {}).get("tags") or []):
+                        if isinstance(t, str) and t.startswith("agent:"):
+                            aid = t.split(":", 1)[1] or "unknown"
+                            by_agent[aid] = by_agent.get(aid, 0) + 1
+                g = ((self._vr.stats() or {}).get("graph") or {})
+                for k in ("edges", "total_edges", "relations"):
+                    if isinstance(g.get(k), int):
+                        relations = g[k]
+                        break
+        except Exception:
+            pass
+        return {
+            "backend": self.backend,
+            "version": self.version,
+            "total_memories": int(total),
+            "relations": int(relations),
+            "shared": int(shared_count),
+            "private": int(max(total - shared_count, 0)),
+            "by_agent": by_agent,
+            "embedding": embedding,
+        }
+
+    def close(self):
+        with self._lock:
+            closer = getattr(self._vr, "close", None)
+            if closer is not None:
+                try:
+                    closer()
+                except Exception:
+                    pass

package/python/foxclaw/core/verify.py

@@ -0,0 +1,173 @@
+"""执行后核验:这一步到底做成了没有,以及凭什么这么说。
+
+病根:工具返回一段文本,模型接着把它写成"已完成"。可这段文本**既不是成功证明,
+也不是失败证明**——它只是工具说了什么。于是出现了审核报告里记的那类静默假成功:
+发送没发出去、写入没落盘,回答里照样写"已搞定"。人只有事后翻记录才发现。
+
+这里给每个工具结果一个**三态结论** + 可展开的证据:
+  · ``verified``   —— 拿到了可核对的后置条件(如搜索结果里的来源链接、命中的本地文件);
+  · ``unverified`` —— 执行没报错,但**没有可观察的后置条件**(写/发送/支付类),
+                      此时模型不许断言"已完成",只能描述"我执行了什么";
+  · ``failed``     —— 明确失败/认不出来。
+
+刻意不做的事:
+- **不猜**。没有后置条件的工具就是 ``unverified``,不会因为文本里有"成功"二字就转成
+  ``verified``——那句"成功"是工具自己写的,不是证据。
+- **不解析自然语言断言**。不去从模型答案里抽取"已完成"再逐个核对(那要靠第二次 LLM
+  调用,既慢又会编);证据只从**工具真实返回**里抽,绑在步骤上,由 UI 展示给人看。
+"""
+from __future__ import annotations
+
+import os
+import re
+import time
+from dataclasses import dataclass, field
+from urllib.parse import urlparse
+
+from . import failure_policy as _policy
+from typing import Callable
+
+VERIFIED = "verified"
+UNVERIFIED = "unverified"
+FAILED = "failed"
+
+MAX_EVIDENCE = 8
+
+_URL_RE = re.compile(r"https?://[^\s<>\"'）)\]}]+")
+_WIN_PATH_RE = re.compile(r"[A-Za-z]:[\\/][^\s\"'<>|*?，。；]+")
+_POSIX_PATH_RE = re.compile(r"(?<![\w:])/(?:[\w.\-]+/)+[\w.\-]+")
+
+
+@dataclass(frozen=True)
+class Evidence:
+    """一条可核对的凭据:一个链接、一个真实存在的文件、或一次工具的原始命中。"""
+
+    kind: str
+    ref: str
+    label: str
+    source: str
+    at: float = field(default_factory=time.time)
+
+    def to_dict(self) -> dict:
+        return {"kind": self.kind, "ref": self.ref, "label": self.label,
+                "source": self.source, "at": self.at}
+
+
+@dataclass
+class Verification:
+    """一次工具调用的核验结论。"""
+
+    status: str
+    reason: str = ""
+    evidence: list[Evidence] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return self.status == VERIFIED
+
+    def to_dict(self) -> dict:
+        return {"status": self.status, "reason": self.reason,
+                "evidence": [e.to_dict() for e in self.evidence]}
+
+
+def _label_for_url(url: str) -> str:
+    try:
+        host = urlparse(url).netloc
+        return host[4:] if host.startswith("www.") else host or url[:40]
+    except Exception:
+        return url[:40]
+
+
+def _paths_in(text: str) -> list[str]:
+    out: list[str] = []
+    for m in _WIN_PATH_RE.finditer(text or ""):
+        out.append(m.group(0).rstrip(".,;:，。；："))
+    for m in _POSIX_PATH_RE.finditer(text or ""):
+        out.append(m.group(0).rstrip(".,;:，。；："))
+    return out
+
+
+def extract_evidence(source: str, text: str, limit: int = MAX_EVIDENCE) -> list[Evidence]:
+    """从工具返回文本里抽可核对的证据。
+
+    只认两类硬凭据:URL(去重、截断到 8 条)与**磁盘上确实存在**的路径。
+    正文摘要不算证据——那是工具的自述,不是可复核的事实。
+    """
+    seen: set[str] = set()
+    out: list[Evidence] = []
+    for m in _URL_RE.finditer(text or ""):
+        url = m.group(0).rstrip(".,;:!?，。；：！？")
+        key = url.split("#", 1)[0]
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(Evidence("url", url, _label_for_url(url), source))
+        if len(out) >= limit:
+            return out
+    for p in _paths_in(text):
+        if p in seen:
+            continue
+        try:
+            if not os.path.exists(p):
+                continue
+        except Exception:
+            continue
+        seen.add(p)
+        out.append(Evidence("file", p, os.path.basename(p), source))
+        if len(out) >= limit:
+            break
+    return out
+
+
+_CHECKERS: dict[str, Callable[..., tuple[bool, str]]] = {
+    "web_search": lambda args, text: (
+        (True, "") if _URL_RE.search(text or "")
+        else (False, "搜索结果没有可核对的来源链接")),
+    "recall_memory": lambda args, text: (
+        (True, "") if (text or "").strip().startswith("【召回的相关记忆】")
+        else (False, "未返回记忆条目")),
+}
+
+
+def verify(name: str, args: dict | None, text: str,
+           capability: dict | None = None) -> Verification:
+    """给一次工具调用的结果下结论(不抛异常:核验本身失败时不拖垮工具轮)。"""
+    kind = _policy.classify(text)
+    if kind not in (_policy.OK, _policy.UNKNOWN):
+        return Verification(FAILED, reason=f"失败类型:{kind}")
+    if kind == _policy.UNKNOWN:
+        return Verification(FAILED, reason="认不出的返回(不当作成功)")
+
+    ev = extract_evidence(name, text)
+    checker = _CHECKERS.get(name)
+    if checker is not None:
+        try:
+            passed, why = checker(args or {}, text or "")
+        except Exception:
+            passed, why = False, "后置条件检查自身出错"
+        if not passed:
+            return Verification(UNVERIFIED, reason=why, evidence=ev)
+        return Verification(VERIFIED, evidence=ev)
+
+    read_only = bool((capability or {}).get("read_only"))
+    if read_only:
+        return Verification(VERIFIED, evidence=ev)
+    return Verification(UNVERIFIED, reason="该工具未声明可观察的后置条件", evidence=ev)
+
+
+def note_for_model(v: Verification, read_only: bool = False) -> str:
+    """给模型的硬提示。**只对未核验/失败**追加;已验证的成功结果一个字都不改。
+
+    ``read_only`` 决定未核验时要不要训话:只读工具的"没核对到来源"照样记进证据区
+    (UI 显示未核验),但不往结果文本里塞提示 —— 否则每条搜索/记忆命中都会多一段
+    劝诫,既挤占上下文又改变既有行为。**有副作用**的未核验必须训:那才是"没做成
+    却可能被写成做成了"的地方。
+    """
+    if v.status == VERIFIED:
+        return ""
+    if v.status == FAILED:
+        return f"[核验] 该步骤未成功({v.reason}),不要向用户声称它已完成。"
+    if read_only:
+        return ""
+    return (f"[核验] 该步骤执行了但没有可核对的凭据({v.reason})。"
+            f"只描述你执行了什么,不要断言「已完成/已成功」。")