修复:查询局部刷新与智能分析会话交互,完善分析收尾和配置切换

This commit is contained in:
2026-10-23 15:30:06 +08:00
parent 5fbeb52b93
commit 6394e057bf
40 changed files with 2107 additions and 239 deletions
+121 -11
View File
@@ -52,8 +52,8 @@ CATEGORIES: dict[str, dict[str, tuple[str, ...]]] = {
}
TOOL_DESCRIPTION = (
"只读查询质量中心正式 HTTP API(127.0.0.1:5281),供查询、比较、正式 TOP、变化线索、具体缺陷聚合和有界明细样本。"
"先调用 catalog 获取 releaseId,再在每次 query/compare/top/changes/defects/details 调用中显式传回该 ID。"
"只读查询质量数据分析平台正式 HTTP API(127.0.0.1:5281),供查询、比较、正式 TOP、变化线索、具体缺陷聚合和有界明细样本。"
"investigate提供全量相关统计、分页明细、字段字典、冻结规则映射和归档原表核验。发现差额/缺失必须继续investigate(action=source),直到表内解释成立或明确阻碍;不推断现场原因。先调用 catalog 获取 releaseId,再在每次 query/compare/top/changes/defects/details 调用中显式传回该 ID。"
"catalog 不传 releaseId 时读取当前正式发布版本;比较只在同一发布版本内进行。"
"category 是黑片/亮片真实报废大类;defect 才是来源字段聚合的具体缺陷;product 表示规格。"
"具体缺陷结果来自 POST /api/analysis/defects,按原始缺陷字段键分别汇总,不跨字段合并。TOP share 仅按接口返回的 shareBasis 解读;"
@@ -63,7 +63,7 @@ TOOL_DESCRIPTION = (
QUALITY_DATA_SCHEMA: dict[str, Any] = {
"type": "object",
"properties": {
"mode": {"type": "string", "enum": ["catalog", "query", "compare", "top", "changes", "defects", "details"], "description": "先用 catalog 取发布版本;之后所有数据 mode 都必传 releaseId。defects 查询具体缺陷字段聚合。"},
"mode": {"type": "string", "enum": ["catalog", "query", "compare", "top", "changes", "defects", "details", "investigate"], "description": "先用 catalog 取发布版本;之后所有数据 mode 都必传 releaseId。defects 查询具体缺陷字段聚合。"},
"releaseId": {"type": "string", "minLength": 1, "description": "正式发布版本 ID。catalog 可省略以读取调用当时的 currentRelease;query/compare/top/changes/defects/details 必须显式传入 catalog 返回的 ID。"},
"scope": {"type": "string", "enum": list(SCOPES), "description": "overall、汽车交通合计、汽车交通国内或海外预设范围。若显式传 scope,则不得同时在 filters.group 传值。"},
"period": {
@@ -84,7 +84,7 @@ QUALITY_DATA_SCHEMA: dict[str, Any] = {
"quarter": {"type": "integer", "minimum": 1, "maximum": 4},
},
"required": ["year"],
"description": "compare/changes/defects 的对照期间;使用同一 releaseId 和完全相同的筛选。",
"description": "仅compare/changes/defects/investigate可用;top禁止传入。对照期间;使用同一 releaseId 和完全相同的筛选。",
},
"filters": {
"type": "object", "additionalProperties": False,
@@ -99,7 +99,7 @@ QUALITY_DATA_SCHEMA: dict[str, Any] = {
"description": "实际筛选值会原样传递给正式 API;工具不会忽略未知或冲突的筛选。",
},
"view": {"type": "string", "enum": ["overall", "department", "group", "product", "projectGroup"], "description": "query 的正式分组视图;changes 仅支持非 overall 维度。"},
"stage": {"type": "string", "enum": ["black", "bright"], "description": "TOP/details/defects 阶段;category 解读所用阶段。"},
"stage": {"type": "string", "enum": ["black", "bright"], "description": "top/details/defects/investigate 必填,black黑片或bright亮片。TOP按阶段分别查询,不存在跨阶段默认TOP。"},
"dimension": {"type": "string", "enum": ["category", "defect", "product", "department", "group", "projectGroup"], "description": "正式 TOP 维度;defect 是来源字段中的具体缺陷,product 是规格。changes 使用 product/department/group/projectGroup。defects 使用 defect 或 product。"},
"defect": {"type": "string", "minLength": 1, "description": "catalog 返回的具体缺陷源字段 key(不是显示名称);defects.dimension=product 时必填,用于按该字段排名规格。dimension=defect 可省略以查看具体缺陷聚合,也可指定 key 筛选。"},
"category": {
@@ -108,12 +108,20 @@ QUALITY_DATA_SCHEMA: dict[str, Any] = {
"description": "真实报废大类筛选。黑片:责废/料废/外废;亮片:镀废/材料废/加工废/扩散废。不是具体缺陷;具体缺陷请用 defect。",
},
"limit": {"type": "integer", "minimum": 1, "maximum": 100, "description": "结果行数上限;details 最多 100 条样本;defects 每次最多请求 100 行。"},
"sort": {"type": "string", "enum": ["scrap_delta", "current_scrap", "rate_drop"], "description": "changes 排序:报废增量、当前报废重量、率下降线索;defects 支持 current_scrap 或 scrap_delta,默认单期按当前重量、带对照期按增量排序。"},
"action": {"type":"string","enum":["overview","rows","fields","source"],"description":"investigate动作:overview全量统计/冻结规则,source核验归档原表(最多100000),rows分页明细,fields字段字典。用户要求核验或主要结论受影响时使用;正常统计不必为小额差异专项调查。"},
"offset": {"type":"integer","minimum":0,"maximum":10000000},
"recordFilter": {"type":"string","enum":["all","differences","unexpectedDifferences"]},
"sourceRevisionId": {"type":"string","minLength":1,"maxLength":64},
"fields": {"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"minItems":1,"maxItems":32,"description":"investigate选择源字段;省略时核对所选大类全部细分和总计。先fields查字典,不能猜列。"},
"sort": {"type": "string", "enum": ["scrap_delta", "current_scrap", "rate_drop"], "description": "仅changes/defects可用;top禁止传入。changes 排序:报废增量、当前报废重量、率下降线索;defects 支持 current_scrap 或 scrap_delta,默认单期按当前重量、带对照期按增量排序。"},
},
"required": ["mode"],
"allOf": [{
"if": {"properties": {"mode": {"not": {"const": "catalog"}}}, "required": ["mode"]},
"then": {"required": ["releaseId"]},
}, {
"if": {"properties": {"mode": {"enum": ["top", "defects", "details", "investigate"]}}, "required": ["mode"]},
"then": {"required": ["stage"]},
}],
"additionalProperties": False,
}
@@ -412,7 +420,7 @@ class QualityTools:
result = self._call("GET", "/api/releases")
items = result.get("items")
if not isinstance(items, list):
raise QualityToolError("正式发布版本接口未返回版本目录;请检查质量中心服务。")
raise QualityToolError("正式发布版本接口未返回版本目录;请检查质量数据分析平台服务。")
return result
@staticmethod
@@ -434,7 +442,7 @@ class QualityTools:
index = self._release_index()
release_id = requested or index.get("currentReleaseId")
if not isinstance(release_id, str) or not release_id:
raise QualityToolError("质量中心当前没有已发布版本,无法查询。请先发布数据版本后重试。")
raise QualityToolError("质量数据分析平台当前没有已发布版本,无法查询。请先发布数据版本后重试。")
return self._release_item(index, release_id)
@staticmethod
@@ -1084,6 +1092,55 @@ class QualityTools:
result["notice"] += " 至少一期接口结果被截断或覆盖不可用;pairedRows 仅为返回集合变化,不能称全局增量TOP。"
return result
def _investigate(self, release, period, comparison, filters, args):
action = args.get("action", "overview")
category = _normalize_category(args["stage"], args["category"]) if args.get("category") is not None else None
def fetch(selected_period):
payload = {"releaseId":release["id"], **selected_period, **filters,
"stage":args["stage"], "action":action, "limit":args.get("limit",20)}
if category is not None: payload["category"] = category
for key in ("offset","recordFilter","sourceRevisionId","fields"):
if key in args: payload[key]=args[key]
response = self._call("POST", "/api/analysis/investigate", payload=payload)
context = response.get("context")
expected = {"releaseId":release["id"], "stage":args["stage"], "category":category,
"includeUnassigned":False, "sourceRevisionId":args.get("sourceRevisionId"), **selected_period, **filters}
if response.get("kind") != "quality_investigation" or response.get("action") != action or not isinstance(context,dict):
raise QualityToolError("调查接口未确认kind/action/context;结果已拒绝。")
for key in ("releaseId","stage","year","month","quarter","department","group","product","projectGroup","includeUnassigned","category","sourceRevisionId"):
if context.get(key) != expected.get(key):
raise QualityToolError(f"调查接口未确认{key}范围;结果已拒绝。")
if context.get("extraFilters",{}) != filters.get("extraFilters",{}):
raise QualityToolError("调查接口未确认额外筛选。")
total=response.get("totalRows")
if isinstance(total,bool) or not isinstance(total,int) or total<0 or response.get("aggregateComplete") is not True:
raise QualityToolError("调查接口未确认全量统计覆盖。")
if not isinstance(response.get("categories"),list) or not isinstance(response.get("lineage"),list):
raise QualityToolError("调查接口缺少类别或来源。")
if action=="rows":
rows=response.get("rows"); offset=args.get("offset",0)
if not isinstance(rows,list) or len(rows)>args.get("limit",20) or response.get("offset")!=offset or response.get("returnedRows")!=len(rows):
raise QualityToolError("调查分页响应与请求不一致。")
matching=response.get("matchingRows")
if not isinstance(matching,int) or isinstance(matching,bool) or not 0<=matching<=total:
raise QualityToolError("调查分页缺少匹配总数。")
more=offset+len(rows)<matching
if response.get("hasMore") is not more or response.get("nextOffset")!=(offset+len(rows) if more else None):
raise QualityToolError("调查分页后继游标无效。")
if action=="source":
proof=response.get("sourceVerification")
if not isinstance(proof,dict) or proof.get("expectedRows")!=total:
raise QualityToolError("原表核验覆盖与统计范围不一致。")
if proof.get("complete") is True and (proof.get("verifiedRows")!=total or proof.get("missingRows")!=0):
raise QualityToolError("原表完整标记与核验行数不一致。")
return response
result={"kind":"quality_investigation", "releaseId":release["id"], "period":period,
"filters":filters,"stage":args["stage"],"category":category,"action":action,"current":fetch(period)}
if comparison is not None:
result["comparisonPeriod"]=comparison
result["comparison"]=fetch(comparison)
return result
def _catalog(self, release: dict[str, Any], access: dict[str, Any], fine_defect_stage: str | None = None) -> dict[str, Any]:
options = self._call("GET", "/api/options", {"releaseId": release["id"]})
years = options.get("years")
@@ -1171,19 +1228,42 @@ class QualityTools:
"dataScope": access.get("scope")},
"filters": {"scopePresets": list(SCOPES), "actual": ["department", "group", "product", "projectGroup", "extraFilters", "includeUnassigned"], "extraFields": access.get("extraFields", [])},
"fineDefects": fine_defects,
"investigation": {"mode":"investigate", "actions":["overview","rows","fields","source"], "fullAggregate":True,"sourceMaxRows":100000,"pageLimit":100,"fieldLimit":32,"readOnly":True,"requiresEvidencePermission":True,"next":"正常分析按原始数据统计展示,VCM合计口径和其他小额差异不必专项追查;用户要求或影响主要结论时再核验原表。"},
"limitations": access.get("limitations") or [],
}
def _validate_arguments(self, args: dict[str, Any]) -> None:
unknown = set(args) - {"mode", "releaseId", "scope", "period", "comparisonPeriod", "filters", "view", "stage", "dimension", "category", "defect", "limit", "sort"}
unknown = set(args) - {"mode", "releaseId", "scope", "period", "comparisonPeriod", "filters", "view", "stage", "dimension", "category", "defect", "limit", "sort", "action", "offset", "recordFilter", "sourceRevisionId", "fields"}
if unknown:
raise QualityToolError(f"不支持参数:{', '.join(sorted(unknown))}。请按 quality_data schema 调整请求。")
if args.get("mode") not in {"catalog", "query", "compare", "top", "changes", "defects", "details"}:
if args.get("mode") not in {"catalog", "query", "compare", "top", "changes", "defects", "details", "investigate"}:
raise QualityToolError("mode 必须是 catalog/query/compare/top/changes/defects/details 之一。")
limit = args.get("limit", 20)
if isinstance(limit, bool) or not isinstance(limit, int) or not 1 <= limit <= 100:
raise QualityToolError("limit 必须是 1 到 100 的整数。")
mode = args["mode"]
extras = {"action", "offset", "recordFilter", "sourceRevisionId", "fields"} & set(args)
if extras and mode != "investigate":
raise QualityToolError("action/offset/recordFilter/sourceRevisionId/fields仅用于investigate。")
if mode == "investigate":
if {"view", "dimension", "defect", "sort"} & set(args) or args.get("stage") not in CATEGORIES:
raise QualityToolError("investigate需要stage,不接受view/dimension/defect/sort。")
if args.get("action", "overview") not in {"overview", "rows", "fields", "source"}:
raise QualityToolError("investigate.action无效。")
if args.get("recordFilter", "all") not in {"all", "differences", "unexpectedDifferences"}:
raise QualityToolError("recordFilter无效。")
if args.get("action","overview")!="rows" and {"offset","recordFilter"}&set(args):
raise QualityToolError("offset/recordFilter只用于rows。")
offset=args.get("offset",0)
if isinstance(offset,bool) or not isinstance(offset,int) or not 0<=offset<=10_000_000:
raise QualityToolError("offset必须是0到10000000整数。")
revision=args.get("sourceRevisionId")
if revision is not None and (not isinstance(revision,str) or not re.fullmatch(r"[a-zA-Z0-9-]{1,64}",revision)):
raise QualityToolError("sourceRevisionId无效。")
fields=args.get("fields")
if fields is not None and (not isinstance(fields,list) or not 1<=len(fields)<=32 or any(not isinstance(f,str) or not f.strip() or len(f)>200 for f in fields)):
raise QualityToolError("fields须为1至32个源字段。")
if args.get("category") is not None: _normalize_category(args["stage"],args["category"])
if mode == "catalog":
unused = {"period", "comparisonPeriod", "scope", "filters", "view", "dimension", "category", "defect", "limit", "sort"} & set(args)
if unused:
@@ -1241,6 +1321,32 @@ class QualityTools:
if args.get("category") is not None:
_normalize_category(args["stage"], args["category"])
@staticmethod
def _model_view(result):
if result.get("kind") != "quality_investigation": return result
view = copy.deepcopy(result)
columns = ["field", "rows", "numericRows", "nullOrBlankRows", "keyAbsentRows", "invalidNumericRows", "negativeRows", "numericSum"]
for name in ("current", "comparison"):
side = view.get(name)
if not isinstance(side, dict): continue
if result.get("action") != "fields": side.pop("fieldDictionary", None)
for category in side.get("categories", []):
rows = category.pop("fields", [])
category["fieldCoverageColumns"] = columns
category["fieldCoverage"] = [[row.get("field"), *[(row.get("coverage") or {}).get(key) for key in columns[1:]]] for row in rows]
proof = side.get("sourceVerification")
if isinstance(proof, dict) and proof.get("allSelectedValuesMatchStored") is True:
for source in proof.get("files", []):
source["verifiedFields"] = [row.get("field") for row in source.pop("fields", [])]
source["coverageBasis"] = "全部命中原表值与存储一致,字段计数见类别fieldCoverage;完整逐字段原件统计保存在本次证据中。"
if result.get("action") == "source":
side.pop("largestDifferenceExamples", None)
side["nextSteps"] = (["原件未完整匹配,不能套用VCM例外;用rows+recordFilter=differences保留全部差额,并明确原件缺失/不一致证据。"]
if not isinstance(proof,dict) or proof.get("allSelectedValuesMatchStored") is not True
else ["若unexpectedDifferenceRows>0,调用rows+recordFilter=unexpectedDifferences;以matchingRows/hasMore核对完整剩余。原件已匹配时说明表内差异,不能归因为漏导入。"])
view["modelViewNotice"] = "仅压缩重复字段统计;全量范围、精确合计、缺失/非法/负值计数、对账状态与来源证明保留。完整响应保存在真实evidenceRef对应证据中。"
return view
def _write_evidence(self, result: dict[str, Any], mode: str) -> tuple[str, str]:
evidence_id = "nao-quality-" + uuid.uuid4().hex
evidence_ref = self._evidence_ref(evidence_id)
@@ -1319,6 +1425,10 @@ class QualityTools:
stage = arguments.get("stage")
result = self._changes(release, current, comparison, filters, arguments["dimension"], stage,
arguments.get("category"), arguments.get("sort", "scrap_delta"), limit)
elif mode == "investigate":
period = normalize_period(arguments.get("period"))
comparison = normalize_period(arguments.get("comparisonPeriod"), "comparisonPeriod", required=False)
result = self._investigate(release, period, comparison, filters, arguments)
elif mode == "defects":
current = normalize_period(arguments.get("period"), "period")
comparison = normalize_period(arguments.get("comparisonPeriod"), "comparisonPeriod", required=False)
@@ -1335,7 +1445,7 @@ class QualityTools:
result["evidencePath"] = evidence_path
result["apiSource"] = {"base": "http://127.0.0.1:5281", "paths": list(dict.fromkeys(call["path"] for call in self._calls)),
"releaseId": release["id"]}
return _json_safe(result)
return _json_safe(self._model_view(result))
def tool_definition() -> dict[str, Any]: