Files
AgentLab/backend/app/ledger/store.py
T
ThearchyHelios 5b4bd91476 口径账本内核:运行封存后在后台比对已发布口径、逐个数标口径、按运行读的账本接口、来源链和导出留痕、统计 E1–E4
为什么:问数据的答案要和已治理口径接起来(next-round 02 做法 2、3、9、10;总方案 X1、X2、X3、X12,拍板 L2、L4、L8)。

- 比对(ledger/match.py):探索运行(chat、canvas、trial、personal_app)成功结束、封存完、有查询快照时,在 runner 封存之后和
  notify_run 同一个位置放到后台;候选口径是每个工作流最新的已发布未退役版本里查库的调用工具节点(受管、已发布都算),按数据源
  和表预筛;逐个用 match_template 比,schema 用查询当时冻结的表结构、列名取同一份快照里冻结的数据目录。每次运行限时 8 秒、在
  线程里、同时最多 2 个;超时、快照被改过或读不出、SQL 解析不了照实记 skipped。启动时(run_manager.setup,和调度循环同一个开关)
  补比最近 7 天封存了却没比过的运行,只读工件和版本表。
- 记法(ledger/store.py,拍板 L8):内容寻址工件 kind=caliber_match(agentlab.caliber_match/1)+ run_append 的 sealed 方式追加
  ledger.matched(core/events.py 登记);工件里不放时间和工作流名,同一份封存再比一次哈希一样;meta 记 calibers / related / counts。
- 标签(ledger/labels.py):单元格按查询的比对状态;指标要每个输入都等价于同一份口径同一版、绑定一致,式子按「哪个取数节点、
  第几行、哪一列」换完和口径卡上的一字不差。caliber(how:independent 等价已证明;composed 助手选用留给第 3 波)/ related /
  reasoning / unknown;整题判断附还缺的入口字段。
- 读(ledger/view.py):GET /api/runs/{id}/ledger(ledger_api.runs_router,和证据同一道门),没比对过、能比的按需排上;证据
  片段接口加 ledger 键(没比对过的运行没有这个键,返回一字不差);报告导出的面板最上面多「口径」一步并写明「封存后比对,不在
  封存范围内」。遮罩按读的那一刻重滤:绑定的值是这次运行查到过的遮罩值时不给值,差异条目和逐行对照走 _Shown。
- 来源链:POST /api/runs 加 origin_ref(只在 origin=chat 时收,服务端核对对话访问权和轮次归属,写进 Run.origin 和封存的
  run.origin);WorkflowIn 加 origin(run_id、conversation_id、turn_id,核对规则同 from-run);报告导出和可验证报告下载各记一条
  审计 report.exported。可验证报告列封存后追加的事件时给 ledger.matched 一句只有条数的说明。
- 统计(ledger/stats.py):E1–E4 从工件、运行、查询快照、审计现算,GET /api/ledger/stats(搭建者);E3 用 app/chat/questions
  的聚类加按(数据源、normalize_sql 文本)的确定性重复;评测直接调 compute_stats(可点名 run_ids)。对账反馈、认证转化、按发布
  的召回在后面几波,照实写没有数据。

测试:test_ledger_match.py(真跑探索运行:等价、相关、没有相关口径、写死的码值、非探索运行、超时、快照被改、解析失败、预筛、
指标两种、级别、只认最新版、补比)、test_ledger_api.py(账本接口、按需比、遮罩、证据片段、导出、审计、统计)、
test_run_origin_ref.py(origin_ref 与画布来源的核对)。
2026-10-16 14:02:55 +08:00

