Files
AgentLab/backend/app/ledger/repository.py
T
ThearchyHelios 2f90f0eb3a 口径台账:固定执行、验证审阅发布与增量重导入
- QueryCore 固定执行(K09):按已发布的不可变口径跑一次,交回类型化标量、发布/manifest 引用与逐查询证据
- 依赖闭包(K08):按选中的指标算出要拷的取数节点、要的入口字段,接进 derive / compose / metrics
- SQL 模板参数完整性(K01):试跑、组合问数、派生图、运行时取数共用一套语义,缺参数在渲染前就拒
- 受限字段变更服务(K03)与口径领域边界(K01):改动打在整图深拷贝上,身份与证据归属不可改
- 版本化受控模板绑定(K04):业务口径按显式绑定落到 SQL,对不上就报 unsupported / needs_update
- 验证记录(K05)与最小审阅:样例匹配不等于正式批准,审批人只从服务端身份取
- 发布依据清单(K07):发布时按不可变图物化内容寻址清单,正式用途按它判
- 增量重导入(K11)与 B/L/R 三方合并、受限自然语言修改提案(K12):只产候选,落图仍走既有写路径
- 接口与前端:口径草稿页接上字段变更、绑定状态、验证与重导入,新增 caliber-drafts / studio 检查脚本

验证:前端 tsc -b 通过。
2026-11-10 15:05:18 +08:00

