Files
AgentLab/backend/app/engine/nodes/io.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

645 lines
30 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
import json
import re
from typing import Any
from app.core.events import EventType
from app.engine.context import NodeContext, NodeError
from app.engine.expressions import ExpressionError, eval_expression
from app.engine.schema import GraphNode, NodeType, _ancestors
from app.engine.state import GraphState, template_context
async def run_input(state: GraphState, ctx: NodeContext) -> dict[str, Any]:
"""入口节点。把运行输入按声明的字段整理进变量池,补上默认值。"""
raw = dict(state.get("input") or {})
fields = ctx.cfg("fields", []) or []
resolved: dict[str, Any] = dict(raw)
for field in fields:
name = field.get("name")
if not name:
continue
if name not in resolved or resolved[name] in (None, ""):
if field.get("required") and field.get("default") in (None, ""):
raise NodeError(ctx.node.id, f"缺少必填输入:{name}")
resolved[name] = field.get("default")
return {
"input": resolved,
"vars": resolved,
"nodes": {ctx.node.id: resolved},
}
async def run_output(state: GraphState, ctx: NodeContext) -> dict[str, Any]:
"""出口节点。按配置把散落在各节点的结果收成一个结构化成果。
配了 contract 就升级成出具契约:核对指标齐不齐、叙述里的数字
能不能回指到指标集,然后给出三档判定(formal / degraded / withheld)。
判定和缺口清单一起印在成果上——降档不是悄悄地降。
"""
mapping = ctx.cfg("fields", None)
tctx = template_context(state)
if mapping:
result: dict[str, Any] = {}
for field in mapping:
name = field.get("name")
if not name:
continue
result[name] = ctx.render(field.get("value", ""), state)
else:
# 没配映射就把最后一条消息当作结果,让新建的图开箱即用
result = {"result": tctx.get("last_message", "")}
reports = _report_fields(result, mapping, state, ctx)
contract = ctx.cfg("contract")
if contract:
cells = True
if isinstance(contract, dict) and contract.get("report_from") not in (None, ""):
from app.engine.governance import cells_allowed, governed_formal
cells = cells_allowed(contract, governed=await governed_formal(ctx.run.run_id))
result["_issuance"] = _apply_contract(contract, state, ctx, reports=reports, cells=cells)
evidence = _evidence_of(reports, contract)
if evidence:
result["_evidence"] = evidence
return {"output": result, "nodes": {ctx.node.id: result}}
# --------------------------------------------------------------------------
# 成果字段和上游报告的对应
# --------------------------------------------------------------------------
def _reference(node: GraphNode) -> re.Pattern[str]:
"""字段模板里「带出了这个报告的正文」的写法。
nodes.write.text、nodes['write']['text']、整个 nodes.write(过 json 也带着正文),以及
存的就是正文的 vars.<assign_to>。nodes.write.repairs / stats / doc_artifact 只是把报告的
统计或文档 id 一起放进成果,没碰正文——算成改动的话,一份全部带引用的报告会被一个
「改写次数」字段拖成降档。模板只认路径加过滤器、没有方法调用,所以这几种写法就是全部。
"""
nid = re.escape(node.id)
head = rf"nodes\s*(?:\.\s*{nid}(?![\w-])|\[\s*['\"]{nid}['\"]\s*\])"
alternatives = [rf"{head}(?:\s*\.\s*text(?![\w-])|\s*\[\s*['\"]text['\"]\s*\]|(?!\s*[.\[]))"]
var = str(node.config.get("assign_to") or "").strip()
if var:
alternatives += [rf"vars\s*\.\s*{re.escape(var)}(?![\w-])",
rf"vars\s*\[\s*['\"]{re.escape(var)}['\"]\s*\]"]
return re.compile("|".join(alternatives))
def _report_fields(
result: dict[str, Any], mapping: Any, state: GraphState, ctx: NodeContext,
) -> list[dict[str, Any]]:
"""上游每个写出了文档的报告节点:哪些成果字段逐字就是它的原文,哪些引用了它却改动过。
逐字相等的字段,界面能按文档逐段画、逐个数点开证据;模板在报告前后拼了别的字、
或者过了过滤器,偏移就对不上了——这种字段不标证据,有契约时记一条 gap。
首尾空白不算改动:Markdown 渲染出来一样,文档的 markdown 本来就去掉了首尾空白。
"""
spec = ctx.run.spec
upstream = _ancestors(spec, ctx.node.id)
nodes = state.get("nodes") or {}
sources = {f.get("name"): f.get("value", "") for f in mapping or [] if isinstance(f, dict) and f.get("name")}
out = []
for node in spec.nodes:
payload = nodes.get(node.id)
if node.type != NodeType.REPORT or node.id not in upstream or not isinstance(payload, dict):
continue
text = payload.get("text")
if not payload.get("doc_artifact") or not isinstance(text, str) or not text.strip():
continue
verbatim = [name for name, value in result.items()
if not name.startswith("_") and isinstance(value, str) and value.strip() == text]
pattern = _reference(node)
edited = [name for name, src in sources.items() if name not in verbatim and pattern.search(
src if isinstance(src, str) else json.dumps(src, ensure_ascii=False, default=str))]
out.append({"node": node, "doc_artifact": payload["doc_artifact"], "verbatim": verbatim,
"edited": edited})
return out
def _evidence_of(reports: list[dict[str, Any]], contract: Any) -> dict[str, Any] | None:
"""成果上的 _evidence:{report_node, doc_artifact, fields}。
不管有没有契约、是不是正式运行都标——探索运行里的报告一样能点开看证据。契约的
report_from 指着的那份优先;另有报告也被原样放进了成果的,列在 others 里。
"""
shown = [r for r in reports if r["verbatim"]]
if not shown:
return None
preferred = contract.get("report_from") if isinstance(contract, dict) else None
shown.sort(key=lambda r: r["node"].id != preferred)
first, *rest = [{"report_node": r["node"].id, "doc_artifact": r["doc_artifact"], "fields": r["verbatim"]}
for r in shown]
return {**first, "others": rest} if rest else first
def _apply_contract(
contract: dict[str, Any], state: GraphState, ctx: NodeContext,
*, reports: list[dict[str, Any]] | None = None, cells: bool = True,
) -> dict[str, Any]:
from datetime import datetime, timezone
from app.engine.issuance import decide_tier, trace_numbers
nodes = state.get("nodes") or {}
# 写了 report_from 就是引用模式:按报告文档逐段复核,不再按数值回指叙述
report_from = contract.get("report_from")
citations = report_from not in (None, "")
# 1) 收指标集:contract.metrics_from 指向一个或多个口径卡节点
metrics: list[dict[str, Any]] = []
calibers: list[dict[str, str]] = []
sources = contract.get("metrics_from") or []
if isinstance(sources, str):
sources = [sources]
# gaps 记的是"校验本身哪里没跑起来",和"校验跑了但没通过"是两回事。
# 没有它,一个写错的节点名会让所有列表都是空的,看起来和"全部通过"一模一样。
gaps: list[str] = []
unresolved: list[str] = []
#: 指标 id → 它来自哪张口径卡(「销售口径 @ v2」),逐个数字回指时标出处
caliber_of: dict[str, str] = {}
for source in sources:
payload = nodes.get(source)
if isinstance(payload, dict) and payload.get("kind") == "metric_set":
metrics.extend(payload.get("metrics") or [])
calibers.append(
{
"node": source,
"caliber": payload.get("caliber", ""),
"version": payload.get("caliber_version", ""),
}
)
label = " @ ".join(str(v) for v in (payload.get("caliber"), payload.get("caliber_version")) if v)
for m in payload.get("metrics") or []:
caliber_of.setdefault(str(m.get("id")), label)
else:
# 节点不存在、还没跑到、或者根本不是口径卡——指标集就是缺的,
# 不能当作"这次没有指标要查"
unresolved.append(source)
if unresolved:
gaps.append(f"指标源未解析:{', '.join(unresolved[:5])}")
# 引用模式下,缺输入记成空值的指标(口径卡 on_missing=null)就是缺:报告里引用不了它,
# 也不能因为 id 在清单里就算「齐了」。旧模式照旧只看 id,行为不变
present = {m["id"] for m in metrics if not citations or m.get("value") is not None}
missing_required = [m for m in (contract.get("required") or []) if m not in present]
missing_expected = [m for m in (contract.get("expected") or []) if m not in present]
trace = None
cited: dict[str, Any] = {}
if citations:
cited = _check_citations(str(report_from), contract, state, ctx, reports or [], cells=cells)
gaps.extend(cited["gaps"])
unmatched = cited["unmatched"]
else:
# 2) 叙述数字回指
declared_narrative = str(contract.get("narrative", ""))
narrative = ctx.render_str(declared_narrative, state)
# 模板取不到路径时 render 出来是空串,所以"声明了叙述但渲染成空"必须单独识别:
# 节点改名、vars 写错都会让回指校验静默变成空操作
if declared_narrative.strip() and not narrative.strip():
gaps.append("叙述模板渲染为空(路径可能写错了)")
elif not declared_narrative.strip():
gaps.append("契约没有声明叙述,数字回指未执行")
trace = (
trace_numbers(narrative, metrics, allow=contract.get("allow_numbers"))
if narrative.strip()
else None
)
unmatched = trace.unmatched if trace else []
# 声明了 metrics_from 却一个指标都没收到,同样是"没查成"
if sources and not metrics:
gaps.append("指标集为空,叙述里的数字无从回指")
# 上游有协作团队用完轮数、按降档交付的:叙述里的话不是调度者认可的结论,
# 数字全都对得上也不能盖「完整出具」
titles = {n.id: n.title for n in ctx.run.spec.nodes}
for node_id, payload in nodes.items():
if isinstance(payload, dict) and payload.get("exhausted"):
gaps.append(f"协作团队「{titles.get(node_id, node_id)}」用完 {payload.get('rounds', '?')} "
"轮仍未完成,交来的是成员最后的原话")
tier = decide_tier(
missing_required=missing_required,
missing_expected=missing_expected,
unmatched=unmatched,
strict=bool(contract.get("strict")),
gaps=gaps,
unresolved=cited.get("unresolved"),
)
if citations:
return _declare_citations(tier, cited, calibers=calibers, metrics=metrics, gaps=gaps,
missing_required=missing_required, missing_expected=missing_expected,
report_from=str(report_from), declared_at=datetime.now(timezone.utc),
ctx=ctx)
# 逐个数字的出处。以前只有一个计数,界面标不出「这个数来自哪个指标」
matched = [
{**hit, **({"caliber": caliber_of[hit["metric"]]} if caliber_of.get(hit.get("metric")) else {})}
for hit in (trace.matched if trace else [])
][:50]
issuance = {
"tier": tier,
"calibers": calibers, # 口径版本照常印
"metrics_checked": len(metrics),
"missing_required": missing_required,
"missing_expected": missing_expected, # 缺数据声明照常印
"unmatched_numbers": unmatched[:20],
"matched_numbers": len(trace.matched) if trace else 0,
"matched": matched,
# 校验没跑全的原因照实印出来——读的人要能分辨"查过都对"和"根本没查"
"gaps": gaps,
"declared_at": datetime.now(timezone.utc).isoformat(),
}
ctx.emit(
EventType.ISSUANCE,
tier=tier,
missing_required=missing_required,
missing_expected=missing_expected,
unmatched=len(unmatched),
calibers=calibers,
# 降档的原因要跟着事件走:只有 gaps 的时候,时间线上的出具步骤以前只能写
# 一个光秃秃的「降档出具」,横幅还说「请对照下方声明」,下方却什么都没有
gaps=gaps,
metrics_checked=len(metrics),
matched_numbers=len(trace.matched) if trace else 0,
matched=matched,
)
return issuance
# --------------------------------------------------------------------------
# 引用模式:按报告文档逐段复核
# --------------------------------------------------------------------------
#: 文档本身对不上(不是某个数没出处):这次复核没法完成,记 gap
_INTEGRITY = {"bad_schema", "segment_mismatch", "structural_text", "render_mismatch", "eid_mismatch",
"state_mismatch"}
def _check_citations(
report_from: str, contract: dict[str, Any], state: GraphState, ctx: NodeContext,
reports: list[dict[str, Any]], *, cells: bool = True,
) -> dict[str, Any]:
"""独立复核报告文档:{matched, unmatched, unresolved, gaps, doc_artifact, stats}。
不信报告节点自己的统计:文档按 id 从工件库取回(取回时复验哈希),目录按报告节点
同一套参数从状态里重建(不用文档里存的那份),每个带引用的片段重新解析、重新渲染、
逐字比对。一个配错的报告节点绕不过这里。
cells:受管级别的正式运行、契约没声明 cells 时为 False,单元格引用一律判解析不了。
"""
from app.core.artifact_store import load
from app.engine.evidence import iter_units, resolve_ref, verify_doc
from app.engine.nodes.report import report_catalog
out: dict[str, Any] = {"matched": [], "unmatched": [], "unresolved": [], "gaps": [],
"doc_artifact": None, "stats": None}
gaps = out["gaps"]
spec = ctx.run.spec
node = spec.node_map().get(report_from)
if node is None or node.type != NodeType.REPORT:
gaps.append(f"契约的 report_from 指向的「{report_from}」不是报告撰写节点,引用核对未执行")
return out
payload = (state.get("nodes") or {}).get(report_from)
doc_artifact = payload.get("doc_artifact") if isinstance(payload, dict) else None
if not doc_artifact:
gaps.append(f"报告撰写节点「{node.title}」没有产出报告文档(没跑到、被跳过或者失败了),"
"引用核对未执行")
return out
out["doc_artifact"] = doc_artifact
try:
doc = load(doc_artifact)
except ValueError:
gaps.append(f"报告「{node.title}」的文档和它的哈希对不上,疑似被改过,引用核对未执行")
return out
if not isinstance(doc, dict):
gaps.append(f"报告「{node.title}」的文档在工件库里取不回来,引用核对未执行")
return out
if doc.get("node_id") != report_from or doc.get("run_id") != ctx.run.run_id \
or doc.get("markdown") != payload.get("text"):
gaps.append(f"报告「{node.title}」的文档和这次运行里它的产出对不上,引用核对未执行")
return out
catalog = report_catalog(state, spec, node)
checked = verify_doc(doc, catalog, allow_numbers=contract.get("allow_numbers"), cells_allowed=cells)
out["stats"] = checked["stats"]
broken: list[str] = []
flagged: set[str] = set()
for v in checked["violations"]:
where = {k: v[k] for k in ("segment", "unit") if v.get(k)}
if v.get("span"):
where.update(start=v["span"][0], end=v["span"][1])
if v.get("segment"):
flagged.add(v["segment"])
if v["code"] == "uncited_number":
out["unmatched"].append({"token": v.get("text", ""), "context": v.get("context", ""), **where})
elif v["code"] == "unresolved_ref":
out["unresolved"].append({"ref": v.get("ref", ""), "message": v["message"], **where})
elif v["code"] in _INTEGRITY:
broken.append(v["message"])
if broken:
more = f"等 {len(broken)} 处" if len(broken) > 1 else ""
gaps.append(f"报告「{node.title}」的文档没通过复核:{broken[0]}{more}")
# 老前端要用的逐个数字出处,从复核通过的数字片段拼出来
for _, unit in iter_units(doc):
for seg in unit.get("segments") or []:
if seg.get("kind") != "number" or not seg.get("ref") or seg.get("id") in flagged:
continue
cite = resolve_ref(str(seg["ref"]), catalog, cells_allowed=cells)
if cite["status"] != "resolved" or cite["rendered"] != seg.get("text"):
continue
entry = catalog.get(cite["alias"]) or {}
start, end = seg["span"]
hit: dict[str, Any] = {"token": seg["text"], "metric": cite["locator"].get("metric")}
if cite["kind"] == "metric":
label = " @ ".join(str(v) for v in (entry.get("caliber"), entry.get("version")) if v)
if label:
hit["caliber"] = label
elif cite["kind"] == "cell":
# 查询单元格:Q1.r0.gmv(全局编号,和 doc.catalog 一致)
hit["cell"] = f"{cite['alias']}.r{cite['locator']['row']}.{cite['locator']['column']}"
else:
hit["input"] = cite["locator"].get("field")
out["matched"].append({**hit, "segment": seg["id"], "unit": unit["id"], "start": start, "end": end,
"span": [start, end], "eid": cite["eid"]})
claims = contract.get("claims")
policy = claims.get("policy") if isinstance(claims, dict) else claims
if policy not in (None, "", "off"):
gaps.append("契约声明了结论句检查(claims),这一版还不支持,结论句没有核对")
mine = next((r for r in reports if r["node"].id == report_from), None)
edited = mine["edited"] if mine else []
for name in edited:
gaps.append(f"成果字段「{name}」改动了报告,无法逐段对应")
if not (mine and mine["verbatim"]) and not edited:
gaps.append(f"成果里没有哪个字段是报告「{node.title}」的原文:读者看到的内容没有经过引用核对")
return out
def _declare_citations(
tier: str, cited: dict[str, Any], *, calibers: list[dict[str, str]], metrics: list[dict[str, Any]],
gaps: list[str], missing_required: list[str], missing_expected: list[str], report_from: str,
declared_at: Any, ctx: NodeContext,
) -> dict[str, Any]:
"""引用模式的 _issuance。旧字段一个不少(老前端照常显示),另加 mode、report、unresolved。"""
report = {"node_id": report_from, "doc_artifact": cited["doc_artifact"]}
issuance = {
"mode": "citations",
"tier": tier,
"report": report,
"calibers": calibers,
"metrics_checked": len(metrics),
"missing_required": missing_required,
"missing_expected": missing_expected,
"unmatched_numbers": cited["unmatched"][:20],
"unresolved": cited["unresolved"][:20],
"matched_numbers": len(cited["matched"]),
"matched": cited["matched"][:50],
"stats": cited["stats"],
"gaps": gaps,
"declared_at": declared_at.isoformat(),
}
ctx.emit(
EventType.ISSUANCE,
mode="citations",
tier=tier,
report=report,
missing_required=missing_required,
missing_expected=missing_expected,
unmatched=len(cited["unmatched"]),
unresolved=len(cited["unresolved"]),
calibers=calibers,
gaps=gaps,
metrics_checked=len(metrics),
matched_numbers=len(cited["matched"]),
matched=cited["matched"][:50],
)
return issuance
async def run_transform(state: GraphState, ctx: NodeContext) -> dict[str, Any]:
"""数据整形。用受限表达式把上游输出揉成下游要的形状,不用为此专门起一个 LLM。"""
tctx = template_context(state)
mode = ctx.cfg("mode", "expression")
output: Any
if mode == "expression":
expr = ctx.cfg("expression", "")
if not expr:
raise NodeError(ctx.node.id, "整形节点没有填表达式")
try:
output = eval_expression(expr, tctx)
except ExpressionError as e:
raise NodeError(ctx.node.id, f"表达式错误:{e}") from e
elif mode == "template":
output = ctx.render_str(ctx.cfg("template", ""), state)
elif mode == "json":
template = ctx.cfg("template", "{}")
rendered = ctx.render_str(template, state)
try:
output = json.loads(rendered)
except json.JSONDecodeError as e:
raise _json_error(e, str(template or ""), tctx, ctx) from e
else:
raise NodeError(ctx.node.id, f"未知的整形模式:{mode}")
updates: dict[str, Any] = {"nodes": {ctx.node.id: output}}
var_name = ctx.cfg("assign_to", "")
if var_name:
updates["vars"] = {var_name: output}
return updates
# --------------------------------------------------------------------------
# 按 JSON 解析失败:错在模板,还是错在上游模型写的文字
# --------------------------------------------------------------------------
#: 产出是模型写的文字的节点(llm 配了 output_schema 时 text 是系统序列化的,但那样也解析得了)
_MODEL_TEXT = (NodeType.AGENT, NodeType.LLM, NodeType.SUPERVISOR)
#: 技术细节里给出出错位置前后各多少个字
_NEAR = 30
_NODE_HEAD = re.compile(r"^nodes\s*(?:\.\s*([\w-]+)|\[\s*['\"]([^'\"]+)['\"]\s*\])")
_VAR_HEAD = re.compile(r"^vars\s*(?:\.\s*([\w-]+)|\[\s*['\"]([^'\"]+)['\"]\s*\])")
TEMPLATE_HINT = "检查模板里的引号、逗号,字符串值要用 | json 过滤器输出"
#: 解析器在这一段的头一个字上要的是这些:前一个值在模板里已经写完了,缺的是模板里的标点
_DELIMITED = ("Expecting ',' delimiter", "Expecting ':' delimiter", "Extra data")
def _json_error(e: json.JSONDecodeError, template: str, tctx: dict[str, Any], ctx: NodeContext) -> NodeError:
"""整形节点按 JSON 解析失败时的报错。
真实踩过:整个模板就是 {{ nodes.X.text }},agent 在 JSON 字符串里夹了没转义的英文双引号,
报错却让人去检查模板、加 | json,把人引到了错的方向。反过来也不行:出错的位置落在模型
写的那一段里,不等于错在模型——模板把一句话原样放进值的位置、放进引号里,或者紧挨着它
漏了逗号,都是模板的错,而且改法就是那句老提示。所以分三种说(见 _diagnose):
- 上游确实在写 JSON 而没写对:点名上游、按实情说原因、指向结构化输出;
- 模板少了 | json:点名是模板里哪一段,给出改好的写法;
- 其余:原来那句提示。
出错位置前后的原文只进技术细节(包在原异常里):首行是给人看的一句话,不贴模型的原文。
"""
doc, pos = e.doc, e.pos
near = (doc[max(0, pos - _NEAR):pos] + "⟨此处⟩" + doc[pos:pos + _NEAR]).replace("\n", "\\n")
e.args = (f"{e.args[0]}\n出错位置前后的原文:{near}",)
verdict = _diagnose(template, tctx, ctx, e)
if verdict is None or isinstance(verdict, str):
return NodeError(ctx.node.id, f"模板渲染出来的不是合法 JSON(第 {e.lineno} 行第 {e.colno} 列附近)。"
f"{verdict or TEMPLATE_HINT}")
node, text, offset, reason = verdict
line = text.count("\n", 0, offset) + 1
column = offset - (text.rfind("\n", 0, offset) + 1) + 1
where = f"第 {line} 行第 {column} 列" if line > 1 else f"第 {column} 列"
fix = ("让模型交结构化数据请给它配 output_schema;数要进口径卡的,改用 agent 的 output_schema + cite_fields"
if node.type == NodeType.LLM else
"让模型交结构化数据请用 output_schema + cite_fields,别用整形节点解析它写的文字")
return NodeError(ctx.node.id, f"上游「{node.title}」输出的不是合法 JSON({where}附近),{reason};{fix}")
def _diagnose(template: str, tctx: dict[str, Any], ctx: NodeContext,
e: json.JSONDecodeError) -> tuple[GraphNode, str, int, str] | str | None:
"""按 JSON 解析失败,错在谁。
返回 (上游节点, 它写的那段文字, 出错位置在文字里的偏移, 原因) 表示错在上游;返回一句话
表示错在模板、而且说得出是哪一段;返回 None 表示照原来那句提示。
只有上游确实在写 JSON(去掉开头空白后以 { 或 [ 开头,或者包在 ``` 代码块里)、而且这一段
不在模板的引号里,才算上游的错;整个模板就是这一段时,模板不可能写错,也算上游的。
解析器停在这一段末尾时(紧跟着的逗号漏了),只有它自己开了括号、引号没收尾才怪它。
每个 {{ }} 单独渲染一次再拼起来,和 render_template 的整段替换结果逐字相同。
"""
from app.engine.expressions import _TEMPLATE_RE, render_template, resolve_path
doc, pos = e.doc, e.pos
at, last = 0, 0
for m in _TEMPLATE_RE.finditer(template):
at += m.start() - last
piece = render_template(m.group(0), tctx)
start, end = at, at + len(piece)
at, last = end, m.end()
expr = m.group(1).strip()
head, *filters = [p.strip() for p in expr.split("|")]
if not head or pos < start:
continue
# 解析器越过空白才报错:停在这一段后面、中间只隔着空白的,也是停在它末尾
at_end = pos >= end and not doc[end:pos].strip()
if not piece.strip():
# 取出来是空的,解析器正好在这里要一个值
if e.msg == "Expecting value" and not doc[start:pos].strip() and not _in_json_string(doc, start):
return f"模板里 {{{{ {expr} }}}} 取出来是空的,这里缺一个值:检查路径写对没有、前面的节点有没有产出"
continue
if pos > end and not at_end:
continue
quoted = _in_json_string(doc, start)
if "json" in filters:
# 过了 | json 就是一个合法的 JSON 值:错不在它的内容里,除非外面又套了一层引号
return (f"模板里 {{{{ {expr} }}}} 出来的已经是合法的 JSON(文字自带引号),外面不要再加引号"
if quoted and not at_end else None)
value = resolve_path(tctx, head)
if not isinstance(value, str) or value != piece:
return None
node = _producer(head, ctx)
model = node is not None and node.type in _MODEL_TEXT
lead = start + len(piece) - len(piece.lstrip())
if pos == lead and e.msg.startswith(_DELIMITED):
return None # 前一个值在模板里就写完了,缺的是它前面的标点
if template.strip() == m.group(0):
return (node, piece, pos - start, _why(piece, at_end)) if model else None
if at_end and not _unclosed(piece):
return None # 这一段本身完整,缺的是它后面的标点
if quoted:
return _needs_json(expr, model)
if _writes_json(piece):
return (node, piece, pos - start, _why(piece, at_end)) if model else None
return _needs_json(expr, model)
return None
def _needs_json(expr: str, model: bool) -> str:
what = "模型写的文字" if model else "一段文字"
return f"模板里 {{{{ {expr} }}}} 是{what},放进 JSON 要写成 {{{{ {expr} | json }}}}(外面不要再加引号)"
def _why(text: str, at_end: bool) -> str:
"""上游写的 JSON 为什么解析不了,按看得出来的实情说。"""
body = text.lstrip()
if body.startswith("```"):
return "它把 JSON 包在了 ``` 代码块里"
if at_end and _unclosed(text):
return "它写的 JSON 没有收尾,可能写到一半被截断了"
if not body.startswith(("{", "[")):
return "它写的是一段文字,不是 JSON"
return "常见原因是字符串里有没转义的英文引号"
def _writes_json(text: str) -> bool:
"""这段文字看得出是想写 JSON:以 { 或 [ 开头,或者是包在 ``` 代码块里的 JSON。"""
body = text.lstrip()
if body.startswith("```"):
body = body.split("\n", 1)[1].lstrip() if "\n" in body else ""
return body.startswith(("{", "["))
def _in_json_string(doc: str, index: int) -> bool:
"""doc[:index] 结束时是不是在一个 JSON 字符串里。解析器已经越过了这里,这一段前缀是
合法的 JSON 开头,数引号(跳过转义)就数得准。"""
inside, i = False, 0
while i < index:
ch = doc[i]
if inside and ch == "\\":
i += 2
continue
if ch == '"':
inside = not inside
i += 1
return inside
def _unclosed(text: str) -> bool:
"""这段文字自己开了引号、括号却没收尾(单独看它,从字符串外面数起)。"""
depth, inside, i = 0, False, 0
while i < len(text):
ch = text[i]
if inside:
if ch == "\\":
i += 1
elif ch == '"':
inside = False
elif ch == '"':
inside = True
elif ch in "{[":
depth += 1
elif ch in "}]":
depth -= 1
i += 1
return inside or depth > 0
def _producer(path: str, ctx: NodeContext) -> GraphNode | None:
"""模板路径取的是哪个节点的产出:nodes.X 就是 X;vars.Y 是 assign_to 为 Y 的节点。"""
nodes = ctx.run.spec.node_map()
if m := _NODE_HEAD.match(path):
return nodes.get(m.group(1) or m.group(2))
if m := _VAR_HEAD.match(path):
var = m.group(1) or m.group(2)
writers = [n for n in ctx.run.spec.nodes if str(n.config.get("assign_to") or "").strip() == var]
# 好几个节点写同一个变量时说不准是谁,宁可给原来的提示也不点错名
return writers[0] if len(writers) == 1 else None
return None