Files
AgentLab/backend/app/engine/governance.py
T
ThearchyHelios fcdcc30d4e 可点击证据第二期:取数链路打通、问数据的答案逐段可点;发布前自动修复
一、可点击证据第二期

取数链路
- 智能体、工具节点、代码节点、知识检索取数时都记进证据台账;报告目录按台账编出 Q1… / K1…
- 报告可以引用快照里的一格([[v:Q1.r0.gmv]]),也可以由系统从快照生成整张表([[table:Q1 cols=… rows=0-4]]),
  表里每一格都是可点的片段;取值一律以快照为准,取回快照时复验哈希
- 口径卡表达式新增 cell(x, row, column),lineage 精确到单元格
- 智能体开 cite_fields(配合 output_schema)后,循环结束做一次结构化抽取,每个字段标出取自哪次查询的哪一格,
  再到快照里核对:一致记 verified;不一致以快照为准并告警;查不到的记为空值,永远不兜底成 0
- 代码节点新增 evidence_role(source / compute)和 code_sha;沙箱算出来的数不能被报告直接引用,要进口径卡
- 查询快照记下列类型,文本列按文本渲染(年份 "2026" 不再显示成「2,026」)
- 升级前发起的运行(停在审批上的)一律走旧逻辑:新的 task 只追加在循环之后,恢复时不会错号

证据接口与面板
- 片段链接上查询步骤:SQL、被引用的行加前后各 2 行、高亮到格;数据源可设 mask_columns 遮罩列,
  遮罩在查询时记进快照,数据源事后改名或删除也照样遮罩(在有身份体系之前,遮罩只减少暴露,不是安全边界)
- 输入来源写明核对结果(与快照一致 / 模型报的值和快照不一致 / 没查到记为空);口径卡缺输入时也给出完整的链
- 受管出具要在契约里声明 cells 才能引用单元格;受管与否记在所钉版本上,改画布不再让受管版本的正式运行降级
- 口径卡可以用 caliber_from 钉住另一个已发布工作流里的口径卡,上游有新版本时按 upgrade_policy 处置,
  和子工作流同一套规则;子工作流节点也补上了升版处置的配置项

Copilot、校验与报错
- 问数据的答案里有数字时,搭 input → 智能体 → 报告 → 出口,报告直接引用查过的单元格
- 写 SQL 前核对数据源的表结构,SQL 里出现表结构里没有的列会被打回
- 不再搭「智能体文字 → 转换节点解析 JSON」这种图;转换节点的 JSON 报错分清是上游模型写坏了、
  模板里裸插了模型文字(给出 | json 的改法),还是模板本身写错了
- 工具节点遇到「查询失败」「SQL 被拒绝」判为失败;发起运行前检查绑定的工具是否存在,不存在时直接拒绝并给出入口

二、发布前自动修复

- 问题带上机器编号(code)和修复 id;新增只读接口 POST /api/workflows/{id}/publish-check 和 /autofix
- 修复分三类:答案唯一、不降低要求的一键修复;要人拿主意的给选项(不替人选);结构性问题交给 Copilot
- 一律先预览,不自动保存、不自动发布;删节点、删契约、放宽审批、关掉 strict、改级别等降低要求的改动一律拒绝,
  Copilot 的方案也要过这一关;应用后重跑检查,错误必须变少且不能冒出新的
- 发布弹窗打开就先检查;问题面板新增「发布前检查」,平时就能看到、就地修掉
- 门禁修正:契约有 report_from 时不再要求 narrative(模板⑨可以发成受管);全图默认审批为「全部放行」时同样拦下
- 修掉画布保存会抹掉全图默认(defaults)的老问题:以前任何一次保存都会把它清空,审批 always 因此被悄悄放宽

验证(沙箱):tsc 干净,生产构建通过,pytest 2268 passed(两遍),check-all 17 项检查、3915 项全过
(新增 check-publish);关键行为做了变异验证、全部抓到。
2026-09-28 21:20:04 +08:00

266 lines
14 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.
from __future__ import annotations
from typing import Any
from sqlalchemy import func, select
from sqlalchemy.ext.asyncio import AsyncSession
from app.engine.schema import GraphSpec, NodeType, ValidationResult, 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)按它认问题、出修复,
文案可以改,编号不能随便改。
"""
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")
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 的并集,顺序也照发布接口。
发布、发布前检查、自动修复复核都走这一个口径——检查说能发的,真发布时不会被拦。
"""
return [*validate_graph(spec).issues, *lint_for_publish(spec, level=level).issues]
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:
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")
if strict and not (contract.get("required") or []):
flag(
"受管模板的出具契约必须声明 required(必需指标),否则「不予出具」这一档永远触发不了",
code="contract.required_missing", node_id=node_id, hard=True, field="contract.required",
)
if strict and not contract.get("strict"):
flag(
"受管模板建议把出具契约设为 strict:非 strict 下未回指的数字只降档不拦截",
code="contract.strict_off", node_id=node_id, field="contract.strict",
)
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)