mirror of
https://github.com/ThearchyHelios/AgentLab.git
synced 2026-11-16 21:41:59 +00:00
050bea4b72
一、一键升级(只给预览,不自动保存)
- engine/upgrade.py:确定性改写,纯函数、重复执行结果不变
- R1 契约的叙述指向模型调用节点 → 换成报告撰写节点(system 和 prompt 合成写作要求,模型配置照搬),契约改成 report_from
- R2 没有契约、但模型写的文字进了出口,而且上游有取数 → 同样换成报告撰写
- R3 input → 智能体 → 出口(问数据的典型图)→ 中间插入报告撰写节点,出口字段接报告的正文;
只改直接相连的出口,经过别的节点读它的出口原样保留并写明原因
- R4 配了 output_schema 的智能体 → 打开 cite_fields
- R5 代码节点的产出被口径卡读 → 不改,只建议标成取数,等人确认
- 一个叙述里混了几个写作者的,不猜,整步不做并写明原因
- POST /api/copilot/upgrade-evidence:返回改动、说明和改完的检查结果;assist 时再交给 Copilot 把纯算术的代码节点
改写成口径卡表达式,不是纯算术的保留并给警告
- 升级和发布前修复走同一道「不许降低要求」的检查,只多两个由升级点名的例外:模型调用换成报告撰写、R3 改接的那条连线;
改完不能更糟
- 校验对符合 R1–R4 的旧结构给一条建议「可以升级为可追溯结构」,不算提示、不挡发布
- Copilot 自查:报告撰写节点上游没有任何能引用数字的来源时打回
二、界面
- 问题面板的快速修复「升级为可追溯结构(预览改动)」:逐项写「节点 · 字段:原值 → 新值」,节点类型的变化写成
「模型调用 → 报告撰写」,新插的节点和改接的连线另外写明;「应用」后走现有的保存,全图默认不丢
- 画布改过、存失败、画布被锁都有明确状态;保存失败后手动存成功会清掉「没存上」的提示,
画布和预览对不上时「重试保存」不再盲存;校验接口失败时升级块照样在
- 记录页里没有逐段证据的运行给横幅「这次的报告没有逐段证据 → 升级这张图」,跳到编排页并打开升级预览
- 修掉一处旧缺陷:应用修复时只换配置、不换节点类型,模型调用换成报告撰写后存下去的还是模型调用
三、受管门禁:cells 一键选
- 图里没有口径卡、契约又没写 cells: true 的受管图,以前能过门禁、正式运行却每次失败;现在门禁拦下,
发布弹窗给两个选项:写 cells: true,或交给 Copilot 改成口径卡指标(人亲手选的不算替人打开,Copilot 自己打开照样拦)
- 「修完要更好」的复核不再把改完才冒出来、只能由人拍板的这一处算作改坏:Copilot 补上契约、把 cells 留给人问,
这一步会被采用,不再被判「冒出新的问题」作废
四、测试
- 开发依赖加上 pytest-xdist(锁文件只多了 pytest-xdist 和 execnet):全量后端测试 -n auto 约 16 秒,原来串行约 2 分钟
- 修掉并行下暴露的一处测试竞态:运行先落终态、再另一个事务封存,测试改成等封存完成再核对
678 lines
37 KiB
Python
678 lines
37 KiB
Python
from __future__ import annotations
|
||
|
||
import re
|
||
from collections import defaultdict
|
||
from typing import Any, Callable
|
||
|
||
from sqlalchemy import func, select
|
||
from sqlalchemy.ext.asyncio import AsyncSession
|
||
|
||
from app.engine.schema import (
|
||
CLAIMS_JUDGE,
|
||
GraphNode,
|
||
GraphSpec,
|
||
NodeType,
|
||
ValidationResult,
|
||
_caliber_inputs,
|
||
claims_problem,
|
||
contract_needs_metrics,
|
||
judge_problems,
|
||
type_label,
|
||
validate_graph,
|
||
)
|
||
|
||
# 口径升版的三种合法处置。没有默认值是刻意的:升版最容易静默翻车的地方
|
||
# 就是"上周和这周的数其实不可比,但报表看起来一切正常"。
|
||
UPGRADE_POLICIES = {"recompute", "dual", "incomparable"}
|
||
|
||
UPGRADE_POLICY_LABELS = {
|
||
"recompute": "用新口径回算历史",
|
||
"dual": "并排双印新旧口径",
|
||
"incomparable": "标注与历史不可比",
|
||
}
|
||
|
||
|
||
def lint_for_publish(spec: GraphSpec, *, level: str) -> ValidationResult:
|
||
"""发布门禁。
|
||
|
||
published:基础可运行性之外只给警告。
|
||
governed:受管模板,出具用的那一档 —— 把关节层的自由度收进边界里,
|
||
错误会挡住发布。
|
||
|
||
每条问题带机器编号(code):发布前自动修复(engine/autofix.py)按它认问题、出修复,
|
||
文案可以改,编号不能随便改。证据门禁 G1–G5 见 _lint_evidence。
|
||
"""
|
||
result = ValidationResult()
|
||
strict = level == "governed"
|
||
|
||
def flag(message: str, *, code: str, node_id: str | None = None, hard: bool = False,
|
||
field: str | None = None) -> None:
|
||
result.add(message, level="error" if (hard and strict) else "warning", node_id=node_id,
|
||
field=field, code=code)
|
||
|
||
has_contract_output = False
|
||
for node in spec.nodes:
|
||
cfg = node.config
|
||
# 文案用画布上的叫法:节点标题 +(节点类型),参数写界面上的选项文字
|
||
who = f"「{node.title}」({type_label(node.type)})"
|
||
if node.type == NodeType.SUPERVISOR:
|
||
# 全动态规划属于探索层。受管模板里出现它,等于把 XAgent 搬上了生产线。
|
||
flag(
|
||
f"{who}:受管模板不允许全动态规划的节点——谁来做、做几轮都由模型临场"
|
||
"决定,属于探索层。改用固定编排的 Agent 或「模型调用」节点",
|
||
code="governed.supervisor", node_id=node.id, hard=True,
|
||
)
|
||
elif node.type == NodeType.SUBGRAPH:
|
||
if not cfg.get("workflow_version"):
|
||
flag(
|
||
f"{who}没有钉住版本,口径会随上游最新版漂移。在节点里选定一个版本",
|
||
code="governed.subgraph_unpinned", node_id=node.id, hard=True, field="workflow_version",
|
||
)
|
||
elif node.type == NodeType.AGENT:
|
||
tools = cfg.get("tools") or []
|
||
if cfg.get("approval") == "never" and tools:
|
||
flag(
|
||
f"{who}的审批策略是「全部自动放行」,受管模板要求危险工具至少人工确认。"
|
||
"改成「仅危险工具需要审批」",
|
||
code="governed.agent_approval_never", node_id=node.id, hard=True, field="approval",
|
||
)
|
||
elif cfg.get("approval") in (None, "") and spec.defaults.get("approval") == "never" and tools:
|
||
# 节点自己没写,运行时跟随全图默认(context.approval_mode:节点 > 图级 defaults > 全局)。
|
||
# 全图默认写着全部自动放行,这个 agent 就是全部自动放行,只是没写在它自己身上
|
||
flag(
|
||
f"{who}没写自己的审批策略,跟随全图默认的「全部自动放行」,受管模板要求危险工具至少"
|
||
"人工确认。把全图默认改成「仅危险工具需要审批」,或者在这个节点上单独设置",
|
||
code="governed.default_approval_never", node_id=node.id, hard=True, field="approval",
|
||
)
|
||
if not tools:
|
||
flag(f"{who}没有配任何可用工具,通常意味着它该是个「模型调用」节点",
|
||
code="governed.agent_no_tools", node_id=node.id, field="tools")
|
||
elif len(tools) > 10:
|
||
flag(
|
||
f"{who}的可用工具有 {len(tools)} 个,边界过宽(白名单衰减的前兆)",
|
||
code="governed.agent_tools_wide", node_id=node.id, field="tools",
|
||
)
|
||
elif node.type == NodeType.OUTPUT:
|
||
contract = cfg.get("contract")
|
||
if contract:
|
||
has_contract_output = True
|
||
_lint_contract(contract, node_id=node.id, spec=spec, flag=flag, strict=strict)
|
||
elif node.type == NodeType.CODE:
|
||
if cfg.get("network"):
|
||
flag(f"{who}打开了「允许联网」:受管模板建议把取数收敛到「调用工具」节点"
|
||
"(那里有取数快照)", code="governed.code_network", node_id=node.id, field="network")
|
||
|
||
_lint_evidence(spec, flag, strict=strict)
|
||
|
||
if strict and not has_contract_output:
|
||
result.add(
|
||
"受管模板至少要有一个「成果 / 出具」节点声明出具契约,否则三档出具无从谈起",
|
||
level="error", code="governed.no_contract",
|
||
)
|
||
return result
|
||
|
||
|
||
def publish_issues(spec: GraphSpec, *, level: str) -> list[Any]:
|
||
"""发布时拦的全部问题:validate_graph 和 lint_for_publish 的并集,顺序也照发布接口。
|
||
|
||
发布、发布前检查、自动修复复核都走这一个口径——检查说能发的,真发布时不会被拦。
|
||
"""
|
||
gate = lint_for_publish(spec, level=level).issues
|
||
return [*_not_repeated(validate_graph(spec).issues, gate, spec), *gate]
|
||
|
||
|
||
#: validate 里和门禁 G4、G5 说同一件事的两条提示(schema.evidence_issues)
|
||
_REPEATS = frozenset({"evidence.caliber_compute_input", "evidence.cite_fields_off"})
|
||
|
||
|
||
def _not_repeated(issues: list[Any], gate: list[Any], spec: GraphSpec) -> list[Any]:
|
||
"""门禁已经点了名的,validate 那条同义的提示不再列:门禁那条带编号、带修复,一处问题只说一遍。
|
||
|
||
G5 落在 agent 上,validate 那条也落在 agent 上;G4 落在喂数的沙箱代码上,validate 那条落在口径卡读它的
|
||
那条指标上,按口径卡的输入对回去。没被门禁覆盖的(比如不给口径卡供数的 agent)照旧提示。
|
||
"""
|
||
cited = {i.node_id for i in gate if i.code == "governed.caliber_agent_cite_fields"}
|
||
compute = {i.node_id for i in gate if i.code == "governed.caliber_compute_input"}
|
||
covered = {("evidence.cite_fields_off", nid, "output_schema") for nid in cited}
|
||
for card in spec.nodes:
|
||
if card.type == NodeType.METRICS and compute:
|
||
covered |= {("evidence.caliber_compute_input", card.id, f"metrics[{i}].expression")
|
||
for i, producer in _caliber_inputs(card, spec) if producer.id in compute}
|
||
return [i for i in issues if i.code not in _REPEATS or (i.code, i.node_id, i.field) not in covered]
|
||
|
||
|
||
def _lint_contract(
|
||
contract: Any, *, node_id: str, spec: GraphSpec, flag: Any, strict: bool
|
||
) -> None:
|
||
"""契约要查内容,不能只查这个 key 在不在。
|
||
|
||
只看 key 存不存在的话,contract={"metrics_from": "随便一个字符串"} 就满足
|
||
"受管模板必须声明出具契约"这条硬门禁了 —— 一个结构上保证每次都出 formal 的
|
||
空壳模板,能合法发布成受管模板。门禁写成这样,还不如没有:它给的是
|
||
"这张图过过闸"的错觉。
|
||
"""
|
||
if not isinstance(contract, dict):
|
||
flag("出具契约必须是一个 JSON 对象", code="contract.not_object", node_id=node_id, hard=True,
|
||
field="contract")
|
||
return
|
||
|
||
metric_nodes = {n.id for n in spec.nodes if n.type == NodeType.METRICS}
|
||
sources = contract.get("metrics_from") or []
|
||
if isinstance(sources, str):
|
||
sources = [sources]
|
||
|
||
if not sources and contract_needs_metrics(contract):
|
||
flag("出具契约没有声明 metrics_from(指标来自哪个「口径卡」节点),叙述里的数字无从回指",
|
||
code="contract.metrics_from_missing", node_id=node_id, hard=True, field="contract.metrics_from")
|
||
for src in sources:
|
||
if src not in metric_nodes:
|
||
flag(
|
||
f"出具契约的 metrics_from 指向 {src!r},但工作流里没有这个「口径卡」节点"
|
||
"(写错了,或者那个节点还没建)",
|
||
code="contract.metrics_from_invalid", node_id=node_id, hard=True, field="contract.metrics_from",
|
||
)
|
||
|
||
# 引用模式(report_from)核对的是报告撰写节点产出的文档,数字回指靠文档里的引用标记,
|
||
# 用不上 narrative。report_from 指错了(不是报告撰写节点、不在出口上游)由 validate_graph
|
||
# 报 error(contract.report_from_invalid),发布时两者一起过,照样挡住
|
||
if contract.get("report_from") in (None, "") and not str(contract.get("narrative") or "").strip():
|
||
flag("出具契约既没有声明 report_from(核对哪个「报告撰写」节点的文档),也没有声明 narrative"
|
||
"(叙述),数字回指校验不会执行", code="contract.report_from_missing", node_id=node_id, hard=True,
|
||
field="contract.report_from")
|
||
|
||
# 引用模式下整张图没有口径卡(只引查询单元格的问数据图):没有指标可列,strict + cells 已经保证
|
||
# 每个数点得开出处、对不上就不予出具(用户 2026-09-29 拍板)。有口径卡的照旧要列必需指标——
|
||
# 按图里有没有口径卡判,不按契约写没写 metrics_from,免得不写 metrics_from 就绕过去
|
||
cells_only = contract.get("report_from") not in (None, "") and not metric_nodes
|
||
if strict and not (contract.get("required") or []) and not cells_only:
|
||
flag(
|
||
"受管模板的出具契约必须声明 required(必需指标),否则「不予出具」这一档永远触发不了",
|
||
code="contract.required_missing", node_id=node_id, hard=True, field="contract.required",
|
||
)
|
||
# 没有口径卡的图,报告里的数只能直接引用查询单元格;受管正式运行不认没声明的单元格引用,
|
||
# 报告撰写节点(numbers strict、on_violation fail)每次都会失败。写不写要作者定:修复给选项
|
||
if strict and cells_only and contract.get("cells") is not True:
|
||
flag(
|
||
"这张图没有口径卡,报告里的数只能直接引用查询单元格:受管出具要在契约里写 cells: true,"
|
||
"否则正式运行里一个数都引用不了,报告撰写节点每次都会失败(也可以加一张口径卡,把数登记成指标)",
|
||
code="contract.cells_undeclared", node_id=node_id, hard=True, field="contract.cells",
|
||
)
|
||
if strict and not contract.get("strict"):
|
||
flag(
|
||
"受管模板建议把出具契约设为 strict:非 strict 下未回指的数字只降档不拦截",
|
||
code="contract.strict_off", node_id=node_id, field="contract.strict",
|
||
)
|
||
claims = contract.get("claims")
|
||
if strict and isinstance(claims, dict) and claims.get("on_uncited") == "ignore":
|
||
# 受管级别的正式运行把 ignore 当 degrade(io._claims),要求没有降低;只是写法看上去像放宽了
|
||
flag(
|
||
"出具契约的 claims 写了 on_uncited: ignore,但受管级别的正式运行里没挂依据的结论句照样计入缺口"
|
||
"(按 degrade 处理),这个写法不会生效。改成 degrade,或者更严的 withhold",
|
||
code="contract.claims_ignored", node_id=node_id, field="contract.claims",
|
||
)
|
||
|
||
|
||
# --------------------------------------------------------------------------
|
||
# 证据门禁 G1–G5:受管出具要在结构上保证「报告里的每个数都点得开出处」
|
||
#
|
||
# G1 带契约的出口核对报告撰写节点的文档,成果字段的文字只能来自报告撰写节点
|
||
# G2 模型写的文字不绕过报告撰写节点直接流进出口(从图上追)
|
||
# G3 报告撰写节点写明 numbers: strict、on_violation: fail、claims: require_citation(或 judge,带上预算)
|
||
# G4 口径卡的输入不来自计算角色的沙箱代码
|
||
# G5 给口径卡供数的 agent 配 output_schema 并开 cite_fields(模型调用节点不能给口径卡供数)
|
||
#
|
||
# 只看图和配置,不看运行结果。只在发布和发布前检查时起作用:已经发布的版本照常运行,
|
||
# 下次发布才按这些规则查。受管级别挡住发布,已发布级别只给警告。
|
||
# --------------------------------------------------------------------------
|
||
|
||
#: 报告撰写节点在受管模板里要写明的三项:(配置键, 要求的值, 为什么)
|
||
REPORT_POLICY = (
|
||
("numbers", "strict", "没有出处的裸数字判为违规"),
|
||
("on_violation", "fail", "重写之后还违规就让节点失败,不带着问题出具"),
|
||
("claims", "require_citation", "没挂引用的结论句计入缺口,按出具档位降档"),
|
||
)
|
||
#: 除了 REPORT_POLICY 里写的那个值,还认的更严的写法。claims: judge 在挂引用之外再请另一个模型按证据逐句
|
||
#: 裁判,不支持的按 on_unsupported 判档——比 require_citation 严,但要写预算(见 judge_budget_missing)
|
||
REPORT_POLICY_ALSO: dict[str, tuple[str, ...]] = {"claims": (CLAIMS_JUDGE,)}
|
||
#: 不限的写法:judge.max_cost_usd 写 null。说给人听的时候照 engine/judge 设置项的说法
|
||
JUDGE_UNLIMITED = "不设上限,费用只受句数、时长上限和每日上限约束"
|
||
|
||
#: 产出本身就是证据、或者由系统确定地算出来的节点。成果字段取它们的值,不算「别的节点写的字」
|
||
_TRACEABLE = (NodeType.REPORT, NodeType.METRICS, NodeType.INPUT, NodeType.TOOL, NodeType.RETRIEVE)
|
||
_WRITERS = (NodeType.LLM, NodeType.AGENT, NodeType.SUPERVISOR)
|
||
#: 往对话里写消息的节点(emit_message 没关时),「最后一条消息」就是它们里最后跑的那个写的
|
||
_EMITTERS = (*_WRITERS, NodeType.REPORT)
|
||
#: 把上游的值原样或加工后往下传的节点:追文字的来路要穿过它们
|
||
_RELAYS = (NodeType.TRANSFORM, NodeType.CODE, NodeType.VALIDATE, NodeType.HUMAN, NodeType.LOOP)
|
||
#: 往回追口径卡的输入时穿过的整形节点。沙箱代码不穿过:它自己就是 G4 要判的
|
||
_RESHAPERS = (NodeType.TRANSFORM, NodeType.VALIDATE)
|
||
#: 只决定走哪条路、不把值往下带的配置
|
||
_CONTROL_KEYS = frozenset({"skip_if", "condition", "cases"})
|
||
|
||
_TEMPLATE = re.compile(r"\{\{(.*?)\}\}", re.S)
|
||
# 模板和表达式里对值的引用。nodes.<id>…、vars.<名字>… 落得到具体节点;last_message、messages
|
||
# 是最后写消息的那个节点写的;output、loops(和整个 nodes / vars)说不准来自谁
|
||
_REF = re.compile(
|
||
r"(?<![\w.])(?P<root>nodes|vars|last_message|messages|output|loops)(?![\w-])"
|
||
r"(?P<path>(?:\s*(?:\.\s*[\w-]+|\[\s*(?:'[^']*'|\"[^\"]*\"|-?\d+)\s*\]))*)")
|
||
_SEGMENT = re.compile(r"\.\s*([\w-]+)|\[\s*(?:'([^']*)'|\"([^\"]*)\"|(-?\d+))\s*\]")
|
||
|
||
#: (根, 名字, 往里取的路径)。last_message 这类没有名字
|
||
Ref = tuple[str, str, tuple[str, ...]]
|
||
_LAST: Ref = ("last_message", "", ())
|
||
|
||
|
||
def _refs(text: str, *, template: bool) -> list[Ref]:
|
||
out: list[Ref] = []
|
||
for piece in [m.group(1) for m in _TEMPLATE.finditer(text)] if template else [text]:
|
||
for m in _REF.finditer(piece):
|
||
path = tuple(next(g for g in s.groups() if g is not None) for s in _SEGMENT.finditer(m.group("path")))
|
||
root = m.group("root")
|
||
if root in ("nodes", "vars") and path:
|
||
out.append((root, path[0], path[1:]))
|
||
else:
|
||
out.append((root, "", path))
|
||
return out
|
||
|
||
|
||
def _strings(value: Any) -> list[str]:
|
||
"""配置里所有带 {{ }} 的字符串。"""
|
||
if isinstance(value, str):
|
||
return [value] if "{{" in value else []
|
||
if isinstance(value, dict):
|
||
return [s for v in value.values() for s in _strings(v)]
|
||
if isinstance(value, list):
|
||
return [s for v in value for s in _strings(v)]
|
||
return []
|
||
|
||
|
||
def _template_refs(value: Any) -> list[Ref]:
|
||
return [r for text in _strings(value) for r in _refs(text, template=True)]
|
||
|
||
|
||
def _flow_refs(node: GraphNode) -> list[Ref]:
|
||
"""这个节点的产出读了哪些值。判断走哪条路的条件不算;校验节点没写 source 时校验的是最后一条消息。"""
|
||
out: list[Ref] = []
|
||
for key, value in node.config.items():
|
||
if key in _CONTROL_KEYS:
|
||
continue
|
||
out += _refs(value, template=False) if key == "expression" and isinstance(value, str) \
|
||
else _template_refs(value)
|
||
if node.type == NodeType.VALIDATE and node.config.get("source") in (None, ""):
|
||
out.append(_LAST)
|
||
return out
|
||
|
||
|
||
def _effective(spec: GraphSpec, node: GraphNode, key: str, default: Any = None) -> Any:
|
||
"""和运行时 NodeContext.cfg 同一个规则:节点上没写就取图级 defaults。"""
|
||
value = node.config.get(key)
|
||
return spec.defaults.get(key, default) if value in (None, "") else value
|
||
|
||
|
||
def judge_budget_missing(spec: GraphSpec, node: GraphNode) -> bool:
|
||
"""claims 是 judge、生效的 judge 配置里却没有 max_cost_usd 这个键(G3)。
|
||
|
||
写 null 是显式的不限,算写了;没写的键运行时取设置里的默认——受管出具要作者自己定。judge 本身写坏了
|
||
(不是对象、max_cost_usd 写成了别的东西)由 validate 的 report.judge_invalid 报,这里不重复。
|
||
judge 和 claims 一样按运行时的规则取:节点上写了就整个用节点的,不和图级 defaults 拼。
|
||
"""
|
||
if _effective(spec, node, "claims") != CLAIMS_JUDGE:
|
||
return False
|
||
judge = _effective(spec, node, "judge")
|
||
if any(field in ("judge", "judge.max_cost_usd") for field, _ in judge_problems(judge)):
|
||
return False
|
||
return not (isinstance(judge, dict) and "max_cost_usd" in judge)
|
||
|
||
|
||
class _Graph:
|
||
"""一张图上反复要用的查找:谁产出了某个值、最后一条消息是谁写的。"""
|
||
|
||
def __init__(self, spec: GraphSpec) -> None:
|
||
self.spec = spec
|
||
self.nodes = spec.node_map()
|
||
self.parents: dict[str, list[str]] = defaultdict(list)
|
||
for e in spec.edges:
|
||
self.parents[e.target].append(e.source)
|
||
|
||
def producers(self, root: str, name: str) -> list[GraphNode]:
|
||
"""nodes.<name> 就是那个节点;vars.<name> 是用 assign_to 写它的节点、同名的入口字段、
|
||
每轮注入它的循环。"""
|
||
if not name or root not in ("nodes", "vars"):
|
||
return []
|
||
if root == "nodes":
|
||
return [self.nodes[name]] if name in self.nodes else []
|
||
out = []
|
||
for n in self.spec.nodes:
|
||
cfg = n.config
|
||
if n.type == NodeType.INPUT:
|
||
writes = {str(f.get("name") or "").strip() for f in cfg.get("fields") or [] if isinstance(f, dict)}
|
||
elif n.type == NodeType.LOOP and cfg.get("mode", "foreach") == "foreach":
|
||
item = str(cfg.get("item_var") or "item").strip()
|
||
writes = {item, f"{item}_index"}
|
||
else:
|
||
writes = set()
|
||
if name in writes or str(cfg.get("assign_to") or "").strip() == name:
|
||
out.append(n)
|
||
return out
|
||
|
||
def last_writers(self, node_id: str) -> list[GraphNode]:
|
||
"""到这个节点时,最后一条消息可能是谁写的:沿连线往回走,每条路上遇到的第一个写消息的节点。"""
|
||
found: set[str] = set()
|
||
seen = {node_id}
|
||
stack = list(self.parents[node_id])
|
||
while stack:
|
||
cur = stack.pop()
|
||
if cur in seen or cur not in self.nodes:
|
||
continue
|
||
seen.add(cur)
|
||
n = self.nodes[cur]
|
||
if n.type in _EMITTERS and _effective(self.spec, n, "emit_message", True):
|
||
found.add(cur)
|
||
continue
|
||
stack.extend(self.parents[cur])
|
||
return [n for n in self.spec.nodes if n.id in found]
|
||
|
||
def sources(self, consumer: str, ref: Ref) -> list[GraphNode]:
|
||
root, name, _ = ref
|
||
return self.last_writers(consumer) if root in ("last_message", "messages") else self.producers(root, name)
|
||
|
||
|
||
def _who(node: GraphNode) -> str:
|
||
return f"「{node.title}」({type_label(node.type)})"
|
||
|
||
|
||
def _traceable(node: GraphNode) -> bool:
|
||
return node.type in _TRACEABLE or (node.type == NodeType.CODE and node.config.get("evidence_role") == "source")
|
||
|
||
|
||
def _model_text(node: GraphNode, ref: Ref) -> bool:
|
||
"""顺着这个引用拿到的是不是模型写的话。开了 cite_fields 的 agent,assign_to(和 nodes.<id>.data)
|
||
拿到的是逐格核对过的字段,那是数据;它的原话、最后一条消息照样是模型写的。"""
|
||
if node.type in (NodeType.LLM, NodeType.SUPERVISOR):
|
||
return True
|
||
if node.type != NodeType.AGENT:
|
||
return False
|
||
root, _, path = ref
|
||
cited = bool(node.config.get("output_schema")) and node.config.get("cite_fields") is True
|
||
return not (cited and (root == "vars" or path[:1] == ("data",)))
|
||
|
||
|
||
def _exit_refs(node: GraphNode) -> list[tuple[str, str | None, list[Ref]]]:
|
||
"""出口交出去的每个字段:(字段路径, 字段名, 引用)。没配字段时交的是最后一条消息(io.run_output)。"""
|
||
fields = node.config.get("fields")
|
||
if not fields:
|
||
return [("fields", None, [_LAST])]
|
||
return [(f"fields[{i}].value", str(f["name"]), _template_refs(f.get("value", "")))
|
||
for i, f in enumerate(fields if isinstance(fields, list) else [])
|
||
if isinstance(f, dict) and f.get("name")]
|
||
|
||
|
||
def _untraceable_sources(graph: _Graph, exit_id: str, refs: list[Ref]) -> list[str]:
|
||
"""一个成果字段里核对不了出处的来源,一个来源一句(「叙述」(模型调用)、最后一条消息…)。"""
|
||
out: list[str] = []
|
||
for ref in refs:
|
||
root, name, _ = ref
|
||
if root in ("output", "loops") or (root in ("nodes", "vars") and not name):
|
||
out.append(f"{root} 里的值(说不准来自哪个节点)")
|
||
elif root in ("last_message", "messages"):
|
||
out += [f"最后一条消息({_who(w)}写的)" for w in graph.last_writers(exit_id) if w.type != NodeType.REPORT]
|
||
else:
|
||
# 开了 cite_fields 的 agent 交的字段逐格核对过,是数据不是模型写的话——和 G2(_model_text)同一口径
|
||
out += [_who(p) for p in graph.producers(root, name)
|
||
if not _traceable(p) and (p.type != NodeType.AGENT or _model_text(p, ref))]
|
||
return list(dict.fromkeys(out))
|
||
|
||
|
||
def exit_text_fields(spec: GraphSpec, exit_node: GraphNode, graph: _Graph | None = None,
|
||
) -> list[tuple[str, str | None, list[str]]]:
|
||
"""G1:出口里文字不是来自报告撰写节点的字段:(字段路径, 字段名, 来源)。字段名为 None 是没配字段。
|
||
|
||
发布前自动修复(autofix)按同一份结果改字段,门禁和修复认的是同一批字段。
|
||
"""
|
||
graph = graph or _Graph(spec)
|
||
out = []
|
||
for field, name, refs in _exit_refs(exit_node):
|
||
if bad := _untraceable_sources(graph, exit_node.id, refs):
|
||
out.append((field, name, bad))
|
||
return out
|
||
|
||
|
||
def _text_leaks(graph: _Graph, exit_node: GraphNode) -> dict[str, tuple[GraphNode, set[tuple[str, ...]]]]:
|
||
"""流进这个出口、没经过报告撰写节点的模型原话:写字的节点 id → (节点, 途经的节点标题)。
|
||
|
||
途经为空的是出口字段直接取的。沿着模板和表达式里的引用往回追,穿过整形、沙箱代码、校验、人工审批、
|
||
循环;碰到报告撰写节点就停——模型写的话进了报告,就只是写作者的素材。
|
||
"""
|
||
found: dict[str, tuple[GraphNode, set[tuple[str, ...]]]] = {}
|
||
seen: set[str] = set()
|
||
todo: list[tuple[str, Ref, tuple[str, ...]]] = [
|
||
(exit_node.id, ref, ()) for _, _, refs in _exit_refs(exit_node) for ref in refs]
|
||
while todo:
|
||
consumer, ref, via = todo.pop(0)
|
||
for source in graph.sources(consumer, ref):
|
||
if source.type == NodeType.REPORT or source.id == exit_node.id:
|
||
continue
|
||
if source.type in _WRITERS:
|
||
if _model_text(source, ref):
|
||
found.setdefault(source.id, (source, set()))[1].add(via)
|
||
elif source.type in _RELAYS and source.id not in seen:
|
||
seen.add(source.id)
|
||
todo += [(source.id, r, (*via, source.title)) for r in _flow_refs(source)]
|
||
return found
|
||
|
||
|
||
def _card_feeders(graph: _Graph, card: GraphNode) -> list[GraphNode]:
|
||
"""口径卡的输入是谁产出的:穿过整形、校验节点往回追到真正的来源。"""
|
||
out: dict[str, GraphNode] = {}
|
||
seen: set[str] = set()
|
||
todo = [producer for _, producer in _caliber_inputs(card, graph.spec)]
|
||
while todo:
|
||
node = todo.pop(0)
|
||
if node.id in seen or node.id == card.id:
|
||
continue
|
||
seen.add(node.id)
|
||
if node.type in _RESHAPERS:
|
||
todo += [s for ref in _flow_refs(node) for s in graph.sources(node.id, ref)]
|
||
else:
|
||
out.setdefault(node.id, node)
|
||
return list(out.values())
|
||
|
||
|
||
def _lint_evidence(spec: GraphSpec, flag: Callable[..., None], *, strict: bool) -> None:
|
||
graph = _Graph(spec)
|
||
outputs = [n for n in spec.nodes if n.type == NodeType.OUTPUT]
|
||
contracted = {n.id for n in outputs if isinstance(n.config.get("contract"), dict) and n.config["contract"]}
|
||
|
||
# G1
|
||
for node in outputs:
|
||
if node.id not in contracted:
|
||
continue
|
||
contract = node.config["contract"]
|
||
# 两样都没写的由 contract.report_from_missing 报,这里只管「写了叙述、没写 report_from」
|
||
if contract.get("report_from") in (None, "") and str(contract.get("narrative") or "").strip():
|
||
flag(f"{_who(node)}的出具契约用的是旧的叙述模式(narrative),没有声明 report_from:数字只能按数值"
|
||
"回头匹配,出处可能不唯一。受管出具核对「报告撰写」节点产出的文档,每个数都有唯一的出处——把 "
|
||
"report_from 指向出口上游的报告撰写节点",
|
||
code="governed.report_from_required", node_id=node.id, hard=True, field="contract.report_from")
|
||
for field, name, bad in exit_text_fields(spec, node, graph):
|
||
head = (f"{_who(node)}的成果字段「{name}」取的是{'、'.join(bad)}的产出" if name is not None
|
||
else f"{_who(node)}没有配成果字段,交出去的是{'、'.join(bad)}")
|
||
flag(f"{head}:受管出具里给人看的文字只能来自「报告撰写」节点,别的节点写的字核对不了出处。"
|
||
+ ("把它改成取报告撰写节点的正文" if name is not None else "给出口配一个字段,取报告撰写节点的正文"),
|
||
code="governed.exit_text_source", node_id=node.id, hard=True, field=field)
|
||
|
||
# G2:每个出口都算。受管级别是 error,已发布级别是警告——和别的 G 规则一样,级别只管轻重,不管范围
|
||
flagged: set[str] = set()
|
||
for node in outputs:
|
||
for writer, vias in _text_leaks(graph, node).values():
|
||
indirect = sorted(v for v in vias if v)
|
||
# 带契约的出口里字段直接取的,G1 已经点名了那个字段
|
||
if writer.id in flagged or (node.id in contracted and not indirect):
|
||
continue
|
||
flagged.add(writer.id)
|
||
via = f"(经过{'、'.join(f'「{t}」' for t in indirect[0])})" if indirect else ""
|
||
flag(f"{_who(writer)}写的文字没经过「报告撰写」节点,就流进了出口「{node.title}」{via}:模型写的话不算"
|
||
"证据,里面的数字、表名都核对不了出处。改由报告撰写节点来写(它只写引用标记,数字由系统渲染),"
|
||
"出口取报告的正文",
|
||
code="governed.text_bypass", node_id=writer.id, hard=True)
|
||
|
||
# G3
|
||
for node in spec.nodes:
|
||
if node.type != NodeType.REPORT:
|
||
continue
|
||
loose = []
|
||
for key, want, why in REPORT_POLICY:
|
||
value = _effective(spec, node, key)
|
||
if key == "claims" and claims_problem(value):
|
||
continue # 写了不认识的值,validate 的 report.claims_invalid 报
|
||
also = REPORT_POLICY_ALSO.get(key, ())
|
||
if value != want and value not in also:
|
||
now = "现在没写" if value in (None, "") else f"现在是 {value}"
|
||
more = "".join(f",或者更严的 {v}" for v in also)
|
||
loose.append((key, f"{key}: {want}({why}{more};{now})"))
|
||
if loose:
|
||
flag(f"{_who(node)}要写明 {';'.join(text for _, text in loose)}。受管模板的报告撰写节点按最严的规则自查",
|
||
code="governed.report_policy", node_id=node.id, hard=True, field=loose[0][0])
|
||
if judge_budget_missing(spec, node):
|
||
flag(f"{_who(node)}的结论句由模型裁判(claims: judge),却没有写每份报告的裁判预算:在 judge 里写 "
|
||
"max_cost_usd——写一个金额(美元),或者显式写 null 表示不限(" + JUDGE_UNLIMITED + ")。"
|
||
"受管出具不让裁判的花费悄悄按设置里的默认值走",
|
||
code="governed.judge_budget", node_id=node.id, hard=True, field="judge.max_cost_usd")
|
||
|
||
# G4、G5
|
||
feeders: dict[str, tuple[GraphNode, list[str]]] = {}
|
||
for card in spec.nodes:
|
||
if card.type == NodeType.METRICS:
|
||
for feeder in _card_feeders(graph, card):
|
||
feeders.setdefault(feeder.id, (feeder, []))[1].append(f"「{card.title}」")
|
||
for feeder, cards in feeders.values():
|
||
to = f"口径卡{'、'.join(dict.fromkeys(cards))}"
|
||
cfg = feeder.config
|
||
if feeder.type == NodeType.CODE and cfg.get("evidence_role") != "source":
|
||
role = "是 compute" if cfg.get("evidence_role") else "没写,按计算算"
|
||
flag(f"{_who(feeder)}的产出喂给了{to},而它的角色是计算(evidence_role {role}):沙箱里算出来的数核对"
|
||
"不了出处。它其实是在取数的话,把 evidence_role 标成 source;是在做计算的话,把计算挪进口径卡的表达式",
|
||
code="governed.caliber_compute_input", node_id=feeder.id, hard=True, field="evidence_role")
|
||
elif feeder.type == NodeType.AGENT and not cfg.get("output_schema"):
|
||
flag(f"{_who(feeder)}给{to}供数,却没有配 output_schema:它交出来的是一段自由文字,口径卡读到的数核对不了"
|
||
"出处。给它配 output_schema 并开 cite_fields,每个字段都核对到查询结果里的那一格",
|
||
code="governed.caliber_agent_schema", node_id=feeder.id, hard=True, field="output_schema")
|
||
elif feeder.type == NodeType.AGENT and cfg.get("cite_fields") is not True:
|
||
flag(f"{_who(feeder)}给{to}供数,配了 output_schema 却没开 cite_fields:字段没有逐个核对到查询结果,"
|
||
"口径卡读到的仍是模型报的数。打开 cite_fields",
|
||
code="governed.caliber_agent_cite_fields", node_id=feeder.id, hard=True, field="cite_fields")
|
||
elif feeder.type == NodeType.LLM:
|
||
flag(f"{_who(feeder)}给{to}供数:模型调用节点不调工具,写出来的数没有出处。改由 Agent(配 output_schema "
|
||
"并开 cite_fields)或「调用工具」节点取数",
|
||
code="governed.caliber_model_input", node_id=feeder.id, hard=True)
|
||
|
||
|
||
async def unresolved_caliber_upgrades(
|
||
session: AsyncSession, spec: GraphSpec
|
||
) -> tuple[list[str], list[dict[str, Any]]]:
|
||
"""检查钉了版本的上游是否有未处置的新版本:子工作流(方法卡),以及用 caliber_from
|
||
钉住别处口径卡的口径卡节点——两者是同一套规则。
|
||
|
||
返回 (阻断性错误, 需记录的升版事件)。有新版本但没声明 upgrade_policy
|
||
的直接阻断 formal 启动 —— 这是"被迫处置",不是提醒。
|
||
"""
|
||
from app.db.models import WorkflowVersion
|
||
|
||
errors: list[str] = []
|
||
events: list[dict[str, Any]] = []
|
||
for node in spec.nodes:
|
||
extra: dict[str, Any] = {}
|
||
if node.type == NodeType.SUBGRAPH:
|
||
pinned = node.config.get("workflow_version")
|
||
wf_id = node.config.get("workflow_id")
|
||
what = f"「{node.title}」(子工作流)钉在 v{pinned}"
|
||
elif node.type == NodeType.METRICS and isinstance(node.config.get("caliber_from"), dict):
|
||
ref = node.config["caliber_from"]
|
||
pinned, wf_id = ref.get("workflow_version"), ref.get("workflow_id")
|
||
extra = {"caliber_node": ref.get("node_id")}
|
||
what = f"「{node.title}」(口径卡)钉住的口径卡在 v{pinned}"
|
||
else:
|
||
continue
|
||
if not pinned or not wf_id or not str(pinned).isdigit():
|
||
continue
|
||
latest = (
|
||
await session.execute(
|
||
select(func.max(WorkflowVersion.version)).where(
|
||
WorkflowVersion.workflow_id == wf_id
|
||
)
|
||
)
|
||
).scalar()
|
||
if latest is None or latest <= int(pinned):
|
||
continue
|
||
policy = node.config.get("upgrade_policy")
|
||
if policy not in UPGRADE_POLICIES:
|
||
errors.append(
|
||
f"{what},但上游已有 v{latest}。"
|
||
f"正式运行前必须在节点上声明升版策略(upgrade_policy):"
|
||
+ " / ".join(f"{k}({v})" for k, v in UPGRADE_POLICY_LABELS.items())
|
||
)
|
||
else:
|
||
events.append(
|
||
{
|
||
"node_id": node.id,
|
||
"workflow_id": wf_id,
|
||
"pinned": int(pinned),
|
||
"latest": int(latest),
|
||
"policy": policy,
|
||
"policy_label": UPGRADE_POLICY_LABELS[policy],
|
||
**extra,
|
||
}
|
||
)
|
||
return errors, events
|
||
|
||
|
||
#: 发起正式运行时记下「这次按不按受管出具」的那条事件(log · info,不进主流程)
|
||
GOVERNANCE_CODE = "run_governance"
|
||
|
||
|
||
def governance_note(*, governed: bool, workflow_name: str, version: int | None = None) -> dict[str, Any]:
|
||
"""发起正式运行时落进事件流的那条记录(runs.start_run 调用)。
|
||
|
||
governed 由调用方按这次钉住的版本发布时记下的级别定(WorkflowVersion.level),老版本没记过的
|
||
看工作流当时的 status。
|
||
"""
|
||
which = f"「{workflow_name}」v{version}" if version else f"「{workflow_name}」"
|
||
message = (f"这次正式运行按受管级别出具:{which}是按受管级别发布的,之后改图、改级别都不影响这次"
|
||
if governed else
|
||
f"这次正式运行按已发布级别出具:{which}不是按受管级别发布的")
|
||
return {"level": "info", "code": GOVERNANCE_CODE, "governed": governed, "message": message}
|
||
|
||
|
||
async def governed_formal(run_id: str) -> bool:
|
||
"""这次运行是不是受管级别的正式运行:从按受管级别发布的版本发起。
|
||
|
||
受管的判断沿用发布门禁的口径(lint_for_publish 的 strict 档位)。探索运行、已发布级别的
|
||
正式运行都不是。
|
||
|
||
报告节点和出口复核各问一次、前后隔着审批和重放,所以按发起时记下的那条事件算(start_run
|
||
在封存范围内记的 run_governance,来源是钉住的那一版发布时记下的级别);没有这条记录的是
|
||
加这条之前发起的运行,照旧看工作流现在的 status。
|
||
"""
|
||
from app.db.base import SessionLocal
|
||
from app.db.models import Run, RunEvent, Workflow
|
||
|
||
async with SessionLocal() as session:
|
||
run = await session.get(Run, run_id)
|
||
if run is None or run.run_class != "formal" or not run.workflow_id:
|
||
return False
|
||
# 这条事件没有 node_id,发起时就记下了:只翻不属于任何节点的日志
|
||
notes = (await session.execute(
|
||
select(RunEvent.data).where(RunEvent.run_id == run_id, RunEvent.type == "log",
|
||
RunEvent.node_id.is_(None)).order_by(RunEvent.seq))).scalars()
|
||
for data in notes:
|
||
if isinstance(data, dict) and data.get("code") == GOVERNANCE_CODE:
|
||
return data.get("governed") is True
|
||
workflow = await session.get(Workflow, run.workflow_id)
|
||
return workflow is not None and workflow.status == "governed"
|
||
|
||
|
||
def cells_allowed(contract: Any, *, governed: bool) -> bool:
|
||
"""报告能不能直接引用查询单元格。受管级别的正式运行要在契约里显式写 "cells": true;
|
||
探索运行和已发布级别一律允许(用户拍板)。"""
|
||
return not governed or (isinstance(contract, dict) and contract.get("cells") is True)
|