证据面板和运行时间线显示 SQL 检查:查询步骤列出级别、中文规则名、说明、涉及的表和列与 SQL 片段,指标步骤在未通过时加标识和原因,时间线把指标所依据的查询未通过 SQL 检查说成一行并给出下一步

This commit is contained in:
ThearchyHelios
2026-10-03 11:49:42 +08:00
parent 6ce01f0b0d
commit 5d7b652149
6 changed files with 249 additions and 3 deletions
+65
View File
@@ -0,0 +1,65 @@
import type { SqlCheckCode, SqlCheckItem, SqlCheckLevel } from '../types'
import { SQL_CHECK_LEVEL_LABEL, SQL_CHECK_RULE_LABEL, SQL_CHECK_TEXT } from './terms'
// ===========================================================================
// 基于数据目录的 SQL 检查(后端 data/sqlcheck.py)在界面上的读法:规则编号 → 中文规则名、级别 → 语义色,
// 以及从证据接口、助手自查、发布前检查的问题里读出一条检查。证据面板、运行时间线、助手面板、发布前检查共用。
// ===========================================================================
/** 七条规则的编号(服务端 CHECK_CODES),按严重程度大致排序 */
export const SQL_CHECK_CODES: readonly SqlCheckCode[] = [
'fanout_sum', 'stock_summed', 'join_unconfirmed', 'ratio_aggregated', 'missing_valid_filter', 'unknown_code', 'wrong_date_column',
]
export const isSqlCheckCode = (code: unknown): code is SqlCheckCode =>
typeof code === 'string' && (SQL_CHECK_CODES as readonly string[]).includes(code)
/** 级别:认不出的按「提示」(最轻的一档),不把拿不准的说重 */
export const sqlCheckLevelOf = (v: unknown): SqlCheckLevel => (v === 'error' || v === 'warning' ? v : 'info')
/** 规则的中文名;服务端新加、这里还不认识的规则统称「SQL 检查」,不露编号 */
export const sqlRuleLabel = (code: unknown): string => (isSqlCheckCode(code) ? SQL_CHECK_RULE_LABEL[code] : SQL_CHECK_TEXT.unknownRule)
/** 各级别的颜色(语义令牌) */
export const SQL_CHECK_TONE: Record<SqlCheckLevel, string> = {
error: 'var(--st-failed)',
warning: 'var(--st-waiting)',
info: 'var(--accent)',
}
const LEVEL_RANK: Record<SqlCheckLevel, number> = { error: 0, warning: 1, info: 2 }
/** 错误在前,同级保持原来的顺序 */
export function sortSqlChecks<T extends { level?: unknown }>(list: T[]): T[] {
return list.map((c, i) => ({ c, i }))
.sort((a, b) => LEVEL_RANK[sqlCheckLevelOf(a.c.level)] - LEVEL_RANK[sqlCheckLevelOf(b.c.level)] || a.i - b.i)
.map((x) => x.c)
}
/** 涉及的表和列:「orders.amount」「orders」 */
export const sqlCheckWhere = (c: Pick<SqlCheckItem, 'table' | 'column'>): string =>
(c.table ? (c.column ? `${c.table}.${c.column}` : c.table) : (c.column ?? ''))
/** 从任意对象读一条检查(证据接口的 checks、助手自查和发布前检查的问题);不是 SQL 检查的返回 null */
export function sqlCheckOf(v: unknown): SqlCheckItem | null {
if (!v || typeof v !== 'object') return null
const o = v as Record<string, unknown>
if (!isSqlCheckCode(o.code)) return null
const str = (x: unknown) => (typeof x === 'string' && x ? x : undefined)
return {
code: o.code,
level: sqlCheckLevelOf(o.level),
message: String(o.message ?? ''),
table: str(o.table) ?? '',
...(str(o.column) ? { column: str(o.column) } : {}),
...(str(o.relation_id) ? { relation_id: str(o.relation_id) } : {}),
...(str(o.sql_excerpt) ? { sql_excerpt: str(o.sql_excerpt) } : {}),
}
}
/** 一条检查写成一行(时间线的展开区、交给助手再修的清单):「错误 · 一对多关联后重复计算:……(涉及 orders.amount)」 */
export function sqlCheckLine(c: SqlCheckItem): string {
const where = sqlCheckWhere(c)
return `${SQL_CHECK_LEVEL_LABEL[sqlCheckLevelOf(c.level)]} · ${sqlRuleLabel(c.code)}:${c.message}`
+ (where ? `(${SQL_CHECK_TEXT.where} ${where})` : '')
}
+68 -1
View File
@@ -44,7 +44,7 @@
import type {
CatalogCardinality, CatalogMeasure, CatalogProfileNumberKey, CatalogSource, CatalogStatus, CatalogTableKind, NodeType, SnapshotReasonCode,
ToolTrust,
SqlCheckCode, SqlCheckLevel, ToolTrust,
} from '../types'
import { formatNumber } from './format'
@@ -248,6 +248,9 @@ export const EVIDENCE_TEXT = {
/** 指标拿截断的查询结果整组算出来(计数、求和……):值只算到了取回的那部分,出具按缺口降档 */
incomplete: '结果不完整',
incompleteFallback: '基于被截断的查询结果计算,结果不完整',
/** 指标所依据的查询对照数据目录查出了错误级的问题:值照算,出具按缺口降档 */
sqlCheckFailed: 'SQL 检查未通过',
sqlCheckFallback: '所依据的查询未通过 SQL 检查,结果不可靠',
/** 输入是 Agent 交来、被截断切开的数组字段 */
inputTruncated: '查询结果已截断,该字段只含取回的部分行',
unshowable: (value: string) => `有值(${value}),但无法按口径卡的格式显示`,
@@ -2365,3 +2368,67 @@ export const CODES_TEXT = {
save: '保存',
cancel: '取消',
}
// ===========================================================================
// 基于数据目录的 SQL 检查(后端 data/sqlcheck.py)
//
// 术语:
// - 「SQL 检查」:对照数据目录找出能执行、数却可能不对的写法。七条规则,界面上写中文规则名,不露规则编号。
// - 级别:错误(依据已确认,结果必然有误)、提醒(依据已确认,结果很可能有误)、提示(依据只是推断,仅供参考)。
// 颜色走语义令牌:错误 --st-failed,提醒 --st-waiting,提示 --accent。
// ===========================================================================
export const SQL_CHECK_RULE_LABEL: Record<SqlCheckCode, string> = {
fanout_sum: '一对多关联后重复计算',
stock_summed: '存量跨期加总',
join_unconfirmed: '关联条件未经确认',
ratio_aggregated: '比率直接加总或平均',
missing_valid_filter: '未筛选有效记录',
unknown_code: '码值不在码值表中',
wrong_date_column: '未按业务日期统计',
}
export const SQL_CHECK_RULE_HINT: Record<SqlCheckCode, string> = {
fanout_sum: '沿一对多方向关联后,对「一」那一侧的度量求和或计数,会按明细行数重复计算',
stock_summed: '对存量列求和却没有按业务日期分组,不同日期的存量被加在一起',
join_unconfirmed: '关联条件对不上数据目录中有确证的关系,可能连错了列',
ratio_aggregated: '对比率列直接求和或求平均,得不到正确的比率',
missing_valid_filter: '表定义了有效记录条件,查询没有按它筛选',
unknown_code: '按码值筛选时用了码值表中没有的值',
wrong_date_column: '表定义了业务日期,查询却按另一个时间列分组或筛选',
}
export const SQL_CHECK_LEVEL_LABEL: Record<SqlCheckLevel, string> = {
error: '错误',
warning: '提醒',
info: '提示',
}
export const SQL_CHECK_LEVEL_HINT: Record<SqlCheckLevel, string> = {
error: '依据已确认,结果必然有误',
warning: '依据已确认,结果很可能有误',
info: '依据尚未确认(推断),仅供参考',
}
export const SQL_CHECK_TEXT = {
title: 'SQL 检查',
/** 规则编号不认识(服务端新加了规则)时的叫法 */
unknownRule: 'SQL 检查',
listLabel: (n: number) => `SQL 检查发现 ${formatNumber(n)} 处问题`,
where: '涉及',
excerpt: 'SQL 片段',
catalogHint: '检查依据来自数据目录。依据有误时,请在数据目录中修正对应项。',
// ---- 运行时间线:指标所依据的查询没通过 SQL 检查(日志 metric_sql_check)
metricTitle: (name: string, n = 1) =>
(n > 1 ? `指标「${name}」所依据的查询有 ${formatNumber(n)} 处未通过 SQL 检查` : `指标「${name}」所依据的查询未通过 SQL 检查`),
metricTitleAnon: '指标所依据的查询未通过 SQL 检查',
metricNext: '指标照常计算,但结果不可靠,出具按缺口降档。请在证据面板的查询步骤中查看问题,修改 SQL 后重新运行;'
+ '检查依据有误时,请在数据目录中修正对应项',
// ---- 助手:搭图时查出的问题
counts: (errors: number, warnings: number, infos: number) =>
[errors ? `${formatNumber(errors)} 处错误` : '', warnings ? `${formatNumber(warnings)} 处提醒` : '',
infos ? `${formatNumber(infos)} 处提示` : ''].filter(Boolean).join('、'),
assistantTitle: (counts: string) => `SQL 检查:${counts}`,
assistantNext: '请打开对应节点,在「参数」中修改 SQL;检查依据有误时,请在数据目录中修正对应项',
assistantInfoNext: '这些检查的依据尚未确认,仅供参考。在数据目录中确认相关项后,检查结论更可靠',
}
+21 -1
View File
@@ -18,7 +18,7 @@ import {
} from '../lib/evidence'
import { humanizeError } from '../lib/errors'
import { formatDateTime, formatNumber, NONE, shortId } from '../lib/format'
import { EVIDENCE_TEXT, JUDGE_TEXT, MERGE_TEXT, NODE_TYPE_LABEL, nodeTypeLabel } from '../lib/terms'
import { EVIDENCE_TEXT, JUDGE_TEXT, MERGE_TEXT, NODE_TYPE_LABEL, SQL_CHECK_TEXT, nodeTypeLabel } from '../lib/terms'
import { useCatalog } from '../store/catalog'
import { askKey, segmentKey, useEvidence, useExplore, useVerdicts } from '../store/evidence'
import type {
@@ -29,6 +29,7 @@ import { ArtifactViewer, ResultTable } from './AssistantStream'
import { useEvidenceHost } from './evidenceHost'
import { EvidenceProvenance } from './EvidenceProvenance'
import { CopyChip } from './Markdown'
import { SqlCheckList } from './SqlChecks'
/**
* 证据面板:点开报告里的一个片段,看它从哪来。
@@ -1109,6 +1110,9 @@ function MetricPart({ step, entry, inputs, runId, seal, pending, failed, resolve
// 拿截断的查询结果整组算出来的:值是真的算出来的,但只算到了取回的那部分,出具已按缺口降档
const incomplete = step?.incomplete === true || entry?.incomplete === true
const incompleteReason = step?.incomplete_reason || entry?.incomplete_reason || EVIDENCE_TEXT.incompleteFallback
// 所依据的查询对照数据目录查出了错误级的问题:值照算,结果不可靠,出具同样按缺口降档。问题和改法在查询步骤里
const sqlFailed = step?.sql_check_failed === true || entry?.sql_check_failed === true
const sqlReason = step?.sql_check_reason || entry?.sql_check_reason || EVIDENCE_TEXT.sqlCheckFallback
return (
<Part title={EVIDENCE_TEXT.metric} data-ev-metric="">
@@ -1121,6 +1125,12 @@ function MetricPart({ step, entry, inputs, runId, seal, pending, failed, resolve
{EVIDENCE_TEXT.incomplete}
</span>
)}
{sqlFailed && (
<span className="chip" data-ev-sql-check-failed="" title={sqlReason}
style={{ color: 'var(--st-waiting)', borderColor: 'var(--st-waiting)' }}>
{EVIDENCE_TEXT.sqlCheckFailed}
</span>
)}
</div>
{(caliber || version || artifact || from) && (
<div className="mt-0.5 flex flex-wrap items-center gap-x-2 text-2xs text-dim">
@@ -1139,6 +1149,9 @@ function MetricPart({ step, entry, inputs, runId, seal, pending, failed, resolve
{incomplete && (
<p className="mt-1" style={{ color: 'var(--st-waiting)' }} data-ev-incomplete-reason="">{incompleteReason}</p>
)}
{sqlFailed && (
<p className="mt-1" style={{ color: 'var(--st-waiting)' }} data-ev-sql-check-reason="">{sqlReason}</p>
)}
{unshowable && (
<p className="mt-1" style={{ color: 'var(--st-waiting)' }} data-ev-unshowable="">
{EVIDENCE_TEXT.unshowable(valueText(value))}
@@ -1366,6 +1379,13 @@ function QueryPart({ id, step, seal, masked }: { id: string; step: EvidenceStep;
{step.sql}
</pre>
)}
{!!step.checks?.length && (
// 这次查询对照数据目录查出的问题:说明、涉及的表和列、SQL 片段。没查出问题时接口不给这个键
<div className="mb-1.5" data-ev-sql-checks="">
<div className="mb-0.5 text-2xs text-faint">{SQL_CHECK_TEXT.title}</div>
<SqlCheckList checks={step.checks} />
</div>
)}
{!!step.merge?.warnings.length && (
<div className="mb-1.5 text-2xs" data-ev-merge-warnings="">
<div className="mb-0.5 text-faint">{MERGE_TEXT.executionWarnings}</div>
+74
View File
@@ -0,0 +1,74 @@
import { Info, OctagonX, TriangleAlert } from 'lucide-react'
import type { LucideIcon } from 'lucide-react'
import clsx from 'clsx'
import type { SqlCheckItem, SqlCheckLevel } from '../types'
import { SQL_CHECK_LEVEL_HINT, SQL_CHECK_LEVEL_LABEL, SQL_CHECK_RULE_HINT, SQL_CHECK_TEXT } from '../lib/terms'
import { SQL_CHECK_TONE, isSqlCheckCode, sortSqlChecks, sqlCheckLevelOf, sqlCheckWhere, sqlRuleLabel } from '../lib/sqlcheck'
// ===========================================================================
// SQL 检查的结果:级别标识(错误、提醒、提示,四通道:图标、文字、颜色、边框)、中文规则名、给人看的说明、涉及的表和列、
// SQL 片段。证据面板的查询步骤和助手面板共用这一份。
// ===========================================================================
const LEVEL_ICON: Record<SqlCheckLevel, LucideIcon> = { error: OctagonX, warning: TriangleAlert, info: Info }
/** 级别标识:图标 + 「错误 / 提醒 / 提示」,悬停写明依据的确证程度 */
export function SqlLevelBadge({ level: raw, className }: { level: unknown; className?: string }) {
const level = sqlCheckLevelOf(raw)
const Icon = LEVEL_ICON[level]
const tone = SQL_CHECK_TONE[level]
return (
<span className={clsx('inline-flex shrink-0 items-center gap-0.5 whitespace-nowrap rounded-full border px-1.5 text-2xs leading-[16px]', className)}
style={{ color: tone, borderColor: `color-mix(in srgb, ${tone} 45%, var(--border))`, background: `color-mix(in srgb, ${tone} 8%, transparent)` }}
title={SQL_CHECK_LEVEL_HINT[level]} data-sql-level={level}>
<Icon size={10} aria-hidden />
{SQL_CHECK_LEVEL_LABEL[level]}
</span>
)
}
/** 一条检查的正文:规则名、说明、涉及的表和列、SQL 片段 */
export function SqlCheckBody({ check: c, excerpt = true }: { check: SqlCheckItem; excerpt?: boolean }) {
const where = sqlCheckWhere(c)
return (
<>
<div className="flex min-w-0 flex-wrap items-center gap-x-1.5 gap-y-0.5">
<SqlLevelBadge level={c.level} />
<span className="font-medium text-fg" title={isSqlCheckCode(c.code) ? SQL_CHECK_RULE_HINT[c.code] : undefined} data-sql-rule="">
{sqlRuleLabel(c.code)}
</span>
{where && (
<span className="text-faint" data-sql-where={where}>
{SQL_CHECK_TEXT.where} <span className="mono text-dim [overflow-wrap:anywhere]">{where}</span>
</span>
)}
</div>
{c.message && <p className="mt-0.5 leading-relaxed text-dim [overflow-wrap:anywhere]" data-sql-message="">{c.message}</p>}
{excerpt && c.sql_excerpt && (
<pre className="mono mt-1 max-h-20 overflow-auto whitespace-pre-wrap rounded bg-bg px-1.5 py-1 leading-relaxed text-dim [overflow-wrap:anywhere]"
aria-label={SQL_CHECK_TEXT.excerpt} title={SQL_CHECK_TEXT.excerpt} data-sql-excerpt="">
{c.sql_excerpt}
</pre>
)}
</>
)
}
/** 检查结果的清单:错误在前。每条一个淡色框,框的颜色跟级别走 */
export function SqlCheckList({ checks, className }: { checks: SqlCheckItem[]; className?: string }) {
const list = sortSqlChecks(checks)
return (
<ul className={clsx('space-y-1 text-2xs', className)} aria-label={SQL_CHECK_TEXT.listLabel(list.length)} data-sql-checks={list.length}>
{list.map((c, i) => {
const tone = SQL_CHECK_TONE[sqlCheckLevelOf(c.level)]
return (
<li key={`${c.code}:${c.table}:${c.column ?? ''}:${i}`} className="rounded border px-2 py-1.5"
style={{ borderColor: `color-mix(in srgb, ${tone} 30%, var(--border))`, background: `color-mix(in srgb, ${tone} 5%, transparent)` }}
data-sql-check={c.code} data-level={sqlCheckLevelOf(c.level)}>
<SqlCheckBody check={c} />
</li>
)
})}
</ul>
)
}
+15 -1
View File
@@ -1,7 +1,7 @@
import type { RunEvent, TeamMember, TeamRound, TeamRun, ToolChange } from '../types'
import type { NodeState, RunPhase } from './trace'
import { formatDuration, formatNumber } from '../lib/format'
import { JUDGE_TEXT, MERGE_TEXT, TYPE_LABEL, claimTally, evidenceTally, issuanceLabel, nodeTypeLabel } from '../lib/terms'
import { JUDGE_TEXT, MERGE_TEXT, SQL_CHECK_TEXT, TYPE_LABEL, claimTally, evidenceTally, issuanceLabel, nodeTypeLabel } from '../lib/terms'
import { claimCountsOf, isJudged, statsTally } from '../lib/evidence'
// 泳道数据画布也要用(supervisor 节点要展开成协作矩阵),所以类型放在
@@ -775,6 +775,20 @@ function explainLog(code: string | undefined, message: string): Pick<Step, 'titl
fix: 'canvas',
}
}
case 'metric_sql_check': {
// 「指标「客单价」所依据的查询未通过 SQL 检查(「订单」关联「订单明细」是一对多,对「订单」的「订单金额」求和会
// 重复计算),结果不可靠」;几处时是「所依据的查询有 2 处未通过 SQL 检查(…等),结果不可靠」(metrics.py
// _sql_check_reason)。括号里的问题本身可能带括号:取到「,结果不可靠」前面最后一个右括号
const name = message.match(/^指标「(.+?)」/)?.[1]
const n = message.match(/有\s*(\d+)\s*处未通过 SQL 检查/)?.[1]
const why = message.match(/未通过 SQL 检查(([\s\S]+))[,,]\s*结果不可靠\s*$/)?.[1]
return {
title: name ? SQL_CHECK_TEXT.metricTitle(name, n ? Number(n) : 1) : SQL_CHECK_TEXT.metricTitleAnon,
sub: why,
next: SQL_CHECK_TEXT.metricNext,
fix: 'canvas',
}
}
case 'judge_limit': {
// 「结论句裁判已到上限(这份报告的裁判金额上限 $0.05):3 句没判,记为未裁判;已判的保留」(judge.py run_request)
const n = message.match(/[::]\s*(\d+)\s*句(?:没判|未裁判)/)?.[1]
+6
View File
@@ -2131,6 +2131,12 @@ export interface EvidenceStep extends Omit<EvidenceInput, 'status'> {
incomplete?: boolean
/** metric:不完整的原因(人话,「基于被截断的查询结果计算(只取回了前 1000 行),结果不完整」) */
incomplete_reason?: string
/** metric:所依据的查询没通过 SQL 检查(有错误级的问题),值照算,出具已按缺口降档 */
sql_check_failed?: boolean
/** metric:没通过的原因(人话,「所依据的查询未通过 SQL 检查(…),结果不可靠」) */
sql_check_reason?: string
/** query:这次查询对照数据目录查出的问题。没查出问题时没有这个键 */
checks?: SqlCheckItem[]
inputs?: EvidenceInput[]
/** 口径卡钉在哪个工作流的哪一版(metric;方案第 5 节的写法,接口实际给在 source 上) */
caliber_from?: EvidenceCaliberSource | null