合入 W3-b 口径账本闭环:caliber_from.nodes 改名映射;问数据的助手 use_caliber 选用已发布口径(服务端确定性内联实例化);按口径正式出具(自动只给问数据的答案)与口径对账;认证队列、固化成口径草稿、发布后补比;账本统计补上对账与认证转化;使用者的原始运行记录只给问数据的运行

This commit is contained in:
ThearchyHelios
2026-10-16 18:45:45 +08:00
34 changed files with 3985 additions and 100 deletions
+27 -6
View File
@@ -117,7 +117,8 @@ async def _look_service(session: AsyncSession, payload: GenerateIn, sources: lis
spec = await copilot_model_spec(session, payload, max_tokens=copilot_context.PICK_MAX_TOKENS)
return await copilot_context.look_service(sources, spec=spec, graph=graph, kinds=kinds,
answer=payload.intent == "answer", catalog_view=catalog_view,
trail={"conversation_id": getattr(payload, "conversation_id", None)})
trail={"conversation_id": getattr(payload, "conversation_id", None)},
session=session)
NODE_REFERENCE = """\
@@ -200,7 +201,8 @@ NODE_REFERENCE = """\
{{ nodes.报告节点id.text }}),审批卡会附上这份报告的核对概况
- validate:JSON Schema 校验,可自动让模型修复。config: {schema, source, max_retries}
- transform:数据整形。config: {mode: expression|template|json, expression/template, assign_to}
- subgraph:嵌套另一个工作流。config: {workflow_id, input}
- subgraph:嵌套另一个工作流。config: {workflow_id, workflow_version, input}:workflow_version 写固定的版本号(1、2…),
不写就跟随那个工作流最新的发布版本。问数据里不要拿子工作流去拼已发布的口径(子工作流里的数报告引用不到)
- metrics:口径卡。报告里要出现的数字、以及所有派生计算(比率、增幅、占比、差值)都登记在这里。
config: {caliber, caliber_version, metrics:[{id, name, unit, decimals, format, expression}], on_missing, assign_to}
expression 是受限表达式(不是模板):vars.kpi.gmv、cell(nodes.fetch, 0, 'gmv')、
@@ -817,7 +819,9 @@ def _graph_system(sources: list[Any], scope: set[str] | None, datasources: str,
"5. 能用 3 个节点解决就别堆 8 个"
f"{_CHAT_USER_PROMPT if chat_user else ''}\n\n"
f"{_STREAM_PROTOCOL}"
+ (f"\n\n{looks.guide()}\n{copilot_context.LOOK_WHEN_PROMPT}" if looks.kinds else "")
# 问数据里能选用已发布口径时(next-round 02 做法 4):协议多一段 use_caliber,「什么时候该看」换成问数据那一份
+ (f"\n{copilot_context.USE_CALIBER_PROMPT}" if copilot_context.composing(looks) else "")
+ (f"\n\n{looks.guide()}\n{copilot_context.look_when(looks)}" if looks.kinds else "")
)
@@ -1700,12 +1704,16 @@ async def answer_ops(payload: GenerateIn, *, catalog_view: Any = None):
# 比对工具绑定的基准:画布上是改之前的图;问数据页是上一轮的图(沿用它的节点 id)
baseline = copy.deepcopy(
(payload.base_graph or {}).get("nodes") or (prev_graph or {}).get("nodes") or [])
# 查看服务:读目录、读能力登记在开流之前做完。现有工作流(画布上的原图、问数据追问时上一轮的图)查过的表列在概览里
# 查看服务:读目录、读能力登记在开流之前做完。现有工作流(画布上的原图、问数据追问时上一轮的图)查过的表列在概览里。
# 问数据另看已发布口径、可以 use_caliber 选用(next-round 02 做法 4):只给搭建者及以上——使用者的图里看得到拷进来的
# 取数 SQL(口径的 SQL 可能写着遮罩值),这一波不给
kinds = ("table", "capability", "caliber") if payload.intent == "answer" and not chat_user \
else ("table", "capability")
looks = await _look_service(session, payload, sources, graph=payload.base_graph if (
payload.base_graph or {}).get("nodes") else prev_graph, catalog_view=view)
payload.base_graph or {}).get("nodes") else prev_graph, catalog_view=view, kinds=kinds)
# 这一份 system 一直用到最后:接着写、自查修正都沿用,不换
system = _graph_system(sources, scope, await copilot_context.section(looks), looks, chat_user=chat_user)
applier = GraphApplier(nodes, edges)
applier = GraphApplier(nodes, edges, composer=copilot_context.composer(looks))
started = time.monotonic()
gen = Generation(model, system=system, applier=applier, looks=looks, started=started,
checker=GraphChecker(applier, scope=scope, sources=sources, baseline=baseline, checkers=checkers,
@@ -2454,6 +2462,10 @@ class FromRunIn(BaseModel):
#: 问数据回答上点「做成应用」时带上:这次运行出自哪段对话的哪一轮,记进新工作流的来源(workflows.origin)
conversation_id: str | None = None
turn_id: str | None = None
#: 固化成口径草稿(next-round 02 做法 8,app/ledger/certify.freeze):报告引用的查询变成固定 SQL 的取数节点,跨轮变化
#: 的字面量成为参数(不保留 Agent)。peers 是同一组(同一个 SQL 形状)的别的运行,认哪些字面量位置变了
freeze: bool = False
peers: list[str] = Field(default_factory=list, max_length=50)
@router.post("/from-run")
@@ -2475,6 +2487,15 @@ async def extract_template(
# 对话只是记进来源:不能用的不让记(D-d),不存在的照旧记下 id
await _ensure_conversation_access(session, payload.conversation_id)
if payload.freeze:
# 固化成口径草稿:取数是固定的 SQL(以后比对认得出等价),不是保留 Agent 的执行路径
from app.ledger.certify import CertifyRefused, freeze
try:
return await freeze(session, payload.run_id, peers=payload.peers, name=payload.name,
conversation_id=payload.conversation_id, turn_id=payload.turn_id)
except CertifyRefused as e:
raise HTTPException(e.status_code, e.message) from e
try:
path = await extract_run_path(session, payload.run_id)
except PathRefused as e:
+50 -4
View File
@@ -10,7 +10,10 @@
模型,数据类请求一次查看到位。
**各入口看什么**(总方案 §5.3):画布、问数据看表和能力(问数据只列只读能力);发布前修复、升级证据看表,由系统按要修
的 SQL 代为查看(look 文档 D5);应用润色看工作流版本和能力(在 copilot.py 里组装)。
的 SQL 代为查看(look 文档 D5);应用润色看工作流版本和能力(在 copilot.py 里组装)。问数据另看已发布口径(next-round 02
做法 4:搭建者及以上;使用者发起的图里看得到拷进来的取数 SQL,这一波不给):助手可以 use_caliber 选用一份口径做骨架,
「什么时候该看」换成 LOOK_WHEN_ANSWER_PROMPT,输出协议多 USE_CALIBER_PROMPT 一段。运行时写 SQL 的 Agent 不看口径(拍板
L2:保持独立解读,「等价已证明」才有意义)。
这里提供:look_service(按入口组装查看服务,开流之前调:读目录、读能力登记要用会话)、section(system 里数据源那一节)、
system_look(系统代为查看)、写 SQL 的硬性要求和「什么时候该看」的判断标准。
@@ -59,6 +62,23 @@ LOOK_WHEN_PROMPT = """\
· 用户说了一条数据事实:先看那张表的现有目录,再提目录修改
· 要看就先看,看完再规划,不要先搭节点再回头看;这次对话里已经看过的表直接点名看,不要只给需求"""
#: 问数据里(能看已发布口径时)的「什么时候该看」:问数据那一条按口径账本改写(next-round 02 做法 4 ④),别的照旧
LOOK_WHEN_ANSWER_PROMPT = LOOK_WHEN_PROMPT.replace(
""" · 问数据:查库交给 agent 节点,它运行时会自己查表结构。只有从概览看不出该用哪个库、用户点了表名、用户说了口径时
才看一次,把看到的表名写进 agent 的提示词,运行时少走弯路""",
""" · 问数据:先看已发布口径(kind 写 caliber)。问法和口径的定义完全对得上时用 use_caliber 选用它;口径只覆盖问题的
一部分时 use_caliber 选用那一部分,其余交给 agent 补;问法多了口径没有的条件(比如「含退款」「只看新客」)时不要套
口径,交给 agent 去查,系统会自动拿它的 SQL 和口径对账。查库交给 agent 时它运行时会自己查表结构:只有从概览看不出
该用哪个库、用户点了表名时才看表,把看到的表名写进 agent 的提示词""")
#: 问数据里输出协议多的一段:选用口径(ledger/compose.py)。只在这一轮能看已发布口径时接在协议后面
USE_CALIBER_PROMPT = """- 选用已发布口径(只在问数据里、look 过 caliber 之后):
{"op":"use_caliber","id":"c1","workflow_id":"…","version":3,"card":"口径卡节点 id","metrics":["指标id"],"inputs":{"字段":"值"}}
照抄查看结果里给的写法,只改 id、metrics、inputs。系统按那一版生成取数节点(c1_<原 id>)和口径卡(节点 id 就是 c1),
并把入口连到取数、取数连到口径卡;你**不要**自己写这几个节点,也不要改它们。接下来只需把口径卡连到报告
(add_edge c1 → report),报告里用 [[m:指标id]] 引用。inputs 按口径的入口字段填(日期、门店这类问题里给出的条件),
填不对会被拒收、原因会交回给你改;口径对不上问法时不要选用"""
#: 系统代为查看时写进记录的需求(界面上显示)
SYSTEM_LOOK_FIX_NEED = "要修的工作流里,查库节点的 SQL 用到的表"
SYSTEM_LOOK_UPGRADE_NEED = "要升级的工作流里,查库节点的 SQL 用到的表"
@@ -66,22 +86,48 @@ SYSTEM_LOOK_UPGRADE_NEED = "要升级的工作流里,查库节点的 SQL 用
async def look_service(sources: list[Any], *, spec: ModelSpec | None, graph: Mapping[str, Any] | None = None,
kinds: tuple[str, ...] = ("table", "capability"), answer: bool = False,
catalog_view: Any = None, trail: Mapping[str, Any] | None = None) -> LookService:
catalog_view: Any = None, trail: Mapping[str, Any] | None = None,
session: Any = None) -> LookService:
"""按入口组装这一轮的查看服务。读目录、读能力登记都用各自的短会话,开流前后都能调。
spec 是助手的模型规格:挑选模型第一次要用时才按它拿(关思考、额度按 look/pick.PICK_MAX_TOKENS)。graph 是现有工作流,概览里列出它查过的表。
answer:问数据(意图为回答),能力只列只读的。catalog_view:表详情里给哪一份数据目录(data/catalog_view.py),不给是当前目录。
trail:按需加入探查范围时的留痕(哪一轮对话:{conversation_id};谁取这次请求的身份)。
kinds 里有 caliber 时用 session(调用方开流之前的会话)读已发布口径,问数据里另判能不能组合(look/calibers 的 compose)。
"""
from app.look.calibers import CaliberKind
picker = Picker(spec)
made: list[Any] = []
if "table" in kinds:
made.append(await TableKind.load(sources, graph=graph, picker=picker, catalog_view=catalog_view, trail=trail))
if "capability" in kinds:
made.append(await CapabilityKind.load(picker=picker, read_only=answer))
if "caliber" in kinds and session is not None:
made.append(await CaliberKind.load(session, picker=picker, compose=answer))
return LookService(made)
def composing(looks: LookService) -> bool:
"""这一轮能不能选用已发布口径(问数据里读好了能组合的口径卡)。"""
kind = looks.kinds.get("caliber")
return kind is not None and getattr(kind, "options", None) is not None
def look_when(looks: LookService) -> str:
"""「什么时候该看」:能选用已发布口径的问数据用改写过的那一份。"""
return LOOK_WHEN_ANSWER_PROMPT if composing(looks) else LOOK_WHEN_PROMPT
def composer(looks: LookService) -> Any | None:
"""GraphApplier 用的组合器(ledger/compose.Composer);这一轮不能选用口径时为 None。"""
if not composing(looks):
return None
from app.ledger.compose import Composer
return Composer(list(looks.kinds["caliber"].options))
async def section(looks: LookService) -> str:
"""system 里数据源那一节:各类对象的概览,有数据源时再加写 SQL 的硬性要求。什么都没有时是空串,不占提示词。"""
overview = await looks.overview()
@@ -105,6 +151,6 @@ async def system_look(looks: LookService, graph: Mapping[str, Any] | None, sourc
__all__ = [
"LOOK_WHEN_PROMPT", "SQL_RULES_PROMPT", "SYSTEM_LOOK_FIX_NEED", "SYSTEM_LOOK_UPGRADE_NEED", "graph_tables",
"look_service", "section", "system_look",
"LOOK_WHEN_ANSWER_PROMPT", "LOOK_WHEN_PROMPT", "SQL_RULES_PROMPT", "SYSTEM_LOOK_FIX_NEED", "SYSTEM_LOOK_UPGRADE_NEED",
"USE_CALIBER_PROMPT", "composer", "composing", "graph_tables", "look_service", "look_when", "section", "system_look",
]
+93 -2
View File
@@ -255,14 +255,30 @@ class GraphApplier:
- skipped_types:模型编出来的节点类型,收尾时说出来
patches:目录修改提案转不转(只有用户亲口说了数据事实的画布、问数据才转)。
composer:问数据里能选用已发布口径时(ledger/compose.Composer,next-round 02 做法 4)。use_caliber 由它按那一版确定性
实例化成取数节点和口径卡,这里落地:节点、连线照 add_node / add_edge 记进 seen(兜底重放照样重放得出来),入口连到
第一个取数节点(入口还没加的话,等入口加了再接);转给界面的只是那一条 use_caliber,带上 result(选用了哪一版、生成了
哪几个节点)。不合规的拒收:result 写原因、照样转给界面(过程里照实写一行),原因记进 refused,自查时交回模型改
(GraphChecker.issues)。没有 composer 的入口(画布、发布前修复、升级)use_caliber 不认,照旧当认不出的操作丢掉。
"""
def __init__(self, nodes: dict[str, dict[str, Any]], edges: list[dict[str, Any]], *, patches: bool = True,
questions: bool = False) -> None:
questions: bool = False, composer: Any = None) -> None:
self.nodes = nodes
self.edges = edges
self.patches = patches
self.questions_mode = questions
self.composer = composer
#: 选用口径实例化出来的段:[(第一个取数节点, 全部节点 id)],接入口用
self.composed: list[tuple[str, list[str]]] = []
#: 已经落地的 use_caliber(ledger/compose.signature),接着写时重发的同一个不再落地
self._composed_ops: set[str] = set()
#: 系统接上的连线(入口 → 取数):模型再发一条一模一样的不重复加
self._wired: list[dict[str, Any]] = []
#: 拒收的 use_caliber:[{op, message}],自查时交回模型
self.refused: list[dict[str, Any]] = []
self._reported = 0
self.seen: list[dict[str, Any]] = []
self.tried: list[dict[str, Any]] = []
self.effective: list[dict[str, Any]] = []
@@ -305,11 +321,18 @@ class GraphApplier:
self.autorun = op.get("run") is not False
self.seen.append(op)
return Applied(False, True)
if kind == "use_caliber" and self.composer is not None:
return self._use_caliber(op)
if kind == "add_edge" and self._was_wired(op.get("edge") or {}):
# 入口 → 取数这条系统已经接上了
return Applied(False, False)
if self._continuing and self._repeats(op):
return Applied(False, False)
self.seen.append(op)
self.tried.append(op)
changed = _apply_op(self.nodes, self.edges, op)
if changed and kind == "add_node":
self._wire()
if changed:
self.effective.append(op)
nid = (op.get("node") or {}).get("id") if kind == "add_node" else op.get("id")
@@ -321,6 +344,56 @@ class GraphApplier:
self.skipped_types.append(str(bad))
return Applied(changed, changed)
def _use_caliber(self, op: dict[str, Any]) -> Applied:
"""选用一份已发布口径(见类说明)。op 原地写上 result,原样转给界面。"""
from app.ledger.compose import ComposeRefused, signature
sig = signature(op)
if sig in self._composed_ops:
return Applied(False, False)
try:
composed = self.composer.compose(op, taken=set(self.nodes))
except ComposeRefused as e:
op["result"] = {"status": "refused", "reason": e.message}
self.refused.append({"op": {k: v for k, v in op.items() if k != "result"}, "message": e.message})
return Applied(False, True, e.message)
self._composed_ops.add(sig)
primitive = [{"op": "add_node", "node": {"id": n["id"], "type": n["type"], "label": n["data"].get("label") or "",
"config": n["data"].get("config") or {}}} for n in composed.nodes]
primitive += [{"op": "add_edge", "edge": e} for e in composed.edges]
for item in primitive:
self.seen.append(item)
self.tried.append(item)
if _apply_op(self.nodes, self.edges, item):
self.effective.append(item)
ids = [str(n["id"]) for n in composed.nodes]
self.composed.append((ids[0], ids))
if composed.op_id not in self._landed:
self._landed.append(composed.op_id)
self._wire()
op["result"] = composed.result()
return Applied(True, True)
def _wire(self) -> None:
"""选用口径生成的取数节点还没有上游、图里已经有入口的:系统把入口连到第一个取数节点。"""
entry = next((nid for nid, n in self.nodes.items() if n.get("type") == "input"), None)
if entry is None:
return
for first, _ in self.composed:
if first in self.nodes and not any(e["target"] == first for e in self.edges):
edge = {"source": entry, "target": first, "sourceHandle": None}
self.edges.append(edge)
self._wired.append(edge)
def _was_wired(self, edge: dict[str, Any]) -> bool:
return any(w["source"] == edge.get("source") and w["target"] == edge.get("target") for w in self._wired)
def unreported(self) -> list[dict[str, Any]]:
"""还没交回过模型的拒收的选用,取走即算交回过(同 AppApplier.unreported)。"""
out = self.refused[self._reported:]
self._reported = len(self.refused)
return out
def _repeats(self, op: dict[str, Any]) -> bool:
"""接着写时和已落地完全相同的操作(look §2.5.5):已有的同一条连线、和已落地节点一模一样的节点、重发的同一个操作。"""
kind = op.get("op")
@@ -355,6 +428,7 @@ class GraphApplier:
for e in graph.get("edges") or []]
for op in self.seen:
_apply_op(self.nodes, self.edges, op)
self._wire()
class GraphChecker:
@@ -387,8 +461,9 @@ class GraphChecker:
async def issues(self) -> list[dict[str, Any]]:
errors = self.blocking()
refused = _refused_issues(self.applier)
if self.known is None:
return errors or []
return [*refused, *(errors or [])]
from app.engine.autofix import _sig
if not self.applier.effective:
@@ -405,6 +480,22 @@ class GraphChecker:
# 应用的落地
# ==========================================================================
#: 选用口径被拒时交回模型的说法
_REFUSED_FOR_MODEL = ("上一次的 use_caliber 被拒收:{message}。按原因改正后重新输出 use_caliber(id 可以沿用);这份口径对不上"
"问法的话就不要选用,交给 agent 查")
def _refused_issues(applier: Any) -> list[dict[str, Any]]:
"""拒收的 use_caliber 还没交回过模型的那几条,形状同自查的问题(error 级:不改就少了这一块)。"""
if not isinstance(applier, GraphApplier):
return []
from app.ledger.compose import REFUSED
return [{"level": "error", "node_id": None, "edge_id": None, "field": None, "code": REFUSED,
"message": f"没有选用口径:{r['message']}", "for_model": _REFUSED_FOR_MODEL.format(message=r["message"])}
for r in applier.unreported()]
APP_REPAIR_PROMPT = (
"这是你刚改好的应用草稿:\n{spec}\n\n"
"应用检查(和发布同一套规则)发现下面这些问题:\n{issues}\n\n"
+9 -6
View File
@@ -9,7 +9,7 @@
- can_read_run / can_read_artifact:运行、工件的读权限(user 角色只能读有授权的应用视图运行、自己参与的实例);
- ensure_role / ensure_can_publish:接口内部按请求内容判定的权限(MCP 的 stdio、受管级发布、版本退役,Q8);
- restricted():这次请求是不是开登录后的 user 角色(按请求内容收窄的接口用:问数据只能发起探索运行、工件按白名单给);
- run_events_readable(principal, run):运行的原始记录、事件、实时流能不能读(user 只读查询结果在工具边界遮过的);
- run_events_readable(principal, run):运行的原始记录、事件、实时流能不能读(user 只读查询结果在工具边界遮过的问数据运行);
- ensure_conversation_access(session, conversation_id):接受 conversation_id 的接口核对对话归属(对话按人隔离);
- run_scope / evidence_scope / chat_scope:main.py 挂在运行、证据、问数据几组路由上的依赖,按 run_id 判断能不能读。
run_scope 同样管运行的 WebSocket,握手时按运行判;
@@ -213,15 +213,18 @@ async def run_events_readable(principal: Principal, run: Any) -> bool:
"""能不能读这次运行的原始记录、事件和实时流(GET /api/runs/{id}、/events、/graph,WebSocket /stream)。
关登录:能。builder 及以上:这次运行它能读就能(can_read_run:别人的个人应用刷新、个人蓝图试运行读不了)。
user:这次运行它能读(can_read_run),而且查询结果在工具边界就遮过(masked_at_boundary)。两个条件缺一不可:
没在边界遮过的运行,事件里 tool.end 的预览、运行状态里是查询结果的原文,遮罩管不到——自己发起的应用实例、
有授权的应用视图运行经应用页和证据接口读(那两处按派生遮罩给)。实际上满足两条的就是它自己开登录后发起的
问数据运行;关登录时自报同名留下的老运行没在边界遮过,开了登录也读不到。"""
user:问数据的运行(origin_kind=chat),这次它能读(can_read_run),而且查询结果在工具边界就遮过(masked_at_boundary)。
三个条件缺一不可:没在边界遮过的运行,事件里 tool.end 的预览、运行状态里是查询结果的原文,遮罩管不到——自己发起的
应用实例、有授权的应用视图运行经应用页和证据接口读(那两处按派生遮罩给)。服务端替他派生的运行也带着边界遮罩,但图
不是他的助手搭的:口径对账(ledger/reconcile)的图里原样是口径取数节点的 SQL 模板(口径的 SQL 可能写着遮罩值,所以
问数据里使用者不看口径),同样经证据接口读(展示的 SQL 里写着的遮罩值换成「已遮罩」,同应用视图运行)。实际上满足
三条的就是它自己开登录后发起的问数据运行;关登录时自报同名留下的老运行没在边界遮过,开了登录也读不到。"""
if principal.mode == "off":
return True
if principal.at_least("builder"):
return await can_read_run(principal, run)
if run is None or not principal.username or not masked_at_boundary(run):
if run is None or not principal.username or getattr(run, "origin_kind", None) != "chat" \
or not masked_at_boundary(run):
return False
return await can_read_run(principal, run)
+8 -2
View File
@@ -1466,7 +1466,9 @@ def _located(locator: dict[str, Any]) -> list[tuple[Any, Any]]:
async def _caliber_source(source: Any) -> dict[str, Any] | None:
"""钉住别处口径卡(caliber_from)时,定义取自哪个工作流的哪一版;带上工作流现在的名字方便认。"""
"""钉住别处口径卡(caliber_from)时,定义取自哪个工作流的哪一版;带上工作流现在的名字方便认。取数节点拷进这张图时
改了名的(caliber_from.nodes,next-round 02 做法 4),来源里照带 nodes 映射:指标的输入写的是改名后的节点,面板据此
说清它们对应那一版里的哪个取数节点。"""
if not isinstance(source, dict) or not source.get("workflow_id"):
return None
async with SessionLocal() as session:
@@ -1478,7 +1480,11 @@ def _caliber_upgrade(event: dict[str, Any] | None) -> dict[str, Any] | None:
"""这张口径卡在正式运行发起时的升版处置:钉在哪一版、上游最新是哪一版、怎么处置的。"""
if not isinstance(event, dict):
return None
return {k: event.get(k) for k in ("workflow_id", "caliber_node", "pinned", "latest", "policy", "policy_label")}
out = {k: event.get(k) for k in ("workflow_id", "caliber_node", "pinned", "latest", "policy", "policy_label")}
if isinstance(event.get("caliber_nodes"), dict):
# 取数节点拷进这张图时改了名(caliber_from.nodes):照给映射;没改名的卡没有这个键,老运行一字不差
out["caliber_nodes"] = dict(event["caliber_nodes"])
return out
#: 双盲复算节点产出里一个指标的结果(engine/nodes/dual_check.py 的 SAME / DIFFERENT / UNCHECKED),原样交给界面
+91 -3
View File
@@ -3,10 +3,15 @@
不另建存储:ActionRecord 本身带着工作流、版本、graph_hash、能力版本、payload_hash、回执;「口径 → 应用」就是固定这一版的
应用版本。用在发布弹窗、退役确认、版本列表三处。
口径账本(docs/design/next-round/02-口径账本.md)在这里加两个只读接口:
口径账本(docs/design/next-round/02-口径账本.md)在这里加的接口:
- GET /api/runs/{run_id}/ledger(runs_router,和证据同一道门):一次运行里每个数的口径标签、整题判断、每条查询的比对、能做的
动作(app/ledger/view.py);
- GET /api/ledger/stats(router,搭建者):账本自身给出的统计 E1–E4,从比对工件、运行、审计现算(app/ledger/stats.py)。
动作、出具过的正式运行、对过的账(app/ledger/view.py);
- GET /api/ledger/stats(router,搭建者):账本自身给出的统计 E1–E4,从比对工件、运行、审计现算(app/ledger/stats.py);
- POST /api/ledger/answers/{run_id}/issue(answers_router,登录即可,第 3 波):按口径正式出具(app/ledger/issue.py,拍板
L1、L5:参数只从比对工件取,使用者只能按他有权使用的应用固定着的版本出具);
- POST /api/ledger/answers/{run_id}/reconcile(同上):口径对账,点开才跑一次确定性派生的只读图(app/ledger/reconcile.py);
- GET /api/ledger/certify-queue、POST /api/ledger/certify-queue/dismiss(router,搭建者,第 3 波):可沉淀的问题、「不是口径」
(app/ledger/certify.py)。这几个新接口都不放给访问密钥(auth/keys.KEY_ROUTES 不登记)。
"""
from __future__ import annotations
@@ -15,6 +20,7 @@ from typing import Any
from datetime import datetime
from fastapi import APIRouter, Depends, HTTPException, Query
from pydantic import BaseModel, Field
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
@@ -100,3 +106,85 @@ async def ledger_stats(since: datetime | None = Query(default=None, description=
origins = [o.strip() for o in (origin or "").split(",") if o.strip()] or None
return await compute_stats(session, since=since, until=until, origins=origins, principal=current_principal())
class IssueIn(BaseModel):
"""按哪份口径出具:只能选口径,参数由服务端从比对工件里取(不收客户端传的参数)。"""
workflow_id: str = Field(min_length=1, max_length=32)
version: int = Field(ge=1)
@answers_router.post("/{run_id}/issue")
async def issue_answer(run_id: str, payload: IssueIn) -> dict[str, Any]:
"""按口径正式出具这次问数据的答案(app/ledger/issue.py):经 launch_run 发起正式运行,来源 ledger_issue。同一运行、同一
口径、同一组参数只发起一次,再点交回已经发起的那一次(created 为假)。不能出具时回 409(整题不等价、版本退役、有人工
节点或写入、缺入口字段……)、403(权限不够:使用者只能按他有权使用的应用固定着的版本出具)、429(超过每日上限),
detail 写明原因。"""
from app.api.coded import CodedHTTPException
from app.api.deps import current_principal
from app.ledger import issue as ledger_issue
try:
run, created = await ledger_issue.issue(run_id, payload.workflow_id, payload.version,
principal=current_principal())
except ledger_issue.IssueRefused as e:
raise CodedHTTPException(e.status_code, e.message, e.code) from e
return {"run_id": run.id, "created": created, "issued": ledger_issue.issued_view(run)}
class ReconcileIn(BaseModel):
"""对哪条查询、和哪份相关口径对账。inputs + confirm:参数要核对时(动作里 needs_check)人核对、改过的参数;pairs:认不出
哪一列对哪个指标时人选的 [{ours: 这次的列, metric: 口径卡上的指标 id}](动作里写明要不要选)。"""
query: str = Field(min_length=1, max_length=64)
workflow_id: str = Field(min_length=1, max_length=32)
version: int = Field(ge=1)
inputs: dict[str, Any] | None = None
confirm: bool = False
pairs: list[dict[str, Any]] | None = None
@answers_router.post("/{run_id}/reconcile", status_code=201)
async def reconcile_answer(run_id: str, payload: ReconcileIn) -> dict[str, Any]:
"""口径对账(app/ledger/reconcile.py):按那一版口径确定性派生只读图,发起一次探索运行(来源 reconcile),差值在对账卡
里算。参数是推断出来的、不全的要先核对(409,code ledger_reconcile_check_inputs);认不出列怎么配的要人选(409,
ledger_reconcile_needs_pairs);多行时维度是遮罩列、键不唯一照实拒绝(409)。"""
from app.api.coded import CodedHTTPException
from app.api.deps import current_principal
from app.ledger import reconcile as ledger_reconcile
try:
run = await ledger_reconcile.reconcile(run_id, ledger_reconcile.Request(
query=payload.query, workflow_id=payload.workflow_id, version=payload.version, inputs=payload.inputs,
confirm=payload.confirm, pairs=payload.pairs), principal=current_principal())
except ledger_reconcile.ReconcileRefused as e:
raise CodedHTTPException(e.status_code, e.message, e.code) from e
return {"run_id": run.id, "reconciled": ledger_reconcile.reconciled_view(run)}
@router.get("/certify-queue")
async def certify_queue(session: AsyncSession = Depends(get_session)) -> dict[str, Any]:
"""可沉淀的问题(认证队列,app/ledger/certify.py):确定性重复的 SQL 形状、问题聚类、被反复用的答案。每项给代表问题、
轮次、(形状的)参数候选和相关口径;点过「不是口径」的不再列。固化走 POST /api/copilot/from-run(freeze: true)。"""
from app.api.deps import current_principal
from app.ledger import certify
return await certify.queue(session, principal=current_principal())
class DismissIn(BaseModel):
item_id: str = Field(min_length=1, max_length=64)
kind: str | None = Field(default=None, max_length=20)
note: str | None = Field(default=None, max_length=500)
@router.post("/certify-queue/dismiss")
async def certify_dismiss(payload: DismissIn, session: AsyncSession = Depends(get_session)) -> dict[str, Any]:
"""「不是口径」:记一条审计(ledger.certify.dismiss),这一项之后不再进队。"""
from app.ledger import certify
if payload.kind is not None and payload.kind not in certify.KINDS:
raise HTTPException(422, "可沉淀的问题只有三种:确定性重复、问题聚类、被反复用的答案")
await certify.dismiss(session, payload.item_id, kind=payload.kind, note=payload.note)
return {"ok": True, "item_id": payload.item_id}
+62
View File
@@ -718,6 +718,61 @@ async def apps_settings(session: AsyncSession) -> dict[str, Any]:
return apps_values(row.value if row else None)
# --------------------------------------------------------------------------
# 口径账本:按口径自动正式出具的开关、每日上限,口径比对的时限(docs/design/next-round/02-口径账本.md 做法 5、2)
# --------------------------------------------------------------------------
#: 设置里 ledger 这一组。auto_issue:问数据的答案整题等价于受管口径(Agent 独立写的 SQL 被证明等价、版本受管、图里没有人工
#: 节点和写入)时自动按口径发起一次正式运行(拍板 L1;不满足的只给一键)。issue_daily_limit:每天最多按口径正式出具几次
#: (自动的、一键的合计,0 表示不再出具):正式运行含报告撰写的模型费用。match_timeout_s:一次运行的口径比对最多算几秒,
#: 超时的照实记没比完(ledger/match.py)。召回的上限在第 4 波加。只有管理员能改(整个设置接口的改动都要管理员)
LEDGER_GROUP = "ledger"
LEDGER_DEFAULTS: dict[str, Any] = {"auto_issue": True, "issue_daily_limit": 20, "match_timeout_s": 8}
LEDGER_SETTING_LABEL = {"auto_issue": "自动按口径正式出具", "issue_daily_limit": "按口径正式出具每日上限",
"match_timeout_s": "口径比对时限(秒)"}
#: 时限的范围:太短比不完一份口径,太长占着比对的线程
LEDGER_TIMEOUT_RANGE = (1, 60)
def _timeout_ok(value: Any) -> bool:
return isinstance(value, (int, float)) and not isinstance(value, bool) \
and LEDGER_TIMEOUT_RANGE[0] <= value <= LEDGER_TIMEOUT_RANGE[1]
def ledger_problem(value: Any) -> str | None:
"""设置页写进来的 ledger 这一组有什么问题,没问题返回 None。"""
if not isinstance(value, dict):
return f"「口径账本」设置格式有误,需要是一个对象,当前为「{value}」"
for key, item in value.items():
if key not in LEDGER_DEFAULTS:
return (f"「口径账本」设置中不支持「{key}」,可设置的项:"
+ "、".join(f"「{LEDGER_SETTING_LABEL[k]}」" for k in LEDGER_DEFAULTS))
if key == "auto_issue" and not isinstance(item, bool):
return f"「{LEDGER_SETTING_LABEL[key]}」只能是开或关,当前为「{item}」"
if key == "issue_daily_limit" and not _daily_limit_ok(item):
return (f"「{LEDGER_SETTING_LABEL[key]}」需要是 0 到 {APPS_DAILY_LIMIT_MAX:,} 之间的整数(0 表示不再按口径出具),"
f"当前为「{item}」")
if key == "match_timeout_s" and not _timeout_ok(item):
return (f"「{LEDGER_SETTING_LABEL[key]}」需要是 {LEDGER_TIMEOUT_RANGE[0]} 到 {LEDGER_TIMEOUT_RANGE[1]} 之间的数,"
f"当前为「{item}」")
return None
def ledger_values(stored: Any) -> dict[str, Any]:
"""库里存的(或刚写进来的)ledger 一组 → 补齐默认;存坏了的项按默认(自动出具的开关存坏了按关,宁可少出具)。"""
stored = stored if isinstance(stored, dict) else {}
auto, limit, timeout = stored.get("auto_issue"), stored.get("issue_daily_limit"), stored.get("match_timeout_s")
return {"auto_issue": auto if isinstance(auto, bool) else (LEDGER_DEFAULTS["auto_issue"] if auto is None else False),
"issue_daily_limit": limit if _daily_limit_ok(limit) else LEDGER_DEFAULTS["issue_daily_limit"],
"match_timeout_s": timeout if _timeout_ok(timeout) else LEDGER_DEFAULTS["match_timeout_s"]}
async def ledger_settings(session: AsyncSession) -> dict[str, Any]:
"""设置里的 ledger 一组,没存过的补默认。按口径出具、比对从这里读。"""
row = await session.get(Setting, LEDGER_GROUP)
return ledger_values(row.value if row else None)
# --------------------------------------------------------------------------
# 用户设置
# --------------------------------------------------------------------------
@@ -763,6 +818,8 @@ DEFAULT_SETTINGS: dict[str, Any] = {
CATALOG_DRAFT_GROUP: catalog_draft_values(None),
# 应用:按需视图的每日上限、使用者能不能建个人应用(管理员在设置页改)
APPS_GROUP: apps_values(None),
# 口径账本:自动按口径正式出具的开关、每日上限,口径比对的时限
LEDGER_GROUP: ledger_values(None),
}
@@ -825,6 +882,7 @@ async def get_settings(session: AsyncSession = Depends(get_session)) -> dict[str
merged[PUBLIC_URL_GROUP] = public_url_values(stored.get(NOTIFY_GROUP))
merged[CATALOG_DRAFT_GROUP] = catalog_draft_values(stored.get(CATALOG_DRAFT_GROUP))
merged[APPS_GROUP] = apps_values(stored.get(APPS_GROUP))
merged[LEDGER_GROUP] = ledger_values(stored.get(LEDGER_GROUP))
for key, value in stored.items():
merged.setdefault(key, value)
return merged
@@ -924,6 +982,10 @@ async def put_settings(
if problem := apps_problem(payload.values[APPS_GROUP]):
raise HTTPException(422, problem)
payload.values[APPS_GROUP] = apps_values(payload.values[APPS_GROUP])
if LEDGER_GROUP in payload.values:
if problem := ledger_problem(payload.values[LEDGER_GROUP]):
raise HTTPException(422, problem)
payload.values[LEDGER_GROUP] = ledger_values(payload.values[LEDGER_GROUP])
if found := await _provider_problem(session, payload.values):
raise CodedHTTPException(422, found[1], PROVIDER_INVALID, field=found[0])
for key, value in payload.values.items():
+4
View File
@@ -576,6 +576,10 @@ async def commit_publish(session: AsyncSession, workflow: Workflow, snapshot: Wo
workflow.published_version = snapshot.version
workflow.published_by = actor
await session.commit()
# 口径账本(next-round 02 做法 8):从问数据固化出的口径发布了,来源运行在后台按它补比一次(不挡发布)
from app.ledger.certify import after_publish
after_publish(workflow.id, workflow.origin)
return {
"ok": True,
"level": level,