mirror of
https://github.com/ThearchyHelios/AgentLab.git
synced 2026-11-16 14:32:00 +00:00
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);关键行为做了变异验证、全部抓到。
266 lines
14 KiB
Python
266 lines
14 KiB
Python
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)
|