"""Read this turn's bounded, private quality evidence for deterministic charts. This path never sends data to a model or reads original workbooks. In particular it must not use the finalizer's presentation-truncated evidence as a full dataset. """ from __future__ import annotations import json import os import copy from pathlib import Path import re import stat import time FILE_LIMIT = 4 * 1024 * 1024 TOTAL_LIMIT = 16 * 1024 * 1024 DOCUMENT_LIMIT = 100 def load_visual_evidence(directory: Path, release_id: str, *, exclude_files=frozenset(), cancel_event=None, budget_seconds: float = 0.3) -> list[dict]: """Fail closed on bad identity, permissions, excessive size, or a changed file. The caller already owns an isolated actor/session directory. The pre-turn file inventory prevents previous questions from supplying the new answer's charts. Bounds count bytes before parsing any document. """ if directory.is_symlink(): raise ValueError('invalid evidence directory') started = time.monotonic() documents: list[dict] = [] total = 0 for path in sorted(directory.glob('nao-quality-*.json')): if cancel_event is not None and cancel_event.is_set(): return [] if time.monotonic() - started > budget_seconds: raise ValueError('visual evidence deadline') if path.name in exclude_files: continue if not re.fullmatch(r'nao-quality-[a-f0-9]{32}\.json', path.name): continue fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK) with os.fdopen(fd, 'rb') as source: before = os.fstat(source.fileno()) if (not stat.S_ISREG(before.st_mode) or before.st_mode & 0o077 or before.st_uid != os.getuid() or before.st_size > FILE_LIMIT): raise ValueError('invalid evidence file') total += before.st_size if total > TOTAL_LIMIT or len(documents) >= DOCUMENT_LIMIT: raise ValueError('visual evidence limit') raw = source.read(FILE_LIMIT + 1) after = os.fstat(source.fileno()) if (len(raw) > FILE_LIMIT or before.st_size != after.st_size or before.st_mtime_ns != after.st_mtime_ns): raise ValueError('evidence changed while reading') document = json.loads(raw) if not isinstance(document, dict): raise ValueError('invalid evidence document') result = document.get('result') if (document.get('tool') != 'quality_data' or document.get('releaseId') != release_id or not isinstance(result, dict) or result.get('releaseId') != release_id or not re.fullmatch(r'Q[A-F0-9]{8}', str(document.get('evidenceRef', '')))): raise ValueError('evidence binding mismatch') if document.get('mode') in ('query', 'rank', 'compare', 'top', 'changes', 'defects'): documents.append(document) return documents def visual_result(directory: Path, release_id: str, question: str, turn_id: str, *, exclude_files=frozenset(), cancel_event=None, context=None) -> dict: """Build a presentation-only result without changing turn status. The complete server-normalized context, including an exact-question ``_agentTask`` when present, is forwarded to the deterministic builder. This adapter does not reinterpret the task or question. """ if os.environ.get('QUALITY_ANALYSIS_VISUALS_ENABLED', 'true').lower() not in ('true', '1', 'yes'): return {'visualSchemaVersion': 1, 'visualState': 'not_requested', 'visuals': []} if cancel_event is not None and cancel_event.is_set(): return {'visualSchemaVersion': 1, 'visualState': 'unavailable', 'visuals': []} try: from analysis_visuals import build_visuals evidence = load_visual_evidence(directory, release_id, exclude_files=exclude_files, cancel_event=cancel_event) if cancel_event is not None and cancel_event.is_set(): return {'visualSchemaVersion': 1, 'visualState': 'unavailable', 'visuals': []} return build_visuals(evidence, question, turn_id, context=context) except Exception: # Presentation must not turn an otherwise successful business answer into # a failed task, including unexpected adapter bugs. Do not expose paths. return {'visualSchemaVersion': 1, 'visualState': 'failed', 'visuals': []} def protocol_visual_result(evidence, scopes, question, turn_id, *, release_id, base_context=None): """One shared chart exit for live queries and frozen-response recovery. Isolate each scope so a malformed optional chart never removes healthy charts produced from other query results in the same answer. """ if not isinstance(evidence, list) or not isinstance(scopes, list): return _protocol_scope_visual_result(evidence, scopes, question, turn_id, release_id=release_id, base_context=base_context) visuals, missing, states, seen = [], [], [], set() for scope in scopes: part = _protocol_scope_visual_result(evidence, [scope], question, turn_id, release_id=release_id, base_context=base_context) states.append(part.get('visualState')) missing.extend(part.get('missingEvidence', [])) for chart in part.get('visuals', []): if chart.get('id') not in seen: seen.add(chart.get('id')) visuals.append(chart) if len(visuals) > 12: missing.append('图表数量超过12张呈现上限,已保留前12张。') visuals = visuals[:12] state = ('ready' if visuals else 'failed' if 'failed' in states else 'unavailable' if 'unavailable' in states else 'not_requested') return {'visualSchemaVersion': 1, 'visualState': state, 'visuals': visuals, 'missingEvidence': list(dict.fromkeys(missing))} def _protocol_scope_visual_result(evidence, scopes, question, turn_id, *, release_id, base_context=None): """Build charts independently within each server-issued node/scope frame.""" if os.environ.get('QUALITY_ANALYSIS_VISUALS_ENABLED', 'true').lower() not in ('true', '1', 'yes'): return {'visualSchemaVersion': 1, 'visualState': 'not_requested', 'visuals': [], 'missingEvidence': []} if not isinstance(evidence, list) or not isinstance(scopes, list): return {'visualSchemaVersion': 1, 'visualState': 'failed', 'visuals': [], 'missingEvidence': ['queryPlan图表输入范围无效。']} try: from analysis_visuals import build_visuals from nao_query_plan import scope_context, scope_documents from nao_weight_ranking import ranking_task all_visuals, missing, requested_visuals = [], [], False for scope in scopes: if not isinstance(scope, dict) or not isinstance(scope.get('task'), dict): missing.append('服务器签发的图表范围不完整。') continue task = scope['task'] node_id, scope_id = scope.get('nodeId'), scope.get('scopeId') metric_scope = scope.get('purpose') == 'metrics' or task.get('kind') == 'metrics' child_question = task.get('question') if isinstance(task.get('question'), str) else question selected = scope_documents(evidence, scope, release_id=release_id) # A finite ranking operator can serve a confirmed single-object # metrics request. Keep that root intent through visual completion, # using the same exact scope/proof gate as narrative composition. # An explicit chart request still follows the normal chart checks. from nao_weight_ranking import protocol_scalar_metrics_scope root = base_context.get('_agentTask', {}) if isinstance(base_context, dict) else {} scalar_metrics = (len(selected) == 1 and protocol_scalar_metrics_scope( root, base_context, selected[0])) node_requires_chart = any(node.get('visualPreference') == 'required' for node in root.get('queryPlan', []) if isinstance(node, dict)) if (scalar_metrics and task.get('visualPreference', 'auto') != 'required' and root.get('visualPreference') != 'required' and not node_requires_chart): continue context = scope_context(scope, release_id=release_id, question=question) if isinstance(base_context, dict): for key in ('_protocol', '_protocolScopes'): if key in base_context: context[key] = copy.deepcopy(base_context[key]) preference = task.get('visualPreference', 'auto') selection = root.get('aggregateSelection') if (selection and scope.get('purpose') == 'metrics' and task.get('dimensions') == [selection.get('dimension')]): if preference != 'none': from dsh_row_selection import ranking_chart # A genuinely empty filtered population has no chart to # retry. Missing signed documents remain a recoverable gap. requested_visuals |= not selected for document in selected: charts = ranking_chart(document, root, turn_id) if charts: requested_visuals = True all_visuals.extend(charts) continue fields, stages = task.get('fields'), task.get('stages') or [] optional_auto_scalar = (metric_scope and task.get('visualPreference') == 'auto' and task.get('comparisonRequired') is not True and task.get('trendRequired') is not True and isinstance(fields, list) and len(fields) == 1 and isinstance(stages, list) and len(stages) <= 1) metric_chart_required = (preference == 'required' or task.get('comparisonRequired') is True or task.get('visualType') is not None and not optional_auto_scalar) # Batch Top1 results may intentionally omit auto charts. A model's # style hint alone must not mark that omission as unavailable. if scope.get('purpose') == 'changes': requested_visuals |= preference == 'required' elif metric_scope: requested_visuals |= preference != 'none' and ( task.get('trendRequired') is True or metric_chart_required or ranking_task(task)) else: requested_visuals |= preference != 'none' and ( task.get('trendRequired') is True or preference == 'required' or task.get('visualType') is not None or ranking_task(task)) child = build_visuals(selected, child_question, turn_id, context=context) child_visuals = child.get('visuals') if isinstance(child.get('visuals'), list) else [] metric_visual_requirements = [] if metric_scope and metric_chart_required: stages = task.get('stages') or [] for field in task.get('fields', []): if field == 'rate': metric_visual_requirements.extend( [(stage + '_rate', stage) for stage in stages] if stages else [('composite_rate', None)]) elif field == 'scrapRate': metric_visual_requirements.extend( [(stage + '_scrap_rate', stage) for stage in (stages or ['black', 'bright'])]) elif field == 'totalWeight': metric_visual_requirements.extend([(stage + '_total_weight', stage) for stage in stages]) elif field == 'scrapWeight': metric_visual_requirements.extend([(stage + '_scrap_weight', stage) for stage in stages]) expected_pairs = set(metric_visual_requirements) # The visual builder may offer both stage rates for a composite # request. Keep only the exact node fields and stage frame. child_visuals = [chart for chart in child_visuals if (chart.get('metric'), chart.get('stage')) in expected_pairs] # Composition is already present in the same signed overall result. # A scalar scrapWeight node must not erase those category values # when the user explicitly asks for a structure report. if (root.get('executionMode') == 'native_agent' and preference != 'none' and scope.get('purpose') in ('metrics', 'trend') and not task.get('dimensions') and re.search(r'报废.*(?:结构|构成|占比)|正式报废大类', root.get('question', ''))): from analysis_visuals import _metrics_category_charts for document in selected: for chart in _metrics_category_charts(document, document.get('result', {}), turn_id, '', semantic_chart_type='donut', semantic_stages=root.get('stages') or None): if not any(existing.get('id') == chart.get('id') for existing in child_visuals): child_visuals.append(chart) # Native overall queries carry all three formal rates in the same # signed monthly response. The scalar stage selector cannot encode # "composite plus both stages". Honour that explicit report request # using only this already scope-checked evidence, never a new query. requested_text = root.get('question', '') wants_stages = (all(label in requested_text for label in ('黑片合格率', '亮片合格率')) or bool(re.search(r'(?:两阶段|阶段)(?:月度)?对照', requested_text))) if (root.get('executionMode') == 'native_agent' and root.get('kind') in ('analysis', 'report') and root.get('trendRequired') is True and preference != 'none' and wants_stages and root.get('stages') in ([], ['black', 'bright'], ['bright', 'black']) and scope.get('purpose') == 'trend' and 'rate' in task.get('fields', []) and selected): present = {chart.get('metric') for chart in child_visuals} for stages, metrics in (([], {'composite_rate'}), (['black', 'bright'], {'black_rate', 'bright_rate'})): if metrics <= present: continue rate_context = copy.deepcopy(context) rate_context['_agentTask'].update(kind='metrics', fields=['rate'], stages=stages) supplement = build_visuals(selected, child_question, turn_id, context=rate_context) for chart in supplement.get('visuals', []): if (chart.get('metric') in metrics - present and chart.get('sectionKey') == 'trend' and chart.get('type') in ('line', 'area') and chart.get('unit') == 'ratio'): child_visuals.append(chart) present.add(chart['metric']) if not {'composite_rate', 'black_rate', 'bright_rate'} <= present: missing.append('当前正式月度证据未完整生成综合、黑片和亮片合格率趋势对照。') if scope.get('purpose') == 'defects' and preference != 'none': query = task.get('defectQuery') if isinstance(task.get('defectQuery'), dict) else {} expected_dimension = query.get('dimension') expected_sort = task.get('sort', 'scrap_delta' if task.get('comparisonRequired') else 'current_scrap') expected_metric = ('source_defect_delta_weight' if task.get('comparisonRequired') and expected_sort == 'scrap_delta' else 'source_defect_weight') chart_types = ({task.get('visualType')} if task.get('visualType') else {'bar', 'column'}) for stage in task.get('stages', []): matched = any( chart.get('metric') == expected_metric and chart.get('stage') == stage and chart.get('dimension') == expected_dimension and chart.get('type') in chart_types and isinstance(chart.get('scope'), dict) and chart['scope'].get('defect') == query.get('defect') and chart['scope'].get('category') == query.get('category') for chart in child_visuals if isinstance(chart, dict)) if not matched: missing.append('节点'+str(node_id)+'范围'+str(scope.get('label') or scope_id) +'缺少'+str(stage)+'来源具体缺陷重量图,或所选图表类型无法诚实表达该范围。') for visual in child_visuals: if isinstance(visual, dict): # Keep the established chart wire schema. Node/scope # identity is validated from the server-issued tasks and # evidence before building charts; it is not chart data. all_visuals.append(copy.deepcopy(visual)) if child.get('visualState') == 'failed': missing.append('节点'+str(node_id)+'范围'+str(scope.get('label') or scope_id)+'图表整理失败。') if scope.get('purpose') != 'defects' and ranking_task(task): from nao_weight_ranking import missing_ranking_visuals missing.extend('节点'+str(node_id)+'范围'+str(scope.get('label') or scope_id)+':'+gap for gap in missing_ranking_visuals(task, child_visuals, selected)) elif task.get('trendRequired') and preference != 'none': expected = [] stages = task.get('stages') or [] for field in task.get('fields', []): if field == 'rate': expected.extend([('composite_rate', None)] if not stages else [(stage+'_rate', stage) for stage in stages]) elif field == 'scrapRate': expected.extend([(stage+'_scrap_rate', stage) for stage in (stages or ['black', 'bright'])]) elif field == 'totalWeight': expected.extend([(stage+'_total_weight', stage) for stage in (stages or ['black', 'bright'])]) elif field == 'scrapWeight': expected.extend([('current_scrap_weight', stage) for stage in (stages or ['black', 'bright'])]) for metric, stage in expected: chart_types = ({task.get('visualType')} if task.get('visualType') else {'line', 'area', 'heatmap'}) if not any(chart.get('metric') == metric and chart.get('stage') == stage and chart.get('type') in chart_types for chart in child_visuals): missing.append('节点'+str(node_id)+'范围'+str(scope.get('label') or scope_id) +'缺少'+str(stage or '综合')+' '+metric+'趋势图。') elif metric_scope and preference != 'none' and metric_chart_required: required = metric_visual_requirements chart_types = ({task.get('visualType')} if task.get('visualType') else {'bar', 'column'}) if not required: missing.append('节点'+str(node_id)+'范围'+str(scope.get('label') or scope_id) +'缺少当前指标范围可表达的图表。') else: for metric, stage in required: if not any(chart.get('metric') == metric and chart.get('stage') == stage and chart.get('type') in chart_types for chart in child_visuals): missing.append('节点'+str(node_id)+'范围'+str(scope.get('label') or scope_id) +'缺少'+str(stage or '综合')+' '+metric+'比较图。') elif preference == 'required' and not child_visuals: missing.append('节点'+str(node_id)+'范围'+str(scope.get('label') or scope_id)+'缺少所需图表。') if len(all_visuals) > 12: missing.append(f'queryPlan共有{len(all_visuals)}张图表,超过12张呈现上限,已截取前12张;结果为部分完成。') all_visuals = all_visuals[:12] state = 'ready' if all_visuals else ('unavailable' if requested_visuals else 'not_requested') return {'visualSchemaVersion': 1, 'visualState': state, 'visuals': all_visuals, 'missingEvidence': list(dict.fromkeys(missing))} except Exception: return {'visualSchemaVersion': 1, 'visualState': 'failed', 'visuals': [], 'missingEvidence': ['queryPlan图表整理失败;已保留文字证据。']}