mirror of
https://github.com/ThearchyHelios/AgentLab.git
synced 2026-11-17 03:01:58 +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);关键行为做了变异验证、全部抓到。
384 lines
18 KiB
Python
384 lines
18 KiB
Python
from __future__ import annotations
|
||
|
||
import json
|
||
from collections.abc import Iterable, Mapping
|
||
from dataclasses import dataclass
|
||
from typing import Any
|
||
|
||
from app.core.events import EventType
|
||
from app.engine.issuance import extract_numbers, trace_numbers
|
||
from app.engine.toolcalls import leaked_markup
|
||
|
||
# --------------------------------------------------------------------------
|
||
# 跑完之后的复核层。
|
||
#
|
||
# 编排跑完只说明「流程走完了」,不说明「答得对」。库里能查到大量 status=succeeded
|
||
# 的运行,过程中检索降级了、工具报错了、agent 步数用满了,而交到用户手上的答案
|
||
# 对此只字不提——最糟的一次(run dd9927e6)交出去的干脆是一句内部管道文案。
|
||
#
|
||
# 出具体系(issuance.py)本来就是干这个的,但它挂在输出节点的可选契约上,还要配
|
||
# 口径卡节点提供受控指标集;问数据页生成的图基本都是 input → agent → output,
|
||
# 走不到那条路。所以这里补一层轻的:
|
||
#
|
||
# 1. scan() 纯规则扫一遍事件流,零成本。干净的运行到此为止,不调模型。
|
||
# 2. review() 只在扫出信号时调一次模型,重组答案并把异常说破。
|
||
# 3. 复核模型看不到原始数据,所以它写出来的任何新数字都是凭空来的
|
||
# —— check_numbers() 机械拦截,对不上就整条退回原答案。
|
||
# --------------------------------------------------------------------------
|
||
|
||
BROKEN = "broken" # 答案不可信
|
||
DEGRADED = "degraded" # 能用,但有缺口要说明
|
||
BENIGN = "benign" # 记在轨迹里就够了,不值得为它叫一次模型
|
||
|
||
_SEVERITY_RANK = {BENIGN: 0, DEGRADED: 1, BROKEN: 2}
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class Signal:
|
||
"""一条「这次运行有什么不对」。detail 同时给模型和用户看,所以写人话。"""
|
||
|
||
kind: str
|
||
detail: str
|
||
severity: str = DEGRADED
|
||
#: agent 为什么提前收尾(engine/guards.py:steps / stall / budget_tokens / budget_usd / context)。
|
||
#: 问数据页据此决定给不给「放宽步数重跑」:只有步数用满时放宽步数才对症
|
||
reason: str | None = None
|
||
|
||
def as_dict(self) -> dict[str, str]:
|
||
out = {"kind": self.kind, "detail": self.detail, "severity": self.severity}
|
||
return {**out, "reason": self.reason} if self.reason else out
|
||
|
||
|
||
# warn 日志按 code 分类,而不是靠匹配中文消息串——消息是给人读的,随时会改,
|
||
# 把复核的判断挂在它上面等于给自己埋一颗定时炸弹。各 emit 点带上 code。
|
||
#
|
||
# 没有 code 的(老运行留在库里的事件)一律按 degraded 处理:宁可多说一句,
|
||
# 也好过把真问题当噪音吞掉。
|
||
WARN_CODES: dict[str, tuple[str, str]] = {
|
||
# 对答案内容零影响,轨迹里有就够了
|
||
"stream_fallback": ("stream_fallback", BENIGN),
|
||
# 安全属性上的降级,不是答案内容的问题;轨迹里已经说清楚了
|
||
"isolation_fallback": ("isolation_fallback", BENIGN),
|
||
# 答案本身就没写完
|
||
"step_limit": ("step_limit", BROKEN),
|
||
"empty_completion": ("empty_completion", BROKEN),
|
||
# 能用但有缺口
|
||
# 步数用尽,但收尾轮让模型基于已查到的部分收了口:答案是完整的一段话,
|
||
# 只是覆盖面不全——这是缺口不是断裂,所以不判 BROKEN。
|
||
# 连带效果是不再触发自动重跑,那正是想要的:同样配置再跑一遍还撞同一堵墙
|
||
"step_limit_settled": ("step_limit_settled", DEGRADED),
|
||
# 收尾轮自己挂了。影响由同时发出的 step_limit(BROKEN) 承担,这条是说清原因
|
||
"settle_failed": ("settle_failed", DEGRADED),
|
||
"loop_limit": ("loop_limit", DEGRADED),
|
||
"tool_args_fixed": ("tool_args_fixed", DEGRADED),
|
||
"node_retry": ("node_retry", DEGRADED),
|
||
"validate_retry": ("validate_retry", DEGRADED),
|
||
"sandbox_reset": ("sandbox_reset", DEGRADED),
|
||
"retrieve_degraded": ("retrieve_degraded", DEGRADED),
|
||
# 模型把工具调用写成了文字。纠正一次好了的,答案是真查过的,只记缺口;
|
||
# 没好的那次节点已经判失败,node_failed 会按 BROKEN 算
|
||
"tool_markup_leak": ("tool_markup_leak", DEGRADED),
|
||
# 协作团队用完轮数、按降档交付:交来的是成员原话,不是调度者认可的结论
|
||
"team_exhausted": ("team_exhausted", BROKEN),
|
||
# 调度者收了工,但最后派出去的成员失败了,成果取自更早的那份:有缺口,不是断裂
|
||
"team_last_failed": ("team_last_failed", DEGRADED),
|
||
# 校验节点的修复编出了原文没有的值,这次修复被作废
|
||
"repair_invented": ("repair_invented", DEGRADED),
|
||
# 报告撰写节点:写作者写了裸数字或引用了不存在的指标,被要求重写。重写好了的
|
||
# 答案是核对过的,只记缺口;没好的那次按 on_violation 失败或把违规标在报告里
|
||
"report_repair": ("report_repair", DEGRADED),
|
||
# 报告撰写节点的上游没有可引用的口径卡指标:报告里的数都没有出处
|
||
"report_no_evidence": ("report_no_evidence", DEGRADED),
|
||
# 口径卡的指标集、报告文档没能落进工件库:答案照常,只是点不开证据
|
||
"evidence_store_failed": ("evidence_store_failed", DEGRADED),
|
||
# agent 的结构化字段:模型报的值和查询快照对不上(已按快照取值),或者出处核对不了
|
||
# (记成空值,不兜底成 0)。答案能用,缺口要说清是哪一种
|
||
"agent_field_mismatch": ("agent_field_mismatch", DEGRADED),
|
||
"agent_field_unverified": ("agent_field_unverified", DEGRADED),
|
||
}
|
||
|
||
# 这些 kind 重跑一次大概率能好:原因说得清,且不是「问题本身没问明白」。
|
||
# 工具参数错了、步数不够、图没校验过,都属于改一下再来一遍就行的。
|
||
RETRYABLE = {"step_limit", "tool_error", "empty_completion", "node_failed"}
|
||
|
||
#: 串行工具模式下塞给未执行调用的占位说明。它漏到用户面前当过答案,
|
||
#: 所以复核要认得出来。从 nodes.llm 导入会绕成循环,这里按内容识别。
|
||
_PLACEHOLDER_MARKS = ("本轮只执行了第一个工具",)
|
||
|
||
|
||
def answer_text(output: Mapping[str, Any] | None) -> str:
|
||
"""把 output 各字段拼成答案正文。和前端 answerText 同一套规则。"""
|
||
if not output:
|
||
return ""
|
||
parts = [
|
||
value if isinstance(value, str) else json.dumps(value, ensure_ascii=False)
|
||
for key, value in output.items()
|
||
if not key.startswith("_") and value not in (None, "")
|
||
]
|
||
return "\n".join(parts).strip()
|
||
|
||
|
||
def _event_field(event: Any, name: str, default: Any = None) -> Any:
|
||
"""事件既可能是 ORM 行也可能是 dict,两种都要吃得下。"""
|
||
if isinstance(event, Mapping):
|
||
return event.get(name, default)
|
||
return getattr(event, name, default)
|
||
|
||
|
||
def scan(events: Iterable[Any], output: Mapping[str, Any] | None = None) -> list[Signal]:
|
||
"""纯规则扫一遍运行事件,挑出会影响答案可信度的那些。
|
||
|
||
不调模型、不碰网络。返回空列表就意味着这次运行干净,可以直接交付。
|
||
"""
|
||
signals: list[Signal] = []
|
||
seen: set[tuple[str, str]] = set()
|
||
|
||
def add(kind: str, detail: str, severity: str, reason: str | None = None) -> None:
|
||
if severity == BENIGN:
|
||
return
|
||
key = (kind, detail)
|
||
if key in seen:
|
||
return
|
||
seen.add(key)
|
||
kinds.add(kind)
|
||
signals.append(Signal(kind, detail, severity, reason))
|
||
|
||
kinds: set[str] = set()
|
||
|
||
rows = list(events)
|
||
|
||
# 工具报错之后,同一个工具在后面又跑成了,说明自愈接住了——那是缺口不是断裂。
|
||
# 不区分的话,参数自动纠正这条路每修一次就报一次「答案不可信」。
|
||
recovered: set[str] = set()
|
||
failed_at: dict[str, int] = {}
|
||
for i, e in enumerate(rows):
|
||
etype = str(_event_field(e, "type", ""))
|
||
data = _event_field(e, "data") or {}
|
||
tool = str(data.get("tool") or "")
|
||
if etype == EventType.TOOL_ERROR and tool:
|
||
failed_at.setdefault(tool, i)
|
||
elif etype == EventType.TOOL_END and tool and tool in failed_at:
|
||
recovered.add(tool)
|
||
|
||
for e in rows:
|
||
etype = str(_event_field(e, "type", ""))
|
||
data = _event_field(e, "data") or {}
|
||
node_id = _event_field(e, "node_id") or ""
|
||
|
||
if etype == EventType.TOOL_ERROR:
|
||
tool = str(data.get("tool") or "工具")
|
||
err = str(data.get("error") or "").strip()[:200]
|
||
if tool in recovered:
|
||
add("tool_args_fixed", f"工具 {tool} 第一次调用失败({err}),重试后成功", DEGRADED)
|
||
else:
|
||
add("tool_error", f"工具 {tool} 调用失败:{err}", BROKEN)
|
||
|
||
elif etype == EventType.NODE_FAILED:
|
||
err = str(data.get("error") or "").strip()[:200]
|
||
add("node_failed", f"节点 {node_id} 执行失败:{err}", BROKEN)
|
||
|
||
elif etype == EventType.RUN_FAILED:
|
||
err = str(data.get("error") or "").strip()[:200]
|
||
add("run_failed", f"运行失败:{err}", BROKEN)
|
||
|
||
elif etype == EventType.RETRIEVE_END:
|
||
if data.get("degraded") and "retrieve_degraded" not in kinds:
|
||
# knowledge.py 在这条事件**之前**已经把每条具体原因发成了 warn
|
||
#("重排结果解析不出来"、"多少条向量对不上")。两边都收就是同一件事
|
||
# 报两遍,一条含糊一条具体——这里只兜没有 warn 的情形
|
||
add("retrieve_degraded", "知识库检索能力降级,可能漏掉换了说法的内容", DEGRADED)
|
||
if not data.get("count"):
|
||
q = str(data.get("query") or "").strip()[:60]
|
||
add("retrieve_empty", f"知识库里没有检索到与「{q}」相关的内容", BROKEN)
|
||
|
||
elif etype == EventType.LOG and data.get("level") == "warn":
|
||
message = str(data.get("message") or "").strip()
|
||
code = str(data.get("code") or "")
|
||
kind, severity = WARN_CODES.get(code, ("warn", DEGRADED))
|
||
reason = data.get("reason")
|
||
if message:
|
||
add(kind, message[:300], severity, reason if isinstance(reason, str) and reason else None)
|
||
|
||
text = answer_text(output)
|
||
if not text:
|
||
add("empty_output", "这次运行没有产出任何成果内容", BROKEN)
|
||
elif any(mark in text for mark in _PLACEHOLDER_MARKS):
|
||
add("placeholder_output", "交出来的是一句内部流程说明,不是对问题的回答", BROKEN)
|
||
elif leaked_markup(text):
|
||
# 老运行、或者绕过了节点检查的路径:成果本身就是一段没执行的工具调用标记
|
||
add("markup_output", "交出来的是一段没有执行的工具调用标记,不是对问题的回答", BROKEN)
|
||
|
||
return signals
|
||
|
||
|
||
def worst(signals: Iterable[Signal]) -> str:
|
||
"""一组信号里最重的那档。没有信号时返回空串。"""
|
||
ranked = sorted(signals, key=lambda s: _SEVERITY_RANK.get(s.severity, 1), reverse=True)
|
||
return ranked[0].severity if ranked else ""
|
||
|
||
|
||
def should_retry(signals: Iterable[Signal]) -> bool:
|
||
"""这些信号里有没有「重跑一次大概率能好」的。"""
|
||
return any(s.kind in RETRYABLE and s.severity == BROKEN for s in signals)
|
||
|
||
|
||
def check_numbers(original: str, revised: str) -> list[str]:
|
||
"""复核重写的答案里,有哪些数字是原答案里没有的。
|
||
|
||
复核模型手上只有原答案和一份异常清单,没有任何原始数据——它写出来的新数字
|
||
只能是凭空来的。这条是硬拦截,不是提示:叙述层无算术权限是这个项目的地基
|
||
(见 issuance.decide_tier)。
|
||
|
||
直接复用出具校验那套回指逻辑,把原答案的数字当成受控指标集。
|
||
"""
|
||
controlled = [
|
||
{"id": tok.raw, "value": tok.value} for tok in extract_numbers(original)
|
||
]
|
||
report = trace_numbers(revised, controlled)
|
||
return [item["token"] for item in report.unmatched]
|
||
|
||
|
||
REVIEW_SYSTEM = (
|
||
"你负责复核一次数据问答的结果。执行过程中检测到了异常,你的任务是让用户"
|
||
"在读这个答案之前就知道它哪里不可靠。\n\n"
|
||
"你会拿到:用户的问题、系统给出的原答案、这次运行的异常清单。\n\n"
|
||
"铁律:\n"
|
||
"1. 你看不到任何原始数据。**不许写出原答案里没有的数字**——一个都不行。"
|
||
"需要改写时只能重组原答案已有的内容。\n"
|
||
"2. 异常必须写进 note,不许淡化或略过。降级要明说,不能悄悄地降。\n"
|
||
"3. 如果异常说明这个答案根本不可信(比如取数工具就没跑通、检索什么都没查到),"
|
||
"就直说答不了、说清缺什么,不要拿一个看起来完整的答案去糊。\n"
|
||
"4. note 写给用户看,一到两句中文,说人话:出了什么事、对这个答案意味着什么。"
|
||
"不要复述事件名或代码。\n\n"
|
||
"输出 JSON:\n"
|
||
'- note:给用户的异常说明(必填)\n'
|
||
'- answer:重写后的答案。原答案本身没问题、只是需要补一句说明时,留空字符串\n'
|
||
'- retry:这次运行是不是「换个配置重跑一遍大概率就好了」(比如步数不够、'
|
||
"工具参数写错)。问题本身没问清楚导致的,填 false"
|
||
)
|
||
|
||
REVIEW_SCHEMA: dict[str, Any] = {
|
||
"title": "review",
|
||
"type": "object",
|
||
"properties": {
|
||
"note": {"type": "string", "description": "给用户的异常说明,一到两句中文"},
|
||
"answer": {"type": "string", "description": "重写后的答案;不需要改写就留空"},
|
||
"retry": {"type": "boolean", "description": "重跑一次是否大概率能好"},
|
||
},
|
||
"required": ["note"],
|
||
}
|
||
|
||
|
||
#: 答案带着逐段证据时追加给复核模型的话
|
||
LOCKED_NOTE = (
|
||
"\n\n这份答案带有逐段证据(报告里的每个数字都对应着核对过的出处),不能改写:"
|
||
"answer 必须留空,只在 note 里说明异常。"
|
||
)
|
||
|
||
|
||
def review_prompt(question: str, answer: str, signals: list[Signal], *, locked: bool = False) -> str:
|
||
"""拼给复核模型的请求。
|
||
|
||
只给信号清单,不给原始事件流:几百条事件塞进 prompt 既贵又没用,而信号
|
||
已经是规则层提炼过的结论。
|
||
"""
|
||
lines = "\n".join(
|
||
f"- [{'严重' if s.severity == BROKEN else '降级'}] {s.detail}" for s in signals
|
||
)
|
||
return (
|
||
f"用户的问题:\n{question or '(未记录)'}\n\n"
|
||
f"系统给出的原答案:\n{answer or '(空)'}\n\n"
|
||
f"检测到的异常:\n{lines}"
|
||
+ (LOCKED_NOTE if locked else "")
|
||
)
|
||
|
||
|
||
@dataclass
|
||
class ReviewResult:
|
||
"""复核结论。verdict 是对「系统实际做了什么」的陈述,不是模型的自我评价。"""
|
||
|
||
verdict: str # ok | annotated | rewritten | reverted | failed
|
||
note: str = ""
|
||
answer: str | None = None # None 表示沿用原答案
|
||
#: 改写之前的那份。改写是有损的,原件得跟着一起落库——否则刷新之后
|
||
#: 只剩一个被重组过的答案,想对照都没得对照
|
||
original: str | None = None
|
||
retry: bool = False
|
||
signals: list[Signal] = None # type: ignore[assignment]
|
||
severity: str = ""
|
||
|
||
def as_dict(self) -> dict[str, Any]:
|
||
return {
|
||
"verdict": self.verdict,
|
||
"note": self.note,
|
||
"answer": self.answer,
|
||
"original": self.original,
|
||
"retry": self.retry,
|
||
"severity": self.severity,
|
||
"signals": [s.as_dict() for s in (self.signals or [])],
|
||
}
|
||
|
||
|
||
async def review(
|
||
model: Any, *, question: str, answer: str, signals: list[Signal], locked: bool = False,
|
||
) -> ReviewResult:
|
||
"""叫一次模型复核。调用方负责确保 signals 非空——空信号根本不该走到这里。
|
||
|
||
复核本身失败不能让整轮挂掉:答案已经在手上了,复核只是加一层说明。
|
||
所以这里把异常全兜住,最差也要把原答案原样交出去。
|
||
|
||
locked:成果带 _evidence(报告撰写节点产出、逐段对应证据文档)。这种答案只能
|
||
加说明、不能改写——改写之后界面上点开的出处,指向的是一段已经不存在的文字。
|
||
"""
|
||
severity = worst(signals)
|
||
rule_retry = should_retry(signals)
|
||
fallback_note = ";".join(s.detail for s in signals if s.severity == BROKEN) or ";".join(
|
||
s.detail for s in signals
|
||
)
|
||
|
||
messages = [("system", REVIEW_SYSTEM), ("human", review_prompt(question, answer, signals, locked=locked))]
|
||
try:
|
||
raw = await model.with_structured_output(REVIEW_SCHEMA).ainvoke(messages)
|
||
if not isinstance(raw, dict):
|
||
raise TypeError("结构化输出没有返回对象")
|
||
except Exception: # noqa: BLE001 - 不支持结构化输出的模型退回文本解析
|
||
try:
|
||
from app.api.copilot import _extract_json
|
||
from app.engine.state import message_text
|
||
|
||
raw = _extract_json(message_text(await model.ainvoke(messages)))
|
||
except Exception: # noqa: BLE001
|
||
# 模型这条路彻底不通。规则层已经知道出了什么事,照样说得出话
|
||
return ReviewResult(
|
||
verdict="annotated", note=fallback_note, retry=rule_retry,
|
||
signals=signals, severity=severity,
|
||
)
|
||
|
||
note = str(raw.get("note") or "").strip() or fallback_note
|
||
revised = str(raw.get("answer") or "").strip()
|
||
# 规则层管**资格**,模型只有**否决权**。反过来(两边取并)的话,模型就能
|
||
# 越过规则强推重跑——而"检索什么都没查到"这类,重跑一遍还是查不到,
|
||
# 白烧一次建图加一次跑图。模型没表态时按规则走
|
||
retry = rule_retry and bool(raw.get("retry", True))
|
||
|
||
if locked or not revised or revised == answer.strip():
|
||
return ReviewResult(
|
||
verdict="annotated", note=note, retry=retry, signals=signals, severity=severity,
|
||
)
|
||
|
||
invented = check_numbers(answer, revised)
|
||
if invented:
|
||
# 重写里冒出了原答案没有的数字。整条退回——说明还是要给的,
|
||
# 但那份正文一个字都不能用
|
||
return ReviewResult(
|
||
verdict="reverted",
|
||
note=f"{note}\n\n(复核改写里出现了原答案中没有的数字"
|
||
f"({'、'.join(invented[:5])}),已退回原答案。)",
|
||
retry=retry, signals=signals, severity=severity,
|
||
)
|
||
|
||
return ReviewResult(
|
||
verdict="rewritten", note=note, answer=revised, original=answer, retry=retry,
|
||
signals=signals, severity=severity,
|
||
)
|