154 lines
7.7 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.
"""口径的领域边界(K03、A01):一份口径卡按卡和指标说话,不说节点、data.config 和路径。
图仍是唯一真相(A01:每份口径只有一个权威写入源)。GraphBackedCaliberRepository 在图上给一层很薄的领域接口:
按卡 id 打开一张源头口径卡、按稳定 metric_id 读一条指标、把改过的这几条换回去——换在**整图的深拷贝**上,
没提到的字段、别的指标、别人加的扩展字段和其他节点原样带着走。这里不做整图 ↔ 领域模型的双向转换,也不另存一份
可编辑的定义:那就是第二份真相,A01 明令禁止。
只认源头口径卡:转抄别处的口径卡(caliber_from,ledger/compose 内联实例化出来的那些)不是权威写入源,改它等于
在别处另存一份定义。指标的完整身份是「卡 + 卡上的 metric_id」(4.1),所以这里所有读写都同时带着这两个。
定义指纹用现成的 data/caliber_identity(只按语义字段算,空值不进哈希):变更服务据此说「这次动没动定义」,
不另造一套指纹。
"""
from __future__ import annotations
import copy
from collections.abc import Mapping
from dataclasses import dataclass
from typing import Any
class CaliberGone(ValueError):
"""图里没有这张可写的口径卡:不在图上、不是口径卡节点,或者是转抄别处的口径卡(不是权威写入源)。"""
class MetricGone(LookupError):
"""这张口径卡上没有这个 metric_id。"""
@dataclass(frozen=True)
class CaliberCard:
"""一张源头口径卡的身份:图上的节点 id、给人看的标题、口径名和口径版本。"""
node_id: str
title: str
caliber: str
caliber_version: str
def _config_of(node: Any) -> dict[str, Any]:
"""节点上的配置(图的原始形状 data.config);没有或者不是对象时交回空的那一份(读的时候不改图)。"""
data = node.get("data") if isinstance(node, Mapping) else None
config = data.get("config") if isinstance(data, Mapping) else None
return config if isinstance(config, dict) else {}
class GraphBackedCaliberRepository:
"""一张源头口径卡在图上的一层薄领域接口。构造时就把卡定位好,定位不到直接 CaliberGone。"""
def __init__(self, graph: Mapping[str, Any] | None, *, card_id: str) -> None:
self._graph = graph if isinstance(graph, dict) else {}
self.card_id = str(card_id or "")
self._node = self._card_node()
def _card_node(self) -> dict[str, Any]:
for node in self._graph.get("nodes") or []:
if not isinstance(node, dict) or str(node.get("id")) != self.card_id:
continue
if node.get("type") != "metrics":
raise CaliberGone(f"图上这个节点不是口径卡:{self.card_id}")
if _config_of(node).get("caliber_from") not in (None, "", {}):
raise CaliberGone("这张卡是从别处转抄来的口径:要改的是它抄的那一份")
return node
raise CaliberGone(f"图上没有这张口径卡:{self.card_id}")
@property
def card(self) -> CaliberCard:
data = self._node.get("data") if isinstance(self._node.get("data"), dict) else {}
config = _config_of(self._node)
return CaliberCard(node_id=self.card_id, title=str(data.get("label") or self.card_id),
caliber=str(config.get("caliber") or ""),
caliber_version=str(config.get("caliber_version") or ""))
def ids(self) -> list[str]:
"""卡上的 metric_id,按它们在图里的先后(重排只改顺序,不改 ID)。没有 id 的条目(画布上留下的半成品)跳过。"""
return [str(metric["id"]) for metric in self._metrics()
if isinstance(metric, dict) and str(metric.get("id") or "").strip()]
def metrics(self) -> list[dict[str, Any]]:
"""卡上每条指标的深拷贝(顺序照图里)。"""
return [copy.deepcopy(metric) for metric in self._metrics()]
def metric(self, metric_id: str) -> dict[str, Any]:
"""一条指标的深拷贝;卡上没有它时 MetricGone。调用方随便改这一份,图不动。"""
wanted = str(metric_id or "")
for metric in self._metrics():
if isinstance(metric, dict) and str(metric.get("id") or "") == wanted:
return copy.deepcopy(metric)
raise MetricGone(wanted)
def graph_copy(self) -> dict[str, Any]:
"""整图的深拷贝:调用方(变更服务)把改过的那一份交回去保存,原图不动。"""
return copy.deepcopy(self._graph)
def replace_node_configs(self, configs: Mapping[str, Mapping[str, Any]]) -> dict[str, Any]:
"""换掉图上这几个取数节点的 data.config(node_id → 整份新配置),交回整图的深拷贝。
K04 的绑定同步用:调用方(ledger/bindings.plan)给的新配置是在**原配置的深拷贝**上只改两处得来的,
所以节点上别的键(tool、args 里别的项、扩展字段)、别的地方一个字不动。指到图里没有的节点时 KeyError——
这是服务端的 bug,照实抛出去,不当成一次成功的同步。
"""
graph = copy.deepcopy(self._graph)
nodes = {str(node.get("id")): node for node in graph.get("nodes") or [] if isinstance(node, dict)}
for node_id, config in configs.items():
node = nodes.get(str(node_id))
if node is None:
raise KeyError(f"图上没有这个节点:{node_id}")
data = node.get("data")
if not isinstance(data, dict):
data = node["data"] = {}
data["config"] = copy.deepcopy(dict(config))
return graph
def replace_metrics(self, metrics: Mapping[str, Mapping[str, Any]]) -> dict[str, Any]:
"""换掉 map 里这几条指标(metric_id → 整条指标),交回**整图的深拷贝**:别的节点、别的指标、图级扩展
字段和这条指标里没被换掉的键都在。map 里有卡上不存在的 id 时 MetricGone——首版不支持用字段操作新增指标。"""
wanted = {str(key): value for key, value in metrics.items()}
known = set(self.ids())
for metric_id in wanted:
if metric_id not in known:
raise MetricGone(metric_id)
graph = copy.deepcopy(self._graph)
node = next(item for item in graph.get("nodes") or [] if str(item.get("id")) == self.card_id)
data = node.get("data")
if not isinstance(data, dict):
data = node["data"] = {}
config = data.get("config")
if not isinstance(config, dict):
config = data["config"] = {}
replaced: list[Any] = []
for metric in self._metrics_of(node):
metric_id = str(metric.get("id") or "") if isinstance(metric, dict) else ""
replaced.append(copy.deepcopy(wanted[metric_id]) if metric_id in wanted else metric)
config["metrics"] = replaced
return graph
def definition_hash(self) -> str:
"""这张卡的指标定义指纹(data/caliber_identity:只取语义字段,空值不进哈希,指标按 id 排序)。"""
from app.data.caliber_identity import definition_hash
card = self.card
return definition_hash(card.caliber, card.caliber_version, self._metrics())
def _metrics(self) -> list[Any]:
return self._metrics_of(self._node)
@staticmethod
def _metrics_of(node: Mapping[str, Any]) -> list[Any]:
metrics = _config_of(node).get("metrics")
return metrics if isinstance(metrics, list) else []
__all__ = ["CaliberCard", "CaliberGone", "GraphBackedCaliberRepository", "MetricGone"]