"""观测台账:每次工具调用一条不可篡改记录,并索引所有返回过的字段值。 这是“数据真实性核验”的后端事实来源: * ``calls`` —— 调用级记录,``prev_hash`` + ``hash`` 构成哈希链; * ``value_index`` —— 调用返回值里的每个字段值一行,供核验层按 ``(call_id, row_index, field, value)`` 精确反查; * ``ledger.jsonl`` —— 追加式落盘副本,便于离线审计或被外部系统消费。 没有登记在台账里的数字,一律视为“无来源”。 """ from __future__ import annotations import hashlib import json import sqlite3 from pathlib import Path from .config import settings from .db import database def _sha256(text: str) -> str: return "sha256:" + hashlib.sha256(text.encode("utf-8")).hexdigest() def _canonical(payload: object) -> str: return json.dumps(payload, sort_keys=True, ensure_ascii=False, default=str) def _to_float(value: object) -> float | None: try: if isinstance(value, bool): return None return float(str(value).replace(",", "")) except (TypeError, ValueError): return None class Ledger: """调用台账。""" def __init__(self, path: str | Path | None = None) -> None: self.path = Path(path or settings.ledger_path) self.enabled = settings.ledger_jsonl if self.enabled: self.path.parent.mkdir(parents=True, exist_ok=True) # ------------------------------------------------------------------ writing def record( self, call_id: str, tool: str, args: dict, result: dict, *, object_ids: list[str] | None = None, session_id: str = "", rows: list[dict] | None = None, verdict_hint: str = "", ) -> dict: """登记一次调用。``rows`` 用于建立字段级索引。""" with database.connect() as connection: previous = connection.execute("SELECT hash FROM calls ORDER BY rowid DESC LIMIT 1").fetchone() prev_hash = previous["hash"] if previous else "" result_hash = _sha256(_canonical(result)) args_hash = _sha256(_canonical(args)) entry_hash = _sha256(f"{prev_hash}|{call_id}|{tool}|{args_hash}|{result_hash}|{session_id}") with database.transaction() as connection: connection.execute( "INSERT OR REPLACE INTO calls(call_id,tool,args_hash,args_json,result_hash,result_json,object_ids," "verdict_hint,prev_hash,hash,session_id,created_at) VALUES(?,?,?,?,?,?,?,?,?,?,?,datetime('now','localtime'))", ( call_id, tool, args_hash, _canonical(args), result_hash, _canonical(result)[:200000], json.dumps(object_ids or [], ensure_ascii=False), verdict_hint, prev_hash, entry_hash, session_id, ), ) if rows: self._index_values(connection, call_id, session_id, rows) entry = { "call_id": call_id, "tool": tool, "args_hash": args_hash, "result_hash": result_hash, "object_ids": object_ids or [], "session_id": session_id, "prev_hash": prev_hash, "hash": entry_hash, } if self.enabled: with self.path.open("a", encoding="utf-8") as handle: handle.write(json.dumps(entry, ensure_ascii=False) + "\n") return entry @staticmethod def _index_values(connection: sqlite3.Connection, call_id: str, session_id: str, rows: list[dict]) -> None: entries: list[tuple] = [] for row in rows: trace = row.get("_trace") or {} values = row.get("values") or {} for field, value in values.items(): if value is None: continue entries.append( ( call_id, session_id, str(trace.get("object_id") or ""), str(trace.get("table") or ""), int(trace.get("row_index", -1)), str(field), str(value), _to_float(value), ) ) if entries: connection.executemany( "INSERT INTO value_index(call_id,session_id,object_id,table_name,row_index,field,value_text,value_num) " "VALUES(?,?,?,?,?,?,?,?)", entries, ) # ------------------------------------------------------------------ reading def get(self, call_id: str) -> dict | None: with database.connect() as connection: row = connection.execute("SELECT * FROM calls WHERE call_id=?", (call_id,)).fetchone() if not row: return None item = dict(row) item["args"] = json.loads(item.pop("args_json") or "{}") item["result"] = json.loads(item.pop("result_json") or "{}") item["object_ids"] = json.loads(item["object_ids"] or "[]") return item def session_calls(self, session_id: str) -> list[dict]: with database.connect() as connection: rows = connection.execute( "SELECT call_id,tool,args_hash,result_hash,object_ids,verdict_hint,created_at,hash " "FROM calls WHERE session_id=? ORDER BY rowid", (session_id,), ).fetchall() return [dict(row) for row in rows] def find_value(self, value: str, session_id: str = "", tolerance: float = 1e-9) -> list[dict]: """在一个会话的台账里反查字段值,返回命中明细。""" number = _to_float(value) with database.connect() as connection: if number is not None: rows = connection.execute( "SELECT call_id,object_id,table_name,row_index,field,value_text,value_num FROM value_index " "WHERE session_id=? AND value_num IS NOT NULL AND ABS(value_num - ?) <= ? " "ORDER BY rowid DESC LIMIT 50", (session_id, number, tolerance * max(1.0, abs(number))), ).fetchall() if rows: return [dict(row) for row in rows] rows = connection.execute( "SELECT call_id,object_id,table_name,row_index,field,value_text,value_num FROM value_index " "WHERE session_id=? AND value_text=? ORDER BY rowid DESC LIMIT 50", (session_id, str(value)), ).fetchall() return [dict(row) for row in rows] def find_calculation(self, calculation_id: str) -> dict | None: item = self.get(calculation_id) if not item or item["tool"] != "calculator": return None return item def chain_ok(self, limit: int = 200) -> bool: """校验哈希链(运维自检用)。""" with database.connect() as connection: rows = connection.execute( "SELECT call_id,tool,args_hash,result_hash,session_id,prev_hash,hash FROM calls ORDER BY rowid LIMIT ?", (limit,), ).fetchall() previous = "" for row in rows: expected = _sha256( f"{row['prev_hash']}|{row['call_id']}|{row['tool']}|{row['args_hash']}|{row['result_hash']}|{row['session_id']}" ) if row["prev_hash"] != previous or row["hash"] != expected: return False previous = row["hash"] return True def stats(self) -> dict: with database.connect() as connection: calls = connection.execute("SELECT COUNT(*) FROM calls").fetchone()[0] values = connection.execute("SELECT COUNT(*) FROM value_index").fetchone()[0] last = connection.execute("SELECT call_id,tool,created_at FROM calls ORDER BY rowid DESC LIMIT 1").fetchone() return { "calls": calls, "indexed_values": values, "last_call": dict(last) if last else None, "chain_ok": self.chain_ok(limit=min(calls, 500)), } ledger = Ledger()