145 lines
7.2 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""口径账本的记法(docs/design/next-round/02-口径账本.md 做法 2,拍板 L8):比对结果存成内容寻址工件,不建新表。
一次比对 = 一份工件 kind=caliber_match(格式 agentlab.caliber_match/1)+ 一条封存之后追加的事件 ledger.matched
{artifact, manifest_hash, algo, counts, trigger}(engine/run_append 的 sealed 方式,同按需裁判的 evidence.judged):
- 工件内容只放比对本身:运行 id、对着哪一次封存(manifest_hash / manifest_seq)、算法版本、考虑过的口径版本(工作流、版本、
级别、graph_hash)、每条查询的状态和绑定、差异条目、列映射、每个数的标签、整题判断。不放时间、耗时、工作流名(名字会改,
界面读的时候再取):同一份封存、同一个算法版本、同一批口径,再比一次得到的工件一字不差、哈希一样。
- 工件引用的 meta 记 {calibers: [等价已证明的「工作流@版本」], related: [相关的], counts}:召回按旧版本反查、统计按种类数,
都只扫 artifacts(kind 有索引),不逐份读内容。
- 事件说的是「这一次封存的这份比对」:读的时候只认 manifest_hash 等于运行现在封存的那几条,取最后一条(之后口径有变、补比
过的,以最新的为准)。工件读不出、被改过、不是这次运行这次封存的,照实说读不出,不拿它标数。
trigger 是谁触发的:sealed(运行封存后马上比的)、backfill(启动时补比)、on_demand(打开账本时按需比的)。后两种是事后按
那时的口径回看的,界面据此写「按现在的口径回看」。它只在事件里,不进工件内容(不然同一份比对因为触发方式不同哈希就不同)。
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Any
from sqlalchemy import select
from app.core.events import EventType
from app.db.base import SessionLocal
from app.db.models import Run, RunEvent
#: 工件的种类和内容格式
KIND = "caliber_match"
FORMAT = "agentlab.caliber_match/1"
#: 比对算法的版本:绑定、证明、标签的规则改了就加一,界面和统计据此分得清是哪一版算法比的
ALGO = "1"
#: 触发方式(见模块说明)
TRIGGERS = ("sealed", "backfill", "on_demand")
@dataclass(frozen=True)
class Recorded:
"""一次运行现在这次封存的最新一份比对。content 读不出时为 None,problem 写为什么。"""
artifact: str
seq: int
ts: Any
trigger: str
algo: str | None
content: dict[str, Any] | None
problem: str | None = None
@property
def retro(self) -> bool:
"""事后按那时的口径回看的(启动时补比、打开时按需比的),不是运行一封存就比的。"""
return self.trigger != "sealed"
#: 读不出比对工件时的说法
UNREADABLE = "比对记录读不出来(文件缺失)"
TAMPERED = "比对记录与哈希不一致,疑似被修改,不能用来标口径"
FOREIGN = "比对记录不属于这次运行的这次封存,不能用来标口径"
def counts_of(queries: list[dict[str, Any]]) -> dict[str, int]:
"""每种查询状态各几条(proven / composed / related / none / skipped),0 也写。"""
out = {status: 0 for status in ("proven", "composed", "related", "none", "skipped")}
for query in queries:
status = str(query.get("status") or "")
if status in out:
out[status] += 1
return out
def meta_of(content: dict[str, Any]) -> dict[str, Any]:
"""工件引用的 meta:{calibers: [等价已证明的「工作流@版本」], related: [相关的], counts}。"""
proven: list[str] = []
related: list[str] = []
for query in content.get("queries") or []:
for cand in query.get("candidates") or []:
key = str(cand.get("caliber") or "")
if not key:
continue
bucket = proven if cand.get("status") == "proven" else related
if key not in bucket:
bucket.append(key)
related = [key for key in related if key not in proven]
return {"calibers": sorted(proven), "related": sorted(related), "counts": counts_of(content.get("queries") or [])}
async def save(run_id: str, content: dict[str, Any], *, seal: tuple[int | None, str | None],
trigger: str) -> str | None:
"""存比对工件、追加 ledger.matched。返回工件 id;运行在比对期间换了封存(没抢到)时只存了工件、没追加事件,返回 None
(不算这次运行的比对:读的时候只认事件)。"""
from app.core.artifact_store import put_json
from app.engine.run_append import append_events
if trigger not in TRIGGERS:
raise ValueError(f"不认识的比对触发方式:{trigger}")
meta = meta_of(content)
artifact = await put_json(content, kind=KIND, run_id=run_id, meta=meta)
written = await append_events(run_id, [(EventType.LEDGER_MATCHED, None, {
"artifact": artifact, "manifest_hash": content.get("manifest_hash"), "algo": content.get("algo"),
"counts": meta["counts"], "trigger": trigger,
})], require="sealed", seal=seal)
return artifact if written else None
async def latest(run_id: str) -> Recorded | None:
"""这次运行现在这次封存的最新一份比对;没比对过(或者比对的是以前的封存)为 None。"""
from app.core.artifact_store import load
async with SessionLocal() as session:
manifest = await session.scalar(select(Run.manifest_hash).where(Run.id == run_id))
if not manifest:
return None
rows = (await session.execute(
select(RunEvent.seq, RunEvent.ts, RunEvent.data).where(
RunEvent.run_id == run_id, RunEvent.type == EventType.LEDGER_MATCHED)
.order_by(RunEvent.seq.desc()))).all()
for seq, ts, data in rows:
if not isinstance(data, dict) or data.get("manifest_hash") != manifest or not data.get("artifact"):
continue
artifact = str(data["artifact"])
trigger = str(data.get("trigger") or "sealed")
try:
content = load(artifact)
except ValueError:
return Recorded(artifact, seq, ts, trigger, data.get("algo"), None, TAMPERED)
if not isinstance(content, dict):
return Recorded(artifact, seq, ts, trigger, data.get("algo"), None, UNREADABLE)
if content.get("format") != FORMAT or content.get("run_id") != run_id \
or content.get("manifest_hash") != manifest:
return Recorded(artifact, seq, ts, trigger, data.get("algo"), None, FOREIGN)
return Recorded(artifact, seq, ts, trigger, data.get("algo"), content)
return None
async def matched_run_ids(session: Any, run_ids: list[str]) -> set[str]:
"""这几次运行里有过比对事件的(不管是哪一次封存的):启动补比据此跳过比过的。"""
if not run_ids:
return set()
rows = await session.execute(select(RunEvent.run_id).where(
RunEvent.run_id.in_(run_ids), RunEvent.type == EventType.LEDGER_MATCHED).distinct())
return {r for (r,) in rows}
__all__ = ["ALGO", "FORMAT", "KIND", "TRIGGERS", "Recorded", "counts_of", "latest", "matched_run_ids", "meta_of", "save"]